@sublang/slc 0.7.0 → 0.8.0

package/dist/verify.js

@@ -556,13 +556,14 @@ function structuredStateIdentityFindings(nodes) {
 }
 function enumerateCaptainBindings(config) {
     const out = [];
+    const initial = initialMachineContext(config) ?? {};
     for (const node of walkStateNodes(config)) {
         for (const invoke of normalizeInvokes(node.state.invoke)) {
             const source = invokeSource(invoke.src);
             const explicitlyWorkActor = source === 'captain' || source === 'player';
             if (!explicitlyWorkActor && invoke.src !== undefined)
                 continue;
-            const inspected = invocationInput(invoke);
+            const inspected = invocationInput(invoke, initial);
             if ('error' in inspected) {
                 if (explicitlyWorkActor) {
                     const actor = source === 'player' ? 'player' : 'captain';
@@ -688,11 +689,12 @@ export function enumerateCaptainStates(config) {
 }
 function enumeratePlaybookBindings(config) {
     const out = [];
+    const initial = initialMachineContext(config) ?? {};
     for (const node of walkStateNodes(config)) {
         for (const invoke of normalizeInvokes(node.state.invoke)) {
             if (invokeSource(invoke.src) !== 'playbook')
                 continue;
-            const inspected = invocationInput(invoke);
+            const inspected = invocationInput(invoke, initial);
             if ('error' in inspected) {
                 out.push({
                     state: malformedPlaybookState(publicStateId(node, undefined), `invoke.input threw during introspection: ${inspected.error}`, node),
@@ -730,6 +732,7 @@ function enumeratePlaybookBindings(config) {
                     const playbookIdSentinel = sentinelFor(fields.playbookIdContext);
                     const textSentinel = sentinelFor(fields.textContext);
                     const wired = invocationInput(invoke, {
+                        ...initial,
                         [fields.playbookIdContext]: playbookIdSentinel,
                         [fields.textContext]: textSentinel,
                     });
@@ -799,6 +802,7 @@ export function enumeratePlaybookStates(config) {
  */
 export function enumerateScriptStates(config) {
     const out = [];
+    const initial = initialMachineContext(config) ?? {};
     for (const node of walkStateNodes(config)) {
         for (const invoke of normalizeInvokes(node.state.invoke)) {
             if (invokeSource(invoke.src) !== 'script')
@@ -811,7 +815,7 @@ export function enumerateScriptStates(config) {
                 ...nestedStatePath(node),
                 bindingFindings: [finding],
             });
-            const inspected = invocationInput(invoke);
+            const inspected = invocationInput(invoke, initial);
             if ('error' in inspected) {
                 out.push(malformed(`invoke.input threw during introspection: ${inspected.error}`));
                 continue;
@@ -1482,13 +1486,15 @@ const sentinelFor = (field) => `«${field}»`;
  * Traces which context fields an `invoke.input` thunk reads, via a recording
  * proxy context; reads collected up to a throw are kept.
  */
-export function probeContextReads(inputFn) {
+export function probeContextReads(inputFn, 
+/** The machine's initial context, so a typed field does not truncate the trace. */
+initial = {}) {
     const reads = new Set();
-    const context = new Proxy({}, {
-        get(_target, prop) {
+    const context = new Proxy({ ...initial }, {
+        get(target, prop) {
             if (typeof prop === 'string')
                 reads.add(prop);
-            return undefined;
+            return Reflect.get(target, prop);
         },
         has() {
             return true;
@@ -1516,6 +1522,117 @@ const BOSS_CONTEXT_FIELDS = [
 function ordinaryContext(reads) {
     return sentinelContext(reads.filter((field) => !BOSS_CONTEXT_FIELDS.includes(field)));
 }
+/**
+ * The machine's resolved initial context (verification-5): a literal record, or
+ * the config's factory resolved with the declared initial input, so a typed
+ * context field an ordinary turn reads keeps its initial shape instead of a
+ * string sentinel. Returns undefined when no initial snapshot can be produced
+ * without running the machine — the caller then degrades to sentinels alone.
+ */
+function initialMachineContext(config) {
+    const declared = config.context;
+    if (declared === undefined)
+        return {};
+    if (typeof declared === 'object' && declared !== null) {
+        return { ...declared };
+    }
+    if (typeof declared !== 'function')
+        return undefined;
+    try {
+        const resolved = declared({
+            input: {},
+            spawn: () => undefined,
+            self: undefined,
+            event: { type: 'xstate.init' },
+        });
+        return typeof resolved === 'object' && resolved !== null
+            ? { ...resolved }
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The context an ordinary-turn probe drives an `invoke.input` thunk with: the
+ * machine's initial context, overlaid with one string sentinel per traced read
+ * whose initial value is absent or itself a string, and never a Boss-reply
+ * field (verification-5).
+ */
+function ordinaryTurnContext(reads, initial, 
+/** Traces the Boss-reply fields too, for wiring capture rather than a turn. */
+includeBossFields = false) {
+    if (initial === undefined) {
+        return includeBossFields ? sentinelContext(reads) : ordinaryContext(reads);
+    }
+    const context = { ...initial };
+    if (!includeBossFields) {
+        for (const field of BOSS_CONTEXT_FIELDS)
+            delete context[field];
+    }
+    for (const field of reads) {
+        if (!includeBossFields && BOSS_CONTEXT_FIELDS.includes(field))
+            continue;
+        const current = context[field];
+        if (current === undefined || typeof current === 'string') {
+            context[field] = sentinelFor(field);
+        }
+    }
+    return context;
+}
+// Input fields the composition contract itself owns: a placeholder naming one
+// of them relays no runtime value, so the probe never overwrites it.
+const CONTRACT_INPUT_FIELDS = [
+    'prompt',
+    'result',
+    'stateId',
+    'sourceItem',
+    'role',
+    'player',
+    ...BOSS_CONTEXT_FIELDS,
+];
+/** The canonical field a `<kebab-token>` placeholder relays: its segments joined camel-case. */
+function placeholderField(token) {
+    const segments = token.replace(/^<|>$/g, '').split('-');
+    return segments
+        .map((segment, index) => index === 0
+        ? segment
+        : segment.charAt(0).toUpperCase() + segment.slice(1))
+        .join('');
+}
+/**
+ * Overlays one string sentinel on every placeholder-derived input field the
+ * prompt relays, so a field the machine's initial context leaves empty or
+ * derives through a typed value still evidences substitution (verification-5).
+ * Returns the probed input and the sentinel field names it carries.
+ */
+function withPlaceholderValues(state, input) {
+    if (typeof input !== 'object' || input === null)
+        return { input, fields: [] };
+    const record = input;
+    const probed = { ...record };
+    const fields = [];
+    for (const token of placeholdersIn(state.prompt)) {
+        const field = placeholderField(token);
+        if (field === '' || CONTRACT_INPUT_FIELDS.includes(field))
+            continue;
+        if (typeof record[field] !== 'string')
+            continue;
+        probed[field] = sentinelFor(field);
+        if (!fields.includes(field))
+            fields.push(field);
+    }
+    return { input: probed, fields };
+}
+/** Every canonical local role the artifact's player states declare (verification-1). */
+function declaredLocalRoles(config) {
+    const roles = new Set();
+    for (const state of enumerateCaptainStates(config)) {
+        if (state.role !== undefined)
+            roles.add(state.role);
+    }
+    return [...roles].sort();
+}
 function carriesSentinel(value, sentinel) {
     try {
         return (JSON.stringify(value) ?? '').includes(sentinel);
@@ -1531,14 +1648,17 @@ function carriesSentinel(value, sentinel) {
  */
 export function capturePromptContract(config) {
     const rows = [];
+    const initial = initialMachineContext(config);
     for (const binding of enumerateCaptainBindings(config)) {
         const { state, inputFn } = binding;
         if (typeof inputFn !== 'function')
             continue;
-        const reads = probeContextReads(inputFn);
+        const reads = probeContextReads(inputFn, initial);
         const wires = {};
         try {
-            const input = inputFn({ context: sentinelContext(reads) });
+            const input = inputFn({
+                context: ordinaryTurnContext(reads, initial, true),
+            });
             if (typeof input === 'object' && input !== null) {
                 for (const [key, value] of Object.entries(input)) {
                     const carried = reads.filter((field) => carriesSentinel(value, sentinelFor(field)));
@@ -1570,6 +1690,8 @@ export function capturePromptContract(config) {
  */
 export function deriveSubstitutions(config, compose, actor) {
     const out = {};
+    const roles = declaredLocalRoles(config);
+    const initial = initialMachineContext(config);
     for (const binding of enumerateCaptainBindings(config)) {
         const { state, inputFn } = binding;
         if (actor !== undefined && state.actor !== actor)
@@ -1577,8 +1699,9 @@ export function deriveSubstitutions(config, compose, actor) {
         if (typeof inputFn !== 'function')
             continue;
         try {
-            const reads = probeContextReads(inputFn);
-            const composed = composeForState(compose, state, inputFn({ context: ordinaryContext(reads) }));
+            const reads = probeContextReads(inputFn, initial);
+            const probed = withPlaceholderValues(state, inputFn({ context: ordinaryTurnContext(reads, initial) }));
+            const composed = composeForState(compose, state, probed.input, roles);
             if (typeof composed !== 'string') {
                 out[state.stateId] = [];
                 continue;
@@ -1589,7 +1712,7 @@ export function deriveSubstitutions(config, compose, actor) {
             // hide valid evidence, while merely deleting a token still cannot
             // masquerade as substitution.
             const evidenced = new Set();
-            const promptReads = promptSentinelFields(state, reads);
+            const promptReads = promptSentinelFields(state, reads, probed.fields, roles);
             for (const line of state.prompt.split('\n')) {
                 for (const token of matchPromptBody(line, composed, promptReads)
                     ?.substitutions ?? []) {
@@ -1615,6 +1738,11 @@ export function deriveSubstitutions(config, compose, actor) {
 export function checkPromptComposition(opts) {
     const findings = [];
     const controller = isControllerMachine(opts.config);
+    const roles = declaredLocalRoles(opts.config);
+    const initial = initialMachineContext(opts.config);
+    if (initial === undefined) {
+        opts.diagnostics?.push('the machine has no resolvable initial context; ordinary-turn input is synthesized from context sentinels alone');
+    }
     const schemaResolution = resolveArtifactSchemaForVerification({
         config: opts.config,
         ...(opts.artifactSchema === undefined
@@ -1632,12 +1760,14 @@ export function checkPromptComposition(opts) {
             continue;
         if (typeof inputFn !== 'function')
             continue;
-        const reads = probeContextReads(inputFn);
-        const promptReads = promptSentinelFields(state, reads);
+        const reads = probeContextReads(inputFn, initial);
         const substituted = substitutions[state.stateId] ?? [];
         let ordinary;
+        let promptReads;
         try {
-            ordinary = composeForState(opts.compose, state, inputFn({ context: ordinaryContext(reads) }));
+            const probed = withPlaceholderValues(state, inputFn({ context: ordinaryTurnContext(reads, initial) }));
+            promptReads = promptSentinelFields(state, reads, probed.fields, roles);
+            ordinary = composeForState(opts.compose, state, probed.input, roles);
             if (typeof ordinary !== 'string') {
                 throw new Error(`${composerName} returned a non-string value`);
             }
@@ -1692,9 +1822,9 @@ export function checkPromptComposition(opts) {
         let continuation;
         let input;
         try {
-            input = inputFn({
+            const probed = withPlaceholderValues(state, inputFn({
                 context: {
-                    ...ordinaryContext(reads),
+                    ...ordinaryTurnContext(reads, initial),
                     pendingBossQuestion,
                     bossReply: reply,
                     pendingBossQuestions: {
@@ -1702,8 +1832,10 @@ export function checkPromptComposition(opts) {
                     },
                     bossReplies: { [state.stateId]: reply },
                 },
-            });
-            continuation = composeForState(opts.compose, state, input);
+            }));
+            input = probed.input;
+            promptReads = promptSentinelFields(state, reads, probed.fields, roles);
+            continuation = composeForState(opts.compose, state, input, roles);
             if (typeof continuation !== 'string') {
                 throw new Error(`${composerName} returned a non-string value`);
             }
@@ -1746,12 +1878,13 @@ export function checkPromptComposition(opts) {
     }
     return findings;
 }
-function promptSentinelFields(state, reads) {
+function promptSentinelFields(state, reads, placeholderFields, declaredRoles) {
+    const fields = [...reads, ...placeholderFields];
     return state.role === undefined
-        ? [...reads]
-        : [...reads, `promptIdentity:${state.role}`];
+        ? fields
+        : [...fields, ...declaredRoles.map((role) => `promptIdentity:${role}`)];
 }
-function composeForState(compose, state, input) {
+function composeForState(compose, state, input, declaredRoles) {
     // Schema-1 composers and the shared default composer use their second
     // positional argument as a placeholder-field map. A callable proxy with a
     // property-clean view is therefore both an invocation-scoped schema-3 lookup
@@ -1761,8 +1894,11 @@ function composeForState(compose, state, input) {
         if (state.role === undefined) {
             throw new Error(`prompt identity lookup used role ${JSON.stringify(roleId)} for a direct-Captain or historical state`);
         }
-        if (roleId !== state.role) {
-            throw new Error(`prompt identity lookup used role ${JSON.stringify(roleId)} instead of canonical local role ${JSON.stringify(state.role)}`);
+        // A prompt may name any declared role's identity — a Coder prompt reaches
+        // the Reviewer's `<reviewer-llm>` — so only an undeclared role is drift
+        // (link.md, "Player prompt composition").
+        if (!declaredRoles.includes(roleId)) {
+            throw new Error(`prompt identity lookup used undeclared role ${JSON.stringify(roleId)}; the artifact declares ${JSON.stringify(declaredRoles)}`);
         }
         return sentinelFor(`promptIdentity:${roleId}`);
     };
@@ -2316,6 +2452,135 @@ export function resolveArtifactSchemaForVerification(opts) {
         }
         : { findings: [] };
 }
+/** The `_internal` composer export serving one state actor (verification-5). */
+const COMPOSER_EXPORTS = {
+    captain: 'composeCaptainPrompt',
+    player: 'composePlayerPrompt',
+};
+/**
+ * Runs the deterministic prompt-contract checks over one live linked module
+ * beside its FSM (verification-5, verification-27): the module imports through
+ * the ephemeral TypeScript FSM edge, its schema evidence reconciles, and every
+ * actor the machine invokes has a composer that honors the link contract.
+ *
+ * Shared by the emitted suite's generator, which pins the derived substitutions
+ * and degrades each observation to a diagnostic, and by the link-fidelity gate,
+ * which relays the same observations as findings — so the gate adds no check of
+ * its own (DR-030).
+ */
+async function inspectLinkedPromptContract(opts) {
+    const { config, evidence } = opts;
+    const withoutModule = (extra) => {
+        const resolution = resolveArtifactSchemaForVerification({
+            config,
+            ...evidence,
+        });
+        return {
+            ...(resolution.artifactSchema === undefined
+                ? {}
+                : { artifactSchema: resolution.artifactSchema }),
+            schemaFindings: resolution.findings,
+            present: true,
+            composers: [],
+            ...extra,
+        };
+    };
+    if (!existsSync(opts.linkedPath))
+        return withoutModule({ present: false });
+    let linked;
+    try {
+        linked = (await loadLinkedModuleForVerification({
+            linkedPath: opts.linkedPath,
+            fsmPath: opts.fsmPath,
+        }));
+    }
+    catch (error) {
+        return withoutModule({ loadError: messageOf(error) });
+    }
+    const resolution = resolveArtifactSchemaForVerification({
+        config,
+        linked,
+        ...evidence,
+    });
+    const artifactSchema = resolution.artifactSchema;
+    const actors = new Set(enumerateCaptainStates(config).map(({ actor }) => actor));
+    const composers = [];
+    for (const actor of ['captain', 'player']) {
+        if (!actors.has(actor))
+            continue;
+        const exportName = COMPOSER_EXPORTS[actor];
+        const compose = linked._internal?.[exportName];
+        if (typeof compose !== 'function') {
+            composers.push({ actor, exportName, findings: [], diagnostics: [] });
+            continue;
+        }
+        const typedCompose = compose;
+        const diagnostics = [];
+        composers.push({
+            actor,
+            exportName,
+            substitutions: deriveSubstitutions(config, typedCompose, actor),
+            findings: checkPromptComposition({
+                config,
+                compose: typedCompose,
+                actor,
+                ...(artifactSchema === undefined ? {} : { artifactSchema }),
+                diagnostics,
+            }),
+            diagnostics,
+        });
+    }
+    return {
+        ...(artifactSchema === undefined ? {} : { artifactSchema }),
+        schemaFindings: resolution.findings,
+        present: true,
+        composers,
+    };
+}
+/**
+ * The deterministic link-fidelity checks over one live linked `playbook` module
+ * beside its FSM (verification-27): exactly the checks the emitted
+ * prompt-contract suite asserts, decided from those two paths alone and
+ * returning one finding per violation.
+ *
+ * The gate that runs this before any Reviewer call must never throw into the
+ * executor it guards (DR-030, phase-execution-53), so a module that cannot be
+ * imported yields its import diagnostic as a finding. An absent module or FSM
+ * yields none: an artifact the performing call has not written is the generic
+ * target check's business (phase-execution-4). An FSM that cannot be imported
+ * yields none either — the suite's checks derive from that machine, so they
+ * degrade exactly as emission degrades its prompt-contract test to a
+ * diagnostic (verification-5).
+ */
+export async function checkLinkedModuleContract(opts) {
+    if (!existsSync(opts.linkedPath) || !existsSync(opts.fsmPath))
+        return [];
+    let config;
+    try {
+        config = findMachineConfig(await loadFsmModule(opts.fsmPath));
+    }
+    catch {
+        return [];
+    }
+    const contract = await inspectLinkedPromptContract({
+        config,
+        linkedPath: opts.linkedPath,
+        fsmPath: opts.fsmPath,
+        evidence: {},
+    });
+    const findings = [...contract.schemaFindings];
+    if (contract.loadError !== undefined) {
+        findings.push(`linked module could not be imported: ${contract.loadError}`);
+        return findings;
+    }
+    // A module exposing no matching composer degrades exactly as emission does
+    // (verification-5): the suite asserts nothing about it, so neither does the
+    // gate that reuses the suite's checks.
+    for (const composer of contract.composers) {
+        findings.push(...composer.findings);
+    }
+    return findings;
+}
 /**
  * Emits the prompt-contract test beside a compiled `playbook` artifact
  * (verification-5): derives and pins the per-state contract from the physical
@@ -2344,66 +2609,39 @@ export async function emitPromptContractTest(opts) {
             ? {}
             : { artifactSchema: opts.artifactSchema }),
     };
-    let schemaResolution = resolveArtifactSchemaForVerification({
+    const contract = await inspectLinkedPromptContract({
         config,
-        ...evidence,
+        linkedPath: join(opts.artifactDir, `${opts.basename}.playbook.ts`),
+        fsmPath,
+        evidence,
     });
-    let artifactSchema = schemaResolution.artifactSchema;
-    let composer;
-    const linkedPath = join(opts.artifactDir, `${opts.basename}.playbook.ts`);
-    if (existsSync(linkedPath)) {
-        try {
-            const linked = (await loadLinkedModuleForVerification({
-                linkedPath,
-                fsmPath,
-            }));
-            schemaResolution = resolveArtifactSchemaForVerification({
-                config,
-                linked,
-                ...evidence,
-            });
-            artifactSchema = schemaResolution.artifactSchema;
-            const actors = new Set(enumerateCaptainStates(config).map(({ actor }) => actor));
-            const substitutions = {};
-            for (const actor of ['captain', 'player']) {
-                if (!actors.has(actor))
-                    continue;
-                const exportName = actor === 'captain' ? 'composeCaptainPrompt' : 'composePlayerPrompt';
-                const compose = linked._internal?.[exportName];
-                if (typeof compose !== 'function') {
-                    diagnostics.push(`prompt contract: linked module exposes no _internal.${exportName}; ${actor} composition checks not emitted`);
-                    continue;
-                }
-                const typedCompose = compose;
-                substitutions[actor] = deriveSubstitutions(config, typedCompose, actor);
-                const findings = checkPromptComposition({
-                    config,
-                    compose: typedCompose,
-                    actor,
-                    ...(artifactSchema === undefined ? {} : { artifactSchema }),
-                });
-                diagnostics.push(...findings.map((finding) => `prompt contract: ${finding}`));
-            }
-            if (substitutions.captain !== undefined ||
-                substitutions.player !== undefined) {
-                composer = {
-                    playbookModule: `./${opts.basename}.playbook.js`,
-                    ...substitutions,
-                };
-            }
-        }
-        catch (error) {
-            diagnostics.push(`prompt contract: linked module could not be imported (${messageOf(error)}); composition checks not emitted`);
+    const artifactSchema = contract.artifactSchema;
+    if (contract.loadError !== undefined) {
+        diagnostics.push(`prompt contract: linked module could not be imported (${contract.loadError}); composition checks not emitted`);
+    }
+    const substitutions = {};
+    for (const inspected of contract.composers) {
+        if (inspected.substitutions === undefined) {
+            diagnostics.push(`prompt contract: linked module exposes no _internal.${inspected.exportName}; ${inspected.actor} composition checks not emitted`);
+            continue;
         }
+        substitutions[inspected.actor] = inspected.substitutions;
+        diagnostics.push(...inspected.diagnostics.map((diagnostic) => `prompt contract: ${diagnostic}`), ...inspected.findings.map((finding) => `prompt contract: ${finding}`));
     }
-    diagnostics.unshift(...schemaResolution.findings.map((finding) => `prompt contract: ${finding}`));
+    const composer = substitutions.captain !== undefined || substitutions.player !== undefined
+        ? {
+            playbookModule: `./${opts.basename}.playbook.js`,
+            ...substitutions,
+        }
+        : undefined;
+    diagnostics.unshift(...contract.schemaFindings.map((finding) => `prompt contract: ${finding}`));
     const content = generatePromptContractTest({
         basename: opts.basename,
         fsmModule: `./${opts.basename}.fsm.js`,
         verifyModule: opts.verifyModule ?? VERIFY_MODULE,
         rows,
         ...(artifactSchema === undefined ? {} : { artifactSchema }),
-        schemaFindings: schemaResolution.findings,
+        schemaFindings: contract.schemaFindings,
         composer,
     });
     await mkdir(opts.artifactDir, { recursive: true });