@sublang/playbook 15.0.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

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+
+// 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 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';
+import { fileURLToPath } from 'node:url';
+
+const HEADING = /^#{1,3}\s/;
+const ITEM_HEADING = /^###\s+([^\s]+)\s*$/;
+const PROMPT_LINE = /^>\s?(.*)$/;
+const LEGACY_SECTION = /^##\s+Prefixed prompts\s*$/;
+
+/** Classify one prompt line by its content inside the outer blockquote marker. */
+function classify(line) {
+  const inner = PROMPT_LINE.exec(line)[1];
+  if (inner === '') return 'blank';
+  return inner.startsWith('>') ? 'relay' : 'instruction';
+}
+
+/**
+ * Rewrite one blockquote (its raw `> …` file lines). Returns the new lines, or
+ * null when no relay block precedes an instruction line.
+ */
+function prefixBlockquote(quote) {
+  const kinds = quote.map(classify);
+  // A relay block is a maximal run of relay lines bounded by blank lines or
+  // the blockquote edges; a relay line adjacent to an instruction line is
+  // authored content of that instruction and stays with it.
+  const inBlock = new Array(quote.length).fill(false);
+  for (let start = 0; start < quote.length; ) {
+    if (kinds[start] !== 'relay') {
+      start++;
+      continue;
+    }
+    let end = start;
+    while (end < quote.length && kinds[end] === 'relay') end++;
+    const boundedBefore = start === 0 || kinds[start - 1] === 'blank';
+    const boundedAfter = end === quote.length || kinds[end] === 'blank';
+    if (boundedBefore && boundedAfter) inBlock.fill(true, start, end);
+    start = end;
+  }
+  const firstBlock = inBlock.indexOf(true);
+  if (firstBlock === -1) return null;
+  const lastInstruction = Math.max(
+    ...kinds.map((kind, index) =>
+      kind === 'blank' || inBlock[index] ? -1 : index,
+    ),
+  );
+  if (lastInstruction < firstBlock) return null; // relays already trail
+
+  // Instruction lines keep their order and their authored blank lines; a
+  // removed block takes the blank lines bounding it and leaves the first of
+  // them where it separated two remaining lines, and none leads or trails the
+  // region.
+  const removed = [...inBlock];
+  inBlock.forEach((inside, index) => {
+    if (!inside) return;
+    for (let at = index - 1; at >= 0 && kinds[at] === 'blank'; at--) removed[at] = true;
+    for (let at = index + 1; at < quote.length && kinds[at] === 'blank'; at++) removed[at] = true;
+  });
+  const statics = [];
+  let separator;
+  for (let index = 0; index < quote.length; index++) {
+    if (removed[index]) {
+      separator ??= quote[index];
+      continue;
+    }
+    if (statics.length === 0 && kinds[index] === 'blank') continue;
+    if (separator !== undefined && statics.length > 0) statics.push(separator);
+    separator = undefined;
+    statics.push(quote[index]);
+  }
+  while (statics.length > 0 && classify(statics[statics.length - 1]) === 'blank') {
+    statics.pop();
+  }
+  const blocks = [];
+  for (let index = 0; index < quote.length; index++) {
+    if (!inBlock[index]) continue;
+    if (index === 0 || !inBlock[index - 1]) blocks.push([]);
+    blocks[blocks.length - 1].push(quote[index]);
+  }
+  const relays = blocks.flatMap((block, index) =>
+    index === 0 ? block : ['>', ...block],
+  );
+  return [...statics, '>', ...relays];
+}
+
+/**
+ * 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.
+  const newline = text.includes('\r\n') ? '\r\n' : '\n';
+  const lines = text.split(/\r?\n/);
+  const starts = [];
+  lines.forEach((line, index) => {
+    const match = ITEM_HEADING.exec(line);
+    if (match !== null) starts.push({ index, id: match[1] });
+  });
+  const out = [];
+  let cursor = 0;
+  const rewritten = [];
+  for (const start of starts) {
+    let end = start.index + 1;
+    while (end < lines.length && !HEADING.test(lines[end])) end++;
+    let quoteStart = start.index + 1;
+    while (quoteStart < end && !PROMPT_LINE.test(lines[quoteStart])) quoteStart++;
+    if (quoteStart === end) continue;
+    let quoteEnd = quoteStart;
+    while (quoteEnd < end && PROMPT_LINE.test(lines[quoteEnd])) quoteEnd++;
+    // A script item's blockquote is shell text, not a prompt (optimize.md).
+    const acting = lines.slice(start.index + 1, quoteStart).join(' ');
+    if (/\bCaptain shall run:/.test(acting) || keep.includes(start.id)) continue;
+    const replaced = prefixBlockquote(lines.slice(quoteStart, quoteEnd));
+    if (replaced === null) continue;
+    out.push(...lines.slice(cursor, quoteStart), ...replaced);
+    cursor = quoteEnd;
+    rewritten.push(start.id);
+  }
+  out.push(...lines.slice(cursor));
+  // 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 (!LEGACY_SECTION.test(out[index])) continue;
+    let start = index;
+    let end = index + 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);
+    }
+    removed = true;
+  }
+  if (rewritten.length === 0 && !removed) return { text, rewritten };
+  return { text: out.join(newline), rewritten };
+}
+
+async function main(argv) {
+  let source;
+  let target;
+  const keep = [];
+  for (let index = 0; index < argv.length; index++) {
+    const flag = argv[index];
+    const value = argv[index + 1];
+    if (value === undefined || value.startsWith('--')) {
+      throw new Error(`${flag} needs a value`);
+    }
+    if (flag === '--source') source = value;
+    else if (flag === '--target') target = value;
+    else if (flag === '--keep') keep.push(value);
+    else throw new Error(`unknown argument ${flag}`);
+    index++;
+  }
+  if (source === undefined || target === undefined) {
+    throw new Error(
+      'usage: prefix-prompts.mjs --source <gears.md> --target <gears.md> [--keep <ITEM-ID>]...',
+    );
+  }
+  const input = await readFile(resolve(source), 'utf8');
+  const { text, rewritten } = prefixPrompts(input, { keep });
+  await writeFile(resolve(target), text);
+  process.stdout.write(
+    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',
+  );
+}
+
+const invokedPath = process.argv[1] === undefined ? undefined : resolve(process.argv[1]);
+if (invokedPath === fileURLToPath(import.meta.url)) {
+  main(process.argv.slice(2)).catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+  });
+}