@sublang/playbook 17.6.0 → 17.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sublang/playbook",
-  "version": "17.6.0",
+  "version": "17.8.0",
   "type": "module",
   "description": "Composable XState v5 playbook runtime with compiled Captain, CODE, REVIEW, DECIDE, DEV, BRANCH, PR, and INSPECT workflows driven by GEARS specs.",
   "license": "Apache-2.0",

package/reference/sdlc/code.playbook/bin/machine-identity.js

@@ -112,6 +112,24 @@ export function resolveMachineIdentity(options = {}) {
   return pending;
 }
 
+/** One store's or coordinator's lazy resolution (playbook-cli-97): the
+ * first identity it resolves is kept for its lifetime, and a refusal is
+ * not, so its next lease or claim resolves again once the file is
+ * repaired. */
+export function lazyMachineIdentity(resolve) {
+  let pending;
+  return () => {
+    if (pending === undefined) {
+      const attempt = Promise.resolve(resolve());
+      pending = attempt;
+      attempt.catch(() => {
+        if (pending === attempt) pending = undefined;
+      });
+    }
+    return pending;
+  };
+}
+
 async function readOrPublish(path, fs, createIdentity) {
   const directory = dirname(path);
   await prepareDirectory(directory, path, fs);

package/reference/sdlc/code.playbook/bin/repository-effects.js

@@ -30,6 +30,7 @@ import {
   classifyOwnerMachine,
   describeOwnerMachine,
   isMachineIdentity,
+  lazyMachineIdentity,
   resolveMachineIdentity,
 } from './machine-identity.js';
 
@@ -975,27 +976,43 @@ async function isAncestor(worktree, baselineHead, afterHead) {
   }
 }
 
