jsfe 1.4.2 → 1.5.0

package/dist/helpers/contact.js

@@ -0,0 +1,178 @@
+/**
+ * Reading a contact out of a customer's answer, ONE way for every flow set (APPROVED_FUNCTIONS readEmail, readPhone,
+ * readIdentifier), saying it back masked (last4, maskEmail), and where a text can reach the customer
+ * (callerTextNumber, textDestination). Before it, an email was read four different ways: only ask-email understood a spoken or spelled
+ * address ("juan at gmail dot com", "j u a n arroba gmail punto com"), so the same answer worked for a statement and
+ * failed at the identity question (flow design review 2026-10-13).
+ *
+ * Part of jsfe/helpers; zero imports.
+ */
+// Words that introduce an address and are never part of it ("my email is", "mi correo es", "send it to").
+const EMAIL_LEAD_IN = new Set(['my', 'mi', 'su', 'your', 'email', 'e-mail', 'mail', 'correo', 'electronico', 'electrónico',
+    'address', 'dirección', 'direccion', 'de', 'is', 'es', "it's", 'its', 'it', 'the', 'el', 'la', 'to', 'para', 'send',
+    'sent', 'envíalo', 'envialo', 'envía', 'envia', 'mandalo', 'mándalo', 'use', 'usa', 'please', 'por', 'favor', 'and', 'y',
+    'yes', 'yeah', 'yep', 'si', 'sí', 'ok', 'okay', 'sure', 'claro', 'hi', 'hello', 'hola', 'um', 'uh', 'eh', 'this', 'thats',
+    "that's", 'here', 'aqui', 'aquí', 'with', 'con', 'try', 'now', 'ahora']);
+/**
+ * The email address in the answer, lowercased, or ''. At / arroba and dot / punto may be spoken, and the name before
+ * the @ may come in several pieces ("J. A Garcia at example.com", "j u a n", "Maria jose@example.com"): every piece
+ * back to the first lead-in word ("my email is", "mi correo es") is kept and joined. On a call the address is read
+ * back for a YES / NO, so a misheard piece can be corrected; a dropped one could not. Accents are dropped from the
+ * name (an address cannot carry them), and only the last @ counts.
+ */
+export function readEmail(text) {
+    const spoken = String(text ?? '')
+        .replace(/\s+(?:at|arroba)\s+/gi, ' @ ')
+        .replace(/\s+(?:dot|punto)\s+/gi, '.')
+        .replace(/\s+(?:underscore|gui[oó]n bajo)[.,]?(?:\s+|$)/gi, '_')
+        .replace(/\s+(?:dash|hyphen|gui[oó]n)[.,]?(?:\s+|$)/gi, '-');
+    const at = spoken.lastIndexOf('@'); // a speech engine may write an @ inside the name too: the last one is the address's
+    if (at < 0) {
+        return '';
+    }
+    else {
+        const domain = (spoken.slice(at + 1).trim().match(/^[^\s@]+/) || [''])[0].replace(/[.,;:!?]+$/, '');
+        const pieces = spoken.slice(0, at).replace(/@/g, ' ').normalize('NFD').replace(/[\u0300-\u036f]/g, '').split(/[\s,;:!?]+/).map((w) => w.replace(/^[^a-z0-9]+|[^a-z0-9]+$/gi, '')).filter(Boolean);
+        const local = [];
+        for (let k = pieces.length - 1; k >= 0 && local.join('').length < 64; k--) {
+            // a one-letter lead-in ("y" = and) beside another single letter is a spelled letter ("s o n n y")
+            if (EMAIL_LEAD_IN.has(pieces[k].toLowerCase()) && !(pieces[k].length === 1 && k > 0 && pieces[k - 1].length === 1)) {
+                break;
+            }
+            else {
+                local.unshift(pieces[k]);
+            }
+        }
+        const email = (local.join('') + '@' + domain).toLowerCase();
+        return /^[a-z0-9][a-z0-9._%+-]*@[a-z0-9.-]+\.[a-z]{2,}$/.test(email) ? email : '';
+    }
+}
+/** The 10-digit North American number in the answer (a leading 1 dropped), or ''. */
+export function readPhone(text) {
+    const digits = String(text ?? '').replace(/[^0-9]/g, '');
+    if (digits.length === 11 && digits.startsWith('1')) {
+        return digits.slice(1);
+    }
+    else if (digits.length === 10) {
+        return digits;
+    }
+    else {
+        return '';
+    }
+}
+/**
+ * A phone number from outside the US / Canada in the answer, as its digits with the country code, or ''. With an
+ * explicit prefix ("+", "plus", "más", "00") 8-15 digits; without one 11-13 digits not starting with 1 (a card or an
+ * account number is not mistaken for one). US / Canada numbers are readPhone's. The flows say what such a number
+ * cannot be used for instead of "I didn't get that" (owner, 2026-10-14).
+ */
+export function readInternationalPhone(text) {
+    const t = String(text ?? '');
+    const prefixed = /(^|[\s(])(\+|00|plus\b|m[aá]s\b)\s*\d/i.test(t);
+    let d = t.replace(/[^0-9]/g, '');
+    if (prefixed && d.startsWith('00')) {
+        d = d.slice(2);
+    }
+    else {
+        // no international call prefix
+    }
+    if (readEmail(t) || readPhone(t) || d.startsWith('1')) {
+        return '';
+    }
+    else if (prefixed) {
+        return d.length >= 8 && d.length <= 15 ? d : '';
+    }
+    else {
+        return d.length >= 11 && d.length <= 13 ? d : '';
+    }
+}
+/** Whether the caller's own number (cargo.callerId) is from outside the US / Canada: on a call, a real caller ID. */
+export function callerIsInternational(cargo) {
+    const c = cargo || {};
+    const d = String(c.callerId ?? '').replace(/\D/g, '');
+    return !!c.voice && d.length >= 8 && !(d.length === 10 || (d.length === 11 && d[0] === '1'));
+}
+/**
+ * What the customer identified themselves with: { kind: 'account' | 'phone' | 'international_phone' | 'email', value } or
+ * null.
+ * accountPattern (a regex source, e.g. '^5\\d{6,7}$') is the tenant's account-number shape; its digits win first.
+ */
+export function readIdentifier(text, accountPattern = '') {
+    const digits = String(text ?? '').replace(/[^0-9]/g, '');
+    let account = false;
+    try {
+        account = !!accountPattern && new RegExp(accountPattern).test(digits);
+    }
+    catch {
+        account = false; // an invalid tenant pattern identifies no account
+    }
+    if (account) {
+        return { kind: 'account', value: digits };
+    }
+    else if (readPhone(text)) {
+        return { kind: 'phone', value: readPhone(text) };
+    }
+    else if (readInternationalPhone(text)) {
+        return { kind: 'international_phone', value: readInternationalPhone(text) };
+    }
+    else if (readEmail(text)) {
+        return { kind: 'email', value: readEmail(text) };
+    }
+    else {
+        return null;
+    }
+}
+/**
+ * The last four characters of a number (card, account, phone, tracking) as said to the customer: spaced one by one on a
+ * call ("5, 4, 7, 5"), as written otherwise ("5475"). Written ~25 times inline across the flow sets before it.
+ */
+export function last4(value, voice) {
+    const tail = String(value ?? '').slice(-4);
+    if (voice) {
+        return tail.split('').join(', ');
+    }
+    else {
+        return tail;
+    }
+}
+/**
+ * An email said back to the customer without reading all of it out. On a call: its first two characters spaced
+ * one by one and its domain ("starting with r, o, at gmail.com" / "que empieza con r, o, arroba gmail.com"): "ending
+ * in @gmail.com" alone is ambiguous on a call, and "ro***" makes the speech engine read the asterisks. Written:
+ * "ro***@gmail.com". '' for anything that is not an email.
+ */
+export function maskEmail(email, voice, lang = 'en') {
+    const m = /^([^@\s]+)@([^@\s]+)$/.exec(String(email ?? '').trim().toLowerCase());
+    if (!m) {
+        return '';
+    }
+    else if (voice) {
+        const head = m[1].slice(0, 2).split('').join(', ');
+        return lang === 'es' ? `que empieza con ${head}, arroba ${m[2]}` : `starting with ${head}, at ${m[2]}`;
+    }
+    else {
+        return `${m[1].slice(0, 2)}***@${m[2]}`;
+    }
+}
+/** A US / Canada number as 10 digits (a leading 1 dropped), or '' for anything else: we text only those. */
+function nanp(value) {
+    const d = String(value ?? '').replace(/\D/g, '');
+    return d.length === 10 ? d : (d.length === 11 && d[0] === '1' ? d.slice(1) : '');
+}
+/**
+ * The number we can text the caller at, 10 digits, or '': ONE rule for offering TEXT and for sending one. Only on a
+ * call with a sender (cargo.twilioNumber), a US / Canada caller ID, and not the number a code could not be texted to
+ * (cargo.otpUndeliverableTo). A number from another country used to be cut to its last 10 digits and offered TEXT,
+ * which then failed (dev calls from +52, 2026-10-13).
+ */
+export function callerTextNumber(cargo) {
+    const c = cargo || {};
+    const n = c.voice && c.twilioNumber ? nanp(c.callerId) : '';
+    return n && n !== String(c.otpUndeliverableTo || '') ? n : '';
+}
+/** Where a text to the customer can go, 10 digits or '': the verified cell, else the caller (callerTextNumber). */
+export function textDestination(cargo) {
+    const c = cargo || {};
+    const cell = c.twilioNumber ? nanp(c.otp_cell_number) : '';
+    return cell && cell !== String(c.otpUndeliverableTo || '') ? cell : callerTextNumber(c);
+}

package/dist/helpers/date-words.d.ts

@@ -0,0 +1,2 @@
+export function dateToWords(date: any, lang?: string, withYear?: boolean): string;
+//# sourceMappingURL=date-words.d.ts.map

package/dist/helpers/date-words.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"date-words.d.ts","sourceRoot":"","sources":["../../src/helpers/date-words.js"],"names":[],"mappings":"AAaA,kFAcC"}

