@sanqianx/claude-ai-workbench 0.13.2 → 0.13.3

package/packages/server/lib/delegation-phase-store.js

@@ -1,357 +1,357 @@
-'use strict';
-
-const fs = require('fs');
-const path = require('path');
-const crypto = require('crypto');
-
-// Durable phase/claim facts for Workbench delegation commands (the mutable
-// companion of the immutable reservation ledger in delegation-store.js).
-//
-// Every fact is a write-once JSON file inside the delegation's own directory
-// <root>/phases/<delegationId>/, published with the same discipline as the
-// ledger: tmp file + fsync + fs.link (create-if-absent) + directory-entry
-// fence. Nothing here ever rewrites the reservation record; a fact that
-// already exists is either an identical idempotent replay or an explicit
-// conflict, never a silent overwrite.
-//
-//   child-created.json      the trusted factory created the reserved child
-//   child-create-failed.json creation/persistence failed; no model input
-//   claim.json              one owner claimed the dispatch attempt (the
-//                           exclusive file IS the cross-process mutex: a
-//                           second process or Service loses with EEXIST)
-//   outcome.json            the claim owner's proven outcome. A claim without
-//                           an outcome can never be proven "not sent" by an
-//                           outside observer: it reads as dispatch-unknown and
-//                           no automatic re-input may ever run.
-//
-// The store never sees or stores prompt bodies, credentials or env; fact
-// payloads carry only ids, fixed codes and timestamps.
-
-const SCHEMA = 'workbench-delegation-phase/v1';
-const VERSION = 1;
-const FACT_NAMES = Object.freeze(['child-created', 'child-create-failed', 'claim', 'outcome']);
-const OUTCOMES = new Set(['dispatched', 'dispatch-unknown']);
-const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
-const SESSION_ID_RE = /^sess-[0-9a-f]{12}$/;
-const DIR_FSYNC_UNSUPPORTED = new Set(['EPERM', 'EINVAL', 'ENOTSUP', 'EOPNOTSUPP', 'ENOSYS', 'EACCES']);
-
-function fail(code, status, message, extra) {
-  const error = new Error(message);
-  error.code = code;
-  error.status = status;
-  if (extra) Object.assign(error, extra);
-  throw error;
-}
-
-function isCleanString(value, max) {
-  if (typeof value !== 'string' || !value.length || value.length > max) return false;
-  for (let k = 0; k < value.length; k += 1) {
-    const code = value.charCodeAt(k);
-    if (code < 0x20 || code === 0x7f) return false;
-  }
-  return true;
-}
-
-function defaultDirFsync(f, dirPath) {
-  let fd;
-  try {
-    fd = f.openSync(dirPath, 'r');
-    f.fsyncSync(fd);
-    return 'supported';
-  } catch (error) {
-    if (DIR_FSYNC_UNSUPPORTED.has(error && error.code)) return 'unsupported';
-    throw error;
-  } finally {
-    if (fd !== undefined) { try { f.closeSync(fd); } catch { /* closed or unusable */ } }
-  }
-}
-
-function createDelegationPhaseStore(options = {}) {
-  const { root, storeScope } = options || {};
-  const f = options.fsx || fs;
-  const dirFsync = typeof f.dirFsync === 'function' ? f.dirFsync.bind(f) : dirPath => defaultDirFsync(f, dirPath);
-  if (typeof root !== 'string' || !root.trim() || !path.isAbsolute(root)) {
-    fail('DELEGATION_STORE_ROOT_INVALID', 400, 'root must be an absolute server-owned directory');
-  }
-  if (!UUID_RE.test(storeScope || '')) {
-    fail('DELEGATION_STORE_SCOPE_INVALID', 400, 'storeScope must be a canonical lowercase UUID v4');
-  }
-  const rootDir = path.resolve(root);
-  const phasesDir = path.join(rootDir, 'phases');
-  const tmpDir = path.join(rootDir, 'tmp');
-
-  function ensureRealDir(dirPath, what) {
-    try {
-      f.mkdirSync(dirPath, { recursive: true });
-    } catch (error) {
-      if (!(error && (error.code === 'EEXIST' || error.code === 'ENOTDIR'))) throw error;
-    }
-    const st = f.lstatSync(dirPath);
-    if (st.isSymbolicLink()) fail('DELEGATION_STORE_PATH_UNSAFE', 400, `${what} must not be a symbolic link`, { path: what });
-    if (!st.isDirectory()) fail('DELEGATION_STORE_PATH_UNSAFE', 400, `${what} must be a real directory`, { path: what });
-  }
-
-  ensureRealDir(rootDir, 'phase store root');
-  ensureRealDir(phasesDir, 'phases directory');
-  ensureRealDir(tmpDir, 'tmp directory');
-
-  let directoryFsync = 'unknown';
-  let tmpCounter = 0;
-  // Claims this store instance currently owns and has not yet settled with an
-  // outcome. Only meaningful in-process: it lets a same-instance concurrent
-  // caller see "dispatching" instead of the conservative dispatch-unknown.
-  const liveClaims = new Map();
-
-  const dirOf = delegationId => path.join(phasesDir, delegationId);
-
-  function requireDelegationId(delegationId) {
-    if (typeof delegationId !== 'string' || !UUID_RE.test(delegationId)) {
-      fail('DELEGATION_ID_INVALID', 400, 'delegationId must be a UUID issued by the ledger');
-    }
-    return delegationId;
-  }
-
-  // Write-once publish of one fact file. Returns 'written' for a fresh
-  // commit, 'present' for an identical replay. Any disagreement with the
-  // existing bytes is an explicit conflict; the file itself never changes.
-  function publishFact(delegationId, name, payload) {
-    const dir = dirOf(delegationId);
-    try {
-      f.mkdirSync(dir, { recursive: true });
-    } catch (error) {
-      fail('DELEGATION_PHASE_WRITE_FAILED', 500, 'delegation phase directory could not be created', { reason: error && error.code });
-    }
-    const st = f.lstatSync(dir);
-    if (st.isSymbolicLink() || !st.isDirectory()) {
-      fail('DELEGATION_STORE_PATH_UNSAFE', 500, 'delegation phase path must be a real directory');
-    }
-    const target = path.join(dir, `${name}.json`);
-    let existing;
-    try { existing = f.lstatSync(target); } catch (error) {
-      if (!(error && error.code === 'ENOENT')) throw error;
-      existing = null;
-    }
-    const body = Buffer.from(`${JSON.stringify(payload)}\n`, 'utf8');
-    if (existing) {
-      const known = readFact(delegationId, name);
-      if (JSON.stringify(stripAt(known)) === JSON.stringify(stripAt(payload))) return 'present';
-      fail('DELEGATION_FACT_CONFLICT', 409, `the delegation ${name} fact already exists with different content`);
-    }
-    tmpCounter += 1;
-    const tmpPath = path.join(tmpDir, `${process.pid}-${tmpCounter}-${crypto.randomUUID()}.tmp`);
-    const cleanup = () => {
-      try { f.unlinkSync(tmpPath); } catch (error) { if (error && error.code !== 'ENOENT') throw error; }
-    };
-    let fd;
-    try {
-      fd = f.openSync(tmpPath, 'wx');
-      let written = 0;
-      while (written < body.length) {
-        const progress = f.writeSync(fd, body, written, body.length - written);
-        if (!(progress > 0)) {
-          const noProgress = new Error('writeSync returned no progress');
-          noProgress.code = 'write-zero-progress';
-          throw noProgress;
-        }
-        written += progress;
-      }
-      f.fsyncSync(fd);
-    } catch (error) {
-      if (fd !== undefined) { try { f.closeSync(fd); } catch { /* reported below */ } }
-      try { cleanup(); } catch { /* reported below */ }
-      fail('DELEGATION_PHASE_WRITE_FAILED', 500, `delegation ${name} fact could not be written durably; nothing was claimed or dispatched`, { reason: error && error.code });
-    }
-    try { f.closeSync(fd); } catch { /* data already fsynced */ }
-    try {
-      f.linkSync(tmpPath, target);
-    } catch (error) {
-      try { cleanup(); } catch { /* reported below */ }
-      if (error && error.code === 'EEXIST') {
-        const known = readFact(delegationId, name);
-        if (JSON.stringify(stripAt(known)) === JSON.stringify(stripAt(payload))) return 'present';
-        fail('DELEGATION_FACT_CONFLICT', 409, `a concurrent ${name} fact exists with different content`);
-      }
-      fail('DELEGATION_PHASE_COMMIT_FAILED', 500, 'delegation phase commit is unavailable on this platform/path', { reason: error && error.code });
-    }
-    try {
-      directoryFsync = dirFsync(dir);
-    } catch (error) {
-      try { cleanup(); } catch { /* the fence failure is the honest answer */ }
-      fail('DELEGATION_DIR_FSYNC_FAILED', 500, `delegation ${name} fact commit fence (directory fsync) failed; the fact stays untouched`, { reason: error && error.code });
-    }
-    try { cleanup(); } catch (error) {
-      fail('DELEGATION_TMP_CLEANUP_FAILED', 500, 'delegation phase committed but its temp file could not be removed', { reason: error && error.code });
-    }
-    return 'written';
-  }
-
-  // stripAt removes volatile fields (at) so a replay of the same fact with a
-  // fresh timestamp still counts as the same fact.
-  function stripAt(payload) {
-    const copy = { ...payload };
-    delete copy.at;
-    return copy;
-  }
-
-  function readFact(delegationId, name) {
-    const file = path.join(dirOf(delegationId), `${name}.json`);
-    let st;
-    try { st = f.lstatSync(file); } catch (error) {
-      if (error && error.code === 'ENOENT') return null;
-      throw error;
-    }
-    if (st.isSymbolicLink() || !st.isFile()) {
-      fail('DELEGATION_PHASE_INVALID', 500, `delegation ${name} fact entry is not a regular file`, { entry: `${delegationId}/${name}.json` });
-    }
-    let parsed;
-    try {
-      parsed = JSON.parse(f.readFileSync(file, 'utf8'));
-    } catch (error) {
-      if (error instanceof SyntaxError) parsed = null;
-      else throw error;
-    }
-    if (!parsed || typeof parsed !== 'object' || parsed.schema !== SCHEMA || parsed.version !== VERSION || parsed.delegationId !== delegationId) {
-      fail('DELEGATION_PHASE_CORRUPT', 500, `stored delegation ${name} fact is invalid`, { entry: `${delegationId}/${name}.json` });
-    }
-    return parsed;
-  }
-
-  // Read the delegation's phase directory; unexpected entries are tampering
-  // and fail loudly instead of yielding a silent partial state. Returns the
-  // bare fact names (without the .json suffix every fact file must carry).
-  function factNames(delegationId) {
-    let entries;
-    try {
-      entries = f.readdirSync(dirOf(delegationId)).sort();
-    } catch (error) {
-      if (error && error.code === 'ENOENT') return [];
-      throw error;
-    }
-    const names = [];
-    for (const entry of entries) {
-      const base = entry.endsWith('.json') ? entry.slice(0, -'.json'.length) : null;
-      if (!base || !FACT_NAMES.includes(base)) {
-        fail('DELEGATION_PHASE_DIR_INVALID', 500, 'delegation phase directory contains an unexpected entry', { entry });
-      }
-      names.push(base);
-    }
-    return names;
-  }
-
-  function recordChildCreated(input = {}) {
-    const delegationId = requireDelegationId(input.delegationId);
-    if (!SESSION_ID_RE.test(input.childSessionId || '')) {
-      fail('DELEGATION_CHILD_INVALID', 400, 'childSessionId must be the ledger-reserved session id');
-    }
-    if (!isCleanString(input.workspaceRef, 128)) {
-      fail('DELEGATION_WORKSPACE_INVALID', 400, 'workspaceRef must be a non-empty string');
-    }
-    publishFact(delegationId, 'child-created', {
-      schema: SCHEMA, version: VERSION, delegationId,
-      childSessionId: input.childSessionId, workspaceRef: input.workspaceRef,
-      at: new Date().toISOString(),
-    });
-    return true;
-  }
-
-  function recordChildCreateFailed(input = {}) {
-    const delegationId = requireDelegationId(input.delegationId);
-    if (!isCleanString(input.code, 128)) {
-      fail('DELEGATION_PHASE_INVALID', 400, 'code must be a non-empty string');
-    }
-    publishFact(delegationId, 'child-create-failed', {
-      schema: SCHEMA, version: VERSION, delegationId, code: input.code,
-      at: new Date().toISOString(),
-    });
-    return true;
-  }
-
-  // The dispatch claim. Exactly one caller across processes wins the
-  // exclusive create; every loser gets the existing claim back and MUST NOT
-  // send any model input.
-  function claimDispatch(input = {}) {
-    const delegationId = requireDelegationId(input.delegationId);
-    if (!UUID_RE.test(input.attemptId || '')) {
-      fail('DELEGATION_PHASE_INVALID', 400, 'attemptId must be a UUID');
-    }
-    if (!Number.isInteger(input.ownerPid) || input.ownerPid <= 0) {
-      fail('DELEGATION_PHASE_INVALID', 400, 'ownerPid must be a positive integer');
-    }
-    if (!UUID_RE.test(input.ownerEpoch || '')) {
-      fail('DELEGATION_PHASE_INVALID', 400, 'ownerEpoch must be a UUID');
-    }
-    const result = publishFact(delegationId, 'claim', {
-      schema: SCHEMA, version: VERSION, delegationId,
-      attemptId: input.attemptId, ownerPid: input.ownerPid, ownerEpoch: input.ownerEpoch,
-      at: new Date().toISOString(),
-    });
-    if (result === 'written') {
-      liveClaims.set(delegationId, input.attemptId);
-      return { claimed: true, claim: readFact(delegationId, 'claim') };
-    }
-    const claim = readFact(delegationId, 'claim');
-    return { claimed: false, claim };
-  }
-
-  function recordOutcome(input = {}) {
-    const delegationId = requireDelegationId(input.delegationId);
-    if (!UUID_RE.test(input.attemptId || '')) {
-      fail('DELEGATION_PHASE_INVALID', 400, 'attemptId must be a UUID');
-    }
-    if (!OUTCOMES.has(input.outcome)) {
-      fail('DELEGATION_PHASE_INVALID', 400, 'outcome must be dispatched or dispatch-unknown');
-    }
-    publishFact(delegationId, 'outcome', {
-      schema: SCHEMA, version: VERSION, delegationId,
-      attemptId: input.attemptId, outcome: input.outcome,
-      at: new Date().toISOString(),
-    });
-    liveClaims.delete(delegationId);
-    return true;
-  }
-
-  // A failed outcome publish can leave the durable claim unsettled even in a
-  // Service that is still alive. The owner must drop its in-process liveness
-  // marker so reads report the conservative dispatch-unknown verdict instead
-  // of an optimistic "dispatching" state. This changes no durable fact.
-  function abandonLiveClaim(input = {}) {
-    const delegationId = requireDelegationId(input.delegationId);
-    if (!UUID_RE.test(input.attemptId || '')) {
-      fail('DELEGATION_PHASE_INVALID', 400, 'attemptId must be a UUID');
-    }
-    if (liveClaims.get(delegationId) === input.attemptId) liveClaims.delete(delegationId);
-    return true;
-  }
-
-  function stateOf(delegationId) {
-    requireDelegationId(delegationId);
-    const names = factNames(delegationId);
-    const state = { childCreated: null, childCreateFailed: null, claim: null, outcome: null };
-    for (const name of names) {
-      if (name === 'child-created') state.childCreated = readFact(delegationId, name);
-      else if (name === 'child-create-failed') state.childCreateFailed = readFact(delegationId, name);
-      else if (name === 'claim') state.claim = readFact(delegationId, name);
-      else if (name === 'outcome') state.outcome = readFact(delegationId, name);
-    }
-    return state;
-  }
-
-  function isClaimLive(delegationId) {
-    return liveClaims.has(delegationId);
-  }
-
-  return {
-    recordChildCreated,
-    recordChildCreateFailed,
-    claimDispatch,
-    recordOutcome,
-    abandonLiveClaim,
-    stateOf,
-    isClaimLive,
-    describe() {
-      return { schema: SCHEMA, version: VERSION, root: rootDir, storeScope, directoryFsync };
-    },
-  };
-}
-
-module.exports = { createDelegationPhaseStore };
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+// Durable phase/claim facts for Workbench delegation commands (the mutable
+// companion of the immutable reservation ledger in delegation-store.js).
+//
+// Every fact is a write-once JSON file inside the delegation's own directory
+// <root>/phases/<delegationId>/, published with the same discipline as the
+// ledger: tmp file + fsync + fs.link (create-if-absent) + directory-entry
+// fence. Nothing here ever rewrites the reservation record; a fact that
+// already exists is either an identical idempotent replay or an explicit
+// conflict, never a silent overwrite.
+//
+//   child-created.json      the trusted factory created the reserved child
+//   child-create-failed.json creation/persistence failed; no model input
+//   claim.json              one owner claimed the dispatch attempt (the
+//                           exclusive file IS the cross-process mutex: a
+//                           second process or Service loses with EEXIST)
+//   outcome.json            the claim owner's proven outcome. A claim without
+//                           an outcome can never be proven "not sent" by an
+//                           outside observer: it reads as dispatch-unknown and
+//                           no automatic re-input may ever run.
+//
+// The store never sees or stores prompt bodies, credentials or env; fact
+// payloads carry only ids, fixed codes and timestamps.
+
+const SCHEMA = 'workbench-delegation-phase/v1';
+const VERSION = 1;
+const FACT_NAMES = Object.freeze(['child-created', 'child-create-failed', 'claim', 'outcome']);
+const OUTCOMES = new Set(['dispatched', 'dispatch-unknown']);
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const SESSION_ID_RE = /^sess-[0-9a-f]{12}$/;
+const DIR_FSYNC_UNSUPPORTED = new Set(['EPERM', 'EINVAL', 'ENOTSUP', 'EOPNOTSUPP', 'ENOSYS', 'EACCES']);
+
+function fail(code, status, message, extra) {
+  const error = new Error(message);
+  error.code = code;
+  error.status = status;
+  if (extra) Object.assign(error, extra);
+  throw error;
+}
+
+function isCleanString(value, max) {
+  if (typeof value !== 'string' || !value.length || value.length > max) return false;
+  for (let k = 0; k < value.length; k += 1) {
+    const code = value.charCodeAt(k);
+    if (code < 0x20 || code === 0x7f) return false;
+  }
+  return true;
+}
+
+function defaultDirFsync(f, dirPath) {
+  let fd;
+  try {
+    fd = f.openSync(dirPath, 'r');
+    f.fsyncSync(fd);
+    return 'supported';
+  } catch (error) {
+    if (DIR_FSYNC_UNSUPPORTED.has(error && error.code)) return 'unsupported';
+    throw error;
+  } finally {
+    if (fd !== undefined) { try { f.closeSync(fd); } catch { /* closed or unusable */ } }
+  }
+}
+
+function createDelegationPhaseStore(options = {}) {
+  const { root, storeScope } = options || {};
+  const f = options.fsx || fs;
+  const dirFsync = typeof f.dirFsync === 'function' ? f.dirFsync.bind(f) : dirPath => defaultDirFsync(f, dirPath);
+  if (typeof root !== 'string' || !root.trim() || !path.isAbsolute(root)) {
+    fail('DELEGATION_STORE_ROOT_INVALID', 400, 'root must be an absolute server-owned directory');
+  }
+  if (!UUID_RE.test(storeScope || '')) {
+    fail('DELEGATION_STORE_SCOPE_INVALID', 400, 'storeScope must be a canonical lowercase UUID v4');
+  }
+  const rootDir = path.resolve(root);
+  const phasesDir = path.join(rootDir, 'phases');
+  const tmpDir = path.join(rootDir, 'tmp');
+
+  function ensureRealDir(dirPath, what) {
+    try {
+      f.mkdirSync(dirPath, { recursive: true });
+    } catch (error) {
+      if (!(error && (error.code === 'EEXIST' || error.code === 'ENOTDIR'))) throw error;
+    }
+    const st = f.lstatSync(dirPath);
+    if (st.isSymbolicLink()) fail('DELEGATION_STORE_PATH_UNSAFE', 400, `${what} must not be a symbolic link`, { path: what });
+    if (!st.isDirectory()) fail('DELEGATION_STORE_PATH_UNSAFE', 400, `${what} must be a real directory`, { path: what });
+  }
+
+  ensureRealDir(rootDir, 'phase store root');
+  ensureRealDir(phasesDir, 'phases directory');
+  ensureRealDir(tmpDir, 'tmp directory');
+
+  let directoryFsync = 'unknown';
+  let tmpCounter = 0;
+  // Claims this store instance currently owns and has not yet settled with an
+  // outcome. Only meaningful in-process: it lets a same-instance concurrent
+  // caller see "dispatching" instead of the conservative dispatch-unknown.
+  const liveClaims = new Map();
+
+  const dirOf = delegationId => path.join(phasesDir, delegationId);
+
+  function requireDelegationId(delegationId) {
+    if (typeof delegationId !== 'string' || !UUID_RE.test(delegationId)) {
+      fail('DELEGATION_ID_INVALID', 400, 'delegationId must be a UUID issued by the ledger');
+    }
+    return delegationId;
+  }
+
+  // Write-once publish of one fact file. Returns 'written' for a fresh
+  // commit, 'present' for an identical replay. Any disagreement with the
+  // existing bytes is an explicit conflict; the file itself never changes.
+  function publishFact(delegationId, name, payload) {
+    const dir = dirOf(delegationId);
+    try {
+      f.mkdirSync(dir, { recursive: true });
+    } catch (error) {
+      fail('DELEGATION_PHASE_WRITE_FAILED', 500, 'delegation phase directory could not be created', { reason: error && error.code });
+    }
+    const st = f.lstatSync(dir);
+    if (st.isSymbolicLink() || !st.isDirectory()) {
+      fail('DELEGATION_STORE_PATH_UNSAFE', 500, 'delegation phase path must be a real directory');
+    }
+    const target = path.join(dir, `${name}.json`);
+    let existing;
+    try { existing = f.lstatSync(target); } catch (error) {
+      if (!(error && error.code === 'ENOENT')) throw error;
+      existing = null;
+    }
+    const body = Buffer.from(`${JSON.stringify(payload)}\n`, 'utf8');
+    if (existing) {
+      const known = readFact(delegationId, name);
+      if (JSON.stringify(stripAt(known)) === JSON.stringify(stripAt(payload))) return 'present';
+      fail('DELEGATION_FACT_CONFLICT', 409, `the delegation ${name} fact already exists with different content`);
+    }
+    tmpCounter += 1;
+    const tmpPath = path.join(tmpDir, `${process.pid}-${tmpCounter}-${crypto.randomUUID()}.tmp`);
+    const cleanup = () => {
+      try { f.unlinkSync(tmpPath); } catch (error) { if (error && error.code !== 'ENOENT') throw error; }
+    };
+    let fd;
+    try {
+      fd = f.openSync(tmpPath, 'wx');
+      let written = 0;
+      while (written < body.length) {
+        const progress = f.writeSync(fd, body, written, body.length - written);
+        if (!(progress > 0)) {
+          const noProgress = new Error('writeSync returned no progress');
+          noProgress.code = 'write-zero-progress';
+          throw noProgress;
+        }
+        written += progress;
+      }
+      f.fsyncSync(fd);
+    } catch (error) {
+      if (fd !== undefined) { try { f.closeSync(fd); } catch { /* reported below */ } }
+      try { cleanup(); } catch { /* reported below */ }
+      fail('DELEGATION_PHASE_WRITE_FAILED', 500, `delegation ${name} fact could not be written durably; nothing was claimed or dispatched`, { reason: error && error.code });
+    }
+    try { f.closeSync(fd); } catch { /* data already fsynced */ }
+    try {
+      f.linkSync(tmpPath, target);
+    } catch (error) {
+      try { cleanup(); } catch { /* reported below */ }
+      if (error && error.code === 'EEXIST') {
+        const known = readFact(delegationId, name);
+        if (JSON.stringify(stripAt(known)) === JSON.stringify(stripAt(payload))) return 'present';
+        fail('DELEGATION_FACT_CONFLICT', 409, `a concurrent ${name} fact exists with different content`);
+      }
+      fail('DELEGATION_PHASE_COMMIT_FAILED', 500, 'delegation phase commit is unavailable on this platform/path', { reason: error && error.code });
+    }
+    try {
+      directoryFsync = dirFsync(dir);
+    } catch (error) {
+      try { cleanup(); } catch { /* the fence failure is the honest answer */ }
+      fail('DELEGATION_DIR_FSYNC_FAILED', 500, `delegation ${name} fact commit fence (directory fsync) failed; the fact stays untouched`, { reason: error && error.code });
+    }
+    try { cleanup(); } catch (error) {
+      fail('DELEGATION_TMP_CLEANUP_FAILED', 500, 'delegation phase committed but its temp file could not be removed', { reason: error && error.code });
+    }
+    return 'written';
+  }
+
+  // stripAt removes volatile fields (at) so a replay of the same fact with a
+  // fresh timestamp still counts as the same fact.
+  function stripAt(payload) {
+    const copy = { ...payload };
+    delete copy.at;
+    return copy;
+  }
+
+  function readFact(delegationId, name) {
+    const file = path.join(dirOf(delegationId), `${name}.json`);
+    let st;
+    try { st = f.lstatSync(file); } catch (error) {
+      if (error && error.code === 'ENOENT') return null;
+      throw error;
+    }
+    if (st.isSymbolicLink() || !st.isFile()) {
+      fail('DELEGATION_PHASE_INVALID', 500, `delegation ${name} fact entry is not a regular file`, { entry: `${delegationId}/${name}.json` });
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(f.readFileSync(file, 'utf8'));
+    } catch (error) {
+      if (error instanceof SyntaxError) parsed = null;
+      else throw error;
+    }
+    if (!parsed || typeof parsed !== 'object' || parsed.schema !== SCHEMA || parsed.version !== VERSION || parsed.delegationId !== delegationId) {
+      fail('DELEGATION_PHASE_CORRUPT', 500, `stored delegation ${name} fact is invalid`, { entry: `${delegationId}/${name}.json` });
+    }
+    return parsed;
+  }
+
+  // Read the delegation's phase directory; unexpected entries are tampering
+  // and fail loudly instead of yielding a silent partial state. Returns the
+  // bare fact names (without the .json suffix every fact file must carry).
+  function factNames(delegationId) {
+    let entries;
+    try {
+      entries = f.readdirSync(dirOf(delegationId)).sort();
+    } catch (error) {
+      if (error && error.code === 'ENOENT') return [];
+      throw error;
+    }
+    const names = [];
+    for (const entry of entries) {
+      const base = entry.endsWith('.json') ? entry.slice(0, -'.json'.length) : null;
+      if (!base || !FACT_NAMES.includes(base)) {
+        fail('DELEGATION_PHASE_DIR_INVALID', 500, 'delegation phase directory contains an unexpected entry', { entry });
+      }
+      names.push(base);
+    }
+    return names;
+  }
+
+  function recordChildCreated(input = {}) {
+    const delegationId = requireDelegationId(input.delegationId);
+    if (!SESSION_ID_RE.test(input.childSessionId || '')) {
+      fail('DELEGATION_CHILD_INVALID', 400, 'childSessionId must be the ledger-reserved session id');
+    }
+    if (!isCleanString(input.workspaceRef, 128)) {
+      fail('DELEGATION_WORKSPACE_INVALID', 400, 'workspaceRef must be a non-empty string');
+    }
+    publishFact(delegationId, 'child-created', {
+      schema: SCHEMA, version: VERSION, delegationId,
+      childSessionId: input.childSessionId, workspaceRef: input.workspaceRef,
+      at: new Date().toISOString(),
+    });
+    return true;
+  }
+
+  function recordChildCreateFailed(input = {}) {
+    const delegationId = requireDelegationId(input.delegationId);
+    if (!isCleanString(input.code, 128)) {
+      fail('DELEGATION_PHASE_INVALID', 400, 'code must be a non-empty string');
+    }
+    publishFact(delegationId, 'child-create-failed', {
+      schema: SCHEMA, version: VERSION, delegationId, code: input.code,
+      at: new Date().toISOString(),
+    });
+    return true;
+  }
+
+  // The dispatch claim. Exactly one caller across processes wins the
+  // exclusive create; every loser gets the existing claim back and MUST NOT
+  // send any model input.
+  function claimDispatch(input = {}) {
+    const delegationId = requireDelegationId(input.delegationId);
+    if (!UUID_RE.test(input.attemptId || '')) {
+      fail('DELEGATION_PHASE_INVALID', 400, 'attemptId must be a UUID');
+    }
+    if (!Number.isInteger(input.ownerPid) || input.ownerPid <= 0) {
+      fail('DELEGATION_PHASE_INVALID', 400, 'ownerPid must be a positive integer');
+    }
+    if (!UUID_RE.test(input.ownerEpoch || '')) {
+      fail('DELEGATION_PHASE_INVALID', 400, 'ownerEpoch must be a UUID');
+    }
+    const result = publishFact(delegationId, 'claim', {
+      schema: SCHEMA, version: VERSION, delegationId,
+      attemptId: input.attemptId, ownerPid: input.ownerPid, ownerEpoch: input.ownerEpoch,
+      at: new Date().toISOString(),
+    });
+    if (result === 'written') {
+      liveClaims.set(delegationId, input.attemptId);
+      return { claimed: true, claim: readFact(delegationId, 'claim') };
+    }
+    const claim = readFact(delegationId, 'claim');
+    return { claimed: false, claim };
+  }
+
+  function recordOutcome(input = {}) {
+    const delegationId = requireDelegationId(input.delegationId);
+    if (!UUID_RE.test(input.attemptId || '')) {
+      fail('DELEGATION_PHASE_INVALID', 400, 'attemptId must be a UUID');
+    }
+    if (!OUTCOMES.has(input.outcome)) {
+      fail('DELEGATION_PHASE_INVALID', 400, 'outcome must be dispatched or dispatch-unknown');
+    }
+    publishFact(delegationId, 'outcome', {
+      schema: SCHEMA, version: VERSION, delegationId,
+      attemptId: input.attemptId, outcome: input.outcome,
+      at: new Date().toISOString(),
+    });
+    liveClaims.delete(delegationId);
+    return true;
+  }
+
+  // A failed outcome publish can leave the durable claim unsettled even in a
+  // Service that is still alive. The owner must drop its in-process liveness
+  // marker so reads report the conservative dispatch-unknown verdict instead
+  // of an optimistic "dispatching" state. This changes no durable fact.
+  function abandonLiveClaim(input = {}) {
+    const delegationId = requireDelegationId(input.delegationId);
+    if (!UUID_RE.test(input.attemptId || '')) {
+      fail('DELEGATION_PHASE_INVALID', 400, 'attemptId must be a UUID');
+    }
+    if (liveClaims.get(delegationId) === input.attemptId) liveClaims.delete(delegationId);
+    return true;
+  }
+
+  function stateOf(delegationId) {
+    requireDelegationId(delegationId);
+    const names = factNames(delegationId);
+    const state = { childCreated: null, childCreateFailed: null, claim: null, outcome: null };
+    for (const name of names) {
+      if (name === 'child-created') state.childCreated = readFact(delegationId, name);
+      else if (name === 'child-create-failed') state.childCreateFailed = readFact(delegationId, name);
+      else if (name === 'claim') state.claim = readFact(delegationId, name);
+      else if (name === 'outcome') state.outcome = readFact(delegationId, name);
+    }
+    return state;
+  }
+
+  function isClaimLive(delegationId) {
+    return liveClaims.has(delegationId);
+  }
+
+  return {
+    recordChildCreated,
+    recordChildCreateFailed,
+    claimDispatch,
+    recordOutcome,
+    abandonLiveClaim,
+    stateOf,
+    isClaimLive,
+    describe() {
+      return { schema: SCHEMA, version: VERSION, root: rootDir, storeScope, directoryFsync };
+    },
+  };
+}
+
+module.exports = { createDelegationPhaseStore };