jsfe 1.5.0 → 1.7.0

package/dist/host/index.js

@@ -7,3 +7,10 @@
  */
 export * from './request.js';
 export * from './systemone-intent.js';
+export * from './intent-stages.js';
+export { createActionJournal, createMemoryActionStorage, ActionJournalError } from './action-journal.js';
+export { actionSessionSnapshot, checkpointActionSession } from './action-session.js';
+export { retainRecoveryState, applyRecoveryStatePolicy } from './recovery-policy.js';
+export { CheckpointCodecError } from './checkpoint-codec-error.js';
+export { createActionRecoveryIdentity, assertActionRecoveryIdentity, actionRecoveryIdentityMatches } from './recovery-identity.js';
+export { assertFlowHostCapabilities, JSFEHostCapabilityError } from './capabilities.js';

package/dist/host/intent-stages.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Two-stage intent detection — the instructions and the decoders, zero runtime imports.
+ *
+ *   Stage 1 (task 'detect_flow'):        which primary flow, if any, the latest message starts.
+ *   Stage 2 (task 'extract_parameters'): the values the user gave for the SELECTED flow's parameters.
+ *
+ * For each stage jsfe builds ONE instruction set per executor — `llm` (a text model) and `systemOne`
+ * (TypeSafe System One) — from the same rules and the same flow fields, and passes both to aiCallback as
+ * its 4th argument. The host is the executor: it runs either, or both as a hedge (the first complete
+ * answer wins and the other is cancelled), and returns the CANONICAL reply as a JSON string:
+ *   stage 1: { "flowName": "<name>" | "None" }
+ *   stage 2: { "parameters": { "<name>": value, … } }
+ * The decoders below turn either executor's raw answer into that reply, so the host never interprets one.
+ *
+ * What each stage reads, and nothing else:
+ *   stage 1: each primary flow's `description` (what should trigger it);
+ *   stage 2: the selected flow's `parameterInstructions` (optional: rules that span its parameters) and its
+ *            parameters — name, type, enum and `description` (that parameter's rule). Parameters marked
+ *            `internal: true` (or whose description begins "Internal") are the flow's own, never asked.
+ * System One answers only closed values (enum, boolean): its stage-2 instructions cover those parameters,
+ * so a flow with any free-text parameter is answered completely only by the LLM.
+ */
+import type { FlowParameterDefinition } from '../index.js';
+/** A noul at or above this is a yes. */
+export declare const STAGE_YES_THRESHOLD = 0.5;
+/** Stage 1, System One: two top flows that together reach this pick the higher one (prod 10-17). */
+export declare const STAGE_PAIR_SUM = 0.7;
+export interface StageTurn {
+    role: 'user' | 'assistant';
+    content: string;
+}
+export interface StageFlow {
+    id: string;
+    name: string;
+    description: string;
+}
+export interface StageParameter {
+    name: string;
+    type?: string;
+    enum?: string[];
+    description?: string;
+    internal?: boolean;
+    jsonSchema?: Record<string, unknown>;
+}
+export interface StageLlm {
+    system: string;
+    user: string;
+    schema: Record<string, unknown>;
+}
+export interface StageSystemOne<I> {
+    state: Record<string, unknown>;
+    questions: Record<string, unknown>;
+    index: I[];
+}
+export interface FlowQuestionRef {
+    id: string;
+    flow: number;
+}
+export type ParameterQuestionRef = {
+    id: string;
+    kind: 'enum';
+    param: string;
+    value: string;
+} | {
+    id: string;
+    kind: 'boolean';
+    param: string;
+};
+export interface FlowStageRequest {
+    task: 'detect_flow';
+    stage: 1;
+    input: string;
+    conversation: StageTurn[];
+    flows: StageFlow[];
+    llm: StageLlm;
+    systemOne: StageSystemOne<FlowQuestionRef>;
+}
+export interface ParameterStageRequest {
+    task: 'extract_parameters';
+    stage: 2;
+    input: string;
+    conversation: StageTurn[];
+    flow: {
+        id: string;
+        name: string;
+        parameterInstructions?: string;
+        parameters: StageParameter[];
+    };
+    llm: StageLlm;
+    /** null when the flow declares no enum or boolean parameter */
+    systemOne: StageSystemOne<ParameterQuestionRef> | null;
+    /** parameters only a text model can answer (free text) */
+    freeText: string[];
+}
+export type IntentStageRequest = FlowStageRequest | ParameterStageRequest;
+/** System One's answers, keyed by question id. */
+export type StageSystemOneAnswers = Record<string, {
+    noul?: unknown;
+} | undefined> | undefined;
+/** The flow's own parameters, never asked of the user. */
+export declare const isInternalParameter: (p: StageParameter | FlowParameterDefinition) => boolean;
+/** Stage 1's instructions for both executors. `flows` are the primaries offered. */
+export declare function buildFlowStage(input: string, conversation: StageTurn[], flows: StageFlow[]): FlowStageRequest;
+/** A text model's stage-1 answer as the canonical reply; throws when it names no offered flow. */
+export declare function decodeFlowLlm(text: string, stage: FlowStageRequest): {
+    flowName: string;
+};
+/**
+ * System One's stage-1 answers as the canonical reply, with the top three scores (for logs and a host's hedge
+ * policy) and `pair` when two close candidates picked the higher. Throws if any question is unanswered.
+ */
+export declare function decodeFlowSystemOne(answers: StageSystemOneAnswers, stage: FlowStageRequest, { threshold, pairSum }?: {
+    threshold?: number | undefined;
+    pairSum?: number | undefined;
+}): {
+    flowName: string;
+    scores: {
+        name: string;
+        p: number;
+    }[];
+    pair: boolean;
+};
+/**
+ * A System One "None" that is a near miss: the chance that at least one of its two top flows applies,
+ * 1 − (1 − p1)(1 − p2), clears the threshold — a flow is wanted and the doubt is which. A host hedge waits
+ * for the other executor on it rather than accepting "None".
+ */
+export declare function isNearMiss(scores: {
+    p: number;
+}[], threshold?: number): boolean;
+/** Does `parameters` hold anything stage 2 asks (a parameter that is not internal)? */
+export declare function hasStageParameters(parameters: (StageParameter | FlowParameterDefinition)[] | undefined): boolean;
+/** Stage 2's instructions for the selected flow, for both executors. */
+export declare function buildParameterStage(input: string, conversation: StageTurn[], flow: {
+    id: string;
+    name: string;
+    parameterInstructions?: string;
+    parameters?: (StageParameter | FlowParameterDefinition)[];
+}): ParameterStageRequest;
+/** A text model's stage-2 answer as the canonical reply: declared parameters with a value only. Throws on non-JSON. */
+export declare function decodeParametersLlm(text: string, stage: ParameterStageRequest): {
+    parameters: Record<string, unknown>;
+};
+/**
+ * System One's stage-2 answers as the canonical reply: an enum takes its argmax value if it clears the cut, a
+ * boolean is true if it clears it; otherwise the parameter is omitted (the flow asks), never set false.
+ */
+export declare function decodeParametersSystemOne(answers: StageSystemOneAnswers, stage: ParameterStageRequest, { threshold }?: {
+    threshold?: number | undefined;
+}): {
+    parameters: Record<string, unknown>;
+};
+/** Is this jsfe's stage request (a host's aiCallback receives it as the 4th argument)? */
+export declare function isIntentStageRequest(request: unknown): request is IntentStageRequest;
+//# sourceMappingURL=intent-stages.d.ts.map

package/dist/host/intent-stages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"intent-stages.d.ts","sourceRoot":"","sources":["../../src/host/intent-stages.ts"],"names":[],"mappings":"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"}

