jsfe 1.6.0 → 1.7.1

package/dist/helpers/spoken-money.d.ts

@@ -0,0 +1,20 @@
+/** [{value,start,end}] covers the entire currency phrase, including a connected cents clause.
+ * Only readings containing actual cardinal words are returned; existing numeric parsing retains ownership of digits. */
+export function scanSpokenMoney(answer: any): {
+    readings: {
+        value: any;
+        start: number;
+        end: number;
+    }[];
+    invalid: {
+        start: number;
+        end: number;
+        reason: string;
+    }[];
+};
+export function readSpokenMoney(answer: any): {
+    value: any;
+    start: number;
+    end: number;
+}[];
+//# sourceMappingURL=spoken-money.d.ts.map

package/dist/helpers/spoken-money.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spoken-money.d.ts","sourceRoot":"","sources":["../../src/helpers/spoken-money.js"],"names":[],"mappings":"AAqDA;wHACwH;AACxH;;;;;;;;;;;EA+BC;AAED;;;;IAAkF"}

package/dist/helpers/spoken-money.js

@@ -0,0 +1,143 @@
+/** Deterministic cardinal grammar for explicitly named monetary phrases. No conversation or intent policy. */
+const EN_SMALL = 'zero one two three four five six seven eight nine ten eleven twelve thirteen fourteen fifteen sixteen seventeen eighteen nineteen'.split(' ');
+const EN_TENS = { twenty: 20, thirty: 30, forty: 40, fifty: 50, sixty: 60, seventy: 70, eighty: 80, ninety: 90 };
+const ES_SMALL = { cero: 0, uno: 1, un: 1, una: 1, dos: 2, tres: 3, cuatro: 4, cinco: 5, seis: 6, siete: 7, ocho: 8, nueve: 9, diez: 10, once: 11, doce: 12, trece: 13, catorce: 14, quince: 15, dieciseis: 16, diecisiete: 17, dieciocho: 18, diecinueve: 19, veinte: 20, veintiuno: 21, veintiun: 21, veintiuna: 21, veintidos: 22, veintitres: 23, veinticuatro: 24, veinticinco: 25, veintiseis: 26, veintisiete: 27, veintiocho: 28, veintinueve: 29 };
+const ES_TENS = { treinta: 30, cuarenta: 40, cincuenta: 50, sesenta: 60, setenta: 70, ochenta: 80, noventa: 90 };
+const ES_HUNDREDS = { doscientos: 200, doscientas: 200, trescientos: 300, trescientas: 300, cuatrocientos: 400, cuatrocientas: 400, quinientos: 500, quinientas: 500, seiscientos: 600, seiscientas: 600, setecientos: 700, setecientas: 700, ochocientos: 800, ochocientas: 800, novecientos: 900, novecientas: 900 };
+const NUMBER_WORDS = new Set([...EN_SMALL, ...Object.keys(EN_TENS), ...Object.keys(ES_SMALL), ...Object.keys(ES_TENS), ...Object.keys(ES_HUNDREDS), 'hundred', 'thousand', 'million', 'cien', 'ciento', 'mil', 'millon', 'millones', 'and', 'y', 'a', 'an']);
+const MAJOR = new Set(['dollar', 'dollars', 'dolar', 'dolares']);
+const MINOR = new Set(['cent', 'cents', 'centavo', 'centavos']);
+const plain = value => value.normalize('NFD').replace(/[\u0300-\u036f]/g, '').toLowerCase();
+const valid = value => Number.isSafeInteger(value) && value >= 0;
+function englishSmall(words) {
+    if (words.length === 1 && EN_SMALL.includes(words[0]))
+        return EN_SMALL.indexOf(words[0]);
+    const tens = EN_TENS[words[0]], unit = EN_SMALL.indexOf(words[1]);
+    return tens && (words.length === 1 || words.length === 2 && unit > 0 && unit < 10) ? tens + (words.length === 2 ? unit : 0) : null;
+}
+function englishHundreds(words) {
+    const hundred = words.indexOf('hundred');
+    if (hundred < 0)
+        return englishSmall(words);
+    if (hundred !== 1 || words.lastIndexOf('hundred') !== 1)
+        return null;
+    const lead = ['a', 'an'].includes(words[0]) ? 1 : EN_SMALL.indexOf(words[0]);
+    if (lead < 1 || lead > 9)
+        return null;
+    let tail = words.slice(2);
+    if (tail[0] === 'and') {
+        if (tail.length === 1)
+            return null;
+        tail = tail.slice(1);
+    }
+    const rest = tail.length ? englishSmall(tail) : 0;
+    return rest === null || tail.length && rest === 0 ? null : lead * 100 + rest;
+}
+function spanishSmall(words) {
+    if (words.length === 1 && Object.hasOwn(ES_SMALL, words[0]))
+        return ES_SMALL[words[0]];
+    const tens = ES_TENS[words[0]], unit = ES_SMALL[words[2]];
+    return tens && (words.length === 1 || words.length === 3 && words[1] === 'y' && unit > 0 && unit < 10) ? tens + (words.length === 3 ? unit : 0) : null;
+}
+function spanishHundreds(words) {
+    if (words[0] === 'cien')
+        return words.length === 1 ? 100 : null;
+    if (words[0] === 'ciento') {
+        const rest = spanishSmall(words.slice(1));
+        return rest !== null && rest > 0 ? 100 + rest : null;
+    }
+    const lead = ES_HUNDREDS[words[0]];
+    if (!lead)
+        return spanishSmall(words);
+    const rest = words.length > 1 ? spanishSmall(words.slice(1)) : 0;
+    return rest === null || words.length > 1 && rest === 0 ? null : lead + rest;
+}
+function scaled(words, lang, level = 0) {
+    const lower = lang === 'en' ? englishHundreds : spanishHundreds;
+    if (level === 2)
+        return lower(words);
+    const scales = lang === 'en' ? [['million'], ['thousand']] : [['millon', 'millones'], ['mil']], scale = level === 0 ? 1000000 : 1000;
+    const positions = words.map((word, index) => scales[level].includes(word) ? index : -1).filter(index => index >= 0);
+    if (!positions.length)
+        return scaled(words, lang, level + 1);
+    if (positions.length !== 1)
+        return null;
+    const at = positions[0], left = words.slice(0, at), right = words.slice(at + 1), lead = left.length ? lang === 'en' && left.length === 1 && ['a', 'an'].includes(left[0]) ? 1 : lower(left) : lang === 'es' && scale === 1000 ? 1 : null;
+    if (lead === null || lead < 1 || lead > 999)
+        return null;
+    if (lang === 'es' && scale === 1000000 && ((lead === 1) !== (words[at] === 'millon')))
+        return null;
+    if (lang === 'en' && right[0] === 'and') {
+        if (right.length === 1)
+            return null;
+        right.shift();
+    }
+    const rest = right.length ? scaled(right, lang, level + 1) : 0;
+    return rest === null || right.length && rest === 0 ? null : lead * scale + rest;
+}
+function cardinal(words) {
+    if (words.length === 1 && /^\d+$/.test(words[0])) {
+        const value = Number(words[0]);
+        return valid(value) ? value : null;
+    }
+    if (!words.length || words.length > 24 || words.some(word => /\d/.test(word)))
+        return null;
+    const en = scaled(words, 'en'), es = scaled(words, 'es');
+    return en !== null ? en : es;
+}
+/** [{value,start,end}] covers the entire currency phrase, including a connected cents clause.
+ * Only readings containing actual cardinal words are returned; existing numeric parsing retains ownership of digits. */
+export function scanSpokenMoney(answer) {
+    const raw = String(answer ?? ''), tokens = [...raw.matchAll(/\p{L}+|\d+(?:[.,]\d+)?|[^\s]/gu)].map(match => ({ word: plain(match[0]), start: match.index, end: match.index + match[0].length }));
+    const units = [], invalid = [];
+    for (let i = 0; i < tokens.length; i++) {
+        const unit = tokens[i].word;
+        if (!MAJOR.has(unit) && !MINOR.has(unit))
+            continue;
+        let start = i;
+        while (start > 0 && (NUMBER_WORDS.has(tokens[start - 1].word) || /^\d+$/.test(tokens[start - 1].word) || tokens[start - 1].word === '-' && start > 1 && NUMBER_WORDS.has(tokens[start - 2].word)))
+            start--;
+        while (start < i && ['and', 'y'].includes(tokens[start].word))
+            start++;
+        const numberTokens = tokens.slice(start, i), words = numberTokens.filter(token => token.word !== '-').map(token => token.word);
+        // The established numeric reader owns digit-only connector phrases, including Spanish 'un' before cents.
+        const digitOnly = words.some(word => /^\d+$/.test(word)) && words.every(word => /^\d+$/.test(word) || ['and', 'y', 'un'].includes(word));
+        const numericCents = MINOR.has(unit) && words.length === 2 && words[0] === 'un' && /^\d+$/.test(words[1]);
+        if (digitOnly && words.length > 1 && !numericCents)
+            continue;
+        const value = cardinal(numericCents ? words.slice(1) : words);
+        const spoken = !digitOnly && words.some(word => /[a-z]/.test(word));
+        if (value === null) {
+            if (spoken)
+                invalid.push({ start: tokens[start].start, end: tokens[i].end, reason: 'invalid_cardinal' });
+            continue;
+        }
+        // A detached sign or a negative phrase is not a positive payment amount.
+        if (start > 0 && ['-', 'minus', 'negative', 'menos', 'negativo'].includes(tokens[start - 1].word)) {
+            if (spoken)
+                invalid.push({ start: tokens[start - 1].start, end: tokens[i].end, reason: 'negative_amount' });
+            continue;
+        }
+        units.push({ value, unit: MAJOR.has(unit) ? 'major' : 'minor', spoken, start: tokens[start].start, end: tokens[i].end });
+    }
+    const readings = [];
+    for (let i = 0; i < units.length; i++) {
+        const first = units[i], next = units[i + 1];
+        if (first.unit === 'major' && next?.unit === 'minor' && /^(?:and|y|con)$/i.test(raw.slice(first.end, next.start).trim())) {
+            if (next.value > 99) {
+                if (first.spoken || next.spoken)
+                    invalid.push({ start: first.start, end: next.end, reason: 'invalid_fractional_cents' });
+                i++;
+                continue;
+            }
+            if (first.spoken || next.spoken)
+                readings.push({ value: Math.round(first.value * 100 + next.value) / 100, start: first.start, end: next.end });
+            i++;
+            continue;
+        }
+        if (first.spoken)
+            readings.push({ value: first.unit === 'minor' ? first.value / 100 : first.value, start: first.start, end: first.end });
+    }
+    return { readings, invalid };
+}
+export function readSpokenMoney(answer) { return scanSpokenMoney(answer).readings; }

