@sublang/playbook 13.3.0 → 14.0.0

package/slc/scaffold-fsm.mjs

@@ -0,0 +1,225 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+
+import { randomUUID } from 'node:crypto';
+import { link, readFile, unlink, writeFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HEADING = /^### ([A-Za-z][\w-]*)$/;
+const QUOTE = /^>[ \t]?(.*)$/;
+const RESULT = /^- `([A-Za-z_$][A-Za-z0-9_$]*)`: (\S(?:.*\S)?)$/;
+const HELP = 'Usage: node scaffold-fsm.mjs --source <GEARS.md> --out <new.fsm.ts>\nCreates an incomplete authoring scaffold; ordinary compiler checks remain required.\n';
+
+function refuse(message) {
+  throw new Error(message);
+}
+
+/** A closed copying profile, not a GEARS semantic compiler. */
+function sourceItems(source) {
+  if (/[\r\u2028\u2029\uFEFF]/.test(source)) refuse('unsupported line encoding; the scaffold profile requires LF text');
+  if (source.split('\n').some(line => /^\s*(```|~~~)/.test(line))) refuse('fenced source bodies are outside this profile');
+  const items = [];
+  let current;
+  for (const line of source.split('\n')) {
+    if (line.startsWith('###')) {
+      const heading = HEADING.exec(line);
+      if (!heading) refuse('unsupported item heading');
+      if (items.some(item => item.id === heading[1])) refuse('duplicate item id');
+      current = { id: heading[1], lines: [] };
+      items.push(current);
+    } else if (/^#{1,2} /.test(line)) {
+      current = undefined;
+    } else if (current) {
+      current.lines.push(line);
+    }
+  }
+  if (items.length === 0) refuse('no supported item headings');
+  const prompted = [];
+  for (const { id, lines } of items) {
+    const first = lines.findIndex(line => QUOTE.test(line));
+    const preamble = lines.slice(0, first === -1 ? lines.length : first);
+    if (preamble.some(line => /Parallel group:|Captain shall run\s*:|Captain shall call playbook selected by/.test(line))) {
+      refuse(`${id}: script, dynamic or parallel item is outside this profile`);
+    }
+    if (first === -1) {
+      if (lines.some(line => /Captain shall|^Results\b/.test(line))) refuse(`${id}: acting item has no blockquote`);
+      continue;
+    }
+    const before = preamble.join(' ');
+    const child = /\bCaptain shall call playbook (?:`([A-Za-z0-9][\w.-]*)`|([A-Za-z0-9][\w.-]*)):\s*$/.exec(before.trim());
+    const player = /\bCaptain shall (?:prompt ([A-Z][\w]*)|relay\b[^.]*?\bto ([A-Z][\w]*)):\s*$/.exec(before.trim());
+    if (!child && /\bCaptain shall call playbook\b/.test(before)) refuse(`${id}: unsupported nested-call form`);
+    if (!player && /\bCaptain shall (?:prompt|relay)\b/.test(before)) refuse(`${id}: unsupported delegated-role form`);
+    if (!child && !player && !/\bCaptain shall\b.*:\s*$/.test(before.trim())) refuse(`${id}: unsupported acting clause`);
+    if (/Results\s*:/.test(before)) refuse(`${id}: Results precedes its prompt`);
+    const prompt = [];
+    let cursor = first;
+    while (cursor < lines.length) {
+      const quote = QUOTE.exec(lines[cursor]);
+      if (!quote) break;
+      prompt.push(quote[1]);
+      cursor++;
+    }
+    const after = lines.slice(cursor);
+    if (after.some(line => QUOTE.test(line))) refuse(`${id}: noncontiguous prompt`);
+    const nonblank = after.filter(line => line.trim() !== '');
+    let results;
+    if (nonblank.some(line => /^Results\b/.test(line))) {
+      if (child) refuse(`${id}: nested-call Results are forbidden`);
+      if (nonblank[0] !== 'Results:') refuse(`${id}: Results must immediately follow its prompt`);
+      results = [];
+      for (const line of nonblank.slice(1)) {
+        const result = RESULT.exec(line);
+        if (!result) refuse(`${id}: malformed Results entry`);
+        if (results.some(([guard]) => guard === result[1])) refuse(`${id}: duplicate Results guard`);
+        results.push([result[1], result[2]]);
+      }
+      if (results.length === 0) refuse(`${id}: empty Results block`);
+    } else if (!child && nonblank.length > 0) {
+      refuse(`${id}: trailing acting-item prose is outside this profile`);
+    }
+    prompted.push({ id, actor: child ? 'playbook' : player ? 'player' : 'captain', prompt: prompt.join('\n'), results });
+  }
+  if (prompted.length === 0) refuse('no supported prompted items');
+  return prompted;
+}
+
+function sourceLicense(source) {
+  const header = /^(?:<!--[^]*?-->\s*)+/.exec(source)?.[0] ?? '';
+  return [...header.matchAll(/<!--\s*(SPDX-[^]*?)\s*-->/g)]
+    .flatMap(match => match[1].split('\n').map(line => `// ${line.trim()}`))
+    .join('\n');
+}
+
+const CHILD_VALIDATION_IMPORTS = `import { validatePlaybookCallResult } from '@sublang/playbook/xstate-runtime';
+import type { PlaybookCallResult } from '@sublang/playbook/runtime';`;
+
+const CHILD_VALIDATION_HELPER = `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;
+  }
+}`;
+
+function render(source, items) {
+  const kinds = [...new Set(items.map(item => item.actor))];
+  const constants = items.map(item => {
+    const result = item.results === undefined ? 'undefined' : `{ ${item.results.map(([guard, description]) => `[${JSON.stringify(guard)}]: ${JSON.stringify(description)}`).join(', ')} }`;
+    return `  [${JSON.stringify(item.id)}]: { prompt: ${JSON.stringify(item.prompt)}, result: ${result} }`;
+  }).join(',\n');
+  const types = kinds.map(kind => {
+    const title = kind[0].toUpperCase() + kind.slice(1);
+    if (kind === 'playbook') return `export type PlaybookInput = { stateId: string; sourceItem: string; playbookId: string; text: string };\nexport type PlaybookOutput = JsonValue | undefined;`;
+    return `export type ${title}Input = { stateId: string; sourceItem: string; ${kind === 'player' ? 'role: string; ' : ''}prompt: string; result: Readonly<Record<string, string>> } & __AUTHOR_${kind.toUpperCase()}_FIELDS__;\nexport type ${title}Output = __AUTHOR_${kind.toUpperCase()}_OUTPUT__;`;
+  }).join('\n');
+  const actors = kinds.map(kind => {
+    const title = kind[0].toUpperCase() + kind.slice(1);
+    return `    ${kind}: fromPromise<${title}Output, ${title}Input>(async () => { throw new Error('${kind} actor must be provided by the runner'); })`;
+  }).join(',\n');
+  const json = kinds.includes('playbook') ? `export type JsonValue = null | boolean | number | string | readonly JsonValue[] | { readonly [key: string]: JsonValue };\n` : '';
+  const license = sourceLicense(source);
+  return `${license ? `${license}\n\n` : ''}// INCOMPLETE AUTHORING SCAFFOLD: replace every __AUTHOR_* marker and finish the workflow.
+// Read the complete GEARS Source and phase definition; constants are not its routing semantics.
+import { assign, fromPromise, setup } from 'xstate';
+${kinds.includes('playbook') ? `${CHILD_VALIDATION_IMPORTS}\n` : ''}
+// Acting prompts stay literal; carry runtime values beside invoke.input.prompt.
+// Nested prompts are templates: compose child text under the phase's actual rules.
+// Results are only authored declarations. Apply the phase's default/question/controller rules.
+export const GEARS_ITEMS = {
+${constants}
+} as const;
+
+type Context = __AUTHOR_CONTEXT__;
+type Event = __AUTHOR_EVENTS__;
+export type MachineInput = __AUTHOR_MACHINE_INPUT__;
+export type MachineOutput = __AUTHOR_MACHINE_OUTPUT__;
+${json}${types}
+${kinds.includes('playbook') ? `\n${CHILD_VALIDATION_HELPER}\n` : ''}
+function invocationOutput(event: unknown): unknown {
+  return typeof event === 'object' && event !== null && 'output' in event ? event.output : undefined;
+}
+
+const actorSetup = setup({
+  types: {} as { context: Context; events: Event; input: MachineInput; output: MachineOutput },
+  actors: {
+${actors}
+  },
+});
+
+// Keep reusable completion assignments registered and reference their names.
+// A standalone typed action reused directly on onDone can mismatch external event types.
+const machineSetup = actorSetup.extend({
+  actions: {
+    rememberResult: assign(({ event }) => {
+      const output = invocationOutput(event);
+      // Narrow unknown output to the declared result arm before reading payload fields.
+      return __AUTHOR_CONTEXT_UPDATE_FROM_OUTPUT__;
+    }),
+  },
+});
+
+// Use machineSetup.createStateConfig(...) for shared transition/config fragments.
+// Agent-owned work includes routes, guards, public metadata, failures, Boss continuation,
+// actor value relays and any child-result predicates. No default topology is supplied.
+export const machine = machineSetup.createMachine({
+  ...__AUTHOR_MACHINE_CONFIG__,
+});
+`;
+}
+
+export async function scaffoldFsm({ sourcePath, outputPath }) {
+  const source = await readFile(sourcePath, 'utf8');
+  if (!outputPath.endsWith('.fsm.ts')) refuse('output must end in .fsm.ts');
+  if (resolve(sourcePath) === resolve(outputPath)) refuse('source and output must differ');
+  const items = sourceItems(source);
+  try {
+    const xstate = createRequire(resolve(outputPath))('xstate');
+    const typed = xstate.setup({});
+    if (typeof typed.extend !== 'function' || typeof typed.createStateConfig !== 'function') {
+      refuse('unsupported XState setup API');
+    }
+  } catch {
+    refuse('target dependencies must supply XState setup.extend and createStateConfig');
+  }
+  const target = render(source, items);
+  const staging = join(dirname(outputPath), `.fsm-scaffold-${randomUUID()}.tmp`);
+  try {
+    await writeFile(staging, target, { flag: 'wx' });
+    // Exclusive publication prevents replacing a target created after our read.
+    await link(staging, outputPath);
+  } finally {
+    await unlink(staging).catch(error => { if (error.code !== 'ENOENT') throw error; });
+  }
+  return { status: 'scaffold', bytes: Buffer.byteLength(target), items: items.length };
+}
+
+async function main(args) {
+  if (args.length === 1 && args[0] === '--help') {
+    process.stdout.write(HELP);
+    return;
+  }
+  const options = {};
+  for (let index = 0; index < args.length; index += 2) {
+    const key = args[index];
+    if (!['--source', '--out'].includes(key) || typeof args[index + 1] !== 'string' || args[index + 1].startsWith('--') || Object.hasOwn(options, key)) refuse(HELP.trim());
+    options[key] = args[index + 1];
+  }
+  if (!options['--source'] || !options['--out']) refuse(HELP.trim());
+  const result = await scaffoldFsm({ sourcePath: resolve(options['--source']), outputPath: resolve(options['--out']) });
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main(process.argv.slice(2)).catch(error => {
+    process.stderr.write(`FSM scaffold: ${error instanceof Error ? error.message : 'initialization failed'}\n`);
+    process.exitCode = 1;
+  });
+}

package/slc/slc.pin-inputs.json

@@ -0,0 +1,13 @@
+{
+  "schema": "sublang.slc.pin-inputs.v1",
+  "closures": {
+    "gears2fsm": ["text2gears.md", "link.md", "workflow-contracts.json"],
+    "link": [
+      "text2gears.md",
+      "gears2fsm.md",
+      "optimize.md",
+      "materialize-link.mjs",
+      "workflow-contracts.json"
+    ]
+  }
+}

package/slc/text2gears.md

@@ -76,9 +76,12 @@ text2gears shall not move a shared instruction ahead of behavior-specific contex
 
 Where Source says that a runtime value is relayed in quotes, the leading `>` is prompt content rather than Source-only blockquote syntax.
 If Source supplies a blockquoted template for that relay, text2gears shall keep one literal leading `>` on every quoted line; the target GEARS line therefore uses its outer blockquote marker followed by the literal marker, such as `> > Coder output: <coder-output>`.
-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.
+If Source names the relayed value but supplies no template, text2gears shall emit a bare quoted prompt-content line, exactly `> <token>`, written as `> > <token>` in the GEARS file because the first marker encloses the prompt and the second is literal content, without an added label or surrounding prose, and shall not summarize, paraphrase, or invent the relayed value.
 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.
 
+Apply each Source-authored relay to every acting behavior it governs, including relays described only in prose.
+Mentioning a value in a condition, result contract, or machine context does not deliver it to the acting role; its complete prompt blockquote shall carry the required quoted placeholder.
+
 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.
 
@@ -137,6 +140,10 @@ Results:
 - `delegation`: Captain selected a call. Output shall include `remainingPlan: <JSON-safe array>`, `nextPlaybookId: <stable id>`, and `nextPlaybookInput: <complete request>`.
 ```
 
+A `Results:` block continues until the next item or section heading; after the label, emit only result bullets and blank lines.
+Put other acting-item conditions and invariants before the acting blockquote, never between the blockquote and `Results:` or after its bullets.
+Nested-call items remain without `Results:` and keep their child-continuation prose after the blockquote.
+
 `Results:` shall be a plain label rather than a heading.
 Every result shall occupy one bullet with exactly a backtick-delimited guard
 name, a colon, and a non-empty description.
@@ -145,6 +152,13 @@ The guard name shall match the ASCII identifier pattern
 The bullet order is authoritative, guard names are unique within the item, and
 the description shall name every required output property with its exact
 case-sensitive identifier.
+After `Output shall include`, reserve backticks for output-field declarations.
+Keep each declaration outside plain-text parentheses; explanatory symbols in
+parenthetical guidance use plain text, never separate backticks, because those
+backticks would declare extra required fields. Guidance may instead occur
+inside a field's complete annotation, including any parentheses there.
+For example, use `` `codeCommit` (new code-owned commit) `` or
+`` `codeCommit: <new code-owned commit>` ``, without backticks around code.
 An output property name shall match the same ASCII identifier pattern as a
 guard name: a kebab-case Source placeholder such as `<coder-output>` names the
 property `coderOutput` through the canonical kebab-token-to-camel-field mapping
@@ -187,6 +201,10 @@ contract, so text2gears shall not invent a one-bullet `Results:` block for it.
 When a later item does consume its output, the produced-value rule above
 applies instead.
 
+When Source requires a terminal return to the caller, preserve every returned value or fact and its return condition as an explicit workflow output obligation in GEARS.
+Merely naming a value in a completion predicate or an acting result does not state that the workflow returns it.
+Keep this non-acting requirement outside prompt blockquotes, in the item's pre-prompt prose, an explicit terminal-return clause in the relevant Results description, or existing nested-call continuation; do not create a Captain action solely to restate the return.
+
 ### Boss-reply continuation
 
 Where a direct-Captain or delegated-player behavior may ask Boss a question
@@ -197,6 +215,10 @@ when the answer changes its complete runtime prompt. It shall not emit a
 second item solely for "Boss answers," "after the question," or clearing the
 consumed question/reply. The FSM and linker own the same-leaf suspension,
 continuation blocks, and consumed-context cleanup.
+When such an authored result asks Boss and waits, its `Results:` description
+shall declare `question: <verbatim final text>` as an output property; the
+result name or prose saying that a question is asked is not the field
+declaration.
 
 This rule is an exception to splitting by accumulated prompt content below.
 Split only when Source requires a genuinely different acting behavior after
@@ -247,6 +269,11 @@ text2gears shall emit an item whose behavior uses
 complete JSON-safe input-text template for that call.
 The literal target id shall be a stable configured playbook id, not a slash
 command or module specifier.
+In both literal and dynamic nested-call forms, the behavior's verb phrase shall
+be exact: `Captain shall call playbook ...:`.
+Text2gears shall not insert sequencing words such as `first`, `then`, `next`,
+or `finally` between `shall` and `call`; required sequencing belongs in the
+`When` or `While` clause or in continuation prose around the item.
 A nested-call item shall carry no `Results:` label: the child's terminal result
 is its outcome, so Source's continuation after child success, abort, or failure
 stays as prose after the blockquote for
@@ -299,8 +326,16 @@ compiled items.
 The kind is defined here so every consumer of the GEARS format shares one
 item-syntax contract.
 
-A script item's blockquote is static shell text: it shall contain no
-`<placeholder>`, and Markdown escapes resolve exactly as in acting prompts.
+A script item's blockquote is static shell text apart from the
+`<placeholder>` forms an acting prompt may carry, which relay a runtime value
+the machine already retains; Markdown escapes resolve exactly as in acting
+prompts.
+A script reads no conversation and produces no prose, so a placeholder is
+sound there only to bind the command to a target the script cannot otherwise
+name — never to carry a value the script would have to interpret.
+It shall occupy a single-quoted shell word, so the authored command is valid
+shell as written and the compiled one binds a literal
+([gears2fsm "Setup"](gears2fsm.md#setup)).
 A script item shall carry a `Results:` label with exactly two bullets in this
 fixed interpretation: the first guard reports the script exiting with status
 zero, the second reports a nonzero exit status.