@sabaiway/agent-workflow-kit 12.4.0 → 13.1.0

package/tools/dispatch-baseline.mjs

@@ -0,0 +1,172 @@
+// dispatch-baseline.mjs — snapshotScope, computeBasePayload, computeBaseFingerprint,
+// isCleanAgainstBase, runBaseDiff and resolveTreeObject; spec:dispatch-baseline.
+// Writes only its own temporary indexes and the blob objects stored by forced adds.
+// Head measurements delegate unchanged to core-evidence without a temporary index.
+// runBaseDiff returns null for head; callers must use their existing head diff path.
+
+import { mkdtempSync, rmSync, lstatSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname, basename, relative } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { computeFingerprintPayload, isTreeClean, isNeverCommittableStat } from './core-evidence.mjs';
+import { KIT_OWN_PATHS, KNOWN_FOOTPRINT, patternToProbe, isDirPattern, expandGlob, isGlobPattern } from './known-footprint.mjs';
+import { GIT_MAX_BUFFER, resolveGitLocation, withGitPath } from './git-env.mjs';
+
+const TEMP_PREFIX = 'aw-dispatch-baseline-';
+const INDEX_NAME = 'index';
+const HASH_ALGORITHM = 'sha256';
+const PAYLOAD_DIFF_ARGS = ['--no-ext-diff', '--no-textconv', '--ignore-submodules=none'];
+const SCOPE_EXCLUSIONS = ['/docs/plans/', '/.claude/settings.json', '/.claude/settings.local.json', '/.mcp.json'];
+const MISSING_PATH_CODES = ['ENOENT', 'ENOTDIR'];
+const ABSENT_HEAD_STATUS = 1;
+const splitPaths = (bytes) => {
+  const text = bytes.toString('utf8');
+  if (!Buffer.from(text).equals(bytes)) throw new Error('git path names are not lossless UTF-8');
+  return text.split('\0').filter(Boolean).map((path) => path.replace(/\/$/, ''));
+};
+const defaultRunGit = (args, cwd, input, env) => spawnSync('git', args, {
+  cwd, input, env: withGitPath(env), maxBuffer: GIT_MAX_BUFFER, windowsHide: true,
+});
+const makeRunner = ({ runGit = defaultRunGit, env = process.env } = {}) => (args, cwd, input, override = env) => {
+  try { return runGit(args, cwd, input, override); }
+  catch (error) { return { error, status: null, stdout: Buffer.alloc(0) }; }
+};
+const readGit = (run, args, top, env) => {
+  const result = run(args, top, undefined, env);
+  if (result == null || result.error || result.signal || result.status !== 0 || result.stdout == null) {
+    throw new Error(`git ${args.join(' ')} failed: ${result?.error?.message ?? String(result?.stderr ?? '').trim()}`);
+  }
+  return Buffer.from(result.stdout);
+};
+const locateTop = (cwd, run, env) => {
+  const location = resolveGitLocation(cwd, { env, spawn: (command, args, options) => run(args, options.cwd, undefined, options.env) });
+  if (location.state !== 'work-tree') throw new Error(location.cause ?? 'not inside a git work tree');
+  return location.top;
+};
+const withTemporaryIndex = (env, action) => {
+  const directory = mkdtempSync(join(tmpdir(), TEMP_PREFIX));
+  try {
+    return action({ ...env, GIT_INDEX_FILE: join(directory, INDEX_NAME), GIT_LITERAL_PATHSPECS: '1' });
+  } finally {
+    rmSync(directory, { recursive: true, force: true });
+  }
+};
+const readStat = (path, lstat) => {
+  try {
+    const stat = lstat(path);
+    if (stat == null) throw new Error(`cannot stat ${path}`);
+    return stat;
+  } catch (error) {
+    if (MISSING_PATH_CODES.includes(error.code)) return null;
+    throw error;
+  }
+};
+const readTreePaths = (run, top, treeOid, env) => splitPaths(readGit(run, ['ls-tree', '-r', '--name-only', '-z', treeOid], top, env));
+const readHeadPaths = (run, top, env) => {
+  const head = run(['rev-parse', '--verify', '--quiet', 'HEAD'], top, undefined, env);
+  if (head && !head.error && !head.signal && head.status === ABSENT_HEAD_STATUS) return [];
+  if (!head || head.error || head.signal || head.status !== 0) throw new Error('cannot resolve HEAD');
+  return readTreePaths(run, top, 'HEAD', env);
+};
+const excludePatterns = (top, paths) => [
+  ...SCOPE_EXCLUSIONS,
+  ...KNOWN_FOOTPRINT.flatMap(({ pattern }) => isGlobPattern(pattern)
+    ? expandGlob(pattern, {
+      dir: top,
+      readdir: (parent) => paths.filter((path) => dirname(path) === relative(top, parent).split('\\').join('/')).map((path) => basename(path)),
+      stat: () => ({ isFile: () => true }),
+    })
+    : [pattern]),
+];
+const collectScope = (top, baseTreeOid, run, lstat, env) => withTemporaryIndex(env, (indexEnv) => {
+  readGit(run, ['read-tree', '--empty'], top, indexEnv);
+  const paths = new Set(splitPaths(readGit(run, ['ls-files', '--others', '--exclude-standard', '-z'], top, indexEnv)));
+  for (const pattern of KIT_OWN_PATHS) {
+    const probe = patternToProbe(pattern);
+    const stat = readStat(join(top, probe), lstat);
+    if (stat === null) continue;
+    if (isDirPattern(pattern) && stat.isDirectory()) {
+      for (const path of splitPaths(readGit(run, ['ls-files', '--others', '-z', '--', probe], top, indexEnv))) paths.add(path);
+    } else paths.add(probe.replace(/\/$/, ''));
+  }
+  for (const path of readHeadPaths(run, top, indexEnv)) paths.add(path);
+  if (baseTreeOid !== null) for (const path of readTreePaths(run, top, baseTreeOid, indexEnv)) paths.add(path);
+  const exclusions = excludePatterns(top, [...paths]).map((pattern) => ({ probe: patternToProbe(pattern), directory: isDirPattern(pattern) }));
+  return [...paths].filter((path) => !path.split('/').includes('node_modules')
+    && !exclusions.some(({ probe, directory }) => directory ? path === probe.slice(0, -1) || path.startsWith(probe) : path === probe)).sort();
+});
+
+export const snapshotScope = (cwd, { baseTreeOid = null } = {}, io = {}) => {
+  try {
+    const env = io.env ?? process.env;
+    const run = makeRunner(io);
+    const top = locateTop(cwd, run, env);
+    return { ok: true, paths: collectScope(top, baseTreeOid, run, io.lstat ?? lstatSync, env) };
+  } catch (error) {
+    return { ok: false, reason: `snapshot scope: ${error.message}` };
+  }
+};
+
+export const resolveTreeObject = (cwd, oid, io = {}) => {
+  try {
+    const env = io.env ?? process.env;
+    const run = makeRunner(io);
+    const top = locateTop(cwd, run, env);
+    const type = readGit(run, ['cat-file', '-t', oid], top, env).toString('utf8').trim();
+    return type === 'tree' ? { ok: true } : { ok: false, reason: `${oid} names a ${type}, not a tree` };
+  } catch (error) {
+    return { ok: false, reason: `${oid} is an unresolvable tree object: ${error.message}` };
+  }
+};
+
+export const runBaseDiff = (cwd, base, args, io = {}) => {
+  if (base.kind !== 'checkpoint') return null;
+  try {
+    const env = io.env ?? process.env;
+    const run = makeRunner(io);
+    const top = locateTop(cwd, run, env);
+    if (!resolveTreeObject(top, base.treeOid, io).ok) return null;
+    const scope = snapshotScope(top, { baseTreeOid: base.treeOid }, io);
+    if (!scope.ok) return null;
+    const basePaths = readTreePaths(run, top, base.treeOid, env);
+    const present = [];
+    const removed = [];
+    for (const path of scope.paths) {
+      const stat = readStat(join(top, path), io.lstat ?? lstatSync);
+      const baseHoldsPath = basePaths.includes(path);
+      const neverCommittable = stat !== null && isNeverCommittableStat(stat);
+      const materialized = stat !== null && !neverCommittable && (stat.isFile() || stat.isSymbolicLink());
+      if (neverCommittable && baseHoldsPath) throw new Error(`base path ${path} is no longer committable`);
+      if (materialized) present.push(path);
+      if (!materialized && !neverCommittable && (stat === null || baseHoldsPath)) removed.push(path);
+    }
+    const excludedBasePaths = basePaths.filter((path) => !scope.paths.includes(path));
+    const conflict = present.find((path) => excludedBasePaths.some((excluded) =>
+      path.startsWith(`${excluded}/`) || excluded.startsWith(`${path}/`)));
+    if (conflict !== undefined) throw new Error(`live path ${conflict} conflicts with an excluded base path`);
+    return withTemporaryIndex(env, (indexEnv) => {
+      readGit(run, ['read-tree', base.treeOid], top, indexEnv);
+      if (removed.length > 0) readGit(run, ['update-index', '--remove', '--', ...removed], top, indexEnv);
+      if (present.length > 0) readGit(run, ['add', '-f', '--', ...present], top, indexEnv);
+      return readGit(run, ['diff', '--cached', base.treeOid, ...args], top, indexEnv);
+    });
+  } catch {
+    return null;
+  }
+};
+
+export const computeBasePayload = (cwd, base, io = {}) => base.kind === 'head'
+  ? computeFingerprintPayload(cwd, io)
+  : runBaseDiff(cwd, base, PAYLOAD_DIFF_ARGS, io);
+
+export const computeBaseFingerprint = (cwd, base, io) => {
+  const payload = computeBasePayload(cwd, base, io);
+  return payload === null ? null : createHash(HASH_ALGORITHM).update(payload).digest('hex');
+};
+
+export const isCleanAgainstBase = (cwd, base, io) => {
+  if (base.kind === 'head') return isTreeClean(cwd, io);
+  const payload = computeBasePayload(cwd, base, io);
+  return payload === null ? null : payload.length === 0;
+};

