@quolu/lattice 0.17.0 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quolu/lattice",
-  "version": "0.17.0",
+  "version": "0.19.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.
  */

package/src/todo-cli.mjs

@@ -461,6 +461,7 @@ async function startAdvisory({ repoRoot, store, projection, planKey, taskId }) {
       contractSuperseded: isTodoIndependenceLegacyMarker(artifact),
       conflictWithActive: conflictsWithActive[0]?.severability ?? null,
       conflictBetweenReady: readyConflict?.severability ?? null,
+      verdictsAbsent: selfUnknowns.some(({ kind }) => kind === 'plan_verdicts_absent'),
     }),
   };
 }
@@ -836,6 +837,8 @@ async function independence({ repoRoot, requestedPlanKey }) {
         .some(({ unknowns }) => unknowns.some(({ kind }) => kind === 'record_stale')),
       conflictWithActive: projected.frontier.conflicts_with_active[0]?.severability ?? null,
       conflictBetweenReady: projected.frontier.serialize_pairs[0]?.severability ?? null,
+      verdictsAbsent: projected.frontier.unknown
+        .some(({ unknowns }) => unknowns.some(({ kind }) => kind === 'plan_verdicts_absent')),
     }),
     frontier: projected.frontier,
     result_digest: '',

package/src/todo-independence-guidance.mjs

@@ -17,6 +17,7 @@ export const TODO_INDEPENDENCE_GUIDANCE_CODES = Object.freeze([
   'independence_stale_for_task',
   'independence_conflict_with_active',
   'independence_conflict_between_ready',
+  'independence_verdicts_absent',
   'independence_verified',
 ]);
 
@@ -90,6 +91,10 @@ const CATALOG = Object.freeze({
     message: '他のready工程と同じ資源を書く記録がある。同時に着手すると衝突する。',
     next_action: 'serialize_or_split_boundary',
   }),
+  independence_verdicts_absent: Object.freeze({
+    message: '判定が途中で止まっており、記録はどの組についてもverdictを持たない。自分にunknownが無いことは、他と干渉しない証拠にならない。',
+    next_action: 'resolve_unknowns_then_recompile',
+  }),
   independence_verified: Object.freeze({
     message: '記録時点の宣言境界では、他のready工程と干渉しない。',
     next_action: 'none',
@@ -164,7 +169,7 @@ export function todoIndependenceGuidance(code, { severability = null } = {}) {
  */
 export function selectIndependenceGuidance({
   coverage, taskDeclared, taskStale, conflictWithActive = null, conflictBetweenReady = null,
-  contractSuperseded = false, readyCount = null,
+  contractSuperseded = false, readyCount = null, verdictsAbsent = false,
 }) {
   // 着手候補が無いなら述べる対象が無い。ここを通さないと、readyが空のとき
   // 「未検査taskが1件も無い」が空虚に真になり、記録が古くても検証済みへ倒れる。
@@ -186,6 +191,9 @@ export function selectIndependenceGuidance({
   if (coverage === 'superseded') return todoIndependenceGuidance('independence_superseded');
   if (!taskDeclared) return todoIndependenceGuidance('independence_task_undeclared');
   if (taskStale) return todoIndependenceGuidance('independence_stale_for_task');
+  // 記録は新しく、この工程自身にも問題が無い。それでもverdictが1つも無いなら、
+  // 述べられるのは「干渉しない」ではなく「まだ何も判定していない」である。
+  if (verdictsAbsent) return todoIndependenceGuidance('independence_verdicts_absent');
   return todoIndependenceGuidance('independence_verified');
 }
 

package/src/todo-independence.mjs

@@ -386,6 +386,18 @@ export function projectIndependenceFrontier({
   for (const entry of artifact.unknowns) {
     if (ready.includes(entry.task_id)) noteUnknown(entry.task_id, entry.kind, entry.ref);
   }
+  // 記録全体がverdictを持たない場合、どのpairについても判定は存在しない。
+  //
+  // compileがBOUNDARY_UNKNOWNで止まると、front endはpairwise verdictを1つも返さないので
+  // artifact.conflictsは空になる。この空をそのまま読むと、自分にunknownが無いreadyどうしが
+  // 「ぶつかる記録が無い＝独立」として並列グループへ入る。実際には**誰についても判定していない**。
+  // 新規fileを1つ宣言したToDoが混ざるだけで、無関係なToDoの実competitionが消えて
+  // 検証済み並列に見える——不在を証拠に読み替える、最も危険な向きの誤りである。
+  if (artifact.outcome !== 'compiled') {
+    for (const taskId of ready) {
+      if (covered.has(taskId)) noteUnknown(taskId, 'plan_verdicts_absent', artifact.outcome);
+    }
+  }
   // planが進んだ記録はtask単位に救えない（topology自体が別物）。
   // HEADだけが進んだ場合は、宣言境界に触れたtaskだけを落とす。
   if (coverage === 'superseded') {