@quolu/lattice 0.17.0 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quolu/lattice",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Lattice — phase-aware TODO graph compiler and conflict-aware orchestration runtime",
   "type": "module",
   "license": "MIT",

package/src/seam-proposal-contracts.mjs

@@ -20,7 +20,7 @@ import {
   seamProposalGuidanceCode,
 } from './todo-independence-guidance.mjs';
 
-export const SEAM_PROPOSAL_SCHEMA = 'lattice.seam_proposal.v1';
+export const SEAM_PROPOSAL_SCHEMA = 'lattice.seam_proposal.v2';
 export const SEAM_PROPOSAL_PROJECTION_SCHEMA = 'lattice.seam_proposal_projection.v1';
 export const SEAM_PROPOSAL_VERDICTS = Object.freeze([
   'seam_candidate',
@@ -142,10 +142,18 @@ function surfaceEntry(value, taskIds, { proposed }) {
     : value.owner_task_ids.length === 1;
 }
 
+/**
+ * `candidate_paths`は、同名symbolが複数fileに居た時だけ埋まる（ADR 0134）。
+ *
+ * 単数の`resolved_path`と併存させるのは、両者が別の事実だからである。前者は「一意に決まった」、
+ * 後者は「決まらず、候補はこれだけあった」。候補を持つ受け皿が無かった頃、後者は`unknown`へ
+ * 潰れ、宣言の`within`で絞れる情報が記録に残らなかった。一意に決まった時に候補を並べない
+ * （空配列に限る）のは、決まった事実と決まらなかった事実を同じ形にしないためである。
+ */
 function queryEntry(value) {
   return exactRecord(value, [
     'query_id', 'operation', 'target', 'outcome', 'resolved_name', 'resolved_path',
-    'result_digest',
+    'candidate_paths', 'result_digest',
   ])
     && isTodoIdentifier(value.query_id)
     && isTodoIdentifier(value.operation)
@@ -153,6 +161,12 @@ function queryEntry(value) {
     && isTodoIdentifier(value.outcome)
     && (value.resolved_name === null || boundedText(value.resolved_name))
     && (value.resolved_path === null || repoRelativePath(value.resolved_path))
+    && boundedList(value.candidate_paths, repoRelativePath)
+    && strictlySorted(value.candidate_paths)
+    && (value.outcome === 'ambiguous'
+      ? value.candidate_paths.length >= 2 && value.resolved_path === null
+        && boundedText(value.resolved_name)
+      : value.candidate_paths.length === 0)
     && isTodoDigest(value.result_digest);
 }
 
@@ -284,7 +298,7 @@ function decisionEntry(value) {
 }
 
 /**
- * Validate the immutable public `lattice.seam_proposal.v1` artifact.
+ * Validate the immutable public `lattice.seam_proposal.v2` artifact.
  *
  * This validates the artifact's closed runtime shape and canonical relations. Binding the
  * recorded conflicts back to the referenced independence bytes is a consumer responsibility.

package/src/seam-proposal-queries.mjs

@@ -249,12 +249,24 @@ function exactSymbolResolution(outcome, target, operation) {
     return { outcome: 'unknown' };
   }
   const paths = [...new Set(exact.map(({ node }) => node.filePath))].sort(compareText);
-  if (paths.length !== 1) return { outcome: 'unknown' };
-  return { outcome: 'resolved', resolved_name: target, resolved_path: paths[0] };
+  if (paths.length === 1) {
+    return { outcome: 'resolved', resolved_name: target, resolved_path: paths[0] };
+  }
+  // 同名が複数fileにある。`query`は「その名前はどこに居るか」を問う操作なので、候補を
+  // 持ったまま返す——宣言の`within`が指す資源で絞れば一意に決まる場合がある（ADR 0134）。
+  // graph操作（callers／callees／impact）は逆に、展開の起点が一意でなければ意味を持たない。
+  // 同じ曖昧さでも問いが違うので、そちらはunknownのまま潰す。
+  if (operation === 'query') {
+    return { outcome: 'ambiguous', resolved_name: target, candidate_paths: paths };
+  }
+  return { outcome: 'unknown' };
 }
 
 function symbolResolutionForEvidence(local, canonical) {
-  if (canonical.outcome === 'unknown') return { outcome: 'unknown' };
+  // 起点が一意でない名前についてのgraph観測は、どのsymbolについての観測か確定しない。
+  if (canonical.outcome === 'unknown' || canonical.outcome === 'ambiguous') {
+    return { outcome: 'unknown' };
+  }
   if (canonical.outcome === 'absent') {
     return local.outcome === 'absent' ? local : { outcome: 'unknown' };
   }
@@ -294,6 +306,7 @@ function evidenceQuery({ query, outcome, resolution }) {
     outcome: resolution.outcome,
     resolved_name: resolution.resolved_name ?? null,
     resolved_path: resolution.resolved_path ?? null,
+    candidate_paths: resolution.candidate_paths ?? [],
     result_digest: digestArtifact(portableSensorOutcome(outcome)),
   };
 }
@@ -472,7 +485,7 @@ async function collectCalleeClosure({
 /**
  * Collect through the bundled sensor adapter. The normalized evidence remains the only
  * contract-shaped artifact; raw outcomes are returned on a separate, in-memory channel for
- * structural cut enumeration and must not be embedded in lattice.seam_proposal.v1.
+ * structural cut enumeration and must not be embedded in lattice.seam_proposal.v2.
  */
 export async function collectSeamProposalEvidenceBundle({
   cwd,

package/src/seam-proposal.mjs

@@ -774,13 +774,42 @@ function pathContains(resourcePath, symbolPath) {
     : symbolPath === resourcePath;
 }
 
+/**
+ * 宣言symbolのpathを、宣言した資源の内側で解く（ADR 0134）。
+ *
+ * 一意に解決した名前はそのまま返す。同名が複数fileに居た場合だけ、receiptが持つ候補を
+ * 資源で絞る——絞って1つに決まる時だけ束縛根拠になる。0個なら宣言した資源の中には無く、
+ * 2つ以上なら資源の中でも決まらない。どちらも「解けなかった」であって、片方を勝たせない。
+ *
+ * 絞るのは宣言された資源であって、宣言そのものではない。sensorが返した候補集合の外から
+ * pathを持ち込むことはないので、宣言が誤っていても存在しないsymbolへは束縛されない。
+ */
+function resolveConcernSymbolPath(queries, name, resourcePath) {
+  const receipt = queries.find((query) => (
+    query.operation === 'query' && query.target === name && query.resolved_name === name
+      && (query.outcome === 'resolved' || query.outcome === 'ambiguous')
+  ));
+  if (receipt === undefined) return null;
+  if (receipt.outcome === 'resolved') {
+    return typeof receipt.resolved_path === 'string' && receipt.resolved_path.length > 0
+      ? receipt.resolved_path : null;
+  }
+  const inside = (receipt.candidate_paths ?? [])
+    .filter((candidate) => pathContains(resourcePath, candidate));
+  return inside.length === 1 ? inside[0] : null;
+}
+
 /**
  * Resolve declared concern anchors against fresh sensor evidence.
  *
- * A declaration only becomes a binding anchor when the sensor resolves the exact name to exactly
- * one path and that path lies inside the declared resource. Fuzzy resolution to a neighbouring
- * symbol, an absent name, or a symbol living outside the contested resource yields a typed
- * unknown instead — a wrong declaration must never widen what the binder believes it knows.
+ * A declaration only becomes a binding anchor when the sensor resolves the exact name inside the
+ * declared resource to exactly one path. Fuzzy resolution to a neighbouring symbol, an absent
+ * name, or a symbol living outside the contested resource yields a typed unknown instead — a
+ * wrong declaration must never widen what the binder believes it knows.
+ *
+ * A name living in several files is resolved against the declared resource rather than being
+ * dropped (ADR 0134). The resource is one the ToDo already claims under `owns`, so this narrows
+ * the sensor's own candidate set; it never introduces a path the sensor did not report.
  *
  * Two ToDos claiming the same symbol is a contradiction in the declarations themselves, not a cut
  * to be discovered: the anchor is dropped from both and reported, so neither side can be bound by
@@ -808,7 +837,7 @@ export function resolveConcernAnchors({ manualWitness, taskIds, evidence } = {})
         continue;
       }
       for (const symbol of entry.symbols) {
-        const symbolPath = resolvedSymbolPath(queries, symbol);
+        const symbolPath = resolveConcernSymbolPath(queries, symbol, resourcePath);
         if (symbolPath === null) {
           unknowns.push({ kind: 'concern_anchor_unresolved', ref: `${taskId}:${symbol}` });
           continue;
@@ -1894,7 +1923,7 @@ function conflictComponents(independenceArtifact) {
 }
 
 /**
- * Build the immutable lattice.seam_proposal.v1 artifact from one complete independence record.
+ * Build the immutable lattice.seam_proposal.v2 artifact from one complete independence record.
  * Sensor collection stays outside this producer; callers pass the original witness evidence and
  * the seam-specific normalized/raw evidence collected for the same clean HEAD.
  */