package/dist/helpers/date-words.js

@@ -0,0 +1,29 @@
+/**
+ * dateToWords (APPROVED_FUNCTIONS): an ISO date ('2026-11-05', or a timestamp starting with one) as words —
+ * 'November 5, 2026' / '5 de noviembre de 2026', or without the year 'November 5' / '5 de noviembre'.
+ * ONE formatter for every flow: three ai-ar flows wrote their own month tables, and one read the raw '2026-12-31'
+ * aloud (flow design review 2026-10-13). Anything that is not a date comes back unchanged.
+ *
+ * Part of jsfe/helpers; zero imports.
+ */
+const MONTHS = {
+    en: ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'],
+    es: ['enero', 'febrero', 'marzo', 'abril', 'mayo', 'junio', 'julio', 'agosto', 'septiembre', 'octubre', 'noviembre', 'diciembre'],
+};
+export function dateToWords(date, lang = 'en', withYear = true) {
+    const m = /^(\d{4})-(\d{1,2})-(\d{1,2})/.exec(String(date ?? '').trim());
+    const month = m ? MONTHS[lang === 'es' ? 'es' : 'en'][parseInt(m[2], 10) - 1] : '';
+    if (!m || !month) {
+        return String(date ?? '');
+    }
+    else {
+        const day = parseInt(m[3], 10);
+        const year = parseInt(m[1], 10);
+        if (lang === 'es') {
+            return withYear ? `${day} de ${month} de ${year}` : `${day} de ${month}`;
+        }
+        else {
+            return withYear ? `${month} ${day}, ${year}` : `${month} ${day}`;
+        }
+    }
+}

