@sublang/playbook 12.0.0 → 12.1.0

package/reference/sdlc/code.playbook/bin/session-store.js

@@ -4080,7 +4080,10 @@ function validateEffectLedgerAuthority(value, record, owner) {
   return authority;
 }
 
-function applyEffectLedgerCommands(
+// Exported for the private worktree host-capability constructor in
+// repository-effects.js, so an external host's in-memory ledger applies the
+// exact command semantics the durable Captain record applies.
+export function applyEffectLedgerCommands(
   ledgerValue,
   authority,
   uncertain,

package/reference/sdlc/code.playbook/host-capabilities.d.ts

@@ -0,0 +1,291 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+
+export type JsonValue =
+  | null
+  | boolean
+  | number
+  | string
+  | readonly JsonValue[]
+  | { readonly [key: string]: JsonValue };
+
+export type PlaybookRepositoryDisposition =
+  | 'unchanged'
+  | 'one-descendant-commit'
+  | 'deferred';
+export type RepositoryReceiptClassification =
+  | 'unchanged'
+  | 'one-descendant-commit'
+  | 'multiple-commits'
+  | 'rewritten-or-non-descendant'
+  | 'worktree-only-change'
+  | 'concurrent-or-foreign-change'
+  | 'observation-ambiguous';
+export declare const REPOSITORY_RECEIPT_CLASSIFICATIONS: readonly RepositoryReceiptClassification[];
+
+export interface RepositoryIdentity {
+  readonly worktree: string;
+  readonly gitDir: string;
+}
+export interface PlaybookRepositoryObservation extends RepositoryIdentity {
+  readonly head: string;
+  readonly projection: Readonly<Record<string, JsonValue>>;
+  readonly projectionDigest: string;
+}
+export interface PlaybookRepositoryReceipt {
+  readonly classification: RepositoryReceiptClassification;
+  readonly baseline: PlaybookRepositoryObservation;
+  readonly after?: PlaybookRepositoryObservation;
+  readonly commitOid?: string;
+}
+export interface RepositoryReceiptOptions {
+  readonly allowedDispositions: readonly PlaybookRepositoryDisposition[];
+}
+
+export declare function observeGitRepository(
+  cwd: string,
+): Promise<PlaybookRepositoryObservation>;
+export declare function classifyRepositoryReceipt(
+  baseline: PlaybookRepositoryObservation,
+  after: PlaybookRepositoryObservation,
+  options: RepositoryReceiptOptions,
+): Promise<PlaybookRepositoryReceipt>;
+export declare function captureRepositoryReceipt(
+  baseline: PlaybookRepositoryObservation,
+  options: RepositoryReceiptOptions,
+): Promise<PlaybookRepositoryReceipt>;
+
+export interface PlaybookPendingBossQuestion {
+  readonly questionId: string;
+  readonly asker:
+    | { readonly kind: 'captain' }
+    | { readonly kind: 'role'; readonly roleId: string };
+  readonly question: string;
+  readonly sourceItem?: string;
+}
+export interface PlaybookEffectBoundary {
+  readonly sequence: number;
+  readonly boundaryId: string;
+  readonly attemptId: string;
+  readonly attemptNumber: number;
+  readonly playbookId: string;
+  readonly runtimeSessionId: string;
+  readonly turnId: number;
+  readonly callId: string;
+  readonly roleId: string;
+  readonly sourceStateId: string;
+  readonly sourceOutcomeSchema: JsonValue;
+  readonly dispositions: readonly PlaybookRepositoryDisposition[];
+  readonly canonicalWorktree: RepositoryIdentity;
+  readonly baseline: PlaybookRepositoryObservation;
+  readonly after?: PlaybookRepositoryObservation;
+  readonly physicalReceipt?: PlaybookRepositoryReceipt;
+  readonly finalText?: string;
+  readonly semanticCandidate?: JsonValue;
+  readonly initialSemanticCandidate?: JsonValue;
+  readonly correctionBudget: {
+    readonly limit: 1;
+    readonly spent: boolean;
+  };
+  readonly cohortId?: string;
+  readonly logicalOperationId?: string;
+}
+export type PlaybookEffectBoundaryStart = Omit<
+  PlaybookEffectBoundary,
+  | 'sequence'
+  | 'attemptId'
+  | 'attemptNumber'
+  | 'after'
+  | 'physicalReceipt'
+  | 'finalText'
+  | 'semanticCandidate'
+  | 'initialSemanticCandidate'
+>;
+export type EffectBoundarySeed = Omit<
+  PlaybookEffectBoundaryStart,
+  'playbookId' | 'canonicalWorktree' | 'baseline' | 'cohortId'
+>;
+export interface PlaybookEffectLogicalOperation {
+  readonly sequence: number;
+  readonly operationId: string;
+  readonly playbookId: string;
+  readonly runtimeSessionId: string;
+  readonly boundaryIds: readonly string[];
+  readonly originalBaseline: PlaybookRepositoryObservation;
+  readonly checkpoint?: PlaybookRepositoryObservation;
+  readonly pendingQuestion?: PlaybookPendingBossQuestion;
+  readonly playerContinuation?: JsonValue;
+  readonly checkpointRestorationEligible: boolean;
+  readonly logicalReceipt?: PlaybookRepositoryReceipt;
+}
+export interface PlaybookEffectLedger {
+  readonly schemaVersion: 1;
+  readonly revision: number;
+  readonly boundaries: readonly PlaybookEffectBoundary[];
+  readonly logicalOperations: readonly PlaybookEffectLogicalOperation[];
+}
+export type PlaybookEffectLedgerCommand =
+  | {
+      readonly kind: 'start-boundaries';
+      readonly boundaries: readonly [
+        PlaybookEffectBoundaryStart,
+        ...PlaybookEffectBoundaryStart[],
+      ];
+    }
+  | {
+      readonly kind: 'replace-boundaries';
+      readonly replacements: readonly [
+        {
+          readonly expected: PlaybookEffectBoundary;
+          readonly next: PlaybookEffectBoundary;
+        },
+        ...{
+          readonly expected: PlaybookEffectBoundary;
+          readonly next: PlaybookEffectBoundary;
+        }[],
+      ];
+    }
+  | {
+      readonly kind: 'append-logical-operations';
+      readonly operations: readonly [
+        Omit<PlaybookEffectLogicalOperation, 'sequence'>,
+        ...Omit<PlaybookEffectLogicalOperation, 'sequence'>[],
+      ];
+    }
+  | {
+      readonly kind: 'replace-logical-operations';
+      readonly replacements: readonly [
+        {
+          readonly expected: PlaybookEffectLogicalOperation;
+          readonly next: PlaybookEffectLogicalOperation;
+        },
+        ...{
+          readonly expected: PlaybookEffectLogicalOperation;
+          readonly next: PlaybookEffectLogicalOperation;
+        }[],
+      ];
+    };
+export type PlaybookEffectLedgerCommandBatch = readonly [
+  PlaybookEffectLedgerCommand,
+  ...PlaybookEffectLedgerCommand[],
+];
+export interface PlaybookEffectLedgerCapability {
+  snapshot(): PlaybookEffectLedger;
+  writeAhead(
+    commands: PlaybookEffectLedgerCommandBatch,
+  ): Promise<PlaybookEffectLedger>;
+}
+
+interface RepositoryOperationSettlement<T> {
+  readonly status: 'fulfilled';
+  readonly value: T;
+}
+interface RepositoryOperationRejection {
+  readonly status: 'rejected';
+  readonly reason: unknown;
+}
+export interface RepositoryExclusiveCompletion<T> {
+  readonly boundary: PlaybookEffectBoundary;
+  readonly operation:
+    | RepositoryOperationSettlement<T>
+    | RepositoryOperationRejection;
+  readonly receipt: PlaybookRepositoryReceipt;
+  readonly outcomeReceipt: PlaybookRepositoryReceipt;
+}
+interface RepositoryDeferredBinding {
+  readonly operationId: string;
+  readonly pendingQuestion: PlaybookPendingBossQuestion;
+  readonly playerContinuation: JsonValue;
+}
+export interface RepositoryCompletionEvidence {
+  readonly finalText?: string;
+  readonly semanticCandidate?: JsonValue;
+  readonly deferred?: RepositoryDeferredBinding;
+  readonly unresolved?: true;
+}
+export interface RepositoryExclusiveResult<T> {
+  readonly operation:
+    | RepositoryOperationSettlement<T>
+    | RepositoryOperationRejection;
+  readonly receipt: PlaybookRepositoryReceipt;
+  readonly effectLedger: PlaybookEffectLedger;
+  readonly deferredStatus?: 'bound' | 'unresolved';
+}
+interface RepositoryDeferredContinuationResult<T> {
+  readonly status: 'continued';
+  readonly operation:
+    | RepositoryOperationSettlement<T>
+    | RepositoryOperationRejection;
+  readonly receipt: PlaybookRepositoryReceipt;
+  readonly logicalReceipt?: PlaybookRepositoryReceipt;
+  readonly effectLedger: PlaybookEffectLedger;
+  readonly deferredStatus?: 'bound' | 'unresolved';
+}
+interface RepositoryDeferredCheckpointMismatch {
+  readonly status: 'checkpoint-mismatch' | 'ineligible';
+  readonly effectLedger: PlaybookEffectLedger;
+}
+interface RepositoryDeferredParked {
+  readonly status: 'parked';
+  readonly effectLedger: PlaybookEffectLedger;
+}
+interface RepositoryDeferredRestoreResult {
+  readonly status: 'restored' | 'checkpoint-mismatch' | 'ineligible';
+  readonly effectLedger: PlaybookEffectLedger;
+}
+export interface RepositoryCapability {
+  runExclusive<T>(options: {
+    readonly signal?: AbortSignal;
+    readonly effectBoundary: EffectBoundarySeed;
+    readonly operation: (context: {
+      readonly baseline: PlaybookRepositoryObservation;
+      readonly identity: RepositoryIdentity;
+    }) => Promise<T>;
+    readonly completeEffectBoundary: (
+      completion: RepositoryExclusiveCompletion<T>,
+    ) => RepositoryCompletionEvidence | Promise<RepositoryCompletionEvidence>;
+  }): Promise<RepositoryExclusiveResult<T>>;
+  runDeferred<T>(options: {
+    readonly mode: 'continue';
+    readonly signal?: AbortSignal;
+    readonly operationId: string;
+    readonly effectBoundary: EffectBoundarySeed;
+    readonly operation: (context: {
+      readonly baseline: PlaybookRepositoryObservation;
+      readonly identity: RepositoryIdentity;
+      readonly playerContinuation: JsonValue;
+    }) => Promise<T>;
+    readonly completeEffectBoundary: (
+      completion: RepositoryExclusiveCompletion<T>,
+    ) => RepositoryCompletionEvidence | Promise<RepositoryCompletionEvidence>;
+  }): Promise<
+    RepositoryDeferredContinuationResult<T> | RepositoryDeferredCheckpointMismatch
+  >;
+  runDeferred(options: {
+    readonly mode: 'park' | 'restore';
+    readonly signal?: AbortSignal;
+    readonly operationId: string;
+  }): Promise<RepositoryDeferredParked | RepositoryDeferredRestoreResult>;
+}
+export interface HostCapabilities {
+  readonly repository: RepositoryCapability;
+  readonly effectLedger: PlaybookEffectLedgerCapability;
+}
+export interface WorktreeRepositoryCapability extends RepositoryCapability {
+  readonly identity: RepositoryIdentity;
+  observe(): Promise<PlaybookRepositoryObservation>;
+}
+export interface WorktreeHostCapabilities extends HostCapabilities {
+  readonly repository: WorktreeRepositoryCapability;
+}
+export interface WorktreeHostCapabilitiesOptions {
+  readonly cwd: string;
+  readonly playbookId: string;
+  readonly requiredRoleIds: readonly string[];
+  readonly concurrentRoleSets?: readonly (readonly string[])[];
+  readonly effectLedger?: PlaybookEffectLedger;
+}
+export declare function createWorktreeHostCapabilities(
+  options: WorktreeHostCapabilitiesOptions,
+): Promise<WorktreeHostCapabilities>;
+export declare function createFailClosedHostCapabilities(): HostCapabilities;

package/reference/sdlc/code.playbook/host-capabilities.js

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+
+// DR-046: the public `@sublang/playbook/host-capabilities` facade. Every
+// member is the CLI host's own repository-effect implementation; this module
+// only narrows the accepted arguments to the declared surface.
+
+import {
+  REPOSITORY_RECEIPT_CLASSIFICATIONS,
+  captureRepositoryReceipt as capture,
+  classifyRepositoryReceipt as classify,
+  createFailClosedHostCapabilities,
+  createWorktreeHostCapabilities,
+  observeGitRepository as observe,
+} from './bin/repository-effects.js';
+
+export {
+  REPOSITORY_RECEIPT_CLASSIFICATIONS,
+  createFailClosedHostCapabilities,
+  createWorktreeHostCapabilities,
+};
+
+export async function observeGitRepository(cwd) {
+  return observe(cwd);
+}
+
+export async function classifyRepositoryReceipt(baseline, after, options) {
+  return classify(baseline, after, receiptOptions(options));
+}
+
+export async function captureRepositoryReceipt(baseline, options) {
+  return capture(baseline, receiptOptions(options));
+}
+
+function receiptOptions(options) {
+  if (options === null || typeof options !== 'object' || Array.isArray(options)) {
+    throw new TypeError('repository receipt options must be an object');
+  }
+  return { allowedDispositions: options.allowedDispositions };
+}

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

@@ -2451,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

@@ -321,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.
 
@@ -352,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)