package/dist/host/action-journal.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Storage contract (all writes are compare-and-swap, false means the comparison lost):
+ * readAttempt(attemptId), readScope(scopeId) -> record|null
+ * readPending(sessionId) -> {version:1,sessionId,sequence,revision,attempts:{[attemptId]:sequence}}|null
+ * claim({attempt,expectedGuard,superseded?,index,expectedIndex}) -> boolean; atomic attempt + guard + session index
+ * complete({attempt,expected,index,expectedIndex}) -> boolean; atomic matching attempt + owned guard + session index
+ * An unresolved claim has no lease expiry. A timeout cannot establish whether an external effect ran.
+ */
+export function createActionJournal({ storage, namespace, now }: {
+    storage: any;
+    namespace: any;
+    now?: (() => number) | undefined;
+}): Readonly<{
+    claim: (input: any) => Promise<{
+        status: string;
+        outcome: any;
+        receipt: {
+            key: any;
+            attemptId: any;
+            scopeId: any;
+            signature: any;
+            sequence: any;
+        };
+    } | {
+        status: string;
+        outcome: {
+            status: string;
+            reason: any;
+        };
+        receipt: {
+            key: any;
+            attemptId: any;
+            scopeId: any;
+            signature: any;
+            sequence: any;
+        } | null;
+    } | {
+        status: string;
+        receipt: {
+            key: any;
+            attemptId: any;
+            scopeId: any;
+            signature: any;
+            sequence: any;
+        };
+    }>;
+    complete: (input: any) => Promise<{
+        status: any;
+        outcome: any;
+        receipt: {
+            key: any;
+            attemptId: any;
+            scopeId: any;
+            signature: any;
+            sequence: any;
+        };
+    }>;
+    checkpoint: ({ sessionId, keys, receipts }: {
+        sessionId: any;
+        keys?: never[] | undefined;
+        receipts: any;
+    }) => Promise<number>;
+    pending: ({ sessionId }: {
+        sessionId: any;
+    }) => Promise<{
+        records: any;
+        checkpoint: {
+            key: any;
+            sequence: any;
+            status: any;
+            session: any;
+        } | null;
+    }>;
+}>;
+/** Hermetic adapter. Share this object across recreated ports to model process loss; never use it as production persistence. */
+export function createMemoryActionStorage(): Readonly<{
+    readAttempt(id: any): Promise<any>;
+    readScope(id: any): Promise<any>;
+    readPending(id: any): Promise<any>;
+    claim({ attempt, expectedGuard, superseded, index, expectedIndex }: {
+        attempt: any;
+        expectedGuard: any;
+        superseded?: null | undefined;
+        index: any;
+        expectedIndex: any;
+    }): Promise<boolean>;
+    complete({ attempt, expected, index, expectedIndex }: {
+        attempt: any;
+        expected: any;
+        index: any;
+        expectedIndex: any;
+    }): Promise<boolean>;
+}>;
+export class ActionJournalError extends Error {
+    constructor(code: any);
+    code: any;
+}
+//# sourceMappingURL=action-journal.d.ts.map

