@quolu/lattice 0.1.0

package/src/runtime-projection.mjs

@@ -0,0 +1,180 @@
+// RC3 runtime state projection（ADR 0044 Decision 3.3）。
+// runtime stateは保存event prefixからのprojectionとしてのみ再構成し、可変summary、
+// executor自己申告、in-memory stateを証拠にしない。本moduleはevent列を唯一の入力に
+// した純関数であり、producer（runtime本体）にもverifierにも依存しない。
+
+function invalidProjection(reason) {
+  throw new TypeError(`runtime projection契約違反: ${reason}`);
+}
+
+function sortedArray(iterable) {
+  return [...iterable].sort();
+}
+
+/**
+ * event prefixからruntime stateを再構成する。
+ * @param {{ events: Array<object> }} options
+ * @returns {object} 再構成されたstate（全collectionは決定論的順序）
+ */
+export function projectRuntimeState(options = {}) {
+  if (options === null || typeof options !== 'object' || Array.isArray(options)
+    || !Array.isArray(options.events)) {
+    invalidProjection('eventsの配列が必要');
+  }
+  const { events } = options;
+
+  const dispatched = new Set();
+  const dispatches = new Map();
+  const running = new Set();
+  const accepted = new Set();
+  const terminal = new Set();
+  const receipts = [];
+  const checkpoints = [];
+  const conflicts = [];
+  const holds = [];
+  const witnesses = new Map();
+  const rebinds = new Map();
+  const invalidatedContexts = [];
+  let freeze = null;
+  const freezeHistory = [];
+  let closed = false;
+
+  let previousSequence = -1;
+  for (const event of events) {
+    if (event === null || typeof event !== 'object') {
+      invalidProjection('eventはplain objectでなければならない');
+    }
+    // 順序judgementはsequenceが正であり、配列順との不一致を黙ってsortで直さない
+    // （ADR 0044 Decision 3.4のfail-loud側）。
+    if (!Number.isSafeInteger(event.sequence) || event.sequence <= previousSequence) {
+      invalidProjection('event列がsequence昇順で保存されていない');
+    }
+    previousSequence = event.sequence;
+    const todoRef = event.subject?.kind === 'todo' ? event.subject.ref : null;
+    switch (event.kind) {
+      case 'executor_dispatched':
+        if (todoRef === null) invalidProjection('executor_dispatchedはtodo subjectが必要');
+        dispatched.add(todoRef);
+        running.add(todoRef);
+        dispatches.set(todoRef, {
+          sequence: event.sequence,
+          payload: structuredClone(event.payload),
+        });
+        break;
+      case 'checkpoint_observed':
+        if (todoRef === null) invalidProjection('checkpoint_observedはtodo subjectが必要');
+        checkpoints.push({
+          todo_id: todoRef,
+          sequence: event.sequence,
+          payload: event.payload,
+        });
+        break;
+      case 'receipt_recorded':
+        if (todoRef === null) invalidProjection('receipt_recordedはtodo subjectが必要');
+        receipts.push({
+          receipt_id: typeof event.payload?.receipt_id === 'string'
+            ? event.payload.receipt_id
+            : `${todoRef}#seq${event.sequence}`,
+          todo_id: todoRef,
+          sequence: event.sequence,
+          plan_epoch: event.plan_epoch,
+          payload: structuredClone(event.payload),
+          accepted_sequence: null,
+          rejected_sequence: null,
+        });
+        break;
+      case 'receipt_accepted': {
+        if (todoRef === null) invalidProjection('receipt_acceptedはtodo subjectが必要');
+        const pending = receipts.findLast((receipt) => (
+          receipt.todo_id === todoRef
+          && receipt.accepted_sequence === null
+          && receipt.rejected_sequence === null
+        ));
+        if (pending !== undefined) pending.accepted_sequence = event.sequence;
+        accepted.add(todoRef);
+        running.delete(todoRef);
+        break;
+      }
+      case 'receipt_rejected': {
+        if (todoRef === null) invalidProjection('receipt_rejectedはtodo subjectが必要');
+        const pending = receipts.findLast((receipt) => (
+          receipt.todo_id === todoRef
+          && receipt.accepted_sequence === null
+          && receipt.rejected_sequence === null
+        ));
+        if (pending !== undefined) pending.rejected_sequence = event.sequence;
+        break;
+      }
+      case 'conflict_found':
+        conflicts.push({ sequence: event.sequence, ...structuredClone(event.payload) });
+        break;
+      case 'intake_frozen':
+        freeze = {
+          sequence: event.sequence,
+          frozen_prefix_digest: event.payload?.frozen_prefix_digest ?? null,
+        };
+        break;
+      case 'intake_resumed':
+        if (freeze !== null) {
+          freezeHistory.push({ ...freeze, resumed_sequence: event.sequence });
+          freeze = null;
+        }
+        break;
+      case 'hold_decided':
+        holds.push({ sequence: event.sequence, ...structuredClone(event.payload) });
+        break;
+      case 'carry_over_witnessed':
+        if (todoRef === null) invalidProjection('carry_over_witnessedはtodo subjectが必要');
+        witnesses.set(todoRef, {
+          sequence: event.sequence,
+          payload: structuredClone(event.payload),
+        });
+        break;
+      case 'epoch_rebound':
+        if (todoRef === null) invalidProjection('epoch_reboundはtodo subjectが必要');
+        rebinds.set(todoRef, {
+          sequence: event.sequence,
+          payload: structuredClone(event.payload),
+        });
+        break;
+      case 'context_invalidated':
+        invalidatedContexts.push({ sequence: event.sequence, todo_id: todoRef });
+        break;
+      case 'executor_terminal':
+        if (todoRef !== null) {
+          running.delete(todoRef);
+          terminal.add(todoRef);
+        }
+        break;
+      case 'run_closed':
+        closed = true;
+        break;
+      case 'run_initialized':
+      case 'plan_compiled':
+      case 'plan_verified':
+      case 'dispatch_decided':
+      case 'plan_recompiled':
+        break;
+      default:
+        invalidProjection(`未知のevent kind: ${String(event.kind)}`);
+    }
+  }
+
+  return {
+    dispatched: sortedArray(dispatched),
+    dispatches: Object.fromEntries([...dispatches.entries()].sort(([a], [b]) => (a < b ? -1 : 1))),
+    running: sortedArray(running),
+    accepted: sortedArray(accepted),
+    terminal: sortedArray(terminal),
+    receipts,
+    checkpoints,
+    conflicts,
+    holds,
+    witnesses: Object.fromEntries([...witnesses.entries()].sort(([a], [b]) => (a < b ? -1 : 1))),
+    rebinds: Object.fromEntries([...rebinds.entries()].sort(([a], [b]) => (a < b ? -1 : 1))),
+    invalidated_contexts: invalidatedContexts,
+    freeze,
+    freeze_history: freezeHistory,
+    closed,
+  };
+}