package/dist/host/intent-stages.js

@@ -0,0 +1,256 @@
+/**
+ * Two-stage intent detection — the instructions and the decoders, zero runtime imports.
+ *
+ *   Stage 1 (task 'detect_flow'):        which primary flow, if any, the latest message starts.
+ *   Stage 2 (task 'extract_parameters'): the values the user gave for the SELECTED flow's parameters.
+ *
+ * For each stage jsfe builds ONE instruction set per executor — `llm` (a text model) and `systemOne`
+ * (TypeSafe System One) — from the same rules and the same flow fields, and passes both to aiCallback as
+ * its 4th argument. The host is the executor: it runs either, or both as a hedge (the first complete
+ * answer wins and the other is cancelled), and returns the CANONICAL reply as a JSON string:
+ *   stage 1: { "flowName": "<name>" | "None" }
+ *   stage 2: { "parameters": { "<name>": value, … } }
+ * The decoders below turn either executor's raw answer into that reply, so the host never interprets one.
+ *
+ * What each stage reads, and nothing else:
+ *   stage 1: each primary flow's `description` (what should trigger it);
+ *   stage 2: the selected flow's `parameterInstructions` (optional: rules that span its parameters) and its
+ *            parameters — name, type, enum and `description` (that parameter's rule). Parameters marked
+ *            `internal: true` (or whose description begins "Internal") are the flow's own, never asked.
+ * System One answers only closed values (enum, boolean): its stage-2 instructions cover those parameters,
+ * so a flow with any free-text parameter is answered completely only by the LLM.
+ */
+/** A noul at or above this is a yes. */
+export const STAGE_YES_THRESHOLD = 0.5;
+/** Stage 1, System One: two top flows that together reach this pick the higher one (prod 10-17). */
+export const STAGE_PAIR_SUM = 0.7;
+// ── the rules: written once, rendered for both executors ─────────────────────────────────────────────
+const FLOW_TRUE = "The latest message, read with the conversation, is what the workflow's description says should start it: the user asks for its action or information, or raises the problem it exists to handle. Also when it accepts the assistant's offer in the conversation to start or resume it (assistant: \"Shall I try the payment again?\" → user: \"yes\").";
+const FLOW_FALSE = "It only shares a topic with the workflow, is not what the workflow's description covers, or is a greeting, an acknowledgement or a fragment that asks for nothing.";
+const PARAMETER_RULES = [
+    'Give a value only when the user gave it, in the latest message or earlier in the conversation. Never guess.',
+    "Write it as the parameter's rule says; otherwise the value alone, in the user's words (never the whole sentence around it).",
+    'A short answer to the assistant\'s last message ("1", "yes", "the first one") chooses what that message offered.',
+    'A value the user did not give is null.',
+];
+const ENUM_TRUE = (value) => `The parameter's rule makes \`${value}\` its value for what the user said.`;
+const ENUM_FALSE = 'Another value, or none, is its value; or the user has not said enough to tell.';
+const BOOLEAN_TRUE = "The parameter's rule makes it true for what the user said.";
+const BOOLEAN_FALSE = 'The rule does not make it true, or the user has not said enough to tell.';
+const isEnum = (p) => Array.isArray(p.enum) && p.enum.length > 0;
+const isBoolean = (p) => p.type === 'boolean';
+/** The flow's own parameters, never asked of the user. */
+export const isInternalParameter = (p) => p.internal === true || /^\s*internal\b/i.test(String(p.description ?? ''));
+const conversationText = (conversation, input) => `${conversation.length ? `<conversation>\n${conversation.map(t => `${t.role}: ${t.content}`).join('\n')}\n</conversation>\n` : ''}<latest-message>\n${input}\n</latest-message>`;
+const stateOf = (conversation, input, instructions) => ({
+    assistant_instructions: instructions,
+    conversation: conversation.map(t => ({ role: t.role, content: t.content })),
+    latest_message: input,
+});
+const jsonTail = (schema) => `\n\n<json-schema>\n${JSON.stringify(schema)}\n</json-schema>\n\nRespond ONLY with valid JSON matching the schema. No other text.`;
+// ── stage 1 ───────────────────────────────────────────────────────────────────────────────────────────
+/** Stage 1's instructions for both executors. `flows` are the primaries offered. */
+export function buildFlowStage(input, conversation, flows) {
+    const names = flows.map(f => f.name);
+    const schema = {
+        type: 'object', additionalProperties: false, required: ['flowName'],
+        properties: { flowName: { type: 'string', enum: [...names, 'None'] } },
+    };
+    const system = [
+        'Decide which workflow, if any, the latest message starts.',
+        `A workflow is chosen when: ${FLOW_TRUE}`,
+        `"None" when: ${FLOW_FALSE}`,
+        'Answer with the exact workflow name, or "None".',
+        '',
+        '<workflows>',
+        ...flows.map(f => `- ${f.name}: ${f.description}`),
+        '</workflows>',
+    ].join('\n') + jsonTail(schema);
+    const questions = {};
+    const index = [];
+    flows.forEach((f, i) => {
+        const id = `f${i}`;
+        questions[id] = {
+            type: 'noul', criteria: { true: FLOW_TRUE, false: FLOW_FALSE },
+            instructions: { flow: { name: f.name, description: f.description }, question: 'Should the latest message start the workflow in `flow`?' },
+        };
+        index.push({ id, flow: i });
+    });
+    return {
+        task: 'detect_flow', stage: 1, input, conversation, flows,
+        llm: { system, user: conversationText(conversation, input), schema },
+        systemOne: { state: stateOf(conversation, input, 'Decide which workflow, if any, the latest message starts.'), questions, index },
+    };
+}
+/** A text model's stage-1 answer as the canonical reply; throws when it names no offered flow. */
+export function decodeFlowLlm(text, stage) {
+    const parsed = parseJsonObject(text);
+    const said = String(parsed.flowName ?? '').trim();
+    if (/^(none|null)$/i.test(said)) {
+        return { flowName: 'None' };
+    }
+    else {
+        const flow = stage.flows.find(f => f.name.toLowerCase() === said.toLowerCase());
+        if (!flow)
+            throw new Error(`stage 1: "${said.slice(0, 60)}" is not an offered workflow`);
+        return { flowName: flow.name };
+    }
+}
+/**
+ * System One's stage-1 answers as the canonical reply, with the top three scores (for logs and a host's hedge
+ * policy) and `pair` when two close candidates picked the higher. Throws if any question is unanswered.
+ */
+export function decodeFlowSystemOne(answers, stage, { threshold = STAGE_YES_THRESHOLD, pairSum = STAGE_PAIR_SUM } = {}) {
+    const p = answered(answers, stage.systemOne.index);
+    const ranked = stage.systemOne.index.map(q => ({ name: stage.flows[q.flow].name, p: p.get(q.id) })).sort((a, b) => b.p - a.p);
+    const scores = ranked.slice(0, 3);
+    const [a, b] = ranked;
+    if (a && a.p >= threshold) {
+        return { flowName: a.name, scores, pair: false };
+    }
+    else if (a && b && a.p + b.p >= pairSum) {
+        return { flowName: a.name, scores, pair: true };
+    }
+    else {
+        return { flowName: 'None', scores, pair: false };
+    }
+}
+/**
+ * A System One "None" that is a near miss: the chance that at least one of its two top flows applies,
+ * 1 − (1 − p1)(1 − p2), clears the threshold — a flow is wanted and the doubt is which. A host hedge waits
+ * for the other executor on it rather than accepting "None".
+ */
+export function isNearMiss(scores, threshold = STAGE_YES_THRESHOLD) {
+    const [a = 0, b = 0] = (scores || []).map(s => Number(s?.p) || 0).sort((x, y) => y - x);
+    return a > 0 && 1 - (1 - a) * (1 - b) >= threshold;
+}
+// ── stage 2 ───────────────────────────────────────────────────────────────────────────────────────────
+/** Does `parameters` hold anything stage 2 asks (a parameter that is not internal)? */
+export function hasStageParameters(parameters) {
+    return (parameters || []).some(p => p && p.name && !isInternalParameter(p));
+}
+/** Stage 2's instructions for the selected flow, for both executors. */
+export function buildParameterStage(input, conversation, flow) {
+    const params = (flow.parameters || []).filter(p => p && p.name && !isInternalParameter(p))
+        .map(p => ({ name: p.name, ...(p.type ? { type: p.type } : {}), ...(Array.isArray(p.enum) ? { enum: [...p.enum] } : {}), description: String(p.description ?? ''), ...(p.jsonSchema ? { jsonSchema: structuredClone(p.jsonSchema) } : {}) }));
+    const typeOf = (p) => (p.type === 'boolean' ? 'boolean' : p.type === 'number' || p.type === 'integer' ? 'number' : 'string');
+    const schema = {
+        type: 'object', additionalProperties: false, required: params.map(p => p.name),
+        properties: Object.fromEntries(params.map(p => [p.name, p.jsonSchema ? { anyOf: [p.jsonSchema, { type: 'null' }] } : isEnum(p) ? { type: ['string', 'null'], enum: [...p.enum, null] } : { type: [typeOf(p), 'null'] }])),
+    };
+    const line = (p) => `- ${p.name} (${isEnum(p) ? `one of: ${p.enum.join(' | ')}` : p.jsonSchema ? p.type || 'object' : typeOf(p)}): ${p.description}`;
+    const instructions = String(flow.parameterInstructions ?? '').trim();
+    const rules = [
+        `The workflow ${flow.name} was chosen. Extract the values the user gave for its parameters.`,
+        ...PARAMETER_RULES.map(r => `- ${r}`),
+        ...(instructions ? ['', instructions] : []),
+    ].join('\n');
+    const system = `${rules}\n\n<parameters>\n${params.map(line).join('\n')}\n</parameters>` + jsonTail(schema);
+    const closed = params.filter(p => isEnum(p) || isBoolean(p));
+    let systemOne = null;
+    if (closed.length) {
+        const questions = {};
+        const index = [];
+        closed.forEach((p, k) => {
+            if (isEnum(p)) {
+                p.enum.forEach((value, v) => {
+                    const id = `p${k}v${v}`;
+                    questions[id] = { type: 'noul', criteria: { true: ENUM_TRUE(value), false: ENUM_FALSE }, instructions: { parameter: { name: p.name }, candidate_value: value, question: `Is \`${value}\` the value of \`${p.name}\`?` } };
+                    index.push({ id, kind: 'enum', param: p.name, value });
+                });
+            }
+            else {
+                const id = `p${k}`;
+                questions[id] = { type: 'noul', criteria: { true: BOOLEAN_TRUE, false: BOOLEAN_FALSE }, instructions: { parameter: { name: p.name }, question: `Is \`${p.name}\` true?` } };
+                index.push({ id, kind: 'boolean', param: p.name });
+            }
+        });
+        const ruleSet = Object.fromEntries(closed.map(p => [p.name, p.description]));
+        systemOne = { state: stateOf(conversation, input, `${rules}\n\nEach question asks for one parameter. The rule of each parameter, by name:\n${JSON.stringify(ruleSet, null, 1)}`), questions, index };
+    }
+    else {
+        // no closed value to classify
+    }
+    return {
+        task: 'extract_parameters', stage: 2, input, conversation,
+        flow: { id: flow.id, name: flow.name, ...(instructions ? { parameterInstructions: instructions } : {}), parameters: params },
+        llm: { system, user: conversationText(conversation, input), schema },
+        systemOne,
+        freeText: params.filter(p => !isEnum(p) && !isBoolean(p)).map(p => p.name),
+    };
+}
+/** A text model's stage-2 answer as the canonical reply: declared parameters with a value only. Throws on non-JSON. */
+export function decodeParametersLlm(text, stage) {
+    const parsed = parseJsonObject(text);
+    const out = {};
+    for (const p of stage.flow.parameters) {
+        const v = parsed[p.name];
+        if (v === null || v === undefined || (typeof v === 'string' && (v.trim() === '' || /^(null|none|n\/a)$/i.test(v.trim())))) {
+            continue; // not given
+        }
+        else {
+            out[p.name] = typeof v === 'string' ? v.trim() : v;
+        }
+    }
+    return { parameters: out };
+}
+/**
+ * System One's stage-2 answers as the canonical reply: an enum takes its argmax value if it clears the cut, a
+ * boolean is true if it clears it; otherwise the parameter is omitted (the flow asks), never set false.
+ */
+export function decodeParametersSystemOne(answers, stage, { threshold = STAGE_YES_THRESHOLD } = {}) {
+    if (!stage.systemOne)
+        return { parameters: {} };
+    const p = answered(answers, stage.systemOne.index);
+    const parameters = {};
+    const best = new Map();
+    for (const q of stage.systemOne.index) {
+        const prob = p.get(q.id);
+        if (q.kind === 'boolean') {
+            if (prob >= threshold)
+                parameters[q.param] = true;
+            else { /* omitted */ }
+        }
+        else {
+            const cur = best.get(q.param);
+            if (!cur || prob > cur.p)
+                best.set(q.param, { value: q.value, p: prob });
+            else { /* lower */ }
+        }
+    }
+    for (const [param, { value, p: prob }] of best) {
+        if (prob >= threshold)
+            parameters[param] = value;
+        else { /* omitted: the flow asks */ }
+    }
+    return { parameters };
+}
+/** Is this jsfe's stage request (a host's aiCallback receives it as the 4th argument)? */
+export function isIntentStageRequest(request) {
+    const r = request;
+    return !!r && ((r.task === 'detect_flow' && r.stage === 1) || (r.task === 'extract_parameters' && r.stage === 2));
+}
+// ── shared ────────────────────────────────────────────────────────────────────────────────────────────
+function parseJsonObject(text) {
+    const t = String(text ?? '').replace(/<think>[\s\S]*?<\/think>/g, '').replace(/^```(?:json)?\s*/i, '').replace(/```\s*$/, '').trim();
+    let parsed;
+    try {
+        parsed = JSON.parse((t.match(/\{[\s\S]*\}/) || [t])[0]);
+    }
+    catch {
+        throw new Error(`not JSON: ${t.slice(0, 60)}`);
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        throw new Error('not a JSON object');
+    return parsed;
+}
+function answered(answers, index) {
+    const p = new Map();
+    for (const q of index) {
+        const noul = Number(answers?.[q.id]?.noul);
+        if (!Number.isFinite(noul))
+            throw new Error(`System One: question ${q.id} unanswered`);
+        p.set(q.id, noul);
+    }
+    return p;
+}

package/dist/host/node.d.ts

@@ -0,0 +1,17 @@
+export function isEncodedCheckpoint(value: any): boolean;
+export function encodeCheckpoint(value: any, overrides?: {}): Promise<{
+    format: string;
+    version: number;
+    encoding: string;
+    decodedBytes: number;
+    sha256: string;
+    data: Buffer<ArrayBufferLike>;
+}>;
+export function decodeCheckpoint(envelope: any, overrides?: {}): Promise<any>;
+export { verifyRuntimeFingerprint } from "./runtime-manifest.js";
+export { CheckpointCodecError } from "./checkpoint-codec-error.js";
+export const CHECKPOINT_CODEC_LIMITS: Readonly<{
+    maxEncodedBytes: number;
+    maxDecodedBytes: number;
+}>;
+//# sourceMappingURL=node.d.ts.map

package/dist/host/node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../src/host/node.js"],"names":[],"mappings":"AAUA,yDAAuN;AACvN;;;;;;;GAUC;AACD,8EAWC;;;AA3BD;;;GAA4G"}

package/dist/host/node.js

@@ -0,0 +1,64 @@
+/** Node-only opaque JSON storage codec. Universal jsfe/host never imports this entry. */
+export { verifyRuntimeFingerprint } from './runtime-manifest.js';
+import { brotliCompress as compress, brotliDecompress as decompress, constants } from 'node:zlib';
+import { promisify } from 'node:util';
+import { CheckpointCodecError } from './checkpoint-codec-error.js';
+export { CheckpointCodecError } from './checkpoint-codec-error.js';
+export const CHECKPOINT_CODEC_LIMITS = Object.freeze({ maxEncodedBytes: 350 * 1024, maxDecodedBytes: 16 * 1024 * 1024 });
+const FORMAT = 'jsfe-checkpoint', brotliCompress = promisify(compress), brotliDecompress = promisify(decompress);
+const options = overrides => { const limits = { ...CHECKPOINT_CODEC_LIMITS, ...overrides }; for (const name of ['maxEncodedBytes', 'maxDecodedBytes'])
+    if (!Number.isSafeInteger(limits[name]) || limits[name] < 1)
+        throw new CheckpointCodecError('invalid_' + name); return limits; };
+const hash = async (bytes) => Array.from(new Uint8Array(await globalThis.crypto.subtle.digest('SHA-256', bytes)), b => b.toString(16).padStart(2, '0')).join('');
+export function isEncodedCheckpoint(value) { return !!value && typeof value === 'object' && (Object.hasOwn(value, 'format') || Object.hasOwn(value, 'encoding') || Object.hasOwn(value, 'sha256') || value.data instanceof Uint8Array); }
+export async function encodeCheckpoint(value, overrides = {}) {
+    const limits = options(overrides);
+    let json;
+    try {
+        json = JSON.stringify(value);
+    }
+    catch {
+        throw new CheckpointCodecError('invalid_json_value');
+    }
+    if (typeof json !== 'string')
+        throw new CheckpointCodecError('invalid_json_value');
+    const raw = new TextEncoder().encode(json);
+    if (raw.byteLength > limits.maxDecodedBytes)
+        throw new CheckpointCodecError('decoded_size_limit');
+    let data;
+    try {
+        data = await brotliCompress(raw, { maxOutputLength: limits.maxEncodedBytes, params: { [constants.BROTLI_PARAM_QUALITY]: 4, [constants.BROTLI_PARAM_LGWIN]: 24, [constants.BROTLI_PARAM_SIZE_HINT]: raw.byteLength } });
+    }
+    catch (error) {
+        throw new CheckpointCodecError(error.code === 'ERR_BUFFER_TOO_LARGE' ? 'encoded_size_limit' : 'compression_failed');
+    }
+    if (data.byteLength > limits.maxEncodedBytes)
+        throw new CheckpointCodecError('encoded_size_limit');
+    return { format: FORMAT, version: 1, encoding: 'br', decodedBytes: raw.byteLength, sha256: await hash(raw), data };
+}
+export async function decodeCheckpoint(envelope, overrides = {}) {
+    const limits = options(overrides);
+    if (!envelope || envelope.format !== FORMAT || envelope.version !== 1 || envelope.encoding !== 'br')
+        throw new CheckpointCodecError('unsupported_format');
+    if (!(envelope.data instanceof Uint8Array) || !Number.isSafeInteger(envelope.decodedBytes) || envelope.decodedBytes < 1 || typeof envelope.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(envelope.sha256))
+        throw new CheckpointCodecError('invalid_envelope');
+    if (envelope.data.byteLength > limits.maxEncodedBytes)
+        throw new CheckpointCodecError('encoded_size_limit');
+    if (envelope.decodedBytes > limits.maxDecodedBytes)
+        throw new CheckpointCodecError('decoded_size_limit');
+    let raw;
+    try {
+        raw = await brotliDecompress(envelope.data, { maxOutputLength: Math.min(limits.maxDecodedBytes, envelope.decodedBytes) });
+    }
+    catch (error) {
+        throw new CheckpointCodecError(error.code === 'ERR_BUFFER_TOO_LARGE' ? 'decoded_size_limit' : 'corrupt_payload');
+    }
+    if (raw.byteLength !== envelope.decodedBytes || await hash(raw) !== envelope.sha256)
+        throw new CheckpointCodecError('integrity_mismatch');
+    try {
+        return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(raw));
+    }
+    catch {
+        throw new CheckpointCodecError('invalid_json_payload');
+    }
+}

