@quolu/lattice 0.21.1 → 0.22.0

package/package.json

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

package/src/runtime-diff-observer.mjs

@@ -45,7 +45,7 @@ function sha256(bytes) {
   return createHash('sha256').update(bytes).digest('hex');
 }
 
-function run(command, args, cwd) {
+function run(command, args, cwd, { allowExitCodes = [0] } = {}) {
   return new Promise((resolve, reject) => {
     const child = spawn(command, args, { cwd, shell: false, stdio: ['ignore', 'pipe', 'pipe'] });
     const stdout = [];
@@ -54,7 +54,9 @@ function run(command, args, cwd) {
     child.stderr.on('data', (chunk) => stderr.push(chunk));
     child.once('error', reject);
     child.once('close', (code, signal) => {
-      if (code === 0 && signal === null) resolve(Buffer.concat(stdout));
+      if (allowExitCodes.includes(code) && signal === null) {
+        resolve(Object.assign(Buffer.concat(stdout), { code }));
+      }
       else {
         reject(new TypeError(
           `${command} ${args[0]} failed (${signal ?? code}): ${Buffer.concat(stderr).toString('utf8').trim()}`,
@@ -144,7 +146,13 @@ async function entryRecord(worktreePath, baseSha, entry) {
 
 /**
  * worktreeの実diffをbounded canonical recordへ変換する。
- * HEADがbase_shaから動いていた場合（commit等の禁止操作）はfail loud。
+ *
+ * HEADはbaseの子孫へ進んでよい（＝workerが自分のworktreeでcommitしてよい）。進んだ分は
+ * `base..HEAD`として観測へ含める。子孫でない位置へ動いた場合——reset、branch切替、rebase——は
+ * 観測の前提が壊れるのでfail loudする（ADR 0139）。
+ *
+ * commitを一律禁止していた頃は、進行中の成果が未commitのままworktreeにしか存在せず、
+ * 再計画がその変更を含まないsourceに対して行われていた。
  */
 export async function captureWorktreeDiff(options = {}) {
   if (!exactRecord(options, ['worktreePath', 'baseSha'])) {
@@ -156,7 +164,12 @@ export async function captureWorktreeDiff(options = {}) {
   }
   const head = (await run('git', ['rev-parse', 'HEAD'], worktreePath)).toString('utf8').trim();
   if (head !== baseSha) {
-    fail(`worktree HEADがbaseから動いている（commit等の禁止操作）: ${head}`);
+    const descendant = await run('git', ['merge-base', '--is-ancestor', baseSha, head], worktreePath, {
+      allowExitCodes: [0, 1],
+    });
+    if (descendant.code !== 0) {
+      fail(`worktree HEADがbaseの子孫でない（reset・branch切替・rebase）: ${head}`);
+    }
   }
   // ignored fileへのwriteもwrite sensorの対象にする（gitignore経由の
   // scope violation迂回を塞ぐ。isolation-runnerと同じ--ignored=matching）。
@@ -164,6 +177,17 @@ export async function captureWorktreeDiff(options = {}) {
     'status', '--porcelain=v1', '-z', '--untracked-files=all', '--ignored=matching',
   ], worktreePath);
   const entries = statusEntries(statusBytes);
+  // commit済みの変更はstatusへ出ない。base..HEADの範囲も観測へ入れないと、
+  // commitした瞬間に変更が観測から消える。
+  if (head !== baseSha) {
+    const committed = await run('git', [
+      'diff', '--name-status', '--no-renames', '-z', `${baseSha}..${head}`,
+    ], worktreePath);
+    const fields = committed.toString('utf8').split('\0').filter((field) => field.length > 0);
+    for (let index = 0; index + 1 < fields.length; index += 2) {
+      entries.push({ path: fields[index + 1], code: `${fields[index][0]} ` });
+    }
+  }
   if (entries.length > MAX_DIFF_ENTRIES) {
     fail(`diff entry数が上限を超える: ${entries.length}`);
   }
@@ -197,12 +221,15 @@ export async function captureWorktreeDiff(options = {}) {
   records.sort((left, right) => (left.path < right.path ? -1 : 1));
   // 観測中のHEAD移動（TOCTOU）を閉じる: 収集後に再確認する。
   const headAfter = (await run('git', ['rev-parse', 'HEAD'], worktreePath)).toString('utf8').trim();
-  if (headAfter !== baseSha) {
+  if (headAfter !== head) {
     fail(`観測中にworktree HEADが動いた: ${headAfter}`);
   }
   const record = {
-    schema: 'lattice.checkpoint_diff.v1',
+    schema: 'lattice.checkpoint_diff.v2',
     base_sha: baseSha,
+    // 生み出した木そのものを記録へ縛る。入力側のdigestだけでは、進行中の成果が
+    // どの状態だったかを後から指せない。
+    head_sha: head,
     entries: records,
   };
   return {

package/src/runtime-engine.mjs

@@ -31,8 +31,18 @@ import {
  */
 
 const ENGINE_ACTOR = 'lattice-runtime';
+/**
+ * workerへ配る禁止操作。
+ *
+ * `commit`は含めない。自分の隔離worktreeでdetached HEADへ進めるcommitは、canonical branchを
+ * 動かさず外部へ効果を出さない一方で、進行中の成果を耐久化し、diff観測が生み出した木そのものを
+ * 縛れるようにする（ADR 0139）。
+ *
+ * 禁止のままにするのは、HEADをbaseの子孫から外す操作と、外部へ効果を出す操作である。
+ * 前者は観測の前提を壊し、後者は承認なしに行わないという公開契約に当たる。
+ */
 const FORBIDDEN_OPERATIONS = Object.freeze([
-  'commit', 'push', 'branch', 'merge', 'rebase', 'reset', 'stash',
+  'push', 'branch', 'merge', 'rebase', 'reset', 'stash',
 ]);
 
 function fail(reason) {

package/src/runtime-seam-treatment.mjs

@@ -0,0 +1,153 @@
+/**
+ * 実行時競合を、実際の変換で解消する処置へ変える（請求項8・ADR 0137〜0139）。
+ *
+ * 実行時の入力は観測である。どのpathでどの2 taskがぶつかったかは`detectCheckpointFindings`が
+ * 実際に変更された資源から返すので、ここで影響範囲を探し直さない。
+ *
+ * 変換の導出はbase状態に対して行う。holdされたTODOは再計画で旧contextを失効させられ、
+ * 新plan_ref由来のpacketで再開するため、進行中の編集は設計上そこで捨てられる。
+ * `head_sha`が効くのは止めずに継続するcarry-over側であり、held側ではない。
+ */
+
+import { createHash } from 'node:crypto';
+
+import { canonicalizeArtifact } from './artifact-contracts.mjs';
+import { selfDigest } from './runtime-contracts.mjs';
+import { seamConflictFromFinding } from './seam-apply.mjs';
+
+const compareText = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+const sha16 = (value) => createHash('sha256').update(value, 'utf8').digest('hex').slice(0, 16);
+
+/** 資源idはidentifier規律なのでpathをそのまま使えない。boundary compilerと同じ合成形にする。 */
+export function pathResourceId(target) {
+  return `own-path-${sha16(target)}`;
+}
+
+function sealed(value, field) {
+  const record = { ...value, [field]: '' };
+  record[field] = selfDigest(record, field);
+  return record;
+}
+
+function canonicalSort(entries) {
+  return [...entries].sort((left, right) => compareText(
+    canonicalizeArtifact(left), canonicalizeArtifact(right),
+  ));
+}
+
+/**
+ * 採用された変換から、再計画が読む`lattice.runtime_seam_split.v1`を組む。
+ *
+ * 所有の差分は「係争資源の所有を降りて、自分の新資源を所有する」である。競合辺は消える——
+ * それが変換の目的であり、消えていなければ五条件のoverlap_reducedが通っていない。
+ */
+export function buildRuntimeSeamSplit({
+  conflict, candidate, taskMigrationDigest, verifierRefs = [],
+} = {}) {
+  const owned = (candidate?.surfaces ?? []).filter(({ role }) => role === 'task_owned');
+  if (owned.length < 2) return { split: null, reasons: ['owned_surfaces_below_two'] };
+  const sourceResource = pathResourceId(conflict.sourcePath);
+
+  const removed = canonicalSort(conflict.taskIds.map((taskId) => ({
+    resource_id: sourceResource, owner_todo_id: taskId, access_kind: 'own',
+  })));
+  const added = canonicalSort(owned.map((surface) => ({
+    resource_id: pathResourceId(surface.path),
+    owner_todo_id: surface.owner_task_ids[0],
+    access_kind: 'own',
+  })));
+
+  // 競合辺は消える側だけを載せる。変換で新しい競合を作っていないことは
+  // 五条件のoverlap_reduced（plan全体の競合対が増えない）が既に見ている。
+  const removedEdges = [];
+  for (let left = 0; left < conflict.taskIds.length; left += 1) {
+    for (let right = left + 1; right < conflict.taskIds.length; right += 1) {
+      const pair = [conflict.taskIds[left], conflict.taskIds[right]].sort(compareText);
+      removedEdges.push({ from_todo_id: pair[0], to_todo_id: pair[1], kind: 'conflict' });
+    }
+  }
+
+  const split = sealed({
+    schema: 'lattice.runtime_seam_split.v1',
+    finding_digest: conflict.findingDigest,
+    predecessor_task_ids: [...conflict.taskIds].sort(compareText),
+    task_migration_digest: taskMigrationDigest,
+    ownership_diff: sealed({
+      schema: 'lattice.runtime_ownership_diff.v1', added, removed, diff_digest: '',
+    }, 'diff_digest'),
+    edge_diff: sealed({
+      schema: 'lattice.runtime_edge_diff.v1',
+      added: [], removed: canonicalSort(removedEdges), diff_digest: '',
+    }, 'diff_digest'),
+    verifier_refs: [...new Set(verifierRefs)].sort(compareText),
+    split_digest: '',
+  }, 'split_digest');
+  return { split, reasons: [] };
+}
+
+/**
+ * 実行時競合の処置を決める。
+ *
+ * 事前宣言された処置があればそれを使う。無ければ**その場で変換候補を導出して適用を試みる**——
+ * ここが請求項8の一手で、従来は事前宣言が無い競合をすべて意図的直列へ倒していた。
+ *
+ * 変換は五条件を通ったときだけ処置になる。1つでも欠けたら意図的直列へ送り、欠けた条件を残す。
+ * 「実行時だから緩める」ことをしない——緩めると、外部挙動を変えうる変更が便益の証明なしに
+ * 実行中のrunへ入る。
+ */
+export async function resolveRuntimeSeamTreatment(options = {}) {
+  const {
+    finding, witnessSet, pathNames = {}, predeclaredTreatments = [],
+    applyConflict, baseSha, manifestDigest, affectedTests = [], taskMigrationDigest,
+  } = options;
+
+  if (finding?.kind === 'observed_write_conflict' && typeof finding.path === 'string') {
+    for (const treatment of predeclaredTreatments) {
+      if (Array.isArray(treatment.covered_paths) && treatment.covered_paths.includes(finding.path)) {
+        return { lane: 'seam_transform', treatment: structuredClone(treatment), split: null, reasons: [] };
+      }
+    }
+  }
+
+  const { conflict, reasons } = seamConflictFromFinding({
+    finding, witnessSet, pathNames, affectedTests, baseSha, manifestDigest,
+  });
+  if (conflict === null) {
+    return { lane: 'intentional_serial', treatment: null, split: null, reasons };
+  }
+  if (typeof applyConflict !== 'function') {
+    return {
+      lane: 'intentional_serial', treatment: null, split: null, reasons: ['applier_absent'],
+    };
+  }
+
+  const applied = await applyConflict({ conflict });
+  if (applied?.outcome?.decision !== 'accepted') {
+    return {
+      lane: 'intentional_serial',
+      treatment: null,
+      split: null,
+      reasons: [...(applied?.outcome?.reasons ?? ['transform_rejected'])],
+    };
+  }
+
+  const built = buildRuntimeSeamSplit({
+    conflict,
+    candidate: applied.candidate ?? { surfaces: applied.outcome.surfaces ?? [] },
+    taskMigrationDigest,
+    verifierRefs: affectedTests,
+  });
+  if (built.split === null) {
+    return { lane: 'intentional_serial', treatment: null, split: null, reasons: built.reasons };
+  }
+  return {
+    lane: 'seam_transform',
+    treatment: {
+      covered_paths: [conflict.sourcePath],
+      candidate_digest: applied.outcome.candidate_digest,
+    },
+    split: built.split,
+    files: applied.files ?? null,
+    reasons: [],
+  };
+}

package/src/todo-cli.mjs

@@ -4,6 +4,7 @@ import {
   lstat, mkdir, open, readFile, realpath, rename, rm, writeFile,
 } from 'node:fs/promises';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { parseTree } from 'jsonc-parser';
 
 import {
@@ -988,7 +989,9 @@ async function seamProposalApply({ repoRoot, planKey, pathNames = {}, land = fal
     pathNames,
     sourceProposal: artifact,
     witnessSet,
-    latticeBin: path.join(repoRoot, 'bin', 'lattice.mjs'),
+    // 配布物内の自分自身を指す。repoRoot配下を指すと、Lattice自身のrepositoryでしか動かない
+    // ——消費側のprojectに`bin/lattice.mjs`は存在しない。
+    latticeBin: fileURLToPath(new URL('../bin/lattice.mjs', import.meta.url)),
     sharedPathFor: (sourcePath) => sourcePath.replace(/(\.[^./]+)$/u, '.seam-shared$1'),
     executors: witnessSet.capacity.executors,
     compileIndependence: {