package/src/runtime-scripted-executor.mjs

@@ -0,0 +1,163 @@
+import { selfDigest, validateExecutorPacket } from './runtime-contracts.mjs';
+
+/**
+ * RC3-E 決定論的scripted executor adapter（ADR 0044 Decision 9）。
+ *
+ * provider非依存adapter interfaceのprimary実装。挙動はscript（TODOごとのstep列）
+ * だけで決まり、wall-clock・乱数・環境に依存しない。scripted campaign（RC3-H）が
+ * 既知の正解集合を持つ条件注入に使う。
+ *
+ * adapter interface（provider非依存契約）:
+ *   dispatch({ packet })            → { executor_handle, worktree_id }
+ *   observe({ executor_handle })    → { state: 'running' }
+ *                                    | { state: 'unknown' }                    … timeout相当
+ *                                    | { state: 'checkpoint_ready', checkpoint }
+ *                                    | { state: 'terminal', receipt }
+ *
+ * - 同一taskの重複dispatchはtyped rejectする（Decision 9.4）。
+ * - `unknown`はfailureではない。同一handleでの再observeだけが正規の回収経路で、
+ *   scriptは`stall`stepでこの経路を決定論的に再現する。
+ * - terminal receiptはdispatch済みpacketへ帰属し（handle・worktree・packet digest）、
+ *   scriptのoverridesで帰属破壊・stale epoch等の敵対条件を注入できる。
+ */
+
+const STEP_KINDS = new Set(['checkpoint', 'stall', 'hold_request', 'terminal']);
+
+function fail(reason) {
+  throw new TypeError(`scripted executor契約違反: ${reason}`);
+}
+
+function plainRecord(value) {
+  return value !== null
+    && typeof value === 'object'
+    && !Array.isArray(value)
+    && Object.getPrototypeOf(value) === Object.prototype;
+}
+
+function validateScript(script) {
+  if (!plainRecord(script)) fail('scriptがplain objectではない');
+  for (const [todoId, steps] of Object.entries(script)) {
+    if (!Array.isArray(steps) || steps.length === 0) fail(`script.${todoId}がstep配列ではない`);
+    for (const step of steps) {
+      if (!plainRecord(step) || !STEP_KINDS.has(step.kind)) {
+        fail(`script.${todoId}に未知のstepがある: ${String(step?.kind)}`);
+      }
+    }
+    if (steps.filter((step) => step.kind === 'terminal').length > 1) {
+      fail(`script.${todoId}のterminal stepは1つまで`);
+    }
+  }
+}
+
+/**
+ * script駆動のexecutor adapterを作る。
+ */
+export function createScriptedExecutorAdapter(options = {}) {
+  if (!plainRecord(options) || !plainRecord(options.script)) {
+    fail('createScriptedExecutorAdapter optionsが不正');
+  }
+  validateScript(options.script);
+  const script = structuredClone(options.script);
+
+  // handle → { packet, steps, cursor, terminalReported }
+  const active = new Map();
+  // 重複拒否はtodo_id単位（task_refの付け替えによる同一TODOの二重起動と、
+  // 決定論的handleの衝突・上書きを塞ぐ。review P1採用）。redispatchは
+  // RC3-Gの新context契約が新しいadapter instanceで行う。
+  const dispatchedTodoIds = new Set();
+
+  function buildReceipt(handleState, step) {
+    const { packet } = handleState;
+    const overrides = plainRecord(step.receipt_overrides) ? step.receipt_overrides : {};
+    const receipt = {
+      schema: 'lattice.executor_receipt.v1',
+      receipt_id: `${packet.todo_id}-r1`,
+      executor_handle: handleState.executorHandle,
+      worktree_id: handleState.worktreeId,
+      base_sha: packet.base_sha,
+      plan_epoch: packet.plan_epoch,
+      packet_digest: packet.packet_digest,
+      todo_id: packet.todo_id,
+      checkpoint_digest: typeof step.checkpoint_digest === 'string'
+        ? step.checkpoint_digest
+        : (handleState.lastCheckpointDigest ?? 'c'.repeat(64)),
+      observed_diff: Array.isArray(step.observed_diff)
+        ? structuredClone(step.observed_diff)
+        : packet.scope.writes.map((path) => ({ path, change: 'modified' })),
+      ...structuredClone(overrides),
+    };
+    receipt.receipt_digest = selfDigest(receipt, 'receipt_digest');
+    return receipt;
+  }
+
+  return {
+    kind: 'scripted',
+
+    async dispatch({ packet } = {}) {
+      if (!validateExecutorPacket(packet)) fail('dispatchにはexecutor_packet.v1が必要');
+      const steps = script[packet.todo_id];
+      if (steps === undefined) fail(`scriptに存在しないTODOをdispatchできない: ${packet.todo_id}`);
+      if (dispatchedTodoIds.has(packet.todo_id)) {
+        fail(`同一TODOの重複dispatchを拒否する: ${packet.todo_id}`);
+      }
+      dispatchedTodoIds.add(packet.todo_id);
+      const executorHandle = `scripted-${packet.todo_id}-h1`;
+      const worktreeId = `wt-${packet.todo_id}`;
+      active.set(executorHandle, {
+        packet: structuredClone(packet),
+        executorHandle,
+        worktreeId,
+        steps: structuredClone(steps),
+        cursor: 0,
+        terminalReported: false,
+        lastCheckpointDigest: null,
+      });
+      return { executor_handle: executorHandle, worktree_id: worktreeId };
+    },
+
+    /**
+     * epoch rebind（Decision 7.3）: content不変のままplan epochだけを更新する。
+     * 以後のterminal receiptは新epochを名乗る（packet_digestはdispatch時の
+     * ものを保持＝dispatch記録への帰属は不変）。
+     */
+    async rebind({ executor_handle: executorHandle, rebind } = {}) {
+      const handleState = active.get(executorHandle);
+      if (handleState === undefined) fail(`未知のhandleをrebindできない: ${String(executorHandle)}`);
+      if (!plainRecord(rebind) || rebind.schema !== 'lattice.epoch_rebind_packet.v1'
+        || rebind.todo_id !== handleState.packet.todo_id) {
+        fail(`rebind packetが不正: ${String(executorHandle)}`);
+      }
+      handleState.packet.plan_epoch = rebind.new_plan_epoch;
+      return { executor_handle: executorHandle, plan_epoch: rebind.new_plan_epoch };
+    },
+
+    async observe({ executor_handle: executorHandle } = {}) {
+      const handleState = active.get(executorHandle);
+      if (handleState === undefined) fail(`未知のhandleを観測できない: ${String(executorHandle)}`);
+      if (handleState.terminalReported) {
+        fail(`terminal報告済みhandleの再観測: ${executorHandle}`);
+      }
+      if (handleState.cursor >= handleState.steps.length) {
+        return { state: 'running' };
+      }
+      const step = handleState.steps[handleState.cursor];
+      handleState.cursor += 1;
+      if (step.kind === 'stall') {
+        return { state: 'unknown' };
+      }
+      if (step.kind === 'checkpoint') {
+        if (!plainRecord(step.checkpoint)) fail('checkpoint stepにcheckpoint payloadが必要');
+        if (typeof step.checkpoint.checkpoint_digest === 'string') {
+          handleState.lastCheckpointDigest = step.checkpoint.checkpoint_digest;
+        }
+        return { state: 'checkpoint_ready', checkpoint: structuredClone(step.checkpoint) };
+      }
+      if (step.kind === 'hold_request') {
+        if (!plainRecord(step.finding)) fail('hold_request stepにfinding payloadが必要');
+        return { state: 'hold_requested', finding: structuredClone(step.finding) };
+      }
+      handleState.terminalReported = true;
+      return { state: 'terminal', receipt: buildReceipt(handleState, step) };
+    },
+  };
+}