package/dist/host/recovery-identity.d.ts

@@ -0,0 +1,16 @@
+export function assertActionRecoveryIdentity(value: any): {
+    protocol: number;
+    runtime: any;
+    definitions: any;
+};
+export function actionRecoveryIdentityMatches(current: any, stored: any): boolean;
+/** Compute once from immutable loaded declarations; callers must not mutate them after activation. */
+export function createActionRecoveryIdentity({ flows, tools }: {
+    flows: any;
+    tools: any;
+}): Promise<Readonly<{
+    protocol: 1;
+    runtime: string;
+    definitions: string;
+}>>;
+//# sourceMappingURL=recovery-identity.d.ts.map

package/dist/host/recovery-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery-identity.d.ts","sourceRoot":"","sources":["../../src/host/recovery-identity.js"],"names":[],"mappings":"AAIA;;;;EAGC;AACD,kFAEC;AA4BD,sGAAsG;AACtG;;;;;;;IAMC"}

package/dist/host/recovery-identity.js

@@ -0,0 +1,73 @@
+/** Immutable checkpoint compatibility. Browser and bundled Node hosts use the same stamped runtime. */
+import { JSFE_RUNTIME_FINGERPRINT } from '../runtime-identity.js';
+const hex = value => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+const runtimeHash = value => typeof value === 'string' && /^sha256:[a-f0-9]{64}$/.test(value);
+export function assertActionRecoveryIdentity(value) {
+    if (!value || value.protocol !== 1 || !runtimeHash(value.runtime) || !hex(value.definitions) || Object.keys(value).some(key => !['protocol', 'runtime', 'definitions'].includes(key)))
+        throw new Error('Invalid action recovery identity');
+    return { protocol: 1, runtime: value.runtime, definitions: value.definitions };
+}
+export function actionRecoveryIdentityMatches(current, stored) {
+    try {
+        const a = assertActionRecoveryIdentity(current), b = assertActionRecoveryIdentity(stored);
+        return a.runtime === b.runtime && a.definitions === b.definitions;
+    }
+    catch {
+        return false;
+    }
+}
+const canonical = value => {
+    const active = new Set();
+    const visit = value => {
+        if (value === null || typeof value === 'string' || typeof value === 'boolean')
+            return value;
+        if (typeof value === 'number') {
+            if (!Number.isFinite(value))
+                throw new Error('Recovery contracts require finite JSON values');
+            return value;
+        }
+        if (!value || typeof value !== 'object' || active.has(value))
+            throw new Error('Recovery contracts require acyclic JSON declarations');
+        active.add(value);
+        let result;
+        if (Array.isArray(value))
+            result = value.map(item => item === undefined ? null : visit(item));
+        else {
+            if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null)
+                throw new Error('Recovery contracts require plain JSON objects');
+            result = Object.fromEntries(Object.keys(value).sort().filter(key => value[key] !== undefined).map(key => [key, visit(value[key])]));
+        }
+        active.delete(value);
+        return result;
+    };
+    return JSON.stringify(visit(value));
+};
+const registry = (entries, name) => {
+    if (!Array.isArray(entries))
+        throw new Error('Recovery identity requires ' + name + ' registry');
+    const seen = new Set();
+    for (const entry of entries) {
+        if (!entry || typeof entry.id !== 'string' || !entry.id || seen.has(entry.id))
+            throw new Error('Recovery identity requires unique ' + name + ' IDs');
+        seen.add(entry.id);
+    }
+    return [...entries].sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+};
+const select = (value, keys) => Object.fromEntries(keys.filter(key => value && value[key] !== undefined).map(key => [key, value[key]]));
+const executionKeys = ['type', 'function', 'url', 'method', 'contentType', 'pathParams', 'queryParams', 'responseMapping', 'timeout', 'retries', 'acceptStatus'];
+function toolContract(tool) {
+    const result = select(tool, ['id', 'name', 'description', 'schema', 'parameters', 'returns']);
+    if (tool.implementation) {
+        result.implementation = select(tool.implementation, executionKeys);
+    }
+    return result;
+}
+/** Compute once from immutable loaded declarations; callers must not mutate them after activation. */
+export async function createActionRecoveryIdentity({ flows, tools }) {
+    if (!runtimeHash(JSFE_RUNTIME_FINGERPRINT))
+        throw new Error('Durable action recovery requires a verified stamped JSFE build');
+    const declarations = { flows: registry(flows, 'flow'), tools: registry(tools, 'tool').map(toolContract) };
+    const bytes = new TextEncoder().encode(canonical(declarations));
+    const definitions = Array.from(new Uint8Array(await globalThis.crypto.subtle.digest('SHA-256', bytes)), byte => byte.toString(16).padStart(2, '0')).join('');
+    return Object.freeze({ protocol: 1, runtime: JSFE_RUNTIME_FINGERPRINT, definitions });
+}

package/dist/host/recovery-policy.d.ts

@@ -0,0 +1,5 @@
+/** Call after changing or deleting host-owned state. Old overrides do not override a newer checkpoint. */
+export function retainRecoveryState(session: any, paths: any): void;
+/** Apply only invalidations newer than the checkpoint, preserving JSON deletion tombstones. */
+export function applyRecoveryStatePolicy(restored: any, current: any): any;
+//# sourceMappingURL=recovery-policy.d.ts.map

package/dist/host/recovery-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery-policy.d.ts","sourceRoot":"","sources":["../../src/host/recovery-policy.js"],"names":[],"mappings":"AAOA,0GAA0G;AAC1G,oEAYC;AACD,+FAA+F;AAC/F,2EAYC"}