package/dist/helpers/index.d.ts

@@ -0,0 +1,72 @@
+export namespace STANDARD_FUNCTIONS {
+    export { matchesChoice };
+    export { isAnswer };
+    export { isAgentRequest };
+    export { isOtherRequest };
+    export { isSpelledFragment };
+    export { isAmountAnswer };
+    export { amountInAnswer };
+    export { pickChoice };
+    export { readEmail };
+    export { readPhone };
+    export { readInternationalPhone };
+    export { readIdentifier };
+    export { last4 };
+    export { maskEmail };
+    export { callerTextNumber };
+    export { textDestination };
+    export { callerIsInternational };
+    export { normalizeAndFindCapture };
+    export { anythingElse };
+    export { goodbye };
+    export { dateToWords };
+    export { amountToSpeech };
+    export { validateCardNumber };
+    export { validateExpiration };
+    export { matchInputs };
+    export { validateOTP };
+    export { validateDigits };
+    export { validatePhone };
+    export { validateEmail };
+    export { urlToSpeech };
+    export { textWithUrlToSpeech };
+}
+import { matchesChoice } from './matches-choice.js';
+import { ANSWER_WORDS } from './answer.js';
+import { CONFIRM_WORDS } from './answer.js';
+import { isAnswer } from './answer.js';
+import { isAgentRequest } from './answer.js';
+import { isOtherRequest } from './answer.js';
+import { isSpelledFragment } from './answer.js';
+import { isAmountAnswer } from './answer.js';
+import { amountInAnswer } from './answer.js';
+import { pickChoice } from './answer.js';
+import { readEmail } from './contact.js';
+import { readPhone } from './contact.js';
+import { readInternationalPhone } from './contact.js';
+import { readIdentifier } from './contact.js';
+import { last4 } from './contact.js';
+import { maskEmail } from './contact.js';
+import { callerTextNumber } from './contact.js';
+import { textDestination } from './contact.js';
+import { callerIsInternational } from './contact.js';
+import { normalizeAndFindCapture } from './capture.js';
+import { anythingElse } from './phrases.js';
+import { goodbye } from './phrases.js';
+import { sayName } from './phrases.js';
+import { dateToWords } from './date-words.js';
+import { amountToSpeech } from './amount-to-speech.js';
+import { validateCardNumber } from './card-checks.js';
+import { validateExpiration } from './card-checks.js';
+import { matchInputs } from './match-inputs.js';
+import { checkOtp } from './otp-check.js';
+import { maskDestination } from './otp-check.js';
+import { validateOTP } from './otp-check.js';
+import { OTP_EXPIRY_MS } from './otp-check.js';
+import { validateDigits } from './validators.js';
+import { validatePhone } from './validators.js';
+import { validateEmail } from './validators.js';
+import { urlToSpeech } from './url-speech.js';
+import { textWithUrlToSpeech } from './url-speech.js';
+export { matchesChoice, ANSWER_WORDS, CONFIRM_WORDS, isAnswer, isAgentRequest, isOtherRequest, isSpelledFragment, isAmountAnswer, amountInAnswer, pickChoice, readEmail, readPhone, readInternationalPhone, readIdentifier, last4, maskEmail, callerTextNumber, textDestination, callerIsInternational, normalizeAndFindCapture, anythingElse, goodbye, sayName, dateToWords, amountToSpeech, validateCardNumber, validateExpiration, matchInputs, checkOtp, maskDestination, validateOTP, OTP_EXPIRY_MS, validateDigits, validatePhone, validateEmail, urlToSpeech, textWithUrlToSpeech };
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/helpers/index.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;8BAc8B,qBAAqB;6BACkG,aAAa;8BAAb,aAAa;yBAAb,aAAa;+BAAb,aAAa;+BAAb,aAAa;kCAAb,aAAa;+BAAb,aAAa;+BAAb,aAAa;2BAAb,aAAa;0BACT,cAAc;0BAAd,cAAc;uCAAd,cAAc;+BAAd,cAAc;sBAAd,cAAc;0BAAd,cAAc;iCAAd,cAAc;gCAAd,cAAc;sCAAd,cAAc;wCAC/H,cAAc;6BACP,cAAc;wBAAd,cAAc;wBAAd,cAAc;4BACjC,iBAAiB;+BACd,uBAAuB;mCACC,kBAAkB;mCAAlB,kBAAkB;4BAC7C,mBAAmB;yBACuB,gBAAgB;gCAAhB,gBAAgB;4BAAhB,gBAAgB;8BAAhB,gBAAgB;+BACzB,iBAAiB;8BAAjB,iBAAiB;8BAAjB,iBAAiB;4BAC7B,iBAAiB;oCAAjB,iBAAiB"}

