@sublang/playbook 15.1.0 → 16.0.0

package/slc/gears2fsm.md

@@ -141,9 +141,11 @@ generic Captain forms, wire `<boss-intent>` from `bossIntent`,
 `remainingPlan`, and `<completed-call-results>` from
 `completedCallResults`. Other non-identity placeholders shall retain the
 semantic typed field established by Source (for example `<#>` from
-`irNumber`). Leaving an ordinary runtime-value placeholder literal, replacing
-it with an empty default because its field was omitted, or making the linker
-recover it from untyped context is malformed.
+`irNumber`); a created-commit or labelled-section placeholder binds as
+[Context and prompts](#context-and-prompts) states. Leaving an ordinary
+runtime-value placeholder literal, replacing it with an empty default because
+its field was omitted, or making the linker recover it from untyped context is
+malformed.
 The corresponding `invoke.input` object shall include that field beside `prompt`; storing it only in machine context does not satisfy the actor-input contract.
 When Source declares a placeholder as the current identity of a local acting
 role, preserve the placeholder literal in the FSM prompt and do not add any
@@ -610,6 +612,37 @@ or remove remaining entries as evidence arrives, but it cannot grow or retain
 the same-length plan indefinitely; the initial finite array therefore bounds
 the number of sequential child calls without an arbitrary runtime call limit.
 
+A placeholder that reads the commit an earlier call created — `<code-commit>`,
+`<decide-commit>` — binds to a typed context field named by its canonical
+mapping, assigned from that call's accepted `latestCommit`, the effect-owned
+property the runtime fills from the repository receipt
+([text2gears](text2gears.md#result-contracts)); the actor input carries the
+field beside the prompt like any other relayed value.
+A placeholder the GEARS defines as a labelled section of another relayed
+text binds to a typed context field named by its canonical mapping. The
+definition names 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. The
+machine derives the field deterministically in the entry action or transition
+that stores the text and again in every action that replaces it, such as a
+fresh entry directive or an interrupt that restarts with new text:
+
+- the text as read is the text itself, except that where every non-blank line
+  begins with `>`, each line is read without that marker and one optional space
+  after it, the literal quote layer a quoted relay adds;
+- the section is the lines of the text as read from the first line that
+  begins with the opening label, the label removed, through the line before the
+  first later line that begins with an ending label, or through the last line,
+  with the result trimmed; a line that merely looks labelled, such as `Note:`
+  or `Constraints:`, stays in the section;
+- where no line begins with the opening label, or the section is empty once
+  trimmed — its label directly followed by an ending label or by the end of
+  the text — the field is the whole text as read, trimmed, so the request is
+  never lost.
+
+The derived field is ordinary context that actor inputs relay, never a player
+or judge output.
+
 Prompts shall pass only the **specific extracted fields** the player needs.
 The compiler shall not dump `JSON.stringify(lastResult)` or any opaque blob: it leaks internal `guard` strings, wastes tokens, and confuses the LLM.
 
@@ -663,6 +696,26 @@ The compiler shall update or reset those source-owned facts only at their actual
 Transitions shall be self-driving when source items define the next obligation.
 Routing to an idle hub is for recovery, unrecoverable Boss input, or one-shot entry events — not the happy path.
 
+Where an artifact-schema-3 delegated-player state's outcomes are governed by the
+linked runtime ([link.md "Captain adjudication"](link.md#captain-adjudication)),
+every accepted `onDone` arm — each arm that routes a declared outcome, not the
+malformed-output fallback — shall carry, first among its actions, the
+root-machine action
+`{ type: 'playbook.acceptedOutcome', params: { source: '<stateId>', target: '<target stateId>', acceptedOutcome: '<guard>' } }`,
+with the setup's `actions` declaring `'playbook.acceptedOutcome'` as a no-op
+that types those three string params.
+`target` names the state the next public snapshot shows for the arm: the arm's
+own target, or the parallel parent's `onDone` target where the arm's target is a
+region's final leaf that completes that parent, because the machine leaves that
+leaf before the snapshot; an arm that completes the join only when every
+sibling region is already final therefore splits into two arms guarded on that
+condition, each naming the state it reaches.
+The linked runtime retains the marker until the next public snapshot confirms
+`source` in the prior snapshot and `target` in the new one, and only then
+publishes the outcome's accepted trace and `→ <acceptedOutcome>` status; an arm
+without the marker accepts its outcome silently, and the host counts none of the
+work it saved.
+
 ### Auto-advance on approval
 
 A review/approval state's success outcome shall **target the next workflow step**, not idle back to a hub.
@@ -811,6 +864,12 @@ Where several questions are pending, the classifier prompt and event shall
 require `questionId` and shall reject an omitted or unknown id without moving
 the FSM.
 
+Every exit from a Captain- or player-invoking state other than into its own
+Boss-reply wait — an accepted outcome, the malformed-output fallback, an actor
+error — and every non-reply exit from a wait shall clear that state's pending
+question and reply context, so a call that fails after resuming leaves no
+stale question for the next turn's classifier to offer.
+
 The scalar `awaitBossReply` state and every local branch wait are quiescent for
 the runtime drive boundary.
 They shall allow a fresh root entry event or interrupt to abandon the relevant
@@ -882,6 +941,16 @@ Where Source declares a JSON-safe terminal result, the setup types shall
 declare that output and the root machine shall derive it from typed context
 through XState's machine `output` function. A final-state transition alone does
 not satisfy a declared output contract.
+Where the selected pipeline supplies the
+[workflow contracts](workflow-contracts.json) catalog and the compiled Source's
+basename is one of its `literalTargetBindings`, the declared terminal output
+shall be exactly that builtin's public interface — its variants, `status`
+constants, property names, and requiredness — derived from typed context,
+because callers compiled against the catalog consume it by those names; an
+authored outcome the interface cannot express is an inconsistency between the
+Source and the catalog, reported as an incompatible compiler input under
+[Nested playbook calls](#nested-playbook-calls) rather than expressed by an
+invented or renamed outcome.
 Fields that Source requires in every terminal output shall be required in the
 TypeScript output type. In particular, a declared `{ response }` result shall
 compile as `{ response: string }`, not `{ response?: string }`; reaching the

package/slc/link.md

@@ -38,15 +38,20 @@ The link compiler shall not modify the FSM artifact and shall not re-derive Capt
 
 ## Optional deterministic materialization
 
-For an ordinary flat workflow using only `player` and `script` actors,
-the supported prompt profile below, shared remaining strategies, and primitive configured options, the linker may
+For an ordinary workflow using only `player` and `script` actors — flat, or
+with root parallel groups of the [Parallel groups](gears2fsm.md#parallel-groups)
+shape — the supported prompt profile below, shared remaining strategies, and primitive configured options, the linker may
 use the adjacent `materialize-link.mjs` tool to emit the thin module.
 The complete definition below remains binding; the tool replaces repetitive
 module generation, not semantic analysis or emitted conformance verification.
 Read the actual FSM and supply every erased or authored contract exactly.
 Do not use `flat-defaults` or `flat-quoted-relays` when another custom composer, classifier, required-field
 extractor, session-derived input mapping, controller strategy, nested call,
-parallel state, or compound state is needed.
+or compound state other than such a parallel group is needed.
+Despite their names, every profile accepts those parallel groups: the tool
+takes each region working leaf's role and label under its stable state id
+like any other player state, declares nothing further, and leaves the
+compiled shape to the factory preflight, which rejects any other form.
 
 Invoke the tool with the actual definition directory, source FSM, and declared
 target; supply a JSON descriptor on standard input:
@@ -101,6 +106,12 @@ session-derived input values are outside this profile; do not widen their
 contracts to an unconstrained primitive.
 The tool adds optional string `cwd` for script-bearing machines; it does not
 put `cwd` in FSM input unless the descriptor explicitly maps it.
+When the linked module is part of a package that compiles and ships
+JavaScript siblings, supply the optional `fsmSpecifier` — the `.js` sibling
+the build emits for the source FSM, such as `./code.fsm.js`, in the same
+directory and with the same basename — so the emitted import satisfies the
+NodeNext rule under Output; omit it for a source-only host, where the tool
+derives the specifier from the `--fsm` path.
 An explicit `entryEvent: null` selects the shared classifier only where this
 definition permits no deterministic entry; it does not relax entry rules.
 `bossEvents` retains the exact additional erased event fields, source ownership,
@@ -125,8 +136,9 @@ correct the identified problem before treating linking as successful.
 
 ### Experimental labelled-string and nested-call profile
 
-`flat-labelled-relays` is an unmeasured candidate for flat single-region
-machines with delegated players, scripts, and nested `playbook` calls. It
+`flat-labelled-relays` is an unmeasured candidate for machines with flat
+root states or root parallel groups of that shape, whose delegated players,
+scripts, and nested `playbook` calls it supports. It
 requires the installed shared `composePlayerContinuation` API. It leaves
 nested input composition, child targets, result guards, recovery, and terminal
 semantics in the unchanged FSM; the shared factory provides the nested bridge.
@@ -154,8 +166,8 @@ source tokens. Undeclared empty relay lines retain their authored text.
 The emitted verification composer has the same identity and optional third
 resume arguments as the runtime; the shared helper owns fresh/resumed Q&A.
 Structured rendering, custom classifiers/extractors/controllers, direct
-Captain actors, compound/parallel topology, and constrained/nonprimitive
-options remain unsupported. Source-derived metadata and all existing
+Captain actors, compound topology other than such a parallel group, and
+constrained/nonprimitive options remain unsupported. Source-derived metadata and all existing
 conformance checks remain mandatory. This profile changes no runtime bridge,
 workflow semantics, or measured performance claim.
 
@@ -1239,7 +1251,7 @@ undeclared extra key, so hidden adjudication cannot replace, paraphrase, or
 decorate prose Boss already saw.
 For an artifact-schema-3 governed delegated-player call, the shared engine
 shall instead use one semantic reconciler for both the default linked runtime
-and any bespoke linked runtime that adopts schema `3`.
+and any linked machinery of an artifact's own that adopts schema `3`.
 That reconciler shall retain the validated player's exact non-empty
 `finalText` as opaque presentation evidence, let the hidden adjudicator read
 it only as semantic evidence, and require the adjudicator's detached
@@ -1257,8 +1269,8 @@ authored placeholder or guidance, with every presentation-, effect-, or
 runtime-owned field named as runtime-supplied to omit — so the judge is never asked for a
 field it does not own; the artifact's description text stays unchanged.
 The shared engine shall export that rendering as `renderGovernedOutcomeContract`
-on `@sublang/playbook/xstate-runtime`, and a bespoke linked runtime shall
-render its judge prompt through it rather than restate the contract.
+on `@sublang/playbook/xstate-runtime`, and linked machinery of an artifact's
+own shall render its judge prompt through it rather than restate the contract.
 The reconciler shall construct the complete actor output rather than accept a
 cross-authority object from the judge: every presentation-owned payload field
 shall receive the canonical `finalText.trim()` value; every effect-owned
@@ -1960,9 +1972,11 @@ A linked runtime may implement the optional adoption capability of
 initialization path distinct from `init` and same-engagement `restore`.
 Adoption may bind a retained generation to a fresh valid `PlaybookSession`
 identity. Every runtime the shared `createXStatePlaybookRuntime` factory
-constructs implements `adopt`, regardless of whether the artifact supplies
-retained-generation classification metadata; a bespoke runtime may omit it,
-and hosts feature-detect the capability by member presence.
+constructs for a flat machine implements `adopt`, regardless of whether the
+artifact supplies retained-generation classification metadata; one it
+constructs for a machine that declares a parallel state omits it, as linked
+machinery of an artifact's own may, and hosts feature-detect the capability
+by member presence.
 
 Before actor construction or any player-session-store, port, trace, status,
 or telemetry effect, `adopt` shall validate and detach the target session, the
@@ -2053,9 +2067,9 @@ and detached from that declaration. Absence means the runtime contributes no
 retained generation; presence supplies only terminal classification metadata
 and does not itself supply the adoption operation.
 Every runtime the shared `createXStatePlaybookRuntime` factory constructs from
-a supplied `unfinishedFinalStateIds` spec member shall expose the marker; a
-bespoke runtime opts into classification only by implementing the public member
-itself.
+a supplied `unfinishedFinalStateIds` spec member shall expose the marker;
+linked machinery of an artifact's own opts into classification only by
+implementing the public member itself.
 
 ## Control surface (optional)
 
@@ -2387,14 +2401,19 @@ Every linked artifact shall emit an `unfinishedFinalStateIds` set beside its res
 The set shall contain exactly the stable ids of root `type: 'final'` states whose terminal outcomes leave the procedure unfinished, and shall be explicitly empty when no terminal outcome does.
 The linker shall not infer the set from a state description, opaque output, or procedure prose.
 The linker shall reject a declared id that does not name a root final state, and the shared factory shall independently reject it at construction before runtime effects.
-For a factory-backed artifact the set is a `spec` member; a bespoke artifact shall retain equivalent linked metadata, and the artifact declaration is not itself the public runtime retention marker or an adoption capability.
-For an FSM that declares no `type: 'parallel'` state — necessarily flat
-under [gears2fsm.md](gears2fsm.md)'s one-state-per-item mapping — it shall
+For a factory-backed artifact the set is a `spec` member; linked machinery of an artifact's own shall retain equivalent linked metadata, and the artifact declaration is not itself the public runtime retention marker or an adoption capability.
+For every FSM [gears2fsm.md](gears2fsm.md) produces — flat under its
+one-state-per-item mapping, or carrying root parallel groups of its
+[Parallel groups](gears2fsm.md#parallel-groups) shape — the linker shall
 emit the thin shared-factory module defined below.
-For an FSM that declares a parallel state, it shall emit bespoke linked
-machinery satisfying this document's runtime contract and shall not invoke
-`createXStatePlaybookRuntime`, whose supported domain is flat single-region
-FSMs under [DR-019](../specs/decisions/019-shared-linked-runtime-factory.md).
+The shared factory interprets such a parallel group through its parallel
+profile under [DR-067](../specs/decisions/067-parallel-proposals-through-the-shared-factory.md), deriving the regions, their leaves, and the
+cohort of working leaves from the FSM and its exported `concurrentRoleSets`,
+so the emitted module declares nothing further for it; bespoke linked
+machinery is no longer the prescribed output for any such FSM.
+Linked machinery of an artifact's own that satisfies this document's runtime
+contract remains a valid implementation for an artifact outside this package
+and declares the `bespoke` registry profile below, so hosts keep accepting it.
 The FSM-interpreter machinery — actor wiring, boundary tracing, Boss-event
 mapping, adjudication, script execution, nested-playbook bridging, session
 lifecycle, abort handling, and the optional parked-session snapshot and
@@ -2510,8 +2529,9 @@ The thin emitted module:
   error.
   `NO_ACTION` and `BOSS_REPLY` are runtime-owned event types the factory
   supplies itself — `NO_ACTION` as exactly `{ type: 'NO_ACTION' }`, and
-  `BOSS_REPLY` as an optional judge-selected `questionId` plus the exact-text
-  `answer` the runtime attaches. `bossEvents` shall carry no entry for either
+  `BOSS_REPLY` as a judge-selected `questionId` — optional while one question
+  is pending and required, from the pending ids, while several are — plus the
+  exact-text `answer` the runtime attaches. `bossEvents` shall carry no entry for either
   type; supplying one is a construction error, so a linker that judges a
   runtime-owned arm to have lost payload detail under erasure shall report
   that gap rather than emit the entry.
@@ -2553,8 +2573,11 @@ The thin emitted module:
   host-construction boundary's setup diagnostic.
 - Exposes, under an `_internal` export, the pure helpers verification
   needs — at least the prompt composers its own machine uses, which may
-  re-export the shared defaults when the spec does not override composition —
-  so compilation-correctness tests can exercise composition without a host.
+  re-export the shared defaults when the spec does not override composition,
+  and the `VERBATIM_PAYLOAD_FIELDS` and `UNFINISHED_FINAL_STATE_IDS` sets the
+  spec declares, which the linked-ownership check reads back — so
+  compilation-correctness tests can exercise composition and ownership
+  without a host.
   A playbook that calls players exposes `composePlayerPrompt`; a playbook
   whose states make direct-Captain calls exposes `composeCaptainPrompt`. A
   controller playbook that calls no players exposes no player composer:

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",