package/tools/dispatch-record.mjs

@@ -131,13 +131,21 @@ const short = (v) => {
 // ── the closed vocabulary ─────────────────────────────────────────────────────────────────────────
 
 export const DELEGATION_SCHEMA_VERSION = 1;
+export const BASELINE_KINDS = deepFreeze(['head', 'checkpoint']);
+export const HEAD_BASELINE = deepFreeze({ kind: 'head', treeOid: null });
+export const OPTIONAL_FIELDS = deepFreeze({ dispatch: ['baseline'] });
+const TREE_OID_RE = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+export const isTreeOid = (v) => typeof v === 'string' && TREE_OID_RE.test(v);
+export const readsBaseline = (dispatch) => Object.hasOwn(dispatch, 'baseline')
+  ? { kind: dispatch.baseline.kind, treeOid: dispatch.baseline.treeOid }
+  : { ...HEAD_BASELINE };
 
 export const DELEGATION_KINDS = deepFreeze(['pre-registration', 'dispatch', 'return', 'fold', 'observation', 'degrade']);
 
 // The closed key set per kind (schema + kind are implicit on every record).
 export const DELEGATION_KEY_SETS = deepFreeze({
   'pre-registration': ['waveId', 'stepClasses', 'pairingKey', 'minPerClass', 'meanLThreshold', 'firstPassNum', 'firstPassDen', 'timestamp'],
-  dispatch: ['waveId', 'nonce', 'stepClass', 'vehicle', 'backend', 'contractDigest', 'preTreeDigest', 'baselineClean', 'deadlineS', 'retryOf', 'retryIndex', 'retryCap', 'rationale', 'timestamp'],
+  dispatch: ['waveId', 'nonce', 'stepClass', 'vehicle', 'backend', 'contractDigest', 'preTreeDigest', 'baselineClean', 'deadlineS', 'retryOf', 'retryIndex', 'retryCap', 'rationale', 'timestamp', 'baseline'],
   return: ['role', 'backend', 'nonce', 'contractDigest', 'preTreeDigest', 'postTreeDigest', 'diffDigest', 'diffLength', 'reportDigest', 'reportLength', 'bundleDigest', 'bundleLength', 'metric', 'outcome', 'exitStatus', 'sessionId', 'wrapperVersion', 'posture', 'timestamp'],
   fold: ['nonce', 'returnDigest', 'treeDigestAtFold', 'verdict', 'timestamp'],
   observation: ['waveId', 'stepClass', 'scope', 'metric', 'planId', 'phase', 'timestamp'],
@@ -217,6 +225,7 @@ const namesAnObject = (kind) => kind !== 'gate-output';
 // ── nested closed forms ───────────────────────────────────────────────────────────────────────────
 
 const VEHICLE_KEYS = ['requested', 'selected'];
+const BASELINE_KEYS = ['kind', 'treeOid'];
 const POSTURE_KEYS = ['model', 'effort', 'tier'];
 const METRIC_KEYS = ['numeratorBytes', 'denominatorBytes', 'components', 'provenance', 'eligible', 'ineligibleReason'];
 const COMPONENT_KEYS = ['kind', 'path', 'objectId', 'bytes'];
@@ -235,6 +244,18 @@ const checkClosedKeys = (at, value, keys) => {
   return { ok: true };
 };
 
+const validateBaseline = (at, baseline) => {
+  const closed = checkClosedKeys(at, baseline, BASELINE_KEYS);
+  if (!closed.ok) return closed;
+  if (!BASELINE_KINDS.includes(baseline.kind)) return refuse(`${at}: unknown kind ${short(baseline.kind)} — expected ${BASELINE_KINDS.join(' | ')}`);
+  if (baseline.treeOid !== null && (typeof baseline.treeOid !== 'string' || !TREE_OID_RE.test(baseline.treeOid))) {
+    return refuse(`${at}: treeOid must be null or exactly 40 or 64 lowercase hex characters (got ${short(baseline.treeOid)})`);
+  }
+  if (baseline.kind === 'head' && baseline.treeOid !== null) return refuse(`${at}: head requires treeOid null`);
+  if (baseline.kind === 'checkpoint' && baseline.treeOid === null) return refuse(`${at}: checkpoint requires treeOid to be non-null`);
+  return { ok: true };
+};
+
 const validateVehicle = (at, vehicle) => {
   const closed = checkClosedKeys(at, vehicle, VEHICLE_KEYS);
   if (!closed.ok) return closed;
@@ -324,6 +345,7 @@ const FIELD_CHECKS = {
   firstPassNum: { ok: isByteCount, want: 'a non-negative integer first-pass numerator' },
   firstPassDen: { ok: (v) => Number.isSafeInteger(v) && v >= 1, want: 'a positive integer first-pass denominator' },
   vehicle: { ok: isPlainObject, want: 'the closed vehicle pair {requested, selected}' },
+  baseline: { ok: isPlainObject, want: 'the closed baseline pair {kind, treeOid}' },
   // The safe token grammar, not merely non-empty: the backend NAMES an artifact beside the store
   // (the exec receipt and its report), so a name outside this grammar records a dispatch whose own
   // receipt could never be written. One grammar on both sides, or the ledger accepts what the
@@ -375,6 +397,7 @@ const checkFields = (kind, record) => {
     return refuse(`${kind}: unknown field "${stray}" — the key set is closed (the canonical digest is identity; a stray key would fork it)`);
   }
   for (const field of fields) {
+    if (!Object.hasOwn(record, field) && (OPTIONAL_FIELDS[kind] ?? []).includes(field)) continue;
     if (!own.includes(field)) {
       return refuse(`${kind}: missing field "${field}" — every field of the closed set is pinned as an OWN ENUMERABLE key (the digest domain)`);
     }
@@ -492,6 +515,10 @@ export const validateDelegationRecord = (record) => {
   }
   if (record.kind === 'dispatch') {
     const vehicle = validateVehicle('dispatch: vehicle', record.vehicle);
+    if (Object.hasOwn(record, 'baseline')) {
+      const baseline = validateBaseline('dispatch: baseline', record.baseline);
+      if (!baseline.ok) return baseline;
+    }
     return vehicle.ok ? validateDispatchCrossFields(record) : vehicle;
   }
   if (record.kind === 'return') return validateReturnCrossFields(record);

package/tools/dispatch-store-read.mjs

@@ -3,7 +3,7 @@ import { spawnSync } from 'node:child_process';
 
 import {
   validateDelegationRecord, canonicalDelegationDigest, allowedSuccessorKinds,
-  isThreadTerminalRecord,
+  isThreadTerminalRecord, readsBaseline,
 } from './dispatch-record.mjs';
 import { readRegularFileNoFollow } from './fs-read-nofollow.mjs';
 import { GIT_MAX_BUFFER } from './git-env.mjs';
@@ -175,6 +175,11 @@ export const delegationSemanticPreflight = ({ records, snapshot, storePath }) =>
       if (snapshot.stepClass !== prior.dispatch.stepClass) {
         throw stop(`refusing a retry: it declares step class "${snapshot.stepClass}" but its retry origin "${snapshot.retryOf}" was dispatched as "${prior.dispatch.stepClass}" — the pairing key is the step class, so a chain that changes it mid-way would split one attempt's accounting across two classes; nothing was written`);
       }
+      const base = readsBaseline(snapshot);
+      const priorBase = readsBaseline(prior.dispatch);
+      if (base.kind !== priorBase.kind || base.treeOid !== priorBase.treeOid) {
+        throw stop(`refusing a retry: its base {kind "${base.kind}", treeOid ${base.treeOid}} differs from its retry origin "${snapshot.retryOf}"'s {kind "${priorBase.kind}", treeOid ${priorBase.treeOid}} — a retry chain is measured against ONE base; nothing was written`);
+      }
       const origin = findRetryChainOrigin(records, prior.dispatch);
       if (snapshot.retryIndex > origin.retryCap) {
         throw stop(`refusing a retry: retryIndex ${snapshot.retryIndex} exceeds the retryCap ${origin.retryCap} recorded on the thread's ORIGIN dispatch ("${origin.nonce}") — a fresh contract never manufactures a fresh retry budget; nothing was written`);

package/tools/dispatch-store.mjs

@@ -2,7 +2,8 @@
 // The read half lives in dispatch-store-read.mjs so read-only consumers never reach this writer.
 
 import { computeTreeFingerprint } from './core-evidence.mjs';
-import { validateDelegationRecord } from './dispatch-record.mjs';
+import { validateDelegationRecord, HEAD_BASELINE } from './dispatch-record.mjs';
+import { computeBaseFingerprint } from './dispatch-baseline.mjs';
 import {
   delegationStoreStop,
   resolveDelegationStorePath,
@@ -30,8 +31,8 @@ export const resolveDelegationLockPath = (storePath) => `${storePath}${DELEGATIO
 
 export const UNCOMMITTED_STATE_FINGERPRINT = 'the uncommitted-state fingerprint';
 
-export const uncommittedStateFingerprint = (cwd = process.cwd(), fsx) => {
-  const fingerprint = computeTreeFingerprint(cwd, fsx);
+export const uncommittedStateFingerprint = (cwd = process.cwd(), fsx, base = HEAD_BASELINE) => {
+  const fingerprint = base.kind === 'head' ? computeTreeFingerprint(cwd, fsx) : computeBaseFingerprint(cwd, base, fsx);
   if (fingerprint == null) {
     throw stop(`cannot compute ${UNCOMMITTED_STATE_FINGERPRINT} — not inside a git work tree (or a git probe failed); a record never carries a null tree digest (fail closed)`);
   }