package/dist/helpers/index.js

@@ -0,0 +1,34 @@
+/**
+ * jsfe/helpers — the functions JSFE's system flows call from expressions, in ONE place for every host: reading an
+ * answer (matchesChoice, pickChoice, isAnswer, readEmail, readIdentifier, amountInAnswer, matchInputs …), saying
+ * values (amountToSpeech, dateToWords, last4, urlToSpeech …), checking shapes and one-time codes. Pure: no credentials,
+ * no network, no host state beyond the container a caller passes in.
+ *
+ * The engine does not register them by itself. A host lists them among its approved functions, usually all at once:
+ *
+ *   import { STANDARD_FUNCTIONS } from 'jsfe/helpers';
+ *   new WorkflowEngine(logger, aiCallback, flows, tools, { ...STANDARD_FUNCTIONS, ...hostFunctions }, …);
+ *
+ * Functions that need credentials or the network (sending a text or an email, geocoding, a store's API) belong to the
+ * host.
+ */
+import { matchesChoice } from './matches-choice.js';
+import { ANSWER_WORDS, CONFIRM_WORDS, isAnswer, isAgentRequest, isOtherRequest, isSpelledFragment, isAmountAnswer, amountInAnswer, pickChoice } from './answer.js';
+import { readEmail, readPhone, readInternationalPhone, readIdentifier, last4, maskEmail, callerTextNumber, textDestination, callerIsInternational } from './contact.js';
+import { normalizeAndFindCapture } from './capture.js';
+import { anythingElse, goodbye, sayName } from './phrases.js';
+import { dateToWords } from './date-words.js';
+import { amountToSpeech } from './amount-to-speech.js';
+import { validateCardNumber, validateExpiration } from './card-checks.js';
+import { matchInputs } from './match-inputs.js';
+import { checkOtp, maskDestination, validateOTP, OTP_EXPIRY_MS } from './otp-check.js';
+import { validateDigits, validatePhone, validateEmail } from './validators.js';
+import { urlToSpeech, textWithUrlToSpeech } from './url-speech.js';
+export { matchesChoice, ANSWER_WORDS, CONFIRM_WORDS, isAnswer, isAgentRequest, isOtherRequest, isSpelledFragment, isAmountAnswer, amountInAnswer, pickChoice, readEmail, readPhone, readInternationalPhone, readIdentifier, last4, maskEmail, callerTextNumber, textDestination, callerIsInternational, normalizeAndFindCapture, anythingElse, goodbye, sayName, dateToWords, amountToSpeech, validateCardNumber, validateExpiration, matchInputs, checkOtp, maskDestination, validateOTP, OTP_EXPIRY_MS, validateDigits, validatePhone, validateEmail, urlToSpeech, textWithUrlToSpeech, };
+/** The functions flows call by name, ready to spread into a host's approved functions. */
+export const STANDARD_FUNCTIONS = {
+    matchesChoice, isAnswer, isAgentRequest, isOtherRequest, isSpelledFragment, isAmountAnswer, amountInAnswer, pickChoice,
+    readEmail, readPhone, readInternationalPhone, readIdentifier, last4, maskEmail, callerTextNumber, textDestination, callerIsInternational,
+    normalizeAndFindCapture, anythingElse, goodbye, dateToWords, amountToSpeech, validateCardNumber, validateExpiration, matchInputs,
+    validateOTP, validateDigits, validatePhone, validateEmail, urlToSpeech, textWithUrlToSpeech,
+};

