@quolu/lattice 0.57.3 → 0.58.1

package/README.ja.md

@@ -67,6 +67,38 @@ lattice todo show --plan <key> --task <id> --json
 後続工程それぞれの状態（未着手／作業中／完了／ブロック中）と、その工程の並列可否を示します。
 note本文はHTMLを描くすべての面へ載ります。project別HTMLの生成や再生成は不要です。
 
+### ToDoのdataflowを実装前と実装後で照合する
+
+codeを変更するplanだけ、plan定義後に論理dataflow検査を明示的に有効化できます。出版や運用など
+code-dataflowを持たないplanへは適用しません。入力schemaはCLIから取得でき、planned sourceを保存しても
+まだ有効化されません。clean worktreeでのauthoritative compileが`consistent`になった時だけ、
+そのplan version専用のimmutable bindingが発行されます。
+
+```bash
+lattice todo structure --schema --json
+lattice todo structure input --plan <key> --input structure.json --dry-run --json
+lattice todo structure input --plan <key> --input structure.json
+lattice todo structure compile --plan <key> --input .lattice/todo/structure/<key>.json
+lattice todo structure --plan <key> --json
+```
+
+verdictは`consistent | inconsistent | unknown`の三値です。`unknown`を問題なしへ丸めず、findingはtask、
+data port、code anchor、commitと次の操作を返します。plannedは不変で、実装後の形はtaskごとの
+append-only realizationとして記録します。有効化済みplanのgraph taskはfresh realizationなしに
+`todo done`できません。全task完了後は最終HEADで再compileし、freshかつconsistentなfinalizationが
+できてからterminalを閉じます。
+
+```bash
+lattice todo structure realize --plan <key> --task <id> --input realization.json
+lattice todo done --plan <key> --task <id> --evidence evidence.json
+lattice todo structure finalize --plan <key> --json
+```
+
+動的dashboardの「構造検査」は工程依存図とは別の面です。task／data／code／external／commit provenance、
+planned／realized／effective、findingと鮮度を表示します。工程依存線へdataflow edgeを混ぜません。
+通常読取とdashboardは保存artifactだけを読み、暗黙にsensorを再実行しません。構造未適用planの
+lifecycleとdashboardには、このgateも構造panelも追加されません。
+
 ### 変換の受入五条件
 
 **5つすべて**を満たしたときだけ採用します。1つでも欠ければ棄却です。

package/README.md

@@ -82,6 +82,39 @@ can run in parallel. Note bodies are carried by every rendered surface, includin
 repository. Static per-project HTML is not generated; `lattice todo gantt serve` and the shared dashboard
 read the store dynamically.
 
+### Check a ToDo's dataflow before and after implementation
+
+A code-changing plan can explicitly opt into logical dataflow inspection after the plan is defined.
+Non-code plans such as publishing or operations are left unchanged. Saving a planned source does not
+enable the feature. Only an authoritative compile on a clean worktree that returns `consistent` emits
+an immutable binding for that exact plan version.
+
+```bash
+lattice todo structure --schema --json
+lattice todo structure input --plan <key> --input structure.json --dry-run --json
+lattice todo structure input --plan <key> --input structure.json
+lattice todo structure compile --plan <key> --input .lattice/todo/structure/<key>.json
+lattice todo structure --plan <key> --json
+```
+
+The verdict is three-valued: `consistent | inconsistent | unknown`. Unknown is never treated as success.
+Findings identify the relevant task, data port, code anchor, and commit, and include the next action.
+The planned form remains immutable; implementation changes are appended as per-task realizations. A graph
+task in an enabled plan cannot complete without a fresh realization. After every task is done, Lattice
+recompiles the final HEAD and requires a fresh, consistent finalization before the terminal phase can close.
+
+```bash
+lattice todo structure realize --plan <key> --task <id> --input realization.json
+lattice todo done --plan <key> --task <id> --evidence evidence.json
+lattice todo structure finalize --plan <key> --json
+```
+
+The dynamic dashboard exposes this as a separate **Structure inspection** pane. It shows task, data, code,
+external contract, and commit-provenance nodes; planned, realized, and effective forms; findings; and
+freshness. Dataflow edges are never mixed into the process-dependency diagram. Normal reads and dashboard
+renders use saved artifacts without silently running the sensor. Plans that do not opt in retain their
+existing lifecycle and do not gain a structure pane.
+
 ### The five acceptance conditions
 
 A transform is adopted only when **all five** hold. One missing condition rejects it:

