@happyvertical/smrt-ui 0.43.4 → 0.43.6

package/dist/components/forms/control-interaction.js

@@ -5,18 +5,152 @@
  * DOM. Controls register serializable metadata plus small imperative handles;
  * adapters translate voice/chat/tutorial requests into commands.
  */
+import { untrack } from 'svelte';
+const localGestureBatchExecutors = new WeakMap();
+// Intentionally module-private: enumerable so transparent object-spread
+// registry adapters retain the same one-shot local-gesture proof path.
+const localGestureBatchExecutor = Symbol('smrt.localGestureBatchExecutor');
+const consumedFallbackGestureEvents = new WeakMap();
+const eventIsTrustedGetter = typeof Event === 'undefined'
+    ? undefined
+    : Object.getOwnPropertyDescriptor(Event.prototype, 'isTrusted')?.get;
+const eventPhaseGetter = typeof Event === 'undefined'
+    ? undefined
+    : Object.getOwnPropertyDescriptor(Event.prototype, 'eventPhase')?.get;
+function nativeEventState(event) {
+    const ownIsTrusted = Object.getOwnPropertyDescriptor(event, 'isTrusted');
+    if (!eventPhaseGetter ||
+        Object.hasOwn(event, 'eventPhase') ||
+        (eventIsTrustedGetter && ownIsTrusted) ||
+        (!eventIsTrustedGetter &&
+            (!ownIsTrusted || ownIsTrusted.configurable || ownIsTrusted.writable))) {
+        return undefined;
+    }
+    try {
+        return {
+            isTrusted: eventIsTrustedGetter
+                ? Boolean(eventIsTrustedGetter.call(event))
+                : Boolean(ownIsTrusted && 'get' in ownIsTrusted
+                    ? ownIsTrusted.get?.call(event)
+                    : ownIsTrusted?.value),
+            eventPhase: Number(eventPhaseGetter.call(event)),
+        };
+    }
+    catch {
+        // Native prototype getters reject plain objects and incompatible receivers.
+        return undefined;
+    }
+}
+function cloneFailureResult(command) {
+    let action = 'stage';
+    let identity = { formId: '', controlId: '' };
+    try {
+        action = command.action;
+    }
+    catch {
+        // A hostile accessor must not turn clone rejection into a thrown error.
+    }
+    try {
+        const source = command.identity;
+        identity = {
+            formId: source.formId,
+            controlId: source.controlId,
+            ...(source.subject
+                ? {
+                    subject: {
+                        type: source.subject.type,
+                        id: source.subject.id,
+                        ...(source.subject.label === undefined
+                            ? {}
+                            : { label: source.subject.label }),
+                    },
+                }
+                : {}),
+        };
+    }
+    catch {
+        // Preserve the structured failure shape without retaining caller aliases.
+    }
+    return {
+        ok: false,
+        action,
+        identity,
+        reason: 'command_failed',
+    };
+}
+function cloneCommandBatch(commands) {
+    try {
+        return cloneValue(commands);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Execute one value-changing command from a local DOM event handler. */
+export function executeLocalControlCommand(registry, command, event) {
+    return executeLocalControlBatch(registry, [command], event).then((batch) => batch.results[0]);
+}
+/** Execute an ordered best-effort batch from one local DOM event handler. */
+export async function executeLocalControlBatch(registry, commands, event) {
+    const commandSnapshots = cloneCommandBatch(commands);
+    if (!commandSnapshots) {
+        const results = commands.map(cloneFailureResult);
+        return { ok: false, results };
+    }
+    const executor = localGestureBatchExecutors.get(registry) ??
+        registry[localGestureBatchExecutor];
+    if (!executor) {
+        const consumed = consumedFallbackGestureEvents.get(registry) ?? new WeakSet();
+        consumedFallbackGestureEvents.set(registry, consumed);
+        const eventState = nativeEventState(event);
+        if (!eventState?.isTrusted ||
+            eventState.eventPhase === 0 ||
+            consumed.has(event)) {
+            return {
+                ok: false,
+                results: commandSnapshots.map((command) => ({
+                    ok: false,
+                    action: command.action,
+                    identity: cloneValue(command.identity),
+                    reason: 'local_gesture_required',
+                })),
+            };
+        }
+        consumed.add(event);
+        const results = [];
+        for (const command of commandSnapshots) {
+            results.push(await registry.execute(command, {
+                source: 'user',
+                confirmed: true,
+                localGesture: true,
+            }));
+        }
+        return { ok: results.every((entry) => entry.ok), results };
+    }
+    return executor(registry, commandSnapshots, event);
+}
 function identityKey(identity) {
-    const subject = identity.subject
-        ? `${identity.subject.type}:${identity.subject.id}`
-        : '';
-    return `${identity.formId}\u0000${identity.controlId}\u0000${subject}`;
+    return JSON.stringify([
+        identity.formId,
+        identity.controlId,
+        identity.subject?.type ?? null,
+        identity.subject?.id ?? null,
+    ]);
 }
 function isMutation(action) {
-    return ['stage', 'apply', 'clear', 'undo'].includes(action);
+    return ['stage', 'apply', 'discard', 'clear', 'undo'].includes(action);
 }
 function isSecret(registration) {
     return registration.metadata.sensitivity === 'secret';
 }
+function hasValueSetter(registration) {
+    return Boolean(registration.setValueWithContext || registration.setValue);
+}
+function setRegistrationValue(registration, value, context) {
+    return registration.setValueWithContext
+        ? registration.setValueWithContext(value, context)
+        : registration.setValue?.(value);
+}
 function capabilitiesOf(registration) {
     const declared = registration.metadata.capabilities;
     const capabilities = declared ? [...declared] : [];
@@ -33,10 +167,13 @@ function capabilitiesOf(registration) {
             capabilities.push('highlight');
         if (registration.validate)
             capabilities.push('validate');
-        if (registration.setValue && registration.metadata.writable !== false) {
-            capabilities.push('stage', 'apply', 'undo');
+        if (hasValueSetter(registration)) {
+            capabilities.push('discard');
+            if (registration.metadata.writable !== false) {
+                capabilities.push('stage', 'apply', 'undo');
+            }
         }
-        if ((registration.clear || registration.setValue) &&
+        if ((registration.clear || hasValueSetter(registration)) &&
             registration.metadata.writable !== false) {
             capabilities.push('clear');
         }
@@ -44,50 +181,305 @@ function capabilitiesOf(registration) {
     return capabilities.filter((capability) => {
         if (capability === 'read')
             return !isSecret(registration);
-        if (isMutation(capability))
-            return !isSecret(registration);
+        if (capability === 'discard')
+            return true;
+        if (isMutation(capability)) {
+            return (!isSecret(registration) && registration.metadata.writable !== false);
+        }
         return true;
     });
 }
 function redactsValue(registration) {
-    return isSecret(registration) || registration.metadata.readable === false;
+    return (isSecret(registration) ||
+        registration.metadata.sensitivity === 'sensitive' ||
+        registration.metadata.readable === false);
 }
-function defaultPolicy(command, context, snapshot) {
+function defaultPolicy(command, context, snapshot, localGestureConfirmed) {
     if (!isMutation(command.action))
         return { allowed: true };
-    if (snapshot.metadata.sensitivity === 'secret') {
-        return { allowed: false, reason: 'sensitive_control' };
+    if (command.action !== 'discard') {
+        if (snapshot.metadata.sensitivity === 'secret') {
+            return { allowed: false, reason: 'sensitive_control' };
+        }
+        if (snapshot.metadata.writable === false) {
+            return { allowed: false, reason: 'control_not_writable' };
+        }
+        if (snapshot.state.disabled || snapshot.state.readonly) {
+            return { allowed: false, reason: 'control_not_editable' };
+        }
     }
-    if (snapshot.metadata.writable === false) {
-        return { allowed: false, reason: 'control_not_writable' };
+    if (context.source === 'agent' && command.action !== 'stage') {
+        return { allowed: false, reason: 'human_confirmation_required' };
     }
-    if (snapshot.state.disabled || snapshot.state.readonly) {
-        return { allowed: false, reason: 'control_not_editable' };
+    if (['apply', 'discard', 'clear', 'undo'].includes(command.action) &&
+        !localGestureConfirmed) {
+        return { allowed: false, reason: 'local_gesture_required' };
     }
-    if (context.source === 'agent' &&
-        command.action !== 'stage' &&
-        !context.confirmed) {
+    if (command.action !== 'stage' && !context.confirmed) {
         return { allowed: false, reason: 'consent_required' };
     }
     return { allowed: true };
 }
+function cloneValue(value) {
+    try {
+        return structuredClone(value);
+    }
+    catch {
+        if (value === undefined)
+            return value;
+        const serialized = JSON.stringify(value, (_key, candidate) => {
+            if (typeof candidate === 'function' ||
+                typeof candidate === 'symbol' ||
+                typeof candidate === 'bigint') {
+                throw new DOMException('Value is not cloneable', 'DataCloneError');
+            }
+            return candidate;
+        });
+        if (serialized === undefined) {
+            throw new DOMException('Value is not cloneable', 'DataCloneError');
+        }
+        return JSON.parse(serialized);
+    }
+}
+function clonePublicValue(value) {
+    try {
+        return cloneValue(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+function valuesEqual(left, right) {
+    if (Object.is(left, right))
+        return true;
+    try {
+        return JSON.stringify(left) === JSON.stringify(right);
+    }
+    catch {
+        return false;
+    }
+}
+function userEditSuperseded(registration, previousUserEdit) {
+    if (!previousUserEdit)
+        return false;
+    const currentUserEdit = registration.getUserEditSnapshot?.();
+    return (currentUserEdit !== undefined &&
+        currentUserEdit.revision !== previousUserEdit.revision);
+}
+async function restoreRegistrationValue(registration, previousValue, previousUserEdit, invokeExtension) {
+    let observedUserEdit = cloneValue(registration.getUserEditSnapshot?.()) ?? null;
+    let value = previousUserEdit &&
+        observedUserEdit &&
+        observedUserEdit.revision !== previousUserEdit.revision
+        ? cloneValue(observedUserEdit.value)
+        : previousValue;
+    for (let attempt = 0; attempt < 8; attempt += 1) {
+        if (registration.restoreValue) {
+            await invokeExtension((context) => registration.restoreValue?.(value, context));
+        }
+        else {
+            await invokeExtension((context) => setRegistrationValue(registration, value, context));
+        }
+        const latestUserEdit = cloneValue(registration.getUserEditSnapshot?.()) ?? null;
+        if (!observedUserEdit ||
+            !latestUserEdit ||
+            latestUserEdit.revision === observedUserEdit.revision) {
+            return;
+        }
+        observedUserEdit = latestUserEdit;
+        value = cloneValue(latestUserEdit.value);
+        if (attempt === 7) {
+            // The bounded replay just observed a newer human value after the final
+            // restorer completed. Hand that value to the control once more without
+            // retrying. Keep using the infallible restoration path when one was
+            // supplied: the ordinary setter may be the fallible workflow that
+            // triggered rollback in the first place.
+            if (registration.restoreValue) {
+                await invokeExtension((context) => registration.restoreValue?.(value, context));
+            }
+            else if (hasValueSetter(registration)) {
+                await invokeExtension((context) => setRegistrationValue(registration, value, context));
+            }
+            return;
+        }
+    }
+}
+function redactedFailureReason(reason) {
+    return [
+        'stale_revision',
+        'staged_value_stale',
+        'no_staged_value',
+        'staged_value_invalid',
+        'staged_value_rejected',
+        'nothing_to_undo',
+        'sensitive_control',
+    ].includes(reason)
+        ? reason
+        : 'command_failed';
+}
+async function validateProposedValue(registration, value, context) {
+    if (!registration.validateValue)
+        return {};
+    // Validators are untrusted extension points. Never expose the registry's
+    // stored proposal or the candidate that will later be passed to the setter.
+    const validation = await registration.validateValue(cloneValue(value), context);
+    if (typeof validation === 'boolean')
+        return { valid: validation };
+    if (typeof validation === 'string') {
+        return { valid: false, validationMessage: validation };
+    }
+    return {
+        valid: validation.valid,
+        validationMessage: validation.message,
+    };
+}
 /** Create an isolated registry; apps choose where and how it is exposed. */
 export function createControlInteractionRegistry(options = {}) {
     const registrations = new Map();
+    const registrationGenerations = new Map();
     const staged = new Map();
     const undo = new Map();
+    const userEdits = new Map();
+    const registrationBaselines = new WeakMap();
+    const activeValueMutations = new Map();
     const listeners = new Set();
+    const now = options.now ?? Date.now;
+    // The context itself is never authority. This private, one-use grant is
+    // object-identity bound to the exact command handed to an adapter, retains a
+    // private immutable snapshot to detect in-place substitution, and is also
+    // bound to the registration generation present during the gesture.
+    const localConfirmationGrants = new WeakMap();
+    const internallyQueuedContexts = new WeakSet();
+    const consumedLocalGestureEvents = new WeakSet();
+    const mutationQueues = new Map();
+    const synchronousExtensionDepth = new Map();
+    let stagedRevision = 0;
+    const editAwareRegistration = (key, registration) => ({
+        ...registration,
+        getUserEditSnapshot: () => registration.getUserEditSnapshot?.() ??
+            userEdits.get(key) ?? {
+            revision: 0,
+            value: registration.getValue?.(),
+        },
+    });
+    const invokeExtension = (key, invoke) => {
+        synchronousExtensionDepth.set(key, (synchronousExtensionDepth.get(key) ?? 0) + 1);
+        const releaseDepth = (depths) => {
+            const remaining = (depths.get(key) ?? 1) - 1;
+            if (remaining === 0) {
+                depths.delete(key);
+            }
+            else {
+                depths.set(key, remaining);
+            }
+        };
+        const extensionContext = {
+            execute(command, context = { source: 'agent' }) {
+                if (isMutation(command.action) &&
+                    identityKey(command.identity) === key) {
+                    const registration = registrations.get(key);
+                    return Promise.resolve(result(command, false, registration, registration && redactsValue(registration)
+                        ? 'command_failed'
+                        : 'reentrant_mutation'));
+                }
+                return registry.execute(command, context);
+            },
+        };
+        let returned;
+        try {
+            returned = invoke(extensionContext);
+        }
+        catch (error) {
+            releaseDepth(synchronousExtensionDepth);
+            throw error;
+        }
+        releaseDepth(synchronousExtensionDepth);
+        return returned;
+    };
+    const reconcileSupersededRegistration = async (key, generation, previousValue) => {
+        const current = registrations.get(key);
+        const currentGeneration = registrationGenerations.get(key);
+        if (!current || !currentGeneration || currentGeneration === generation) {
+            return false;
+        }
+        const currentWithEdits = editAwareRegistration(key, current);
+        const baseline = registrationBaselines.get(currentGeneration) ?? {
+            value: previousValue,
+            userEdit: { revision: 0, value: cloneValue(previousValue) },
+        };
+        await restoreRegistrationValue(currentWithEdits, cloneValue(baseline.value), cloneValue(baseline.userEdit), (invoke) => invokeExtension(key, invoke));
+        return true;
+    };
+    const enqueueMutation = (key, operation) => {
+        const previous = mutationQueues.get(key) ?? Promise.resolve();
+        const pending = previous.catch(() => undefined).then(operation);
+        const settled = pending.then(() => undefined, () => undefined);
+        mutationQueues.set(key, settled);
+        void settled.finally(() => {
+            if (mutationQueues.get(key) === settled)
+                mutationQueues.delete(key);
+        });
+        return pending;
+    };
+    const invokeTrackedValueMutation = async (key, registration, generation, previousValue, previousUserEdit, invoke) => {
+        const activeMutation = {
+            registration,
+            generation,
+            previousValue: cloneValue(previousValue),
+            immediateValue: cloneValue(previousValue),
+            previousUserEdit: cloneValue(previousUserEdit),
+        };
+        try {
+            activeValueMutations.set(key, activeMutation);
+            const pending = invokeExtension(key, invoke);
+            activeMutation.immediateValue = cloneValue(registration.getValue?.());
+            return await pending;
+        }
+        finally {
+            if (activeValueMutations.get(key) === activeMutation) {
+                activeValueMutations.delete(key);
+            }
+        }
+    };
     const emit = (event) => {
-        const next = { ...event, timestamp: Date.now() };
-        for (const listener of listeners)
-            listener(next);
+        const next = { ...event, timestamp: now() };
+        for (const listener of listeners) {
+            try {
+                listener(cloneValue(next));
+            }
+            catch {
+                // Observers cannot change a command's committed result or registry state.
+            }
+        }
     };
     const snapshotOf = (registration) => {
         const key = identityKey(registration.identity);
         const redacted = redactsValue(registration);
-        const hasStaged = staged.has(key);
+        const stagedEntry = staged.get(key);
+        const stale = stagedEntry
+            ? !valuesEqual(stagedEntry.baseValue, registration.getValue?.())
+            : false;
+        const runtimeState = registration.getState?.();
+        const publicStaged = stagedEntry &&
+            !isSecret(registration) &&
+            registration.metadata.writable !== false
+            ? {
+                value: redacted ? undefined : cloneValue(stagedEntry.value),
+                valueRedacted: redacted,
+                provenance: { ...stagedEntry.provenance },
+                stagedAt: stagedEntry.stagedAt,
+                revision: stagedEntry.revision,
+                stale,
+                valid: stagedEntry.valid,
+                validationMessage: redacted
+                    ? undefined
+                    : stagedEntry.validationMessage,
+            }
+            : undefined;
+        const rawValue = redacted ? undefined : registration.getValue?.();
+        const publicValue = redacted ? undefined : clonePublicValue(rawValue);
         return {
-            identity: { ...registration.identity },
+            identity: cloneValue(registration.identity),
             metadata: {
                 ...registration.metadata,
                 capabilities: capabilitiesOf(registration),
@@ -99,32 +491,81 @@ export function createControlInteractionRegistry(options = {}) {
                 })),
             },
             state: {
-                ...registration.getState?.(),
-                value: redacted ? undefined : registration.getValue?.(),
-                valueRedacted: redacted,
-                stagedValue: hasStaged && !redacted ? staged.get(key) : undefined,
-                stagedValueRedacted: hasStaged ? redacted : undefined,
+                ...runtimeState,
+                validationMessage: redacted
+                    ? undefined
+                    : runtimeState?.validationMessage,
+                value: publicValue,
+                valueRedacted: redacted || (rawValue !== undefined && publicValue === undefined),
+                ...(publicStaged
+                    ? {
+                        stagedValue: publicStaged.value,
+                        stagedValueRedacted: publicStaged.valueRedacted,
+                        staged: publicStaged,
+                    }
+                    : {}),
             },
         };
     };
-    const result = (command, ok, registration, reason) => ({
-        ok,
-        action: command.action,
-        identity: { ...command.identity },
-        snapshot: registration ? snapshotOf(registration) : undefined,
-        reason,
-    });
-    return {
+    const result = (command, ok, registration, reason) => {
+        let snapshot;
+        try {
+            snapshot = registration ? snapshotOf(registration) : undefined;
+        }
+        catch {
+            // A broken control reader must not prevent a structured command result.
+        }
+        return {
+            ok,
+            action: command.action,
+            identity: cloneValue(command.identity),
+            snapshot,
+            reason,
+        };
+    };
+    const registry = {
         register(registration) {
             const key = identityKey(registration.identity);
+            const generation = {};
+            // Capture synchronously so an already-released superseded setter cannot
+            // overwrite the replacement generation before its baseline is recorded.
+            // `untrack` keeps this read out of a caller's reactive registration effect.
+            untrack(() => {
+                try {
+                    const currentValue = cloneValue(registration.getValue?.());
+                    const activeMutation = activeValueMutations.get(key);
+                    const userEdit = cloneValue(registration.getUserEditSnapshot?.() ?? userEdits.get(key));
+                    const newerUserEdit = activeMutation &&
+                        userEdit &&
+                        (!activeMutation.previousUserEdit ||
+                            userEdit.revision !== activeMutation.previousUserEdit.revision);
+                    const value = activeMutation &&
+                        registrationGenerations.get(key) === activeMutation.generation &&
+                        (registration === activeMutation.registration ||
+                            valuesEqual(currentValue, activeMutation.immediateValue)) &&
+                        !newerUserEdit
+                        ? cloneValue(activeMutation.previousValue)
+                        : currentValue;
+                    registrationBaselines.set(generation, {
+                        value,
+                        userEdit: userEdit ?? { revision: 0, value: cloneValue(value) },
+                    });
+                }
+                catch {
+                    // A broken reader is handled by command execution, not registration.
+                }
+            });
             registrations.set(key, registration);
+            registrationGenerations.set(key, generation);
             emit({ type: 'registered', identity: registration.identity });
             return () => {
-                if (registrations.get(key) !== registration)
+                if (registrationGenerations.get(key) !== generation)
                     return;
                 registrations.delete(key);
+                registrationGenerations.delete(key);
                 staged.delete(key);
                 undo.delete(key);
+                userEdits.delete(key);
                 emit({ type: 'unregistered', identity: registration.identity });
             };
         },
@@ -132,10 +573,23 @@ export function createControlInteractionRegistry(options = {}) {
             const key = identityKey(identity);
             if (!registrations.delete(key))
                 return;
+            registrationGenerations.delete(key);
             staged.delete(key);
             undo.delete(key);
+            userEdits.delete(key);
             emit({ type: 'unregistered', identity });
         },
+        recordUserEdit(identity) {
+            const key = identityKey(identity);
+            const registration = registrations.get(key);
+            if (!registration)
+                return;
+            const previous = userEdits.get(key);
+            userEdits.set(key, {
+                revision: (previous?.revision ?? 0) + 1,
+                value: cloneValue(registration.getValue?.()),
+            });
+        },
         list(formId) {
             return [...registrations.values()]
                 .filter((registration) => formId ? registration.identity.formId === formId : true)
@@ -145,37 +599,160 @@ export function createControlInteractionRegistry(options = {}) {
             const registration = registrations.get(identityKey(identity));
             return registration ? snapshotOf(registration) : undefined;
         },
+        refresh(formId) {
+            for (const registration of registrations.values()) {
+                if (formId && registration.identity.formId !== formId)
+                    continue;
+                emit({ type: 'refreshed', identity: registration.identity });
+            }
+        },
         async execute(command, context = { source: 'user', confirmed: true }) {
+            const suppliedCommand = command;
+            const localGrant = localConfirmationGrants.get(context);
+            if (localGrant)
+                localConfirmationGrants.delete(context);
+            if (!internallyQueuedContexts.has(context)) {
+                try {
+                    command = cloneValue(command);
+                }
+                catch {
+                    return cloneFailureResult(command);
+                }
+            }
             const key = identityKey(command.identity);
+            if (isMutation(command.action) &&
+                (synchronousExtensionDepth.get(key) ?? 0) > 0) {
+                const registration = registrations.get(key);
+                return result(command, false, registration, registration && redactsValue(registration)
+                    ? 'command_failed'
+                    : 'reentrant_mutation');
+            }
+            const localGestureConfirmed = Boolean(localGrant &&
+                localGrant.command === suppliedCommand &&
+                valuesEqual(localGrant.snapshot, command) &&
+                localGrant.generation === registrationGenerations.get(key));
+            if (isMutation(command.action) &&
+                !internallyQueuedContexts.has(context)) {
+                const queuedContext = { ...context };
+                internallyQueuedContexts.add(queuedContext);
+                const commandSnapshot = command;
+                if (localGestureConfirmed) {
+                    localConfirmationGrants.set(queuedContext, {
+                        command: commandSnapshot,
+                        snapshot: cloneValue(commandSnapshot),
+                        generation: localGrant?.generation,
+                    });
+                }
+                return await enqueueMutation(key, () => this.execute(commandSnapshot, queuedContext));
+            }
             const registration = registrations.get(key);
             if (!registration)
                 return result(command, false, undefined, 'not_found');
-            const snapshot = snapshotOf(registration);
-            const policyDecision = await (options.policy ?? defaultPolicy)(command, context, snapshot);
-            if (!policyDecision.allowed) {
-                const denied = result(command, false, registration, policyDecision.reason ?? 'denied');
-                emit({
-                    type: 'command',
-                    identity: command.identity,
-                    command,
-                    context,
-                    result: denied,
-                });
-                return denied;
-            }
-            const capabilities = capabilitiesOf(registration);
-            if (!capabilities.includes(command.action)) {
-                const unsupported = result(command, false, registration, 'unsupported');
-                emit({
-                    type: 'command',
-                    identity: command.identity,
-                    command,
-                    context,
-                    result: unsupported,
-                });
-                return unsupported;
-            }
+            const generation = registrationGenerations.get(key);
+            if (!generation)
+                return result(command, false, undefined, 'not_found');
+            const registrationWithEdits = editAwareRegistration(key, registration);
+            const restoreMutationValue = async (previousValue, previousUserEdit) => {
+                if (await reconcileSupersededRegistration(key, generation, previousValue)) {
+                    return;
+                }
+                await restoreRegistrationValue(registrationWithEdits, previousValue, previousUserEdit, (invoke) => invokeExtension(key, invoke));
+            };
+            let publicCommand = redactsValue(registration) &&
+                (command.action === 'stage' || command.action === 'apply')
+                ? cloneValue({ ...command, value: undefined })
+                : cloneValue(command);
+            const publicContext = {
+                source: context.source,
+                confirmed: context.confirmed,
+                localGesture: localGestureConfirmed,
+                actorId: context.actorId,
+                sessionId: context.sessionId,
+            };
+            const customPolicy = options.policy;
             try {
+                let snapshot = snapshotOf(registration);
+                let preparedStageValue;
+                let preparedStageBaseValue;
+                const commandUserEditSnapshot = command.action === 'apply' ||
+                    command.action === 'clear' ||
+                    command.action === 'undo'
+                    ? (cloneValue(registrationWithEdits.getUserEditSnapshot?.()) ??
+                        null)
+                    : null;
+                let invariantDecision = defaultPolicy(command, publicContext, snapshot, publicContext.localGesture === true);
+                let policyDecision = invariantDecision;
+                if (invariantDecision.allowed && command.action === 'stage') {
+                    // A control may resolve a proposal relative to its current value (for
+                    // example, append-mode textareas). Custom policy must inspect the
+                    // exact resolved value that will be staged. If a human changes the
+                    // control while policy awaits, retry against the new stable base.
+                    for (let attempt = 0; attempt < 8; attempt += 1) {
+                        preparedStageBaseValue = cloneValue(registration.getValue?.());
+                        preparedStageValue = cloneValue(registration.prepareValue
+                            ? invokeExtension(key, () => registration.prepareValue?.(command.value))
+                            : command.value);
+                        snapshot = snapshotOf(registration);
+                        publicCommand = redactsValue(registration)
+                            ? cloneValue({ ...command, value: undefined })
+                            : cloneValue({ ...command, value: preparedStageValue });
+                        policyDecision = customPolicy
+                            ? await invokeExtension(key, (extensionContext) => customPolicy(cloneValue(publicCommand), cloneValue(publicContext), cloneValue(snapshot), extensionContext))
+                            : invariantDecision;
+                        if (registrationGenerations.get(key) !== generation) {
+                            throw new Error('staged_value_stale');
+                        }
+                        invariantDecision = defaultPolicy(command, publicContext, snapshotOf(registration), publicContext.localGesture === true);
+                        if (!invariantDecision.allowed) {
+                            throw new Error(invariantDecision.reason ?? 'denied');
+                        }
+                        if (valuesEqual(preparedStageBaseValue, registration.getValue?.())) {
+                            break;
+                        }
+                        if (attempt === 7)
+                            throw new Error('staged_value_stale');
+                    }
+                }
+                else if (invariantDecision.allowed && customPolicy) {
+                    policyDecision = await invokeExtension(key, (extensionContext) => customPolicy(cloneValue(publicCommand), cloneValue(publicContext), cloneValue(snapshot), extensionContext));
+                }
+                if (registrationGenerations.get(key) !== generation) {
+                    throw new Error('staged_value_stale');
+                }
+                if (commandUserEditSnapshot &&
+                    userEditSuperseded(registrationWithEdits, commandUserEditSnapshot)) {
+                    throw new Error('staged_value_stale');
+                }
+                const postPolicyInvariant = defaultPolicy(command, publicContext, snapshotOf(registration), publicContext.localGesture === true);
+                if (!postPolicyInvariant.allowed) {
+                    throw new Error(postPolicyInvariant.reason ?? 'denied');
+                }
+                if (!policyDecision.allowed) {
+                    const denialReason = redactsValue(registration)
+                        ? redactedFailureReason(policyDecision.reason ?? 'denied')
+                        : (policyDecision.reason ?? 'denied');
+                    const denied = result(command, false, registration, denialReason);
+                    emit({
+                        type: 'command',
+                        identity: command.identity,
+                        command: publicCommand,
+                        context: publicContext,
+                        result: denied,
+                    });
+                    return denied;
+                }
+                const capabilities = capabilitiesOf(registration);
+                if (!capabilities.includes(command.action)) {
+                    const unsupported = result(command, false, registration, 'unsupported');
+                    emit({
+                        type: 'command',
+                        identity: command.identity,
+                        command: publicCommand,
+                        context: publicContext,
+                        result: unsupported,
+                    });
+                    return unsupported;
+                }
                 switch (command.action) {
                     case 'focus':
                         await registration.focus?.();
@@ -189,40 +766,287 @@ export function createControlInteractionRegistry(options = {}) {
                     case 'explain':
                         break;
                     case 'validate':
-                        await registration.validate?.();
+                        await invokeExtension(key, (extensionContext) => registration.validate?.(extensionContext));
                         break;
                     case 'stage':
-                        staged.set(key, command.value);
-                        emit({
-                            type: 'staged',
-                            identity: command.identity,
-                            command,
-                            context,
-                        });
-                        break;
+                        stagedRevision += 1;
+                        {
+                            const revision = stagedRevision;
+                            const preparedValue = preparedStageValue;
+                            const entry = {
+                                value: cloneValue(preparedValue),
+                                baseValue: cloneValue(preparedStageBaseValue),
+                                provenance: {
+                                    source: context.source,
+                                    actorId: context.actorId,
+                                    sessionId: context.sessionId,
+                                },
+                                stagedAt: now(),
+                                revision,
+                            };
+                            const previousEntry = staged.get(key);
+                            staged.set(key, entry);
+                            try {
+                                const validation = await invokeExtension(key, (extensionContext) => validateProposedValue(registration, preparedValue, extensionContext));
+                                if (registrationGenerations.get(key) !== generation ||
+                                    staged.get(key) !== entry) {
+                                    throw new Error('stale_revision');
+                                }
+                                const commitSnapshot = {
+                                    identity: cloneValue(registration.identity),
+                                    metadata: {
+                                        ...registration.metadata,
+                                        capabilities: capabilitiesOf(registration),
+                                    },
+                                    state: {
+                                        ...registration.getState?.(),
+                                        valueRedacted: redactsValue(registration),
+                                    },
+                                };
+                                const commitInvariant = defaultPolicy(command, publicContext, commitSnapshot, publicContext.localGesture === true);
+                                if (!commitInvariant.allowed) {
+                                    throw new Error(commitInvariant.reason ?? 'denied');
+                                }
+                                if (!capabilitiesOf(registration).includes('stage')) {
+                                    throw new Error('unsupported');
+                                }
+                                Object.assign(entry, validation);
+                                const stageSnapshot = snapshotOf(registration);
+                                const completed = {
+                                    ok: true,
+                                    action: command.action,
+                                    identity: { ...command.identity },
+                                    snapshot: stageSnapshot,
+                                };
+                                emit({
+                                    type: 'staged',
+                                    identity: command.identity,
+                                    command: publicCommand,
+                                    context: publicContext,
+                                    staged: stageSnapshot.state.staged,
+                                });
+                                emit({
+                                    type: 'command',
+                                    identity: command.identity,
+                                    command: publicCommand,
+                                    context: publicContext,
+                                    result: completed,
+                                });
+                                return completed;
+                            }
+                            catch (error) {
+                                if (staged.get(key) === entry) {
+                                    if (previousEntry) {
+                                        staged.set(key, previousEntry);
+                                    }
+                                    else {
+                                        staged.delete(key);
+                                    }
+                                }
+                                throw error;
+                            }
+                        }
                     case 'apply': {
-                        const nextValue = 'value' in command && command.value !== undefined
-                            ? command.value
-                            : staged.get(key);
-                        if (nextValue === undefined && !staged.has(key)) {
+                        const stagedEntry = staged.get(key);
+                        if (command.revision !== undefined &&
+                            stagedEntry?.revision !== command.revision) {
+                            throw new Error('stale_revision');
+                        }
+                        if (stagedEntry &&
+                            !valuesEqual(stagedEntry.baseValue, registration.getValue?.())) {
+                            throw new Error('staged_value_stale');
+                        }
+                        const suppliedValue = 'value' in command && command.value !== undefined;
+                        const usesExactStagedValue = suppliedValue &&
+                            stagedEntry !== undefined &&
+                            valuesEqual(command.value, stagedEntry.value);
+                        const usesCanonicalReviewValue = suppliedValue &&
+                            stagedEntry !== undefined &&
+                            command.reviewedValueIsCanonical === true &&
+                            localGestureConfirmed;
+                        const nextValue = usesExactStagedValue
+                            ? stagedEntry.value
+                            : usesCanonicalReviewValue
+                                ? registration.prepareReviewedValue
+                                    ? invokeExtension(key, () => registration.prepareReviewedValue?.(command.value))
+                                    : registration.prepareValue
+                                        ? invokeExtension(key, () => registration.prepareValue?.(command.value))
+                                        : command.value
+                                : suppliedValue
+                                    ? registration.prepareValue
+                                        ? invokeExtension(key, () => registration.prepareValue?.(command.value))
+                                        : command.value
+                                    : stagedEntry?.value;
+                        if (nextValue === undefined && !stagedEntry) {
                             throw new Error('no_staged_value');
                         }
+                        const authorizedValue = cloneValue(nextValue);
+                        const proposedValidation = await invokeExtension(key, (extensionContext) => validateProposedValue(registration, authorizedValue, extensionContext));
+                        if (registrationGenerations.get(key) !== generation) {
+                            throw new Error('staged_value_stale');
+                        }
+                        if (commandUserEditSnapshot &&
+                            userEditSuperseded(registrationWithEdits, commandUserEditSnapshot)) {
+                            throw new Error('staged_value_stale');
+                        }
+                        if (stagedEntry &&
+                            (staged.get(key) !== stagedEntry ||
+                                !valuesEqual(stagedEntry.baseValue, registration.getValue?.()))) {
+                            throw new Error('stale_revision');
+                        }
+                        if (proposedValidation.valid === false) {
+                            if (stagedEntry)
+                                Object.assign(stagedEntry, proposedValidation);
+                            throw new Error(redactsValue(registration)
+                                ? 'staged_value_invalid'
+                                : (proposedValidation.validationMessage ??
+                                    'staged_value_invalid'));
+                        }
+                        const preMutationInvariant = defaultPolicy(command, publicContext, snapshotOf(registration), publicContext.localGesture === true);
+                        if (!preMutationInvariant.allowed) {
+                            throw new Error(preMutationInvariant.reason ?? 'denied');
+                        }
+                        const previousValue = cloneValue(registration.getValue?.());
                         const history = undo.get(key) ?? [];
-                        history.push(registration.getValue?.());
+                        const userEditSnapshot = commandUserEditSnapshot;
+                        try {
+                            await invokeTrackedValueMutation(key, registration, generation, previousValue, userEditSnapshot, (extensionContext) => setRegistrationValue(registration, cloneValue(authorizedValue), extensionContext));
+                        }
+                        catch (error) {
+                            try {
+                                await restoreMutationValue(previousValue, userEditSnapshot);
+                            }
+                            catch {
+                                // Preserve the original setter failure for the command result.
+                            }
+                            throw error;
+                        }
+                        if (registrationGenerations.get(key) !== generation ||
+                            userEditSuperseded(registrationWithEdits, userEditSnapshot)) {
+                            await restoreMutationValue(previousValue, userEditSnapshot);
+                            throw new Error('staged_value_stale');
+                        }
+                        const appliedValue = cloneValue(registration.getValue?.());
+                        if (!valuesEqual(appliedValue, authorizedValue)) {
+                            try {
+                                await restoreMutationValue(previousValue, userEditSnapshot);
+                            }
+                            catch {
+                                // Preserve the rejected apply result and retain its proposal.
+                            }
+                            throw new Error('staged_value_rejected');
+                        }
+                        try {
+                            const valid = await invokeExtension(key, (extensionContext) => registration.validate?.(extensionContext));
+                            if (registrationGenerations.get(key) !== generation ||
+                                userEditSuperseded(registrationWithEdits, userEditSnapshot)) {
+                                throw new Error('staged_value_stale');
+                            }
+                            if (!valuesEqual(registration.getValue?.(), appliedValue)) {
+                                throw new Error('staged_value_stale');
+                            }
+                            if (valid === false) {
+                                if (stagedEntry) {
+                                    stagedEntry.valid = false;
+                                    stagedEntry.validationMessage =
+                                        registration.getState?.().validationMessage ??
+                                            'staged_value_invalid';
+                                }
+                                throw new Error('staged_value_invalid');
+                            }
+                        }
+                        catch (error) {
+                            let currentValue;
+                            try {
+                                currentValue = registration.getValue?.();
+                            }
+                            catch {
+                                // A broken reader is reported without attempting a blind overwrite.
+                            }
+                            if (valuesEqual(currentValue, appliedValue)) {
+                                try {
+                                    await restoreMutationValue(previousValue, userEditSnapshot);
+                                }
+                                catch {
+                                    // Preserve the original validation failure for the command result.
+                                }
+                            }
+                            throw error;
+                        }
+                        history.push({
+                            previousValue,
+                            appliedValue,
+                        });
                         undo.set(key, history);
-                        await registration.setValue?.(nextValue);
+                        if (!stagedEntry || staged.get(key) === stagedEntry) {
+                            staged.delete(key);
+                        }
+                        break;
+                    }
+                    case 'discard': {
+                        const stagedEntry = staged.get(key);
+                        if (!stagedEntry)
+                            throw new Error('no_staged_value');
+                        if (command.revision !== undefined &&
+                            stagedEntry.revision !== command.revision) {
+                            throw new Error('stale_revision');
+                        }
                         staged.delete(key);
-                        await registration.validate?.();
                         break;
                     }
                     case 'clear': {
+                        const previousValue = cloneValue(registration.getValue?.());
+                        let clearDecision;
+                        const userEditSnapshot = commandUserEditSnapshot;
+                        try {
+                            const decision = await invokeTrackedValueMutation(key, registration, generation, previousValue, userEditSnapshot, (extensionContext) => registration.clear
+                                ? registration.clear(extensionContext)
+                                : setRegistrationValue(registration, '', extensionContext));
+                            clearDecision =
+                                decision === true
+                                    ? true
+                                    : decision === false
+                                        ? false
+                                        : undefined;
+                        }
+                        catch (error) {
+                            try {
+                                await restoreMutationValue(previousValue, userEditSnapshot);
+                            }
+                            catch {
+                                // Preserve the original clear failure for the command result.
+                            }
+                            throw error;
+                        }
+                        if (registrationGenerations.get(key) !== generation ||
+                            userEditSuperseded(registrationWithEdits, userEditSnapshot)) {
+                            await restoreMutationValue(previousValue, userEditSnapshot);
+                            throw new Error('staged_value_stale');
+                        }
+                        const clearedValue = registration.getValue?.();
+                        const rejected = clearDecision === false ||
+                            (clearDecision !== true &&
+                                valuesEqual(clearedValue, previousValue) &&
+                                previousValue !== '' &&
+                                previousValue !== null &&
+                                previousValue !== undefined &&
+                                previousValue !== false &&
+                                !(Array.isArray(previousValue) && previousValue.length === 0));
+                        if (rejected) {
+                            try {
+                                await restoreMutationValue(previousValue, userEditSnapshot);
+                            }
+                            catch {
+                                // The rejected command still retains its proposal for recovery.
+                            }
+                            throw new Error('staged_value_rejected');
+                        }
                         const history = undo.get(key) ?? [];
-                        history.push(registration.getValue?.());
+                        history.push({
+                            previousValue,
+                            appliedValue: cloneValue(clearedValue),
+                        });
                         undo.set(key, history);
-                        if (registration.clear)
-                            await registration.clear();
-                        else
-                            await registration.setValue?.('');
                         staged.delete(key);
                         break;
                     }
@@ -230,7 +1054,42 @@ export function createControlInteractionRegistry(options = {}) {
                         const history = undo.get(key) ?? [];
                         if (history.length === 0)
                             throw new Error('nothing_to_undo');
-                        await registration.setValue?.(history.pop());
+                        const undoEntry = history.at(-1);
+                        if (!undoEntry)
+                            throw new Error('nothing_to_undo');
+                        const currentValue = cloneValue(registration.getValue?.());
+                        const expectedPreviousValue = cloneValue(undoEntry.previousValue);
+                        const userEditSnapshot = commandUserEditSnapshot;
+                        if (!valuesEqual(currentValue, undoEntry.appliedValue)) {
+                            throw new Error('staged_value_stale');
+                        }
+                        try {
+                            await invokeTrackedValueMutation(key, registration, generation, currentValue, userEditSnapshot, (extensionContext) => setRegistrationValue(registration, cloneValue(expectedPreviousValue), extensionContext));
+                        }
+                        catch (error) {
+                            try {
+                                await restoreMutationValue(currentValue, userEditSnapshot);
+                            }
+                            catch {
+                                // Preserve the original setter failure for the command result.
+                            }
+                            throw error;
+                        }
+                        if (registrationGenerations.get(key) !== generation ||
+                            userEditSuperseded(registrationWithEdits, userEditSnapshot)) {
+                            await restoreMutationValue(currentValue, userEditSnapshot);
+                            throw new Error('staged_value_stale');
+                        }
+                        if (!valuesEqual(registration.getValue?.(), expectedPreviousValue)) {
+                            try {
+                                await restoreMutationValue(currentValue, userEditSnapshot);
+                            }
+                            catch {
+                                // Preserve the rejected undo result while retaining its history.
+                            }
+                            throw new Error('staged_value_rejected');
+                        }
+                        history.pop();
                         undo.set(key, history);
                         break;
                     }
@@ -239,27 +1098,95 @@ export function createControlInteractionRegistry(options = {}) {
                 emit({
                     type: 'command',
                     identity: command.identity,
-                    command,
-                    context,
+                    command: publicCommand,
+                    context: publicContext,
                     result: completed,
                 });
                 return completed;
             }
             catch (error) {
-                const failed = result(command, false, registration, error instanceof Error ? error.message : 'command_failed');
+                const errorReason = error instanceof Error ? error.message : 'command_failed';
+                const failed = result(command, false, registration, redactsValue(registration)
+                    ? redactedFailureReason(errorReason)
+                    : errorReason);
                 emit({
                     type: 'command',
                     identity: command.identity,
-                    command,
-                    context,
+                    command: publicCommand,
+                    context: publicContext,
                     result: failed,
                 });
                 return failed;
             }
         },
+        async executeBatch(commands, context = { source: 'user', confirmed: true }) {
+            const commandSnapshots = cloneCommandBatch(commands);
+            if (!commandSnapshots) {
+                const results = commands.map(cloneFailureResult);
+                return { ok: false, results };
+            }
+            let contextSnapshot;
+            try {
+                contextSnapshot = cloneValue(context);
+            }
+            catch {
+                const results = commandSnapshots.map(cloneFailureResult);
+                return { ok: false, results };
+            }
+            const results = [];
+            for (const command of commandSnapshots) {
+                results.push(await this.execute(command, contextSnapshot));
+            }
+            return { ok: results.every((entry) => entry.ok), results };
+        },
         subscribe(listener) {
             listeners.add(listener);
             return () => listeners.delete(listener);
         },
     };
+    const localGestureExecutor = async (suppliedRegistry, commands, event) => {
+        const eventState = nativeEventState(event);
+        const isLocalGesture = options.isLocalGesture ?? (() => eventState?.isTrusted);
+        if (!eventState ||
+            !isLocalGesture(event) ||
+            eventState.eventPhase === 0 ||
+            consumedLocalGestureEvents.has(event)) {
+            return {
+                ok: false,
+                results: commands.map((command) => result(command, false, registrations.get(identityKey(command.identity)), 'local_gesture_required')),
+            };
+        }
+        consumedLocalGestureEvents.add(event);
+        // Bind the entire already-snapshotted batch to the registration generations
+        // present at gesture validation time. Earlier awaited commands must not be
+        // able to authorize later commands against newly mounted replacements.
+        const gestureGenerations = commands.map((command) => registrationGenerations.get(identityKey(command.identity)));
+        const results = [];
+        for (const [index, command] of commands.entries()) {
+            const context = {
+                source: 'user',
+                confirmed: true,
+            };
+            localConfirmationGrants.set(context, {
+                command,
+                snapshot: cloneValue(command),
+                generation: gestureGenerations[index],
+            });
+            try {
+                results.push(await suppliedRegistry.execute(command, context));
+            }
+            finally {
+                // Adapters may retain context references, but no authority survives the
+                // terminal delegation/denial for this exact command.
+                localConfirmationGrants.delete(context);
+            }
+        }
+        return { ok: results.every((entry) => entry.ok), results };
+    };
+    localGestureBatchExecutors.set(registry, localGestureExecutor);
+    Object.defineProperty(registry, localGestureBatchExecutor, {
+        value: localGestureExecutor,
+        enumerable: true,
+    });
+    return registry;
 }