package/dist/helpers/match-inputs.d.ts

@@ -0,0 +1,28 @@
+/**
+ * candidates: [{ form, name, profile, value?, confirm_against? }] — the inputs of the form chain that apply now (`when`
+ * holds): the current form's first, then its parent's, and so on up. `value` is what is already stored for it.
+ * current: { form, name } of the input that was asked, or { form, names } when the asked input is one of several
+ * (an any_of group: phone, email or account number); every member counts as the current input. choiceKey: the key
+ * ask-choice picked from the current input's own choices, if any.
+ *
+ * Readings that claim DIFFERENT parts of the answer are all taken (a compound answer fills several inputs). Readings
+ * that claim the SAME part are settled by scope (owner decision 2026-10-19, A):
+ *   1. the current input takes it;
+ *   2. else the one input of the current form that fits takes it, and parent forms are not considered;
+ *   3. else the same test one form up, and so on;
+ *   4. two inputs at the nearest form that fits are ambiguous: asked, never ranked.
+ * Exception: an input that declares `confirm_against: [names]` is asked about together with those inputs whenever both
+ * fit the same words, wherever scope would have put it ('62' at the payment offer: $62 or sub-account 62, prod
+ * 2026-10-19 07:38).
+ *
+ * Returns { hits, ambiguous }:
+ *   hits      — what the answer fills, each { form, name, value, known } (`known`: equals the stored value);
+ *   ambiguous — the readings to ask about (the first such group), or empty.
+ */
+export function matchInputs(answer: any, candidates: any, current: any, choiceKey: any): {
+    hits: {
+        [x: string]: any;
+    }[];
+    ambiguous: any;
+};
+//# sourceMappingURL=match-inputs.d.ts.map

package/dist/helpers/match-inputs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"match-inputs.d.ts","sourceRoot":"","sources":["../../src/helpers/match-inputs.js"],"names":[],"mappings":"AA0GA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;;;;;EAuEC"}