package/docs/schemas/lattice.todo_structure_binding.v1.schema.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/kitepon-rgb/Lattice/blob/main/docs/schemas/lattice.todo_structure_binding.v1.schema.json",
+  "title": "lattice.todo_structure_binding.v1",
+  "description": "Immutable activation binding emitted by a successful authoritative planned compile.",
+  "$comment": "Runtime validation additionally enforces exact keys, strict timestamps, actor identity, and the canonical self-digest.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema", "project_id", "plan_key", "plan_version", "topology_digest", "profile",
+    "baseline_sha", "structure_set_digest", "compiled_head_sha", "compile_artifact_digest",
+    "activated_at", "actor", "binding_digest"
+  ],
+  "properties": {
+    "schema": { "const": "lattice.todo_structure_binding.v1" },
+    "project_id": { "$ref": "#/$defs/identifier" },
+    "plan_key": { "$ref": "#/$defs/identifier" },
+    "plan_version": { "$ref": "#/$defs/identifier" },
+    "topology_digest": { "$ref": "#/$defs/digest" },
+    "profile": { "const": "code-dataflow" },
+    "baseline_sha": { "$ref": "#/$defs/gitSha" },
+    "structure_set_digest": { "$ref": "#/$defs/digest" },
+    "compiled_head_sha": { "$ref": "#/$defs/gitSha" },
+    "compile_artifact_digest": { "$ref": "#/$defs/digest" },
+    "activated_at": { "$ref": "#/$defs/strictTimestamp" },
+    "actor": { "$ref": "#/$defs/actor" },
+    "binding_digest": { "$ref": "#/$defs/digest" }
+  },
+  "$defs": {
+    "identifier": { "type": "string", "pattern": "^[0-9A-Za-z](?:[0-9A-Za-z._-]{0,127})$" },
+    "digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+    "gitSha": { "type": "string", "pattern": "^[0-9a-f]{40}$" },
+    "strictTimestamp": {
+      "type": "string",
+      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\\.[0-9]{3}Z$"
+    },
+    "actor": {
+      "type": "object", "additionalProperties": false,
+      "required": ["host", "session", "agent"],
+      "properties": {
+        "host": { "$ref": "#/$defs/identifier" },
+        "session": { "$ref": "#/$defs/identifier" },
+        "agent": { "$ref": "#/$defs/identifier" }
+      }
+    }
+  }
+}

package/docs/schemas/lattice.todo_structure_realization.v1.schema.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/kitepon-rgb/Lattice/blob/main/docs/schemas/lattice.todo_structure_realization.v1.schema.json",
+  "title": "lattice.todo_structure_realization.v1",
+  "description": "Append-only realized logical dataflow for one applicable task.",
+  "$comment": "Runtime validation additionally enforces canonical ordering, chain continuity, supersedes membership, structure-set identity, planned digest, UTF-8 byte bounds, and the canonical self-digest.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema", "project_id", "plan_key", "plan_version", "task_id", "sequence",
+    "previous_digest", "structure_set_digest", "planned_digest", "head_sha", "commit_oids",
+    "realized", "supersedes", "actor", "recorded_at", "realization_digest"
+  ],
+  "properties": {
+    "schema": { "const": "lattice.todo_structure_realization.v1" },
+    "project_id": { "$ref": "#/$defs/identifier" },
+    "plan_key": { "$ref": "#/$defs/identifier" },
+    "plan_version": { "$ref": "#/$defs/identifier" },
+    "task_id": { "$ref": "#/$defs/identifier" },
+    "sequence": { "type": "integer", "minimum": 1 },
+    "previous_digest": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/digest" }] },
+    "structure_set_digest": { "$ref": "#/$defs/digest" },
+    "planned_digest": { "$ref": "#/$defs/digest" },
+    "head_sha": { "$ref": "#/$defs/gitSha" },
+    "commit_oids": {
+      "type": "array", "minItems": 1, "maxItems": 256, "uniqueItems": true,
+      "items": { "$ref": "#/$defs/gitSha" }
+    },
+    "realized": {
+      "$ref": "lattice.todo_structure_set.v1.schema.json#/$defs/transform"
+    },
+    "supersedes": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/digest" }] },
+    "actor": { "$ref": "#/$defs/actor" },
+    "recorded_at": { "$ref": "#/$defs/strictTimestamp" },
+    "realization_digest": { "$ref": "#/$defs/digest" }
+  },
+  "$defs": {
+    "identifier": { "type": "string", "pattern": "^[0-9A-Za-z](?:[0-9A-Za-z._-]{0,127})$" },
+    "digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+    "gitSha": { "type": "string", "pattern": "^[0-9a-f]{40}$" },
+    "strictTimestamp": {
+      "type": "string",
+      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\\.[0-9]{3}Z$"
+    },
+    "actor": {
+      "type": "object", "additionalProperties": false,
+      "required": ["host", "session", "agent"],
+      "properties": {
+        "host": { "$ref": "#/$defs/identifier" },
+        "session": { "$ref": "#/$defs/identifier" },
+        "agent": { "$ref": "#/$defs/identifier" }
+      }
+    }
+  }
+}