-async function descendantCount(worktree, baselineHead, afterHead) {
-  const value = await runGitText(worktree, [
+// DR-088 §1: the commits reachable from the after HEAD and not from the
+// baseline HEAD — every reachable commit for the null HEAD — oldest first, so
+// the last is the after HEAD itself.
+async function newCommits(worktree, baselineHead, afterHead) {
+  const raw = await runGitText(worktree, [
     'rev-list',
-    '--count',
+    '--topo-order',
+    '--reverse',
     baselineHead === NULL_GIT_OID ? afterHead : `${baselineHead}..${afterHead}`,
   ]);
-  const count = Number(value);
-  if (!Number.isSafeInteger(count) || count < 0) {
+  const commits = raw.length === 0 ? [] : raw.split('\n');
+  if (
+    commits.some((oid) => !/^[0-9a-f]{40}(?:[0-9a-f]{24})?$/.test(oid)) ||
+    new Set(commits).size !== commits.length ||
+    (commits.length > 0 && commits.at(-1) !== afterHead)
+  ) {
     throw new RepositoryObservationAmbiguousError(
-      'Git returned an invalid descendant count',
+      'Git returned an invalid list of new commits',
     );
   }
-  return count;
+  return commits;
 }
 
-function receipt(classification, baseline, after, commitOid, preExisting) {
+function receipt(
+  classification,
+  baseline,
+  after,
+  commitOid,
+  preExisting,
+  commits,
+) {
   return deepFreeze({
     classification,
     baseline,
     ...(after === undefined ? {} : { after }),
     ...(commitOid === undefined ? {} : { commitOid }),
+    ...(commits === undefined ? {} : { commits }),
     ...(preExisting === undefined ? {} : { preExisting }),
   });
 }
@@ -1048,12 +1065,13 @@ export async function classifyRepositoryReceipt(
   ) {
     return receipt('rewritten-or-non-descendant', baseline, after);
   }
-  const count = await descendantCount(after.worktree, baseline.head, after.head);
-  if (count > 1) return receipt('multiple-commits', baseline, after);
-  if (count !== 1) {
+  // DR-088 §1: HEAD advanced by one or more new commits; a receipt of more
+  // than one lists every one, oldest first.
+  const commits = await newCommits(after.worktree, baseline.head, after.head);
+  if (commits.length === 0) {
     return receipt('rewritten-or-non-descendant', baseline, after);
   }
-  // DR-062 §2: the one commit proves itself when every baseline entry is
+  // DR-062 §2: the advance proves itself when every baseline entry is
   // preserved, absorbed, or altered and carried by it, and the after
   // projection holds nothing else.
   const fates = await baselineEntryFates(baseline, after);
@@ -1070,6 +1088,7 @@ export async function classifyRepositoryReceipt(
     after,
     unattributable ? undefined : after.head,
     preExistingFromFates(fates),
+    unattributable || commits.length === 1 ? undefined : commits,
   );
 }
 
@@ -1328,8 +1347,9 @@ function validateCohort(options) {
 
 export function createRepositoryEffectCoordinator(options = {}) {
   // DR-087: the claim owner's `hostname` carries this machine's identity,
-  // read once at the first claim; an explicit value stands in for it
-  // (tests). An untagged owner is a legacy host name compared with the
+  // read at the first claim and kept once read, while a refusal is read
+  // again at the next (playbook-cli-97); an explicit value stands in for
+  // it (tests). An untagged owner is a legacy host name compared with the
   // current one — or with an explicit untagged value, which then names
   // this machine both ways.
   const explicitHostname = options.hostname;
@@ -1338,15 +1358,13 @@ export function createRepositoryEffectCoordinator(options = {}) {
     (typeof explicitHostname === 'string' && !isMachineIdentity(explicitHostname)
       ? explicitHostname
       : systemHostname());
-  let currentIdentityPending;
-  const currentIdentity = () =>
-    (currentIdentityPending ??=
-      explicitHostname !== undefined
-        ? Promise.resolve(explicitHostname)
-        : resolveMachineIdentity({
-            ...(options.env !== undefined ? { env: options.env } : {}),
-            ...(options.homeDir !== undefined ? { homeDir: options.homeDir } : {}),
-          }));
+  const currentIdentity = lazyMachineIdentity(() =>
+    explicitHostname !== undefined
+      ? explicitHostname
+      : resolveMachineIdentity({
+          ...(options.env !== undefined ? { env: options.env } : {}),
+          ...(options.homeDir !== undefined ? { homeDir: options.homeDir } : {}),
+        }));
   const currentPid = options.pid ?? process.pid;
   const pollIntervalMs = options.pollIntervalMs ?? 10;
   const probeProcess = options.probeProcess ?? defaultProbeProcess;

package/reference/sdlc/code.playbook/bin/session-store.js

@@ -28,7 +28,7 @@ import {
   unlink,
 } from 'node:fs/promises';
 import { homedir, hostname as systemHostname } from 'node:os';
-import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { isDeepStrictEqual } from 'node:util';
 import { assertSupportedEffort } from '@sublang/cligent';
@@ -48,6 +48,7 @@ import {
   classifyOwnerMachine,
   describeOwnerMachine,
   isMachineIdentity,
+  lazyMachineIdentity,
   resolveMachineIdentity,
 } from './machine-identity.js';
 import { sameFileIdentity, syncDirectory, tightenPrivateEntry } from './private-paths.js';
@@ -638,41 +639,50 @@ export function createCaptainSessionStore(options = {}) {
   const createTempId = options.createTempId ?? randomUUID;
   const createLeaseToken = options.createLeaseToken ?? randomUUID;
   // DR-087: the owner's `hostname` carries this machine's identity, read
-  // once at the first lease boundary; an explicit value stands in for it
-  // (tests, migration sub-stores). An untagged owner is a legacy host
-  // name, compared with the current one — or with an explicit untagged
-  // value, which then names this machine both ways.
+  // at the first lease boundary and kept once read, while a refusal is
+  // read again at the next (playbook-cli-97); an explicit value stands in
+  // for it (tests, migration sub-stores). An untagged owner is a legacy
+  // host name, compared with the current one — or with an explicit
+  // untagged value, which then names this machine both ways.
   const explicitHostname = options.hostname;
   const legacyHostname =
     options.legacyHostname ??
     (typeof explicitHostname === 'string' && !isMachineIdentity(explicitHostname)
       ? explicitHostname
       : systemHostname());
-  let localIdentityPending;
-  const localIdentity = () =>
-    (localIdentityPending ??=
-      explicitHostname !== undefined
-        ? Promise.resolve(explicitHostname)
-        : options.resolveHostname !== undefined
-          ? options.resolveHostname()
-          : resolveMachineIdentity({ env, homeDir: home }));
+  const localIdentity = lazyMachineIdentity(() =>
+    explicitHostname !== undefined
+      ? explicitHostname
+      : options.resolveHostname !== undefined
+        ? options.resolveHostname()
+        : resolveMachineIdentity({ env, homeDir: home }));
   const localPid = options.pid ?? process.pid;
   const probeProcess =
     options.probeProcess ?? ((pid) => process.kill(pid, 0));
   const fs = { ...DEFAULT_FS_OPERATIONS, ...(options.fsOps ?? {}) };
+  // session-storage-11: a host that prepared the directory may forbid
+  // creating it or an ancestor, so a directory that moves or vanishes
+  // mid-operation is refused rather than recreated at its former path.
+  const createSessionsDir =
+    options.createSessionsDir === undefined ? true : options.createSessionsDir;
+  const mayCreateDirectory = (directory) =>
+    createSessionsDir || !isPathOrAncestor(directory, sessionsDir);
   const replayReadCursors = new Map();
   const replayReadQueues = new Map();
   const portableWriters = new Map();
   const assetStores = new Map();
   const assetStoreFor = (sessionId) => {
     assertSessionId(sessionId);
-    if (!assetStores.has(sessionId)) assetStores.set(sessionId, createAssetStore({ directory: join(sessionsDir, `${sessionId}.assets`), ...(options.maxAssetBytes === undefined ? {} : { maxAssetBytes: options.maxAssetBytes }) }));
+    if (!assetStores.has(sessionId)) assetStores.set(sessionId, createAssetStore({ directory: join(sessionsDir, `${sessionId}.assets`), createAncestors: createSessionsDir, ...(options.maxAssetBytes === undefined ? {} : { maxAssetBytes: options.maxAssetBytes }) }));
     return assetStores.get(sessionId);
   };
 
   if (!isAbsolute(sessionsDir)) {
     throw new Error('Captain session store path must be absolute');
   }
+  if (typeof createSessionsDir !== 'boolean') {
+    throw new TypeError('Captain session store createSessionsDir must be a boolean');
+  }
   if (
     explicitHostname !== undefined &&
     (typeof explicitHostname !== 'string' ||
@@ -1101,7 +1111,7 @@ export function createCaptainSessionStore(options = {}) {
       : await portableWriters.get(recordValue.sessionId)?.checkpoint(recordValue);
     if (record === undefined) throw new Error('session persistence requires its owning lifecycle');
     const destination = recordPathFor(record.sessionId);
-    await ensurePrivateDirectory(sessionsDir, fs);
+    await ensurePrivateDirectory(sessionsDir, fs, mayCreateDirectory);
 
     if (noReplace) {
       await assertPathMissing(
@@ -1358,7 +1368,7 @@ export function createCaptainSessionStore(options = {}) {
   };
 
   const makeLeaseStage = async (sessionId) => {
-    await ensurePrivateDirectory(sessionsDir, fs);
+    await ensurePrivateDirectory(sessionsDir, fs, mayCreateDirectory);
     const ownerToken = createLeaseToken();
     assertUuid(ownerToken, 'Captain session lease owner token');
     const retiredPath = retiredPathFor(sessionId, ownerToken);
@@ -1625,10 +1635,10 @@ export function createCaptainSessionStore(options = {}) {
     // the lease below; a preflight read never authorizes migration writes.
     try { decodeSource(await readPrivateRegularFile(sourcePath, 0o600, fs, 'migration source')); }
     catch (cause) { if (cause?.code !== 'ENOENT' || !sidecar && !external) throw cause; }
-    let sourceLease, lease;
+    let sourceLease, lease, failure;
     try {
       if (external) {
-        const sourceStore = createCaptainSessionStore({ sessionsDir: sourceDir, env, homeDir: home, fsOps: fs, resolveHostname: localIdentity, legacyHostname, pid: localPid, probeProcess });
+        const sourceStore = createCaptainSessionStore({ sessionsDir: sourceDir, createSessionsDir, env, homeDir: home, fsOps: fs, resolveHostname: localIdentity, legacyHostname, pid: localPid, probeProcess });
         sourceLease = await sourceStore.acquireManagement(sessionId);
       }
       lease = await acquire(sessionId, true);
@@ -1719,7 +1729,7 @@ export function createCaptainSessionStore(options = {}) {
           if (existing !== `${JSON.stringify(manifest)}\n`) throw new Error('migration destination manifest diverged');
         } catch (cause) { if (cause?.code !== 'ENOENT') throw cause; }
       }
-      await ensurePrivateDirectory(inputsDir, fs);
+      await ensurePrivateDirectory(inputsDir, fs, mayCreateDirectory);
       const inputs = [{ path: sourcePath, bytes: Buffer.from(sourceBytes, 'utf8') }, ...(originalReplay === undefined ? [] : [{ path: sourceReplayPath, bytes: originalReplay }])];
       for (const [index, input] of inputs.entries()) {
         const path = join(inputsDir, String(index));
@@ -1743,8 +1753,11 @@ export function createCaptainSessionStore(options = {}) {
       if (sidecar || external) { await fs.unlink(sourcePath); await syncDirectory(sourceDir, fs); }
       await writePrivateJson(receiptPath, { ...receipt, complete: true }, fs);
       return { manifest, migrated: true, reasons: [] };
+    } catch (cause) {
+      failure = { cause };
+      throw cause;
     } finally {
-      try { await lease?.release(); } finally { await sourceLease?.release(); }
+      await releaseInOrder([lease, sourceLease], failure, `cannot migrate Captain session ${JSON.stringify(sessionId)} without leaving ownership uncertain`);
     }
   };
 
@@ -1754,7 +1767,7 @@ export function createCaptainSessionStore(options = {}) {
     const sourceDir = join(sourceEnv.XDG_STATE_HOME || join(sourceHome, '.local', 'state'), 'playbook', 'sessions');
     const result = { sourceDir, migrated: [], skipped: [] };
     if (sourceDir === sessionsDir) return result;
-    const sourceStore = createCaptainSessionStore({ sessionsDir: sourceDir, env: sourceEnv, homeDir: sourceHome, fsOps: fs, resolveHostname: localIdentity, legacyHostname, pid: localPid, probeProcess });
+    const sourceStore = createCaptainSessionStore({ sessionsDir: sourceDir, createSessionsDir, env: sourceEnv, homeDir: sourceHome, fsOps: fs, resolveHostname: localIdentity, legacyHostname, pid: localPid, probeProcess });
     await sourceStore.prepare();
     try { await assertPrivateDirectory(sourceDir, fs); }
     catch (cause) { if (cause?.code === 'ENOENT') return result; throw cause; }
@@ -1778,8 +1791,10 @@ export function createCaptainSessionStore(options = {}) {
 
   const remove = async (sessionId) => {
     const lease = await acquire(sessionId, true);
+    let failure;
     try { await lease.assertOwner(); await deleteRecord(sessionId); }
-    finally { await lease.release(); }
+    catch (cause) { failure = { cause }; throw cause; }
+    finally { await releaseInOrder([lease], failure, `cannot delete Captain session ${JSON.stringify(sessionId)} without leaving ownership uncertain`); }
   };
 
   const exportBundle = async (sessionId) => {
@@ -6706,7 +6721,7 @@ async function assertPathMissing(path, fs, message) {
 }
 
 
-async function ensurePrivateDirectory(path, fs) {
+async function ensurePrivateDirectory(path, fs, mayCreate = () => true) {
   try {
     await assertPrivateDirectory(path, fs);
     return;
@@ -6728,6 +6743,15 @@ async function ensurePrivateDirectory(path, fs) {
       cursor = parent;
     }
   }
+  // Refuse before creating anything, so a forbidden ancestor is never
+  // recreated beneath a permitted descendant (session-storage-11).
+  const forbidden = missing.find((directory) => !mayCreate(directory));
+  if (forbidden !== undefined) {
+    throw Object.assign(
+      new Error(`Captain session store directory ${JSON.stringify(forbidden)} is missing and this store may not create it`),
+      { code: 'ENOENT' },
+    );
+  }
   for (const directory of missing.reverse()) {
     let created = false;
     try {
@@ -6750,6 +6774,32 @@ async function ensurePrivateDirectory(path, fs) {
   await assertPrivateDirectory(path, fs);
 }
 
+// Releases every acquired lease in order. Without an earlier failure the
+// last release error propagates, as nested try/finally releases would; a
+// release error never hides the failure that preceded it.
+async function releaseInOrder(leases, failure, message) {
+  const errors = [];
+  for (const lease of leases) {
+    try {
+      await lease?.release();
+    } catch (error) {
+      errors.push(error);
+    }
+  }
+  if (errors.length === 0) return;
+  if (failure === undefined) throw errors.at(-1);
+  throw new AggregateError([failure.cause, ...errors], message);
+}
+
+function isPathOrAncestor(directory, path) {
+  const fromDirectory = relative(directory, path);
+  return fromDirectory === '' || (
+    fromDirectory !== '..' &&
+    !fromDirectory.startsWith(`..${sep}`) &&
+    !isAbsolute(fromDirectory)
+  );
+}
+
 async function assertPrivateDirectory(path, fs) {
   const stat = await assertDirectoryNotLink(path, fs);
   if ((stat.mode & 0o7777) !== 0o700) {

package/reference/sdlc/code.playbook/host-capabilities.d.ts

@@ -42,6 +42,8 @@ export interface PlaybookRepositoryReceipt {
   readonly baseline: PlaybookRepositoryObservation;
   readonly after?: PlaybookRepositoryObservation;
   readonly commitOid?: string;
+  /** Every new commit, oldest first, where HEAD advanced by more than one (DR-088). */
+  readonly commits?: readonly string[];
   readonly preExisting?: PlaybookRepositoryPreExistingChanges;
 }
 export interface RepositoryReceiptOptions {

package/reference/sdlc/code.playbook/playbook-captain.js

@@ -621,6 +621,112 @@ function carriedPreExistingFacts(carried) {
         return `The commit ${commitOid} carries changes that were uncommitted before the step: ${lists.join('; ')}.`;
     });
 }
+function commitsBeforeFailure(ledger, boundaryPrefixCount, unresolvedEffects) {
+    // An entry names a commit by its proven OID, or — for a receipt listing
+    // several commits, which projects as `multiple-commits` (DR-088 §3) — by
+    // its after HEAD, the last of them.
+    const named = new Set(unresolvedEffects.flatMap(({ classification, afterHead, commitOid }) => commitOid !== undefined
+        ? [commitOid]
+        : classification === 'multiple-commits' && afterHead !== undefined
+            ? [afterHead]
+            : []));
+    const commits = [];
+    for (const boundary of ledger.boundaries) {
+        if (boundary.sequence <= boundaryPrefixCount)
+            continue;
+        const receipt = boundary.physicalReceipt;
+        if (receipt?.classification !== 'one-descendant-commit' ||
+            receipt.commitOid === undefined ||
+            named.has(receipt.commitOid)) {
+            continue;
+        }
+        named.add(receipt.commitOid);
+        commits.push({
+            baselineHead: receipt.baseline.head,
+            commitOid: receipt.commitOid,
+            ...(receipt.commits === undefined ? {} : { commits: receipt.commits }),
+        });
+    }
+    return commits;
+}
+/** What one step committed, with every commit where it made several (DR-088). */
+function commitBeforeFailureClause({ baselineHead, commitOid, commits, }) {
+    const made = commits === undefined
+        ? 'made one new commit'
+        : `made ${commits.length} new commits, oldest first: ${boundedPathList(commits)}`;
+    return `${made}; HEAD moved from ${baselineHead} to the proven commit ${commitOid}.`;
+}
+function commitBeforeFailureFact(commit) {
+    return `Before the failure, a step ${commitBeforeFailureClause(commit)}`;
+}
+function commitsBeforeFailureReport(commits) {
+    if (commits.length === 0)
+        return undefined;
+    return [
+        'Repository changes made before the failure:',
+        ...commits.map((commit) => `- A step ${commitBeforeFailureClause(commit)}`),
+        'The failure does not undo these commits.',
+    ].join('\n');
+}
+/**
+ * DR-088 §2: whether a final text names one commit as a word, by its full OID
+ * or by an abbreviation of at least seven leading hex digits — the
+ * reconciler's own designation rule, read here to say what it accepted.
+ */
+function finalTextNamesCommit(finalText, oid) {
+    for (const [word] of finalText.matchAll(/(?<![0-9A-Za-z_])[0-9A-Fa-f]{7,64}(?![0-9A-Za-z_])/g)) {
+        if (oid.startsWith(word.toLowerCase()))
+            return true;
+    }
+    return false;
+}
+/**
+ * DR-088 §3: what the steps completed after `boundaryPrefixCount` committed,
+ * one statement each, in boundary sequence order: every new commit where a
+ * receipt proves more than one, and the commit already at HEAD where a step
+ * whose outcomes all commit or ask named it over an `unchanged` receipt. A
+ * step in a deferred chain reads the chain's cumulative receipt at its last
+ * boundary.
+ */
+function stepCommitStatements(ledger, boundaryPrefixCount) {
+    const statements = [];
+    for (const boundary of ledger.boundaries) {
+        if (boundary.sequence <= boundaryPrefixCount)
+            continue;
+        let receipt = boundary.physicalReceipt;
+        if (boundary.logicalOperationId !== undefined) {
+            const operation = ledger.logicalOperations.find(({ operationId }) => operationId === boundary.logicalOperationId);
+            if (operation?.boundaryIds.at(-1) !== boundary.boundaryId)
+                continue;
+            receipt = operation.logicalReceipt;
+        }
+        if (receipt === undefined)
+            continue;
+        if (receipt.classification === 'one-descendant-commit' &&
+            receipt.commits !== undefined) {
+            statements.push(`The step made ${receipt.commits.length} new commits, oldest first: ${boundedPathList(receipt.commits)}.`);
+            continue;
+        }
+        const candidate = boundary.semanticCandidate;
+        const guard = candidate !== null &&
+            typeof candidate === 'object' &&
+            !Array.isArray(candidate)
+            ? candidate.guard
+            : undefined;
+        const head = receipt.after?.head;
+        if (receipt.classification === 'unchanged' &&
+            head !== undefined &&
+            !/^0+$/.test(head) &&
+            boundary.dispositions.includes('one-descendant-commit') &&
+            !boundary.dispositions.includes('unchanged') &&
+            typeof guard === 'string' &&
+            guard !== BOSS_QUESTION_OUTCOME &&
+            finalTextNamesCommit(boundary.finalText?.trim() ?? '', head)) {
+            statements.push(`The step made no new commit; it named ${head}, already at HEAD, as its work.`);
+        }
+    }
+    return statements;
+}
 // DR-063 §4: the Boss-visible failure report. Every host sees the same
 // sentences because the shell composes them from the structured cause instead
 // of asking a model to describe facts it may drop. The report exposes no file
@@ -2402,6 +2508,15 @@ async function buildEnablements(options, loadModule, hostCapabilities) {
 const unresolvedEffectFromReceipt = (receipt, baselineHead = receipt.baseline.head) => {
     if (receipt.classification === 'unchanged')
         return undefined;
+    // DR-088 §3: a receipt listing more than one new commit reads as
+    // `multiple-commits`, whose entry names more than one commit and no OID.
+    if (receipt.commits !== undefined) {
+        return {
+            classification: 'multiple-commits',
+            baselineHead,
+            ...(receipt.after === undefined ? {} : { afterHead: receipt.after.head }),
+        };
+    }
     return {
         classification: receipt.classification,
         baselineHead,
@@ -2478,12 +2593,18 @@ const cumulativeOpenLogicalEffect = (operation, boundaries) => {
     }
     if (receipt.classification === 'one-descendant-commit' &&
         (sameProjection || receiptAccountsFromOriginal)) {
-        return {
-            classification: 'one-descendant-commit',
-            baselineHead: original.head,
-            afterHead: after.head,
-            commitOid: after.head,
-        };
+        return receipt.commits === undefined
+            ? {
+                classification: 'one-descendant-commit',
+                baselineHead: original.head,
+                afterHead: after.head,
+                commitOid: after.head,
+            }
+            : {
+                classification: 'multiple-commits',
+                baselineHead: original.head,
+                afterHead: after.head,
+            };
     }
     return {
         classification: 'observation-ambiguous',
@@ -2792,21 +2913,30 @@ export function createPlaybookCaptainShell(options, deps = {}) {
         if (turn.carriedEffectPrefix !== undefined)
             return;
         let carried;
+        let commitStatements;
         try {
             const ledger = assertPlaybookEffectLedger(currentEffectLedger());
             carried = carriedPreExistingChanges(ledger, presentedEffectPrefix);
+            commitStatements = stepCommitStatements(ledger, presentedEffectPrefix);
             turn.carriedEffectPrefix = ledger.boundaries.length;
         }
         catch {
             return;
         }
         const report = carriedPreExistingReport(carried);
-        if (report === undefined)
-            return;
-        const facts = carriedPreExistingFacts(carried);
-        appendMandatoryPresentationSuffix(turn, report, facts);
-        for (const fact of facts) {
-            joinSettlementFact(turn, fact);
+        if (report !== undefined) {
+            const facts = carriedPreExistingFacts(carried);
+            appendMandatoryPresentationSuffix(turn, report, facts);
+            for (const fact of facts) {
+                joinSettlementFact(turn, fact);
+            }
+        }
+        // DR-088 §3: the commits each step took, read from the same boundaries.
+        if (commitStatements.length > 0) {
+            appendMandatoryPresentationSuffix(turn, commitStatements.join('\n'), commitStatements);
+            for (const fact of commitStatements) {
+                joinSettlementFact(turn, fact);
+            }
         }
     };
     /**
@@ -6203,6 +6333,26 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             controls: failureControlLines(view, fenced),
         };
         joinSettlementFact(turn, fact, statement?.fact, speak);
+        reportCommitsBeforeFailure(turn, unresolvedEffects);
+    };
+    // DR-089: the commits the turn's receipts proved before its leaf parked,
+    // stated beside the failure report and joined to the settlement facts the
+    // closing-reply prompt reads.
+    const reportCommitsBeforeFailure = (turn, unresolvedEffects) => {
+        let commits;
+        try {
+            commits = commitsBeforeFailure(assertPlaybookEffectLedger(currentEffectLedger()), presentedEffectPrefix, unresolvedEffects);
+        }
+        catch {
+            return;
+        }
+        const report = commitsBeforeFailureReport(commits);
+        if (report === undefined)
+            return;
+        const facts = commits.map(commitBeforeFailureFact);
+        appendMandatoryPresentationSuffix(turn, report, facts);
+        for (const fact of facts)
+            joinSettlementFact(turn, fact);
     };
     // The runtimes own each frame's position. The shell only joins their stack.
     const saveProgress = async (starting, step, required = true) => {