package/dist/helpers/match-inputs.js

@@ -0,0 +1,223 @@
+/**
+ * Which of a FORM's inputs an answer fills (APPROVED_FUNCTIONS matchInputs), for the system collect-input worker
+ * (owner direction 2026-10-19, the FORM convention in the jsfe-flow-designer skill). A caller may answer out of order,
+ * fill several inputs at once, or say something that fits two inputs; this reads the answer against every candidate
+ * input's declared shape and says which, never guessing between two: an answer whose words fit two inputs is
+ * returned as ambiguous, and the flow asks.
+ *
+ * Tenant-agnostic shape reading only (the same class as pickChoice / readIdentifier). Conversation behaviour stays in
+ * the flows. Part of jsfe/helpers; imports only siblings.
+ */
+import { matchesChoice } from './matches-choice.js';
+import { pickChoice, amountInAnswer, isAmountAnswer } from './answer.js';
+import { readEmail, readPhone, readInternationalPhone, readIdentifier } from './contact.js';
+/** The answer as said: jsfe stores user input escaped (don\'t). */
+function unescape(answer) {
+    return String(answer ?? '').replace(/\\(['"\\])/g, '$1');
+}
+/** Digit runs as said: spoken digits come apart ("4 3 2 1", "555-123-4567"), so single spaces / dashes / dots inside a run join it. */
+function digitRuns(raw) {
+    return (raw.match(/\d(?:[\s.-]?\d)*/g) || []).map((r) => r.replace(/\D/g, ''));
+}
+/**
+ * One input's reading of the answer: { value, evidence } or null. `evidence` is what the answer spent on it (digits
+ * or words), so two inputs that claim the same part of the answer are told apart from a compound answer.
+ */
+function readProfile(profile, raw, isCurrent) {
+    const kind = profile && profile.kind;
+    if (kind === 'choice') {
+        const choices = Array.isArray(profile.choices) ? profile.choices : [];
+        const key = pickChoice(raw, choices, false);
+        if (key && key.indexOf('__') !== 0) {
+            const choice = choices.filter((c) => c && c.key === key)[0] || { words: [] };
+            const words = (choice.words || []).filter((w) => matchesChoice(raw, [w]));
+            // a number word is the same evidence as a number read by another input ('62' as a sub-account and as $62)
+            return { value: key, evidence: words.map((w) => (/^[\d\s.-]+$/.test(String(w)) ? `d:${String(w).replace(/\D/g, '')}` : `w:${String(w).toLowerCase()}`)) };
+        }
+        else {
+            return null; // no choice, or an AGENT / EXIT request (ask-choice owns those)
+        }
+    }
+    else if (kind === 'amount') {
+        const n = profile.marked ? (isAmountAnswer(raw) ? amountInAnswer(raw) : NaN) : amountInAnswer(raw);
+        const inRange = !isNaN(n) && (profile.min === undefined || n >= Number(profile.min)) && (profile.max === undefined || n <= Number(profile.max));
+        if (inRange) {
+            // the digits it was read from: the runs that start with its whole-dollar part ("82.50" said as "82 50" → 8250)
+            const runs = digitRuns(raw).filter((d) => d.indexOf(String(Math.trunc(n))) === 0);
+            return { value: String(n), evidence: runs.length ? runs.map((d) => `d:${d}`) : ['amount'] };
+        }
+        else {
+            return null;
+        }
+    }
+    else if (kind === 'email') {
+        const e = readEmail(raw);
+        if (e) {
+            return { value: e, evidence: [`e:${e}`] };
+        }
+        else {
+            return null;
+        }
+    }
+    else if (kind === 'phone') {
+        const p = readPhone(raw) || readInternationalPhone(raw);
+        if (p) {
+            return { value: p, evidence: [`d:${String(p).replace(/\D/g, '')}`] };
+        }
+        else {
+            return null;
+        }
+    }
+    else if (kind === 'identifier') {
+        const id = readIdentifier(raw, profile.pattern || '');
+        if (id && id.kind === 'account') {
+            return { value: id.value, evidence: [`d:${id.value}`] };
+        }
+        else {
+            return null;
+        }
+    }
+    else if (kind === 'digits') {
+        const min = Number(profile.min || 1);
+        const max = Number(profile.max || min);
+        const fits = [...new Set(digitRuns(raw).filter((d) => d.length >= min && d.length <= max))];
+        if (fits.length === 1) {
+            return { value: fits[0], evidence: [`d:${fits[0]}`] };
+        }
+        else {
+            return null; // none, or two different numbers of that length: not this input's answer by shape alone
+        }
+    }
+    else if (kind === 'pattern') {
+        let m = null;
+        try {
+            m = new RegExp(profile.regex, profile.flags || 'i').exec(raw);
+        }
+        catch {
+            m = null; // an invalid pattern in a spec reads nothing
+        }
+        if (m) {
+            const v = m[profile.group || 0] || m[0];
+            return { value: v, evidence: [`p:${String(v).toLowerCase()}`] };
+        }
+        else {
+            return null;
+        }
+    }
+    else if (kind === 'text') {
+        const t = raw.trim();
+        if (isCurrent && t) {
+            return { value: t, evidence: ['text'] };
+        }
+        else {
+            return null; // free text fills only the input that was asked, or every answer would fit it
+        }
+    }
+    else {
+        return null; // an unknown kind (e.g. 'date' before its reader exists) reads nothing
+    }
+}
+/**
+ * candidates: [{ form, name, profile, value?, confirm_against? }] — the inputs of the form chain that apply now (`when`
+ * holds): the current form's first, then its parent's, and so on up. `value` is what is already stored for it.
+ * current: { form, name } of the input that was asked, or { form, names } when the asked input is one of several
+ * (an any_of group: phone, email or account number); every member counts as the current input. choiceKey: the key
+ * ask-choice picked from the current input's own choices, if any.
+ *
+ * Readings that claim DIFFERENT parts of the answer are all taken (a compound answer fills several inputs). Readings
+ * that claim the SAME part are settled by scope (owner decision 2026-10-19, A):
+ *   1. the current input takes it;
+ *   2. else the one input of the current form that fits takes it, and parent forms are not considered;
+ *   3. else the same test one form up, and so on;
+ *   4. two inputs at the nearest form that fits are ambiguous: asked, never ranked.
+ * Exception: an input that declares `confirm_against: [names]` is asked about together with those inputs whenever both
+ * fit the same words, wherever scope would have put it ('62' at the payment offer: $62 or sub-account 62, prod
+ * 2026-10-19 07:38).
+ *
+ * Returns { hits, ambiguous }:
+ *   hits      — what the answer fills, each { form, name, value, known } (`known`: equals the stored value);
+ *   ambiguous — the readings to ask about (the first such group), or empty.
+ */
+export function matchInputs(answer, candidates, current, choiceKey) {
+    const raw = unescape(answer);
+    const list = Array.isArray(candidates) ? candidates.filter((c) => c && c.name && c.profile) : [];
+    const cur = current && typeof current === 'object' ? current : {};
+    const isCur = (c) => (Array.isArray(cur.names) ? cur.names.indexOf(c.name) > -1 : c.name === cur.name) && (cur.form === undefined || c.form === cur.form);
+    const own = Array.isArray(cur.names) ? undefined : list.filter(isCur)[0]; // a group has no single own choice list
+    // A declared confirm_against pair with the current input is read in full below, even when its own choice was picked.
+    const pairedWithOwn = !!own && list.some((c) => c !== own && ((Array.isArray(c.confirm_against) && c.confirm_against.indexOf(own.name) > -1) || (Array.isArray(own.confirm_against) && own.confirm_against.indexOf(c.name) > -1)));
+    if (own && choiceKey && !pairedWithOwn && own.profile.kind === 'choice' && (own.profile.choices || []).some((c) => c && c.key === choiceKey)) {
+        return { hits: [{ form: own.form, name: own.name, value: choiceKey, known: own.value === choiceKey }], ambiguous: [] };
+    }
+    else {
+        // no direct pick of the current input's own choice: read every candidate's shape
+    }
+    // A form's scope level: 0 for the current input's form, then each further form in the order the chain lists them.
+    const forms = [];
+    if (own) {
+        forms.push(own.form);
+    }
+    else {
+        // the current input is not among the candidates (it no longer applies): levels follow the list order
+    }
+    list.forEach((c) => { if (forms.indexOf(c.form) === -1) {
+        forms.push(c.form);
+    }
+    else { /* already ranked */ } });
+    const readings = [];
+    for (const c of list) {
+        const r = readProfile(c.profile, raw, isCur(c));
+        if (r) {
+            readings.push({ form: c.form, name: c.name, value: r.value, known: c.value !== undefined && c.value !== null && String(c.value) === String(r.value), evidence: r.evidence, level: forms.indexOf(c.form), current: isCur(c), confirm: Array.isArray(c.confirm_against) ? c.confirm_against : [] });
+        }
+        else {
+            // this input's shape is not in the answer
+        }
+    }
+    // Readings that spent the same evidence form a group (connected components).
+    const conflicts = (a, b) => a.evidence.some((e) => b.evidence.indexOf(e) > -1);
+    const parent = readings.map((_, i) => i);
+    const find = (i) => (parent[i] === i ? i : (parent[i] = find(parent[i])));
+    for (let i = 0; i < readings.length; i++) {
+        for (let j = i + 1; j < readings.length; j++) {
+            if (conflicts(readings[i], readings[j])) {
+                parent[find(i)] = find(j);
+            }
+            else {
+                // distinct parts of the answer
+            }
+        }
+    }
+    const groups = {};
+    readings.forEach((r, i) => { (groups[find(i)] = groups[find(i)] || []).push(r); });
+    const strip = ({ evidence, level, current: c, confirm, ...r }) => r;
+    const paired = (a, b) => a.confirm.indexOf(b.name) > -1 || b.confirm.indexOf(a.name) > -1;
+    const hits = [];
+    let ambiguous = [];
+    for (const members of Object.values(groups)) {
+        let winners;
+        if (members.length === 1) {
+            winners = members;
+        }
+        else if (members.some((m) => m.current)) {
+            winners = members.filter((m) => m.current);
+        }
+        else {
+            const nearest = Math.min(...members.map((m) => m.level));
+            winners = members.filter((m) => m.level === nearest);
+        }
+        // a winner declared to be confirmed against another member is asked about together with it
+        const confirmWith = winners.length === 1 ? members.filter((m) => m !== winners[0] && paired(m, winners[0])) : [];
+        const asked = confirmWith.length ? winners.concat(confirmWith) : winners;
+        if (asked.length === 1) {
+            hits.push(strip(asked[0]));
+        }
+        else if (ambiguous.length === 0) {
+            ambiguous = asked.map(strip);
+        }
+        else {
+            // a second ambiguous group in one answer is left for the next question
+        }
+    }
+    return { hits, ambiguous };
+}

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

@@ -0,0 +1,26 @@
+/**
+ * Strict word-aware option matching for flow CASE conditions (APPROVED_FUNCTIONS.matchesChoice) —
+ * replaces the substring `.some(choice => input.includes(choice))` idiom, whose false positives broke
+ * branch routing ('si' inside "imposible"/"así" matched YES, prod-observed 2026-08-09).
+ *
+ * Rules (deliberately NO fuzzy/prefix matching):
+ *  - single-word choice: exact word membership
+ *  - multi-word choice: exact word-sequence containment
+ *  - plurals/inflections: enumerate them explicitly in the choice list
+ *  - a keypad key (one digit, * or #) matches ONLY an answer that is exactly that key, never a key
+ *    inside a longer answer (owner rule): "I made payments by 1," at "press 1 to pay" charged the full
+ *    amount due on dev, 2026-10-14
+ *  - an ELONGATED word the user typed is forgiven (2026-10-01): a repeated vowel or any letter typed
+ *    3+ times collapses — "Sii" matches 'si', "nadaaaa" 'nada', "yesss" 'yes'. A typed "Sii" at the
+ *    authentication retry menu ended the conversation in contact-support. Only the user's word is
+ *    collapsed, and only against an option word with no doubled letter of its own. Measured on a
+ *    week of prod prompts (scratch replay, 98 option lists × 23,692 prompts):
+ *      · collapsing BOTH sides: rejected — 'all' → 'al' made "servicio al cliente" (138 turns) pick
+ *        the "all" option, and 'mm' → 'm' made "I'm" a filler;
+ *      · collapsing every doubled letter of the user's word: rejected — "mess" matched Spanish
+ *        'mes' and "Mall" 'mal'. A doubled consonant is real spelling, so "okk" stays unmatched.
+ *
+ * Zero imports, so scripts/tests/matches-choice.mjs runs the real implementation.
+ */
+export function matchesChoice(input: any, choices: any): boolean;
+//# sourceMappingURL=matches-choice.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"matches-choice.d.ts","sourceRoot":"","sources":["../../src/helpers/matches-choice.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,iEAiCC"}