jsfe 1.7.1 → 1.7.3

package/dist/helpers/form-proposals.js

@@ -0,0 +1,292 @@
+/** Owned input proposals. Candidates and their consent remain separate from canonical values and action proposals. */
+import { formInputApplies, formValuesEqual, hasFormValue } from './form-state.js';
+import { formSignature, actionConfirmationValid } from './form-actions.js';
+import { validateFormProposalPolicy, validateFormProposalDescriptor, validateProposalData } from './proposal-contract.js';
+const own = (value, key) => Object.prototype.hasOwnProperty.call(value || {}, key);
+const statuses = new Set(['pending', 'confirmed', 'declined', 'superseded']);
+const fail = message => { throw new Error('FORM input proposal ' + message); };
+const text = value => typeof value === 'string' && !!value.trim();
+function data(value) {
+    const seen = new Set();
+    const inspect = item => {
+        if (!item || typeof item !== 'object')
+            return;
+        if (seen.has(item))
+            fail('requires acyclic JSON data');
+        seen.add(item);
+        if (Object.getOwnPropertySymbols(item).length)
+            fail('requires JSON data without symbols');
+        for (const [key, property] of Object.entries(Object.getOwnPropertyDescriptors(item))) {
+            if (Array.isArray(item) && key === 'length')
+                continue;
+            if (Array.isArray(item) && (!/^(0|[1-9]\d*)$/.test(key) || Number(key) >= item.length))
+                fail('requires JSON arrays without extra properties');
+            if (property.get || property.set || !property.enumerable)
+                fail('requires enumerable JSON data properties');
+            inspect(property.value);
+        }
+        seen.delete(item);
+    };
+    inspect(value);
+    validateProposalData(value);
+    return structuredClone(value);
+}
+function inputOwner(cargo, id, name) {
+    const state = cargo?.forms?.[id], spec = state?.specs?.flatMap(input => input.any_of || [input]).find(input => input.name === name);
+    if (!state || state.id !== id || !spec || ['__proto__', 'prototype', 'constructor'].includes(name))
+        fail('requires a live owning input');
+    if (!Number.isSafeInteger(state.revision) || state.revision < 0 || !text(state.definition) || !text(state.task))
+        fail('has invalid owner identity or revision');
+    return { state, spec };
+}
+function candidate(cargo, reading) {
+    if (!reading || reading.ok !== true || !hasFormValue(reading.value))
+        fail('requires a validated nonempty candidate');
+    const owner = inputOwner(cargo, reading.form, reading.name);
+    data(reading.value);
+    return owner;
+}
+const identity = state => ({ id: state.id, definition: state.definition, task: state.task });
+const signature = (owner, input, value, revision, descriptor) => formSignature({ owner, input, value, revision, binding: descriptor.binding ?? null, descriptor });
+const token = (value, record) => !!value && typeof value === 'object' && !Array.isArray(value) && Object.keys(value).every(key => ['id', 'signature'].includes(key)) && value.id === record?.id && value.signature === record?.signature;
+const sourceReading = reading => Object.fromEntries(['raw', 'utterance', 'origin', 'current', 'asked'].filter(key => reading[key] !== undefined).map(key => [key, data(reading[key])]));
+function recordFor(cargo, state, name) {
+    const record = state.inputProposals?.[name];
+    if (!record)
+        return null;
+    if (!text(record.id) || record.form !== state.id || record.input !== name || !statuses.has(record.status) || typeof record.committed !== 'boolean' || !Number.isSafeInteger(record.owner_revision) || record.owner_revision < 0 || !Number.isSafeInteger(record.revision) || record.revision < 1 || typeof record.child !== 'string' || !hasFormValue(record.value) || !record.reading || typeof record.reading !== 'object' || Array.isArray(record.reading))
+        fail('has invalid retained state');
+    data(record.value);
+    data(record.reading);
+    const descriptor = validateFormProposalDescriptor(record.descriptor);
+    if (!formValuesEqual(record.owner, identity(state)) || !formValuesEqual(record.binding, descriptor.binding ?? null) || record.signature !== signature(record.owner, name, record.value, record.owner_revision, descriptor))
+        fail('retained identity or binding changed');
+    return record;
+}
+const active = record => !!record && !record.committed && ['pending', 'confirmed'].includes(record.status);
+function contextChild(cargo, state, id) {
+    const child = cargo.forms?.[id];
+    return child && child.id === id && child.context_only === true && child.parent === state.id && child.task === state.task && state.contexts?.[child.definition] === id ? child : null;
+}
+function withdraw(cargo, state, record) {
+    const child = contextChild(cargo, state, record.child);
+    if (child && child.proposalPrompt?.id === record.id && child.proposalPrompt?.signature === record.signature && child.proposalPrompt?.input === record.input) {
+        child.confirmation = null;
+        delete child.proposalPrompt;
+    }
+    delete record.approval;
+}
+const current = (state, record) => record.owner_revision === state.revision && record.signature === signature(identity(state), record.input, record.value, state.revision, record.descriptor);
+function proofValid(cargo, state, record) {
+    if (!record || record.status !== 'confirmed' || record.committed || record.deferred || !current(state, record) || !record.approval)
+        return false;
+    const proof = record.approval;
+    if (proof.id !== record.id || proof.signature !== record.signature || proof.child !== record.child || !Number.isSafeInteger(proof.revision) || proof.confirmation?.revision !== proof.revision)
+        return false;
+    const child = cargo.forms?.[record.child];
+    return !child || !!contextChild(cargo, state, record.child) && child.proposalPrompt?.id === record.id && child.proposalPrompt?.signature === record.signature && child.revision === proof.revision && formValuesEqual(child.confirmation, proof.confirmation) && actionConfirmationValid(cargo, child.id, { signature: child.proposal?.signature || null });
+}
+function approved(cargo, state, record, reading) {
+    return token(reading.proposalResume, record) && token(reading.proposalApproval, record) && formValuesEqual(reading.value, record.value) && proofValid(cargo, state, record);
+}
+/** Static policy selectors use this batch's proposed values; a validator's explicit descriptor independently applies. */
+export function formProposalPolicy(cargo, reading, check, accepted = []) {
+    const { state, spec } = inputOwner(cargo, reading.form, reading.name);
+    const declared = spec.proposal === undefined ? null : validateFormProposalPolicy(spec.proposal);
+    const dynamic = check && own(check, 'proposal') && check.proposal !== undefined ? validateFormProposalDescriptor(check.proposal) : null;
+    if (check?.ok === false)
+        return null;
+    const record = recordFor(cargo, state, reading.name), values = { ...state.values, ...Object.fromEntries(accepted.filter(hit => hit.form === state.id && hit.ok === true).map(hit => [hit.name, hit.value])), [reading.name]: reading.value };
+    const origin = reading.origin || 'answer';
+    const matches = declared && formInputApplies(declared, values, cargo, state) && (!declared.origins || declared.origins.includes(origin) || active(record));
+    return matches || dynamic ? { ...(matches ? declared : {}), ...(dynamic || {}) } : null;
+}
+/** A null descriptor admits ordinary input, but cannot silently waive the same retained candidate's consent. */
+export function stageFormProposal(cargo, reading, descriptor) {
+    const { state } = candidate(cargo, reading), decision = descriptor === null ? null : validateFormProposalDescriptor(descriptor);
+    let old = recordFor(cargo, state, reading.name);
+    const resumed = own(reading, 'proposalResume');
+    if (resumed && !token(reading.proposalResume, old))
+        return false;
+    if (old?.committed && resumed)
+        return false;
+    if (decision === null) {
+        if (!old || old.status === 'superseded' || old.committed)
+            return !own(reading, 'proposalApproval');
+        if (old.status === 'declined') {
+            if (!resumed && !own(reading, 'proposalApproval')) {
+                withdraw(cargo, state, old);
+                old.status = 'superseded';
+                return true;
+            }
+            return false;
+        }
+        if (formValuesEqual(old.value, reading.value)) {
+            if (approved(cargo, state, old, reading))
+                return true;
+            withdraw(cargo, state, old);
+            old.status = 'superseded';
+            return false;
+        }
+        if (resumed)
+            return false;
+        withdraw(cargo, state, old);
+        old.status = 'superseded';
+        return !own(reading, 'proposalApproval');
+    }
+    const binding = data(decision.binding ?? null), value = data(reading.value), nextSignature = signature(identity(state), reading.name, value, state.revision, decision);
+    const same = old && !old.committed && ['pending', 'confirmed', 'declined'].includes(old.status) && formValuesEqual(old.value, value) && formValuesEqual(old.binding, binding);
+    if (same && old.status === 'declined' && resumed)
+        return false;
+    if (!same || old.status === 'declined') {
+        if (old) {
+            withdraw(cargo, state, old);
+            old.status = 'superseded';
+        }
+        const sequence = state.inputProposalSequence ?? 0;
+        if (!Number.isSafeInteger(sequence) || sequence < 0 || !Number.isSafeInteger(sequence + 1))
+            fail('has an invalid proposal sequence');
+        state.inputProposalSequence = sequence + 1;
+        old = { id: `${state.id}:proposal:${state.inputProposalSequence}`, form: state.id, input: reading.name, owner: identity(state), value, reading: sourceReading(reading), descriptor: decision, binding, signature: nextSignature, owner_revision: state.revision, revision: 1, status: 'pending', committed: false, deferred: false, child: '' };
+        state.inputProposals ||= {};
+        state.inputProposals[reading.name] = old;
+    }
+    else if (old.signature !== nextSignature) {
+        withdraw(cargo, state, old);
+        Object.assign(old, { value, descriptor: decision, binding, signature: nextSignature, owner_revision: state.revision, revision: old.revision + 1, status: 'pending' });
+    }
+    old.deferred = false;
+    return approved(cargo, state, old, reading);
+}
+/** Only actionable records enter the confirmation worker; dependency-deferred records await the normal batch. */
+export function nextFormProposal(cargo, owner) {
+    const state = cargo.forms?.[owner];
+    if (!state)
+        return null;
+    for (const spec of state.specs.flatMap(input => input.any_of || [input])) {
+        const record = recordFor(cargo, state, spec.name);
+        if (active(record) && !record.deferred && formInputApplies(spec, { ...state.values, [spec.name]: record.value }, cargo, state))
+            return record;
+    }
+    return null;
+}
+/** Owner replay issues approval only for confirmed records; named child refresh never invents approval. */
+export function formProposalReadings(cargo, owner, input = '', approve = true) {
+    const state = cargo.forms?.[owner];
+    if (!state)
+        return [];
+    const names = input ? [input] : Object.keys(state.inputProposals || {}), out = [];
+    for (const name of names) {
+        const { spec } = inputOwner(cargo, owner, name), record = recordFor(cargo, state, name);
+        if (!record || record.committed || record.status === 'superseded' || record.deferred || approve && record.status !== 'confirmed' || !input && record.status === 'declined')
+            continue;
+        const hit = { ...spec, ...data(record.reading), form: owner, name, value: data(record.value), revalidate: true, proposalResume: { id: record.id, signature: record.signature } };
+        delete hit.proposalApproval;
+        if (approve && proofValid(cargo, state, record))
+            hit.proposalApproval = { id: record.id, signature: record.signature };
+        out.push(hit);
+    }
+    return out;
+}
+/** Bind only a real context child; ordinary child slots and unrelated owners cannot collect consent. */
+export function bindFormProposal(cargo, owner, input, childId) {
+    const { state } = inputOwner(cargo, owner, input), record = recordFor(cargo, state, input), child = contextChild(cargo, state, childId);
+    if (!active(record) || record.deferred || !current(state, record) || !child)
+        fail('cannot bind a stale proposal or foreign confirmation child');
+    if (record.child && record.child !== childId)
+        withdraw(cargo, state, record);
+    if (child.proposalPrompt?.id !== record.id || child.proposalPrompt?.signature !== record.signature)
+        child.confirmation = null;
+    record.child = childId;
+    child.proposalPrompt = { id: record.id, signature: record.signature, input };
+    return record;
+}
+/** Exact YES must have passed the ordinary confirm-form revision check; NO never admits the candidate. */
+export function decideFormProposal(cargo, owner, input, childId, decision) {
+    if (!['confirmed', 'declined'].includes(decision))
+        fail('has an invalid decision');
+    const { state } = inputOwner(cargo, owner, input), record = recordFor(cargo, state, input), child = contextChild(cargo, state, childId);
+    if (!active(record) || record.deferred || !current(state, record) || !child || record.child !== childId || child.proposalPrompt?.id !== record.id || child.proposalPrompt?.signature !== record.signature || child.proposalPrompt?.input !== input)
+        return false;
+    if (decision === 'confirmed' && !actionConfirmationValid(cargo, childId, { signature: child.proposal?.signature || null }))
+        return false;
+    record.status = decision;
+    if (decision === 'confirmed')
+        record.approval = { id: record.id, signature: record.signature, child: childId, revision: child.revision, confirmation: data(child.confirmation) };
+    else {
+        withdraw(cargo, state, record);
+        child.confirmation = null;
+    }
+    return true;
+}
+/** Validate the entire final batch before consuming any proof; invoke immediately before acceptFormReadings. */
+export function commitFormProposals(cargo, accepted = []) {
+    const changes = [], readings = [];
+    for (const hit of accepted) {
+        const { state } = candidate(cargo, hit);
+        readings.push({ state, hit });
+        const record = recordFor(cargo, state, hit.name);
+        if (!record) {
+            if (own(hit, 'proposalResume') || own(hit, 'proposalApproval'))
+                fail('approval has no live record');
+            continue;
+        }
+        const tagged = own(hit, 'proposalResume') || own(hit, 'proposalApproval');
+        if (tagged) {
+            if (!approved(cargo, state, record, hit))
+                fail('requires current unconsumed approval before commitment');
+            if (changes.some(change => change.record === record))
+                fail('approval cannot be consumed twice in one batch');
+            changes.push({ state, record, commit: true });
+        }
+        else if (!record.committed && record.status !== 'superseded' && formValuesEqual(record.value, hit.value))
+            fail('cannot commit a retained candidate without approval');
+        else if (!formValuesEqual(record.value, hit.value) && record.status !== 'superseded')
+            changes.push({ state, record, commit: false });
+    }
+    // Canonical exclusive selection also replaces uncommitted peer candidates, even if this input has no proposal.
+    // Plan every withdrawal after validation, so an invalid later reading cannot partially consume consent.
+    for (const { state, hit } of readings)
+        for (const group of state.specs.filter(spec => spec.exclusive === true && spec.any_of?.some(member => member.name === hit.name))) {
+            const peers = group.any_of.filter(member => member.name !== hit.name);
+            if (readings.some(other => other.state.id === state.id && peers.some(peer => peer.name === other.hit.name)))
+                fail('exclusive alternatives require clarification before commitment');
+            for (const peer of peers) {
+                const record = recordFor(cargo, state, peer.name);
+                if (active(record) && !changes.some(change => change.record === record))
+                    changes.push({ state, record, commit: false });
+            }
+        }
+    for (const { state, record, commit } of changes) {
+        if (commit) {
+            record.committed = true;
+            record.deferred = false;
+        }
+        else
+            record.status = 'superseded';
+        withdraw(cargo, state, record);
+    }
+    return true;
+}
+/** Failed validation withdraws the candidate; unmet prerequisites wait for the normal dependency replay. */
+export function settleFormProposalValidation(cargo, batch = {}) {
+    for (const hit of [...(batch.rejected || []), ...(batch.ignored || [])]) {
+        const state = cargo.forms?.[hit.form];
+        if (!state)
+            continue;
+        const record = recordFor(cargo, state, hit.name);
+        if (active(record)) {
+            withdraw(cargo, state, record);
+            record.status = 'superseded';
+        }
+    }
+    for (const hit of batch.pending || []) {
+        const state = cargo.forms?.[hit.form];
+        if (!state)
+            continue;
+        const record = recordFor(cargo, state, hit.name);
+        if (active(record))
+            record.deferred = true;
+    }
+    return batch;
+}

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

