@quolu/lattice 0.23.0 → 0.25.0

package/package.json

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

package/src/cli-help.mjs

@@ -70,6 +70,7 @@ Write commands:
   evidence promote --plan <key> --task <id> --evidence <file>
   independence compile --plan <key> --input <file>  # witness setとsensorから並列可否を記録する
   independence witness migrate --plan <key>  # revision後の宣言をtask migrationで写す
+  independence witness scaffold --plan <key> --input <draft>  # 下書きとfresh観測から宣言を書き出す
   seam-proposal compile --plan <key>  # 並列可否記録と実sensorからseam提案を記録する
   seam-proposal apply --plan <key>  # 記録済み提案を隔離worktreeで適用し五条件で採否を決める
   seam-proposal land --plan <key> --names <file>  # 採用された変換を本ツリーへ着地させる

package/src/runtime-hold-recompile.mjs

@@ -66,6 +66,7 @@ function sha16(value) {
 const WITNESS_KINDS = Object.freeze(['state', 'schema', 'invariant', 'effect', 'external_effect']);
 const HEX_DIGEST = /^[0-9a-f]{64}$/u;
 const IDENTIFIER = /^[0-9A-Za-z](?:[0-9A-Za-z._-]{0,127})$/u;
+const compareText = (left, right) => left < right ? -1 : left > right ? 1 : 0;
 
 function selfDigestValid(value, field) {
   return plainRecord(value) && HEX_DIGEST.test(value[field] ?? '')
@@ -532,6 +533,67 @@ export function decideHoldAndCarryOver(options = {}) {
  * predeclared treatmentがfindingのpath集合を覆う場合だけseam laneを返し、
  * それ以外（shared state/effect・未宣言path競合）はintentional serialにする。
  */
+/**
+ * 同じ競合が何epochにわたって観測されたかを数える。
+ *
+ * 過去epochのconflictを再seedしないguardは既に在るが、**新しく観測された同じ競合**は毎epoch
+ * seedされる。原因が続く限り「hold→再計画→再開→また同じ競合」が繰り返せる。
+ * 誤帰属でも、scope違反を繰り返すworkerでも、変換で解けない競合でも同じことが起きる。
+ *
+ * 鍵は種別・資源・関与task対である。plan_epochで数えるのは、同一epoch内の複数回観測を
+ * 繰り返しと数えないためで、再計画を1回挟んで再び現れたことだけを繰り返しとする。
+ */
+export function countConflictRecurrence(events = []) {
+  const epochsByKey = new Map();
+  for (const event of events) {
+    if (event?.kind !== 'conflict_found') continue;
+    const finding = event.payload ?? {};
+    if (typeof finding.kind !== 'string' || !Array.isArray(finding.todo_ids)) continue;
+    const key = [
+      finding.kind,
+      typeof finding.path === 'string' ? finding.path : '',
+      [...finding.todo_ids].sort(compareText).join(','),
+    ].join('\u0000');
+    if (!epochsByKey.has(key)) epochsByKey.set(key, new Set());
+    epochsByKey.get(key).add(event.plan_epoch);
+  }
+  return epochsByKey;
+}
+
+/**
+ * 再計画で解けていない競合。1つでもあれば、もう一度同じ処置を試しても収束しない。
+ *
+ * 既定の閾値を3とするのは、1回目は通常の競合、2回目は再計画が効かなかった可能性（順序の綾を
+ * 含む）、3回目で「同じことが繰り返されている」と言えるためである。直列化で誤魔化さない——
+ * 誤帰属が原因なら直列化しても解けず、解けないことを解けたように見せることになる。
+ */
+export const NON_CONVERGENT_EPOCH_THRESHOLD = 3;
+
+export function detectNonConvergentConflicts(options = {}) {
+  if (!exactRecord(options, ['events']) && !exactRecord(options, ['events', 'threshold'])) {
+    fail('detectNonConvergentConflicts optionsがexact shapeでない');
+  }
+  const { events, threshold = NON_CONVERGENT_EPOCH_THRESHOLD } = options;
+  if (!Array.isArray(events)) fail('eventsがarrayでない');
+  if (!Number.isSafeInteger(threshold) || threshold < 2) fail('thresholdが2以上の整数でない');
+  const recurrence = countConflictRecurrence(events);
+  const entries = [];
+  for (const [key, epochs] of recurrence) {
+    if (epochs.size < threshold) continue;
+    const [kind, resource, todoIds] = key.split('\u0000');
+    entries.push({
+      kind,
+      resource,
+      todo_ids: todoIds === '' ? [] : todoIds.split(','),
+      epochs: [...epochs].sort((left, right) => left - right),
+    });
+  }
+  return entries.sort((left, right) => compareText(
+    `${left.kind}\u0000${left.resource}\u0000${left.todo_ids.join(',')}`,
+    `${right.kind}\u0000${right.resource}\u0000${right.todo_ids.join(',')}`,
+  ));
+}
+
 export function routeConflictTreatment(options = {}) {
   if (!exactRecord(options, ['finding', 'predeclaredTreatments'])) {
     fail('routeConflictTreatment optionsがexact shapeでない');
@@ -567,6 +629,14 @@ export function recompileNextEpochPlan(options = {}) {
   if (!validateRuntimePlan(plan)) fail('planがruntime_plan.v1 contractを満たさない');
   if (!validateHoldDecision(holdDecision)) fail('holdDecisionがcontractを満たさない');
   if (!Array.isArray(additionalConflicts)) fail('additionalConflictsがarrayではない');
+  // 同じ競合が閾値のepoch数だけ繰り返しているなら、もう一度同じ処置を試しても収束しない。
+  // 直列化やもう1周で誤魔化さず、解けていないことをtypedに述べて止める。
+  const nonConvergent = detectNonConvergentConflicts({ events });
+  if (nonConvergent.length > 0) {
+    fail(`再計画で解けていない競合がある（非収束）: ${nonConvergent
+      .map((entry) => `${entry.kind}:${entry.resource}:${entry.todo_ids.join(',')}@${entry.epochs.join('/')}`)
+      .join(' ')}`);
+  }
 
   const state = projectRuntimeState({ events });
   if (state.freeze === null) fail('freeze中でないprefixからrecompileできない');

package/src/todo-cli.mjs

@@ -85,7 +85,12 @@ import {
   validateSeamProposalProjection,
 } from './seam-proposal-contracts.mjs';
 import { compileSeamProposalArtifact, declaredConcernSymbols } from './seam-proposal.mjs';
+import { collectSensorEvidence } from './sensor-adapter.mjs';
 import { applySeamProposal } from './seam-apply.mjs';
+import {
+  WITNESS_DRAFT_SCHEMA, buildWitnessObservationQuerySet, buildWitnessSet, serializeWitnessSet,
+  validateWitnessDraft,
+} from './witness-scaffold.mjs';
 import {
   parseTodoSourceRef, todoLegacyReconciliationDigest, validatePhaseTodoRevision,
   validateTodoRevision, validateTodoRevisionSet,
@@ -938,6 +943,53 @@ async function seamProposalCompile({ repoRoot, planKey }) {
   return result;
 }
 
+/**
+ * 下書きとfresh観測から、そのまま通るwitness setを書き出す。
+ *
+ * 推定はしない。何を所有し何を触るかは下書きが述べ、ここが供給するのはAIには作れないもの——
+ * affected testのfresh観測、query setとprovenanceの配線、canonical bytesと自己digest——だけである。
+ */
+async function witnessScaffold({ repoRoot, planKey, inputRef }) {
+  const draft = await readJsonInput(repoRoot, inputRef, {
+    validate: validateWitnessDraft,
+    invalidCode: 'WITNESS_DRAFT_INVALID',
+  });
+  if (draft.plan_key !== planKey) {
+    throw new TodoStoreError('INPUT_INVALID', 'witness_draft_plan_mismatch', undefined, {
+      draft_plan_key: draft.plan_key, plan_key: planKey,
+    });
+  }
+  const { queries, paths } = buildWitnessObservationQuerySet(draft);
+  const collected = await collectSensorEvidence({ cwd: repoRoot, querySet: { queries } });
+  const affectedTestsByPath = {};
+  queries.forEach((query, index) => {
+    if (query.operation !== 'affected') return;
+    const entry = collected.outcomes[index]?.targets?.[0];
+    // 観測できていないものを空配列へ丸めない。丸めるとdriftでcompileが落ちる。
+    if (entry?.path_state === 'absent' || !Array.isArray(entry?.data?.affectedTests)) return;
+    affectedTestsByPath[query.target] = [...entry.data.affectedTests];
+  });
+  const { witnessSet, reasons } = buildWitnessSet({ draft, affectedTestsByPath });
+  if (witnessSet === null) {
+    throw new TodoStoreError('WITNESS_SCAFFOLD_INCOMPLETE', 'witness_scaffold_incomplete', undefined, {
+      reasons, next_action: 'resolve_declaration_then_retry',
+    });
+  }
+  const ref = todoWitnessRef(planKey);
+  await mkdir(path.dirname(path.join(repoRoot, ref)), { recursive: true });
+  await writeFile(path.join(repoRoot, ref), serializeWitnessSet(witnessSet));
+  return {
+    schema: 'lattice.todo_witness_scaffold_result.v1',
+    project_id: draft.project_id,
+    plan_key: planKey,
+    witness_ref: ref,
+    observed_paths: paths,
+    task_count: Object.keys(witnessSet.manual_witness).length,
+    witness_set_digest: witnessSet.witness_set_digest,
+    next_action: 'compile_independence',
+  };
+}
+
 /**
  * 着地時に使うsurface名。提案が出すhash由来の仮名を、人が読む名前へ置き換える。
  *
@@ -1729,6 +1781,10 @@ export async function runTodoCli({ argv, cwd, stdout, stderr, env = process.env
   } else if (argv.length === 4 && argv[0] === 'seam-proposal' && argv[1] === 'apply'
     && argv[2] === '--plan' && isTodoIdentifier(argv[3])) {
     action = (repoRoot) => seamProposalApply({ repoRoot, planKey: argv[3] });
+  } else if (argv.length === 7 && argv[0] === 'independence' && argv[1] === 'witness'
+    && argv[2] === 'scaffold' && argv[3] === '--plan' && isTodoIdentifier(argv[4])
+    && argv[5] === '--input' && isTodoRef(argv[6])) {
+    action = (repoRoot) => witnessScaffold({ repoRoot, planKey: argv[4], inputRef: argv[6] });
   } else if (argv.length === 6 && argv[0] === 'seam-proposal' && argv[1] === 'land'
     && argv[2] === '--plan' && isTodoIdentifier(argv[3])
     && argv[4] === '--names' && isTodoRef(argv[5])) {

package/src/witness-scaffold.mjs

@@ -0,0 +1,150 @@
+/**
+ * 宣言を書くための道具（AGENTS.md「装置の境界」）。
+ *
+ * 推定はしない。何を所有し、係争資源の中で何を触るかはAIが決める——Latticeを操作するAIは装置の
+ * 一部であり、そこへ同じ能力を二重化しない。ここが供給するのは、AIには作れないものだけである。
+ *
+ * - `affected_tests`のfresh観測。宣言と観測はbinding単位でexact比較されるので、手で当てると外れる。
+ * - `sensor_query_set`と`sensor_provenance`の配線。宣言と観測の裏付けが別の資源を指す事故を防ぐ。
+ * - canonical bytesと自己digest。非canonicalな宣言は独立性判定を通ってseam提案でだけ落ちる。
+ *
+ * この3つは2026-07-27の作業で実際に踏んだ摩擦であり、道具が無いと毎回踏む。
+ */
+
+import { canonicalizeTodoArtifact, isTodoIdentifier, isTodoRef, todoSelfDigest } from './todo-contracts.mjs';
+import { TODO_WITNESS_SET_SCHEMA } from './todo-independence-contracts.mjs';
+
+const compareText = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+const sortedUnique = (values) => [...new Set(values)].sort(compareText);
+
+export const WITNESS_DRAFT_SCHEMA = 'lattice.todo_witness_draft.v1';
+
+function reject(reasons) {
+  return { witnessSet: null, queries: [], reasons: sortedUnique(reasons) };
+}
+
+/** 下書きの形。AIが書く欄だけを持ち、観測で埋まる欄は持たない。 */
+export function validateWitnessDraft(value) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return false;
+  if (value.schema !== WITNESS_DRAFT_SCHEMA) return false;
+  if (!isTodoIdentifier(value.project_id) || !isTodoIdentifier(value.plan_key)) return false;
+  if (value.capacity === null || typeof value.capacity !== 'object'
+    || !Number.isSafeInteger(value.capacity.executors) || value.capacity.executors < 1) return false;
+  if (value.tasks === null || typeof value.tasks !== 'object' || Array.isArray(value.tasks)) return false;
+  const entries = Object.entries(value.tasks);
+  if (entries.length === 0) return false;
+  return entries.every(([taskId, task]) => isTodoIdentifier(taskId)
+    && task !== null && typeof task === 'object' && !Array.isArray(task)
+    && Array.isArray(task.owns) && task.owns.every(isTodoRef)
+    && (task.reads === undefined || (Array.isArray(task.reads) && task.reads.every(isTodoRef)))
+    && (task.unknowns === undefined || (Array.isArray(task.unknowns)
+      && task.unknowns.every((entry) => entry !== null && typeof entry === 'object'
+        && isTodoIdentifier(entry.kind) && typeof entry.ref === 'string' && entry.ref.length > 0)))
+    && (task.concern_anchors === undefined || (Array.isArray(task.concern_anchors)
+      && task.concern_anchors.every((anchor) => anchor !== null && typeof anchor === 'object'
+        && isTodoRef(anchor.within) && Array.isArray(anchor.symbols)
+        && anchor.symbols.length > 0 && anchor.symbols.every(isTodoIdentifier)))));
+}
+
+function queryIdFor(index) {
+  return `witness-affected-${String(index).padStart(3, '0')}`;
+}
+
+/** 下書きから、観測に要るquery setを組む。所有pathごとに1つのaffected queryを引く。 */
+export function buildWitnessObservationQuerySet(draft) {
+  const paths = sortedUnique(Object.values(draft.tasks).flatMap(({ owns }) => owns));
+  return {
+    queries: [
+      { id: 'witness-status', operation: 'status' },
+      ...paths.map((target, index) => ({
+        id: queryIdFor(index), operation: 'affected', target,
+      })),
+    ],
+    paths,
+  };
+}
+
+/**
+ * 下書きと観測から、そのまま通るwitness setを組む。
+ *
+ * @param {object} options
+ * @param {object} options.draft `lattice.todo_witness_draft.v1`
+ * @param {object} options.affectedTestsByPath 所有pathごとのfresh観測
+ */
+export function buildWitnessSet({ draft, affectedTestsByPath } = {}) {
+  if (!validateWitnessDraft(draft)) return reject(['draft_invalid']);
+  const { paths } = buildWitnessObservationQuerySet(draft);
+  const queryIdByPath = new Map(paths.map((target, index) => [target, queryIdFor(index)]));
+
+  const reasons = [];
+  const manualWitness = {};
+  for (const [taskId, task] of Object.entries(draft.tasks).sort(([left], [right]) => compareText(left, right))) {
+    const owns = sortedUnique(task.owns);
+    if (owns.length === 0) { reasons.push(`owns_empty:${taskId}`); continue; }
+    // affected_testsは宣言とfresh観測をbinding単位でexact比較する。複数pathを所有すると
+    // 観測集合が一致しない限り必ず落ちるので、今の契約では表現できない（2026-07-27の実測）。
+    if (owns.length > 1) { reasons.push(`multiple_owned_paths_unsupported:${taskId}`); continue; }
+    const [target] = owns;
+    const affected = affectedTestsByPath?.[target];
+    // 観測できていないことを空配列へ丸めない。丸めるとdriftでcompileが落ちる。
+    if (!Array.isArray(affected)) { reasons.push(`affected_tests_unobserved:${target}`); continue; }
+    for (const anchor of task.concern_anchors ?? []) {
+      // `within`は自分が所有している資源に限る。所有していない資源の内側に担当を主張させない。
+      if (!owns.includes(anchor.within)) reasons.push(`anchor_outside_owned:${taskId}:${anchor.within}`);
+    }
+    manualWitness[taskId] = {
+      owns: [{ kind: 'path', target }],
+      reads: sortedUnique(task.reads ?? []),
+      writes: [target],
+      resources: [],
+      state_effects: [],
+      sensor_provenance: {
+        queries: [{
+          query_id: queryIdByPath.get(target),
+          expect: { kind: 'affected', path: target },
+        }],
+      },
+      affected_tests: sortedUnique(affected),
+      // 明示unknownは下書きが持つ。観測で埋まる欄ではなく、書き手が「ここは確定していない」と
+      // 述べる欄なので、道具が発明も削除もしない。
+      unknowns: [...(task.unknowns ?? [])]
+        .map(({ kind, ref }) => ({ kind, ref }))
+        .sort((left, right) => compareText(`${left.kind}\u0000${left.ref}`, `${right.kind}\u0000${right.ref}`)),
+      ...(Array.isArray(task.concern_anchors) && task.concern_anchors.length > 0
+        ? {
+          concern_anchors: [...task.concern_anchors]
+            .map((anchor) => ({
+              within: { kind: 'path', target: anchor.within },
+              symbols: sortedUnique(anchor.symbols),
+            }))
+            .sort((left, right) => compareText(left.within.target, right.within.target)),
+        }
+        : {}),
+    };
+  }
+  if (reasons.length > 0) return reject(reasons);
+
+  const witnessSet = {
+    schema: TODO_WITNESS_SET_SCHEMA,
+    project_id: draft.project_id,
+    plan_key: draft.plan_key,
+    capacity: { executors: draft.capacity.executors },
+    sensor_query_set: {
+      queries: [
+        ...paths.map((target) => ({
+          id: queryIdByPath.get(target), operation: 'affected', target,
+        })),
+        { id: 'witness-status', operation: 'status' },
+      ].sort((left, right) => compareText(left.id, right.id)),
+    },
+    manual_witness: manualWitness,
+    witness_set_digest: '',
+  };
+  witnessSet.witness_set_digest = todoSelfDigest(witnessSet, 'witness_set_digest');
+  return { witnessSet, reasons: [] };
+}
+
+/** storeへ置くbytes。canonical＋末尾LFでないと、判定は通るのにseam提案で落ちる。 */
+export function serializeWitnessSet(witnessSet) {
+  return `${canonicalizeTodoArtifact(witnessSet)}\n`;
+}