@sublang/playbook 14.1.0 → 15.1.0

package/slc/prefix-prompts.mjs

@@ -0,0 +1,190 @@
+#!/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 one `## Prefixed prompts` section at the end lists
+// the items this and every earlier application rewrote. `--keep <ITEM-ID>`
+// excludes an item the pass judged ineligible; the tool never modifies the
+// source.
+
+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 SECTION = '## Prefixed prompts';
+const SECTION_HEADING = /^##\s+Prefixed prompts\s*$/;
+const LISTED = /^-\s+([^\s:]+):\s+relays → tail\s*$/;
+const bullet = (id) => `- ${id}: relays → tail`;
+
+/** 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`.
+ * Returns the rewritten text with its provenance section, or the source text
+ * unchanged when no item was eligible, plus 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);
+  }
+  if (rewritten.length === 0) return { text, rewritten };
+  out.push(...lines.slice(cursor));
+  // One provenance section follows every other section, ending in one newline;
+  // it replaces every section an earlier application appended and lists, in
+  // item order, each item this or that application rewrote.
+  const listed = new Set(rewritten);
+  for (let index = out.length - 1; index >= 0; index--) {
+    if (!SECTION_HEADING.test(out[index])) continue;
+    let end = index + 1;
+    for (; end < out.length && !HEADING.test(out[end]); end++) {
+      const entry = LISTED.exec(out[end]);
+      if (entry !== null) listed.add(entry[1]);
+    }
+    out.splice(index, end - index);
+  }
+  while (out.length > 0 && out[out.length - 1] === '') out.pop();
+  const ids = starts.map((start) => start.id).filter((id) => listed.has(id));
+  out.push('', SECTION, '', ...ids.map(bullet), '');
+  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 { text, rewritten } = prefixPrompts(await readFile(resolve(source), 'utf8'), { keep });
+  await writeFile(resolve(target), text);
+  process.stdout.write(
+    rewritten.length === 0
+      ? 'no eligible item; target equals source\n'
+      : `${rewritten.join('\n')}\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;
+  });
+}

package/slc/prefix.md

@@ -0,0 +1,200 @@
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+<!-- SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai> -->
+
+# GEARS Prompt-Prefix Pass
+
+Optional optimization pass of a playbook (a state-machine agent orchestrating
+other agents).
+Reorders each acting prompt so that its static instructions come first and the
+runtime values relayed into it come last, giving every run of the same item an
+identical prompt prefix that an LLM provider's prompt cache can serve.
+
+- Source: a package of GEARS spec items produced by [text2gears](text2gears.md)
+  and, when scheduled, already rewritten by [optimize](optimize.md).
+- Target: the same package with eligible prompts laid out prefix-first.
+
+The pass is format-preserving: source and target are both GEARS packages, and
+the pass sits between [text2gears](text2gears.md) and
+[gears2fsm](gears2fsm.md), after [optimize](optimize.md) by pass-name order.
+A playbook compiled without this pass has identical observable behavior; the
+pass trades a compile-time rewrite for cheaper prompt processing at run time.
+
+Prompt caches are prefix caches: a provider serves the longest prefix it has
+already seen and processes everything after the first differing token afresh
+[[1]], [[2]], [[3]].
+A prompt that opens with this run's relayed request therefore shares nothing
+with the previous run's prompt for the same item, while one that opens with
+the item's instructions shares them all.
+
+## Formats
+
+| Role   | Format | Extension |
+| ------ | ------ | --------- |
+| source | gears  | .md       |
+| target | gears  | .md       |
+
+## Prompt regions
+
+Within an item's blockquote, each prompt line is one of:
+
+- a **relay line** — prompt content that begins with the literal quote marker
+  `>` (written `> > …` in the GEARS file), which is how
+  [text2gears](text2gears.md#authored-prompt-fragments) relays a runtime value
+  such as `> Original request: <caller-input>`;
+- a **blank line** — an empty prompt line, written `>`;
+- an **instruction line** — any other prompt line.
+
+A **relay block** is a maximal run of consecutive relay lines bounded by blank
+lines or the blockquote's edges, whether Source authored it as a separate
+quoted relay or set it apart with blank lines inside a fenced instruction.
+A relay line adjacent to an instruction line is authored content of that
+instruction — a quoted example inside a fenced instruction, for instance — and
+belongs to the instruction, not to a relay block.
+
+An instruction line may carry an inline `<placeholder>`, such as a configured
+model name; the pass never splits or rewrites an instruction line to isolate
+it.
+
+## Eligibility
+
+The pass shall rewrite an item only when **all** of the following hold:
+
+- The item is an acting item with a prompt: a direct-Captain, delegated-role,
+  or nested-playbook-call blockquote.
+  A script item (`Captain shall run:`) has no prompt and is never rewritten.
+- At least one relay block precedes an instruction line.
+  An item whose relay blocks already trail every instruction line is already
+  prefix-first and stays unchanged.
+- No instruction line depends on a relayed value standing before it — one
+  that refers to the relayed text as above or preceding, or that continues a
+  sentence the relay began.
+  A reference to the relayed text as below or following stays true after the
+  move.
+
+Judgment stays conservative: when eligibility is uncertain, the pass shall
+leave the item unchanged rather than guess.
+The pass shall not invent prompt lines, labels, or separators, and shall not
+rewrite, merge, split, or drop any line.
+
+Source prose that places a relay after an instruction, or an instruction at
+the end of the prompt, tells [text2gears](text2gears.md) how to compose the
+prompt faithfully; it does not make the item ineligible.
+This pass overrides that composition order by design, records the override in
+its provenance section, and `--no-optimize` restores it.
+
+## Rewriting
+
+For each eligible item, the pass shall rewrite only the blockquote:
+
+- Emit every line that is not part of a relay block, in its original order,
+  keeping each line byte-for-byte, dropping leading and trailing blank lines,
+  and replacing each run of removed relay blocks together with the blank lines
+  bounding it by the first of those blank lines where it separated two
+  remaining lines; every other blank line, such as one inside a fenced
+  template, stays where it is.
+- Emit one blank line.
+- Emit the relay blocks in their original order, each byte-for-byte, with one
+  blank line between consecutive blocks.
+- Keep the item's ID, heading, condition, acting clause, `Results:`, and any
+  other metadata unchanged.
+- Preserve every other item and every non-item section byte-for-byte,
+  including an `## Optimizations` section the optimize pass appended.
+
+Because no line changes, the target stays in the Source language and every
+authored fragment remains intact; only the order of relay blocks relative to
+instructions changes.
+
+E.g., the source item
+
+```markdown
+### REVIEW-2
+
+When Reviewer raises or keeps any finding, Captain shall relay the caller input and Reviewer's findings to Coder with the disposition prompt:
+
+> > Original request: <caller-input>
+> > Reviewer findings: <reviewer-output>
+>
+> For each review item, accept or reject it.
+> Report every disposition, all relevant run results, and every rebuttal.
+
+Results:
+- `committed`: Coder accepted at least one item and added one new review-fix commit. Output shall include `coderOutput: <verbatim final text>` and `latestCommit: <commit identity>`.
+- `rejectedAll`: Coder rejected every item and made no commit. Output shall include `coderOutput: <verbatim final text>`.
+```
+
+becomes
+
+```markdown
+### REVIEW-2
+
+When Reviewer raises or keeps any finding, Captain shall relay the caller input and Reviewer's findings to Coder with the disposition prompt:
+
+> For each review item, accept or reject it.
+> Report every disposition, all relevant run results, and every rebuttal.
+>
+> > Original request: <caller-input>
+> > Reviewer findings: <reviewer-output>
+
+Results:
+- `committed`: Coder accepted at least one item and added one new review-fix commit. Output shall include `coderOutput: <verbatim final text>` and `latestCommit: <commit identity>`.
+- `rejectedAll`: Coder rejected every item and made no commit. Output shall include `coderOutput: <verbatim final text>`.
+```
+
+## Provenance
+
+The target shall end with one `## Prefixed prompts` section — after an
+`## Optimizations` section when one is present — listing every rewritten
+item, one bullet per item in item order: `- <ITEM-ID>: relays → tail`.
+A section an earlier application left in the source is replaced, and the
+items it listed stay listed.
+When no item is eligible, the target shall be the source content unchanged;
+a package the pass never rewrote carries no `## Prefixed prompts` section.
+
+The section is what lets a Source-to-GEARS fidelity checker accept the new
+order: for a listed item it requires each instruction and relay block of the
+fragments the item carries intact, blank lines inside a block included, and
+used exactly once, the instruction blocks in Source order, the relay blocks in
+Source order, and every relay after the last instruction, a relay Source joined
+directly to an instruction staying beside it with its authored boundary, a bare
+relay the prose authored free to trail, and one occurrence standing for one
+authored fragment; for any other item it requires Source order throughout.
+
+## Deterministic rewriting
+
+The adjacent `prefix-prompts.mjs` tool performs this rewrite exactly:
+
+```sh
+node "<definition-directory>/prefix-prompts.mjs" --source "<source.gears.md>" --target "<target.gears.md>" [--keep <ITEM-ID>]...
+```
+
+It reads the source, rewrites every item eligible by the mechanical rules
+above, writes the one provenance section and the target, and prints the
+rewritten item IDs — or reports that no item was eligible and the target
+equals the source.
+`--keep` excludes an item the tool would otherwise rewrite.
+
+The pass shall use the tool rather than rewrite by hand:
+
+1. Read the source and decide, for each item with a relay block preceding an
+   instruction line, whether an instruction depends on a relay standing before
+   it; that judgment is the pass's only non-mechanical step.
+2. Run the tool with `--keep` for each item so excluded.
+3. Read the target and confirm that every listed item's instructions and
+   relays are intact and that nothing else changed.
+
+The tool writes only the declared target and never modifies the source.
+
+## Out of scope
+
+- Any change to prompt wording, conditions, result contracts, or item order.
+- Rewriting behaviors into one another; that is the [optimize](optimize.md)
+  pass.
+- Where a transport sends a prompt as one content block, the provider's cache
+  boundary is the transport's concern; this pass only makes the shared prefix
+  exist.
+
+## References
+
+[1]: https://platform.claude.com/docs/en/docs/build-with-claude/prompt-caching "Anthropic — Prompt caching: place static content at the beginning of the prompt"
+[2]: https://developers.openai.com/api/docs/guides/prompt-caching "OpenAI — Prompt caching: put stable instructions first, dynamic content at the end"
+[3]: https://ai.google.dev/gemini-api/docs/caching "Google — Gemini context caching: put large and common contents at the beginning of the prompt"

package/slc/slc.pin-inputs.json

@@ -2,6 +2,7 @@
   "schema": "sublang.slc.pin-inputs.v1",
   "closures": {
     "gears2fsm": ["text2gears.md", "link.md", "workflow-contracts.json"],
+    "prefix": ["prefix-prompts.mjs"],
     "link": [
       "text2gears.md",
       "gears2fsm.md",

package/src/xstate-playbook-runtime.d.ts

@@ -1,5 +1,5 @@
 import type { AnyStateMachine, EventObject, PromiseActorLogic } from 'xstate';
-import type { CaptainResult, JsonValue, PlaybookEffectBoundary, PlaybookEffectBoundaryStart, PlaybookEffectLedger, PlaybookEffectLedgerCapability, NormalizedError, PlaybookPendingBossQuestion, PlaybookPorts, PlaybookRepositoryReceipt, PlaybookRuntimeFactory, PlaybookSession, PlaybookState, PlayerResult } from './runtime.js';
+import type { CaptainResult, JsonValue, PlaybookEffectBoundary, PlaybookEffectBoundaryStart, PlaybookEffectLedger, PlaybookEffectLedgerCapability, NormalizedError, PlaybookFailureCause, PlaybookPendingBossQuestion, PlaybookPorts, PlaybookRepositoryReceipt, PlaybookRuntimeFactory, PlaybookSession, PlaybookState, PlayerResult } from './runtime.js';
 export interface PlaybookPendingBossQuestionContext {
     questionId: string;
     resumeStateId: string;
@@ -115,6 +115,33 @@ export declare const BOSS_REPLY_ERRORS: {
     readonly missingQuestion: "needsBossReply outcome missing 'question' field";
     readonly unregisteredState: (stateId: string) => string;
 };
+export declare const ABORTED_FAILURE_CAUSE: PlaybookFailureCause;
+export declare function runtimeDefectCause(reason: string): PlaybookFailureCause;
+export declare function playerFailureCause(input: {
+    readonly roleId: string;
+    readonly playerId?: string;
+    readonly error: unknown;
+}): PlaybookFailureCause;
+/**
+ * DR-063 §1: the cause of an unresolved governed settlement. A reconciled
+ * mismatch supplies its own receipt-read cause; the reasons a runtime owns map
+ * to adjudication, abort, and runtime-defect codes. Shared with DECIDE's
+ * bespoke runtime, which decides the same reasons.
+ */
+export declare function governedSettlementCause(reason: string, error: unknown, aborted: boolean, supplied: PlaybookFailureCause | undefined): PlaybookFailureCause;
+/**
+ * DR-063 §2: the causes decided for thrown values that cannot carry the
+ * marker — a string, a frozen error — kept by identity for as long as the
+ * failure stands, so every surface that reads the FSM's own `lastError`
+ * publishes the cause decided for exactly that value, whatever turn reads it.
+ * A value that carries the marker answers from it; the map is bounded, since
+ * only values that refuse the marker need an entry.
+ */
+export interface PlaybookFailureCauseRetention {
+    retain(error: unknown, cause: PlaybookFailureCause): void;
+    causeOf(error: unknown): PlaybookFailureCause | undefined;
+}
+export declare function createFailureCauseRetention(): PlaybookFailureCauseRetention;
 interface XStateRepositoryOperationSettlement<T> {
     readonly status: 'fulfilled';
     readonly value: T;
@@ -389,6 +416,13 @@ export declare function normalizeErrorFull(err: unknown): NormalizedError | unde
 export declare function pendingBossQuestionFromContext(context: Record<string, unknown>): PlaybookPendingBossQuestionContext | undefined;
 /** Add clarification context without repeating the question in a live conversation. */
 export declare function composePlayerContinuation(input: Pick<PlaybookPlayerInput, 'pendingBossQuestion' | 'bossReply'>, body: string, resuming?: boolean): string;
+/**
+ * The block for one governed call, or `undefined` where the call is not
+ * effect-authorized — a call whose declared outcomes carry no
+ * `one-descendant-commit` disposition may commit nothing, so it is told
+ * nothing.
+ */
+export declare function effectAuthorizedPreExistingBlock(effectBoundary: Pick<PlaybookEffectBoundaryStart, 'dispositions'>, baseline: PlaybookRepositoryReceipt['baseline'] | undefined): string | undefined;
 /**
  * Default player-prompt composer (slc/link.md §Player prompt composition).
  * One callback-based pass substitutes each `<fieldName>` placeholder whose