@sublang/playbook 11.0.0 → 12.1.0

package/slc/gears2fsm.md

@@ -540,6 +540,10 @@ 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.
 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
@@ -776,6 +780,22 @@ compile as `{ response: string }`, not `{ response?: string }`; reaching the
 final state without a non-empty response shall be guarded out before the
 machine output is constructed.
 
+## Compiled execution
+
+This section governs compiled execution of this phase; the rules above remain the transformation's normative content for both execution paths.
+
+Where the phase host supplies `<definition>` as the exact bytes of the definition file the request names, when a transformation request names a `gears` Source (`.md`) and an `fsm` Target (`.ts`), Captain shall carry out the GEARS-to-FSM transformation as specified:
+
+> Follow the definition relayed between the `--- DEFINITION ---` and `--- END DEFINITION ---` lines exactly, adding no rules of your own: read the named Source and write the named Target as the definition specifies.
+> If the Source cannot be transformed under the definition, do not guess: leave the Target unwritten and report the concrete reason.
+> --- DEFINITION ---
+> \<definition\>
+> --- END DEFINITION ---
+
+Results:
+- `compiled`: Captain wrote the named Target as the relayed definition specifies.
+- `rejected`: Captain reported that the Source cannot be transformed under the relayed definition and left the Target unwritten.
+
 ## References
 
 [1]: https://stately.ai/docs/xstate 'XState Official Documentation'

package/slc/link.md

@@ -423,7 +423,7 @@ After a governed operation settles, the host shall retain any exact proposed com
 Each state shall name exactly the outcomes in that state's `invoke.input.result`, and each outcome shall contain exactly `fields` and `repositoryDisposition`.
 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 only on `one-descendant-commit`, and `deferred` is valid only on `needsBossReply` with presentation-owned `question` and another outcome in that state declaring `one-descendant-commit`.
+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 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.
@@ -1081,8 +1081,11 @@ field shall satisfy the result map's required-field type before any actor
 output is delivered.
 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, effect-owned
-`latestCommit` shall receive only the qualifying receipt's exact commit OID,
+shall receive the canonical `finalText.trim()` value; every effect-owned
+field shall receive only the qualifying receipt's repository fact selected by
+the accepted outcome's declared disposition — the exact new-descendant commit
+OID on `one-descendant-commit`, or the matching `unchanged` receipt's
+observed HEAD OID on `unchanged` — never a value keyed on the field's name;
 and no authority may supply, overwrite, or contradict another authority's
 field.
 It shall reject an absent required field, an undeclared or extra field, a
@@ -1092,8 +1095,12 @@ inconsistent candidate before FSM delivery.
 For a non-deferred candidate, reconciliation shall require a complete durable
 physical receipt, or the complete cumulative logical receipt of a deferred
 operation, whose classification is exactly the outcome's declared
-`unchanged` or `one-descendant-commit` disposition; the latter shall carry
-exactly the after-HEAD OID used for `latestCommit`.
+`unchanged` or `one-descendant-commit` disposition; a `one-descendant-commit`
+receipt shall carry exactly the after-HEAD OID used for the arm's effect-owned
+fields, while an `unchanged` receipt's complete validated observation supplies
+its observed HEAD OID for them, and a receipt that cannot prove that observed
+HEAD shall leave the envelope unresolved rather than inject a fabricated
+value.
 A `deferred` candidate shall be admissible only for its already-validated
 effect-authorized `needsBossReply` outcome and only from a complete after
 observation whose HEAD equals the logical operation's original baseline HEAD
@@ -2444,6 +2451,22 @@ This spec is silent on the choice; the contract is the same in any location.
 
 New behavior in any of these areas requires a separate slc spec.
 