package/src/runtime-worktree-executor.mjs

@@ -0,0 +1,199 @@
+import { spawn } from 'node:child_process';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import { captureWorktreeDiff } from './runtime-diff-observer.mjs';
+import { selfDigest, validateExecutorPacket } from './runtime-contracts.mjs';
+
+/**
+ * RC3-F isolated worktree executor adapter（ADR 0044 Decision 9、plan RC3-F）。
+ *
+ * disposable repoのbase_shaからdetached worktreeをtmpdir配下へprovisionし、
+ * caller提供のwork関数（TODOごとのfile変更）を実行して、実diffだけを
+ * checkpoint／receiptとして報告する。canonical worktreeへは書かない。
+ *
+ * - adapter契約はscripted executorと同一（dispatch／observe）。
+ * - commit・branch切替等の禁止操作はdiff observerのHEAD drift検査でfail loud。
+ * - terminal時にworktreeをcleanupし、失敗を成功へ丸めず観測結果
+ *   （cleanup_ok・residual_paths）としてterminal observationへ載せる。
+ * - 同一TODOの重複dispatchはtyped reject（Decision 9.4）。
+ */
+
+function fail(reason) {
+  throw new TypeError(`worktree executor契約違反: ${reason}`);
+}
+
+function plainRecord(value) {
+  return value !== null
+    && typeof value === 'object'
+    && !Array.isArray(value)
+    && Object.getPrototypeOf(value) === Object.prototype;
+}
+
+function run(command, args, cwd) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { cwd, shell: false, stdio: ['ignore', 'pipe', 'pipe'] });
+    const stdout = [];
+    const stderr = [];
+    child.stdout.on('data', (chunk) => stdout.push(chunk));
+    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).toString('utf8'));
+      else {
+        reject(new TypeError(
+          `${command} ${args[0]} failed (${signal ?? code}): ${Buffer.concat(stderr).toString('utf8').trim()}`,
+        ));
+      }
+    });
+  });
+}
+
+/**
+ * disposable repoに対するworktree executor adapterを作る。
+ * work: { [todoId]: async ({ worktreePath }) => void }
+ */
+export function createWorktreeExecutorAdapter(options = {}) {
+  if (!plainRecord(options)
+    || typeof options.repoRoot !== 'string' || options.repoRoot.length === 0
+    || !plainRecord(options.work)) {
+    fail('createWorktreeExecutorAdapter optionsが不正');
+  }
+  const { repoRoot, work } = options;
+  const active = new Map();
+  const dispatchedTodoIds = new Set();
+  let handleCounter = 0;
+
+  // canonical repo（disposable repoの本体worktreeと共有refs）への書込・ref作成を
+  // 協調前提の検出guardとして観測する（Decision 9.2。malicious executorはNon-goal）。
+  async function canonicalFingerprint() {
+    const head = await run('git', ['rev-parse', 'HEAD'], repoRoot);
+    const status = await run('git', ['status', '--porcelain=v1', '--untracked-files=all', '--ignored=matching'], repoRoot);
+    const refs = await run('git', ['for-each-ref', '--format=%(refname) %(objectname)'], repoRoot);
+    return `${head.trim()}\n${status}\n${refs}`;
+  }
+
+  async function cleanupWorktree(worktreePath, worktreeRoot) {
+    try {
+      await run('git', ['worktree', 'remove', '--force', worktreePath], repoRoot);
+      await rm(worktreeRoot, { recursive: true, force: true });
+      return { cleanup_ok: true, residual_paths: [] };
+    } catch (error) {
+      return {
+        cleanup_ok: false,
+        residual_paths: [worktreeRoot],
+        recovery: `git worktree remove --force ${worktreePath} を手動再実行する`,
+        message: String(error?.message ?? error),
+      };
+    }
+  }
+
+  return {
+    kind: 'isolated-worktree',
+
+    async dispatch({ packet } = {}) {
+      if (!validateExecutorPacket(packet)) fail('dispatchにはexecutor_packet.v1が必要');
+      const workFn = work[packet.todo_id];
+      if (typeof workFn !== 'function') fail(`work関数が未定義のTODO: ${packet.todo_id}`);
+      if (dispatchedTodoIds.has(packet.todo_id)) {
+        fail(`同一TODOの重複dispatchを拒否する: ${packet.todo_id}`);
+      }
+      dispatchedTodoIds.add(packet.todo_id);
+
+      handleCounter += 1;
+      const executorHandle = `worktree-${packet.todo_id}-h${handleCounter}`;
+      const worktreeId = `wt-${packet.todo_id}-${handleCounter}`;
+      const worktreeRoot = await mkdtemp(path.join(tmpdir(), `lattice-rc3-wt-${packet.todo_id}-`));
+      const worktreePath = path.join(worktreeRoot, 'tree');
+      const fingerprintBefore = await canonicalFingerprint();
+      try {
+        await run('git', ['worktree', 'add', '--detach', worktreePath, packet.base_sha], repoRoot);
+        await workFn({ worktreePath });
+        const fingerprintAfter = await canonicalFingerprint();
+        if (fingerprintAfter !== fingerprintBefore) {
+          fail(`work関数がcanonical repoまたは共有refsを変更した: ${packet.todo_id}`);
+        }
+      } catch (error) {
+        // 失敗経路でもworktreeを孤立させない。cleanup失敗は失敗messageへ載せて
+        // fail loudし、retryできるようdispatch予約を解放する。
+        const cleanup = await cleanupWorktree(worktreePath, worktreeRoot);
+        dispatchedTodoIds.delete(packet.todo_id);
+        const residual = cleanup.cleanup_ok ? '' : `（cleanup失敗、残存path: ${cleanup.residual_paths.join(', ')}）`;
+        throw new TypeError(`dispatch失敗: ${String(error?.message ?? error)}${residual}`);
+      }
+
+      active.set(executorHandle, {
+        packet: structuredClone(packet),
+        executorHandle,
+        worktreeId,
+        worktreeRoot,
+        worktreePath,
+        checkpoint: null,
+        terminalReported: false,
+      });
+      return { executor_handle: executorHandle, worktree_id: worktreeId };
+    },
+
+    /** epoch rebind（Decision 7.3）: content不変のままplan epochだけを更新する。 */
+    async rebind({ executor_handle: executorHandle, rebind } = {}) {
+      const handleState = active.get(executorHandle);
+      if (handleState === undefined) fail(`未知のhandleをrebindできない: ${String(executorHandle)}`);
+      if (!plainRecord(rebind) || rebind.schema !== 'lattice.epoch_rebind_packet.v1'
+        || rebind.todo_id !== handleState.packet.todo_id) {
+        fail(`rebind packetが不正: ${String(executorHandle)}`);
+      }
+      handleState.packet.plan_epoch = rebind.new_plan_epoch;
+      return { executor_handle: executorHandle, plan_epoch: rebind.new_plan_epoch };
+    },
+
+    async observe({ executor_handle: executorHandle } = {}) {
+      const handleState = active.get(executorHandle);
+      if (handleState === undefined) fail(`未知のhandleを観測できない: ${String(executorHandle)}`);
+      if (handleState.terminalReported) fail(`terminal報告済みhandleの再観測: ${executorHandle}`);
+      const { packet } = handleState;
+
+      if (handleState.checkpoint === null) {
+        // 1回目: 実diffをbounded canonical recordへ変換してcheckpoint報告。
+        // 観測失敗（HEAD drift等の禁止操作検出を含む）時はworktreeを回収してから
+        // fail loudする（無証拠の恒久leakを残さない）。
+        let checkpoint;
+        try {
+          checkpoint = await captureWorktreeDiff({
+            worktreePath: handleState.worktreePath,
+            baseSha: packet.base_sha,
+          });
+        } catch (error) {
+          handleState.terminalReported = true;
+          const cleanup = await cleanupWorktree(handleState.worktreePath, handleState.worktreeRoot);
+          const residual = cleanup.cleanup_ok ? '' : `（cleanup失敗、残存path: ${cleanup.residual_paths.join(', ')}）`;
+          throw new TypeError(`${String(error?.message ?? error)}${residual}`);
+        }
+        handleState.checkpoint = checkpoint;
+        return { state: 'checkpoint_ready', checkpoint: structuredClone(checkpoint) };
+      }
+
+      // 2回目: terminal receipt＋worktree cleanup（失敗を丸めず観測へ載せる）。
+      handleState.terminalReported = true;
+      const receipt = {
+        schema: 'lattice.executor_receipt.v1',
+        receipt_id: `${packet.todo_id}-r1`,
+        executor_handle: handleState.executorHandle,
+        worktree_id: handleState.worktreeId,
+        base_sha: packet.base_sha,
+        plan_epoch: packet.plan_epoch,
+        packet_digest: packet.packet_digest,
+        todo_id: packet.todo_id,
+        checkpoint_digest: handleState.checkpoint.checkpoint_digest,
+        observed_diff: handleState.checkpoint.diff.entries.map((entry) => ({
+          path: entry.path,
+          change: entry.change,
+        })),
+      };
+      receipt.receipt_digest = selfDigest(receipt, 'receipt_digest');
+
+      const cleanup = await cleanupWorktree(handleState.worktreePath, handleState.worktreeRoot);
+      return { state: 'terminal', receipt, cleanup };
+    },
+  };
+}