@quolu/lattice 0.22.0 → 0.24.0

package/package.json

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

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/runtime-managed-supervisor.mjs

@@ -92,6 +92,27 @@ export async function observeMacosBinaryIdentity(binaryPath) {
 }
 
 /** storeが解決したimmutable bindingからprocess/worktree/checkpointをDirect OSで再観測する。 */
+/**
+ * 本repositoryの現在状態を1つのdigestへ畳む。
+ *
+ * HEAD・作業ツリー状態（untracked／ignoredを含む）・全refを見る。workerがworktreeの外へ
+ * 書いてもworktreeのdiffには映らないので、ここだけが本repositoryへの書き込みを捕まえる。
+ */
+export async function canonicalRepositoryFingerprint(repoRoot) {
+  const parts = [];
+  for (const args of [
+    ['rev-parse', 'HEAD'],
+    ['status', '--porcelain=v1', '--untracked-files=all', '--ignored=matching'],
+    ['for-each-ref', '--format=%(refname) %(objectname)'],
+  ]) {
+    const { stdout } = await execFileAsync('git', args, {
+      cwd: repoRoot, encoding: 'utf8', maxBuffer: 32 * 1024 * 1024,
+    });
+    parts.push(stdout);
+  }
+  return createHash('sha256').update(parts.join('\u0000'), 'utf8').digest('hex');
+}
+
 export function createDirectOsProcessObserver({ resolveObservationBinding }) {
   if (typeof resolveObservationBinding !== 'function') fail('SUPERVISOR_CONFIGURATION_INVALID', 'observation binding resolverなし');
   return async ({ kind, binding, ack }) => {
@@ -104,6 +125,15 @@ export function createDirectOsProcessObserver({ resolveObservationBinding }) {
       || typeof resolved.base_sha !== 'string' || !/^[0-9a-f]{40}$/.test(resolved.base_sha)
       || !validateProcessStartIdentity(resolved.process_start_identity)
       || resolved.process_start_identity.pid !== resolved.process_pid) fail('HOLD_ACKS_INCOMPLETE', 'observation binding不正');
+    // 本repositoryを見る材料は対で渡す。片方だけでは照合できず、片方だけを受けると
+    // 「検査した」と読める記録が検査なしで作れてしまう。
+    const canonicalRoot = resolved.canonical_root ?? null;
+    const canonicalBaseline = resolved.canonical_fingerprint_digest ?? null;
+    if ((canonicalRoot === null) !== (canonicalBaseline === null)
+      || (canonicalRoot !== null && !path.isAbsolute(canonicalRoot))
+      || (canonicalBaseline !== null && !/^[0-9a-f]{64}$/u.test(canonicalBaseline))) {
+      fail('HOLD_ACKS_INCOMPLETE', 'canonical repository観測bindingが不正');
+    }
     let processState = 'exited';
     let observedIdentity = resolved.process_start_identity;
     let processGroupId = resolved.process_group_id;
@@ -145,7 +175,17 @@ export function createDirectOsProcessObserver({ resolveObservationBinding }) {
     const checkpoint = await captureWorktreeDiff({ worktreePath: worktreeRealpath, baseSha: resolved.base_sha });
     const processObservation = { schema: 'lattice.direct_process_observation.v1', pid: resolved.process_pid, process_start_identity_digest: observedIdentity.identity_digest, process_group_id: processGroupId, state: processState };
     const processObservationDigest = digestArtifact(processObservation);
-    const worktreeFingerprint = { schema: 'lattice.direct_worktree_fingerprint.v1', worktree_id: binding?.worktree_id ?? ack.worktree_id, worktree_realpath: worktreeRealpath, checkpoint_digest: checkpoint.checkpoint_digest };
+    // worktreeの外——本repository——への書き込みは、worktreeのdiffにはまったく映らない。
+    // 見ていないことを「変更が無かった」と読ませないため、検査したかどうかを記録へ残す
+    // （ADR 0140）。渡されていなければ`null`＝未検査であり、無変更の主張ではない。
+    let canonicalDigest = null;
+    if (canonicalRoot !== null) {
+      canonicalDigest = await canonicalRepositoryFingerprint(canonicalRoot);
+      if (canonicalDigest !== canonicalBaseline) {
+        fail('HOLD_ACKS_INCOMPLETE', 'canonical repositoryがworker実行中に変化した');
+      }
+    }
+    const worktreeFingerprint = { schema: 'lattice.direct_worktree_fingerprint.v2', worktree_id: binding?.worktree_id ?? ack.worktree_id, worktree_realpath: worktreeRealpath, checkpoint_digest: checkpoint.checkpoint_digest, canonical_fingerprint_digest: canonicalDigest };
     const worktreeFingerprintDigest = digestArtifact(worktreeFingerprint);
     return {
       quiesced: true,