@sublang/playbook 13.2.0 → 14.0.0

package/slc/gears2fsm.md

@@ -54,8 +54,10 @@ inference. Helpers that construct transition arrays shall preserve guard,
 action, and target literals with `as const`, `satisfies`, or typed action/guard
 functions rather than widening registered names to plain `string`.
 
-The artifact shall not import a runner or bake in concrete actor
-implementations. Each actor placeholder shall fail explicitly (for example,
+The artifact shall not bind or construct a runner or bake in concrete actor
+implementations. A named stateless public boundary validator is permitted;
+importing it shall not construct a runtime, bind host capabilities, or call ports.
+Each actor placeholder shall fail explicitly (for example,
 throw `'captain actor must be provided by the runner'`).
 Where the Source artifact begins with an SPDX comment block, the generated
 artifact shall preserve its license and copyright text before the imports
@@ -83,7 +85,15 @@ comment delimiters into a TypeScript target.
 - `stateId`: the stable id of the invoking working leaf;
 - `sourceItem`: the GEARS item ID this state realizes;
 - `command`: the script item's blockquote text, verbatim after Markdown
-  unescaping;
+  unescaping, with every runtime-value placeholder it carries bound from typed
+  machine context — a script has no prose contract to carry the field
+  separately, and the provided actor executes `command` verbatim.
+  A bound value is data, never syntax: the placeholder occupies a
+  single-quoted shell word, and binding replaces that whole word — quotes
+  included — with the value encoded as its own single-quoted literal, each
+  embedded `'` written `'\''`. Interpolating a value into double-quoted or
+  unquoted command text is malformed, because a retained value is reported
+  text that would otherwise expand or run as shell syntax;
 - `result`: a record whose keys are the item's two declared guard names, first
   the zero-exit guard, then the nonzero-exit guard.
 
@@ -119,19 +129,28 @@ Nested-playbook output, completed-result evidence, plans, context, and machine
 output shall use that readonly type rather than a mutable array/record
 near-duplicate. The linker shall not cast or copy around a variance mismatch.
 
-Every runtime-value placeholder established by Source in a direct-Captain or
-delegated-player prompt shall be backed by a typed actor-input field populated
-from typed machine context, so the linker can substitute it with the exact
-runtime value. Angle-bracketed metavariables quoted inside domain instructions
-(for example the literal `<model>` in a commit-message format) remain ordinary
-prompt text and are not runtime-value placeholders. For the generic Captain
-forms, wire `<boss-intent>` from `bossIntent`,
+Except for a Source-declared local-role prompt-identity placeholder, every
+runtime-value placeholder established by Source in a direct-Captain or
+delegated-player prompt shall be backed by a typed ordinary actor-input field
+populated from typed machine context, so the linker can substitute it with the
+exact runtime value. Angle-bracketed metavariables quoted inside domain
+instructions (for example the literal `<model>` in a commit-message format)
+remain ordinary prompt text and are not runtime-value placeholders. For the
+generic Captain forms, wire `<boss-intent>` from `bossIntent`,
 `<enabled-playbooks>` from `enabledPlaybooks`, `<remaining-plan>` from
 `remainingPlan`, and `<completed-call-results>` from
-`completedCallResults`. Other placeholders shall retain the semantic typed
-field established by Source (for example `<#>` from `irNumber`). Leaving a
-placeholder literal, replacing it with an empty default because its field was
-omitted, or making the linker recover it from untyped context is malformed.
+`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.
+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
+identity-value field to machine input, runtime options, machine context, or
+actor input, required or optional. The linker shall resolve the placeholder at
+prompt-composition time by calling the invocation-scoped
+`promptIdentity(roleId)` lookup for the declared local role identified by Source.
 The sole blockquote placeholder of a dynamic nested-playbook item is instead
 the child `textContext` field specified in §Nested playbook calls.
 
@@ -261,14 +280,16 @@ Each state shall declare:
 
 The source item ID shall live in `invoke.input.sourceItem`, not in a comment — this keeps the GEARS-to-state mapping machine-readable.
 
+Public `meta.playbook` state metadata belongs only to nodes declared under `states`; the machine root shall omit `meta.playbook`, while its XState `id`, description, and metadata outside that namespace remain unrestricted.
 Outside a parallel group's regions, a state's `meta.playbook.stateId` shall equal its state key — the one identity a factory-backed linked runtime indexes by.
 A delegated state's `invoke.input.role` shall match the canonical lowercase id of its source item's named role.
 A direct Captain state shall not invent a `Captain` role binding.
 
-Every invoking working leaf — sequential or parallel, whatever its actor
-kind — shall carry the tag `playbook.busy`: the shared quiescence helper
-derives busyness strictly from active-state tags, so an untagged working leaf
-reads as quiescent while its call is still in flight.
+Every direct-Captain, delegated-player, or script working leaf — sequential
+or parallel — shall carry the tag `playbook.busy`: the shared quiescence
+helper derives busyness strictly from active-state tags, so an untagged
+Captain, player, or script leaf reads as quiescent while its call is still in
+flight.
 
 The machine's initial state shall be a quiescent idle hub (no `invoke`) — typically `ready` — that accepts the Boss entry events and carries the `playbook.parked` tag because it can return control to Boss.
 Captain- and player-invoking work begins only on a Boss-originated event, so
@@ -315,7 +336,12 @@ An item that prompts or relays to a named role shall map to exactly one `player`
 A nested-call item shall map to exactly one `playbook` invocation.
 A script item (`Captain shall run:`) shall map to
 exactly one `script` invocation whose `input.command` carries the blockquote
-verbatim and whose `result` preserves the item's two guards in declared order.
+with its runtime-value placeholders substituted, and whose `result` preserves
+the item's two guards in declared order.
+Where the substituted value is absent, the compiled input shall keep the
+placeholder literal rather than an empty default, so the command compares
+against text no output can equal and the step refuses instead of acting on an
+unbound target.
 The compiler shall not infer one actor kind from a
 runtime player name or encode Captain as a player.
 A script state is not agent-invoking: the compiler shall not add
@@ -369,6 +395,28 @@ the sibling invocations automatically.
 
 ## Nested playbook calls
 
+The independently packaged [workflow contracts](workflow-contracts.json) describe
+only the public outputs of builtin dependencies from `@sublang/playbook`.
+This pipeline adopts the catalog's `literalTargetBindings` as its default
+nested-target namespace. An explicit Source or supplied compiler-dependency
+binding overrides a default and requires the replacement's own public interface.
+Runtime hosts shall honor the compiled dependency bindings as external ABIs.
+When the call target is bound to one of those packaged builtins, read its exact
+output interface before compiling a Source-authored acceptance or relay
+predicate; do not infer field names from the desired meaning or inspect the
+callee implementation. A local basename or a custom target reusing an id does
+not establish that dependency binding.
+The shared bridge correlates the invocation and its supplied input scope;
+the builtin REVIEW result attests to that scope with `noUnsettledFindings: true`
+and `evaluatedRevision`. Do not invent `reviewedCommit` or require the final
+evaluated revision to equal the caller's earlier commit, since REVIEW may make
+its own fixes. Retain every Source-authored predicate on the declared fields.
+If an output-dependent call needs an external interface that is unavailable or
+inconsistent with the declared dependency, report `BLOCKED` with that missing
+compiler input rather than inventing fields or asking the source author to
+repair sufficient domain behavior. Missing or contradictory authored behavior
+still requires the host's source-clarification protocol.
+
 An item whose behavior is a literal or dynamic
 `Captain shall call playbook ...:` shall compile to a state that invokes a
 typed `playbook` actor, not the `captain` or `player` actor.
@@ -416,8 +464,13 @@ parsing the `invoke.input` function's source. The evaluated `playbookId` and
 corresponding metadata property. Literal calls need not carry these dynamic
 metadata properties and retain their existing behavior.
 
-The call state shall carry tag `playbook.suspended` and shall route
-`invoke.onDone` from child output and `invoke.onError` from child failure.
+The call state shall carry tag `playbook.suspended`.
+The call state and every ancestor state, including the machine root, shall omit
+tag `playbook.busy`.
+An independently active sibling Captain, player, or script leaf may carry
+`playbook.busy`.
+The call state shall route `invoke.onDone` from child output and
+`invoke.onError` from child failure.
 The child call shall remain state-scoped: leaving the call state stops the
 invoked actor and aborts the host call through XState's invocation signal
 [[2]].
@@ -447,9 +500,12 @@ result, the error action shall inspect whether its status was `aborted` or
 `error`; it shall not collapse both into an invented success/failure enum. The
 FSM may inspect that public structural data without importing the runner or
 constructing runtime call identities.
-Because a failure terminal reaches `onError`, `onDone` alone proves the child
-succeeded: a caller shall not decide success by inspecting the callee's output
-fields, and shall read those fields only where its own Source relays them.
+`onDone` proves successful bridge delivery without a declared child failure;
+it does not establish every caller-owned domain condition. The caller shall
+enforce its own explicit Source-authored acceptance or relay predicates on
+the delivered output before continuing, without inventing predicates from
+callee implementation details or overriding the child's compiled terminal
+kind with output fields.
 For a workflow that reassesses child results, use a typed JSON-safe record such
 as `{ playbookId, status: 'ok', output }` on `onDone` and
 `{ playbookId, status: 'aborted' | 'error', error }` on `onError`, with a
@@ -466,36 +522,47 @@ been created. On success, persist only `event.output`, which is the actual child
 machine output returned by the bridge, not a runtime call-result envelope.
 When that optional output is absent, omit the `output` property from the
 completed-result record rather than storing `undefined`.
-The outer trusted error is an actual `Error` instance and therefore is not a
-plain JSON object. The structural guard shall inspect its public `.result`
-property directly, then validate only that nested result before sanitizing it;
-it shall not require the outer error itself to pass a plain-object/JSON guard.
-Validation of that nested public result includes its status-specific required
-members and target identity: `playbookId` shall equal the current selected
-target, an `error` result shall carry a normalized error, and every optional
-member that is present shall have the public contract's declared shape. A
-look-alike such as `{ status: 'error' }` is malformed control data, not an
-authored child failure, and shall take the fallback `failed` arm without
-appending evidence. The guard shall not fabricate missing identity or error
-members merely because the status string happens to be recognized.
-The public result's declared optional `childSessionId` and `state` members are
-valid when their shapes satisfy the shared contract; validate and then discard
-them when building compact Captain evidence. They are not undeclared extras.
-Likewise, the public normalized error may carry its declared optional string
-`stack`; validate it and omit it from the compact `{ name, message }` evidence
-rather than rejecting an otherwise valid authored child result.
-Apply the public union exactly: an `aborted` or `error` result shall reject an
-`output` member; `childSessionId`, when present, shall be non-empty; `error`
-shall contain only non-empty `name`, string `message`, and optional string
-`stack`; and `state`, when present, shall validate every declared
-`PlaybookState` member and reject unknown or missing members. Treating an
-arbitrary JSON-safe object as a valid `state`, or checking only that these
-members have broad string/object types, is not complete public-result
-validation.
-In other words, the guard validates the complete public result it received,
-while the action retains only the current selected playbook id, status, and
-compact error. Do not implement evidence minimization by accepting only the
-three keys that survive that projection.
+Recognize authored rejected child results with the existing named
+`validatePlaybookCallResult` export from `@sublang/playbook/xstate-runtime`
+and the type-only `PlaybookCallResult` from `@sublang/playbook/runtime`:
+
+```typescript
+import { validatePlaybookCallResult } from '@sublang/playbook/xstate-runtime';
+import type { PlaybookCallResult } from '@sublang/playbook/runtime';
+
+export function authoredChildResult(error: unknown, expectedPlaybookId: string): PlaybookCallResult | undefined {
+  if (!(error instanceof Error)) return undefined;
+  try {
+    const result = validatePlaybookCallResult(
+      (error as Error & { result?: unknown }).result,
+      expectedPlaybookId,
+    );
+    return result.status !== 'ok' || result.terminal?.kind === 'failure' ? result : undefined;
+  } catch {
+    return undefined;
+  }
+}
+```
+
+Pass the actual selected target id from the same source-owned target used by
+`invoke.input`; do not fabricate a request or child-session identity for this
+check. The shared bridge owns invocation correlation. Its existing validator
+owns the complete [public result union](link.md#playbookports-contract),
+including terminal/state shapes, optional abort error, and JSON validity;
+do not rewrite those structural checks or redeclare their public types.
+An invalid result returns no authored outcome and takes the existing
+control-error fallback. A validated successful child output still needs its
+separate Source-owned acceptance predicate on `onDone`.
+After preserving Source-authored success acceptance and recovery cases plus the
+public control-error `onError` fallback, omit an `onDone` transition whose guard
+cannot be reached from any legal predecessor/context after the prior ordered
+`onDone` arms.
+This rule does not require arbitrary finite enumeration, drop valid failure
+behavior, or relax verifier obligations.
+Validate the full public result before projecting only the permitted compact
+evidence; evidence minimization shall not narrow the accepted public union.
+The helper supplies no workflow route, child-domain predicate, runner or actor
+implementation. Its ordinary package import is an explicit artifact dependency.
 
 Before entering a dynamic call, the machine shall reject an empty target and
 empty input text, any target equal to `selfPlaybookId`, and any target that
@@ -551,10 +618,13 @@ The artifact shall not bake them into machine input, options, or context; model
 Host-owned configuration such as an enabled-playbook catalog shall remain
 immutable machine input/context for the session. Boss events and actor outputs
 shall not carry, replace, append to, or otherwise overwrite that catalog.
-A placeholder whose value Source assigns to the host — for example the
-`<definition>` a phase host supplies to a compiled phase — is such host-owned
-configuration: a required machine `input` field carried into typed context and
-the acting actor's input, never a Boss-event or actor-output payload.
+A non-identity placeholder whose value Source assigns to the host — for
+example the `<definition>` a phase host supplies to a compiled phase — is such
+host-owned configuration: a required machine `input` field carried into typed
+context and the acting actor's input, never a Boss-event or actor-output
+payload. A Source-declared local-role prompt-identity placeholder is the
+explicit exception; it resolves from the invocation-scoped `promptIdentity`
+lookup and is not persisted as host configuration.
 Every machine with a dynamic call shall receive its own registered or authored
 playbook id as immutable machine input/context named `selfPlaybookId`, and its
 dynamic-call guard shall reject that target. The leaf-level `stateId` name is
@@ -588,6 +658,8 @@ while an actual back-edge is rejected.
 A transition fires on an event — typically `onDone` (actor completed) [[4]].
 When multiple are possible, a synchronous guard [[5]] picks the path.
 Transitions shall persist relevant typed fields from `event.output` to context via `assign` [[6]] so downstream prompts can read them.
+Where a Source outcome's availability condition is deterministically knowable from execution state, such as a prior Boss reply already received by the machine, the transition shall enforce that condition with authored guards or typed state before the result can be accepted; stating the condition only in a Results description, Judge prose, or prompt text is not enough.
+The compiler shall update or reset those source-owned facts only at their actual Source lifecycle boundaries, and shall not attempt to mechanically decide semantic judgments that Source leaves to the acting agent.
 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.
 
@@ -647,6 +719,15 @@ contract shall require exactly `targetId: 'routing'` plus the fresh
 `BOSS_INTERRUPT` jumps into an **active** machine, pre-empting whichever state is running.
 **Boss entry events** start or resume from idle or recoverable states when Boss-supplied parameters can't be inferred from machine state alone.
 Entry events shall be typed alongside `BOSS_INTERRUPT` and populate context via a dedicated action.
+Boss text supplied by an entry event shall not become a required machine-construction input unless Source independently requires that value before the first Boss turn; an optional source-appropriate seed may remain.
+A generated required input annotation alone is not evidence of that independent Source bootstrap requirement.
+Entry guards run before entry copy actions: validate supplied text from the
+current event, not solely from the context that action will populate.
+For an omitted event value, use an existing context seed only where Source
+permits it; do not manufacture a required constructor value to satisfy a
+context-only entry guard. The linked runtime sends the entry event normally;
+its `entryEvent.contextField` declaration supports failure retry and does not
+copy fresh text into context before the guard.
 An entry event's copy action shall not clear per-run parameters the event omits: an absent optional field falls back to the existing (input-seeded) context value.
 The two surfaces shall not be collapsed. `BOSS_INTERRUPT` always carries its
 target id and may additionally carry typed Boss-supplied fields such as an
@@ -698,6 +779,9 @@ A delegated `PlayerInput` shall produce the role asker with its canonical local
 Only
 `question` shall come from adjudicated actor output.
 
+The canonical storage paths are `context.pendingBossQuestion` and `context.bossReply` for the scalar form, or `context.pendingBossQuestions[stateId]` and `context.bossReplies[stateId]` for the keyed form.
+A private wrapper such as `context.continuation` shall not replace these fields directly on machine context.
+
 A machine with at most one active Captain or player task may use the scalar
 form:
 
@@ -740,6 +824,9 @@ A captain- or player-invoking state's `invoke.input` function shall carry the
 pending question and reply selected for that working leaf as singular
 `pendingBossQuestion` and `bossReply` fields, regardless of the scalar or keyed
 context representation, so prompt composition has one stable contract.
+When Source requires earlier discussion or constraints on a later invocation, the compiler shall persist that source-owned history in serializable machine context before replacing or clearing the pending Q/A fields.
+The later `invoke.input` shall relay that persisted context on both resumed and fresh calls that Source says need it, preserving Source-owned relevance and format without imposing all-history semantics on sources that do not require it.
+Shared Boss-reply continuation carries only the latest Q/A pair, and a backend continuation token is not durable Source history.
 When both fields are present, the linked runtime shall compose the continuation preamble and labelled Q&A blocks per [link.md "Player prompt composition"](link.md#player-prompt-composition).
 The FSM artifact shall not bake the continuation preamble into the GEARS-derived `prompt` body.
 

package/slc/link.md

@@ -24,6 +24,9 @@ Hosts are out of scope for this phase.
 Each host has an adapter that loads a `PlaybookRuntime` module and supplies the host's primitives as `PlaybookPorts`.
 The adapter shall speak only `PlaybookPorts` to the runtime and shall not leak host types back into it.
 
+At construction, the shared factory validates linked metadata and the shared construction shape; the Captain host owns registry-manifest and live authority-envelope validation at its construction boundary.
+Do not audit the bare shared factory as if it owned that Captain-host boundary or synthesize host capabilities in the emitted artifact.
+
 The link compiler shall not modify the FSM artifact and shall not re-derive Captain prompts, result keys, or guard semantics — those are fixed by the FSM.
 
 ## Formats
@@ -33,6 +36,138 @@ The link compiler shall not modify the FSM artifact and shall not re-derive Capt
 | source | fsm      | .ts       |
 | target | playbook | .ts       |
 
+## 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
+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.
+
+Invoke the tool with the actual definition directory, source FSM, and declared
+target; supply a JSON descriptor on standard input:
+
+```sh
+node "<definition-directory>/materialize-link.mjs" --fsm "<source.fsm.ts>" --out "<target.playbook.ts>" <<'JSON'
+{
+  "schema": "sublang.playbook.link.v1",
+  "profile": "flat-defaults",
+  "machineExport": "exampleMachine",
+  "label": "EXAMPLE",
+  "options": {},
+  "inputMapping": {},
+  "entryEvent": { "type": "BOSS_TASK", "textField": "bossIntent", "contextField": "bossIntent" },
+  "bossEvents": [],
+  "outcomeAuthority": {
+    "governedPlayerStates": {
+      "work": {
+        "done": { "fields": {}, "repositoryDisposition": "one-descendant-commit" },
+        "needsBossReply": { "fields": { "question": "presentation" }, "repositoryDisposition": "deferred" }
+      }
+    }
+  },
+  "placeholderFields": {},
+  "transitionEventFields": ["bossIntent", "answer", "questionId"],
+  "verbatimPayloadFields": [],
+  "resumableStateIds": ["work"],
+  "unfinishedFinalStateIds": [],
+  "controlContextFields": []
+}
+JSON
+```
+
+This descriptor is an example shape, not default workflow semantics.
+Select `flat-defaults` for the unchanged shared player composer, or
+`flat-quoted-relays` when the source requires standalone `> <token>` relay lines.
+The latter uses the same descriptor keys and `placeholderFields` mappings;
+ordinary string tokens substitute literally, while standalone relay values
+quote each nonempty line with `> ` and preserve LF/CRLF and blank lines.
+An empty relay value omits its complete template line; missing or non-string
+values retain the token. Inserted values are never substituted again.
+The emitted composer preserves the installed shared fresh/resumed Q&A prefix
+and does not modify the original input. Labelled relays, identity-specific
+composition, structured renderers, and other custom strategies require
+ordinary linking; do not select either profile for those requirements.
+Every top-level member is required; unknown members are errors.
+`options` maps each configured option to `{ "type": "string" | "number" |
+"boolean", "required": true | false }`; `inputMapping` maps each FSM input
+field to its supplying option name.
+Option unions, closed values, range constraints, nested structures, and
+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.
+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,
+requiredness, and closed values specified under Output.
+The state/outcome/field authority map, placeholder exceptions, transition and
+verbatim fields, resumable states, unfinished finals, and safe ordered context
+projection retain their exact obligations under Output.
+The tool copies role labels and identities from the machine and never guesses
+result semantics by executing an invocation against invented context.
+
+The helper resolves the installed shared engine from the source and target
+locations and refuses differing engine resolutions.
+Its factory preflight checks linked metadata.
+It accepts `.fsm.js` on supported Node versions; `.fsm.ts` requires native
+type stripping (Node 23.6+, or Node 22.18+).
+On success it atomically writes only the declared target after factory
+preflight; run all existing conformance checks afterward.
+Exit 2 reports `unsupported` without changing the target: continue ordinary
+linking under this complete definition.
+Exit 1 reports invalid metadata, loading, preflight, or output failure:
+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
+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.
+It does not authorize generating or importing maintained workflow artifacts.
+
+Select it only for literal string substitution in unchanged player templates,
+including labelled `> Label: <token>` lines and source-declared role-identity
+tokens. In addition to every descriptor member above, supply:
+
+- `playerInputExport`: the exact exported FSM player-input type name.
+- `omitEmptyRelayLines`: exact complete source lines to omit only when their
+  mapped string value is empty, for example
+  `["> Run results: <run-results>"]`. Each line starts with `> ` and ends in
+  one placeholder; any preceding label is literal. Use an explicit empty
+  array when no line is optional; never infer optionality from a missing value.
+- `identityPlaceholders`: an explicit token-to-canonical-local-role map, such
+  as `{ "coder-llm": "coder" }` only where Source requires that identity.
+  These values come solely from the invocation-scoped identity lookup, never
+  from options, FSM context, or model prose. Use `{}` when none is authored.
+
+The composer replaces original tokens once, prefixes each continuation line
+of a value inserted into a quoted source line with `> `, preserves line
+separators and literal inserted text, and leaves missing/non-string values as
+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
+conformance checks remain mandatory. This profile changes no runtime bridge,
+workflow semantics, or measured performance claim.
+
+For an FSM that satisfies one of the materializer profiles above, derive its
+complete source-owned descriptor and run `materialize-link.mjs` before writing
+an ordinary linked module by hand. Use the supported profile whose composer
+matches the actual source. An unsupported-profile exit continues ordinary
+linking under this definition; invalid metadata must be corrected. Never
+widen an option, omit a required custom strategy, change the FSM, or relax a
+verification check to make a profile fit.
+
+
 ## PlaybookRuntime contract
 
 The emitted module shall default-export a factory of the following shape:
@@ -364,7 +499,7 @@ The roleless session-Captain is the sole signature exception: its public options
 
 Artifact schema `3` shall require `outcomeAuthority` as an own plain-JSON data property and shall instantiate the shared factory with exactly `{ configuredOptions, hostCapabilities }`, where `configuredOptions` is the registry-validated plain-JSON workflow slice and `hostCapabilities` is a non-null live current-host object.
 For schema `3`, the `Options` argument of the one-argument shared `PlaybookRuntimeFactory<Options>` shall be `XStatePlaybookRuntimeConstruction<ConfiguredOptions, HostCapabilities>`; the registry's public entry receives the two members separately and composes that one internal argument only at the artifact boundary.
-For a Captain-hosted schema-3 artifact, `hostCapabilities` shall contain exactly `authority`, `repository`, and `effectLedger`: authority binds that artifact's id, schema, detached role and cohort declarations, current configured working directory, logical session and lease-owner identities, and canonical worktree; repository exposes that same canonical identity plus host-bound observation, acquisition, exclusive-call, and cohort operations, whose optional live completion mapper may return only detached `finalText`, `semanticCandidate`, `logicalOperationId`, and additional typed ledger commands for the same atomic completion; and the ledger exposes its synchronous detached `snapshot(): PlaybookEffectLedger` mirror plus `writeAhead(commands: PlaybookEffectLedgerCommandBatch): Promise<PlaybookEffectLedger>` against the current host's atomic writer.
+For a Captain-hosted schema-3 artifact, `hostCapabilities` shall contain exactly `authority`, `repository`, and `effectLedger`: authority binds that artifact's id, schema, detached role and cohort declarations, current configured working directory, logical session and lease-owner identities, and canonical worktree; repository exposes that same canonical identity plus host-bound observation, acquisition, exclusive-call, and cohort operations, whose optional live completion mapper may return only detached `finalText`, `semanticCandidate`, `logicalOperationId`, additional typed ledger commands for the same atomic completion, one `deferred` binding carrying optional UUID `operationId` plus exact `pendingQuestion` and `playerContinuation`, or literal `unresolved: true`, where `deferred` shall be mutually exclusive with `unresolved`, `logicalOperationId`, and commands; and the ledger exposes its synchronous detached `snapshot(): PlaybookEffectLedger` mirror plus `writeAhead(commands: PlaybookEffectLedgerCommandBatch): Promise<PlaybookEffectLedger>` against the current host's atomic writer.
 Only `configuredOptions` may reach option snapshotting and FSM input.
 The capability object, its callbacks, lease token, and live claim or store handles shall enter neither `PlaybookPorts`, machine input or context, runtime snapshots, launch or durable projections, retained generations, nor continuation identity; the detached ledger data and canonical identities returned by its ledger channel shall instead persist only through the versioned effect-ledger members defined below.
 
@@ -425,6 +560,9 @@ Each state shall name exactly the outcomes in that state's `invoke.input.result`
 The outcome key owns the semantic discriminator, so `guard` shall not appear in `fields`; the `fields` keys shall equal every additional payload field named by that outcome's result description.
 Each field shall have exactly one authority from `presentation`, `semantic`, `effect`, or `runtime`; every linker-declared verbatim payload field and `question` shall be `presentation`, `latestCommit` shall be `effect`, and the payload fields `irNumber` and `irTask` shall be `semantic`, while outcome keys such as `moreTasks` and `finalTask` remain semantic discriminators.
 Each repository disposition shall be exactly `unchanged`, `one-descendant-commit`, or `deferred`; an effect-owned field is valid on `one-descendant-commit` and `unchanged` and never on `deferred`, and `deferred` is valid only on `needsBossReply` with presentation-owned `question` and another outcome in that state declaring `one-descendant-commit`.
+The linker shall derive each disposition from the source-derived operation and the outcome's required repository effect, independently of whether its result description declares an effect-owned payload field.
+A completion that requires committing the result to Git shall declare `one-descendant-commit` even when its outcome is simply `done` with `fields: {}`; its eligible `needsBossReply` arm shall declare `deferred` under the rule above.
+The absence of `latestCommit` or any other effect-owned field shall never justify defaulting that completion to `unchanged`.
 The shared factory shall reject every legacy artifact schema and reject schema-3 missing, extra, unknown, wrongly owned, or inconsistent metadata before the affected player call.
 
 `init` receives the host-owned playbook session identity and ports, constructs the XState actor with FSM `input` derived from `options`, and starts the actor.
@@ -459,6 +597,17 @@ remain a required readonly runtime option passed through to machine input; the
 linker shall neither invent an empty catalog nor require it to be baked into a
 CLI link option.
 
+The linked module shall export public synchronous pure `validateOptions(value: unknown): PlaybookRuntimeOptions` and bind that same function as the shared spec's `snapshotOptions`.
+The validator shall first capture `value === undefined ? {} : value` with the public `snapshotJsonValue` exported by `@sublang/playbook/xstate-runtime`, before reading option members, applying defaults, or constructing a replacement record; only top-level `undefined` is normalized, and non-JSON input rejects through that shared boundary.
+It shall then validate the artifact's actual option shape, requiredness, source-authored defaults, unknown keys, and declared values against the detached snapshot, reject null and invalid options, and return a detached immutable plain-JSON option record without runtime construction or live host capabilities.
+Boss text supplied by the entry event is not a required startup option unless Source independently requires it before the first Boss turn; a generated required type annotation alone is not that evidence.
+A generated entry guard that requires the text already in context is likewise
+not independent Source evidence; it is a producer defect when the entry action
+has yet to copy the event's text. Do not compensate with a required option or
+invented startup task. `entryEvent.contextField` supplies failure-retry text;
+it does not populate fresh entry context before FSM guards execute.
+A source-appropriate optional seed may remain, and genuine required bootstrap catalogs or other options shall not be erased or filled with invented defaults.
+
 Concrete player binding and prompt identity are host policy and shall not enter `PlaybookRuntimeOptions`, machine input, or the emitted artifact.
 For a shell-hosted runtime, `PlaybookSession.roleBindings` shall carry exactly the runtime's local roles, map each to its resolved player id and current prompt identity, and be the sole source for call targeting, player-facing prompt identity, concurrency keys, and trace player ids.
 The host shall derive `promptIdentity` from the current effective model when present and the established adapter otherwise; a standalone runtime may omit the map and retain only its local role identity.
@@ -1457,10 +1606,12 @@ artifact declares its reached final state's kind: the runtime reads
 `meta.playbook.terminal` and that state's authored description from the
 artifact, never from an agent reply, and a declared value other than `success`
 or `failure` is a control-plane error rather than a child outcome.
-Because the bridge routes a failure terminal to the error path, `onDone` alone
-proves the child succeeded and a caller never inspects a callee's output fields
-to decide that; a caller reads those fields only when its own Source relays
-them.
+`onDone` proves successful bridge delivery without a declared child failure;
+it does not establish every caller-owned domain condition. The caller shall
+enforce its own explicit Source-authored acceptance or relay predicates on
+the delivered output before continuing, without inventing predicates from
+callee implementation details or overriding the child's compiled terminal
+kind with output fields.
 Unknown, duplicate, or stale call ids reject without changing actor state.
 The finish trace shall therefore precede any parent FSM transition caused by
 the child return.
@@ -2250,8 +2401,8 @@ The thin emitted module:
   by `PlaybookSession` or another linker-owned source (§PlaybookRuntime
   contract), plus the optional `cwd` option whenever the FSM contains a
   `script` state (§Script execution).
-- Supplies the spec's `snapshotOptions` with the same options-validation
-  semantics previously generated inline: validate and JSON-snapshot the
+- Exports the public `validateOptions` function specified above and supplies
+  it as the spec's identical `snapshotOptions` callback: validate and JSON-snapshot the
   caller's options, rejecting undeclared keys and non-conforming values, so
   the factory binds an immutable options record before constructing any
   actor.