Structural Anchor ID Protocol
A lightweight protocol for stable structural addressing in human-AI collaborative development.
日本語は下にあります / Japanese follows below.
SAI (Structural Anchor ID) assigns a short, stable identifier to each structural unit in a project.
k7Da / preview_renderer
Qd92 / reconstruction_pipeline
rT5n / pptx_export_adapter
These identifiers exist outside the codebase, in an external map. They are not embedded in source code, not used as variable names, not required at runtime. Removing SAI entirely does not affect how the application runs.
SAI is a development navigation layer. It can carry provenance.
1. Non-embedded — lives outside the codebase
Unlike LSP symbols, ARNs, or trace IDs, SAI does not depend on the existence of the target. The identifier survives refactoring, session boundaries, and model changes because it is anchored in an external file, not inside the code.
2. Designed for human-AI collaboration
Existing tools assume humans as the primary user. SAI assumes that humans and AI agents need to refer to the same structural unit across sessions, across model changes, and across team boundaries — without re-explaining what "that preview section" means every time.
When a diagnostic trace shows:
[rT5n / pptx_export_adapter] export failed: missing layout binding
both the developer and the AI agent know exactly where to look. No session context required.
3. Deterministic lightweight provenance — not random, not cryptographic
SAI IDs are generated deterministically from Primary, Secondary, and ProjectName. The same inputs always reproduce the same ID space. Different inputs produce structurally distinct ID spaces.
Each 4-character ID contains:
- 1 character from Primary (case-balanced)
- 1 character from Secondary (case-balanced)
- 2 alphanumeric noise characters (drawn from a balanced bag of 62)
- 4 slots arranged by a deterministic project-seeded shuffle (all 24 permutations balanced across the complete cycle)
The result: noise distribution, case ratio, and slot permutations are all statistically uniform within one epoch — while the pattern of IDs carries an implicit signature of its origin. Not random. Not a cryptographic proof. A practical, lightweight provenance.
- Not DRM
- Not obfuscation
- Not a license mechanism
- Not a security boundary
- Not a runtime dependency
- Not a replacement for cryptographic signatures
- Not a function name, variable name, CSS class, DOM ID, or API endpoint
SAI must not affect runtime behavior. SAI must not be required for application logic.
SAI is managed in an external index file, not inside the codebase.
# sai/registry/sai.index.yaml
anchors:
- id: k7Da
layer: ui.preview
status: active
title: Preview surface renderer
target:
path: src/components/PreviewRenderer.tsxThe human-readable label lives here. The source code stays clean.
sai/registry/sai.pool.yaml Pool (master). Generated once at project start. Read-only.
sai/registry/sai.index.yaml Index (ledger). Records assigned anchors. Updated as work proceeds.
The pool is generated deterministically by tools/sai_generator.py. The index consumes IDs from the pool. IDs are never invented — they are dispensed from the pre-generated pool. This is what makes fabrication structurally impossible.
k7Da / preview_renderer
x4Tq / source_block_normalizer
Qd92 / reconstruction_pipeline
Disabled by default. No effect on runtime behavior.
[k7Da / source_block_normalizer] normalized 12 source blocks
[Qd92 / reconstruction_pipeline] generated 8 slide candidates
[rT5n / pptx_export_adapter] export failed: missing layout binding
SAI separates two layers with different lifecycles:
| Layer | Contents | Mutability |
|---|---|---|
| Constitution | spec/, docs/, tools/sai_generator.py |
Read-only. Never modified during operation. |
| Operation | sai/registry/sai.pool.yaml, sai/registry/sai.index.yaml |
Updated as work proceeds. Deletable. Regenerable. |
The operation layer (sai/) can be deleted entirely and regenerated from sai_generator.py with the same inputs. It is a cache, not a source of truth for the codebase itself.
SAI is not specific to software development. The same protocol applies to:
| Domain | Example anchor targets |
|---|---|
| Software development | functions, classes, models, UI components |
| Academic papers | chapters, sections, related work, theorems |
| Research projects | data fragments, experimental notes, citations |
| PM / PMO | issues, tickets, risks, milestones |
What SAI anchors is defined per domain by the project, not by this core protocol.
SAI is designed to work together with Structural Patch Protocol (SPP).
SAI = what to touch
SPP = how to safely touch it
SAI provides stable structural addresses for identifying what a human or AI agent should inspect, modify, or reference.
SPP defines how an AI agent should safely modify an existing artifact after the target has been identified.
Together, SAI and SPP form a complementary pair:
- SAI prevents target ambiguity.
- SPP prevents unsafe or inference-based modification.
- SAI locks the structural target.
- SPP controls the patch process.
SPP repository:
https://github.com/StateToolsLab/structural-patch-protocol
- Transparent — fully specified and publicly documented
- Removable — no runtime effect; can be stripped without breaking functionality
- Not required for contribution — contributors need not use SAI to contribute
- Explained — full documentation in this repository
sai-protocol/
├── README.md
├── spec/
│ └── SAI-v0.1.md Core specification
├── docs/
│ ├── concept.md Design philosophy and differentiators
│ ├── usage.md How to use SAI in practice
│ ├── threat-model.md What SAI defends and what it does not
│ └── images/
│ └── architecture.png Two-layer / pool-and-index diagram
├── tools/
│ ├── sai_generator.py Reference ID generator
│ └── sai_index_spec.md Pool and index schema specification
├── examples/
│ ├── sai.pool.example.yaml Example pool file
│ ├── sai.index.example.yaml Example index file
│ ├── SAI_Master.example.md Example master record
│ └── structural_anchors.example.json
└── paper/
├── README.md Paper directory overview
├── status.md Writing status (Phase 1 scope)
├── summary-ja.md Working paper summary (Japanese)
└── summary-en.md Working paper summary (English)
Experimental. The protocol may change.
Extension modules (structural authentication, tamper localization) are available separately.
Related protocol: Structural Patch Protocol (SPP) is available separately for safe AI-driven modification after target identification.
Structural Anchor ID Protocol
人間とAIの協働開発のための、安定した構造アドレッシングプロトコル。
SAI（Structural Anchor ID）は、プロジェクト内の各構造単位に、短く安定した識別子を付与します。
k7Da / preview_renderer
Qd92 / reconstruction_pipeline
rT5n / pptx_export_adapter
この識別子はコードベースの外側に存在します。ソースコードに埋め込まれず、変数名にも使わず、実行時にも不要です。SAIをすべて削除しても、アプリケーションの動作は変わりません。
SAIは開発ナビゲーション用レイヤーであり、provenanceを内包できます。
1. 非埋め込み — コードベースの外側に存在する
LSPシンボル、ARN、トレースIDと異なり、SAIは対象の存在に依存しません。識別子はリファクタリング・セッション境界・モデル変更をまたいで生き続けます。なぜなら、コードの中ではなく外部ファイルに固定されているからです。
2. AI協働を前提とした設計
既存ツールは人間を主たる利用者として設計されています。SAIは、人間とAIエージェントが、セッション・モデル変更・チームの境界をまたいで、毎回「あのプレビュー部分」を再説明することなく、同じ構造単位を参照できることを前提にしています。
Diagnostic Traceに以下が表示されれば：
[rT5n / pptx_export_adapter] export failed: missing layout binding
開発者もAIエージェントも、どこを見るべきかが即座にわかります。セッションのコンテキストは不要です。
3. 決定論的な軽量Provenance — 完全ランダムでも暗号署名でもない
SAI IDは、Primary・Secondary・ProjectNameから決定論的に生成されます。同じ入力は常に同じID空間を再現します。異なる入力は構造的に異なるID空間を生成します。
4文字のIDには以下が含まれます：
- Primary由来の1文字（大小文字均衡）
- Secondary由来の1文字（大小文字均衡）
- 英数字ノイズ2文字（62種の均衡化バッグから取得）
- 決定論的なproject-seeded shuffleによる4スロット配置（24通りのすべての配置がcomplete cycle内で均衡）
結果として、1 epoch内でノイズ分布・大小文字比率・スロット配置がすべて統計的に均一になります。一方、IDのパターンはその出所の暗黙的な署名を帯びます。完全ランダムではなく、暗号的な証明でもない。実用的な軽量provenanceです。
- DRMではない
- 難読化ではない
- ライセンス機構ではない
- セキュリティ境界ではない
- 実行時依存ではない
- 暗号署名の代替ではない
- 関数名・変数名・CSSクラス・DOM ID・APIエンドポイントではない
SAIは実行時の挙動に影響してはいけません。SAIはアプリケーションロジックに必須であってはいけません。
SAIはコードベースの内側ではなく、外部のindex fileで管理されます。
# sai/registry/sai.index.yaml
anchors:
- id: k7Da
layer: ui.preview
status: active
title: Preview surface renderer
target:
path: src/components/PreviewRenderer.tsx人間可読なラベルはここに存在します。ソースコードは清潔なままです。
sai/registry/sai.pool.yaml 台帳（マスタープール）。プロジェクト起点で一度生成。読み取り専用。
sai/registry/sai.index.yaml 払い出し記録。割り当てたアンカーを記録。随時更新。
台帳はtools/sai_generator.pyによって決定論的に生成されます。indexは台帳からIDを消費します。IDは創作されず、事前生成済みの台帳から払い出されます。これが捏造を構造的に不可能にします。
k7Da / preview_renderer
x4Tq / source_block_normalizer
Qd92 / reconstruction_pipeline
デフォルトでは無効。実行時の挙動に影響しません。
[k7Da / source_block_normalizer] normalized 12 source blocks
[Qd92 / reconstruction_pipeline] generated 8 slide candidates
[rT5n / pptx_export_adapter] export failed: missing layout binding
SAIは、性質の異なる二つのレイヤーに分離されます。
| レイヤー | 内容 | 可変性 |
|---|---|---|
| 憲法レイヤー | spec/・docs/・tools/sai_generator.py |
読み取り専用。運用中は変更しない。 |
| 運用レイヤー | sai/registry/sai.pool.yaml・sai/registry/sai.index.yaml |
随時更新。削除可能。再生成可能。 |
運用レイヤー（sai/）はまるごと削除でき、同じ入力でsai_generator.pyから再生成できます。コードベース本体の真実の源ではなく、キャッシュです。
SAIはソフトウェア開発に限定されません。同じプロトコルが以下にも適用できます。
| ドメイン | アンカー対象の例 |
|---|---|
| ソフトウェア開発 | 関数・クラス・モデル・UIコンポーネント |
| 論文 | 章・節・関連研究・定理 |
| 研究プロジェクト | 資料断片・実験ノート・引用 |
| PM / PMO | 課題・チケット・リスク・マイルストーン |
何をアンカー対象とするかは、コアプロトコルではなく、各プロジェクトがドメインに応じて定義します。
SAIは、Structural Patch Protocol（SPP） と組み合わせて使うことを想定しています。
SAI = 何を触るか
SPP = どう安全に触るか
SAIは、人間またはAIエージェントが参照・検査・変更する対象を、安定した構造住所として固定します。
SPPは、対象が特定された後に、AIエージェントが既存成果物をどう安全に変更するかを定義します。
SAIとSPPは、次のように補完関係にあります。
- SAIは対象の曖昧さを防ぐ。
- SPPは推論ベースの危険な変更を防ぐ。
- SAIは構造対象を固定する。
- SPPはパッチ手順を制御する。
SPPリポジトリ：
https://github.com/StateToolsLab/structural-patch-protocol
- 透明 — 完全に仕様化・公開されている
- 除去可能 — 実行時への影響なし、機能を壊さずに除去できる
- コントリビューションに不要 — SAIを使わなくてもコントリビュートできる
- 説明済み — このリポジトリに完全なドキュメントがある
sai-protocol/
├── README.md
├── spec/
│ └── SAI-v0.1.md コア仕様
├── docs/
│ ├── concept.md 設計思想と差別化ポイント
│ ├── usage.md 実際の使い方
│ ├── threat-model.md 何を守り、何を守らないか
│ └── images/
│ └── architecture.png 二層構造・Pool-and-Index 図
├── tools/
│ ├── sai_generator.py 参照実装ジェネレータ
│ └── sai_index_spec.md Pool・Indexスキーマ仕様
├── examples/
│ ├── sai.pool.example.yaml 台帳サンプル
│ ├── sai.index.example.yaml 払い出し記録サンプル
│ ├── SAI_Master.example.md マスターレコードサンプル
│ └── structural_anchors.example.json
└── paper/
├── README.md paperディレクトリの案内
├── status.md 執筆状況（Phase 1スコープ）
├── summary-ja.md ワーキングペーパー要約（日本語）
└── summary-en.md ワーキングペーパー要約（英語）
実験段階。プロトコルは変更される可能性があります。
認証・改竄箇所特定のための拡張モジュールは、別途提供予定です。
関連プロトコル：対象特定後の安全なAI変更手順として、Structural Patch Protocol（SPP）を別リポジトリで提供しています。