jsfe 1.15.9 → 1.17.0

package/README.md

@@ -12,6 +12,7 @@ npm i jsfe
 - **[JavaScript Flow Engine User Guide](user-guide.md)** 
 - Comprehensive tutorials, examples, and best practices
 - **[README.md](README.md)** - Technical API reference (this document)
+- **[Flows architecture guide](docs/architecture-guide.md)** - start here: the concepts, the building blocks, what the caller experiences, and how conversational AI and exact transactional flows work together (the reply ranker and DISPATCH)
 - **[Flow author reference](docs/copilot-reference.md)** - the authoritative engine and JSON authoring specification for flow authors and AI flow generators (shipped in the package; the Flow Designer's CoPilot reads it from the published version, so change it with the engine)
 - **[Development candidate acceptance](docs/development-release.md)** - reproducible package and cross-repository verification
 - **[System Flows](docs/flows/system/README.md)** and **[Shopify Flows](docs/flows/shopify/README.md)** - the bundled flow and tool libraries in `flows/`: a page and a chart per flow, generated from the JSON (`node scripts/flow-docs.mjs`), plus the conventions the system flows share

package/dist/docs/flow-docs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flow-docs.d.ts","sourceRoot":"","sources":["../../src/docs/flow-docs.js"],"names":[],"mappings":"AAiBA;;;;;;;;;;;EAqRC"}
+{"version":3,"file":"flow-docs.d.ts","sourceRoot":"","sources":["../../src/docs/flow-docs.js"],"names":[],"mappings":"AAkBA;;;;;;;;;;;EAsRC"}

package/dist/docs/flow-docs.js

@@ -14,8 +14,10 @@
  */
 import fs from 'fs';
 import path from 'path';
+import { resolveSetDataReferences } from '../forms/declarations.js';
 export function generateFlowDocs({ sets, root, check = false, hostRun = {}, log = console.log }) {
-    const SETS = sets;
+    // A catalog or value written as {"$data": path} is documented as compilation resolves it.
+    const SETS = sets.map((s) => ({ ...s, flows: resolveSetDataReferences(s.flows) }));
     // Which set holds a flow id; a page links to a flow in its own set, or in another set's folder.
     const setOf = new Map(), flowOf = new Map();
     for (const s of SETS) {
@@ -422,7 +424,7 @@ export function generateFlowDocs({ sets, root, check = false, hostRun = {}, log
         }
         else { /* not a compiled form */ }
         if (flow.performs) {
-            out.push('', '### Performs', '', ...flow.performs.map((a) => `- \`${a.action}\` (${a.effect}): ${a.reconcile && a.reconcile.policy ? cut(a.reconcile.policy, 300) : ''}`), '', performsChart(flow));
+            out.push('', '### Performs', '', ...flow.performs.map((a) => `- \`${a.action}\` (${a.effect})`), '', performsChart(flow));
         }
         else { /* not a performer */ }
         if (flow.call) {

package/dist/forms/address-flows.js

@@ -28,7 +28,7 @@ const street = C('address-street-validate', 'Validate a proposed street against
     W('address_street_malformed', "!/^\\d{1,6}\\s+[A-Za-z\\xC0-\\xFF]/.test(String(value))", S('address_street_invalid', 'noop', "(cargo.inputCheck={ok:false,message:'Please give the street number and street name.',message_es:'Indique el número y nombre de la calle.'},true)")), W('address_street_stop', "!/^\\d{1,6}\\s+[A-Za-z\\xC0-\\xFF]/.test(String(value))", { id: 'address_street_invalid_end', type: 'END' }),
     S('address_street_components', 'components', "'postal_code:'+values.zip+'|country:US'"), { id: 'address_street_tool', type: 'CALL-TOOL', tool: 'geocode-street', variable: 'result', args: { address: '{{value}}', components: '{{components}}' }, onFail: S('address_street_failed', 'result', 'null') },
     S('address_street_projection', 'location', E(streetLocation, 'result', 'value', 'values.zip')),
-    S('address_street_result', 'noop', "(cargo.forms[form].data.street=location, cargo.inputCheck={ok:true,value:String(value)}, true)")
+    S('address_street_result', 'noop', "(cargo.forms[form].data.street=location, location.city&&cargo.forms[form].accepted&&cargo.forms[form].accepted.city&&cargo.forms[form].accepted.city.origin==='derived'&&cargo.forms[form].values.city!==location.city?(cargo.forms[form].values.city=location.city):null, cargo.inputCheck={ok:true,value:String(value)}, true)")
 ], { parameters: [P('form'), P('value'), P('values', 'object')], variables: V({ components: '', result: null, location: null }), contract: { tools: ['geocode-street'], result: { path: 'cargo.inputCheck', type: 'object' } } });
 const zipPrompt = C('address-zip-prompt', 'Render the ZIP retry wording from the owned address instance.', [S('address_zip_prompt', 'noop', "(cargo.forms[form].data.zip_question=(cargo.forms[form].data.retry ? \"Let's try again. \" : '')+'What is the 5-digit zip code of your new address?',cargo.forms[form].data.zip_question_es=(cargo.forms[form].data.retry?'Intentémoslo otra vez. ':'')+'¿Cuál es el código postal de 5 dígitos de su nueva dirección?',true)")], { parameters: [P('form')], contract: { result: { path: 'cargo.forms[form].data', type: 'object' } } });
 const streetPrompt = C('address-street-prompt', 'Include the ZIP-derived location when asking for the street.', [S('address_street_prompt', 'noop', "(cargo.forms[form].data.street_question=(cargo.forms[form].data.location?'Got it, '+(cargo.forms[form].values.city?cargo.forms[form].values.city+', '+cargo.forms[form].data.location.state:cargo.forms[form].data.location.line)+'. ':'')+'What is the street address?',cargo.forms[form].data.street_question_es=(cargo.forms[form].data.location?'Entendido, '+(cargo.forms[form].values.city?cargo.forms[form].values.city+', '+cargo.forms[form].data.location.state:cargo.forms[form].data.location.line)+'. ':'')+'¿Cuál es la dirección?',true)")], { parameters: [P('form')], contract: { result: { path: 'cargo.forms[form].data', type: 'object' } } });

package/dist/forms/continuation-compat.d.ts

@@ -0,0 +1,5 @@
+export function continuationBreaks(previousFlows: any, nextFlows: any): {
+    id: any;
+    removed: {};
+}[];
+//# sourceMappingURL=continuation-compat.d.ts.map

package/dist/forms/continuation-compat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"continuation-compat.d.ts","sourceRoot":"","sources":["../../src/forms/continuation-compat.js"],"names":[],"mappings":"AAgBA;;;IAgBC"}

package/dist/forms/continuation-compat.js

@@ -0,0 +1,45 @@
+/**
+ * A deploy check: a change that can break a saved session must bump its declaration's major version. A saved session
+ * continues across a minor or patch change, so an entry argument or a form input it may still hold must not disappear
+ * without a major bump; neither may a shared data or function name without its entry's major bump. Removing a flow needs
+ * no bump: a session standing in a flow that no longer exists is retired anyway.
+ *
+ *   continuationBreaks(previousFlows, nextFlows) → [{ id, removed: { parameters?, inputs?, data?, functions? } }]
+ *     both arrays are the authored declarations (a set's .flows file); ordinary executable flows are not compared.
+ * It reads names only: a change of meaning under the same name is still the author's to declare with a major bump.
+ */
+import { majorOf } from './declarations.js';
+const parameterNames = parameters => Array.isArray(parameters) ? parameters.map(p => p?.name).filter(Boolean) : Object.keys(parameters || {});
+const inputNames = inputs => (inputs || []).flatMap(input => [input?.name, ...inputNames(input?.any_of)]).filter(Boolean);
+const missing = (before, after) => { const keep = new Set(after); return [...new Set(before)].filter(name => !keep.has(name)); };
+export function continuationBreaks(previousFlows, nextFlows) {
+    const next = new Map((nextFlows || []).filter(flow => flow && flow.id).map(flow => [flow.id, flow]));
+    const breaks = [];
+    for (const before of previousFlows || []) {
+        const after = before && next.get(before.id);
+        if (!after || before.declarationVersion === undefined || majorOf(before.version) !== majorOf(after.version))
+            continue;
+        const removed = {};
+        if (before.library === 'data') {
+            const names = missing(Object.keys(before.data || {}), Object.keys(after.data || {}));
+            if (names.length)
+                removed.data = names;
+        }
+        else if (before.library === 'functions') {
+            const names = missing(Object.keys(before.functions || {}), Object.keys(after.functions || {}));
+            if (names.length)
+                removed.functions = names;
+        }
+        else {
+            const parameters = missing(parameterNames(before.parameters), parameterNames(after.parameters));
+            if (parameters.length)
+                removed.parameters = parameters;
+            const inputs = missing(inputNames(before.form?.inputs), inputNames(after.form?.inputs));
+            if (inputs.length)
+                removed.inputs = inputs;
+        }
+        if (Object.keys(removed).length)
+            breaks.push({ id: before.id, removed });
+    }
+    return breaks;
+}

package/dist/forms/contracts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../../src/forms/contracts.js"],"names":[],"mappings":"AAgBA;;;IAGC;AACD;;;;;EAGC;AACD,qGAAqG;AACrG;;QAwCC;AAqBD;;;QAEC;AAgBD;;;;;;;;;QASC;AACD;;;;QAGC;AACD;;;;;;;;QA8BC;AAED,mHAAmH;AACnH,kDAgBC;AAED,+GAA+G;AAC/G;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA2EC"}
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../../src/forms/contracts.js"],"names":[],"mappings":"AAgBA;;;IAGC;AACD;;;;;EAGC;AACD,qGAAqG;AACrG;;QAwCC;AAqBD;;;QAEC;AAgBD;;;;;;;;;QASC;AACD;;;;QAGC;AACD;;;;;;;;QA8BC;AAED,mHAAmH;AACnH,kDAgBC;AAED,+GAA+G;AAC/G;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4EC"}

package/dist/forms/contracts.js

@@ -138,7 +138,7 @@ export function defineProvider({ provides, contract, parameters = [], variables
 }
 export function defineForm({ contract, provides, ...spec }) {
     const flow = formFlow({ ...spec, ...(provides ? { extraVars: { ...spec.extraVars, provides, questions: providerQuestions(provides) } } : {}) });
-    return declared(flow, { role: 'collector', ...contract, form: { inputs: 'inputs' } });
+    return declared(flow, { role: 'collector', ...contract, form: { inputs: 'inputs' }, ...(provides ? { catalog: 'provides' } : {}) });
 }
 export function definePerformer({ performs, contract, prepare, present, project = [], provides, ...spec }) {
     validateActionProjection(project, spec.id);
@@ -170,7 +170,7 @@ export function definePerformer({ performs, contract, prepare, present, project
             { ...set('receipt_applied', 'noop', 'pf_receipt ? consumeActionReceipt(cargo,pf_receipt) : true'), requireTrue: true },
             call('present', present, { form: '{{form_instance}}', request: '{{pf_request}}', result: '{{pf_result}}' }),
             ...(spec.after || [])] });
-    return declared(flow, { role: 'performer', ...contract, requires: ['guardedActions', ...normalizeHostRequirements(contract?.requires, spec.id)], actions: 'performs', form: { inputs: 'inputs' }, prepares: prepare, presents: present, projects: 'projection' });
+    return declared(flow, { role: 'performer', ...contract, requires: ['guardedActions', ...normalizeHostRequirements(contract?.requires, spec.id)], actions: 'performs', form: { inputs: 'inputs' }, prepares: prepare, presents: present, projects: 'projection', ...(provides ? { catalog: 'provides' } : {}) });
 }
 /** A registered tool gets one generated adapter with explicit args; no dynamic tool-name interpreter is needed. */
 export function operationWorkers(tools) {
@@ -278,6 +278,10 @@ export function validateFlowContracts(flows, tools = [], { externalFlows = [], r
             for (const reference of [provides.gate?.flow, provides.source?.flow])
                 if (reference && !ids.has(reference))
                     fail(flow.id, `unknown provider worker ${reference}`);
+            // a FLOW to a name that does not exist is skipped silently at run time, so a menu choice's target is checked here
+            for (const choice of provides.menu?.choices || [])
+                if (choice?.flow && !ids.has(choice.flow))
+                    fail(flow.id, `unknown menu worker ${choice.flow}`);
         }
         for (const action of contract.performs || flow.variables?.[contract.actions]?.value || []) {
             if (action.retry?.unknown && !(action.effect === 'send' && action.retry.unknown === 'explicit'))
@@ -292,8 +296,6 @@ export function validateFlowContracts(flows, tools = [], { externalFlows = [], r
                 fail(flow.id, `unknown action worker ${action.flow}`);
             if (!action.outcomes || !Object.keys(action.outcomes).length)
                 fail(flow.id, `action ${action.action} needs outcomes`);
-            if (['charge', 'write', 'send', 'cancel'].includes(action.effect) && !action.idempotency && !action.reconcile)
-                fail(flow.id, `action ${action.action} needs idempotency or reconciliation`);
             if ((action.effect === 'charge' || action.effect === 'cancel' || action.reversible === false) && action.confirm?.exact !== true)
                 fail(flow.id, `action ${action.action} needs exact confirmation`);
         }

package/dist/forms/declarations.d.ts

@@ -1,6 +1,7 @@
 /** The set's shared data for expressions, read as $data.<name>: references resolved, deep-frozen (one engine serves many
  * sessions), never copied into session variables. Every $data.<name> an expression reads must exist, checked at load. */
 export function flowSetData(flows: any, compiledFlows?: any[]): any;
+export function resolveSetDataReferences(flows: any): any;
 /** Compile only explicitly versioned declarations. Ordinary executable JSON is unchanged.
  * @param {any[]} flows
  * @param {{tools?: any[], externalFlows?: any[], validate?: boolean}} options
@@ -20,4 +21,6 @@ export function captureOriginalDeclaration(flow: any): {
 export function serializeFlowDeclaration(flow: any, { resolvedFlow }?: {
     resolvedFlow?: any;
 }): any;
+/** The major of a declared version ("2.4.1" → "2"; absent or unreadable → "0"). */
+export function majorOf(version: any): string;
 //# sourceMappingURL=declarations.d.ts.map

package/dist/forms/declarations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"declarations.d.ts","sourceRoot":"","sources":["../../src/forms/declarations.js"],"names":[],"mappings":"AAgDA;yHACyH;AACzH,oEAaC;AAmFD;;;;GAIG;AACH,+CAJW,GAAG,EAAE,uCACL;IAAC,KAAK,CAAC,EAAE,GAAG,EAAE,CAAC;IAAC,aAAa,CAAC,EAAE,GAAG,EAAE,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAC,GACxD,GAAG,EAAE,CAmEjB;AAED,sGAAsG;AACtG;;;SAAqK;AAuBrK,6FAA6F;AAC7F;;QAuCC"}
+{"version":3,"file":"declarations.d.ts","sourceRoot":"","sources":["../../src/forms/declarations.js"],"names":[],"mappings":"AAyDA;yHACyH;AACzH,oEAaC;AAID,0DAIC;AAmFD;;;;GAIG;AACH,+CAJW,GAAG,EAAE,uCACL;IAAC,KAAK,CAAC,EAAE,GAAG,EAAE,CAAC;IAAC,aAAa,CAAC,EAAE,GAAG,EAAE,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAC,GACxD,GAAG,EAAE,CAuEjB;AAED,sGAAsG;AACtG;;;SAAqK;AAuBrK,6FAA6F;AAC7F;;QAuCC;AAnSD,mFAAmF;AACnF,8CAA4G"}

package/dist/forms/declarations.js

@@ -12,6 +12,15 @@ const fail = message => { throw new Error('Flow declaration: ' + message); };
 function sourceRevision(source) { const text = JSON.stringify(source); const hashes = [2166136261, 2246822507, 3266489909, 668265263]; for (let i = 0; i < text.length; i++)
     for (let lane = 0; lane < hashes.length; lane++)
         hashes[lane] = Math.imul(hashes[lane] ^ text.charCodeAt(i), 16777619 + lane * 2) >>> 0; return hashes.map(n => n.toString(16).padStart(8, '0')).join(''); }
+/** The major of a declared version ("2.4.1" → "2"; absent or unreadable → "0"). */
+const majorOf = version => { const m = /^\s*v?(\d+)/i.exec(String(version ?? '')); return m ? String(Number(m[1])) : '0'; };
+/** A declaration's continuation revision: its major version, plus the major of each shared entry it uses ($data, fn.).
+ * A minor or patch change keeps the revision, so a saved session continues; a breaking change bumps the major. */
+function majorRevision(declarationVersion, source, libraries) {
+    const text = JSON.stringify(source), uses = { data: /\$data\b/.test(text), functions: /(?<![\w$])fn\./.test(text) };
+    const shared = libraries.filter(library => uses[library.library]).map(library => library.library + '@' + library.id + ':' + majorOf(library.version)).sort();
+    return 'declaration-v' + declarationVersion + ':major:' + majorOf(source.version) + (shared.length ? '/' + shared.join('/') : '');
+}
 const variableDeclaration = value => value && typeof value === 'object' && !Array.isArray(value) && ['string', 'number', 'integer', 'boolean', 'object', 'array'].includes(value.type) ? value : { type: Array.isArray(value) ? 'array' : value === null || typeof value === 'object' ? 'object' : typeof value, value };
 const DECLARATION_VERSIONS = new Set([1, 2]);
 /** A flow set's shared entries: {id, library:'functions', declarationVersion:2, functions} and
@@ -29,7 +38,7 @@ function sharedFunctions(libraries) {
             fail('a shared functions entry needs an id');
         if (library.declarationVersion !== 2)
             fail('shared functions ' + library.id + ' require declarationVersion 2');
-        const extra = Object.keys(library).filter(key => !['id', 'name', 'library', 'declarationVersion', 'description', 'functions'].includes(key));
+        const extra = Object.keys(library).filter(key => !['id', 'name', 'library', 'declarationVersion', 'description', 'version', 'functions'].includes(key));
         if (extra.length)
             fail('shared functions ' + library.id + ' cannot declare ' + extra.join(', '));
         if (!library.functions || typeof library.functions !== 'object' || Array.isArray(library.functions) || !Object.keys(library.functions).length)
@@ -51,7 +60,7 @@ function sharedData(libraries) {
             fail('a shared data entry needs an id');
         if (library.declarationVersion !== 2)
             fail('shared data ' + library.id + ' requires declarationVersion 2');
-        const extra = Object.keys(library).filter(key => !['id', 'name', 'library', 'declarationVersion', 'description', 'data'].includes(key));
+        const extra = Object.keys(library).filter(key => !['id', 'name', 'library', 'declarationVersion', 'description', 'version', 'data'].includes(key));
         if (extra.length)
             fail('shared data ' + library.id + ' cannot declare ' + extra.join(', '));
         if (!library.data || typeof library.data !== 'object' || Array.isArray(library.data) || !Object.keys(library.data).length)
@@ -88,6 +97,15 @@ export function flowSetData(flows, compiledFlows = []) {
     }
     return Object.keys(resolved).length ? resolved : undefined;
 }
+/** A set's version 2 declarations with every {"$data":"path"} replaced by its value, as compilation sees them; the shared
+ * data entries are kept. For readers of the declarations (the flow docs); compilation resolves them itself. */
+export { majorOf };
+export function resolveSetDataReferences(flows) {
+    const data = sharedData((flows || []).filter(isLibrary));
+    if (!Object.keys(data).length)
+        return flows;
+    return flows.map(flow => flow?.declarationVersion === 2 && !isLibrary(flow) ? resolveDataReferences(flow, data, flow.id) : flow);
+}
 const isDataReference = value => !!value && typeof value === 'object' && !Array.isArray(value) && Object.keys(value).length === 1 && typeof value.$data === 'string';
 /** Replace every {"$data":"path"} with a copy of the shared value at that path; an unknown path fails compilation. */
 function resolveDataReferences(value, data, where, active = new Set()) {
@@ -266,7 +284,11 @@ export function compileFlowDeclarations(flows, { tools, externalFlows = [], vali
                 return false; parameterNames.add(parameter.name); return true; }), ...(rest.parameterInstructions !== undefined ? { parameterInstructions: rest.parameterInstructions } : {}), ...(functions ? { functions } : {}), metadata: { ...flow.metadata, declaration: { version: declarationVersion, source: source.id } } };
         // Revisions are engine bookkeeping; a stale authored token cannot override source change detection.
         const { safetyRevision: ignoredRevision, ...revisionSource } = source;
-        return withSafetyRevision(flow, 'declaration-v' + declarationVersion + ':' + sourceRevision(declarationVersion === 2 && Object.keys(shared).length ? { ...revisionSource, sharedFunctions: shared } : revisionSource));
+        const revised = withSafetyRevision(flow, majorRevision(declarationVersion, original, libraries));
+        // The earlier revision, a fingerprint of the whole declaration: a session saved under it continues while the declaration
+        // is unchanged (and takes the major revision), so moving to major revisions retires no session.
+        revised.safetyRevisionCompat = 'declaration-v' + declarationVersion + ':' + sourceRevision(declarationVersion === 2 && Object.keys(shared).length ? { ...revisionSource, sharedFunctions: shared } : revisionSource);
+        return revised;
     });
     const externalObjects = externalFlows.filter(flow => flow && typeof flow === 'object');
     const formIds = new Set(flows.filter(flow => flow.declarationVersion !== undefined && flow.form).map(flow => flow.id));
@@ -472,7 +494,7 @@ export function serializeFlowDeclaration(flow, { resolvedFlow = flow } = {}) {
     else if (spec.variables)
         result.variables = spec.variables;
     for (const [key, value] of Object.entries(spec))
-        if (!sharedKeys.includes(key) && !['extraVars', 'variables', 'helpers', 'safetyRevision'].includes(key) && !(isForm && formKeys.has(key)))
+        if (!sharedKeys.includes(key) && !['extraVars', 'variables', 'helpers', 'safetyRevision', 'safetyRevisionCompat'].includes(key) && !(isForm && formKeys.has(key)))
             result[key] = value;
     const out = rewrite(result);
     // Helpers and bodies can reference other explicitly authored expressions as well.

package/dist/forms/flows.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flows.d.ts","sourceRoot":"","sources":["../../src/forms/flows.js"],"names":[],"mappings":"AAqIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6DC;AACD;;;GAGG;AACH;;;;;;EAGC;AAgfD,wHAAwH;AACxH,wEAaC;AACD,4FAA4F;AAC5F;;;EAYC;AACD,sGAAsG;AACtG;;;EAOC;AArrBM,6CAAuG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA82B9G;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAOG"}
+{"version":3,"file":"flows.d.ts","sourceRoot":"","sources":["../../src/forms/flows.js"],"names":[],"mappings":"AAqIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6DC;AACD;;;GAGG;AACH;;;;;;EAGC;AAsfD,wHAAwH;AACxH,wEAaC;AACD,4FAA4F;AAC5F;;;EAYC;AACD,sGAAsG;AACtG;;;EAOC;AA3rBM,6CAAuG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAo3B9G;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAOG"}

package/dist/forms/flows.js

@@ -459,20 +459,26 @@ const readFormChoice = {
 // form's other choices (a correction) and a person, never YES. Result: cargo.confirmRanked = 'no' | 'changed' | 'none'
 // (ConfirmForm reads it); `abort` ends every flow; `new_request` goes to intent detection.
 const readConfirmReply = {
-    id: 'read-confirm-reply', name: 'ReadConfirmReply', version: '1.2.0', scope: 'isolated', description: 'Rank an unreadable answer to a confirmation: it declines (NO), picks another of the form\'s choices (a correction, read as that input\'s answer), asks for a person, or is asked again; a withdrawal or a new request leaves with saved form progress. Never confirms.',
-    parameters: [{ name: 'form', type: 'string' }, { name: 'question', type: 'string' }, { name: 'question_es', type: 'string' }],
-    variables: vars({ question: '', question_es: '', asked: '', ranked: [], reply: null, chain: null, others: [], picked: null, reading: null }),
+    id: 'read-confirm-reply', name: 'ReadConfirmReply', version: '1.3.0', scope: 'isolated', description: 'Rank an unreadable answer to a confirmation: it declines (NO), picks another of the form\'s choices (a correction, read as that input\'s answer), says a named field read back is wrong (confirm.named_fields: that input is asked again), asks for a person, or is asked again; a withdrawal or a new request leaves with saved form progress. Never confirms.',
+    parameters: [{ name: 'form', type: 'string' }, { name: 'question', type: 'string' }, { name: 'question_es', type: 'string' }, { name: 'named_fields', type: 'boolean' }],
+    variables: vars({ question: '', question_es: '', asked: '', ranked: [], reply: null, chain: null, others: [], fields: [], field: null, picked: null, reading: null, named_fields: false }),
     steps: [SET('confirm_asked', 'asked', "language === 'es' && question_es ? question_es : question"),
         SET('confirm_chain', 'chain', 'formInputChain(cargo.forms, form, cargo)'),
         SET('confirm_others', 'others', otherChoicesJS("''", '[]')),
-        rankedChoices('confirm_ranked_choices', "[{key:'no',label:'no: declines or refuses what the question asks to confirm'}].concat(others.map(function(c){return {key:c.key,label:c.label};}))"),
+        // confirm.named_fields: a field read back may be corrected in the caller's own words ('es Long Beach' at an address
+        // read back with the ZIP code's city): each named input of this form that holds a value is offered, and a pick asks
+        // that input again, so the caller's value replaces the one read back
+        SET('confirm_fields', 'fields', "named_fields === true || named_fields === 'true' ? (chain || []).filter(function(i){var v=cargo.forms[form] && cargo.forms[form].values;return i.form===form && !i.confirmation && Array.isArray(i.names) && i.names.length && v && v[i.name]!==undefined && v[i.name]!==null && v[i.name]!=='';}).map(function(i){var l=String(i.label || i.names[0]);return {key:'field:'+i.name,label:'says the '+l+' read back is wrong, or gives a different '+l,owner:{form:i.form,name:i.name}};}) : []"),
+        rankedChoices('confirm_ranked_choices', "[{key:'no',label:'no: declines or refuses what the question asks to confirm'}].concat(others.map(function(c){return {key:c.key,label:c.label};})).concat(fields.map(function(c){return {key:c.key,label:c.label};}))"),
         rankedDispatch('confirm_dispatch', 'confirmation_not_matched'),
         ...escapeRoutes('confirm_escape'),
         // a correction picked by the ranker is read as its input's answer: the form changes and is confirmed again, never confirmed
         SET('confirm_picked', 'picked', "others.filter(function(c){return reply && c.key===reply.key;})[0] || null"),
         SET('confirm_read', 'reading', "picked ? enrichFormMatches(readFormAnswer(picked.key, chain, picked.owner, picked.key, []), chain, form, [picked.owner.name], picked.owner.name) : null"),
         WHEN('confirm_change', 'reading && reading.hits.length', FLOW('confirm_change_accept', 'collect-input-accept', 'call', { hits: '{{reading.hits}}' })),
-        SIDE('confirm_ranked', "(cargo.confirmRanked=reading && reading.hits.length ? 'changed' : reply && reply.key==='no' ? 'no' : 'none',true)")]
+        SET('confirm_field', 'field', "fields.filter(function(c){return reply && c.key===reply.key;})[0] || null"),
+        WHEN('confirm_field_reset', 'field', SIDE('confirm_field_ask', '(resetFormInputs(cargo, field.owner.form, [field.owner.name]), true)')),
+        SIDE('confirm_ranked', "(cargo.confirmRanked=reading && reading.hits.length || field ? 'changed' : reply && reply.key==='no' ? 'no' : 'none',true)")]
 };
 const collectContextualAnswer = formFlow({ id: 'collect-contextual-answer', name: 'CollectContextualAnswer', description: 'Collect one open-ended answer using contextual DISPATCH and preserve the caller wording.',
     parameters: [...['question', 'question_es', 'description', 'context', 'context_es'].map(name => ({ name, type: 'string' })), { name: 'choices', type: 'array' }, { name: 'digits', type: 'object' }],
@@ -597,7 +603,7 @@ const confirmForm = {
                 'condition: cf_named': SET('cf_named_reset', 'cf_result', "(resetFormInputs(cargo, cf_named.form, [cf_named.name]), 'changed')"),
                 "condition: cargo.choice === 'no'": SET('cf_declined', 'cf_result', "'no'"),
                 "condition: Array.isArray(clarifications) && pickChoice(String(cargo.choiceText || '').replace(/[?¿]/g,''),[{key:'clarify',phrases:clarifications,exact:true}],false)==='clarify'": SET('cf_clarification', 'cf_result', "'clarification'"),
-                'condition: !cf_must && cf_words > 0': FLOW('cf_elsewhere', 'read-confirm-reply', 'call', { form: '{{form}}', question: '{{cf_prompt}}', question_es: '{{cf_prompt_es}}' }),
+                'condition: !cf_must && cf_words > 0': FLOW('cf_elsewhere', 'read-confirm-reply', 'call', { form: '{{form}}', question: '{{cf_prompt}}', question_es: '{{cf_prompt_es}}', named_fields: '{{named_fields}}' }),
                 default: SET('cf_unclear', 'cf_result', "'unclear'")
             } },
         // the ranker's reading of an unread answer: a decline is the NO; an answer that declines nothing is asked again

package/dist/forms/identity-flows.d.ts

@@ -5,7 +5,10 @@ export function serviceDigits(text: any): string;
 export function otpDigits(text: any): string;
 export function contactPrompt(cargo: any, options: any, callerAllowed: any, partial?: boolean, es?: boolean): string;
 export function contactError(kind: any, options: any, es?: boolean): string;
+export function otpWhere(cargo: any, es?: boolean): string;
 export function otpPrompt(cargo: any, es?: boolean): string;
+/** What the caller hears when a second code goes to the account's email: the address masked to its first letter and domain. */
+export function otpAlsoSent(cargo: any, es?: boolean): string;
 export function emailReadback(address: any, voice: any, es?: boolean): string;
 /** Reenter the existing owning FORM or its gate without making the owner its own parent. */
 export function identityResumeContext(forms: any, owner: any, target: any, identifiers?: {}): {

package/dist/forms/identity-flows.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"identity-flows.d.ts","sourceRoot":"","sources":["../../src/forms/identity-flows.js"],"names":[],"mappings":"AA2BA,+GAA+G;AAC/G,oFAOC;AAQD,wFAAwF;AACxF,iDAGC;AACD,6CAMC;AACD,qHAQC;AAMD,4EAKC;AAoFD,4DAKC;AAmHD,8EAGC;AA4BD,4FAA4F;AAC5F;;;;EAOC;AAQD,0BAAmI"}
+{"version":3,"file":"identity-flows.d.ts","sourceRoot":"","sources":["../../src/forms/identity-flows.js"],"names":[],"mappings":"AA2BA,+GAA+G;AAC/G,oFAOC;AAQD,wFAAwF;AACxF,iDAGC;AACD,6CAMC;AACD,qHAQC;AAMD,4EAKC;AAwFD,2DAOC;AACD,4DAOC;AACD,+HAA+H;AAC/H,8DAGC;AA0ID,8EAGC;AA4BD,4FAA4F;AAC5F;;;;EAOC;AAQD,0BAA4I"}

package/dist/forms/identity-flows.js

@@ -95,6 +95,9 @@ const contact = worker('get-cell-or-email', 'GetCellOrEmail', 'Identify a suppli
         when('identity_contact_partial_reset', '!contact_partial', effect('identity_contact_partial_forget', "(cargo.gcePartial='',true)")),
         set('identity_contact_allowed', 'contact_allowed', "!!cargo.callerId && !callerIsInternational(cargo) && !cargo.callerDeclined && contact_options.caller_on_file !== 'no'"),
         set('identity_contact_prefill', 'contact_prefill', "String(acct_number || cell_number || email || (!contact_partial && contact_allowed && contact_options.caller_on_file === 'yes' ? cargo.callerId : ''))"),
+        // a question answered from what is already known (the caller ID, a contact given) is never spoken: its intro (why the
+        // account is needed) leads the verification code question instead (otpPrompt). A spoken question said it (or had none).
+        effect('identity_contact_intro_unsaid', "(!contact_prefill ? (cargo.otpIntro='',cargo.otpIntro_es='') : contact_options.intro && !cargo.contactIntroSkip && !contact_options.fromMenu ? (cargo.otpIntro=String(contact_options.intro),cargo.otpIntro_es=String(contact_options.intro_es || contact_options.intro)) : true,true)"),
         effect('identity_contact_preselected', "(acct_number || cell_number || email ? true : (cargo.callerPreselected=!!(contact_prefill && contact_options.caller_on_file === 'yes')),true)"),
         set('identity_contact_profiles', 'contact_profiles', "contact_profiles_base.map(function (field) {return field.name === 'account' ? Object.assign({},field,{profile:{kind:'identifier',pattern:contact_options.account_pattern || '(?!)'}}) : field;}).concat(contact_allowed ? [{name:'caller_decision',label:'caller ID choice',label_es:'opción del identificador de llamadas',profile:{kind:'choice',choices:[{key:'yes',phrases:['1','yes','si','sí'],exact:true},{key:'no',phrases:['no','nope','nah'],exact:true}]}}] : [])"),
         set('identity_contact_keypad', 'contact_keypad', "(function () {var shapes=[{first:'23456789',lengths:[10]},{first:'1',lengths:[11]}].concat(contact_options.account_shape || []);if(contact_partial){var left=[];(contact_options.account_shape || []).forEach(function(s){(s.lengths || []).forEach(function(n){var rest=n-String(cargo.gcePartial).length;if(rest>0 && left.indexOf(rest)<0)left.push(rest);});});return {min:1,max:12,autoSubmitMs:3000,complete:[{first:'0123456789',lengths:left.sort(function(a,b){return a-b;})}]};}return {min:7,max:12,autoSubmitMs:3000,autoSubmitChars:contact_allowed?['1']:[],complete:shapes};})()"),
@@ -148,7 +151,7 @@ const authKeys = ['retry_flow', 'cancel_flow', 'email_validator', 'cell_validato
 const auth = worker('authenticate-user', 'AuthenticateUser', 'Authenticate a contact using shared FORM collection and one-time-code services.', { parameters: Object.keys(AUTH_DEFAULTS).filter(k => !['contact_valid', 'auth_result', 'auth_contact_error', 'auth_contact_error_es', 'auth_previous_options', 'auth_restart', 'auth_join', 'otp_expiry_ms'].includes(k)).map(k => param(k, k.replace(/_/g, ' '), ['retry_returns', 'retrying', 'declined_caller'].includes(k) ? 'boolean' : 'string')).concat([param('caller_on_file', 'Caller-ID eligibility inherited from the invoking service')]), variables: vars(AUTH_DEFAULTS), contract: { role: 'gate', summary: 'Generic one-time-code identity gate', result: { paths: ['cargo.otpVerified', 'cargo.authRetry'], type: 'object' } }, steps: [
         set('auth_restart', 'auth_restart', "retrying === true || retrying === 'true'"),
         set('auth_previous_options', 'auth_previous_options', 'cargo.authOptions ? Object.assign({},cargo.authOptions) : null'),
-        when('auth_declined_caller', "declined_caller === true || declined_caller === 'true'", effect('auth_decline_state', "(cargo.callerDeclined=true,cargo.callerPreselected=false,cargo.otpHash=null,cargo.contactIntroSkip=true,cargo.callerNamed ? (cargo.displayName='',cargo.displayNameSetBy='flow',cargo.callerNamed=false) : true,true)")),
+        when('auth_declined_caller', "declined_caller === true || declined_caller === 'true'", effect('auth_decline_state', "(cargo.callerDeclined=true,cargo.callerPreselected=false,cargo.otpHash=null,cargo.otpAltHash=null,cargo.otpAltTimestamp=null,cargo.contactIntroSkip=true,cargo.callerNamed ? (cargo.displayName='',cargo.displayNameSetBy='flow',cargo.callerNamed=false) : true,true)")),
         when('auth_already_verified', 'cargo.otpVerified === true', end('auth_verified_end')),
         ...authKeys.map(key => set('auth_option_' + key, key, `auth_restart && cargo.authOptions ? cargo.authOptions.${key} || ${key === 'retry_returns' ? 'false' : "''"} : ${key}`)),
         set('auth_default_retry', 'retry_flow', "retry_flow || 'authenticate-user'"), set('auth_default_cancel', 'cancel_flow', "cancel_flow || 'contact-support'"),
@@ -165,22 +168,53 @@ const auth = worker('authenticate-user', 'AuthenticateUser', 'Authenticate a con
         when('auth_join_challenge', 'auth_join', call('auth_join_collect', 'get-and-validate-otp-code')),
         when('auth_join_release', 'auth_join', call('auth_join_gate_end', 'task-gate', { form: '{{parent_form}}', gate: 'authenticate-user', active: false })),
         when('auth_join_return', 'auth_join', end('auth_join_complete')),
-        effect('auth_challenge_init', "(cargo.otpLateCode='',cargo.otpResends=0,cargo.otpMismatches=0,cargo.otpFormatMisses=0,cargo.otpWordMisses=0,cargo.otp_cell_number=cell_number || '',cargo.otp_email=email || '',true)"),
+        effect('auth_challenge_init', "(cargo.otpLateCode='',cargo.otpResends=0,cargo.otpMismatches=0,cargo.otpFormatMisses=0,cargo.otpWordMisses=0,cargo.otp_cell_number=cell_number || '',cargo.otp_email=email || '',cargo.otpAltSent=false,cargo.otpAltHash=null,cargo.otpAltTimestamp=null,true)"),
         call('auth_send', 'send-otp-code'), when('auth_send_failed', 'cargo.otpSendFailure', call('auth_send_failure', 'otp-send-failed', undefined, 'replace')),
         call('auth_code', 'get-and-validate-otp-code'),
         cases('auth_complete', { 'condition: cargo.otpVerified === true': set('auth_ok', 'auth_result', 'true'), 'condition: cargo.authRetry': end('auth_return_retry'), default: otpMenu('auth_retry_code', "I couldn't verify your account. You can try again or use another contact.", 'No pude verificar su cuenta. Puede intentarlo de nuevo o usar otro contacto.', true) }),
         call('auth_gate_end', 'task-gate', { form: '{{parent_form}}', gate: 'authenticate-user', active: false })
     ] });
+// Where the code went, for a caller who asks ('¿dónde está?'): the channel and the masked destination, never the code.
+export function otpWhere(cargo, es = false) {
+    const number = String(cargo.otp_cell_number || '').replace(/\D/g, '').slice(-4), tail = cargo.voice ? number.split('').join(', ') : number;
+    if (cargo.otpSentOn === 'whatsapp')
+        return es ? 'Se lo acabo de enviar aquí en este chat.' : 'I just sent it to you here in this chat.';
+    const mail = String(cargo.otpAltEmail || ''), at = mail.indexOf('@'), masked = cargo.voice ? (es ? 'que empieza con ' : 'starting with ') + mail.charAt(0).toUpperCase() + (es ? ', arroba ' : ', at ') + mail.slice(at + 1) : mail.charAt(0) + '…@' + mail.slice(at + 1);
+    if (cargo.otp_cell_number && cargo.otpAltSent === true)
+        return es ? 'Se lo envié por mensaje de texto al celular que termina con ' + tail + ', y también le envié un código a su correo ' + masked + '. Revise sus mensajes de texto y su correo.' : 'I sent it by text message to the cell ending with ' + tail + ', and I also sent a code to your email ' + masked + '. Check your text messages and your email.';
+    if (cargo.otp_cell_number)
+        return es ? 'Se lo envié por mensaje de texto al celular que termina con ' + tail + '. Revise sus mensajes de texto.' : 'I sent it by text message to the cell ending with ' + tail + '. Check your text messages.';
+    return es ? 'Se lo envié por correo electrónico a ' + String(cargo.otp_email || '') + '. Revise su correo.' : 'I sent it by email to ' + String(cargo.otp_email || '') + '. Check your email.';
+}
 export function otpPrompt(cargo, es = false) {
     const verb = es ? cargo.verb_es : cargo.verb, number = String(cargo.otp_cell_number || '').replace(/\D/g, '').slice(-4), tail = cargo.voice ? number.split('').join(', ') : number;
     const where = cargo.otpSentOn === 'whatsapp' ? (es ? 'que le acabo de enviar aquí en este chat' : 'I just sent you here in this chat') : (es ? 'que recibió en ' : 'you received at ') + (cargo.otp_cell_number ? (es ? 'celular que termina con ' : 'cell ending with ') + tail : (es ? 'correo electrónico: ' : 'email: ') + String(cargo.otp_email || ''));
+    const mail = String(cargo.otpAltEmail || ''), at = mail.indexOf('@'), also = cargo.otp_cell_number && cargo.otpAltSent === true ? (es ? ' o en su correo ' : ' or at your email ') + (cargo.voice ? (es ? 'que empieza con ' : 'starting with ') + mail.charAt(0).toUpperCase() + (es ? ', arroba ' : ', at ') + mail.slice(at + 1) : mail.charAt(0) + '…@' + mail.slice(at + 1)) : '';
     const name = cargo.callerPreselected && cargo.callerNamed && cargo.displayName ? cargo.displayName : '';
-    return (name ? name + (es ? ', por favor' : ', please') : es ? 'Por favor' : 'Please') + ' ' + verb + ' ' + (cargo.voice ? es ? 'o ingrese ' : 'or enter ' : '') + (es ? 'el código de verificación de 6 dígitos ' : 'the 6-digit verification code ') + where + '. ' + (es ? `También puede ${cargo.voice ? 'presionar * o decir' : 'escribir'} SALIR para cancelar.` : `You can also ${cargo.voice ? 'press * or ' : ''}${verb} EXIT to cancel.`) + (cargo.callerPreselected ? (es ? ` Para usar otra cuenta, ${verb} OTRA CUENTA.` : ` To use another account, ${verb} ANOTHER ACCOUNT.`) : '');
+    const lead = String((es ? cargo.otpIntro_es : cargo.otpIntro) || '');
+    return (lead ? lead + ' ' : '') + (name ? name + (es ? ', por favor' : ', please') : es ? 'Por favor' : 'Please') + ' ' + verb + ' ' + (cargo.voice ? es ? 'o ingrese ' : 'or enter ' : '') + (es ? 'el código de verificación de 6 dígitos ' : 'the 6-digit verification code ') + where + also + '. ' + (es ? `También puede ${cargo.voice ? 'presionar * o decir' : 'escribir'} SALIR para cancelar.` : `You can also ${cargo.voice ? 'press * or ' : ''}${verb} EXIT to cancel.`) + (cargo.callerPreselected ? (es ? ` Para usar otra cuenta, ${verb} OTRA CUENTA.` : ` To use another account, ${verb} ANOTHER ACCOUNT.`) : '');
+}
+/** What the caller hears when a second code goes to the account's email: the address masked to its first letter and domain. */
+export function otpAlsoSent(cargo, es = false) {
+    const mail = String(cargo.otpAltEmail || ''), at = mail.indexOf('@'), masked = cargo.voice ? (es ? 'que empieza con ' : 'starting with ') + mail.charAt(0).toUpperCase() + (es ? ', arroba ' : ', at ') + mail.slice(at + 1) : mail.charAt(0) + '…@' + mail.slice(at + 1);
+    return es ? 'Muy bien, también le envié un código a su correo ' + masked + '.' : 'Okay, I also sent a code to your email ' + masked + '.';
 }
+// The caller cannot find the texted code (or asks for another way, or for email): a second code goes to the account's email
+// (cargo.otpAltEmail, set by the tenant's contact step when the code goes to a cell), once per challenge, without a question.
+// The texted code stays valid beside it (send-email-otp additional: otpAltHash). A refused address says where the code went.
+const emailToo = worker('send-otp-email-too', 'SendOtpEmailToo', "Email a second one-time code to the account's email beside the texted one, and say so.", { variables: vars({ alt_hash: '', also_sent: '', also_sent_es: '', otp_where: '', otp_where_es: '' }), contract: { role: 'worker', summary: "Second one-time code to the account's email", tools: ['send-email-otp'] }, steps: [
+        { id: 'otp_email_too_send', type: 'CALL-TOOL', tool: 'send-email-otp', variable: 'alt_hash', args: { to: '{{cargo.otpAltEmail}}', container: '{{cargo}}', language: '{{language}}', additional: true }, onFail: set('otp_email_too_failed', 'alt_hash', "''") },
+        effect('otp_email_too_state', "(cargo.otpAltSent=/^[0-9a-f]{64}$/.test(String(alt_hash || ''))?true:'failed',true)"),
+        set('otp_email_too_said', 'also_sent', expression(otpAlsoSent, 'cargo')), set('otp_email_too_said_es', 'also_sent_es', expression(otpAlsoSent, 'cargo', 'true')),
+        set('otp_email_too_where', 'otp_where', expression(otpWhere, 'cargo')), set('otp_email_too_where_es', 'otp_where_es', expression(otpWhere, 'cargo', 'true')),
+        cases('otp_email_too_say', { 'condition: cargo.otpAltSent === true': say('otp_email_too_sent', '{{also_sent}}', '{{also_sent_es}}'), default: say('otp_email_too_refused', '{{otp_where}}', '{{otp_where_es}}') })
+    ] });
 const OTP_PROFILES = [{ name: 'code', label: 'verification code', label_es: 'código de verificación', profile: { kind: 'digits', min: 6, max: 6 } }, raw];
 const code = worker('get-and-validate-otp-code', 'GetAndValidateOtpCode', 'Collect a one-time-code answer through the owning FORM ancestry, preserving protocol commands for validation.', { variables: vars({ otp_code: '', user_choice: '', normalized_otp_code: '', otp_question: '', otp_question_es: '', otp_profiles: OTP_PROFILES }), contract: { role: 'collector', summary: 'One-time-code answer collector using shared FORM matching' }, steps: [
         when('otp_already_verified', 'cargo.otpVerified === true', end('otp_existing_verification')),
         set('otp_question', 'otp_question', expression(otpPrompt, 'cargo')), set('otp_question_es', 'otp_question_es', expression(otpPrompt, 'cargo', 'true')),
+        // a contact question's unsaid intro (identity_contact_intro_unsaid) leads the first code question only
+        effect('otp_intro_said', "(cargo.otpIntro='',cargo.otpIntro_es='',true)"),
         call('otp_collect', 'collect-service-answer', { profiles: '{{otp_profiles}}', question: '{{otp_question}}', question_es: '{{otp_question_es}}', keypad: { min: 6, max: 6 }, parent_form: '{{cargo.authOptions.parent_form}}', stop_path: 'cargo.otpVerified', context: 'account verification', context_es: 'verificación de cuenta' }),
         when('otp_verified_by_join', 'cargo.otpVerified === true', end('otp_join_finished')),
         set('otp_answer', 'otp_code', "String(cargo.serviceAnswer.values.code || cargo.serviceAnswer.raw || '')"), set('otp_choice', 'user_choice', 'otp_code.trim().toLowerCase()'), set('otp_digits', 'normalized_otp_code', expression(otpDigits, 'otp_code')),
@@ -193,6 +227,9 @@ const OTP_WORDS = {
     other_alone: ['otra', 'otro', 'another', 'other'],
     email: ['email', 'e-mail', 'e mail', 'emails', 'correo', 'correos', 'correo electrónico', 'correo electronico', 'imeil'],
     resend: ['resend', 'send again', 'send it again', 'not received', 'never received', 'did not receive', 'didn t receive', 'didn t get', 'haven t received', 'nothing came', 'no code', 'no text', 'no llegó', 'no llego', 'no llega', 'no ha llegado', 'no me llegó', 'no me llego', 'no le llegó', 'no le llego', 'no me ha llegado', 'no recibí', 'no recibi', 'no lo recibí', 'no lo recibi', 'no tengo el código', 'no tengo el codigo', 'no lo tengo', 'no alcancé', 'no alcance', 'mándame el código', 'mandame el codigo', 'envíame el código', 'enviame el codigo', 'reenviar', 'reenvíe', 'reenvie'],
+    // the caller cannot find the texted code, or asks for another way to get it or to verify
+    cannot_find: ['don t have it', 'i don t have it', 'don t have the code', 'i don t have the code', 'can t find', 'cannot find', 'can not find', 'couldn t find', 'could not find', 'can t find it', 'cannot find it', 'i can t find', 'i cannot find', 'not there', 'isn t there', 'it s not there', 'there s no code', 'no encuentro', 'no lo encuentro', 'no la encuentro', 'no encuentro el código', 'no encuentro el codigo', 'no aparece', 'no hay código', 'no hay codigo'],
+    another_way: ['another way', 'different way', 'other way', 'some other way', 'a different way', 'another option', 'other option', 'otra forma', 'otra manera', 'de otra forma', 'de otra manera', 'otra opción', 'otra opcion', 'hay otra forma', 'hay otra manera'],
     later: ['driving', 'i am driving', 'i m busy', 'im busy', 'not now', 'later', 'call me later', 'call back', 'cant right now', 'can t right now', 'can t now', 'cannot right now', 'manejando', 'conduciendo', 'estoy manejando', 'voy manejando', 'ahora no', 'ahora no puedo', 'no puedo ahora', 'más tarde', 'mas tarde', 'estoy ocupado', 'estoy ocupada'],
     noPhone: ['don t have that phone', 'don t have that number', 'don t have that phone anymore', 'don t have the phone', 'not my number anymore', 'not my phone anymore', 'that s an old number', 'old number', 'changed my number', 'changed my phone', 'lost my phone', 'no tengo ese teléfono', 'no tengo ese telefono', 'no tengo ese número', 'no tengo ese numero', 'ya no tengo ese', 'ya no tengo el teléfono', 'ya no tengo el telefono', 'ya no es mi número', 'ya no es mi numero', 'número viejo', 'numero viejo', 'cambié de número', 'cambie de numero', 'cambié mi número', 'perdí mi teléfono', 'perdi mi telefono', 'don t have a phone', 'don t have phone', 'don t have my phone', 'don t have a cell', 'don t have the cell', 'don t have my cell', 'don t have a cell phone', 'don t have access to that phone', 'don t have access to the phone', 'no tengo teléfono', 'no tengo telefono', 'no tengo celular', 'no tengo el celular', 'no tengo mi teléfono', 'no tengo mi telefono', 'no tengo mi celular', 'no tengo un teléfono', 'no tengo un telefono', 'no tengo acceso a ese teléfono', 'no tengo acceso a ese telefono']
 };
@@ -206,24 +243,29 @@ function otpPhoneUnavailable(value) {
 // What the reply ranker may take at the code question beside the code: the step's offers. Email and another account are
 // offered only where the step offers them (a code sent by text; a caller-ID preselection).
 const OTP_REPLY_CHOICES = [{ key: 'email', label: 'use the email on the account instead of the phone' }, { key: 'another_account', label: 'use another account' },
-    { key: 'resend', label: 'the code did not arrive; send it again' }, { key: 'no_phone', label: 'no longer has that phone or number' }, { key: '__agent', label: 'speak with a person (a live agent)' }];
-const validateCode = worker('validate-otp-code', 'ValidateOtpCode', 'Validate a challenge response with explicit bounded retries, alternate-contact handling and tenant callbacks.', { variables: vars({ otp_phrases: OTP_WORDS, no_code_given: false, wants_other_account: false, other_account_given: false, otp_validation_result: false, whatsapp_invite_sent: false, invite_text: '', otp_cancel: 'contact-support', answer_key: '', answer_value: '', otp_reply_choices: OTP_REPLY_CHOICES, otp_offers: [], otp_reply: {} }), contract: { role: 'gate', summary: 'Validate the active one-time challenge', tools: ['validate-otp', 'send-whatsapp-invite'], result: { path: 'cargo.otpVerified', type: 'boolean' } }, steps: [
+    { key: 'where', label: 'asks where the code was sent' }, { key: 'cannot_find', label: 'cannot find the code, or it is not there' }, { key: 'another_way', label: 'asks for another way to get the code or to verify' }, { key: 'resend', label: 'the code did not arrive; send it again' }, { key: 'no_phone', label: 'no longer has that phone or number' }, { key: '__agent', label: 'speak with a person (a live agent)' }];
+const validateCode = worker('validate-otp-code', 'ValidateOtpCode', 'Validate a challenge response with explicit bounded retries, alternate-contact handling and tenant callbacks.', { variables: vars({ otp_phrases: OTP_WORDS, email_too: false, no_code_given: false, wants_other_account: false, other_account_given: false, otp_validation_result: false, whatsapp_invite_sent: false, invite_text: '', otp_cancel: 'contact-support', answer_key: '', answer_value: '', otp_reply_choices: OTP_REPLY_CHOICES, otp_offers: [], otp_reply: {}, otp_where: '', otp_where_es: '' }), contract: { role: 'gate', summary: 'Validate the active one-time challenge', tools: ['validate-otp', 'send-whatsapp-invite'], result: { path: 'cargo.otpVerified', type: 'boolean' } }, steps: [
         set('otp_cancel', 'otp_cancel', "cargo.authCancelFlow || 'contact-support'"),
+        set('otp_email_too_ready', 'email_too', "!!(cargo.otp_cell_number && cargo.otpAltSent !== true && cargo.otpAltSent !== 'failed' && validateEmail(String(cargo.otpAltEmail || '')))"),
         set('otp_reset_no_code', 'no_code_given', 'false'), set('otp_reset_invite', 'whatsapp_invite_sent', 'false'), set('otp_reset_callback', 'answer_key', "''"),
         when('otp_tenant_code', 'cargo.authOptions && cargo.authOptions.code_validator && normalized_otp_code.length !== 6 && /[0-9]/.test(user_choice)', call('otp_tenant_code_call', '{{cargo.authOptions.code_validator}}', { answer: '{{user_choice}}' })),
         set('otp_other_given', 'other_account_given', "answer_key === 'another_account' ? (cargo.authOtherAccount=String(answer_value || ''),true) : false"),
         set('otp_other_requested', 'wants_other_account', 'other_account_given || !!(cargo.callerPreselected && normalized_otp_code.length !== 6 && (matchesChoice(user_choice,otp_phrases.other) || otp_phrases.other_alone.includes(user_choice.replace(/[.,!?¡¿]/g,\'\').trim())))'),
         when('otp_tenant_answer', 'cargo.authOptions && cargo.authOptions.answer_handler && normalized_otp_code.length !== 6 && !wants_other_account', call('otp_tenant_answer_call', '{{cargo.authOptions.answer_handler}}', { answer: '{{user_choice}}' })),
+        set('otp_where_early', 'otp_where', expression(otpWhere, 'cargo')), set('otp_where_early_es', 'otp_where_es', expression(otpWhere, 'cargo', 'true')),
         cases('otp_response', {
             'condition: normalized_otp_code.length === 6': { id: 'otp_check_tool', type: 'CALL-TOOL', tool: 'validate-otp', variable: 'otp_validation_result', args: { otp: '{{normalized_otp_code}}', container: '{{cargo}}' }, onFail: call('otp_check_failed', 'get-and-validate-otp-code', undefined, 'replace') },
             'condition: wants_other_account': call('otp_change_account', 'authenticate-user', { cell_number: '', email: '', retrying: true, declined_caller: true }, 'replace'),
             // Email asked for at a code sent by text: authentication is an input step, so the contact question is asked again
             // (without the caller-ID offer) and the caller gives the email; a code sent by email keeps "no me llegó el correo" a resend.
+            ['condition: email_too && normalized_otp_code.length !== 6 && (' + 'matchesChoice(user_choice,otp_phrases.resend) || matchesChoice(user_choice,otp_phrases.cannot_find) || matchesChoice(user_choice,otp_phrases.another_way) || matchesChoice(user_choice,otp_phrases.email)' + ')']: call('otp_email_too', 'send-otp-email-too'),
             'condition: !!cargo.otp_cell_number && normalized_otp_code.length !== 6 && matchesChoice(user_choice,otp_phrases.email)': call('otp_use_email', 'authenticate-user', { cell_number: '', email: '', retrying: true, declined_caller: true }, 'replace'),
             "condition: isExitRequest(user_choice)": call('otp_exit', '{{otp_cancel}}', undefined, 'reboot'),
             "condition: isAnswer(user_choice,'agent')": call('otp_agent', 'live-agent-requested', undefined, 'reboot'),
             "condition: isAnswer(user_choice,'text')": call('otp_text', 'switch-to-text', undefined, 'reboot'),
             'condition: matchesChoice(user_choice,otp_phrases.resend)': call('otp_resend', 'resend-otp-code', { resend_reason: 'requested' }),
+            'condition: matchesChoice(user_choice,otp_phrases.cannot_find)': say('otp_cannot_find', '{{otp_where}}', '{{otp_where_es}}'),
+            'condition: matchesChoice(user_choice,otp_phrases.another_way)': say('otp_no_other_way', '{{otp_where}} To reach a person, {{cargo.verb}} AGENT.', '{{otp_where_es}} Para hablar con una persona, {{cargo.verb_es}} AGENTE.'),
             'condition: matchesChoice(user_choice,otp_phrases.later)': say('otp_later', "No problem. Say TEXT and I'll continue with you by message so you can do this when you are free, or {{cargo.verb}} the code whenever you are ready.", 'No hay problema. Diga TEXTO y sigo con usted por mensaje para que lo haga cuando esté libre, o {{cargo.verb_es}} el código cuando pueda.'),
             'condition: normalized_otp_code.length > 0 && Number(cargo.otpFormatMisses || 0)<2': say('otp_bad_format', "I was expecting a 6-digit code. Let's try again. You can also {{cargo.voice ? 'press * or ' : ''}}{{cargo.verb}} EXIT to cancel.", "Esperaba un código de 6 dígitos. Intentemos de nuevo. También puede {{cargo.voice ? 'presionar * o decir' : 'escribir'}} SALIR para cancelar."),
             'condition: normalized_otp_code.length > 0': effect('otp_format_cap_next', 'true'),
@@ -243,10 +285,14 @@ const validateCode = worker('validate-otp-code', 'ValidateOtpCode', 'Validate a
             + ".concat(((typeof $callers !== 'undefined' && $callers && $callers['authenticate-user']) || []).map(function(c){return {key:'usecase:'+c.id,label:'states the reason for the call: '+c.label};}))"
             + ".concat(((typeof $gateExits !== 'undefined' && $gateExits && $gateExits['authenticate-user']) || []).map(function(a){return {key:'exit:'+a.key,label:a.label,route:'new_request'};}))"),
         when('otp_off_topic', 'no_code_given', { id: 'otp_reply_rank', type: 'DISPATCH', onResponse: 'continue', responseContext: 'Please say the 6-digit verification code I sent you. (Por favor diga el código de verificación de 6 dígitos que le envié.)', responseChoices: 'otp_offers', responseVariable: 'otp_reply', onNoIntent: 'stay' }),
+        set('otp_where', 'otp_where', expression(otpWhere, 'cargo')), set('otp_where_es', 'otp_where_es', expression(otpWhere, 'cargo', 'true')),
         set('otp_reply_picked', 'no_code_given', "no_code_given && !(otp_reply && otp_reply.key && String(otp_reply.key).indexOf('usecase:') !== 0)"),
         cases('otp_reply_route', {
+            "condition: !no_code_given && email_too && otp_reply && ['email','resend','cannot_find','another_way'].includes(otp_reply.key)": call('otp_ranked_email_too', 'send-otp-email-too'),
             "condition: !no_code_given && otp_reply && otp_reply.key === 'email'": call('otp_ranked_email', 'authenticate-user', { cell_number: '', email: '', retrying: true, declined_caller: true }, 'replace'),
             "condition: !no_code_given && otp_reply && otp_reply.key === 'another_account'": call('otp_ranked_account', 'authenticate-user', { cell_number: '', email: '', retrying: true, declined_caller: true }, 'replace'),
+            "condition: !no_code_given && otp_reply && (otp_reply.key === 'where' || otp_reply.key === 'cannot_find')": say('otp_ranked_where', '{{otp_where}}', '{{otp_where_es}}'),
+            "condition: !no_code_given && otp_reply && otp_reply.key === 'another_way'": say('otp_ranked_no_other_way', '{{otp_where}} To reach a person, {{cargo.verb}} AGENT.', '{{otp_where_es}} Para hablar con una persona, {{cargo.verb_es}} AGENTE.'),
             "condition: !no_code_given && otp_reply && otp_reply.key === 'resend'": call('otp_ranked_resend', 'resend-otp-code', { resend_reason: 'requested' }),
             "condition: !no_code_given && otp_reply && otp_reply.key === 'no_phone'": otpMenu('otp_ranked_no_phone', "No problem. Then the code can't reach you there. You can use the email on your account instead, or {{cargo.verb}} AGENT to reach a person.", 'No hay problema. Entonces el código no le puede llegar ahí. Puede usar el correo electrónico de su cuenta, o {{cargo.verb_es}} AGENTE para hablar con una persona.', false),
             "condition: !no_code_given && otp_reply && otp_reply.key === '__agent'": call('otp_ranked_agent', 'live-agent-requested', undefined, 'reboot'),
@@ -261,7 +307,7 @@ const validateCode = worker('validate-otp-code', 'ValidateOtpCode', 'Validate a
         when('otp_format_cap', 'normalized_otp_code.length !== 6 && cargo.otpFormatMisses >= 3', otpMenu('otp_format_menu', "I still don't have a 6-digit code. To reach a person, {{cargo.verb}} AGENT.", 'Todavía no tengo un código de 6 dígitos. Para hablar con una persona, {{cargo.verb_es}} AGENTE.', true)),
         when('otp_format_retry', 'normalized_otp_code.length !== 6', call('otp_collect_again', 'get-and-validate-otp-code', undefined, 'replace')),
         effect('otp_mismatch_count', "(cargo.otpMismatches=Number(cargo.otpMismatches || 0)+(!cargo.otpVerified && cargo.otpFailure === 'mismatch'?1:0),true)"),
-        when('otp_mismatch_cap', "!cargo.otpVerified && cargo.otpFailure === 'mismatch' && cargo.otpMismatches >= 3", effect('otp_withdraw', '(cargo.otpHash=null,true)')),
+        when('otp_mismatch_cap', "!cargo.otpVerified && cargo.otpFailure === 'mismatch' && cargo.otpMismatches >= 3", effect('otp_withdraw', '(cargo.otpHash=null,cargo.otpAltHash=null,cargo.otpAltTimestamp=null,true)')),
         cases('otp_verified_result', {
             'condition: cargo.otpVerified === true': effect('otp_verified_record', '(cargo.otpLateCode=String(normalized_otp_code),true)'),
             "condition: cargo.otpFailure === 'expired' || cargo.otpFailure === 'missing'": call('otp_refresh', 'resend-otp-code', { resend_reason: '{{cargo.otpFailure}}' }),
@@ -349,4 +395,4 @@ const resume = worker('resume-identity-caller', 'ResumeIdentityCaller', 'Resume
     steps: [set('identity_resume_context', 'resume_context', expression(identityResumeContext, 'cargo.forms', 'parent_form', 'retry_flow', '{acct_number:acct_number,cell_number:cell_number,email:email}')),
         call('identity_resume_caller', '{{retry_flow}}', { form_instance: '{{resume_context.form_instance}}', parent_form: '{{resume_context.parent_form}}', result_input: '{{resume_context.result_input}}', gate_options: '{{gate_options}}', cell_number: '{{cell_number}}', email: '{{email}}', acct_number: '{{acct_number}}' }, 'replace')]
 });
-export const FLOWS = [taskGate, resume, service, rawTransport, contact, declined, splitFailed, rejected, auth, code, validateCode, retry, email];
+export const FLOWS = [taskGate, resume, service, rawTransport, contact, declined, splitFailed, rejected, auth, code, validateCode, emailToo, retry, email];

package/dist/forms/index.d.ts

@@ -2,6 +2,7 @@ export const FLOWS: any[];
 export { FLOWS as IDENTITY_FLOWS } from "./identity-flows.js";
 export { compileFormPrompts } from "./prompt-compiler.js";
 export { explainSession } from "./inspection.js";
+export { continuationBreaks } from "./continuation-compat.js";
 export { inheritFlowDeclaration } from "./declaration-capture.js";
 export { withSafetyRevision, CONTINUATION_SAFETY_REQUIREMENT } from "./continuation-safety.js";
 export { FIELD_PRESETS, formFlow, declinedFlow, textValue } from "./flows.js";

package/dist/forms/index.js

@@ -13,4 +13,5 @@ export { addressDraft, zipLocation, streetLocation, resolvedAddress } from '../h
 export { explainSession } from './inspection.js';
 export { Form, Provider, Performer, Worker, compileExpression } from './authoring.js';
 export { compileFlowDeclarations, serializeFlowDeclaration, captureOriginalDeclaration } from './declarations.js';
+export { continuationBreaks } from './continuation-compat.js';
 export { inheritFlowDeclaration } from './declaration-capture.js';

package/dist/helpers/address.d.ts

@@ -16,6 +16,7 @@ export function streetLocation(result: any, said: any, zip: any): {
     street: string;
     said: string;
     verified: boolean;
+    city: any;
 };
 export function resolvedAddress(values: any, data: any): {
     street: any;

package/dist/helpers/address.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"address.d.ts","sourceRoot":"","sources":["../../src/helpers/address.js"],"names":[],"mappings":"AAAA,uFAAuF;AACvF;;;;;EAQC;AACD;;;;;SASC;AACD,gDAEC;AACD;;;;EAMC;AACD;;;;;;;;EAIC"}
+{"version":3,"file":"address.d.ts","sourceRoot":"","sources":["../../src/helpers/address.js"],"names":[],"mappings":"AAAA,uFAAuF;AACvF;;;;;EAQC;AACD;;;;;SASC;AACD,gDAEC;AACD;;;;;EASC;AACD;;;;;;;;EAIC"}

package/dist/helpers/address.js

@@ -27,7 +27,10 @@ export function streetLocation(result, said, zip) {
     const part = kind => components.find(c => (c.types || []).includes(kind))?.long_name || '';
     const types = row.types || [], locationType = row.location_type || row.geometry?.location_type || '';
     const exact = result?.status === 'OK' && row.partial_match !== true && types.includes('street_address') && locationType === 'ROOFTOP' && part('street_number') && part('route') && (!part('postal_code') || part('postal_code') === zip);
-    return { street: exact ? part('street_number') + ' ' + part('route') : String(said).trim(), said: String(said).trim(), verified: !!exact };
+    // An exact street match names the place its mail carries; it corrects a city read from the ZIP code alone (90805 is
+    // Lakewood to the ZIP lookup, while its streets are Long Beach and Lakewood)
+    const city = exact ? part('locality') || part('postal_town') || part('sublocality') : '';
+    return { street: exact ? part('street_number') + ' ' + part('route') : String(said).trim(), said: String(said).trim(), verified: !!exact, city };
 }
 export function resolvedAddress(values, data) {
     const unit = /^(none|no|ninguno|ninguna|sin|no hay)$/i.test(String(values.unit || '')) ? '' : String(values.unit || '').replace(/^(apt\.?|unit|#)\s*/i, '');

package/dist/helpers/form-actions.js

@@ -1,4 +1,4 @@
-/** Session-owned action state. Backend idempotency and reconciliation remain explicit parts of the action contract. */
+/** Session-owned action state. */
 import { nextFormInput, formPath, formInputApplies } from './form-state.js';
 export function formSignature(value) {
     return JSON.stringify(value, (_key, v) => v && typeof v === 'object' && !Array.isArray(v)