package/dist/host/action-journal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-journal.d.ts","sourceRoot":"","sources":["../../src/host/action-journal.js"],"names":[],"mappings":"AAQA;;;;;;;GAOG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0HC;AAED,gIAAgI;AAChI;;;;;;;;;;;;;;;;;GAmBC;AA3JD;IACG,uBAAkG;IAAhB,UAAc;CAClG"}

package/dist/host/action-journal.js

@@ -0,0 +1,218 @@
+/** Durable action policy. The injected storage adapter owns atomic I/O, never conversational decisions. */
+const STATES = new Set(['attempted', 'unknown', 'completed', 'superseded']);
+const text = (value, name, max = 4096) => { if (typeof value !== 'string' || !value.trim() || value.length > max)
+    throw new ActionJournalError('invalid_' + name); return value; };
+const clone = value => JSON.parse(JSON.stringify(value));
+const hash = async (value) => Array.from(new Uint8Array(await globalThis.crypto.subtle.digest('SHA-256', new TextEncoder().encode(value))), b => b.toString(16).padStart(2, '0')).join('');
+export class ActionJournalError extends Error {
+    constructor(code) { super(`Action journal: ${code}`); this.name = 'ActionJournalError'; this.code = code; }
+}
+/**
+ * Storage contract (all writes are compare-and-swap, false means the comparison lost):
+ * readAttempt(attemptId), readScope(scopeId) -> record|null
+ * readPending(sessionId) -> {version:1,sessionId,sequence,revision,attempts:{[attemptId]:sequence}}|null
+ * claim({attempt,expectedGuard,superseded?,index,expectedIndex}) -> boolean; atomic attempt + guard + session index
+ * complete({attempt,expected,index,expectedIndex}) -> boolean; atomic matching attempt + owned guard + session index
+ * An unresolved claim has no lease expiry. A timeout cannot establish whether an external effect ran.
+ */
+export function createActionJournal({ storage, namespace, now = Date.now }) {
+    text(namespace, 'namespace');
+    for (const method of ['readAttempt', 'readScope', 'readPending', 'claim', 'complete'])
+        if (typeof storage?.[method] !== 'function')
+            throw new ActionJournalError('missing_storage_' + method);
+    const sessionHash = sessionId => hash(JSON.stringify([namespace, text(sessionId, 'session')]));
+    const tick = () => { const stamp = now(); if (!Number.isFinite(stamp) || stamp < 0)
+        throw new ActionJournalError('invalid_clock'); return stamp; };
+    const attemptId = async (sessionId, key) => hash(JSON.stringify([await sessionHash(sessionId), text(key, 'key')]));
+    const scopeId = async (sessionId, scope) => hash(JSON.stringify([await sessionHash(sessionId), text(scope, 'scope')]));
+    const receipt = row => ({ key: row.key, attemptId: row.attemptId, scopeId: row.scopeId, signature: row.signature, sequence: row.sequence });
+    const check = (row, { scope, attempt, signature } = {}) => {
+        if (!row)
+            return null;
+        if (row.version !== 1 || !STATES.has(row.status) || typeof row.revision !== 'string' || typeof row.key !== 'string' || typeof row.scopeId !== 'string' || typeof row.attemptId !== 'string' || typeof row.signature !== 'string' || !Number.isFinite(row.createdAt) || !Number.isFinite(row.updatedAt) || (['completed', 'unknown'].includes(row.status) && (!row.result || typeof row.result.status !== 'string')))
+            throw new ActionJournalError('invalid_stored_record');
+        if (scope && row.scopeId !== scope || attempt && row.attemptId !== attempt)
+            throw new ActionJournalError('stored_identity_mismatch');
+        if (signature && row.signature !== signature)
+            throw new ActionJournalError('key_reused_for_different_request');
+        return row;
+    };
+    const checkIndex = (row, session) => {
+        if (!row)
+            return null;
+        if (row.version !== 1 || row.sessionId !== session || !Number.isSafeInteger(row.sequence) || row.sequence < 1 || typeof row.revision !== 'string' || !row.attempts || typeof row.attempts !== 'object' || Array.isArray(row.attempts))
+            throw new ActionJournalError('invalid_session_index');
+        return row;
+    };
+    const nextIndex = (previous, session) => ({ version: 1, sessionId: session, sequence: Number(previous?.sequence || 0) + 1, revision: globalThis.crypto.randomUUID(), attempts: { ...previous?.attempts } });
+    async function identity({ sessionId, record, action }) {
+        if (!record || !action || typeof action.action !== 'string' || record.action !== action.action || !action.effect)
+            throw new ActionJournalError('invalid_action');
+        return { session: await sessionHash(sessionId), attempt: await attemptId(sessionId, record.key), scope: await scopeId(sessionId, record.scope), signature: await hash(text(record.signature, 'signature', 1048576)) };
+    }
+    const replay = row => ({ status: 'replay', outcome: clone(row.result), receipt: receipt(row) });
+    const hold = (row, reason) => ({ status: 'hold', outcome: { status: 'unknown', reason }, receipt: row ? receipt(row) : null });
+    function retryAllowed(guard, record, action) {
+        const retry = record.retryAuthorization, proof = retry?.authorization;
+        return ['attempted', 'unknown'].includes(guard.status) && action.effect === 'send' && action.retry?.unknown === 'explicit' && retry?.previousKey === guard.key && proof && typeof proof.form === 'string' && !!proof.form && typeof proof.input === 'string' && !!proof.input && Object.hasOwn(proof, 'value') && Number.isInteger(proof.revision) && proof.revision >= 0 && Number.isFinite(proof.at) && proof.at >= guard.createdAt;
+    }
+    async function claim(input) {
+        const { sessionId, record, action } = input, id = await identity(input);
+        for (let race = 0; race < 3; race++) {
+            const [prior, guard, indexBefore] = await Promise.all([storage.readAttempt(id.attempt), storage.readScope(id.scope), storage.readPending(id.session)]);
+            check(prior, { scope: id.scope, attempt: id.attempt, signature: id.signature });
+            check(guard, { scope: id.scope });
+            checkIndex(indexBefore, id.session);
+            if (prior)
+                return prior.status === 'completed' ? replay(prior) : hold(prior, prior.status === 'superseded' ? 'action_superseded' : 'action_result_unresolved');
+            if (guard?.status === 'completed' && !guard.checkpointed)
+                return guard.signature === id.signature ? replay(guard) : hold(guard, 'completed_action_not_checkpointed');
+            let superseded = null, consentFingerprint = '';
+            if (guard && ['attempted', 'unknown'].includes(guard.status)) {
+                if (!retryAllowed(guard, record, action))
+                    return hold(guard, 'action_result_unresolved');
+                const proof = record.retryAuthorization.authorization;
+                consentFingerprint = await hash(JSON.stringify([proof.form, proof.input, proof.sequence ?? null, proof.revision, proof.at, proof.value]));
+                if (consentFingerprint === guard.consentFingerprint)
+                    return hold(guard, 'retry_consent_already_used');
+                const previous = check(await storage.readAttempt(guard.attemptId), { scope: id.scope, attempt: guard.attemptId });
+                if (!previous || previous.revision !== guard.revision || previous.status !== guard.status)
+                    return hold(guard, 'retry_history_changed');
+                superseded = { expected: previous, attempt: { ...previous, status: 'superseded', retryAuthorization: clone(record.retryAuthorization), revision: globalThis.crypto.randomUUID(), updatedAt: tick() } };
+                delete superseded.attempt.checkpoint;
+            }
+            else if (guard && guard.status !== 'completed')
+                return hold(guard, 'invalid_scope_state');
+            const stamp = tick();
+            const index = nextIndex(indexBefore, id.session);
+            if (superseded)
+                delete index.attempts[superseded.expected.attemptId];
+            index.attempts[id.attempt] = index.sequence;
+            const attempt = { version: 1, sessionId: id.session, sequence: index.sequence, attemptId: id.attempt, scopeId: id.scope, key: record.key, action: action.action, effect: action.effect, signature: id.signature,
+                revision: globalThis.crypto.randomUUID(), status: 'attempted', checkpointed: false, createdAt: stamp, updatedAt: stamp,
+                ...(input.checkpoint !== undefined ? { checkpoint: clone(input.checkpoint) } : {}),
+                ...(superseded ? { retryAuthorization: clone(record.retryAuthorization), consentFingerprint } : {}) };
+            if (await storage.claim({ attempt, expectedGuard: guard || null, superseded, index, expectedIndex: indexBefore || null }))
+                return { status: 'execute', receipt: receipt(attempt) };
+        }
+        return hold(null, 'claim_contended');
+    }
+    async function complete(input) {
+        const { record, action, outcome } = input, id = await identity(input);
+        const candidate = outcome && typeof outcome === 'object' && Object.hasOwn(action.outcomes || {}, outcome.status) ? clone(outcome) : { status: 'unknown', reason: 'invalid_action_result' };
+        for (let race = 0; race < 3; race++) {
+            const [stored, indexBefore] = await Promise.all([storage.readAttempt(id.attempt), storage.readPending(id.session)]);
+            const prior = check(stored, { scope: id.scope, attempt: id.attempt, signature: id.signature });
+            checkIndex(indexBefore, id.session);
+            if (!prior)
+                throw new ActionJournalError('completion_without_claim');
+            if (prior.status === 'completed')
+                return { status: 'completed', outcome: clone(prior.result), receipt: receipt(prior) };
+            if (prior.status === 'superseded')
+                throw new ActionJournalError('completion_after_supersession');
+            const guard = check(await storage.readScope(id.scope), { scope: id.scope });
+            if (!guard || guard.key !== record.key || guard.revision !== prior.revision)
+                throw new ActionJournalError('completion_ownership_lost');
+            if (!indexBefore || !Object.hasOwn(indexBefore.attempts, id.attempt) && !prior.checkpointed)
+                throw new ActionJournalError('missing_pending_action');
+            const index = nextIndex(indexBefore, id.session);
+            index.attempts[id.attempt] = index.sequence;
+            const attempt = { ...prior, checkpointed: false, sequence: index.sequence, status: candidate.status === 'unknown' ? 'unknown' : 'completed', result: candidate, revision: globalThis.crypto.randomUUID(), updatedAt: tick(), ...(input.checkpoint !== undefined ? { checkpoint: clone(input.checkpoint) } : {}) };
+            if (await storage.complete({ attempt, expected: prior, index, expectedIndex: indexBefore }))
+                return { status: attempt.status, outcome: clone(candidate), receipt: receipt(attempt) };
+        }
+        throw new ActionJournalError('completion_contended');
+    }
+    async function checkpoint({ sessionId, keys = [], receipts }) {
+        let count = 0;
+        const versioned = receipts !== undefined;
+        if (versioned && (!Array.isArray(receipts) || receipts.some(item => !item || typeof item.key !== 'string' || !Number.isSafeInteger(item.sequence) || item.sequence < 1)))
+            throw new ActionJournalError('invalid_checkpoint_receipt');
+        const expected = new Map(versioned ? receipts.map(item => [item.key, item.sequence]) : keys.map(key => [key, null]));
+        const session = await sessionHash(sessionId);
+        for (const [key, sequence] of expected) {
+            const id = await attemptId(sessionId, key);
+            for (let race = 0; race < 3; race++) {
+                const [stored, indexBefore] = await Promise.all([storage.readAttempt(id), storage.readPending(session)]);
+                const prior = check(stored, { attempt: id });
+                checkIndex(indexBefore, session);
+                if (!prior || versioned && prior.sequence !== sequence)
+                    break;
+                if (prior.status === 'superseded') {
+                    count++;
+                    break;
+                }
+                if (prior.checkpointed) {
+                    count++;
+                    break;
+                }
+                const guard = check(await storage.readScope(prior.scopeId), { scope: prior.scopeId });
+                if (!guard || guard.key !== prior.key || guard.revision !== prior.revision)
+                    break;
+                if (!indexBefore || !Object.hasOwn(indexBefore.attempts, id))
+                    throw new ActionJournalError('missing_pending_action');
+                const index = nextIndex(indexBefore, session);
+                delete index.attempts[id];
+                const attempt = { ...prior, checkpointed: true, revision: globalThis.crypto.randomUUID(), updatedAt: tick() };
+                delete attempt.checkpoint;
+                if (await storage.complete({ attempt, expected: prior, index, expectedIndex: indexBefore })) {
+                    count++;
+                    break;
+                }
+                if (race === 2)
+                    throw new ActionJournalError('checkpoint_contended');
+            }
+        }
+        return count;
+    }
+    async function pending({ sessionId }) {
+        const session = await sessionHash(sessionId);
+        for (let race = 0; race < 3; race++) {
+            const index = checkIndex(await storage.readPending(session), session);
+            if (!index)
+                return { records: [], checkpoint: null };
+            const records = await Promise.all(Object.keys(index.attempts).map(async (id) => check(await storage.readAttempt(id), { attempt: id })));
+            const after = checkIndex(await storage.readPending(session), session);
+            if (after?.revision !== index.revision)
+                continue;
+            if (records.some(row => !row || row.sessionId !== session || row.sequence !== index.attempts[row.attemptId]))
+                throw new ActionJournalError('pending_index_mismatch');
+            records.sort((a, b) => a.sequence - b.sequence || a.updatedAt - b.updatedAt || a.key.localeCompare(b.key));
+            const latest = records.filter(row => row.checkpoint !== undefined).at(-1);
+            return { records: clone(records), checkpoint: latest ? { key: latest.key, sequence: latest.sequence, status: latest.status, session: clone(latest.checkpoint) } : null };
+        }
+        throw new ActionJournalError('pending_read_contended');
+    }
+    return Object.freeze({ claim, complete, checkpoint, pending });
+}
+/** Hermetic adapter. Share this object across recreated ports to model process loss; never use it as production persistence. */
+export function createMemoryActionStorage() {
+    const attempts = new Map(), scopes = new Map(), indexes = new Map();
+    const read = (rows, id) => rows.has(id) ? clone(rows.get(id)) : null;
+    const matches = (actual, expected) => expected ? actual?.revision === expected.revision : !actual;
+    return Object.freeze({
+        async readAttempt(id) { return read(attempts, id); }, async readScope(id) { return read(scopes, id); }, async readPending(id) { return read(indexes, id); },
+        async claim({ attempt, expectedGuard, superseded = null, index, expectedIndex }) {
+            if (attempts.has(attempt.attemptId) || !matches(scopes.get(attempt.scopeId), expectedGuard) || !matches(indexes.get(index.sessionId), expectedIndex) || superseded && !matches(attempts.get(superseded.expected.attemptId), superseded.expected))
+                return false;
+            const guard = clone(attempt);
+            delete guard.checkpoint;
+            attempts.set(attempt.attemptId, clone(attempt));
+            scopes.set(attempt.scopeId, guard);
+            indexes.set(index.sessionId, clone(index));
+            if (superseded)
+                attempts.set(superseded.attempt.attemptId, clone(superseded.attempt));
+            return true;
+        },
+        async complete({ attempt, expected, index, expectedIndex }) {
+            if (!matches(attempts.get(attempt.attemptId), expected) || !matches(scopes.get(attempt.scopeId), expected) || !matches(indexes.get(index.sessionId), expectedIndex))
+                return false;
+            const guard = clone(attempt);
+            delete guard.checkpoint;
+            attempts.set(attempt.attemptId, clone(attempt));
+            scopes.set(attempt.scopeId, guard);
+            indexes.set(index.sessionId, clone(index));
+            return true;
+        },
+    });
+}

