@sublang/playbook 15.1.0 → 17.0.0

package/slc/materialize-link.mjs

@@ -7,7 +7,7 @@
 import { createRequire } from 'node:module';
 import { lstat, open, realpath, rename, unlink } from 'node:fs/promises';
 import { randomUUID } from 'node:crypto';
-import { dirname, extname, relative, resolve } from 'node:path';
+import { basename, dirname, extname, relative, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 
 // Compile-time source only; emitted modules depend only on the shared engine.
@@ -78,6 +78,10 @@ const DESCRIPTOR_KEYS = [
   'transitionEventFields', 'verbatimPayloadFields', 'resumableStateIds',
   'unfinishedFinalStateIds', 'controlContextFields',
 ];
+// Optional: the runtime specifier of the FSM's emitted JavaScript sibling, for
+// a module inside a package that compiles and ships `.js` beside its sources.
+const OPTIONAL_KEYS = ['fsmSpecifier'];
+const JS_SPECIFIER = /^\.\.?\/.+\.js$/;
 const LABELLED_KEYS = ['playerInputExport', 'omitEmptyRelayLines', 'identityPlaceholders'];
 const TOKEN = /^(#|[A-Za-z_$][A-Za-z0-9_$-]*)$/;
 const CONTRACT_TYPES = [
@@ -126,7 +130,10 @@ function validateDescriptor(value, engine) {
   const descriptor = engine.snapshotJsonValue(value, 'link descriptor');
   const labelled = descriptor?.profile === 'flat-labelled-relays';
   const keys = labelled ? [...DESCRIPTOR_KEYS, ...LABELLED_KEYS] : DESCRIPTOR_KEYS;
-  record(descriptor, 'descriptor', keys, keys);
+  record(descriptor, 'descriptor', [...keys, ...OPTIONAL_KEYS], keys);
+  if (descriptor.fsmSpecifier !== undefined && (typeof descriptor.fsmSpecifier !== 'string' || !JS_SPECIFIER.test(descriptor.fsmSpecifier))) {
+    throw new TypeError('fsmSpecifier must be a relative runtime specifier ending in .js');
+  }
   if (descriptor.schema !== SCHEMA) throw new TypeError(`descriptor.schema must equal ${SCHEMA}`);
   if (!['flat-defaults', 'flat-quoted-relays', 'flat-labelled-relays'].includes(descriptor.profile)) throw new UnsupportedLinkProfile('profile requires ordinary normative linking');
   if (labelled) {
@@ -228,27 +235,46 @@ function validateDescriptor(value, engine) {
 function inspectMachine(machine, engine, labelled = false) {
   const config = machine?.config;
   if (!config || typeof config !== 'object' || !config.states) throw new TypeError('FSM export must be an XState machine');
-  if (config.type === 'parallel' || config.invoke) throw new UnsupportedLinkProfile('root parallel states or invocations require ordinary linking');
+  if (config.type === 'parallel' || config.invoke) throw new UnsupportedLinkProfile('a parallel machine root or root invocation requires ordinary linking');
   const descriptions = engine.stateDescriptionsFromMachine(machine);
   const roleStates = Object.create(null);
   let hasScript = false;
-  for (const [key, state] of Object.entries(config.states)) {
+  const children = (value) => value && typeof value === 'object' ? Object.entries(value) : [];
+  const inspectState = (key, state) => {
     if (RESERVED_KEYS.has(key)) throw new UnsupportedLinkProfile(`state ${key} requires ordinary linking`);
     if (!state || typeof state !== 'object') throw new TypeError(`state ${key} must be an object`);
-    if (state.states || (state.type !== undefined && !['atomic', 'final'].includes(state.type))) {
-      throw new UnsupportedLinkProfile(`state ${key} is outside the flat single-region profile`);
-    }
     const invokes = Array.isArray(state.invoke) ? state.invoke : state.invoke ? [state.invoke] : [];
     if (invokes.length > 1) throw new UnsupportedLinkProfile(`state ${key} has multiple actors`);
     for (const invoke of invokes) {
       if (!(labelled ? ['player', 'script', 'playbook'] : ['player', 'script']).includes(invoke.src)) throw new UnsupportedLinkProfile(`state ${key} actor ${String(invoke.src)} requires ordinary linking`);
       if (invoke.src === 'script') hasScript = true;
       else if (invoke.src === 'player') {
-        const role = nonempty(state.meta?.playbook?.role, `state ${key} role`);
-        const label = nonempty(descriptions.get(key), `state ${key} description`);
-        roleStates[key] = { role, label };
+        // The engine keys a player state by its stable playbook id, which a
+        // parallel region's leaf carries distinct from its local key.
+        const stateId = typeof state.meta?.playbook?.stateId === 'string' ? state.meta.playbook.stateId
+          : typeof state.id === 'string' ? state.id : key;
+        if (RESERVED_KEYS.has(stateId)) throw new UnsupportedLinkProfile(`state ${stateId} requires ordinary linking`);
+        const role = nonempty(state.meta?.playbook?.role, `state ${stateId} role`);
+        const label = nonempty(descriptions.get(stateId), `state ${stateId} description`);
+        roleStates[stateId] = { role, label };
+      }
+    }
+  };
+  for (const [key, state] of Object.entries(config.states)) {
+    if (RESERVED_KEYS.has(key)) throw new UnsupportedLinkProfile(`state ${key} requires ordinary linking`);
+    if (!state || typeof state !== 'object') throw new TypeError(`state ${key} must be an object`);
+    if (state.type === 'parallel') {
+      // DR-067: walk a root parallel state's region leaves; the engine's
+      // construction preflight below owns validation of the compiled shape.
+      for (const [, region] of children(state.states)) {
+        for (const [leafKey, leaf] of children(region?.states)) inspectState(leafKey, leaf);
       }
+      continue;
+    }
+    if (state.states || (state.type !== undefined && !['atomic', 'final'].includes(state.type))) {
+      throw new UnsupportedLinkProfile(`state ${key} is outside the flat single-region profile`);
     }
+    inspectState(key, state);
   }
   return { roleStates, hasScript };
 }
@@ -355,6 +381,7 @@ const OPTION_SCHEMA = ${json(options)} as const;
 const INPUT_MAPPING = ${json(descriptor.inputMapping)} as const;
 const RESUMABLE_STATE_IDS: ReadonlySet<string> = new Set(${json(descriptor.resumableStateIds)});
 const UNFINISHED_FINAL_STATE_IDS: ReadonlySet<string> = new Set(${json(descriptor.unfinishedFinalStateIds)});
+const VERBATIM_PAYLOAD_FIELDS: ReadonlySet<string> = new Set(${json(descriptor.verbatimPayloadFields)});
 export function validateOptions(value: unknown): PlaybookRuntimeOptions {
   const captured = snapshotJsonValue(value === undefined ? {} : value, ${JSON.stringify(`${descriptor.label} runtime options`)});
   if (captured === null || typeof captured !== 'object' || Array.isArray(captured)) {
@@ -380,7 +407,7 @@ ${quotedPlayer || labelledPlayer ? '  composePlayerPrompt,\n' : ''}  ...${json(d
     Object.entries(INPUT_MAPPING).filter(([, key]) => options[key as keyof PlaybookRuntimeOptions] !== undefined)
       .map(([field, key]) => [field, options[key as keyof PlaybookRuntimeOptions]]),
   ),
-  verbatimPayloadFields: new Set<string>(${json(descriptor.verbatimPayloadFields)}),
+  verbatimPayloadFields: VERBATIM_PAYLOAD_FIELDS,
   resumableStateIds: RESUMABLE_STATE_IDS,
   unfinishedFinalStateIds: UNFINISHED_FINAL_STATE_IDS,
 } satisfies XStatePlaybookRuntimeSpecV3<PlaybookRuntimeOptions>;
@@ -389,6 +416,7 @@ export const _internal = {
   ${quotedPlayer || labelledPlayer ? 'composePlayerPrompt,\n  ' : hasPlayer ? `composePlayerPrompt: (input: PlaybookPlayerInput, _identity?: unknown${hasContinuationMode ? ', resuming = false' : ''}) =>
     defaultComposePlayerPrompt(input, ${json(descriptor.placeholderFields)}${hasContinuationMode ? ', resuming' : ''}),\n  ` : ''}RESUMABLE_STATE_IDS,
   UNFINISHED_FINAL_STATE_IDS,
+  VERBATIM_PAYLOAD_FIELDS,
 };
 const createPlaybookRuntime: XStatePlaybookRuntimeFactory<
   XStatePlaybookRuntimeConstruction<PlaybookRuntimeOptions, PlaybookHostCapabilities>, 3
@@ -428,9 +456,19 @@ export async function runMaterializer(argv, input) {
   // Validate the export name before selecting it from the imported module.
   validateDescriptor(descriptor, engine);
   const module = await import(pathToFileURL(source).href);
-  const specifier = relative(dirname(out), fsm).replaceAll('\\', '/');
+  const derived = relative(dirname(out), fsm).replaceAll('\\', '/');
+  let specifier = derived.startsWith('.') ? derived : `./${derived}`;
+  if (descriptor.fsmSpecifier !== undefined) {
+    // The declared `.js` sibling must be the build output of exactly this FSM:
+    // same directory and same basename, differing only in the extension.
+    const declared = resolve(dirname(out), descriptor.fsmSpecifier);
+    if (dirname(declared) !== dirname(fsm) || basename(declared, '.js') !== basename(fsm, extname(fsm))) {
+      throw new TypeError('fsmSpecifier must name the .js sibling of the --fsm file');
+    }
+    specifier = descriptor.fsmSpecifier;
+  }
   const code = materializeLink({ machine: module[descriptor.machineExport], descriptor,
-    fsmSpecifier: specifier.startsWith('.') ? specifier : `./${specifier}`, engine });
+    fsmSpecifier: specifier, engine });
   const temporary = `${out}.${randomUUID()}.tmp`;
   try {
     const file = await open(temporary, 'wx', 0o644);

package/slc/optimize.md

@@ -116,7 +116,10 @@ shell script are language-independent.
 
 The pass shall append one `## Optimizations` section at the end of the target
 listing every rewritten item, one bullet per item:
-`- <ITEM-ID>: <original behavior kind> → script`.
+`- <ITEM-ID>: captain → script`, where `captain` is the fixed token for the
+direct-Captain behavior kind the pass rewrites — the only kind eligible — so
+the section reads the same in every target and a consumer can match it
+exactly.
 When no item is eligible, the target shall be the source content unchanged,
 with no `## Optimizations` section.
 

package/slc/prefix-prompts.mjs

@@ -4,10 +4,10 @@
 
 // Deterministic realization of the prompt-prefix pass (slc/prefix.md): every
 // standalone relay block of an eligible item moves after its last instruction
-// line, byte-for-byte, and one `## Prefixed prompts` section at the end lists
-// the items this and every earlier application rewrote. `--keep <ITEM-ID>`
-// excludes an item the pass judged ineligible; the tool never modifies the
-// source.
+// line, byte-for-byte, and nothing records the rewrite beside the prompts; a
+// `## Prefixed prompts` section an earlier version of the pass appended is
+// removed. `--keep <ITEM-ID>` excludes an item the pass judged ineligible; the
+// tool never modifies the source.
 
 import { readFile, writeFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
@@ -16,10 +16,7 @@ import { fileURLToPath } from 'node:url';
 const HEADING = /^#{1,3}\s/;
 const ITEM_HEADING = /^###\s+([^\s]+)\s*$/;
 const PROMPT_LINE = /^>\s?(.*)$/;
-const SECTION = '## Prefixed prompts';
-const SECTION_HEADING = /^##\s+Prefixed prompts\s*$/;
-const LISTED = /^-\s+([^\s:]+):\s+relays → tail\s*$/;
-const bullet = (id) => `- ${id}: relays → tail`;
+const LEGACY_SECTION = /^##\s+Prefixed prompts\s*$/;
 
 /** Classify one prompt line by its content inside the outer blockquote marker. */
 function classify(line) {
@@ -97,9 +94,9 @@ function prefixBlockquote(quote) {
 }
 
 /**
- * Rewrite every eligible item of a GEARS package not named by `keep`.
- * Returns the rewritten text with its provenance section, or the source text
- * unchanged when no item was eligible, plus the rewritten item ids.
+ * Rewrite every eligible item of a GEARS package not named by `keep` and
+ * remove any legacy `## Prefixed prompts` section. Returns the target text —
+ * the source text itself when neither applies — and the rewritten item ids.
  */
 export function prefixPrompts(text, { keep = [] } = {}) {
   // Keep the source's own line-ending convention so untouched lines stay bytes.
@@ -130,24 +127,25 @@ export function prefixPrompts(text, { keep = [] } = {}) {
     cursor = quoteEnd;
     rewritten.push(start.id);
   }
-  if (rewritten.length === 0) return { text, rewritten };
   out.push(...lines.slice(cursor));
-  // One provenance section follows every other section, ending in one newline;
-  // it replaces every section an earlier application appended and lists, in
-  // item order, each item this or that application rewrote.
-  const listed = new Set(rewritten);
+  // A legacy section runs to the next heading; at the end of the file it
+  // takes the blank lines before it too, so the file ends as it did before
+  // the section was appended.
+  let removed = false;
   for (let index = out.length - 1; index >= 0; index--) {
-    if (!SECTION_HEADING.test(out[index])) continue;
+    if (!LEGACY_SECTION.test(out[index])) continue;
+    let start = index;
     let end = index + 1;
-    for (; end < out.length && !HEADING.test(out[end]); end++) {
-      const entry = LISTED.exec(out[end]);
-      if (entry !== null) listed.add(entry[1]);
+    while (end < out.length && !HEADING.test(out[end])) end++;
+    if (end === out.length) {
+      while (start > 0 && out[start - 1] === '') start--;
+      out.splice(start, end - start, '');
+    } else {
+      out.splice(start, end - start);
     }
-    out.splice(index, end - index);
+    removed = true;
   }
-  while (out.length > 0 && out[out.length - 1] === '') out.pop();
-  const ids = starts.map((start) => start.id).filter((id) => listed.has(id));
-  out.push('', SECTION, '', ...ids.map(bullet), '');
+  if (rewritten.length === 0 && !removed) return { text, rewritten };
   return { text: out.join(newline), rewritten };
 }
 
@@ -172,12 +170,15 @@ async function main(argv) {
       'usage: prefix-prompts.mjs --source <gears.md> --target <gears.md> [--keep <ITEM-ID>]...',
     );
   }
-  const { text, rewritten } = prefixPrompts(await readFile(resolve(source), 'utf8'), { keep });
+  const input = await readFile(resolve(source), 'utf8');
+  const { text, rewritten } = prefixPrompts(input, { keep });
   await writeFile(resolve(target), text);
   process.stdout.write(
-    rewritten.length === 0
-      ? 'no eligible item; target equals source\n'
-      : `${rewritten.join('\n')}\n`,
+    rewritten.length > 0
+      ? `${rewritten.join('\n')}\n`
+      : text === input
+        ? 'no eligible item; target equals source\n'
+        : 'no eligible item; legacy ## Prefixed prompts section removed\n',
   );
 }
 

package/slc/prefix.md

@@ -79,8 +79,8 @@ rewrite, merge, split, or drop any line.
 Source prose that places a relay after an instruction, or an instruction at
 the end of the prompt, tells [text2gears](text2gears.md) how to compose the
 prompt faithfully; it does not make the item ineligible.
-This pass overrides that composition order by design, records the override in
-its provenance section, and `--no-optimize` restores it.
+This pass overrides that composition order by design, and `--no-optimize`
+restores it.
 
 ## Rewriting
 
@@ -98,7 +98,8 @@ For each eligible item, the pass shall rewrite only the blockquote:
 - Keep the item's ID, heading, condition, acting clause, `Results:`, and any
   other metadata unchanged.
 - Preserve every other item and every non-item section byte-for-byte,
-  including an `## Optimizations` section the optimize pass appended.
+  including an `## Optimizations` section the optimize pass appended, except
+  a legacy `## Prefixed prompts` section (see [Provenance](#provenance)).
 
 Because no line changes, the target stays in the Source language and every
 authored fragment remains intact; only the order of relay blocks relative to
@@ -142,22 +143,24 @@ Results:
 
 ## Provenance
 
-The target shall end with one `## Prefixed prompts` section — after an
-`## Optimizations` section when one is present — listing every rewritten
-item, one bullet per item in item order: `- <ITEM-ID>: relays → tail`.
-A section an earlier application left in the source is replaced, and the
-items it listed stay listed.
-When no item is eligible, the target shall be the source content unchanged;
-a package the pass never rewrote carries no `## Prefixed prompts` section.
-
-The section is what lets a Source-to-GEARS fidelity checker accept the new
-order: for a listed item it requires each instruction and relay block of the
-fragments the item carries intact, blank lines inside a block included, and
-used exactly once, the instruction blocks in Source order, the relay blocks in
-Source order, and every relay after the last instruction, a relay Source joined
-directly to an instruction staying beside it with its authored boundary, a bare
-relay the prose authored free to trail, and one occurrence standing for one
-authored fragment; for any other item it requires Source order throughout.
+The pass shall record nothing beside the rewritten prompts, whose layout
+shows the rewrite.
+A `## Prefixed prompts` section an earlier version of this pass appended shall
+be removed — up to the next heading, and at the end of the file with the blank
+lines before it; when no item is eligible and no such section is present, the
+target shall be the source content unchanged.
+Re-running the pass is a no-op by layout: an item whose relays already trail
+is not eligible.
+
+A Source-to-GEARS fidelity checker therefore reads the layout from each prompt:
+it accepts an item either in Source order throughout or in the prefix-first
+layout, which requires each instruction and relay block of the fragments the
+item carries intact, blank lines inside a block included, and used exactly
+once, the instruction blocks in Source order, the relay blocks in Source order,
+and every relay after the last instruction, a relay Source joined directly to
+an instruction staying beside it with its authored boundary, a bare relay the
+prose authored free to trail, and one occurrence standing for one authored
+fragment.
 
 ## Deterministic rewriting
 
@@ -168,9 +171,8 @@ node "<definition-directory>/prefix-prompts.mjs" --source "<source.gears.md>" --
 ```
 
 It reads the source, rewrites every item eligible by the mechanical rules
-above, writes the one provenance section and the target, and prints the
-rewritten item IDs — or reports that no item was eligible and the target
-equals the source.
+above, removes a legacy `## Prefixed prompts` section, writes the target, and
+prints the rewritten item IDs — or reports that no item was eligible.
 `--keep` excludes an item the tool would otherwise rewrite.
 
 The pass shall use the tool rather than rewrite by hand:
@@ -179,8 +181,9 @@ The pass shall use the tool rather than rewrite by hand:
    instruction line, whether an instruction depends on a relay standing before
    it; that judgment is the pass's only non-mechanical step.
 2. Run the tool with `--keep` for each item so excluded.
-3. Read the target and confirm that every listed item's instructions and
-   relays are intact and that nothing else changed.
+3. Read the target and confirm that every rewritten item's instructions and
+   relays are intact and that nothing changed beyond the rewritten items and
+   the removal of a legacy `## Prefixed prompts` section.
 
 The tool writes only the declared target and never modifies the source.
 

package/slc/slc.pin-inputs.json

@@ -1,8 +1,17 @@
 {
   "schema": "sublang.slc.pin-inputs.v1",
   "closures": {
-    "gears2fsm": ["text2gears.md", "link.md", "workflow-contracts.json"],
-    "prefix": ["prefix-prompts.mjs"],
+    "text2gears": [
+      "workflow-contracts.json"
+    ],
+    "gears2fsm": [
+      "text2gears.md",
+      "link.md",
+      "workflow-contracts.json"
+    ],
+    "prefix": [
+      "prefix-prompts.mjs"
+    ],
     "link": [
       "text2gears.md",
       "gears2fsm.md",

package/slc/text2gears.md

@@ -157,13 +157,37 @@ Keep each declaration outside plain-text parentheses; explanatory symbols in
 parenthetical guidance use plain text, never separate backticks, because those
 backticks would declare extra required fields. Guidance may instead occur
 inside a field's complete annotation, including any parentheses there.
-For example, use `` `codeCommit` (new code-owned commit) `` or
-`` `codeCommit: <new code-owned commit>` ``, without backticks around code.
+For example, use `` `latestCommit` (new code-owned commit) `` or
+`` `latestCommit: <commit identity>` ``, without backticks around code.
+The commit a call itself creates is always declared as `latestCommit`, the
+canonical effect-owned property every linked runtime fills from the
+repository receipt and every terminal output projects from.
 An output property name shall match the same ASCII identifier pattern as a
 guard name: a kebab-case Source placeholder such as `<coder-output>` names the
 property `coderOutput` through the canonical kebab-token-to-camel-field mapping
 of [link](link.md), never a quoted kebab-case key, because downstream artifacts
 and calling playbooks consume these properties by name.
+A result shall declare an output property only where a consumer requires it:
+a later item's `<placeholder>`, the workflow's terminal return, or the
+workflow's declared public interface below.
+A detail the acting agent reports only within its final text — a reason, a
+summary, a list — travels in the result's verbatim final-text property and is
+not a separate judge-authored property.
+
+Where the selected pipeline supplies the
+[workflow contracts](workflow-contracts.json) catalog and the Source's basename
+is one of its `literalTargetBindings`, the compiled workflow is held to that
+builtin's declared output interface, because callers compiled against the
+catalog address it by that id: a result property whose value that interface
+returns shall take the interface's property name — `branch`, `issueSummary`,
+and `coderOutput` for `branch`; `evaluatedRevision` for the revision a clean
+review round evaluated — whether the value is semantic, presentation, or
+effect-owned, while the commit a call itself creates keeps the canonical
+`latestCommit` for the FSM to project into the interface's field.
+A Source placeholder that names such a value otherwise is an inconsistency
+between the Source and the catalog: leave the Target unwritten and report it
+as an incompatible compiler input rather than rename or invent.
+A Source outside those ids is named from its own words as above.
 
 A produced value consumed later shall have a declared producer: where any
 later item's blockquote reads a value through a `<placeholder>`, the item
@@ -172,14 +196,37 @@ whose relevant description names the produced output property, using the
 placeholder's exact identifier — this is what lets the FSM thread the value
 through typed context.
 A single-outcome producer then declares exactly one bullet naming the
-property; this consumed-output case is the sole one in which a
-single-outcome behavior carries a `Results:` label.
+property; this consumed-output case and the qualified-outcome case below are
+the two in which a single-outcome behavior carries a `Results:` label.
+The commit a call itself creates is the one exception to naming the property
+after the placeholder: its producer declares `latestCommit: <commit identity>`
+whatever placeholder a later prompt reads it through — `<code-commit>` or
+`<decide-commit>`, for instance — because the linked runtime fills that
+property from the repository receipt rather than from the player, and
+[gears2fsm](gears2fsm.md#context-and-prompts) binds the Source's placeholder
+to the retained commit.
+A placeholder the Source defines as a labelled section of another relayed
+value, naming the label that opens the section and the labels that end it —
+`<original-intent>` as the `Original intent:` section of the caller's request,
+which runs to the `Review scope:` line or to the end of the request, for
+instance — is derived, not produced: text2gears shall keep that defining
+sentence verbatim in the package introduction, or in the item's prose where the
+Source states it there, name the placeholder as the Source does, and declare no
+result property for it, because no player produces the value and
+[gears2fsm](gears2fsm.md#context-and-prompts) derives it from the relayed text.
 
 Where a later prompt relays a delegated player's whole final response as quoted context, the producer shall declare that property in the exact annotated form `` `<field>: <verbatim final text>` ``.
 The annotation makes the field runtime-owned: the adjudicator selects the result guard, while the linked runtime carries the player's canonical final text into that field instead of asking a judge to reproduce it.
 A distinct typed field extracted from that response remains judge-authored even when a later prompt quotes its exact value; quoting a field does not turn it into the player's whole final response.
 One property name shall not be annotated as verbatim in one result contract and judge-authored in another; text2gears shall choose distinct properties or report that the Source cannot be represented by the current contract.
 
+A Source statement that qualifies an outcome's evidence — what affirmatively
+supports it, what supports no outcome, such as "a progress report, status
+update, or promise of a later result supports no review outcome" — shall be
+carried in that outcome's result description, the only text the adjudicator
+reads when it selects the guard; left in the item's prose, it reaches no
+judge.
+
 Result metadata is compiler control data, not part of the acting agent's
 prompt.
 text2gears shall not put guard names, result-property schema, JSON control
@@ -194,12 +241,16 @@ Where Source restricts an initial Captain to routing, text2gears shall preserve
 only the authored question and delegation outcomes and shall not infer a
 direct-answer or terminal result merely because Captain is the acting agent.
 
-A single-outcome behavior whose output no later item consumes carries no
-`Results:` label; downstream,
+A single-outcome behavior whose output no later item consumes and whose
+outcome Source leaves unqualified carries no `Results:` label; downstream,
 [gears2fsm](gears2fsm.md#setup) gives its state the default single-outcome
 contract, so text2gears shall not invent a one-bullet `Results:` block for it.
 When a later item does consume its output, the produced-value rule above
-applies instead.
+applies instead; when Source qualifies the one outcome's evidence — what
+affirmatively supports it, what supports no outcome — the behavior carries
+exactly one `Results:` bullet naming that outcome and carrying the
+qualification, with an output property only where a consumer requires one,
+because the adjudicator reads the qualification nowhere else.
 
 When Source requires a terminal return to the caller, preserve every returned value or fact and its return condition as an explicit workflow output obligation in GEARS.
 Merely naming a value in a completion predicate or an acting result does not state that the workflow returns it.
@@ -215,10 +266,16 @@ when the answer changes its complete runtime prompt. It shall not emit a
 second item solely for "Boss answers," "after the question," or clearing the
 consumed question/reply. The FSM and linker own the same-leaf suspension,
 continuation blocks, and consumed-context cleanup.
-When such an authored result asks Boss and waits, its `Results:` description
-shall declare `question: <verbatim final text>` as an output property; the
-result name or prose saying that a question is asked is not the field
-declaration.
+Outside the decide-call-observe routing contract, an authored Boss question
+is the framework-owned `needsBossReply` outcome that
+[gears2fsm](gears2fsm.md#boss-reply-suspension) adds to every Captain- or
+player-invoking state: text2gears shall keep the question's conditions in the
+prompt and its continuation in the item's prose and shall declare no result
+for it, because a second guard for the same wait would give the adjudicator
+two equivalent outcomes.
+Only the routing contract's own `question` and `followUpQuestion` results
+declare the question, as `question: <verbatim final text>`; there, the result
+name or prose saying that a question is asked is not the field declaration.
 
 This rule is an exception to splitting by accumulated prompt content below.
 Split only when Source requires a genuinely different acting behavior after
@@ -395,6 +452,9 @@ Markdown escaping is Source syntax, not content: extraction shall resolve escape
 
 Partition items by every variable that determines prompt content — including accumulated state when the trigger alone doesn't.
 
+Conversely, do not split by trigger alone: where two or more triggers lead to one behavior with the same acting clause, prompt, and result contract — a nested call Source says a later path makes "with the same input as" an earlier path's, for instance — text2gears shall emit one item whose condition joins the triggers and shall keep each path's continuation as that item's prose.
+An item per trigger duplicates an identical prompt and multiplies the FSM's states without a content difference.
+
 ### Prune dead disjuncts
 
 Drop disjunctive branches incompatible with the rest of an item's condition or prompt.

package/src/runtime.d.ts

@@ -173,10 +173,13 @@ export type PlaybookRunResult = {
     pendingCall: PlaybookPendingCall;
 };
 export interface PlaybookPorts {
+    /** Acknowledge the durable start before work and its result before transition. */
+    recordStep?(step: PlaybookStepRecord, position?: PlaybookRuntimeSnapshot): Promise<void>;
     callPlayer(roleId: string, prompt: string, signal: AbortSignal, options: PlayerCallOptions): Promise<PlayerResult>;
     callCaptain(prompt: string, signal: AbortSignal, options: CaptainCallOptions): Promise<CaptainResult>;
     callJudge(prompt: string, signal: AbortSignal): Promise<string>;
     callPlaybook(request: PlaybookCallRequest, signal: AbortSignal): Promise<PlaybookCallStart>;
+    /** Mark question presentation with data.kind = "boss-question"; Captain relays it from pendingQuestions. */
     emitStatus(message: string, data?: unknown): Promise<void>;
     emitTelemetry(event: {
         topic: string;
@@ -275,6 +278,8 @@ export interface PlaybookEffectBoundary {
     readonly baseline: PlaybookRepositoryObservation;
     readonly after?: PlaybookRepositoryObservation;
     readonly physicalReceipt?: PlaybookRepositoryReceipt;
+    /** A later exact restoration permits replay of this standalone read-only call. */
+    readonly restored?: PlaybookRepositoryObservation;
     readonly finalText?: string;
     readonly semanticCandidate?: JsonValue;
     readonly initialSemanticCandidate?: JsonValue;
@@ -286,7 +291,7 @@ export interface PlaybookEffectBoundary {
     readonly logicalOperationId?: string;
 }
 /** One physical boundary before the host assigns attempt and sequence data. */
-export type PlaybookEffectBoundaryStart = Omit<PlaybookEffectBoundary, 'sequence' | 'attemptId' | 'attemptNumber' | 'after' | 'physicalReceipt' | 'finalText' | 'semanticCandidate' | 'initialSemanticCandidate'>;
+export type PlaybookEffectBoundaryStart = Omit<PlaybookEffectBoundary, 'sequence' | 'attemptId' | 'attemptNumber' | 'after' | 'physicalReceipt' | 'restored' | 'finalText' | 'semanticCandidate' | 'initialSemanticCandidate'>;
 /** One deferred logical operation spanning its ordered physical boundaries. */
 export interface PlaybookEffectLogicalOperation {
     readonly sequence: number;
@@ -388,8 +393,26 @@ export interface PlaybookRuntimeSnapshot {
         readonly boundaryPrefix: number;
         readonly attemptId: string | null;
     };
+    /** Interrupted invocation, captured before its external call (DR-069). */
+    recoveryCheckpoint?: PlaybookRecoveryCheckpoint;
     suspendedCall?: PlaybookSuspendedCall;
 }
+export interface PlaybookRecoveryCheckpoint {
+    readonly id?: string;
+    readonly stateId: string;
+    readonly prompt: string;
+    readonly machine: JsonValue;
+    readonly boundaryPrefix: number;
+    /** Completed actor output supplied by the execution journal on restore. */
+    readonly result?: JsonValue;
+    readonly delivered?: true;
+}
+export interface PlaybookStepRecord {
+    readonly id: string;
+    readonly kind: 'player' | 'captain' | 'script';
+    readonly stateId: string;
+    readonly result?: JsonValue;
+}
 export type PlaybookControlStanding = 'ready' | 'no-op' | 'blocked';
 export type PlaybookControlActionReason = 'receipt-complete';
 export interface PlaybookControlAction {
@@ -398,6 +421,20 @@ export interface PlaybookControlAction {
     standing?: PlaybookControlStanding;
     reason?: PlaybookControlActionReason;
 }
+export interface PlaybookRecoveryOffer {
+    prompt: string;
+    description?: string;
+    /** Runtime-owned conditions to satisfy; these never authorize task completion. */
+    preparation?: string;
+    /** Saved observations and result choices for diagnosing the stopped step. */
+    evidence?: JsonValue;
+    continuation: {
+        kind: 'reply';
+    } | {
+        kind: 'runtime';
+        actionId: string;
+    };
+}
 export interface PlaybookControlView {
     state: PlaybookState;
     stateDescription?: string;
@@ -405,6 +442,8 @@ export interface PlaybookControlView {
     pendingQuestions: readonly PlaybookPendingBossQuestion[];
     lastError?: NormalizedError;
     actions: readonly PlaybookControlAction[];
+    /** Context only for an explicitly authorized Captain preparation call. */
+    recovery?: PlaybookRecoveryOffer;
 }
 export type PlaybookControlReceipt = {
     disposition: 'rejected';
@@ -415,13 +454,16 @@ export type PlaybookControlReceipt = {
 } | {
     disposition: 'failed';
     error: NormalizedError;
+    run?: PlaybookRunResult;
 };
 export interface PlaybookRetainedGenerationMetadata {
     readonly unfinishedFinalStateIds: readonly string[];
 }
 export interface PlaybookRuntime {
     init(session: PlaybookSession): Promise<void>;
-    exportSnapshot?(): PlaybookRuntimeSnapshot | undefined;
+    exportSnapshot?(checkpoint?: {
+        child?: PlaybookPendingCall;
+    }): PlaybookRuntimeSnapshot | undefined;
     restore?(session: PlaybookSession, snapshot: PlaybookRuntimeSnapshot): Promise<void>;
     adopt?(session: PlaybookSession, snapshot: PlaybookRuntimeSnapshot, context: PlaybookAdoptionContext): Promise<void>;
     readonly retainedGenerationMetadata?: PlaybookRetainedGenerationMetadata;
@@ -447,6 +489,8 @@ export interface PlaybookRuntime {
     handleBossInput(turn: {
         text: string;
         signal: AbortSignal;
+        /** Called synchronously just before accepting the event, at most once. */
+        onAccepted?: () => void;
     }): Promise<PlaybookRunResult>;
     resumePlaybookCall(input: {
         callId: string;