jsfe 1.6.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
 
@@ -108,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'.",
@@ -151,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'.",
@@ -2011,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) {
@@ -2020,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
                 }
             }
         }
@@ -2032,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);
                 }
             }
         }
@@ -2123,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
@@ -2676,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;
@@ -2712,7 +2747,8 @@ 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) } : {})
             }))
         }))
     };
@@ -3351,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)
@@ -3408,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,
@@ -3722,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}'`);
@@ -4032,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
@@ -4052,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
@@ -4060,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}`);
@@ -4086,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)
@@ -5207,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
@@ -5582,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
@@ -5647,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
@@ -5956,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;
@@ -6065,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
@@ -6195,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
@@ -6205,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
@@ -6238,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.

package/docs/forms.md

@@ -0,0 +1,122 @@
+# Native forms, providers and performers
+
+Implemented locally on 2026-10-19 in `jsfe/src/forms` and `jsfe/src/helpers`. These changes are a local, unpublished development candidate. Record the package version and runtime byte fingerprint; a matching version string alone does not identify a build. No production deployment is implied.
+
+This is the current authoring reference. Earlier `collect-input-pattern.md` and `manifests.md` preserve the original design discussion; their carry/lift migration recipe and definition-keyed state examples are superseded.
+
+## Ownership
+
+- JSFE owns generic matching, input validation protocol, form instances/dependencies, provider retrieval, confirmation, action identity and durable recovery policy. Import builders and shared declarations from `jsfe/forms`; expression helpers come from `jsfe/helpers`.
+- The host owns credentialed transport, storage adapters and persistence acknowledgments. Shared behavior does not belong in tenant-local or host-local support copies.
+- Tenant modules own catalogs, API payloads, business eligibility and presentation. Pure domain rules may be authored as source functions and embedded at build time. Do not read legacy generators or snapshots to construct runtime steps.
+- `defineForm`, `defineProvider`, `definePerformer`, `defineWorker`, `operationWorkers` and `linkFormSchemas` compile native declarations. `validateFlowContracts` checks contracts and references; it does not prove behavioral parity.
+
+## One instance per owned task
+
+`cargo.forms[instance]` contains `definition`, `task`, `parent`, `result_input`, canonical `specs`, `values`, accepted proofs, pending readings, errors, preparation state, `data`, saved arguments and child instances. Instance IDs are opaque. `cargo.formTasks[definition]` identifies an active root; nested ownership is `(parent instance, input slot)`, allowing two address slots or independent tasks to coexist.
+
+Use the supplied `form_instance` only for internal reentry. A form resumes its saved arguments and validated progress. A sub-form returns through the same acceptance/invalidation transition as a field. Context service forms use `parent_form` with no `result_input`; they inherit the owner’s task without fabricating a value slot.
+
+Never mutate accepted values directly for ordinary input. Use the common acceptance protocol. Explicit business-derived values and service results must have declared owning paths and dependencies.
+
+## Input declarations
+
+Use presets (`field`), an owned sub-form (`form`), or a narrow inline `profile`. Include labels and prompts in both languages. Relevant attributes:
+
+- `when` / `unless`: relevance and readability. Conditions can reference sibling values, `cargo.*`, or `form.data.*`. Unknown conditions wait; they do not silently count as false.
+- `required_when`: whether a relevant field must be collected. False makes the field optional while retaining voluntary recognition. Unknown blocks completion until its premise is known. Omit for required fields.
+- `depends_on`: preparation/validation waits for committed prerequisite evidence; changing the prerequisite invalidates the dependent transitively.
+- `reset_on`: invalidation only. It does not add a validation prerequisite.
+- `validator`: receives `{form,input,value,values,reading}` and writes `cargo.inputCheck={ok,value?,message?,message_es?}`. Missing result fails closed. Activation and conversational answers use this same path.
+- `prepare`: runs once before first validation or prompt; `refresh` runs before each prompt. `choices_from` / `question_from` read owner `data`. Use `compileFormPrompts` for contextual template prompts; it preserves declarations and generates workers.
+- `activate` / `activate_on`: nominate dormant child entry fields that may propose controller assignments, such as a card number selecting a new-card branch. The controller and nominated entry validate as one atomic group; rejection cannot flip the controller. Use narrow descendant paths, never broad matching of every child field.
+- `validate_always:true`: revalidate even an unchanged value when its business assumptions must be refreshed. Validator `revalidate:true` provides the same explicit cache bypass at validator declaration.
+- `after`: post-commit callback. `any_of` groups can be `exclusive`; conflicting members require clarification.
+- `confirm_against`: explicitly requires clarification when two field interpretations overlap, including current-field priority exceptions.
+- `choices[].keys`: whole-answer keypad aliases, recognized only for the current field. An explicit current keypad key wins an overlapping current-field claim, including an `any_of` group; `confirm_against` can still require clarification. Keys never become aliases for noncurrent fields. `words` are semantic aliases; `current_only` restricts a choice. Grouped digit aliases and marked currency must not steal each other’s spans. English and Spanish word amounts require explicit currency and follow the shared cardinal grammar; sequential card digits are not money.
+
+A batch retains independent valid fields if another field fails. Dependent early values remain pending until prerequisites validate. An invalid prerequisite cannot authorize an effect. Structured submissions are read leaf by leaf; objects are never coerced into scalar values. Primary nested extraction schemas derive from the same input declarations.
+
+## Resolution and reentry
+
+Resolve overlapping evidence in this order: current field, one matching field at the nearest owning scope, then ancestors. Multiple competing claims at the same applicable scope are clarified. Independent spans fill independent fields. Typed evidence beats an unconstrained text fallback. `confirm_against` deliberately overrides ordinary priority.
+
+The common loop asks the first ready missing required input, skips accepted data, unwinds inapplicable children and blocks unresolved prerequisites. A context service may use `stop` and `close_on_stop:true` to close itself without handing a value to its parent. With `resume_on_parent_change:true`, an accepted owner correction closes the stale context service and resumes the same owned form with its retained progress, requiring a fresh confirmation. `RETURN` ends the entire engine transaction; ordinary worker completion uses `END`.
+
+Optional follow-ups may declare `incomplete_outcome:{outcome:'resolved',reason:'payment_made'}` to preserve an already completed task’s outcome when collection cannot finish or the user leaves. Accepted outcome values are `resolved`, `unresolved` and `deflected`, with a nonempty reason. A reusable form may instead use `incomplete_outcome:{from:'completed_outcome'}` with a declared object parameter; its runtime value must pass the same validation. The nearest actual owned ancestor supplies a fallback to a child. Another task’s outcome never does. The policy covers missing input specifications, blocked dependencies, exhausted validation/retries and unmatched collection/confirmation dispatch; it does not complete missing inputs or authorize effects. Omit it for ordinary required forms, which retain their existing unresolved outcomes and reasons.
+
+For bounded collection recovery, declare `on_exhausted:'recovery-worker'` on an input or FORM. On attempt exhaustion, the resolver checks the failed input/member, its group, then its containing form before walking actual owned ancestors. The worker receives `{form,failed_form,input,failed_input,reason:'attempts_exhausted'}`: `form` and `input` identify the selected policy’s owner, while `failed_form` and `failed_input` identify the original failure. Shared recovery resets only the selected input branch, closes its child without handing off an incomplete value, withdraws confirmation and reboots to that worker. Independent draft fields remain. The callback must deliberately collect a new choice and obtain any required fresh confirmation before an effect; exhaustion is not consent. Worker names and references are validated. With no callback, the existing incomplete-outcome or give-up path applies.
+
+The common collector passes `form_context:{form,current,names,questions}` to `ask-choice`. The reader checks declared current-field or unique same-scope form readings before classifying an answer as a stale verification-code echo. A valid ZIP, amount or current menu key must not be discarded merely because its digits occur in the prior OTP. Use this shared context instead of a tenant-specific code filter.
+
+Private provider questions during collection preserve the owner and pending verification. Repeated questions join the pending provider request instead of stacking another authentication flow. Independent field clauses are accepted before a provider suspends for verification. Questions cannot become invalid OTP attempts or arbitrary text answers.
+
+## Providers
+
+Declare a `provides` catalog: subject, gate (`flow`, verified paths), source (`flow`, result path, subject/freshness policy), facts and fact sets. Each fact has a key, phrasings, source path or dedicated worker, rendering rules and explicit missing-data text. A private catalog requires an explicit gate. Derive `asked` and mid-form question choices with the builder; do not maintain another list.
+
+`provide-data`, `load-source` and `answer-facts` retrieve and answer requested facts. An explicit fact request does not require a generic account summary. Source refresh clears old results first and records freshness only after success. Subject changes invalidate incompatible data and verification. `no_gate` may skip rerunning a gate only when its declared verification paths hold; it never bypasses their check.
+
+## Performers
+
+Declare each action’s name, effect, subject, gate, execution worker/tool, idempotency or reconciliation policy, exact confirmation where applicable, and outcomes. `definePerformer` gathers inputs, prepares an immutable request, selects one applicable action, confirms it, calls `perform-action`, runs its required pure projector, consumes the exact durable receipt, then presents the stored result. Presenter arguments are `{form,request,result}`; retain that explicit result across nested performers rather than rereading the shared last-result cargo slot.
+
+Declare `project:[SET steps]` for deterministic session updates such as payment and case ledgers. Its expression locals are `{form,formSnapshot,request,result,key}`: `form` is the owned instance ID and `formSnapshot` is its state at the recorded action. Projection writes target current `cargo`; detached recovery does not replace current forms with that snapshot. Use the durable key for idempotence, the original result timestamp for ordering and explicit ownership guards to preserve newer task drafts or facts. The compiler accepts only SET expressions with local temporary variables and rejects flow/tool/message orchestration. Projectors must be effect-free; expression failure prevents receipt consumption. Presenters own conversation and optional subsequent performers. Ledger updates belong in `project`, because detached late recovery runs this projector without replaying the presenter, `after` steps or caller continuation.
+
+Bind subjects to owner data, including composite identities where necessary: `{account,service}` for cancellation or `{contact,type,reason}` for CRM filing. Compare the prepared subject to the current verification evidence before execution. An old unknown result holds that action scope; it cannot capture unrelated requests.
+
+Confirmation is separate from fields. It binds the current form revision, values and prepared request. A correction invalidates that binding. Use `confirm.no_keys` only when a declared menu needs different keypad semantics; default `2` remains NO. Confirmation events receive `{form,event,text}` and reenter through ordinary validation. A YES embedded in other content is not consent. `confirm.clarifications` may list exact whole-answer clarification phrases in both languages, such as `['what does that mean','qué significa eso']`. Matching ignores question punctuation and uses the bounded ordinary unclear-answer retry path. These phrases neither consent nor change the request; other unrelated requests still dispatch normally.
+
+## Durable actions and host save boundary
+
+Hosts inject `createActionJournal({storage,namespace})` from `jsfe/host`; storage implements atomic attempt/scope/session-index compare-and-swap. A journal must expose claim, complete, checkpoint and pending recovery. The built-in `jsfe:action-claim` and `jsfe:action-complete` ports are reserved. Missing storage fails closed before native effects. In hy-rag-lambdas, `config.jsfe.durableActions` defaults to false: the journal stays unattached, and ordinary legacy turns make no journal reads or add native recovery progress. Only an explicitly opted-in tenant activates this policy.
+
+`engine.getActionRecoveryIdentity()` privately caches a verified build stamp and a canonical digest of the loaded compiled flow and tool execution contracts. The stamp is verified before bundling and remains available inside the bundle; production recovery performs no runtime filesystem scan. Checkpoints carry `{protocol:1,runtime,definitions}`. Before full restoration or pure projection, JSFE requires an exact identity match. Missing, unsupported or different identities hold the pending outcome, preserve current task state, defer the incoming message and run no effect, projector or acknowledgment. A package version label is not a compatibility identity. Loaded definitions are immutable after activation; hot reload constructs a new engine, and execution counters/default data belong to individual frames.
+
+The journal records a resumable engine checkpoint before an effect and the result afterward. For an opted-in native tenant, JSFE examines unconsumed versions per action key before consuming a new user message. Only an exact compatible recovery identity proceeds to continuation selection. A storage sequence orders journal writes, not workflow progress. A checkpoint from progress absent in the saved session restores its continuation; a late completion after saved progress runs only its pure projector against the current session, preserving current tasks and never replaying its presenter or caller tail. The arriving input is recorded as deferred recovery metadata. It never treats that message as retroactive consent. A higher journal sequence alone cannot justify restoring an older workflow; per-key applied versions, saved workflow progress, recovery epoch and host invalidation revision determine whether continuation restore is safe.
+
+The host saves the resulting session first, then awaits `checkpointActionSession`. Failed or rejected saves never release action scopes. Versioned `{key,sequence}` receipts stay persisted for acknowledgment retry. Freeze those versions at the successful save boundary: an older attempted/unknown receipt must never acknowledge a later completion. Late tool callbacks return results without advancing the active session’s applied watermark. The performer advances it only after consuming and projecting the durable result. Acknowledging an unknown outcome clears its recovery checkpoint but retains its scope hold. No elapsed timeout resolves an uncertain financial action; a balance change alone is not transaction identity evidence. Explicit fresh consent may supersede an uncertain SEND only under a declared send retry policy.
+
+Host invalidations use `retainRecoveryState(session,paths)` after changing or deleting host-owned cargo. Newer invalidations, including deletion tombstones, select pure result projection against the current session instead of restoring the older workflow or its private presenter. Explicit conversation resets rotate the persisted recovery epoch: old outcomes can be projected, but discarded workflows cannot resume. Before every fresh effect, `perform-action` reruns the declared `gate.flow` and checks current verification paths; a stale derived permission flag cannot replace that gate.
+
+The host’s DynamoDB adapter shares the configured chats table with reserved internal keys. Chat entry points reject those keys. Do not deploy a new durable performer without configuring this port and testing the actual save boundary.
+
+## Checkpoint storage codec
+
+The Node host storage boundary imports `encodeCheckpoint`, `decodeCheckpoint` and `isEncodedCheckpoint` from `jsfe/host/node`. This Node-only entry uses asynchronous Brotli; the universal `jsfe/host` entry remains free of Node imports. The version-1 envelope stores binary `Uint8Array` data, the original UTF-8 JSON byte count and a SHA-256 integrity digest. It losslessly round-trips JSON-compatible session data without trimming history, forms or action records.
+
+The default limits are 16 MiB of decoded JSON and 350 KiB of encoded binary. Decompression is bounded before decoding, and the host separately checks the complete DynamoDB item against a conservative 400 KiB bound, including all metadata and other fields. Compression does not guarantee that arbitrary data fits; an oversized item fails before the database write.
+
+The host journal adapter encodes only the attempt checkpoint and decodes it when reading; successful acknowledgment removes that checkpoint payload. Journal-internal storage remains separate from conversation storage. Conversation writers default to `config.jsfe.sessionEncoding:'plain'`; only an explicit `'br-v1'` enables binary `engineSession` writes. This capability is independent of `durableActions`. The configuration group and both keys may be omitted; malformed values and unknown keys reject configuration. Conversation readers always decode supported envelopes before constructing a session, including when writers are disabled. Receipt versions are frozen at the actual save boundary, and other host fields retain their normal representation.
+
+Historical plaintext remains readable. Unsupported envelopes, corrupt data, integrity failures and codec limits raise `CheckpointCodecError`; whole-item overflow raises `JSFEStorageSizeLimit`. A corrupt saved conversation must not become a fresh session or overwrite its stored row. Failed writes never acknowledge action receipts. Disabling encoding converts a decoded row to plaintext only on its next successful size-bounded save; it does not convert dormant rows, and oversized plaintext fails without trimming or modifying the old envelope.
+
+Roll out decoder-capable readers before enabling any tenant’s binary writer. Old workers in a mixed fleet cannot read new envelopes. A pre-reader rollback requires lossless, revision-checked conversion and verification of every affected row; a flag toggle alone is insufficient. Existing native continuations and pending/unknown actions must remain on a compatible recovery service when native starts are disabled. Never hand them to legacy execution or reset them to manufacture rollback compatibility.
+
+## Explicit monetary grammar and compatibility
+
+`amountInAnswer(text)` and `isAmountAnswer(text)` preserve the published JSFE 1.6 behavior. Installing native FORM support does not make existing production flows accept cardinal words or treat pesos as dollar markers.
+
+Native inputs can declare enhanced grammar explicitly:
+
+```js
+{ name: 'amount', profile: { kind: 'amount', min: 0.50,
+    money: { currency: 'USD', cardinals: true, intent: 'payment' } },
+  validator: 'validate-payment-amount' }
+```
+
+`readMoneyAmount(text, options)` returns a number or `NaN`; `isMoneyAmount` is true exactly for a finite result, including bare numeric input. Options require `currency: 'USD'`; `cardinals` defaults to false, and `intent` is optional. Currently USD is the only supported currency. Explicit pesos/MXN, euros and other named foreign currencies fail closed; no currency conversion or equivalence is inferred. The optional cardinal grammar supports complete English/Spanish dollar and cents phrases and preserves source spans. Unequal independent amounts, malformed cardinal phrases and signed negative amounts are rejected.
+
+With `intent: 'payment'`, the shared `moneyIntentAllows` policy recognizes explicit English/Spanish payment-refusal, inability and deferral forms while allowing uncertainty followed by a positive correction (for example, “no entiendo, quiero pagar250”). The vocabulary is deterministic, not an exhaustive linguistic classifier. A recognized declined monetary instruction is not accepted as a numeric correction. Matching may pass an uncommittable `refused: true` candidate with raw text to a declared validator so that it can route to domain recovery. The common validation batch withholds that candidate even when a permissive validator returns success; activation and conversational paths use the same rule. Confirmation remains a separate, later action decision.
+
+## Acceptance
+
+Map every original behavior to native definitions or an explicit consolidation. Runtime import graphs must exclude carried JSON, lifted steps, source-renaming adapters and the old generator. Historical fixtures can remain outside the runtime graph. Counts and valid contracts alone do not establish completion.
+
+Run independent rule tests, real-engine journeys with JSON session round trips, original behavioral suites, anonymized production response-shape journeys and intent/parameter probes in English and Spanish. Include nested out-of-order input, optional-field recognition, multiple ambiguity groups, corrections, subject changes, provider questions during OTP, duplicate turns, refused APIs, unknown effects and process loss before host save. Preserve intentional interaction differences explicitly rather than weakening effects or consent assertions.
+
+Generation failures, stale artifacts, empty suite selections, crashed suites and failed expectations must fail acceptance. Record engine/build identity, source revisions, model configuration and exact executed evidence. Production deployment still requires Ron’s explicit authorization.
+
+### Host capability admission
+
+`definePerformer` declares `durableActions` in its contract requirements. A host must call `assertFlowHostCapabilities(flows, capabilities)` from `jsfe/host` before activation and supply `durableActions: true` explicitly for these flows. The check does not enable a journal or choose a conversation encoding. Missing requirements reject activation before customer input or effects. Other flow builders may declare additional boolean host requirements through `contract.requires`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jsfe",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "TypeScript workflow engine for conversational/automation apps: multi-flow orchestration, interrupt/resume, stack-based control, robust errors, and flexible tool/REST integration.",
   "license": "MIT",
   "author": "Ron Pinkas",
@@ -19,9 +19,17 @@
       "types": "./dist/host/index.d.ts",
       "import": "./dist/host/index.js"
     },
+    "./host/node": {
+      "types": "./dist/host/node.d.ts",
+      "import": "./dist/host/node.js"
+    },
     "./helpers": {
       "types": "./dist/helpers/index.d.ts",
       "import": "./dist/helpers/index.js"
+    },
+    "./forms": {
+      "types": "./dist/forms/index.d.ts",
+      "import": "./dist/forms/index.js"
     }
   },
   "main": "./dist/index.js",
@@ -31,13 +39,16 @@
     "dist",
     "README.md",
     "LICENSE",
-    "docs/copilot-reference.md"
+    "docs/copilot-reference.md",
+    "docs/forms.md",
+    "docs/development-release.md"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.json && node scripts/stamp-runtime.mjs",
     "clean": "rm -rf dist",
     "test": "for t in tests/*.test.mjs; do node \"$t\" || exit 1; done",
-    "prepublishOnly": "npm run clean && npm run build"
+    "prepublishOnly": "npm run clean && npm run build",
+    "verify:runtime": "node scripts/stamp-runtime.mjs --check"
   },
   "keywords": [
     "workflow",