package/dist/host/action-session.d.ts

@@ -0,0 +1,12 @@
+/** Save-boundary helpers. A receipt acknowledges only the exact action version consumed by the saved session. */
+export function actionSessionSnapshot(session: any): {
+    keys: any[];
+    receipts: {
+        key: any;
+        sequence: any;
+    }[];
+    session: any;
+};
+/** String keys resolve through the consumed-revision map; explicit receipt objects freeze the host's save boundary. */
+export function checkpointActionSession(journal: any, session: any, keys?: any[]): Promise<any>;
+//# sourceMappingURL=action-session.d.ts.map

package/dist/host/action-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-session.d.ts","sourceRoot":"","sources":["../../src/host/action-session.js"],"names":[],"mappings":"AAAA,iHAAiH;AACjH;;;;;;;EAKC;AACD,uHAAuH;AACvH,gGAeC"}

package/dist/host/action-session.js

@@ -0,0 +1,29 @@
+/** Save-boundary helpers. A receipt acknowledges only the exact action version consumed by the saved session. */
+export function actionSessionSnapshot(session) {
+    const keys = [...new Set(session?.cargo?.actionJournalReceipts || [])];
+    const revisions = session?.cargo?.actionJournalReceiptRevisions || {};
+    const receipts = keys.filter(key => Number.isSafeInteger(revisions[key]) && revisions[key] > 0).map(key => ({ key, sequence: revisions[key] }));
+    return { keys, receipts, session };
+}
+/** String keys resolve through the consumed-revision map; explicit receipt objects freeze the host's save boundary. */
+export async function checkpointActionSession(journal, session, keys = []) {
+    if (!keys.length)
+        return 0;
+    const revisions = session?.cargo?.actionJournalReceiptRevisions || {};
+    const selected = new Map(keys.map(item => typeof item === 'string' ? [item, revisions[item]] : [item.key, item.sequence]));
+    const receipts = [...selected].filter(([, sequence]) => Number.isSafeInteger(sequence) && sequence > 0).map(([key, sequence]) => ({ key, sequence }));
+    if (!receipts.length)
+        return 0;
+    if (!journal)
+        throw new Error('Cannot checkpoint action receipts without a durable journal');
+    const count = await journal.checkpoint({ sessionId: session.sessionId, receipts });
+    if (count === selected.size && receipts.length === selected.size) {
+        const acknowledged = new Map(receipts.map(item => [item.key, item.sequence]));
+        const current = session.cargo.actionJournalReceiptRevisions || {};
+        session.cargo.actionJournalReceipts = (session.cargo.actionJournalReceipts || []).filter(key => !acknowledged.has(key) || current[key] !== acknowledged.get(key));
+        for (const { key, sequence } of receipts)
+            if (current[key] === sequence)
+                delete current[key];
+    }
+    return count;
+}

