jsfe 1.5.0 → 1.7.0

package/dist/index.js

@@ -1,3 +1,6 @@
+import { ACTION_TOOLS } from './forms/action-tools.js';
+import { resumableActionSession, restoreActionSession, projectActionRecoverySession } from './forms/action-recovery.js';
+import { createActionRecoveryIdentity, actionRecoveryIdentityMatches } from './host/recovery-identity.js';
 /**
  * Copyright (c) 2025 InstantAIguru.com
 
@@ -16,6 +19,7 @@ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FO
 DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 **/
+import { buildFlowStage, buildParameterStage, hasStageParameters } from './host/intent-stages.js';
 /*
   // Deploy new version to NPM:
   npm version patch -m "chore(release): %s"
@@ -107,6 +111,8 @@ const DEFAULT_MESSAGE_REGISTRY = {
         flow_resumed_with_guidance: "Resuming {{flowPrompt}} - Type 'cancel flow' or 'help' for options.",
         flow_completed: "{{flowPrompt}} completed successfully.",
         flow_completed_generic: "Flow completed.",
+        action_recovery_incompatible: "I cannot safely finish checking your earlier request right now. I have not repeated it or processed your latest message.",
+        action_recovery_input_deferred: "I recovered the earlier result above. Your latest message was not processed; please send it again if you still need help.",
         flow_cancelled: "Cancelled {{flowPrompt}}.",
         flow_help_general: "Processing {{flowPrompt}} - You can also 'cancel flow' or request 'help'.",
         flow_help_payment: "Processing {{flowPrompt}} - You can also 'cancel flow' or request 'help'.",
@@ -150,6 +156,8 @@ const DEFAULT_MESSAGE_REGISTRY = {
         flow_resumed_with_guidance: "Continuando {{flowPrompt}} - Escriba 'cancelar flujo' o 'ayuda' para opciones.",
         flow_completed: "{{flowPrompt}} completado exitosamente.",
         flow_completed_generic: "Flujo completado.",
+        action_recovery_incompatible: "No puedo terminar de verificar su solicitud anterior de forma segura en este momento. No la he repetido ni he procesado su último mensaje.",
+        action_recovery_input_deferred: "Recuperé el resultado anterior que aparece arriba. Su último mensaje no se procesó; envíelo de nuevo si todavía necesita ayuda.",
         flow_cancelled: "{{flowPrompt}} cancelado.",
         flow_help_general: "Procesando {{flowPrompt}} - También puede 'cancelar flujo' o solicitar 'ayuda'.",
         flow_help_payment: "Procesando {{flowPrompt}} - También puede 'cancelar flujo' o solicitar 'ayuda'.",
@@ -2010,6 +2018,28 @@ function switchToPreviousStack(engine) {
         throw error;
     }
 }
+// Mutable execution data must belong to its activation, never the registered template.
+// Plain programmatic definitions may contain callbacks; preserve those references while
+// cloning their surrounding data rather than rejecting them with structuredClone.
+function cloneFlowValue(value, seen = new WeakMap()) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (seen.has(value))
+        return seen.get(value);
+    const prototype = Object.getPrototypeOf(value);
+    if (!Array.isArray(value) && prototype !== Object.prototype && prototype !== null) {
+        return structuredClone(value);
+    }
+    const copy = Array.isArray(value) ? new Array(value.length) : Object.create(prototype);
+    seen.set(value, copy);
+    for (const key of Object.keys(value)) {
+        Object.defineProperty(copy, key, {
+            value: cloneFlowValue(value[key], seen),
+            enumerable: true, writable: true, configurable: true
+        });
+    }
+    return copy;
+}
 function getInitialVariables(engine, flowDefinition, inheritedVariables) {
     let variables;
     if (inheritedVariables) {
@@ -2019,7 +2049,7 @@ function getInitialVariables(engine, flowDefinition, inheritedVariables) {
         if (flowDefinition?.variables) {
             for (const [varName, varDef] of Object.entries(flowDefinition.variables)) {
                 if (varDef.value !== undefined) {
-                    variables[varName] = varDef.value; // Modify in-place on shared reference
+                    variables[varName] = cloneFlowValue(varDef.value); // Fresh defaults; the caller's variable container stays shared
                 }
             }
         }
@@ -2031,7 +2061,7 @@ function getInitialVariables(engine, flowDefinition, inheritedVariables) {
         if (flowDefinition?.variables) {
             for (const [varName, varDef] of Object.entries(flowDefinition.variables)) {
                 if (varDef.value !== undefined) {
-                    variables[varName] = varDef.value;
+                    variables[varName] = cloneFlowValue(varDef.value);
                 }
             }
         }
@@ -2122,7 +2152,7 @@ async function isFlowActivated(input, engine, userId = 'anonymous') {
             flowName: flow.name,
             flowId: flow.id,
             flowVersion: flow.version,
-            flowStepsStack: [...flow.steps].reverse(),
+            flowStepsStack: cloneFlowValue(flow.steps).reverse(),
             contextStack: [{ role: 'user', content: sanitizeInput(input), timestamp: Date.now() }], // Keep activation input in context for reference
             inputStack: [], // Start empty - only SAY-GET responses go here
             variables, // Start with global variables + flow definition variables + extracted parameters
@@ -2675,8 +2705,14 @@ function enforceParameterTypes(flow, parameters) {
             const n = typeof value === 'number' ? value : (typeof value === 'string' && value.trim() !== '' ? Number(value) : NaN);
             converted = Number.isFinite(n) && (type === 'number' || Number.isInteger(n)) ? n : undefined;
         }
+        else if (p.jsonSchema && type === 'object') {
+            converted = value !== null && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+        }
+        else if (p.jsonSchema && type === 'array') {
+            converted = Array.isArray(value) ? value : undefined;
+        }
         else {
-            converted = value; // object, array or another declared type - not checked here
+            converted = value; // Legacy parameters without an extraction schema retain their existing behavior
         }
         if (converted !== undefined) {
             result[p.name] = converted;
@@ -2711,11 +2747,60 @@ function buildDetectFlowRequest(input, lastChatTurn, flows) {
                 name: p.name,
                 description: p.description,
                 ...(p.type !== undefined ? { type: p.type } : {}),
-                ...(Array.isArray(p.enum) ? { enum: [...p.enum] } : {})
+                ...(Array.isArray(p.enum) ? { enum: [...p.enum] } : {}),
+                ...(p.jsonSchema ? { jsonSchema: structuredClone(p.jsonSchema) } : {})
             }))
         }))
     };
 }
+/**
+ * Two-stage intent detection (engine.intentDetection = 'two-stage'): stage 1 picks the flow, stage 2 extracts the
+ * selected flow's parameters. Each stage is ONE aiCallback call whose positional arguments are the LLM instructions and
+ * whose 4th argument carries both executors' (jsfe/host intent-stages); the host replies with the canonical JSON
+ * ({ flowName } / { parameters }). A stage-1 failure reaches the host as before; a stage-2 failure starts the flow
+ * without its parameters (it asks for them) rather than losing the turn.
+ */
+async function detectFlowInTwoStages(input, engine, flows) {
+    const { input: cleanInput, conversation } = buildDetectFlowRequest(input, engine.lastChatTurn, []);
+    const stage1 = buildFlowStage(cleanInput, conversation, flows.map(f => ({ id: f.id, name: f.name, description: String(f.description ?? '') })));
+    const reply1 = parseStageReply(await fetchAiResponse(stage1.llm.system, stage1.llm.user, engine.aiCallback, engine.aiTimeOut, stageSchema('detect_flow', stage1.llm.schema), stage1));
+    const said = String(reply1.flowName ?? 'None');
+    // only an offered (primary) flow is ever activated; it calls its workers with the arguments it holds
+    const flow = /^(none|null)$/i.test(said) ? null : flows.find(f => f.name.toLowerCase() === said.toLowerCase()) || null;
+    if (!flow) {
+        if (!/^(none|null)$/i.test(said))
+            logger.error(`Flow "${said}" not found in flows menu`);
+        else
+            logger.info(`No flow activated for input: "${input}"`);
+        return null;
+    }
+    else if (!hasStageParameters(flow.parameters)) {
+        return { flow, parameters: {} };
+    }
+    else {
+        try {
+            const stage2 = buildParameterStage(cleanInput, conversation, flow);
+            const reply2 = parseStageReply(await fetchAiResponse(stage2.llm.system, stage2.llm.user, engine.aiCallback, engine.aiTimeOut, stageSchema('extract_parameters', stage2.llm.schema), stage2));
+            const given = reply2.parameters && typeof reply2.parameters === 'object' ? reply2.parameters : {};
+            return { flow, parameters: enforceParameterEnums(flow, enforceParameterTypes(flow, ownParametersOnly(flow, given))) };
+        }
+        catch (error) {
+            logger.warn(`detectFlowWithParameters: stage 2 failed for "${flow.name}" (${error.message}) - the flow starts without its parameters`);
+            return { flow, parameters: {} };
+        }
+    }
+}
+/** The OpenAI-compatible response_format wrapper a host already reads from the 3rd argument. */
+function stageSchema(name, schema) {
+    return JSON.stringify({ type: 'json_schema', json_schema: { name, strict: true, schema } });
+}
+function parseStageReply(text) {
+    const t = String(text ?? '').replace(/^```(?:json)?\s*/i, '').replace(/```\s*$/, '').trim();
+    const parsed = JSON.parse((t.match(/\{[\s\S]*\}/) || [t])[0]);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        throw new Error('intent stage: the reply is not a JSON object');
+    return parsed;
+}
 export async function getFlowForInput(input, engine) {
     const result = await detectFlowWithParameters(input, engine);
     return result ? result.flow : null;
@@ -2740,6 +2825,22 @@ export async function detectFlowWithParameters(input, engine) {
         const primaryFlows = flowsMenu.filter(flow => flow.primary === true);
         const flowsForIntentDetection = primaryFlows.length > 0 ? primaryFlows : flowsMenu;
         logger.debug(`Using ${flowsForIntentDetection.length} flows for intent detection (${primaryFlows.length} primary flows available)`);
+        // A host start (ContextEntry.start) answers detection for this turn: that flow, with its arguments.
+        if (engine.hostStart) {
+            const wanted = engine.hostStart;
+            const flow = flowsMenu.find(f => f.id === wanted.flow || f.name === wanted.flow);
+            if (!flow) {
+                logger.warn(`Host start: flow "${wanted.flow}" is not in the flows menu`);
+                return null;
+            }
+            else {
+                const given = wanted.arguments && typeof wanted.arguments === 'object' ? wanted.arguments : {};
+                return { flow, parameters: enforceParameterEnums(flow, enforceParameterTypes(flow, ownParametersOnly(flow, given))) };
+            }
+        }
+        else {
+            // no host start: intent detection decides
+        }
         // First try direct name or id matching (case-insensitive) - check all flows
         const directMatch = flowsMenu.find(flow => flow.name.toLowerCase() === input.toLowerCase() || (flow.id.toLowerCase() === input.toLowerCase()));
         if (directMatch) {
@@ -2751,6 +2852,12 @@ export async function detectFlowWithParameters(input, engine) {
             logger.info(`No flow matched for input: "${input}" (no AI)`);
             return null;
         }
+        if (engine.intentDetection === 'two-stage') {
+            return await detectFlowInTwoStages(input, engine, flowsForIntentDetection);
+        }
+        else {
+            // the original single call, below
+        }
         // If AI callback is present, use AI for intent detection with primary flows only
         const task = "Considering the chat history when available and applicable, decide if the user input should trigger any available flow. If a flow is triggered, extract any relevant parameters defined in the flow's 'parameters' section.";
         const rules = `- Return the exact flow name if a match is found
@@ -3280,7 +3387,7 @@ async function handleToolStep(currentFlowFrame, engine) {
                             flowName: rebootFlow.name,
                             flowId: rebootFlow.id,
                             flowVersion: rebootFlow.version,
-                            flowStepsStack: [...rebootFlow.steps].reverse(),
+                            flowStepsStack: cloneFlowValue(rebootFlow.steps).reverse(),
                             contextStack: [{ role: 'user', content: input, timestamp: Date.now() }],
                             inputStack: [input],
                             variables: variables, // Fresh variables for reboot flow (with injected params)
@@ -3337,7 +3444,7 @@ async function handleToolStep(currentFlowFrame, engine) {
                             flowName: onFailFlow.name,
                             flowId: onFailFlow.id,
                             flowVersion: onFailFlow.version,
-                            flowStepsStack: [...onFailFlow.steps].reverse(),
+                            flowStepsStack: cloneFlowValue(onFailFlow.steps).reverse(),
                             contextStack: [...currentFlowFrame.contextStack], // Inherit context
                             inputStack: [...currentFlowFrame.inputStack],
                             variables: variables,
@@ -3651,6 +3758,11 @@ function handleSetStep(currentFlowFrame, engine) {
             returnType: 'auto'
         }, engine)
         : step.value;
+    if (step.requireTrue === true && interpolatedValue !== true) {
+        const error = new Error(`Required SET step ${step.id || ''} did not complete successfully`);
+        error.name = 'JSFERequiredSetFailed';
+        throw error;
+    }
     if (currentFlowFrame && currentFlowFrame.variables !== undefined) {
         currentFlowFrame.variables[step.variable] = interpolatedValue;
         logger.info(`SET step: stored '${interpolatedValue}' in variable '${step.variable}'`);
@@ -3961,7 +4073,7 @@ async function handleSubFlowStep(currentFlowFrame, engine) {
                 flowName: subFlow.name,
                 flowId: subFlow.id,
                 flowVersion: subFlow.version,
-                flowStepsStack: [...subFlow.steps].reverse(),
+                flowStepsStack: cloneFlowValue(subFlow.steps).reverse(),
                 contextStack: [{ role: 'user', content: input, timestamp: Date.now() }],
                 inputStack: [input],
                 variables, // Fresh variables for reboot flow
@@ -3981,7 +4093,7 @@ async function handleSubFlowStep(currentFlowFrame, engine) {
             currentFlowFrame.flowName = subFlow.name;
             currentFlowFrame.flowId = subFlow.id;
             currentFlowFrame.flowVersion = subFlow.version;
-            currentFlowFrame.flowStepsStack = [...subFlow.steps].reverse();
+            currentFlowFrame.flowStepsStack = cloneFlowValue(subFlow.steps).reverse();
             addToContextStack(currentFlowFrame.contextStack, 'user', input);
             currentFlowFrame.inputStack.push(input);
             // Inject parameters into current variables — or, for an isolated flow, start this frame's own scope
@@ -3989,13 +4101,18 @@ async function handleSubFlowStep(currentFlowFrame, engine) {
                 currentFlowFrame.variables = Object.assign(getInitialVariables(engine, subFlow), flowParameters);
                 currentFlowFrame.isolatedScope = true;
             }
-            else if (Object.keys(flowParameters).length > 0) {
-                logger.info(`Injecting parameters into variables for flow ${subFlow.name}`, flowParameters);
-                Object.assign(currentFlowFrame.variables, flowParameters);
-                logger.info(`Variables after injection:`, currentFlowFrame.variables);
-            }
             else {
-                // no parameters, shared scope: the frame keeps its variables
+                // Legacy shared replacement preserves the current variable container. New workers may
+                // explicitly initialize target defaults that are still undefined; accepted progress stays.
+                currentFlowFrame.variables ||= {};
+                if (step.initializeDefaults === true) {
+                    for (const [name, definition] of Object.entries(subFlow.variables || {})) {
+                        if (currentFlowFrame.variables[name] === undefined && definition.value !== undefined) {
+                            currentFlowFrame.variables[name] = cloneFlowValue(definition.value);
+                        }
+                    }
+                }
+                Object.assign(currentFlowFrame.variables, flowParameters);
             }
             // Update transaction
             TransactionManager.fail(currentFlowFrame.transaction, `Replaced by flow ${subFlow.name}`);
@@ -4015,7 +4132,7 @@ async function handleSubFlowStep(currentFlowFrame, engine) {
                 flowName: subFlow.name,
                 flowId: subFlow.id,
                 flowVersion: subFlow.version,
-                flowStepsStack: [...subFlow.steps].reverse(),
+                flowStepsStack: cloneFlowValue(subFlow.steps).reverse(),
                 contextStack: [{ role: 'user', content: input, timestamp: Date.now() }],
                 inputStack: [input],
                 variables, // Inherit + merge flow definition variables (isolated: its own)
@@ -5136,32 +5253,19 @@ function evaluateJavaScriptExpression(expression, context, preserveObjects = fal
         }
         return value;
     });
-    // Build function body that evaluates the expression
-    // When preserveObjects is true (e.g., SET steps), don't auto-stringify objects
-    const functionBody = preserveObjects ? `
-    "use strict";
+    // Keep evaluator temporaries outside the generated function: a flow may legitimately declare `result`.
+    const evaluatorFunction = new Function(...validParamNames, `"use strict"; return (${expression});`);
     try {
-      return (${expression});
-    } catch (e) {
-      throw new Error('Expression evaluation failed: ' + e.message);
+        const evaluated = evaluatorFunction(...paramValues);
+        if (!preserveObjects && typeof evaluated === 'object' && evaluated !== null &&
+            !(evaluated.__userInput === true && evaluated.__literal === true)) {
+            return JSON.stringify(evaluated);
+        }
+        return evaluated;
+    }
+    catch (error) {
+        throw new Error('Expression evaluation failed: ' + error.message);
     }
-  ` : `
-    "use strict";
-    try {
-      const result = (${expression});
-      // Auto-stringify complex data structures when used in string contexts
-      if (typeof result === 'object' && result !== null &&
-          !(result.__userInput === true && result.__literal === true)) {
-        return JSON.stringify(result);
-      }
-      return result;
-    } catch (e) {
-      throw new Error('Expression evaluation failed: ' + e.message);
-    }
-  `;
-    // Create and execute function with only valid parameter names
-    const evaluatorFunction = new Function(...validParamNames, functionBody);
-    return evaluatorFunction(...paramValues);
 }
 /**
  * Security-aware variable setter for user input with AI-powered voice cleanup
@@ -5511,7 +5615,7 @@ async function handlePendingInterruptionSwitch(engine, userId) {
         flowName: targetFlow,
         flowId: targetFlowDefinition.id,
         flowVersion: targetFlowDefinition.version || '1.0',
-        flowStepsStack: [...targetFlowDefinition.steps].reverse(),
+        flowStepsStack: cloneFlowValue(targetFlowDefinition.steps).reverse(),
         contextStack: [],
         inputStack: [],
         variables: getInitialVariables(engine, targetFlowDefinition), // Fresh variables for first flow activation
@@ -5576,7 +5680,7 @@ async function handleRegularFlowInterruption(intentAnalysis, engine, userId) {
                 flowName: targetFlow,
                 flowId: targetFlowDefinition.id,
                 flowVersion: targetFlowDefinition.version || '1.0',
-                flowStepsStack: [...targetFlowDefinition.steps].reverse(),
+                flowStepsStack: cloneFlowValue(targetFlowDefinition.steps).reverse(),
                 contextStack: [], // Start with empty context - don't use interruption input
                 inputStack: [], // Start with empty input stack - new flow will get proper input next
                 variables: getInitialVariables(engine, targetFlowDefinition), // Fresh variables for interrupting flow activation
@@ -5885,6 +5989,21 @@ export function applyWraps(flowsMenu) {
     }
 }
 export class WorkflowEngine {
+    /** Host-injected durable action journal. Without it common performers fail closed before effects. */
+    actionJournal;
+    actionRecoveryIdentityPromise;
+    /** Loaded definitions are immutable after activation. Hot reload constructs a new engine. */
+    async getActionRecoveryIdentity() {
+        if (this.actionJournal) {
+            for (const method of ['claim', 'complete', 'checkpoint', 'pending']) {
+                if (typeof this.actionJournal[method] !== 'function')
+                    throw new Error('Durable action journal requires ' + method);
+            }
+        }
+        if (!this.actionRecoveryIdentityPromise)
+            this.actionRecoveryIdentityPromise = createActionRecoveryIdentity({ flows: this.flowsMenu, tools: this.toolsRegistry });
+        return this.actionRecoveryIdentityPromise;
+    }
     cargo;
     flowsMenu;
     toolsRegistry;
@@ -5903,6 +6022,15 @@ export class WorkflowEngine {
      * warning on a mismatch. Diagnostic only — a result is never altered or withheld because of it.
      */
     validateToolReturns = false;
+    /**
+     * Opt-in (default 'single-call'): how intent detection asks aiCallback. 'two-stage': stage 1 picks the flow
+     * (from the primaries' descriptions only), stage 2 extracts the SELECTED flow's parameters; each call carries
+     * both executors' instructions (`llm`, `systemOne`) as its 4th argument — see jsfe/host intent-stages.
+     * 'single-call': the original one call that picks a flow and extracts parameters for every flow at once.
+     */
+    intentDetection = 'single-call';
+    /** This turn's host start (ContextEntry.start), or null. */
+    hostStart = null;
     /**
      * Opt-in (default false): log one warning when a tool returns a failure (`success: false` or a
      * non-zero `error`), with the tool and its message, digit runs masked. Diagnostic only.
@@ -5985,8 +6113,18 @@ export class WorkflowEngine {
         logger = withPiiRedaction(hostLogger); // Assign to global logger (a SAY-GET's `pii` answer never reaches it)
         this.aiCallback = aiCallback;
         this.flowsMenu = applyWraps(flowsMenu);
-        this.toolsRegistry = toolsRegistry;
-        this.APPROVED_FUNCTIONS = APPROVED_FUNCTIONS;
+        if (toolsRegistry.some(tool => ACTION_TOOLS.some(internal => internal.id === tool.id)))
+            throw new Error('Internal JSFE action tool identities are reserved');
+        this.toolsRegistry = [...toolsRegistry, ...ACTION_TOOLS];
+        const receipt = (reply) => reply;
+        this.APPROVED_FUNCTIONS = { ...APPROVED_FUNCTIONS,
+            jsfeClaimAction: async ({ record, action }) => receipt(this.actionJournal
+                ? await this.actionJournal.claim({ sessionId: this.sessionId, record, action, checkpoint: resumableActionSession(this.sessionContext, this.flowsMenu, await this.getActionRecoveryIdentity()) })
+                : { status: 'hold', outcome: { status: 'unknown', reason: 'durable_journal_unavailable' } }),
+            jsfeCompleteAction: async ({ record, action, outcome }) => receipt(this.actionJournal
+                ? await this.actionJournal.complete({ sessionId: this.sessionId, record, action, outcome, checkpoint: resumableActionSession(this.sessionContext, this.flowsMenu, await this.getActionRecoveryIdentity()) })
+                : { status: 'unknown', outcome: { status: 'unknown', reason: 'durable_journal_unavailable' } }),
+        };
         this.globalVariables = globalVariables ? { ...globalVariables } : {}; // Copy global variables to prevent external mutations
         this.aiTimeOut = aiTimeOut ?? 2000; // Default to 2000ms (2 seconds)
         // if validateOnInit is not provided, default to true
@@ -6050,7 +6188,8 @@ export class WorkflowEngine {
     async updateActivity(contextEntry, engineSessionContext) {
         try {
             this.cargo = engineSessionContext.cargo || {};
-            logger.info(`Received Cargo: ${JSON.stringify(this.cargo, (k, v) => (/^(cvv|cvc|cvv2|cardcode|securitycode)$/i.test(k) && v ? '•••' : v))}`);
+            // a security code under any key that names one (a form stores it as `card_cvv`)
+            logger.info(`Received Cargo: ${JSON.stringify(this.cargo, (k, v) => (/(cvv|cvc|card_?code|security_?code)/i.test(k) && v ? '•••' : v))}`);
             this.sessionId = engineSessionContext.sessionId;
             this.createdAt = engineSessionContext.createdAt;
             // Store reference to session context - no copying needed! Engine works directly with session data
@@ -6065,6 +6204,8 @@ export class WorkflowEngine {
             this.sessionContext.lastTurnToolCalls = [];
             // Same one-shot semantics for a DISPATCH record (see recordDispatch).
             delete this.sessionContext.lastTurnDispatch;
+            // A host start belongs to this turn only (ContextEntry.start).
+            this.hostStart = contextEntry && contextEntry.role === 'user' && contextEntry.start && typeof contextEntry.start.flow === 'string' ? contextEntry.start : null;
             // DIAGNOSTIC: Log flowStepsStack state from loaded session (before any processing)
             if (engineSessionContext.flowStacks) {
                 for (let si = 0; si < engineSessionContext.flowStacks.length; si++) {
@@ -6112,6 +6253,50 @@ export class WorkflowEngine {
             if (engineSessionContext) {
                 engineSessionContext.lastActivity = this.lastActivity;
             }
+            // Recover durable effects before the new message can mutate an older saved session.
+            // A successfully saved session carries its observed sequence even when acknowledgement failed.
+            delete engineSessionContext.lastTurnRecovery;
+            let recoveredAction = false;
+            let suspendedRecoveryStacks;
+            if (contextEntry.role === 'user' && this.actionJournal) {
+                const recoveryIdentity = await this.getActionRecoveryIdentity();
+                const pending = await this.actionJournal.pending({ sessionId: this.sessionId });
+                const applied = (this.cargo.actionJournalApplied || {});
+                // A journal sequence orders writes, not execution progress. Track consumption per attempt.
+                const record = (pending?.records || []).filter((row) => row.checkpoint && Number(row.sequence) > Number(applied[row.key] || 0))
+                    .sort((a, b) => Number(a.sequence) - Number(b.sequence)).at(-1);
+                const recovery = record ? { key: record.key, sequence: record.sequence, status: record.status, session: record.checkpoint, record } : null;
+                if (recovery) {
+                    if (!actionRecoveryIdentityMatches(recoveryIdentity, recovery.session.actionRecoveryIdentity)) {
+                        engineSessionContext.lastTurnToolCalls = [];
+                        delete engineSessionContext.lastFlowOutcome;
+                        delete engineSessionContext.lastTurnDispatch;
+                        this.hostStart = null;
+                        engineSessionContext.lastTurnRecovery = { key: record.key, sequence: record.sequence, status: record.status, hold: true, reason: 'incompatible_recovery_identity', deferredInput: contextEntry };
+                        engineSessionContext.response = getSystemMessage(this, 'action_recovery_incompatible');
+                        return engineSessionContext;
+                    }
+                    const snapshotProgress = recovery.session.actionRecoveryProgress;
+                    const changedEpoch = (engineSessionContext.actionRecoveryEpoch || null) !== (recovery.session.actionRecoveryEpoch || null);
+                    const alreadyAdvanced = Number.isSafeInteger(snapshotProgress) && Number(engineSessionContext.actionRecoveryProgress || 0) >= Number(snapshotProgress);
+                    const snapshotApplied = recovery.session.cargo?.actionJournalApplied || {};
+                    const hasNewerApplied = Object.entries(applied).some(([key, sequence]) => Number(sequence) > Number(snapshotApplied[key] || 0));
+                    const invalidatedSinceCheckpoint = Number(engineSessionContext.actionRecoveryPolicy?.revision || 0) > Number(recovery.session.actionRecoveryPolicy?.revision || 0);
+                    if (changedEpoch || alreadyAdvanced || hasNewerApplied || invalidatedSinceCheckpoint) {
+                        suspendedRecoveryStacks = projectActionRecoverySession(engineSessionContext, recovery, contextEntry, this.flowsMenu, recoveryIdentity);
+                    }
+                    else {
+                        restoreActionSession(engineSessionContext, recovery, contextEntry, recoveryIdentity);
+                    }
+                    this.cargo = engineSessionContext.cargo;
+                    this.reconstructVariableReferences();
+                    engineSessionContext.lastTurnToolCalls = [];
+                    delete engineSessionContext.lastFlowOutcome;
+                    delete engineSessionContext.lastTurnDispatch;
+                    this.hostStart = null;
+                    recoveredAction = true;
+                }
+            }
             // Role-based processing logic
             if (contextEntry.role === 'user') {
                 // A sensitive answer (SAY-GET `pii`) is kept out of every log line of this turn, raw and as its digits
@@ -6122,10 +6307,16 @@ export class WorkflowEngine {
                 // Detect intent to activate a flow or switch flows
                 let responseOrNull;
                 try {
-                    responseOrNull = await processActivity(said, userId, this);
+                    if (!recoveredAction && this.actionJournal)
+                        engineSessionContext.actionRecoveryProgress = Number(engineSessionContext.actionRecoveryProgress || 0) + 1;
+                    responseOrNull = recoveredAction ? await playFlowFrame(this) : await processActivity(said, userId, this);
                 }
                 finally {
                     piiInputs = [];
+                    if (suspendedRecoveryStacks) {
+                        engineSessionContext.flowStacks = suspendedRecoveryStacks;
+                        this.reconstructVariableReferences();
+                    }
                 }
                 // Anomaly guard: a flow is STILL ACTIVE but produced no response.
                 // Detect activity by frame EXISTENCE, not by the response value: a frame
@@ -6155,6 +6346,8 @@ export class WorkflowEngine {
                     err.name = 'JSFEActiveFlowEmptyResponse';
                     throw err;
                 }
+                if (recoveredAction)
+                    responseOrNull = [responseOrNull, getSystemMessage(this, 'action_recovery_input_deferred')].filter(Boolean).join('\n\n');
                 // Store user turn in lastChatTurn if not in a flow
                 if (responseOrNull === null) {
                     this.sessionContext.lastChatTurn.user = contextEntry;

package/dist/runtime-identity.d.ts

@@ -0,0 +1,3 @@
+/** Replaced in dist by the post-build stamper. Legacy execution does not require a stamp. */
+export declare const JSFE_RUNTIME_FINGERPRINT: string;
+//# sourceMappingURL=runtime-identity.d.ts.map

package/dist/runtime-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-identity.d.ts","sourceRoot":"","sources":["../src/runtime-identity.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAC7F,eAAO,MAAM,wBAAwB,EAAE,MAAkB,CAAC"}

package/dist/runtime-identity.js

@@ -0,0 +1 @@
+export const JSFE_RUNTIME_FINGERPRINT = "sha256:c17204fa29bf43386d3e2433a775108403a9999f7f3d63a9da4761f685c1ecfd";

package/docs/development-release.md

@@ -0,0 +1,23 @@
+# Reproducible native JSFE development candidate
+
+The native form/performer implementation spans the engine, host and tenant flow generator. Testing an unversioned sibling symlink does not establish that a clean consumer installation will use the same engine.
+
+A local candidate is an unpublished prerelease. Freeze and test its source, run `npm run clean`, `npm run build` and `npm test`, then use `npm pack --ignore-scripts` to create an immutable artifact. Never replace a candidate tarball with different bytes under the same version. If runtime source changes afterward, create the next prerelease version.
+
+Both consumers pin the identical tarball under `vendor/jsfe/` using an exact `file:` dependency and lockfile integrity. Record the tarball SHA-256, package version, engine runtime fingerprint, source revisions and dirty source digest, and Node/npm versions. Verify each installed consumer's bytes with `flow-tests/lib/runtime-build.mjs`; matching package version labels alone are insufficient. Exercise a clean `npm ci` installation before accepting the candidate.
+
+Acceptance includes engine tests, host journal/save-boundary/invalidation tests, tenant `npm run test:accept`, real-engine production-response-shape journeys, the independent designer-skill example and bilingual live intent/parameter probes. Include late completion after newer saved work, versioned receipt acknowledgment races, expiry/reset recovery, strict projector failure, optional follow-up outcomes and explicit confirmation clarification. Exercise the actual storage adapter and conversation helpers with full session checkpoints and high-entropy history, checking exact decoded round trips, complete item bounds and removal of acknowledged checkpoint payloads. Customer/API effects in these checks use local stubs. Model credential access is a separately authorized test operation. Do not retain credentials in reports.
+
+The original `ai-ar` behavioral suites remain runnable in original mode. Native mode declares deliberate interaction changes explicitly and preserves independent payload, consent, subject, failure and retry expectations. There are no blanket exclusions for failed suites. Stale artifacts, crashed or empty selections and failed assertions fail acceptance.
+
+Compatibility remains explicit. The published `amountInAnswer` and `isAmountAnswer` helpers retain their legacy defaults. USD grammar uses `readMoneyAmount`/`isMoneyAmount` with `{currency:'USD',cardinals:true,intent:'payment'}`, or a FORM amount profile with that object under `money`; cardinal parsing and payment intent are optional flags. Shared `FLOW` replacement retains its current variables unless the step declares `initializeDefaults:true`, which fills only undefined target defaults. Native builders opt in; loaded legacy flows are not rewritten. Mutable declared defaults and authored step data are private to each activation, while shared flow variables still use the caller's container. `SET requireTrue:true` requires a literal true result; absent or false retains ordinary SET behavior.
+
+An absent `config.jsfe` group defaults to `{durableActions:false,sessionEncoding:'plain'}`; omitted keys default independently to those values. Unknown keys, invalid types and unsupported encodings reject configuration. `durableActions:true` attaches the action journal; legacy turns otherwise perform no journal reads. `sessionEncoding:'br-v1'` enables encoded conversation writes through Node-only `jsfe/host/node`; keep universal `jsfe/host` free of Node dependencies. Journal-internal encoding is separate from conversation policy. Codec bounds default to 16 MiB decoded JSON and 350 KiB encoded binary; the host additionally rejects complete DynamoDB items above its conservative 400 KiB bound. Unsupported/corrupt envelopes and codec limits raise `CheckpointCodecError`; complete-item overflow raises `JSFEStorageSizeLimit`. A failed decode must not replace the conversation, and a failed save must not acknowledge action receipts.
+
+Deploy compatible readers across the fleet before enabling `br-v1` for a tenant. New readers accept historical plaintext and supported encoded rows; pre-reader hosts cannot read envelopes. Switching back to `plain` converts an existing encoded row only on a successful, size-bounded save, without trimming; dormant rows remain encoded and an oversized plaintext result blocks conversion. Before an older-reader rollback, stop new native starts, keep pending native continuations on capable routing, losslessly CAS-convert every target encoded row and verify none remain. Toggling policy or resetting sessions is not a migration.
+
+Durable restore/project requires an exact identity match for `{protocol:1,runtime:'sha256:...',definitions:'<digest>'}`. Missing, invalid or different identities HOLD recovery: preserve current state, defer new input, and perform no projector, effect or acknowledgment. The definition digest includes canonical flows and nonsecret tool execution declarations; loaded definitions are immutable for an engine instance, so hot reload requires a new engine. This deliberately limits recovery across runtime or definition changes; it is not a production rollout approval.
+
+Native performer declarations include `contract.requires: ['durableActions']`. `assertFlowHostCapabilities` checks each declared requirement against an explicitly supplied boolean capability; it never enables one. The host rejects unmet requirements before constructing an engine. Legacy flows without capability declarations keep the default-off behavior. The flow-set switch preflight uses the same helper; an explicit `--jsfe-policy` JSON file can merge approved policy keys in the same tenant configuration write as the flows and tools. Omitting the option preserves the current policy and rejects a native set when its requirements are unmet. Compression remains a separate storage decision.
+
+Publishing the package, deploying the host or uploading tenant/system flow sets are separate release actions requiring the owner's authorization. A release should replace local tarball dependencies with the exact published package whose bytes were accepted, and deploy matched host/system/tenant contracts together. No deployment is implied by a passing local candidate.