+## Compiled execution
+
+This section governs compiled execution of this phase; the rules above remain the transformation's normative content for both execution paths.
+
+Where the phase host supplies `<definition>` as the exact bytes of the definition file the request names, when a transformation request names an `fsm` Source (`.ts`) and a `playbook` Target (`.ts`), Captain shall carry out the FSM-to-runtime linking as specified:
+
+> Follow the definition relayed between the `--- DEFINITION ---` and `--- END DEFINITION ---` lines exactly, adding no rules of your own: read the named Source and write the named Target as the definition specifies.
+> If the Source cannot be transformed under the definition, do not guess: leave the Target unwritten and report the concrete reason.
+> --- DEFINITION ---
+> \<definition\>
+> --- END DEFINITION ---
+
+Results:
+- `compiled`: Captain wrote the named Target as the relayed definition specifies.
+- `rejected`: Captain reported that the Source cannot be transformed under the relayed definition and left the Target unwritten.
+
 ## References
 
 [1]: text2gears.md "First phase: text → GEARS spec items."

package/slc/text2gears.md

@@ -79,6 +79,9 @@ If Source supplies a blockquoted template for that relay, text2gears shall keep
 If Source names the relayed value but supplies no template, text2gears shall emit its canonical typed placeholder on a line beginning with literal `> ` and shall not summarize, paraphrase, or invent a value in its place.
 An ordinary Source blockquote that specifies a complete acting prompt without requiring quoted relay retains the existing rule above: its one leading marker is Source syntax and is not prompt content.
 
+An acting prompt whose instructions refer to a runtime value the acting role cannot otherwise observe — for example the Boss input task that triggered the workflow — shall relay that value as a quoted `<placeholder>` line appended to the prompt even when Source states no explicit relay.
+A prompt that references an undelivered value asks its player to act on data it never received; omitting the relay is a compilation defect, not a faithful rendering of Source.
+
 Source statements that assign active-leaf routing, call identity, suspension,
 or return matching to the host describe execution preconditions rather than
 behaviors for Captain to perform. text2gears shall use such a statement only as
@@ -318,7 +321,8 @@ exact English form regardless of Source language.
 ## Transformation-spec sources
 
 A Source may itself be the normative specification of a transformation — e.g., a compiler phase definition, as when a meta pipeline compiles this file.
-Such a Source declares no roles and prompts none; its implied procedure is that Captain performs the specified transformation on request.
+Such a Source declares no roles and prompts none; Captain performs the specified transformation on request.
+Where such a Source carries a `## Compiled execution` section, text2gears shall compile it from that section alone: the section is the Source's complete behavior — its acting item, prompt, and `Results:` contract — and the remaining definition text is relayed content, not behaviors to transcribe, so the composition below applies only to a Source without that section.
 Compose Captain-acting spec items for it: when a transformation request names the specification's source and target, Captain shall carry out the transformation as specified.
 Prompts shall carry the specification's normative requirements as instructions to Captain — deduplicated, one point per line — without inventing roles, triggers, or requirements the specification does not state.
 
@@ -349,6 +353,22 @@ Partition items by every variable that determines prompt content — including a
 Drop disjunctive branches incompatible with the rest of an item's condition or prompt.
 Dead branches mislead readers and downstream phases.
 