package/dist/host/capabilities.d.ts

@@ -0,0 +1,14 @@
+/** Copy/normalize declaration data so subsequent caller mutations cannot change admission. */
+export function normalizeHostRequirements(requirements: any, flowId: any): readonly any[];
+/** Durable is the native default; session-only must be selected explicitly by the host. */
+export function actionPersistenceMode(mode?: string): "durable" | "session-only";
+/** Boolean requirements remain strict. guardedActions additionally accepts the explicit session-only policy. */
+export function assertFlowHostCapabilities(flows: any, capabilities?: {}): boolean;
+/** Declarative flow admission. No engine imports, I/O, or implicit host capability activation. */
+export class JSFEHostCapabilityError extends Error {
+    constructor(flowId: any, capability: any, reason: any);
+    code: string;
+    flowId: any;
+    capability: any;
+}
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/host/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../src/host/capabilities.js"],"names":[],"mappings":"AAWA,8FAA8F;AAC9F,0FASC;AAED,2FAA2F;AAC3F,iFAKC;AAED,gHAAgH;AAChH,mFA0BC;AA1DD,kGAAkG;AAClG;IACG,uDAMC;IAHE,aAA2C;IAC3C,YAA0B;IAC1B,gBAAkC;CAEvC"}

package/dist/host/capabilities.js