@@ -12,6 +12,7 @@ export function enrichFormMatches(matches: any, chain: any, form: any, names?: a
 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): {
+    ignored: any[];
     accepted: any[];
     rejected: any[];
     pending: any[];

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

@@ -1 +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"}
+{"version":3,"file":"form-state.d.ts","sourceRoot":"","sources":["../../src/helpers/form-state.js"],"names":[],"mappings":"AAOA,qDAKC;AAED,oDAEC;AAED,qFAAqF;AACrF,oEA2BC;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;AAvjBM,8CAAmE"}

package/dist/helpers/form-state.js

@@ -1,3 +1,4 @@
+import { validateFormProposalPolicy } from './proposal-contract.js';
 /** Shared FORM semantics. Pure readers plus explicit mutations of the supplied session container; no host I/O. */
 import { readInputProfile } from './match-inputs.js';
 import { validateMoneyOptions } from './money.js';
@@ -35,6 +36,13 @@ export function resolveFormInputs(inputs, presets = {}) {
             validateMoneyOptions(input.profile.money);
         }
         validateFormExhaustion(input.on_exhausted);
+        if (input.proposal !== undefined) {
+            if (!input.profile || input.form || input.any_of || input.bind)
+                throw new Error('FORM proposal requires a readable leaf input; declare it on each group member or inside the subform');
+            validateFormProposalPolicy(input.proposal);
+        }
+        if (input.max_misses !== undefined && (!Number.isInteger(input.max_misses) || input.max_misses < 1))
+            throw new Error('FORM max_misses must be a positive integer');
         if (input.max_attempts !== undefined && (!Number.isInteger(input.max_attempts) || input.max_attempts < 1))
             throw new Error('FORM max_attempts must be a positive integer');
         if (input.any_of)
@@ -262,7 +270,7 @@ export function settleFormActivations(batch = {}, cargo = null) {
             for (const [name, hit] of Object.entries(state.pending || {}))
                 if (discarded.has(hit.activation_group))
                     delete state.pending[name];
-    return { accepted: accepted.filter(h => !held.has(h.activation_group) && !discarded.has(h.activation_group)),
+    return { ignored: [...(batch.ignored || [])], accepted: accepted.filter(h => !held.has(h.activation_group) && !discarded.has(h.activation_group)),
         rejected: rejected.map(h => h.activation_inferred ? { ...h, ...h.activation_entry, activation_inferred: false } : h), pending: pending.concat(accepted.filter(h => held.has(h.activation_group))).filter(h => !discarded.has(h.activation_group)).map(h => held.has(h.activation_group) ? { ...h, ok: undefined, outcome: 'pending', silent: true } : h) };
 }
 /** Explicit ownership: unrelated tasks and sibling inputs never share an instance by definition id. */
@@ -300,7 +308,7 @@ export function openFormInstance(cargo, definition, specs, { parent = null, inpu
     cargo.formSequence = Number(cargo.formSequence || 0) + 1;
     const id = `${definition}:${cargo.formSequence}`;
     cargo.forms[id] = { id, definition, task: owner?.task || task || id, parent, result_input: input,
-        on_exhausted: on_exhausted || '', incomplete_outcome: incomplete, context_only: !!context, parent_revision: owner?.revision ?? null, specs, values: {}, accepted: {}, errors: {}, pending: {}, seeds: {}, attempts: {}, prepared: {}, data: {}, arguments: {}, contexts: {}, children: {}, childResults: {}, revision: 0,
+        on_exhausted: on_exhausted || '', incomplete_outcome: incomplete, context_only: !!context, parent_revision: owner?.revision ?? null, specs, values: {}, accepted: {}, errors: {}, pending: {}, seeds: {}, attempts: {}, misses: {}, feedback: {}, prepared: {}, data: {}, arguments: {}, contexts: {}, children: {}, childResults: {}, revision: 0,
         providers: providers || owner?.providers || null, questions: questions?.length ? questions : owner?.questions || [], status: 'collecting' };
     if (owner) {
         if (context) {

package/dist/helpers/index.d.ts

@@ -1,4 +1,21 @@
 export namespace STANDARD_FUNCTIONS {
+    export { formProposalPolicy };
+    export { stageFormProposal };
+    export { nextFormProposal };
+    export { formProposalReadings };
+    export { bindFormProposal };
+    export { decideFormProposal };
+    export { commitFormProposals };
+    export { settleFormProposalValidation };
+    export { formProposalProtocol };
+    export { validateFormProposalPolicy };
+    export { validateFormProposalDescriptor };
+    export { formProposalDescriptor };
+    export { clearFormMisses };
+    export { missFormInput };
+    export { formInputPrompt };
+    export { consumeFormFeedback };
+    export { formConversationOutcome };
     export { readMoneyAmount };
     export { isMoneyAmount };
     export { moneyIntentAllows };
@@ -88,6 +105,23 @@ export namespace STANDARD_FUNCTIONS {
     export { urlToSpeech };
     export { textWithUrlToSpeech };
 }
+import { formProposalPolicy } from './form-proposals.js';
+import { stageFormProposal } from './form-proposals.js';
+import { nextFormProposal } from './form-proposals.js';
+import { formProposalReadings } from './form-proposals.js';
+import { bindFormProposal } from './form-proposals.js';
+import { decideFormProposal } from './form-proposals.js';
+import { commitFormProposals } from './form-proposals.js';
+import { settleFormProposalValidation } from './form-proposals.js';
+import { formProposalProtocol } from './proposal-contract.js';
+import { validateFormProposalPolicy } from './proposal-contract.js';
+import { validateFormProposalDescriptor } from './proposal-contract.js';
+import { formProposalDescriptor } from './proposal-contract.js';
+import { clearFormMisses } from './form-conversation.js';
+import { missFormInput } from './form-conversation.js';
+import { formInputPrompt } from './form-conversation.js';
+import { consumeFormFeedback } from './form-conversation.js';
+import { formConversationOutcome } from './form-conversation.js';
 import { readMoneyAmount } from './money.js';
 import { isMoneyAmount } from './money.js';
 import { moneyIntentAllows } from './money.js';
@@ -181,5 +215,5 @@ import { validatePhone } from './validators.js';
 import { validateEmail } from './validators.js';
 import { urlToSpeech } from './url-speech.js';
 import { textWithUrlToSpeech } from './url-speech.js';
-export { readMoneyAmount, isMoneyAmount, moneyIntentAllows, validateMoneyOptions, takeChoiceOffer, 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, consumeActionReceipt, authorizeFormActionRetry, formSignature, selectFormAction, confirmFormRevision, prepareFormAction, actionConfirmationValid, beginFormAction, finishFormAction, actionGateVerified, sourceNeedsLoad, beginSourceRefresh, completeSourceRefresh, pickProviderQuestion, matchInputs, readFormAnswer, readInputProfile, resolveFormInputs, formInputApplies, formInputFilled, nextFormInput, formInputChain, openFormInstance, validateFormIncompleteOutcome, formIncompleteOutcome, validateFormExhaustion, exhaustFormInput, formInitialReadings, orderFormReadings, proposedFormValues, applyFormValidation, formReadingDependencies, exclusiveFormReadings, enrichFormMatches, expandFormActivations, settleFormActivations, rememberFormArguments, resetFormInputs, hasFormValue, formPath, formValuesEqual, formReadingReady, formReadingRelevant, formPreparation, queueFormReadings, pendingFormReadings, formWorkLimit, rejectFormReadings, invalidateFormInputs, acceptFormReadings, formInstanceApplies, closeFormInstance, checkOtp, maskDestination, validateOTP, OTP_EXPIRY_MS, validateDigits, validatePhone, validateEmail, urlToSpeech, textWithUrlToSpeech };
+export { formProposalPolicy, stageFormProposal, nextFormProposal, formProposalReadings, bindFormProposal, decideFormProposal, commitFormProposals, settleFormProposalValidation, formProposalProtocol, validateFormProposalPolicy, validateFormProposalDescriptor, formProposalDescriptor, clearFormMisses, missFormInput, formInputPrompt, consumeFormFeedback, formConversationOutcome, readMoneyAmount, isMoneyAmount, moneyIntentAllows, validateMoneyOptions, takeChoiceOffer, 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, consumeActionReceipt, authorizeFormActionRetry, formSignature, selectFormAction, confirmFormRevision, prepareFormAction, actionConfirmationValid, beginFormAction, finishFormAction, actionGateVerified, sourceNeedsLoad, beginSourceRefresh, completeSourceRefresh, pickProviderQuestion, matchInputs, readFormAnswer, readInputProfile, resolveFormInputs, formInputApplies, formInputFilled, nextFormInput, formInputChain, openFormInstance, validateFormIncompleteOutcome, formIncompleteOutcome, validateFormExhaustion, exhaustFormInput, formInitialReadings, orderFormReadings, proposedFormValues, applyFormValidation, formReadingDependencies, exclusiveFormReadings, enrichFormMatches, expandFormActivations, settleFormActivations, rememberFormArguments, resetFormInputs, hasFormValue, formPath, formValuesEqual, formReadingReady, formReadingRelevant, formPreparation, queueFormReadings, pendingFormReadings, formWorkLimit, rejectFormReadings, invalidateFormInputs, acceptFormReadings, formInstanceApplies, closeFormInstance, checkOtp, maskDestination, validateOTP, OTP_EXPIRY_MS, validateDigits, validatePhone, validateEmail, urlToSpeech, textWithUrlToSpeech };
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/helpers/index.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gCAkBmF,YAAY;8BAAZ,YAAY;kCAAZ,YAAY;qCAAZ,YAAY;gCAlB/D,mBAAmB;8BAiBrB,qBAAqB;6BAEkG,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;qCAxB+I,mBAAmB;yCAAnB,mBAAmB;8BAAnB,mBAAmB;iCAAnB,mBAAmB;oCAAnB,mBAAmB;kCAAnB,mBAAmB;wCAAnB,mBAAmB;gCAAnB,mBAAmB;iCAAnB,mBAAmB;mCAAnB,mBAAmB;gCAe1I,mBAAmB;mCAAnB,mBAAmB;sCAAnB,mBAAmB;qCAAnB,mBAAmB;4BAUtD,mBAAmB;+BAAnB,mBAAmB;iCAAnB,mBAAmB;kCAC6mB,iBAAiB;iCAAjB,iBAAiB;gCAAjB,iBAAiB;8BAAjB,iBAAiB;+BAAjB,iBAAiB;iCAAjB,iBAAiB;8CAAjB,iBAAiB;sCAAjB,iBAAiB;uCAAjB,iBAAiB;iCAAjB,iBAAiB;oCAAjB,iBAAiB;kCAAjB,iBAAiB;mCAAjB,iBAAiB;oCAAjB,iBAAiB;wCAAjB,iBAAiB;sCAAjB,iBAAiB;kCAAjB,iBAAiB;sCAAjB,iBAAiB;sCAAjB,iBAAiB;sCAAjB,iBAAiB;gCAAjB,iBAAiB;6BAAjB,iBAAiB;yBAAjB,iBAAiB;gCAAjB,iBAAiB;iCAAjB,iBAAiB;oCAAjB,iBAAiB;gCAAjB,iBAAiB;kCAAjB,iBAAiB;oCAAjB,iBAAiB;8BAAjB,iBAAiB;mCAAjB,iBAAiB;qCAAjB,iBAAiB;mCAAjB,iBAAiB;oCAAjB,iBAAiB;kCAAjB,iBAAiB;yBACzoB,gBAAgB;gCAAhB,gBAAgB;4BAAhB,gBAAgB;8BAAhB,gBAAgB;+BACzB,iBAAiB;8BAAjB,iBAAiB;8BAAjB,iBAAiB;4BAC7B,iBAAiB;oCAAjB,iBAAiB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/helpers/index.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mCAA8K,qBAAqB;kCAArB,qBAAqB;iCAArB,qBAAqB;qCAArB,qBAAqB;iCAArB,qBAAqB;mCAArB,qBAAqB;oCAArB,qBAAqB;6CAArB,qBAAqB;qCAC/E,wBAAwB;2CAAxB,wBAAwB;+CAAxB,wBAAwB;uCAAxB,wBAAwB;gCACpC,wBAAwB;8BAAxB,wBAAwB;gCAAxB,wBAAwB;oCAAxB,wBAAwB;wCAAxB,wBAAwB;gCAmB7C,YAAY;8BAAZ,YAAY;kCAAZ,YAAY;qCAAZ,YAAY;gCAlB/D,mBAAmB;8BAiBrB,qBAAqB;6BAEkG,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;qCAxB+I,mBAAmB;yCAAnB,mBAAmB;8BAAnB,mBAAmB;iCAAnB,mBAAmB;oCAAnB,mBAAmB;kCAAnB,mBAAmB;wCAAnB,mBAAmB;gCAAnB,mBAAmB;iCAAnB,mBAAmB;mCAAnB,mBAAmB;gCAe1I,mBAAmB;mCAAnB,mBAAmB;sCAAnB,mBAAmB;qCAAnB,mBAAmB;4BAUtD,mBAAmB;+BAAnB,mBAAmB;iCAAnB,mBAAmB;kCAC6mB,iBAAiB;iCAAjB,iBAAiB;gCAAjB,iBAAiB;8BAAjB,iBAAiB;+BAAjB,iBAAiB;iCAAjB,iBAAiB;8CAAjB,iBAAiB;sCAAjB,iBAAiB;uCAAjB,iBAAiB;iCAAjB,iBAAiB;oCAAjB,iBAAiB;kCAAjB,iBAAiB;mCAAjB,iBAAiB;oCAAjB,iBAAiB;wCAAjB,iBAAiB;sCAAjB,iBAAiB;kCAAjB,iBAAiB;sCAAjB,iBAAiB;sCAAjB,iBAAiB;sCAAjB,iBAAiB;gCAAjB,iBAAiB;6BAAjB,iBAAiB;yBAAjB,iBAAiB;gCAAjB,iBAAiB;iCAAjB,iBAAiB;oCAAjB,iBAAiB;gCAAjB,iBAAiB;kCAAjB,iBAAiB;oCAAjB,iBAAiB;8BAAjB,iBAAiB;mCAAjB,iBAAiB;qCAAjB,iBAAiB;mCAAjB,iBAAiB;oCAAjB,iBAAiB;kCAAjB,iBAAiB;yBACzoB,gBAAgB;gCAAhB,gBAAgB;4BAAhB,gBAAgB;8BAAhB,gBAAgB;+BACzB,iBAAiB;8BAAjB,iBAAiB;8BAAjB,iBAAiB;4BAC7B,iBAAiB;oCAAjB,iBAAiB"}

package/dist/helpers/index.js

@@ -1,3 +1,6 @@
+import { formProposalPolicy, stageFormProposal, nextFormProposal, formProposalReadings, bindFormProposal, decideFormProposal, commitFormProposals, settleFormProposalValidation } from './form-proposals.js';
+import { formProposalProtocol, validateFormProposalPolicy, validateFormProposalDescriptor, formProposalDescriptor } from './proposal-contract.js';
+import { clearFormMisses, missFormInput, formInputPrompt, consumeFormFeedback, formConversationOutcome } from './form-conversation.js';
 import { takeChoiceOffer } from './choice-offer.js';
 import { consumeActionReceipt, authorizeFormActionRetry, formSignature, selectFormAction, confirmFormRevision, prepareFormAction, actionConfirmationValid, beginFormAction, finishFormAction, actionGateVerified } from './form-actions.js';
 /**
@@ -29,9 +32,11 @@ import { resolveFormInputs, formInputApplies, formInputFilled, nextFormInput, fo
 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 { readMoneyAmount, isMoneyAmount, moneyIntentAllows, validateMoneyOptions, takeChoiceOffer, 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, consumeActionReceipt, authorizeFormActionRetry, formSignature, selectFormAction, confirmFormRevision, prepareFormAction, actionConfirmationValid, beginFormAction, finishFormAction, actionGateVerified, sourceNeedsLoad, beginSourceRefresh, completeSourceRefresh, pickProviderQuestion, matchInputs, readFormAnswer, readInputProfile, resolveFormInputs, formInputApplies, formInputFilled, nextFormInput, formInputChain, openFormInstance, validateFormIncompleteOutcome, formIncompleteOutcome, validateFormExhaustion, exhaustFormInput, formInitialReadings, orderFormReadings, proposedFormValues, applyFormValidation, formReadingDependencies, exclusiveFormReadings, enrichFormMatches, expandFormActivations, settleFormActivations, rememberFormArguments, resetFormInputs, hasFormValue, formPath, formValuesEqual, formReadingReady, formReadingRelevant, formPreparation, queueFormReadings, pendingFormReadings, formWorkLimit, rejectFormReadings, invalidateFormInputs, acceptFormReadings, formInstanceApplies, closeFormInstance, checkOtp, maskDestination, validateOTP, OTP_EXPIRY_MS, validateDigits, validatePhone, validateEmail, urlToSpeech, textWithUrlToSpeech, };
+export { formProposalPolicy, stageFormProposal, nextFormProposal, formProposalReadings, bindFormProposal, decideFormProposal, commitFormProposals, settleFormProposalValidation, formProposalProtocol, validateFormProposalPolicy, validateFormProposalDescriptor, formProposalDescriptor, clearFormMisses, missFormInput, formInputPrompt, consumeFormFeedback, formConversationOutcome, readMoneyAmount, isMoneyAmount, moneyIntentAllows, validateMoneyOptions, takeChoiceOffer, 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, consumeActionReceipt, authorizeFormActionRetry, formSignature, selectFormAction, confirmFormRevision, prepareFormAction, actionConfirmationValid, beginFormAction, finishFormAction, actionGateVerified, sourceNeedsLoad, beginSourceRefresh, completeSourceRefresh, pickProviderQuestion, matchInputs, readFormAnswer, readInputProfile, resolveFormInputs, formInputApplies, formInputFilled, nextFormInput, formInputChain, openFormInstance, validateFormIncompleteOutcome, formIncompleteOutcome, validateFormExhaustion, exhaustFormInput, formInitialReadings, orderFormReadings, proposedFormValues, applyFormValidation, formReadingDependencies, exclusiveFormReadings, enrichFormMatches, expandFormActivations, settleFormActivations, rememberFormArguments, resetFormInputs, hasFormValue, formPath, formValuesEqual, formReadingReady, formReadingRelevant, formPreparation, queueFormReadings, pendingFormReadings, formWorkLimit, rejectFormReadings, invalidateFormInputs, acceptFormReadings, formInstanceApplies, closeFormInstance, 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 = {
+    formProposalPolicy, stageFormProposal, nextFormProposal, formProposalReadings, bindFormProposal, decideFormProposal, commitFormProposals, settleFormProposalValidation, formProposalProtocol, validateFormProposalPolicy, validateFormProposalDescriptor, formProposalDescriptor,
+    clearFormMisses, missFormInput, formInputPrompt, consumeFormFeedback, formConversationOutcome,
     readMoneyAmount, isMoneyAmount, moneyIntentAllows, validateMoneyOptions, takeChoiceOffer, matchesChoice, isAnswer, isAgentRequest, isOtherRequest, isSpelledFragment, isAmountAnswer, amountInAnswer, pickChoice,
     readEmail, readPhone, readInternationalPhone, readIdentifier, last4, maskEmail, callerTextNumber, textDestination, callerIsInternational,
     normalizeAndFindCapture, anythingElse, goodbye, sayName, dateToWords, amountToSpeech, validateCardNumber, validateExpiration, consumeActionReceipt, authorizeFormActionRetry, formSignature, selectFormAction, confirmFormRevision, prepareFormAction, actionConfirmationValid, beginFormAction, finishFormAction, actionGateVerified, sourceNeedsLoad, beginSourceRefresh, completeSourceRefresh, pickProviderQuestion, matchInputs, readFormAnswer, readInputProfile, resolveFormInputs, formInputApplies, formInputFilled, nextFormInput, formInputChain, openFormInstance, validateFormIncompleteOutcome, formIncompleteOutcome, validateFormExhaustion, exhaustFormInput, formInitialReadings, orderFormReadings, proposedFormValues, applyFormValidation, formReadingDependencies, exclusiveFormReadings, enrichFormMatches, expandFormActivations, settleFormActivations, rememberFormArguments, resetFormInputs, hasFormValue, formPath, formValuesEqual, formReadingReady, formReadingRelevant, formPreparation, queueFormReadings, pendingFormReadings, formWorkLimit, rejectFormReadings, invalidateFormInputs, acceptFormReadings, formInstanceApplies, closeFormInstance,

package/dist/helpers/match-inputs.js

@@ -232,7 +232,7 @@ export function readFormAnswer(answer, candidates, current, choiceKey, questions
     let consumed = false;
     const remaining = parts.map(part => {
         const text = part.trim();
-        if (!/^[¿\s]*(?:how\b|what\b|when\b|where\b|which\b|why\b|who\b|cu[aá]nt[oa]s?\b|qu[eé]\b|cu[aá]ndo\b|d[oó]nde\b|c[oó]mo\b|(?:can|could) you (?:tell|show)\b|(?:i (?:want|would like) to know|tell me|show me|quiero saber|quisiera saber|me gustar[ií]a saber|d[ií]game|dime|mu[eé]strame)\b)/i.test(text))
+        if (!/^[¿\s]*(?:how\b|what\b|when\b|where\b|which\b|why\b|who\b|cu[aá]nt[oa]s?\b|cu[aá]l(?:es)?\b|qu[eé](?=$|[^\p{L}\p{N}_])|cu[aá]ndo\b|d[oó]nde\b|c[oó]mo\b|(?:can|could) you (?:tell|show)\b|(?:i (?:want|would like) to know|tell me|show me|quiero saber|quisiera saber|me gustar[ií]a saber|d[ií]game|dime|mu[eé]strame)\b)/iu.test(text))
             return part;
         const key = pickProviderQuestion(text, questions);
         if (!key || key.startsWith('__'))

package/dist/helpers/proposal-contract.d.ts

@@ -0,0 +1,7 @@
+export function validateProposalData(value: any, seen?: Set<any>): any;
+export function validateFormProposalPolicy(value: any): any;
+export function validateFormProposalDescriptor(value: any): any;
+/** Keep policy selectors out of the runtime decision descriptor; null is an explicit opt-out. */
+export function formProposalDescriptor(policy: any, prepared?: undefined): any;
+export function formProposalProtocol(): number;
+//# sourceMappingURL=proposal-contract.d.ts.map

package/dist/helpers/proposal-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proposal-contract.d.ts","sourceRoot":"","sources":["../../src/helpers/proposal-contract.js"],"names":[],"mappings":"AAMA,uEAcC;AAUD,4DAWC;AACD,gEAIC;AACD,iGAAiG;AACjG,+EASC;AAzDM,+CAAoC"}

package/dist/helpers/proposal-contract.js

@@ -0,0 +1,95 @@
+export const formProposalProtocol = () => 1;
+/** Data-only authoring and runtime contract for input proposal confirmation. */
+const safeName = value => typeof value === 'string' && /^[A-Za-z0-9][\w.:-]*$/.test(value);
+const plain = value => !!value && typeof value === 'object' && !Array.isArray(value) && [Object.prototype, null].includes(Object.getPrototypeOf(value));
+const string = value => typeof value === 'string' && !!value.trim();
+const fail = message => { throw new Error('FORM proposal ' + message); };
+export function validateProposalData(value, seen = new Set()) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean' || typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (!value || typeof value !== 'object' || seen.has(value) || !Array.isArray(value) && !plain(value))
+        fail('binding must be finite, acyclic JSON data');
+    seen.add(value);
+    const array = Array.isArray(value), keys = Reflect.ownKeys(value);
+    for (const key of keys) {
+        const property = Object.getOwnPropertyDescriptor(value, key);
+        if (typeof key !== 'string' || !Object.hasOwn(property, 'value') || !property.enumerable && !(array && key === 'length'))
+            fail('must contain only enumerable JSON data properties');
+        if (array && key === 'length')
+            continue;
+        if (['__proto__', 'prototype', 'constructor'].includes(key) || array && !/^(0|[1-9]\d*)$/.test(key))
+            fail('binding contains an unsafe key');
+        validateProposalData(property.value, seen);
+    }
+    if (array && keys.length !== value.length + 1)
+        fail('binding cannot contain array holes');
+    seen.delete(value);
+    return value;
+}
+const confirmationKeys = ['question', 'question_es', 'binding', 'words', 'interrupts', 'no_keys', 'clarifications', 'on_declined'];
+function confirmation(value, required) {
+    if (required && !string(value.question))
+        fail('needs a nonempty question');
+    for (const key of ['question', 'question_es'])
+        if (value[key] !== undefined && !string(value[key]))
+            fail(key + ' must be nonempty text');
+    if (value.on_declined !== undefined && !safeName(value.on_declined))
+        fail('on_declined needs a static worker id');
+    for (const key of ['words', 'no_keys', 'clarifications'])
+        if (value[key] !== undefined && (!Array.isArray(value[key]) || !value[key].every(string)))
+            fail(key + ' must be an array of nonempty words');
+    if (value.interrupts !== undefined) {
+        if (!Array.isArray(value.interrupts))
+            fail('interrupts must be an array');
+        const keys = new Set();
+        for (const event of value.interrupts) {
+            if (!plain(event) || Object.keys(event).some(k => !['key', 'words', 'flow', 'exact'].includes(k)) || !safeName(event.key) || keys.has(event.key) || !safeName(event.flow) || !Array.isArray(event.words) || !event.words.length || !event.words.every(string) || event.exact !== undefined && typeof event.exact !== 'boolean')
+                fail('invalid interrupt declaration');
+            keys.add(event.key);
+        }
+    }
+    if (value.binding !== undefined)
+        validateProposalData(value.binding);
+}
+export function validateFormProposalPolicy(value) {
+    validateProposalData(value);
+    if (!plain(value) || Object.keys(value).some(key => !['prepare', 'origins', 'when', 'unless', ...confirmationKeys].includes(key)))
+        fail('invalid input policy');
+    if (value.prepare !== undefined && !safeName(value.prepare))
+        fail('prepare needs a static worker id');
+    if (!value.prepare && !string(value.question))
+        fail('policy needs a prepare worker or question');
+    if (value.origins !== undefined && (!Array.isArray(value.origins) || !value.origins.length || new Set(value.origins).size !== value.origins.length || !value.origins.every(origin => ['activation', 'answer'].includes(origin))))
+        fail('invalid origins');
+    const path = key => typeof key === 'string' && key.split('.').every(part => /^[A-Za-z_$][\w$-]*$/.test(part) && !['__proto__', 'prototype', 'constructor'].includes(part));
+    const scalar = item => item === null || typeof item === 'string' || typeof item === 'boolean' || typeof item === 'number' && Number.isFinite(item);
+    if (value.when !== undefined && (!plain(value.when) || Object.entries(value.when).some(([key, wanted]) => !path(key) || !(Array.isArray(wanted) ? wanted.length && wanted.every(scalar) : scalar(wanted)))))
+        fail('when must map safe paths to scalar conditions or nonempty scalar arrays');
+    if (value.unless !== undefined && (!Array.isArray(value.unless) || !value.unless.every(path)))
+        fail('unless must be an array of safe paths');
+    confirmation(value, false);
+    return structuredClone(value);
+}
+export function validateFormProposalDescriptor(value) {
+    validateProposalData(value);
+    if (!plain(value) || Object.keys(value).some(key => !confirmationKeys.includes(key)))
+        fail('invalid decision descriptor');
+    confirmation(value, true);
+    return structuredClone(value);
+}
+/** Keep policy selectors out of the runtime decision descriptor; null is an explicit opt-out. */
+export function formProposalDescriptor(policy, prepared = undefined) {
+    if (!policy)
+        return null;
+    validateFormProposalPolicy(policy);
+    if (policy.prepare && prepared === undefined)
+        fail('prepare must explicitly return a descriptor or null');
+    if (prepared === null)
+        return null;
+    if (prepared !== undefined)
+        validateProposalData(prepared);
+    if (prepared !== undefined && (!prepared || typeof prepared !== 'object' || Array.isArray(prepared)))
+        fail('prepare must return a descriptor or null');
+    const base = Object.fromEntries(confirmationKeys.filter(key => policy[key] !== undefined).map(key => [key, policy[key]]));
+    return validateFormProposalDescriptor({ ...base, ...prepared });
+}

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

@@ -1 +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"}
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../src/host/capabilities.js"],"names":[],"mappings":"AAYA,8FAA8F;AAC9F,0FASC;AAED,2FAA2F;AAC3F,iFAKC;AAED,gHAAgH;AAChH,mFA6BC;AA7DD,kGAAkG;AAClG;IACG,uDAMC;IAHE,aAA2C;IAC3C,YAA0B;IAC1B,gBAAkC;CAEvC"}

package/dist/host/capabilities.js

@@ -1,3 +1,4 @@
+import { INPUT_PROPOSALS_REQUIREMENT } from '../forms/proposal-runtime.js';
 /** Declarative flow admission. No engine imports, I/O, or implicit host capability activation. */
 export class JSFEHostCapabilityError extends Error {
     constructor(flowId, capability, reason) {
@@ -40,6 +41,11 @@ export function assertFlowHostCapabilities(flows, capabilities = {}) {
     for (const flow of flows) {
         const requirements = normalizeHostRequirements(flow?.variables?.contract?.value?.requires, flow?.id);
         for (const capability of requirements) {
+            // Intrinsic runtime support, not a host option or an implicit host permission.
+            if (capability === INPUT_PROPOSALS_REQUIREMENT)
+                continue;
+            if (capability.startsWith('jsfe:'))
+                throw new JSFEHostCapabilityError(flow?.id, capability, 'unsupported intrinsic runtime contract');
             if (!capabilities || typeof capabilities !== 'object' || Array.isArray(capabilities)) {
                 throw new JSFEHostCapabilityError(flow?.id, capability, 'explicit host capabilities must be an object');
             }

package/dist/host/flow-recovery.d.ts

@@ -0,0 +1,19 @@
+/** @returns {FlowRecovery} */
+export function validateFlowRecovery(value: any): FlowRecovery;
+/** Undefined means historical behavior; null explicitly clears a completed task's handoff. */
+export function flowHandoffInfo(result: any): {
+    flow: any;
+    reason: string;
+    kind: string;
+    recovery: FlowRecovery;
+} | null | undefined;
+/** Instructions belong to JSFE; the host only composes this explicit, consume-once note. */
+export function renderFlowRecovery(handoff: any): string | undefined;
+export type FlowRecovery = {
+    version: 1;
+    mode: "resume" | "restart" | "hold" | "none";
+    reason: string;
+    form?: string;
+    flow?: string;
+};
+//# sourceMappingURL=flow-recovery.d.ts.map

package/dist/host/flow-recovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-recovery.d.ts","sourceRoot":"","sources":["../../src/host/flow-recovery.js"],"names":[],"mappings":"AAIA,8BAA8B;AAC9B,kDADc,YAAY,CAMzB;AACD,8FAA8F;AAC9F;;;;;qBAKC;AACD,4FAA4F;AAC5F,qEAWC;2BA7Ba;IAAC,OAAO,EAAC,CAAC,CAAC;IAAA,IAAI,EAAC,QAAQ,GAAC,SAAS,GAAC,MAAM,GAAC,MAAM,CAAC;IAAA,MAAM,EAAC,MAAM,CAAC;IAAA,IAAI,CAAC,EAAC,MAAM,CAAC;IAAA,IAAI,CAAC,EAAC,MAAM,CAAA;CAAC"}