package/docs/schemas/lattice.todo_structure_set.v1.schema.json

@@ -0,0 +1,264 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/kitepon-rgb/Lattice/blob/main/docs/schemas/lattice.todo_structure_set.v1.schema.json",
+  "title": "lattice.todo_structure_set.v1",
+  "description": "AI-authored logical dataflow overlay for one registered Lattice plan version.",
+  "$comment": "Runtime validation additionally enforces UTF-8 byte bounds, strict canonical ordering, referential integrity, exact plan task coverage when supplied, unique data IDs, constant canonical-byte limits, the canonical self-digest, and plan-wide totals of at most 512 anchors, 4096 ports, 2048 operations, and 4096 sinks.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema", "project_id", "plan_key", "plan_version", "topology_digest", "profile",
+    "baseline_sha", "external_contracts", "tasks", "structure_set_digest"
+  ],
+  "properties": {
+    "schema": { "const": "lattice.todo_structure_set.v1" },
+    "project_id": { "$ref": "#/$defs/identifier" },
+    "plan_key": { "$ref": "#/$defs/identifier" },
+    "plan_version": { "$ref": "#/$defs/identifier" },
+    "topology_digest": { "$ref": "#/$defs/digest" },
+    "profile": { "const": "code-dataflow" },
+    "baseline_sha": { "$ref": "#/$defs/gitSha" },
+    "external_contracts": {
+      "type": "array", "maxItems": 256, "uniqueItems": true,
+      "items": { "$ref": "#/$defs/externalContract" }
+    },
+    "tasks": {
+      "type": "array", "minItems": 1, "maxItems": 512, "uniqueItems": true,
+      "items": { "oneOf": [{ "$ref": "#/$defs/graphTask" }, { "$ref": "#/$defs/excludedTask" }] }
+    },
+    "structure_set_digest": { "$ref": "#/$defs/digest" }
+  },
+  "$defs": {
+    "identifier": {
+      "type": "string", "pattern": "^[0-9A-Za-z](?:[0-9A-Za-z._-]{0,127})$"
+    },
+    "digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+    "gitSha": { "type": "string", "pattern": "^[0-9a-f]{40}$" },
+    "repoRef": {
+      "type": "string", "minLength": 1, "maxLength": 1024,
+      "pattern": "^(?!/)(?!.*(?:^|/)\\.{1,2}(?:/|$))(?!.*\\\\)(?!.*[\\u0000-\\u001f\\u007f])[^/]+(?:/[^/]+)*$"
+    },
+    "text": {
+      "type": "string", "minLength": 1, "maxLength": 4096,
+      "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
+    },
+    "schemaRef": {
+      "type": "object", "additionalProperties": false,
+      "required": ["path", "symbol", "json_pointer"],
+      "properties": {
+        "path": { "$ref": "#/$defs/repoRef" },
+        "symbol": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/text" }] },
+        "json_pointer": {
+          "oneOf": [
+            { "type": "null" },
+            { "type": "string", "pattern": "^(?:/(?:[^~/]|~[01])*)*$" }
+          ]
+        }
+      }
+    },
+    "dataContract": {
+      "type": "object", "additionalProperties": false,
+      "required": [
+        "shape_id", "schema_ref", "identity_fields", "lifecycle", "cardinality",
+        "compatible_shape_ids"
+      ],
+      "properties": {
+        "shape_id": { "$ref": "#/$defs/identifier" },
+        "schema_ref": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/schemaRef" }] },
+        "identity_fields": {
+          "type": "array", "maxItems": 256, "uniqueItems": true,
+          "items": { "$ref": "#/$defs/identifier" }
+        },
+        "lifecycle": {
+          "enum": ["snapshot", "event", "stream", "mutable_state", "immutable_artifact"]
+        },
+        "cardinality": { "enum": ["one", "optional", "many"] },
+        "compatible_shape_ids": {
+          "type": "array", "maxItems": 256, "uniqueItems": true,
+          "items": { "$ref": "#/$defs/identifier" }
+        }
+      }
+    },
+    "codeAnchor": {
+      "type": "object", "additionalProperties": false,
+      "required": ["anchor_id", "effect", "path", "symbol", "expected_at"],
+      "properties": {
+        "anchor_id": { "$ref": "#/$defs/identifier" },
+        "effect": { "enum": ["read", "modify", "create", "delete"] },
+        "path": { "$ref": "#/$defs/repoRef" },
+        "symbol": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/text" }] },
+        "expected_at": { "enum": ["baseline", "current", "after_task"] }
+      }
+    },
+    "sourceRef": {
+      "oneOf": [
+        {
+          "type": "object", "additionalProperties": false,
+          "required": ["kind", "anchor_id"],
+          "properties": { "kind": { "const": "code" }, "anchor_id": { "$ref": "#/$defs/identifier" } }
+        },
+        {
+          "type": "object", "additionalProperties": false,
+          "required": ["kind", "task_id", "port_id"],
+          "properties": {
+            "kind": { "const": "task_output" },
+            "task_id": { "$ref": "#/$defs/identifier" },
+            "port_id": { "$ref": "#/$defs/identifier" }
+          }
+        },
+        {
+          "type": "object", "additionalProperties": false,
+          "required": ["kind", "contract_id"],
+          "properties": {
+            "kind": { "const": "external" },
+            "contract_id": { "$ref": "#/$defs/identifier" }
+          }
+        },
+        {
+          "type": "object", "additionalProperties": false,
+          "required": ["kind", "constant_id", "value"],
+          "properties": {
+            "kind": { "const": "constant" },
+            "constant_id": { "$ref": "#/$defs/identifier" },
+            "value": true
+          }
+        }
+      ]
+    },
+    "inputPort": {
+      "type": "object", "additionalProperties": false,
+      "required": ["port_id", "source", "access", "contract"],
+      "properties": {
+        "port_id": { "$ref": "#/$defs/identifier" },
+        "source": { "$ref": "#/$defs/sourceRef" },
+        "access": { "enum": ["read", "consume", "observe"] },
+        "contract": { "$ref": "#/$defs/dataContract" }
+      }
+    },
+    "outputSink": {
+      "oneOf": [
+        {
+          "type": "object", "additionalProperties": false,
+          "required": ["kind", "task_id", "port_id"],
+          "properties": {
+            "kind": { "const": "task" },
+            "task_id": { "$ref": "#/$defs/identifier" },
+            "port_id": { "$ref": "#/$defs/identifier" }
+          }
+        },
+        {
+          "type": "object", "additionalProperties": false,
+          "required": ["kind", "anchor_id"],
+          "properties": { "kind": { "const": "code" }, "anchor_id": { "$ref": "#/$defs/identifier" } }
+        },
+        {
+          "type": "object", "additionalProperties": false,
+          "required": ["kind", "contract_id"],
+          "properties": {
+            "kind": { "const": "external" },
+            "contract_id": { "$ref": "#/$defs/identifier" }
+          }
+        },
+        {
+          "type": "object", "additionalProperties": false,
+          "required": ["kind", "product_id"],
+          "properties": {
+            "kind": { "const": "final_product" },
+            "product_id": { "$ref": "#/$defs/identifier" }
+          }
+        }
+      ]
+    },
+    "outputPort": {
+      "type": "object", "additionalProperties": false,
+      "required": ["port_id", "data_id", "contract", "sinks"],
+      "properties": {
+        "port_id": { "$ref": "#/$defs/identifier" },
+        "data_id": { "$ref": "#/$defs/identifier" },
+        "contract": { "$ref": "#/$defs/dataContract" },
+        "sinks": {
+          "type": "array", "maxItems": 256, "uniqueItems": true,
+          "items": { "$ref": "#/$defs/outputSink" }
+        }
+      }
+    },
+    "operation": {
+      "type": "object", "additionalProperties": false,
+      "required": ["operation_id", "input_port_ids", "output_port_ids", "summary"],
+      "properties": {
+        "operation_id": { "$ref": "#/$defs/identifier" },
+        "input_port_ids": {
+          "type": "array", "maxItems": 256, "uniqueItems": true,
+          "items": { "$ref": "#/$defs/identifier" }
+        },
+        "output_port_ids": {
+          "type": "array", "minItems": 1, "maxItems": 256, "uniqueItems": true,
+          "items": { "$ref": "#/$defs/identifier" }
+        },
+        "summary": { "$ref": "#/$defs/text" }
+      }
+    },
+    "transform": {
+      "type": "object", "additionalProperties": false,
+      "required": [
+        "outcome", "inputs", "operations", "outputs", "code_anchors", "failures",
+        "first_live_e2e", "non_goals"
+      ],
+      "properties": {
+        "outcome": { "$ref": "#/$defs/text" },
+        "inputs": {
+          "type": "array", "maxItems": 256, "uniqueItems": true,
+          "items": { "$ref": "#/$defs/inputPort" }
+        },
+        "operations": {
+          "type": "array", "maxItems": 256, "uniqueItems": true,
+          "items": { "$ref": "#/$defs/operation" }
+        },
+        "outputs": {
+          "type": "array", "maxItems": 256, "uniqueItems": true,
+          "items": { "$ref": "#/$defs/outputPort" }
+        },
+        "code_anchors": {
+          "type": "array", "maxItems": 256, "uniqueItems": true,
+          "items": { "$ref": "#/$defs/codeAnchor" }
+        },
+        "failures": {
+          "type": "array", "maxItems": 128, "uniqueItems": true,
+          "items": { "$ref": "#/$defs/text" }
+        },
+        "first_live_e2e": { "$ref": "#/$defs/text" },
+        "non_goals": {
+          "type": "array", "maxItems": 128, "uniqueItems": true,
+          "items": { "$ref": "#/$defs/text" }
+        }
+      }
+    },
+    "externalContract": {
+      "type": "object", "additionalProperties": false,
+      "required": ["contract_id", "description", "contract"],
+      "properties": {
+        "contract_id": { "$ref": "#/$defs/identifier" },
+        "description": { "$ref": "#/$defs/text" },
+        "contract": { "$ref": "#/$defs/dataContract" }
+      }
+    },
+    "graphTask": {
+      "type": "object", "additionalProperties": false,
+      "required": ["task_id", "applicability", "planned"],
+      "properties": {
+        "task_id": { "$ref": "#/$defs/identifier" },
+        "applicability": { "const": "graph" },
+        "planned": { "$ref": "#/$defs/transform" }
+      }
+    },
+    "excludedTask": {
+      "type": "object", "additionalProperties": false,
+      "required": ["task_id", "applicability", "excluded_reason"],
+      "properties": {
+        "task_id": { "$ref": "#/$defs/identifier" },
+        "applicability": { "const": "excluded" },
+        "excluded_reason": { "$ref": "#/$defs/text" }
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quolu/lattice",
-  "version": "0.57.3",
+  "version": "0.58.1",
   "description": "Schedulability compiler for multi-agent development: observe real code boundaries, refactor the conflicting seam, recompile the plan for parallel execution",
   "author": {
     "name": "Quo / クオ at kitepon.dev",
@@ -34,6 +34,9 @@
     "docs/schemas/lattice.phase_todo_revision.v3.schema.json",
     "docs/schemas/lattice.todo_extraction.v2.schema.json",
     "docs/schemas/lattice.todo_extraction.v3.schema.json",
+    "docs/schemas/lattice.todo_structure_set.v1.schema.json",
+    "docs/schemas/lattice.todo_structure_realization.v1.schema.json",
+    "docs/schemas/lattice.todo_structure_binding.v1.schema.json",
     "docs/schemas/lattice.run_request.v1.schema.json",
     "docs/schemas/lattice.executor_packet.v1.schema.json",
     "docs/schemas/lattice.executor_receipt.v1.schema.json",

package/sensor/dist/bin/exact-traversal.d.ts

@@ -0,0 +1,20 @@
+export interface TraversalCandidate {
+    node: {
+        name: string;
+        qualifiedName?: string;
+        filePath: string;
+    };
+}
+export type ExactTraversalSelection<T> = {
+    outcome: 'ready';
+    candidate: T;
+} | {
+    outcome: 'absent' | 'ambiguous';
+    candidate: null;
+};
+/**
+ * fuzzy検索結果から、宣言されたsymbolとfileを同時にexact一致するnodeを一つだけ選ぶ。
+ * node IDは既存index内の走査にだけ使い、外部contractへは公開しない。
+ */
+export declare function selectExactTraversalCandidate<T extends TraversalCandidate>(candidates: T[], symbol: string, exactPath: string): ExactTraversalSelection<T>;
+//# sourceMappingURL=exact-traversal.d.ts.map

package/sensor/dist/bin/exact-traversal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exact-traversal.d.ts","sourceRoot":"","sources":["../../src/bin/exact-traversal.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE;QACJ,IAAI,EAAE,MAAM,CAAC;QACb,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;CACH;AAED,MAAM,MAAM,uBAAuB,CAAC,CAAC,IACjC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,CAAC,CAAA;CAAE,GAClC;IAAE,OAAO,EAAE,QAAQ,GAAG,WAAW,CAAC;IAAC,SAAS,EAAE,IAAI,CAAA;CAAE,CAAC;AAEzD;;;GAGG;AACH,wBAAgB,6BAA6B,CAAC,CAAC,SAAS,kBAAkB,EACxE,UAAU,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GACjD,uBAAuB,CAAC,CAAC,CAAC,CAM5B"}

package/sensor/dist/bin/exact-traversal.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.selectExactTraversalCandidate = selectExactTraversalCandidate;
+/**
+ * fuzzy検索結果から、宣言されたsymbolとfileを同時にexact一致するnodeを一つだけ選ぶ。
+ * node IDは既存index内の走査にだけ使い、外部contractへは公開しない。
+ */
+function selectExactTraversalCandidate(candidates, symbol, exactPath) {
+    const exact = candidates.filter(({ node }) => node.filePath === exactPath
+        && (node.name === symbol || node.qualifiedName === symbol));
+    if (exact.length === 0)
+        return { outcome: 'absent', candidate: null };
+    if (exact.length > 1)
+        return { outcome: 'ambiguous', candidate: null };
+    return { outcome: 'ready', candidate: exact[0] };
+}
+//# sourceMappingURL=exact-traversal.js.map

package/sensor/dist/bin/exact-traversal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exact-traversal.js","sourceRoot":"","sources":["../../src/bin/exact-traversal.ts"],"names":[],"mappings":";;AAgBA,sEAQC;AAZD;;;GAGG;AACH,SAAgB,6BAA6B,CAC3C,UAAe,EAAE,MAAc,EAAE,SAAiB;IAElD,MAAM,KAAK,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,KAAK,SAAS;WACpE,CAAC,IAAI,CAAC,IAAI,KAAK,MAAM,IAAI,IAAI,CAAC,aAAa,KAAK,MAAM,CAAC,CAAC,CAAC;IAC9D,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IACtE,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IACvE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC,CAAE,EAAE,CAAC;AACpD,CAAC"}

package/sensor/dist/bin/lattice-sensor.js

@@ -84,6 +84,7 @@ const node_version_check_1 = require("./node-version-check");
 const fatal_handler_1 = require("./fatal-handler");
 const wasm_runtime_flags_1 = require("../extraction/wasm-runtime-flags");
 const command_supervision_1 = require("./command-supervision");
+const exact_traversal_1 = require("./exact-traversal");
 const extraction_version_1 = require("../extraction/extraction-version");
 const telemetry_1 = require("../telemetry");
 // Decided once, before `--color`/`--no-color` are stripped from argv below
@@ -1805,6 +1806,7 @@ function main() {
         .description('Find all functions/methods that call a specific symbol')
         .option('-p, --path <path>', 'Project path')
         .option('-l, --limit <number>', 'Maximum results', '20')
+        .option('--exact-path <repo-relative-path>', 'Traverse one exact symbol in this repo-relative file')
         .option('-j, --json', 'Output as JSON')
         .action(async (symbol, options) => {
         const projectPath = resolveProjectPath(options.path);
@@ -1824,9 +1826,13 @@ function main() {
             }
             const seen = new Set();
             const allCallers = [];
-            for (const match of matches) {
+            const strict = options.exactPath === undefined
+                ? null : (0, exact_traversal_1.selectExactTraversalCandidate)(matches, symbol, options.exactPath);
+            const traversalMatches = strict === null
+                ? matches : strict.outcome === 'ready' ? [strict.candidate] : [];
+            for (const match of traversalMatches) {
                 const exactMatch = match.node.name === symbol || match.node.name.endsWith(`.${symbol}`) || match.node.name.endsWith(`::${symbol}`);
-                if (!exactMatch && matches.length > 1)
+                if (strict === null && !exactMatch && matches.length > 1)
                     continue;
                 for (const c of cg.getCallers(match.node.id)) {
                     if (!seen.has(c.node.id)) {
@@ -1836,7 +1842,7 @@ function main() {
                 }
             }
             // Fallback: if exact filter removed everything, use the top match
-            if (allCallers.length === 0 && matches[0]) {
+            if (strict === null && allCallers.length === 0 && matches[0]) {
                 for (const c of cg.getCallers(matches[0].node.id)) {
                     if (!seen.has(c.node.id)) {
                         seen.add(c.node.id);
@@ -1846,7 +1852,11 @@ function main() {
             }
             const limited = allCallers.slice(0, limit);
             if (options.json) {
-                console.log(JSON.stringify({ symbol, callers: limited }, null, 2));
+                console.log(JSON.stringify({
+                    symbol,
+                    ...(strict === null ? {} : { exactPath: options.exactPath, exactResolution: strict.outcome }),
+                    callers: limited,
+                }, null, 2));
             }
             else if (limited.length === 0) {
                 info(`No callers found for "${symbol}"`);
@@ -1876,6 +1886,7 @@ function main() {
         .description('Find all functions/methods that a specific symbol calls')
         .option('-p, --path <path>', 'Project path')
         .option('-l, --limit <number>', 'Maximum results', '20')
+        .option('--exact-path <repo-relative-path>', 'Traverse one exact symbol in this repo-relative file')
         .option('-j, --json', 'Output as JSON')
         .action(async (symbol, options) => {
         const projectPath = resolveProjectPath(options.path);
@@ -1895,9 +1906,13 @@ function main() {
             }
             const seen = new Set();
             const allCallees = [];
-            for (const match of matches) {
+            const strict = options.exactPath === undefined
+                ? null : (0, exact_traversal_1.selectExactTraversalCandidate)(matches, symbol, options.exactPath);
+            const traversalMatches = strict === null
+                ? matches : strict.outcome === 'ready' ? [strict.candidate] : [];
+            for (const match of traversalMatches) {
                 const exactMatch = match.node.name === symbol || match.node.name.endsWith(`.${symbol}`) || match.node.name.endsWith(`::${symbol}`);
-                if (!exactMatch && matches.length > 1)
+                if (strict === null && !exactMatch && matches.length > 1)
                     continue;
                 for (const c of cg.getCallees(match.node.id)) {
                     if (!seen.has(c.node.id)) {
@@ -1906,7 +1921,7 @@ function main() {
                     }
                 }
             }
-            if (allCallees.length === 0 && matches[0]) {
+            if (strict === null && allCallees.length === 0 && matches[0]) {
                 for (const c of cg.getCallees(matches[0].node.id)) {
                     if (!seen.has(c.node.id)) {
                         seen.add(c.node.id);
@@ -1916,7 +1931,11 @@ function main() {
             }
             const limited = allCallees.slice(0, limit);
             if (options.json) {
-                console.log(JSON.stringify({ symbol, callees: limited }, null, 2));
+                console.log(JSON.stringify({
+                    symbol,
+                    ...(strict === null ? {} : { exactPath: options.exactPath, exactResolution: strict.outcome }),
+                    callees: limited,
+                }, null, 2));
             }
             else if (limited.length === 0) {
                 info(`No callees found for "${symbol}"`);

package/sensor/package.json

@@ -38,7 +38,7 @@
     "fast-wrap-ansi": "^0.2.0",
     "ignore": "^7.0.5",
     "jsonc-parser": "^3.3.1",
-    "picomatch": "^4.0.3",
+    "picomatch": "^4.0.4",
     "sisteransi": "^1.0.5",
     "tree-sitter-wasms": "^0.1.11",
     "web-tree-sitter": "^0.25.3"