+## Compiled execution
+
+This section governs compiled execution of this phase; the rules above remain the transformation's normative content for both execution paths.
+
+Where the phase host supplies `<definition>` as the exact bytes of the definition file the request names, when a transformation request names a `text` Source (`.md`) and a `gears` Target (`.md`), Captain shall carry out the text-to-GEARS transformation as specified:
+
+> Follow the definition relayed between the `--- DEFINITION ---` and `--- END DEFINITION ---` lines exactly, adding no rules of your own: read the named Source and write the named Target as the definition specifies.
+> If the Source cannot be transformed under the definition, do not guess: leave the Target unwritten and report the concrete reason.
+> --- DEFINITION ---
+> \<definition\>
+> --- END DEFINITION ---
+
+Results:
+- `compiled`: Captain wrote the named Target as the relayed definition specifies.
+- `rejected`: Captain reported that the Source cannot be transformed under the relayed definition and left the Target unwritten.
+
 ## References
 
 [1]: GEARS definition shipped by the installed `@sublang/spex` package: `@sublang/spex/scaffold/specs/meta.md` (English) and `@sublang/spex/scaffold/i18n/zh/specs/meta.md` (Chinese); canonical renditions [GEARS: AI-Ready Spec Syntax](https://sublang.ai/ref/gears-ai-ready-spec-syntax) (en) and [GEARS：面向 AI 的规约语法](https://sublang.ai/zh/ref/gears-ai-ready-spec-syntax) (zh)

package/src/xstate-playbook-runtime.js

@@ -1242,9 +1242,12 @@ function snapshotOutcomeAuthority(descriptor, label, playerStates, verbatimPaylo
                 !REPOSITORY_DISPOSITIONS.has(disposition)) {
                 throw new TypeError(`${outcomePath}.repositoryDisposition must be unchanged, one-descendant-commit, or deferred`);
             }
-            if (disposition !== 'one-descendant-commit' &&
+            // DR-045: an unchanged arm may declare effect-owned fields (injected
+            // from the matching unchanged receipt's observed HEAD); only deferred
+            // arms remain barred from effect ownership.
+            if (disposition === 'deferred' &&
                 Object.values(fields).includes('effect')) {
-                throw new TypeError(`${outcomePath} may declare effect-owned fields only for one-descendant-commit`);
+                throw new TypeError(`${outcomePath} may not declare effect-owned fields for deferred`);
             }
             outcomes[outcome] = Object.freeze({
                 fields: Object.freeze(fields),

package/src/xstate-playbook-runtime.ts

@@ -2226,12 +2226,15 @@ function snapshotOutcomeAuthority(
           `${outcomePath}.repositoryDisposition must be unchanged, one-descendant-commit, or deferred`,
         );
       }
+      // DR-045: an unchanged arm may declare effect-owned fields (injected
+      // from the matching unchanged receipt's observed HEAD); only deferred
+      // arms remain barred from effect ownership.
       if (
-        disposition !== 'one-descendant-commit' &&
+        disposition === 'deferred' &&
         Object.values(fields).includes('effect')
       ) {
         throw new TypeError(
-          `${outcomePath} may declare effect-owned fields only for one-descendant-commit`,
+          `${outcomePath} may not declare effect-owned fields for deferred`,
         );
       }
       outcomes[outcome] = Object.freeze({

package/src/xstate-runtime.js

@@ -892,7 +892,19 @@ export function reconcilePlaybookSemanticEvidence(input) {
             value = finalText;
         }
         else if (authority === 'effect') {
-            value = field === 'latestCommit' ? receipt.commitOid : undefined;
+            // DR-045: effect injection selects by the accepted arm's declared
+            // repository disposition, never by the field's name. A
+            // one-descendant-commit arm's effect fields carry the qualifying
+            // receipt's exact new-descendant commit OID; an unchanged arm's effect
+            // fields carry the matching unchanged receipt's observed HEAD OID. A
+            // deferred arm declares no effect field, and any shape the validated
+            // receipt cannot prove fails closed as unresolved.
+            value =
+                disposition === 'one-descendant-commit'
+                    ? receipt.commitOid
+                    : disposition === 'unchanged'
+                        ? receipt.after?.head
+                        : undefined;
             if (value === undefined) {
                 return unresolvedSemanticEvidence('missing-effect-evidence', evidence);
             }

package/src/xstate-runtime.ts

@@ -1416,7 +1416,19 @@ export function reconcilePlaybookSemanticEvidence(
     } else if (authority === 'presentation') {
       value = finalText;
     } else if (authority === 'effect') {
-      value = field === 'latestCommit' ? receipt.commitOid : undefined;
+      // DR-045: effect injection selects by the accepted arm's declared
+      // repository disposition, never by the field's name. A
+      // one-descendant-commit arm's effect fields carry the qualifying
+      // receipt's exact new-descendant commit OID; an unchanged arm's effect
+      // fields carry the matching unchanged receipt's observed HEAD OID. A
+      // deferred arm declares no effect field, and any shape the validated
+      // receipt cannot prove fails closed as unresolved.
+      value =
+        disposition === 'one-descendant-commit'
+          ? receipt.commitOid
+          : disposition === 'unchanged'
+            ? receipt.after?.head
+            : undefined;
       if (value === undefined) {
         return unresolvedSemanticEvidence('missing-effect-evidence', evidence);
       }