@@ -0,0 +1,60 @@
+/** Declarative flow admission. No engine imports, I/O, or implicit host capability activation. */
+export class JSFEHostCapabilityError extends Error {
+    constructor(flowId, capability, reason) {
+        super(`Flow ${flowId || '<unknown>'} host capability ${capability || '<declaration>'}: ${reason}`);
+        this.name = 'JSFEHostCapabilityError';
+        this.code = 'JSFE_HOST_CAPABILITY_REQUIRED';
+        this.flowId = flowId || '';
+        this.capability = capability || '';
+    }
+}
+/** Copy/normalize declaration data so subsequent caller mutations cannot change admission. */
+export function normalizeHostRequirements(requirements, flowId) {
+    if (requirements === undefined)
+        return Object.freeze([]);
+    if (!Array.isArray(requirements))
+        throw new JSFEHostCapabilityError(flowId, '', 'contract.requires must be an array of nonempty capability names');
+    for (const name of requirements) {
+        if (typeof name !== 'string' || !name || name.trim() !== name) {
+            throw new JSFEHostCapabilityError(flowId, '', 'contract.requires must contain nonempty, unpadded strings');
+        }
+    }
+    return Object.freeze([...new Set(requirements)]);
+}
+/** Durable is the native default; session-only must be selected explicitly by the host. */
+export function actionPersistenceMode(mode = 'durable') {
+    if (mode !== 'durable' && mode !== 'session-only') {
+        throw new JSFEHostCapabilityError('', 'actionPersistence', "must be 'durable' or 'session-only'");
+    }
+    return mode;
+}
+/** Boolean requirements remain strict. guardedActions additionally accepts the explicit session-only policy. */
+export function assertFlowHostCapabilities(flows, capabilities = {}) {
+    if (!Array.isArray(flows))
+        throw new JSFEHostCapabilityError('', '', 'flows must be an array');
+    const own = key => Object.prototype.hasOwnProperty.call(capabilities || {}, key);
+    const mode = actionPersistenceMode(own('actionPersistence') ? capabilities.actionPersistence : undefined);
+    if (mode === 'session-only' && capabilities?.durableActions === true) {
+        throw new JSFEHostCapabilityError('', 'actionPersistence', 'session-only conflicts with durableActions:true');
+    }
+    for (const flow of flows) {
+        const requirements = normalizeHostRequirements(flow?.variables?.contract?.value?.requires, flow?.id);
+        for (const capability of requirements) {
+            if (!capabilities || typeof capabilities !== 'object' || Array.isArray(capabilities)) {
+                throw new JSFEHostCapabilityError(flow?.id, capability, 'explicit host capabilities must be an object');
+            }
+            if (capability === 'guardedActions') {
+                if (own('durableActions') && capabilities.durableActions === true || own('actionPersistence') && mode === 'session-only')
+                    continue;
+                throw new JSFEHostCapabilityError(flow?.id, capability, 'requires explicit boolean true for durableActions or explicit actionPersistence:session-only');
+            }
+            if (!Object.prototype.hasOwnProperty.call(capabilities, capability)) {
+                throw new JSFEHostCapabilityError(flow?.id, capability, 'requires explicit boolean true; capability is missing');
+            }
+            if (capabilities[capability] !== true) {
+                throw new JSFEHostCapabilityError(flow?.id, capability, `requires explicit boolean true; received ${typeof capabilities[capability]}`);
+            }
+        }
+    }
+    return true;
+}

package/dist/host/checkpoint-codec-error.d.ts

@@ -0,0 +1,6 @@
+/** Stable codec errors are safe to inspect without loading a Node-only storage implementation. */
+export class CheckpointCodecError extends Error {
+    constructor(code: any);
+    code: any;
+}
+//# sourceMappingURL=checkpoint-codec-error.d.ts.map

package/dist/host/checkpoint-codec-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-codec-error.d.ts","sourceRoot":"","sources":["../../src/host/checkpoint-codec-error.js"],"names":[],"mappings":"AAAA,kGAAkG;AAClG;IACC,uBAAyG;IAAhB,UAAc;CACvG"}

package/dist/host/checkpoint-codec-error.js

@@ -0,0 +1,4 @@
+/** Stable codec errors are safe to inspect without loading a Node-only storage implementation. */
+export class CheckpointCodecError extends Error {
+    constructor(code) { super('JSFE checkpoint codec: ' + code); this.name = 'CheckpointCodecError'; this.code = code; }
+}