@sublang/playbook 17.2.0 → 17.4.0

package/reference/sdlc/inspect.playbook/inspect.playbook.ts

@@ -0,0 +1,184 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+// Generated by slc/materialize-link.mjs; governed by the complete slc/link.md.
+// FSM: "./inspect.fsm.js"; export: inspectMachine; strategies: shared defaults with labelled string relays and nested actors.
+import { inspectMachine as machine } from "./inspect.fsm.js";
+import type { PlayerInput as SourcePlayerInput } from "./inspect.fsm.js";
+import {
+  createXStatePlaybookRuntime, snapshotJsonValue,
+  composePlayerContinuation, type XStatePromptIdentity,
+  type PlaybookPlayerInput,
+  type XStatePlaybookRuntimeConstruction,
+  type XStatePlaybookRuntimeFactory,
+  type XStatePlaybookRuntimeSpecV3,
+} from '@sublang/playbook/xstate-runtime';
+export type {
+  PlayerResult,
+  PlayerCallOptions,
+  PlayerSessionStore,
+  CaptainResult,
+  CaptainCallOptions,
+  JsonValue,
+  NormalizedError,
+  PlaybookCallRequest,
+  PlaybookCallResult,
+  PlaybookCallStart,
+  PlaybookStateValue,
+  PlaybookState,
+  PlaybookPendingCall,
+  PlaybookRunResult,
+  PlaybookRuntime,
+  PlaybookRuntimeFactory,
+  PlaybookRuntimeSnapshot,
+  PlaybookSession,
+  PlaybookPorts,
+  PlaybookTraceEvent,
+  PlaybookTraceType,
+  PlaybookControlReceipt,
+  PlaybookControlView,
+} from '@sublang/playbook/runtime';
+
+export interface PlaybookRuntimeOptions {
+  readonly "discussionContext"?: string;
+}
+export type PlaybookHostCapabilities = XStatePlaybookRuntimeConstruction<
+  PlaybookRuntimeOptions, { readonly authority: object }
+>['hostCapabilities'];
+
+const OPTION_SCHEMA = {
+  "discussionContext": {
+    "type": "string",
+    "required": false
+  }
+} as const;
+const INPUT_MAPPING = {
+  "discussionContext": "discussionContext"
+} as const;
+const RESUMABLE_STATE_IDS: ReadonlySet<string> = new Set([
+  "inspecting"
+]);
+const UNFINISHED_FINAL_STATE_IDS: ReadonlySet<string> = new Set([
+  "unavailable"
+]);
+const VERBATIM_PAYLOAD_FIELDS: ReadonlySet<string> = new Set([
+  "report"
+]);
+export function validateOptions(value: unknown): PlaybookRuntimeOptions {
+  const captured = snapshotJsonValue(value === undefined ? {} : value, "INSPECT runtime options");
+  if (captured === null || typeof captured !== 'object' || Array.isArray(captured)) {
+    throw new TypeError("INSPECT runtime options must be an object");
+  }
+  const fields = captured as Readonly<Record<string, unknown>>;
+  for (const key of Object.keys(captured)) {
+    if (!Object.hasOwn(OPTION_SCHEMA, key)) throw new TypeError("INSPECT runtime options." + key + ' is not declared');
+  }
+  for (const [key, schema] of Object.entries(OPTION_SCHEMA) as [string, { type: string; required: boolean }][]) {
+    if (!Object.hasOwn(captured, key)) {
+      if (schema.required) throw new TypeError("INSPECT runtime options." + key + ' is required');
+    } else if (typeof fields[key] !== schema.type || (schema.type === 'number' && !Number.isFinite(fields[key]))) {
+      throw new TypeError("INSPECT runtime options." + key + ' must be a ' + schema.type);
+    }
+  }
+  return captured as unknown as PlaybookRuntimeOptions;
+}
+function renderPlayerPrompt(input: SourcePlayerInput, promptIdentity: XStatePromptIdentity, resuming = false): string {
+  const fields = input as unknown as Readonly<Record<string, unknown>>;
+  const mapping: Readonly<Record<string, string>> = {};
+  const identities: Readonly<Record<string, string>> = {};
+  const omitted = new Set<string>(["> Discussion context: <discussion-context>"]);
+  const fieldFor = (token: string): string => Object.hasOwn(mapping, token) ? mapping[token]! : (token === '#' ? 'irNumber' : token.replace(/-([A-Za-z0-9_$])/g, (_match: string, next: string) => next.toUpperCase()));
+  const parts = input.prompt.split(/(\r?\n)/);
+  let body = '';
+  for (let index = 0; index < parts.length; index += 2) {
+    const line = parts[index]!;
+    if (omitted.has(line)) {
+      const token = /<(#|[A-Za-z_$][A-Za-z0-9_$-]*)>$/.exec(line)![1]!;
+      if (fields[fieldFor(token)] === '') continue;
+    }
+    body += line.replace(/<(#|[A-Za-z_$][A-Za-z0-9_$-]*)>/g, (match: string, token: string): string => {
+      const value = Object.hasOwn(identities, token) ? promptIdentity(identities[token]!) : fields[fieldFor(token)];
+      if (typeof value !== 'string') return match;
+      return line.startsWith('> ') ? value.replace(/\r?\n/g, (ending: string) => ending + '> ') : value;
+    }) + (parts[index + 1] ?? '');
+  }
+  return composePlayerContinuation(input, body, resuming);
+}
+const composePlayerPrompt = (input: PlaybookPlayerInput, promptIdentity: XStatePromptIdentity, resuming?: boolean): string =>
+  renderPlayerPrompt(input as SourcePlayerInput, promptIdentity, resuming);
+const runtimeSpec = {
+  composePlayerPrompt,
+  ...{
+  "label": "INSPECT",
+  "compat": {
+    "artifactSchema": 3,
+    "runtimeAbi": 1
+  },
+  "entryEvent": {
+    "type": "START",
+    "textField": "inspectionRequest",
+    "contextField": "inspectionRequest"
+  },
+  "bossEvents": [],
+  "roleStates": {
+    "inspecting": {
+      "role": "inspector",
+      "label": "Inspector investigates the requested material and gives an evidence-based explanation."
+    }
+  },
+  "outcomeAuthority": {
+    "governedPlayerStates": {
+      "inspecting": {
+        "completed": {
+          "fields": {
+            "status": "semantic",
+            "report": "presentation"
+          },
+          "repositoryDisposition": "unchanged"
+        },
+        "unavailable": {
+          "fields": {
+            "status": "semantic",
+            "report": "presentation"
+          },
+          "repositoryDisposition": "unchanged"
+        },
+        "needsBossReply": {
+          "fields": {
+            "question": "presentation"
+          },
+          "repositoryDisposition": "unchanged"
+        }
+      }
+    }
+  },
+  "placeholderFields": {},
+  "transitionEventFields": [
+    "inspectionRequest",
+    "discussionContext",
+    "answer",
+    "questionId"
+  ],
+  "controlContextFields": [
+    "inspectionRequest"
+  ]
+},
+  snapshotOptions: validateOptions,
+  machineInput: (options: PlaybookRuntimeOptions) => Object.fromEntries(
+    Object.entries(INPUT_MAPPING).filter(([, key]) => options[key as keyof PlaybookRuntimeOptions] !== undefined)
+      .map(([field, key]) => [field, options[key as keyof PlaybookRuntimeOptions]]),
+  ),
+  verbatimPayloadFields: VERBATIM_PAYLOAD_FIELDS,
+  resumableStateIds: RESUMABLE_STATE_IDS,
+  unfinishedFinalStateIds: UNFINISHED_FINAL_STATE_IDS,
+} satisfies XStatePlaybookRuntimeSpecV3<PlaybookRuntimeOptions>;
+
+export const _internal = {
+  composePlayerPrompt,
+  RESUMABLE_STATE_IDS,
+  UNFINISHED_FINAL_STATE_IDS,
+  VERBATIM_PAYLOAD_FIELDS,
+};
+const createPlaybookRuntime: XStatePlaybookRuntimeFactory<
+  XStatePlaybookRuntimeConstruction<PlaybookRuntimeOptions, PlaybookHostCapabilities>, 3
+> = createXStatePlaybookRuntime<PlaybookRuntimeOptions, PlaybookHostCapabilities>(machine, runtimeSpec);
+export default createPlaybookRuntime;

package/reference/sdlc/inspect.playbook/inspect.registry.d.ts

@@ -0,0 +1,41 @@
+import { type PlaybookRuntimeOptions, type PlaybookHostCapabilities, type PlaybookRuntime } from './inspect.playbook.js';
+import type { PlaybookHostConstructionCapabilities } from '../code.playbook/playbook-captain.js';
+export interface PlaybookSummaryPolicy {
+    stateCountLabels: Readonly<Record<string, string>>;
+    copyPasteGuardNames: readonly string[];
+    savedCountsLine(counts: {
+        interruptions: number;
+        copyPastes: number;
+    }, rounds: number): string;
+}
+export type InspectOptions = PlaybookRuntimeOptions;
+export interface InspectPlaybookRegistryEntry {
+    id: 'inspect';
+    command: 'inspect';
+    intent: string;
+    artifactSchema: 3;
+    runtimeProfile: {
+        readonly kind: 'shared-factory';
+        readonly compat: {
+            readonly artifactSchema: 3;
+            readonly runtimeAbi: number;
+        };
+    };
+    requiredRoleIds: readonly ['inspector'];
+    concurrentRoleSets: readonly [];
+    summaryPolicy: PlaybookSummaryPolicy;
+    validateOptions(optionSlice: unknown): InspectOptions;
+    createRuntime(options: InspectOptions, hostCapabilities: PlaybookHostConstructionCapabilities & PlaybookHostCapabilities): PlaybookRuntime;
+}
+export declare const inspectStateCountLabels: {
+    readonly inspecting: "inspection round";
+};
+export declare const inspectCopyPasteGuardNames: readonly ["completed"];
+export declare function inspectSavedCountsLine(counts: {
+    interruptions: number;
+    copyPastes: number;
+}, rounds: number): string;
+export declare const inspectSummaryPolicy: PlaybookSummaryPolicy;
+export declare function validateInspectOptions(optionSlice: unknown): InspectOptions;
+export declare const inspectPlaybookRegistryEntry: InspectPlaybookRegistryEntry;
+export default inspectPlaybookRegistryEntry;

package/reference/sdlc/inspect.playbook/inspect.registry.js

@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+import createPlaybookRuntime, { validateOptions, } from './inspect.playbook.js';
+// INSPECT counts its delegated evidence-gathering calls as inspection rounds.
+export const inspectStateCountLabels = {
+    inspecting: 'inspection round',
+};
+export const inspectCopyPasteGuardNames = ['completed'];
+function countNoun(count, singular, plural = `${singular}s`) {
+    return `${count} ${count === 1 ? singular : plural}`;
+}
+export function inspectSavedCountsLine(counts, rounds) {
+    return [
+        'Saved you',
+        countNoun(counts.interruptions, 'interruption'),
+        'and',
+        countNoun(counts.copyPastes, 'copy-paste'),
+        'across',
+        countNoun(rounds, 'round'),
+        'of inspection.',
+    ].join(' ');
+}
+export const inspectSummaryPolicy = {
+    stateCountLabels: inspectStateCountLabels,
+    copyPasteGuardNames: inspectCopyPasteGuardNames,
+    savedCountsLine: inspectSavedCountsLine,
+};
+export function validateInspectOptions(optionSlice) {
+    return validateOptions(optionSlice);
+}
+export const inspectPlaybookRegistryEntry = {
+    id: 'inspect',
+    command: 'inspect',
+    intent: 'inspect supplied material or a running web interface and explain observed evidence without changing the repository',
+    artifactSchema: 3,
+    runtimeProfile: Object.freeze({
+        kind: 'shared-factory',
+        compat: createPlaybookRuntime.compat,
+    }),
+    requiredRoleIds: ['inspector'],
+    concurrentRoleSets: [],
+    summaryPolicy: inspectSummaryPolicy,
+    validateOptions: validateInspectOptions,
+    createRuntime(options, hostCapabilities) {
+        return createPlaybookRuntime({
+            configuredOptions: options,
+            hostCapabilities,
+        });
+    },
+};
+export default inspectPlaybookRegistryEntry;

package/reference/sdlc/inspect.playbook/inspect.registry.ts

@@ -0,0 +1,110 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+
+import createPlaybookRuntime, {
+  validateOptions,
+  type PlaybookRuntimeOptions,
+  type PlaybookHostCapabilities,
+  type PlaybookRuntime,
+} from './inspect.playbook.js';
+import type { PlaybookHostConstructionCapabilities } from '../code.playbook/playbook-captain.js';
+
+export interface PlaybookSummaryPolicy {
+  stateCountLabels: Readonly<Record<string, string>>;
+  copyPasteGuardNames: readonly string[];
+  savedCountsLine(
+    counts: { interruptions: number; copyPastes: number },
+    rounds: number,
+  ): string;
+}
+
+export type InspectOptions = PlaybookRuntimeOptions;
+
+export interface InspectPlaybookRegistryEntry {
+  id: 'inspect';
+  command: 'inspect';
+  intent: string;
+  artifactSchema: 3;
+  runtimeProfile: {
+    readonly kind: 'shared-factory';
+    readonly compat: {
+      readonly artifactSchema: 3;
+      readonly runtimeAbi: number;
+    };
+  };
+  requiredRoleIds: readonly ['inspector'];
+  concurrentRoleSets: readonly [];
+  summaryPolicy: PlaybookSummaryPolicy;
+  validateOptions(optionSlice: unknown): InspectOptions;
+  // The linked module types live authority as opaque (link-materialization);
+  // the Captain entry binds its own construction capabilities here.
+  createRuntime(
+    options: InspectOptions,
+    hostCapabilities: PlaybookHostConstructionCapabilities &
+      PlaybookHostCapabilities,
+  ): PlaybookRuntime;
+}
+
+// INSPECT counts its delegated evidence-gathering calls as inspection rounds.
+export const inspectStateCountLabels = {
+  inspecting: 'inspection round',
+} as const;
+
+export const inspectCopyPasteGuardNames = ['completed'] as const;
+
+function countNoun(
+  count: number,
+  singular: string,
+  plural = `${singular}s`,
+): string {
+  return `${count} ${count === 1 ? singular : plural}`;
+}
+
+export function inspectSavedCountsLine(
+  counts: { interruptions: number; copyPastes: number },
+  rounds: number,
+): string {
+  return [
+    'Saved you',
+    countNoun(counts.interruptions, 'interruption'),
+    'and',
+    countNoun(counts.copyPastes, 'copy-paste'),
+    'across',
+    countNoun(rounds, 'round'),
+    'of inspection.',
+  ].join(' ');
+}
+
+export const inspectSummaryPolicy: PlaybookSummaryPolicy = {
+  stateCountLabels: inspectStateCountLabels,
+  copyPasteGuardNames: inspectCopyPasteGuardNames,
+  savedCountsLine: inspectSavedCountsLine,
+};
+
+export function validateInspectOptions(optionSlice: unknown): InspectOptions {
+  return validateOptions(optionSlice);
+}
+
+export const inspectPlaybookRegistryEntry: InspectPlaybookRegistryEntry = {
+  id: 'inspect',
+  command: 'inspect',
+  intent:
+    'inspect supplied material or a running web interface and explain observed evidence without changing the repository',
+  artifactSchema: 3,
+  runtimeProfile: Object.freeze({
+    kind: 'shared-factory',
+    compat: createPlaybookRuntime.compat,
+  }),
+  requiredRoleIds: ['inspector'],
+  concurrentRoleSets: [],
+  summaryPolicy: inspectSummaryPolicy,
+  validateOptions: validateInspectOptions,
+  createRuntime(options, hostCapabilities) {
+    return createPlaybookRuntime({
+      configuredOptions: options,
+      hostCapabilities,
+    });
+  },
+};
+
+export default inspectPlaybookRegistryEntry;

package/slc/workflow-contracts.json

@@ -359,6 +359,47 @@
           }
         ]
       }
+    },
+    "inspect": {
+      "callInput": "text",
+      "output": {
+        "anyOf": [
+          {
+            "type": "object",
+            "properties": {
+              "status": {
+                "const": "complete"
+              },
+              "report": {
+                "type": "string",
+                "description": "Inspector's complete explanation; presentation evidence, not independent effect authority."
+              }
+            },
+            "required": [
+              "status",
+              "report"
+            ],
+            "additionalProperties": false
+          },
+          {
+            "type": "object",
+            "properties": {
+              "status": {
+                "const": "unavailable"
+              },
+              "report": {
+                "type": "string",
+                "description": "Inspector's complete explanation; presentation evidence, not independent effect authority."
+              }
+            },
+            "required": [
+              "status",
+              "report"
+            ],
+            "additionalProperties": false
+          }
+        ]
+      }
     }
   },
   "literalTargetBindings": {
@@ -366,6 +407,7 @@
     "decide": "decide",
     "code": "code",
     "branch": "branch",
-    "pr": "pr"
+    "pr": "pr",
+    "inspect": "inspect"
   }
 }