jsfe 1.6.0 → 1.7.0

package/dist/helpers/answer.js

@@ -232,7 +232,9 @@ const DOLLARS_JOINED_CENTS = /(\$\s*)?(\d+)(\s*(?:dollars?|d[oó]lar(?:es)?|buck
  * one by one, are not amounts; two different remaining numbers are ambiguous unless exactly one is marked as money ($,
  * dollars, cents or decimals). "50 cents" alone is $0.50; "82 dollars and 50" and "82 con 50" are $82.50. Amounts said only in words are NaN (not parsed yet).
  */
-export function amountInAnswer(input) {
+export function amountInAnswer(input) { return numericAmountReading(input).value; }
+/** Internal numeric evidence shared by the opt-in money reader; legacy results stay unchanged. */
+export function numericAmountReading(input) {
     const raw = String(input ?? '').replace(/\\(['"\\])/g, '$1');
     // 1.234,56 (European) → 1234.56; 1,234.56 → 1234.56; 12,50 → 12.50
     let t = /\d{1,3}(\.\d{3})+,\d{1,2}\b/.test(raw) ? raw.replace(/\./g, '').replace(',', '.') : raw.replace(/,(?=\d{3}\b)/g, '').replace(/(\d),(\d{1,2})\b/g, '$1.$2');
@@ -259,11 +261,11 @@ export function amountInAnswer(input) {
         // no number at all
     }
     if (!pick) {
-        return NaN;
+        return { value: NaN, candidates: found.length };
     }
     else {
         // Cents alone only when nothing else was said: "76 con50 centavos" read as $0.50 (prod, 10-15).
-        return pick.cents ? (values.length === 1 ? Math.round(pick.v) / 100 : NaN) : pick.v;
+        return { value: pick.cents ? (values.length === 1 ? Math.round(pick.v) / 100 : NaN) : pick.v, candidates: found.length };
     }
 }
 // Number words a caller says for a keypad key (prod 2026-10-16 7:07 AM: "dos" at "presione 2 o diga NO" was re-asked).

package/dist/helpers/choice-offer.d.ts

@@ -0,0 +1,3 @@
+/** Consume the one-time conversational offer shared by question and terminal presenters. */
+export function takeChoiceOffer(cargo: any): any;
+//# sourceMappingURL=choice-offer.d.ts.map

package/dist/helpers/choice-offer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"choice-offer.d.ts","sourceRoot":"","sources":["../../src/helpers/choice-offer.js"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,iDAIC"}

package/dist/helpers/choice-offer.js

@@ -0,0 +1,6 @@
+/** Consume the one-time conversational offer shared by question and terminal presenters. */
+export function takeChoiceOffer(cargo) {
+    const offer = cargo.switchOffer;
+    cargo.switchOffer = null;
+    return offer && typeof offer === 'object' && !Array.isArray(offer) && typeof offer.flow === 'string' && offer.flow ? offer : null;
+}

package/dist/helpers/form-actions.d.ts

@@ -0,0 +1,13 @@
+export function formSignature(value: any): string;
+export function selectFormAction(cargo: any, id: any, actions: any): any;
+export function confirmFormRevision(cargo: any, id: any): boolean;
+export function prepareFormAction(cargo: any, id: any, action: any, request: any): any;
+/** Unknown SEND results may be retried only by a declared policy and a freshly accepted recovery choice. */
+export function authorizeFormActionRetry(cargo: any, id: any, action: any, consent: any): boolean;
+export function actionConfirmationValid(cargo: any, id: any, record: any): boolean;
+export function beginFormAction(cargo: any, id: any, action: any, record: any): boolean;
+export function actionGateVerified(cargo: any, action: any): boolean;
+export function finishFormAction(cargo: any, id: any, action: any, outcome: any): any;
+/** A result is consumed only after its effect-free domain projection succeeds. */
+export function consumeActionReceipt(cargo: any, receipt: any): boolean;
+//# sourceMappingURL=form-actions.d.ts.map

package/dist/helpers/form-actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"form-actions.d.ts","sourceRoot":"","sources":["../../src/helpers/form-actions.js"],"names":[],"mappings":"AAEA,kDAGC;AACD,yEAMC;AACD,kEAKC;AACD,uFAkBC;AACD,4GAA4G;AAC5G,kGAkBC;AACD,mFAGC;AACD,wFAYC;AACD,qEAGC;AACD,sFASC;AAED,kFAAkF;AAClF,wEAYC"}

package/dist/helpers/form-actions.js

@@ -0,0 +1,144 @@
+/** Session-owned action state. Backend idempotency and reconciliation remain explicit parts of the action contract. */
+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)
+        ? Object.fromEntries(Object.keys(v).sort().map(k => [k, v[k]])) : v);
+}
+export function selectFormAction(cargo, id, actions) {
+    const state = cargo.forms?.[id];
+    if (!state)
+        throw new Error('Cannot select an action without a form instance');
+    const eligible = (actions || []).filter(action => formInputApplies(action, state.values, cargo, state));
+    if (eligible.length > 1)
+        throw new Error('Ambiguous action selection');
+    return eligible[0] || null;
+}
+export function confirmFormRevision(cargo, id) {
+    const state = cargo.forms?.[id];
+    if (!state || nextFormInput(state, cargo))
+        throw new Error('Cannot confirm an incomplete form');
+    state.confirmation = { revision: state.revision, values: formSignature(state.values), proposal: state.proposal?.signature || null };
+    return true;
+}
+export function prepareFormAction(cargo, id, action, request) {
+    const state = cargo.forms?.[id];
+    if (!state || nextFormInput(state, cargo))
+        throw new Error('Cannot prepare action from an incomplete form');
+    if (!action?.action || !action.outcomes)
+        throw new Error('Action contract is missing');
+    const subject = action.subject ? formPath({ cargo, form: state, request }, action.subject) : null;
+    const scope = formSignature({ action: action.action, subject });
+    const signature = formSignature({ action: action.action, subject, request });
+    cargo.actionJournal ||= {};
+    const unresolved = Object.values(cargo.actionJournal).find(record => record.scope === scope && ['attempted', 'unknown'].includes(record.status));
+    state.actions ||= {};
+    if (unresolved) {
+        state.actions[action.action] = unresolved;
+        state.proposal = unresolved;
+        return unresolved;
+    }
+    const existing = state.actions[action.action];
+    if (existing?.signature === signature && existing.status !== 'superseded' && (existing.revision === state.revision || existing.status !== 'completed' || !(action.retry?.after || []).includes(existing.result?.status)))
+        return existing;
+    if (existing?.scope === scope && ['attempted', 'unknown'].includes(existing.status))
+        return existing;
+    const record = { key: globalThis.crypto.randomUUID(), signature, revision: state.revision, status: 'prepared', scope, request: structuredClone(request), action: action.action };
+    if (cargo.actionRetryAuthorizations?.[scope]) {
+        record.retryAuthorization = cargo.actionRetryAuthorizations[scope];
+        delete cargo.actionRetryAuthorizations[scope];
+    }
+    state.actions[action.action] = record;
+    state.proposal = record;
+    return record;
+}
+/** Unknown SEND results may be retried only by a declared policy and a freshly accepted recovery choice. */
+export function authorizeFormActionRetry(cargo, id, action, consent) {
+    const state = cargo.forms?.[id];
+    if (action?.effect !== 'send' || action.retry?.unknown !== 'explicit')
+        throw new Error('Action does not allow an explicit unknown-result retry');
+    if (!state || !consent?.input || !state.accepted[consent.input] || state.errors[consent.input] || state.pending[consent.input] || state.values[consent.input] !== consent.value)
+        throw new Error('Retry requires an accepted recovery choice');
+    const scope = formSignature({ action: action.action, subject: action.subject ? formPath({ cargo, form: state }, action.subject) : null });
+    const consentKey = formSignature({ scope, input: consent.input, sequence: state.accepted[consent.input].sequence ?? state.accepted[consent.input].revision });
+    state.retryConsents ||= {};
+    if (state.retryConsents[consentKey])
+        throw new Error('Recovery consent was already consumed');
+    const records = Object.values(cargo.actionJournal || {}).filter(record => record.scope === scope && record.status === 'unknown');
+    if (records.length)
+        state.retryConsents[consentKey] = true;
+    for (const record of records) {
+        const authorization = { form: id, input: consent.input, value: consent.value, revision: state.revision, sequence: state.accepted[consent.input].sequence, at: Date.now() };
+        record.status = 'superseded';
+        record.retryAuthorization = authorization;
+        cargo.actionRetryHistory ||= [];
+        cargo.actionRetryHistory.push({ key: record.key, action: record.action, authorization });
+        cargo.actionRetryAuthorizations ||= {};
+        cargo.actionRetryAuthorizations[scope] = { previousKey: record.durableKey || record.key, authorization };
+        for (const owner of Object.values(cargo.forms))
+            for (const previous of Object.values(owner.actions || {}))
+                if (previous.key === record.key) {
+                    previous.status = 'superseded';
+                    previous.retryAuthorization = authorization;
+                }
+        delete cargo.actionJournal[record.key];
+    }
+    return true;
+}
+export function actionConfirmationValid(cargo, id, record) {
+    const state = cargo.forms?.[id], confirmation = state?.confirmation;
+    return !!confirmation && confirmation.revision === state.revision && confirmation.values === formSignature(state.values) && confirmation.proposal === record.signature;
+}
+export function beginFormAction(cargo, id, action, record) {
+    const state = cargo.forms?.[id];
+    if (!state || nextFormInput(state, cargo))
+        throw new Error('Cannot execute action from an incomplete form');
+    const owned = state.actions?.[action.action];
+    if (!owned || record.key !== owned.key || record.signature !== owned.signature)
+        throw new Error('Action ownership mismatch');
+    if (owned.status !== 'prepared' || !formInputApplies(action, state.values, cargo, state))
+        return false;
+    if (owned.signature !== formSignature({ action: action.action, subject: action.subject ? formPath({ cargo, form: state, request: owned.request }, action.subject) : null, request: owned.request }))
+        return false;
+    if (action.confirm?.exact && !actionConfirmationValid(cargo, id, owned))
+        return false;
+    if (!actionGateVerified(cargo, action))
+        return false;
+    owned.status = 'attempted';
+    cargo.actionJournal ||= {};
+    cargo.actionJournal[owned.key] = owned;
+    return true;
+}
+export function actionGateVerified(cargo, action) {
+    const gate = action.gate?.verified;
+    return !gate || [].concat(gate).every(path => !!formPath({ cargo }, path));
+}
+export function finishFormAction(cargo, id, action, outcome) {
+    const record = cargo.forms?.[id]?.actions?.[action.action];
+    if (!record || record.status !== 'attempted' && record.status !== 'unknown')
+        throw new Error('Action was not attempted');
+    const valid = outcome && Object.prototype.hasOwnProperty.call(action.outcomes, outcome.status);
+    record.result = valid ? outcome : { status: 'unknown', reason: 'invalid_action_result' };
+    record.status = record.result.status === 'unknown' ? 'unknown' : 'completed';
+    if (record.status === 'completed')
+        delete cargo.actionJournal?.[record.key];
+    else
+        cargo.actionJournal[record.key] = record;
+    return record.result;
+}
+/** A result is consumed only after its effect-free domain projection succeeds. */
+export function consumeActionReceipt(cargo, receipt) {
+    if (!receipt)
+        return true;
+    if (!receipt.key || !Number.isSafeInteger(receipt.sequence) || receipt.sequence < 1)
+        throw new Error('Invalid action receipt');
+    const key = receipt.key, sequence = receipt.sequence;
+    cargo.actionJournalSequence = Math.max(Number(cargo.actionJournalSequence || 0), sequence);
+    cargo.actionJournalApplied ||= {};
+    cargo.actionJournalApplied[key] = Math.max(Number(cargo.actionJournalApplied[key] || 0), sequence);
+    cargo.actionJournalReceipts ||= [];
+    if (!cargo.actionJournalReceipts.includes(key))
+        cargo.actionJournalReceipts.push(key);
+    cargo.actionJournalReceiptRevisions ||= {};
+    cargo.actionJournalReceiptRevisions[key] = Math.max(Number(cargo.actionJournalReceiptRevisions[key] || 0), sequence);
+    return true;
+}

package/dist/helpers/form-sources.d.ts

@@ -0,0 +1,7 @@
+export function sourceNeedsLoad(cargo: any, source: any, now?: number): boolean;
+export function beginSourceRefresh(cargo: any, source: any): boolean;
+export function completeSourceRefresh(cargo: any, source: any, now?: number): boolean;
+/** Prefer the most specific positively matched catalog phrase over a contained broad fact alias.
+ * Ordinary menu actions retain their own exact-choice rules. No match returns no fact. */
+export function pickProviderQuestion(answer: any, questions?: any[]): any;
+//# sourceMappingURL=form-sources.d.ts.map

package/dist/helpers/form-sources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"form-sources.d.ts","sourceRoot":"","sources":["../../src/helpers/form-sources.js"],"names":[],"mappings":"AAKA,gFAKC;AACD,qEASC;AACD,sFAKC;AAED;0FAC0F;AAC1F,0EAMC"}

package/dist/helpers/form-sources.js

@@ -0,0 +1,47 @@
+/** Provider freshness is tied to the subject and to a successful write by the loader. */
+import { formPath } from './form-state.js';
+import { pickChoice } from './answer.js';
+const present = value => value !== undefined && value !== null;
+const subject = (cargo, source) => source.subject ? JSON.stringify(formPath({ cargo }, source.subject) ?? null) : '';
+export function sourceNeedsLoad(cargo, source, now = Date.now()) {
+    if (!source?.result || !source.flow)
+        throw new Error('Provider source needs a result path and loader');
+    const have = formPath({ cargo }, source.result), at = cargo.sourceLoadedAt?.[source.result];
+    if (!present(have) || !at || cargo.sourceLoadedFor?.[source.result] !== subject(cargo, source))
+        return true;
+    return source.refresh === 'per_turn' || (source.max_age_ms !== undefined && now - at >= Number(source.max_age_ms));
+}
+export function beginSourceRefresh(cargo, source) {
+    const keys = String(source.result || '').split('.');
+    if (keys.shift() !== 'cargo' || !keys.length || keys.some(k => !k || ['__proto__', 'constructor', 'prototype'].includes(k)))
+        throw new Error('Provider result must be a safe cargo path');
+    let target = cargo;
+    for (const key of keys.slice(0, -1)) {
+        if (!target[key] || typeof target[key] !== 'object')
+            target[key] = {};
+        target = target[key];
+    }
+    delete target[keys[keys.length - 1]];
+    if (cargo.sourceLoadedAt)
+        delete cargo.sourceLoadedAt[source.result];
+    if (cargo.sourceLoadedFor)
+        delete cargo.sourceLoadedFor[source.result];
+    return true;
+}
+export function completeSourceRefresh(cargo, source, now = Date.now()) {
+    if (!present(formPath({ cargo }, source.result)))
+        return false;
+    cargo.sourceLoadedAt ||= {};
+    cargo.sourceLoadedFor ||= {};
+    cargo.sourceLoadedAt[source.result] = now;
+    cargo.sourceLoadedFor[source.result] = subject(cargo, source);
+    return true;
+}
+/** Prefer the most specific positively matched catalog phrase over a contained broad fact alias.
+ * Ordinary menu actions retain their own exact-choice rules. No match returns no fact. */
+export function pickProviderQuestion(answer, questions = []) {
+    const matches = questions.flatMap((question, index) => (question.words || []).flatMap(word => pickChoice(answer, [{ ...question, words: [word] }], false) === question.key
+        ? [{ key: question.key, length: String(word).normalize('NFD').replace(/[\u0300-\u036f]/g, '').trim().length, index }] : []));
+    matches.sort((a, b) => b.length - a.length || a.index - b.index);
+    return matches[0]?.key || '';
+}

package/dist/helpers/form-state.d.ts

@@ -0,0 +1,94 @@
+export function formValuesEqual(a: any, b: any): any;
+export function formPath(root: any, path: any): any;
+/** Resolve once before the state is used by collection, validation or completion. */
+export function resolveFormInputs(inputs: any, presets?: {}): any[];
+export function formInputApplies(input: any, values?: {}, cargo?: {}, state?: {}): boolean;
+export function formInputFilled(input: any, state: any, cargo?: {}, checking?: Set<any>): any;
+export function nextFormInput(state: any, cargo?: {}): any;
+export function formInputChain(forms: any, id: any, cargo?: {}): any[];
+/** Attach the canonical field contract to every claim, including independent ambiguity groups. */
+export function enrichFormMatches(matches: any, chain: any, form: any, names?: any[], asked?: string): any;
+/** Expand inferred controllers before normal ordering/validation. A slot's entry and controllers form one commit unit. */
+export function expandFormActivations(cargo: any, hits?: any[]): any[];
+/** No partial activation: validation failure suppresses inferred changes; pending prerequisites retain the complete group. */
+export function settleFormActivations(batch?: {}, cargo?: null): {
+    accepted: any[];
+    rejected: any[];
+    pending: any[];
+};
+/** Explicit ownership: unrelated tasks and sibling inputs never share an instance by definition id. */
+export function openFormInstance(cargo: any, definition: any, specs: any, { parent, input, resume, task, providers, questions, context, incomplete_outcome, on_exhausted }?: {
+    parent?: null | undefined;
+    input?: string | undefined;
+    resume?: string | undefined;
+    task?: string | undefined;
+    providers?: null | undefined;
+    questions?: null | undefined;
+    context?: boolean | undefined;
+    incomplete_outcome?: undefined;
+    on_exhausted?: undefined;
+}): any;
+/** An incomplete optional follow-up may preserve an explicitly completed task outcome. */
+export function validateFormIncompleteOutcome(value: any): {
+    outcome: any;
+    reason: any;
+} | null;
+/** Only actual owned ancestors may provide a fallback; another task's outcome is irrelevant. */
+export function formIncompleteOutcome(cargo: any, id: any, fallback?: {
+    outcome: string;
+    reason: string;
+}): {
+    owner: any;
+    outcome: any;
+    reason: any;
+} | {
+    owner: string;
+    outcome?: any;
+    reason?: any;
+};
+/** Explicit worker references only; recovery cannot contain an inline effect or caller expression. */
+export function validateFormExhaustion(value: any): string;
+/** Resolve nearest declared owner, release only its exhausted input branch, and withdraw old consent.
+ * A reboot to this worker unwinds the collector; no incomplete value is handed to an ancestor.
+ * Recovery must deliberately collect another choice before resuming the preserved owning draft.
+ */
+export function exhaustFormInput(cargo: any, failed_form: any, failed_input?: string): {
+    flow: string;
+    form: any;
+    failed_form: any;
+    input: string;
+    failed_input: string;
+    reason: string;
+} | null;
+/** Activation values are queued for the same validator flow as conversational readings. */
+export function rememberFormArguments(state: any, supplied: any, names: any, resume?: boolean): any;
+export function formInitialReadings(state: any, supplied?: {}, cargo?: {}): any;
+/** One exclusive group is clarified at a time; independent readings continue through the same protocol. */
+export function exclusiveFormReadings(cargo: any, hits?: any[]): {
+    ambiguous: any[];
+    hits: any[];
+};
+export function orderFormReadings(cargo: any, hits?: any[]): any[];
+export function formReadingDependencies(cargo: any, hit: any): any;
+export function rejectFormReadings(cargo: any, hits?: any[]): boolean;
+export function proposedFormValues(cargo: any, id: any, accepted?: any[]): any;
+export function formReadingRelevant(cargo: any, hit: any, accepted?: any[]): boolean;
+export function formReadingReady(cargo: any, hit: any, accepted?: any[], rejected?: any[]): boolean;
+export function formPreparation(cargo: any, id: any, input: any): {
+    flow: any;
+    input: any;
+} | null;
+export function queueFormReadings(cargo: any, hits?: any[]): boolean;
+export function pendingFormReadings(cargo: any, id: any): any[];
+export function formWorkLimit(cargo: any, id: any): number;
+export function applyFormValidation(cargo: any, id: any, result: any): "failed" | "retry" | "valid";
+/** Invalidation is transitive and independent of declaration order. */
+export function invalidateFormInputs(cargo: any, id: any, changed: any, preserve?: any[], preserveNodes?: any[]): any[];
+/** An intentional retry resets the named inputs as well as all of their dependent state. Unknown actions stay held. */
+export function resetFormInputs(cargo: any, id: any, names?: any[]): boolean;
+/** Commit only validated readings. Callers batch dependency-related candidates before invoking this transition. */
+export function acceptFormReadings(cargo: any, hits: any, additionalCandidates?: any[]): boolean;
+export function formInstanceApplies(cargo: any, id: any): any;
+export function closeFormInstance(cargo: any, id: any, handOn?: boolean): any;
+export function hasFormValue(v: any): boolean;
+//# sourceMappingURL=form-state.d.ts.map

package/dist/helpers/form-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"form-state.d.ts","sourceRoot":"","sources":["../../src/helpers/form-state.js"],"names":[],"mappings":"AAMA,qDAKC;AAED,oDAEC;AAED,qFAAqF;AACrF,oEAsBC;AAuCD,2FAEC;AACD,8FAcC;AACD,2DAOC;AACD,uEAuCC;AAED,kGAAkG;AAClG,2GAOC;AACD,0HAA0H;AAC1H,uEAwBC;AACD,8HAA8H;AAC9H;;;;EAWC;AACD,uGAAuG;AACvG;;;;;;;;;;QA8BC;AAED,0FAA0F;AAC1F;;;SAIC;AACD,gGAAgG;AAChG;;;;;;;;;;;EAQC;AAED,sGAAsG;AACtG,2DAIC;AACD;;;GAGG;AACH;;;;;;;SAkBC;AAED,2FAA2F;AAC3F,oGAIC;AACD,gFA4BC;AAED,2GAA2G;AAC3G;;;EASC;AACD,mEAoBC;AACD,mEAGC;AACD,sEAUC;AACD,+EAEC;AACD,qFASC;AACD,oGAoCC;AACD;;;SAKC;AACD,qEAGC;AACD,gEAgBC;AACD,2DAQC;AACD,oGAUC;AAED,uEAAuE;AACvE,wHA+BC;AAED,uHAAuH;AACvH,6EAaC;AACD,mHAAmH;AACnH,iGA4CC;AACD,8DAQC;AACD,8EAeC;AAljBM,8CAAmE"}