@unrulysystems/native-motion-core 0.1.0-alpha.0

package/dist/motion-value-driver-port.cjs

@@ -0,0 +1,636 @@
+"use strict";
+// Private, host-free CORE seam for an exact public MotionValue driven by an external runtime
+// (REQ-VALUE-014/015). Implements the direct-public creation brand, binding eligibility, the
+// direct-operation epoch with synchronous public-method order, the token-blind public control
+// slot, transported write/callback application with drain-progress accounting, guarded
+// candidate-cache terminals, and the local-frame transition event port. Native adapters import
+// it only through `internal-driver`.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MotionValueDriverPortUnimplementedError = exports.MOTION_VALUE_DRIVER_PORT_UNIMPLEMENTED = exports.MotionValueDriverPortInvariantError = exports.MOTION_VALUE_DRIVER_PORT_INVARIANT = void 0;
+exports.createDirectPublicMotionValue = createDirectPublicMotionValue;
+exports.isDirectPublicNumericMotionValue = isDirectPublicNumericMotionValue;
+exports.createLocalFrameEventPort = createLocalFrameEventPort;
+exports.createMotionValueDriverPort = createMotionValueDriverPort;
+const constants_1 = require("./config/constants.cjs");
+const motion_value_1 = require("./motion-value.cjs");
+exports.MOTION_VALUE_DRIVER_PORT_INVARIANT = 'NATIVE_MOTION_CORE_MOTION_VALUE_DRIVER_PORT_INVARIANT';
+/** Typed fail-closed refusal for an unusable restored public-control slot. */
+class MotionValueDriverPortInvariantError extends Error {
+    code = exports.MOTION_VALUE_DRIVER_PORT_INVARIANT;
+    invariant;
+    constructor(invariant) {
+        super(`native-motion-core: MotionValue driver-port invariant '${invariant}' was violated ` +
+            '(REQ-VALUE-015)');
+        this.name = 'MotionValueDriverPortInvariantError';
+        this.invariant = invariant;
+    }
+}
+exports.MotionValueDriverPortInvariantError = MotionValueDriverPortInvariantError;
+exports.MOTION_VALUE_DRIVER_PORT_UNIMPLEMENTED = 'NATIVE_MOTION_CORE_MOTION_VALUE_DRIVER_PORT_UNIMPLEMENTED';
+class MotionValueDriverPortUnimplementedError extends Error {
+    code = exports.MOTION_VALUE_DRIVER_PORT_UNIMPLEMENTED;
+    operation;
+    constructor(operation) {
+        super(`native-motion-core: MotionValue driver-port operation '${operation}' is unimplemented ` +
+            '(REQ-VALUE-014/015)');
+        this.name = 'MotionValueDriverPortUnimplementedError';
+        this.operation = operation;
+    }
+}
+exports.MotionValueDriverPortUnimplementedError = MotionValueDriverPortUnimplementedError;
+const DIRECT_PUBLIC_CREATION = new WeakMap();
+function initializerProvenance(initial) {
+    if (typeof initial !== 'number')
+        return { kind: 'ineligible', reason: 'non-number' };
+    if (!Number.isFinite(initial))
+        return { kind: 'ineligible', reason: 'non-finite-number' };
+    return { kind: 'finite-number' };
+}
+/**
+ * The one private direct-public creation seam used by native `useMotionValue`. It returns the exact
+ * graph object and records immutable initializer provenance without widening the public graph API.
+ */
+function createDirectPublicMotionValue(graph, initial) {
+    const value = graph.motionValue(initial);
+    DIRECT_PUBLIC_CREATION.set(value, {
+        kind: 'direct-public',
+        initializer: initializerProvenance(initial),
+    });
+    return value;
+}
+/**
+ * Private mount-time routing predicate for the identity channel. It reads only the immutable
+ * creation brand plus the caller's collector-silent mount snapshot; behavioral eligibility remains
+ * owned by `MotionValueDriverPort.evaluateBindingEligibility` once the canonical port is attached.
+ */
+function isDirectPublicNumericMotionValue(value, currentValue) {
+    const creation = DIRECT_PUBLIC_CREATION.get(value);
+    if (creation?.kind !== 'direct-public' || creation.initializer.kind !== 'finite-number') {
+        return false;
+    }
+    return typeof currentValue === 'number' && Number.isFinite(currentValue);
+}
+function defaultPortState(rawSnapshot, channelId) {
+    return {
+        channelId,
+        rawCurrentValue: rawSnapshot.currentValue,
+        history: rawSnapshot.history,
+        directOperationEpoch: rawSnapshot.directOperationEpoch,
+        authoritativeSequence: rawSnapshot.authoritativeSequence,
+        currentExecutionId: null,
+        executionLease: 0,
+        publicControlSlot: { kind: 'empty' },
+        acceptedWriteSequence: 0,
+        demandedWriteSequence: 0,
+        deliveredEventWatermark: 0,
+        synchronousSnapshotReadCount: 0,
+        outboundOriginCommandCount: 0,
+    };
+}
+/**
+ * Pinned finite-difference velocity (motion-dom `getVelocity`): last two timed samples, delta
+ * clamped to the staleness window, zero for a non-positive delta or a single sample.
+ */
+function finiteDifferenceVelocity(history) {
+    if (history.kind !== 'finite-difference')
+        return 0;
+    const dt = Math.min(history.currentTimestampMs - history.previousTimestampMs, constants_1.MAX_VELOCITY_DELTA_MS);
+    if (dt <= 0)
+        return 0;
+    return ((history.currentValue - history.previousValue) * 1000) / dt;
+}
+class MotionValueDriverPortImpl {
+    value;
+    #impl;
+    #creation;
+    #state;
+    constructor(value, creation, state, initialPublicControlSlotInstallation) {
+        this.value = value;
+        this.#impl = value instanceof motion_value_1.MotionValueImpl ? value : null;
+        this.#creation = creation;
+        // Copy so the caller's serializable record is never mutated through the port.
+        this.#state = { ...state };
+        if (initialPublicControlSlotInstallation !== null) {
+            this.#installSlot(initialPublicControlSlotInstallation);
+        }
+    }
+    /**
+     * Every behavioral operation owns the exact graph-created value (the eligibility law admits
+     * only direct-public identities, which this graph created). A structural duck never reaches
+     * them: fail closed with a typed invariant, never a raw TypeError.
+     */
+    #requireGraphMotionValue() {
+        const impl = this.#impl;
+        if (impl === null) {
+            throw new MotionValueDriverPortInvariantError('value-not-graph-motion-value');
+        }
+        return impl;
+    }
+    /**
+     * The public control slot IS `isAnimating()` (the pinned `value.animation` member): install the
+     * liveness hook whose invocation stops exactly this installation's physical execution. Motion's
+     * stop/jump order — cancellation listeners, then the physical stop, then the slot clear — falls
+     * out of `MotionValueImpl.stop()` running this hook after its notification.
+     */
+    #installSlot(installation) {
+        const impl = this.#requireGraphMotionValue();
+        this.#state.publicControlSlot = {
+            kind: 'installed',
+            controlId: installation.controlId,
+            executionId: installation.executionId,
+        };
+        impl.attachAnimationStopper(() => {
+            installation.stopPhysicalExecution();
+            impl.endAnimation();
+            this.#state.publicControlSlot = { kind: 'empty' };
+        });
+    }
+    observe() {
+        const current = this.#state.rawCurrentValue;
+        const currentValueKind = typeof current !== 'number'
+            ? 'non-number'
+            : Number.isFinite(current)
+                ? 'finite-number'
+                : 'non-finite-number';
+        const observedInitializerProvenance = this.#creation.kind === 'unrecognized'
+            ? 'unrecognized'
+            : this.#creation.initializer.kind === 'finite-number'
+                ? 'finite-number'
+                : this.#creation.initializer.reason;
+        const history = this.#state.history;
+        return {
+            channelId: this.#state.channelId,
+            creationKind: this.#creation.kind,
+            initializerProvenance: observedInitializerProvenance,
+            currentValueKind,
+            cachedCurrentValue: history.kind === 'unavailable' ? null : history.currentValue,
+            cachedPreviousValue: history.kind === 'finite-difference' ? history.previousValue : null,
+            cachedCurrentTimestampMs: history.kind === 'unavailable' ? null : history.currentTimestampMs,
+            cachedPreviousTimestampMs: history.kind === 'finite-difference' ? history.previousTimestampMs : null,
+            directOperationEpoch: this.#state.directOperationEpoch,
+            authoritativeSequence: this.#state.authoritativeSequence,
+            currentExecutionId: this.#state.currentExecutionId,
+            executionLease: this.#state.executionLease,
+            publicControlSlotControlId: this.#state.publicControlSlot.kind === 'empty'
+                ? null
+                : this.#state.publicControlSlot.controlId,
+            publicControlSlotExecutionId: this.#state.publicControlSlot.kind === 'empty'
+                ? null
+                : this.#state.publicControlSlot.executionId,
+            acceptedWriteSequence: this.#state.acceptedWriteSequence,
+            demandedWriteSequence: this.#state.demandedWriteSequence,
+            deliveredEventWatermark: this.#state.deliveredEventWatermark,
+            synchronousSnapshotReadCount: this.#state.synchronousSnapshotReadCount,
+            outboundOriginCommandCount: this.#state.outboundOriginCommandCount,
+        };
+    }
+    evaluateBindingEligibility(currentValue) {
+        if (this.#creation.kind !== 'direct-public') {
+            return { kind: 'ineligible', reason: 'not-direct-public' };
+        }
+        // The initializer brand is immutable: a finite `set` after a non-numeric/non-finite
+        // initializer never upgrades the value (the creation provenance is the law, not the value).
+        if (this.#creation.initializer.kind !== 'finite-number') {
+            return { kind: 'ineligible', reason: 'initializer-not-finite-number' };
+        }
+        if (typeof currentValue !== 'number' || !Number.isFinite(currentValue)) {
+            return { kind: 'ineligible', reason: 'current-not-finite-number' };
+        }
+        return {
+            kind: 'eligible',
+            creationKind: 'direct-public',
+            initializerProvenance: 'finite-number',
+            currentValue,
+        };
+    }
+    beginDirectOperation(operation) {
+        const impl = this.#requireGraphMotionValue();
+        // The epoch advances BEFORE the synchronous public method, so change/cancel/destroy
+        // listeners already observe the new operation epoch (pinned public-method order).
+        this.#state.directOperationEpoch += 1;
+        this.#state.outboundOriginCommandCount += 1;
+        switch (operation.kind) {
+            case 'set':
+                impl.set(operation.value);
+                this.#state.rawCurrentValue = operation.value;
+                break;
+            case 'jump':
+                impl.jump(operation.value);
+                this.#state.rawCurrentValue = operation.value;
+                break;
+            case 'stop':
+                // With an installed slot this routes through its exact stop capability; with a graph
+                // animation through the graph's stopper. Either way the value's own `stop()` order holds.
+                impl.stop();
+                break;
+            case 'destroy':
+                impl.destroy();
+                break;
+            case 'start':
+                // A new execution supersedes the prior one: identify it and roll the lease so the prior
+                // execution's transported samples reject as stale from here on.
+                this.#state.currentExecutionId = operation.executionId;
+                this.#state.executionLease += 1;
+                break;
+            default: {
+                const exhaustive = operation;
+                void exhaustive;
+                throw new MotionValueDriverPortInvariantError('direct-operation-kind-unrecognized');
+            }
+        }
+        return {
+            kind: 'direct-operation-begun',
+            operation: operation.kind,
+            directOperationEpoch: this.#state.directOperationEpoch,
+            outboundOriginCommand: 'required',
+        };
+    }
+    installPublicControlSlot(installation) {
+        this.#installSlot(installation);
+        return {
+            kind: 'public-control-slot-updated',
+            publicControlSlot: this.#state.publicControlSlot,
+            physicalExecution: 'retained',
+        };
+    }
+    clearPublicControlSlotTokenBlind(causedByExecutionId) {
+        // Token-blind law (pinned completion/cancellation continuation): the post-listener slot
+        // clears unconditionally — never matched against the causing execution and NEVER stopping
+        // the retained physical execution, which may keep sampling as an orphan.
+        void causedByExecutionId;
+        const impl = this.#requireGraphMotionValue();
+        this.#state.publicControlSlot = { kind: 'empty' };
+        impl.detachAnimationStopper();
+        return {
+            kind: 'public-control-slot-updated',
+            publicControlSlot: this.#state.publicControlSlot,
+            physicalExecution: 'retained',
+        };
+    }
+    applyTransportedSample(sample, progress) {
+        const impl = this.#requireGraphMotionValue();
+        switch (sample.kind) {
+            case 'generator-sample': {
+                const armedCompletion = sample.completion.kind === 'armed' ? 'retained' : 'not-armed';
+                if (sample.directOperationEpoch < this.#state.directOperationEpoch) {
+                    return {
+                        kind: 'rejected',
+                        reason: 'stale-direct-operation-epoch',
+                        armedCompletion,
+                        originEcho: 'suppressed',
+                    };
+                }
+                if (sample.executionLease < this.#state.executionLease) {
+                    return {
+                        kind: 'rejected',
+                        reason: 'stale-execution-lease',
+                        armedCompletion,
+                        originEcho: 'suppressed',
+                    };
+                }
+                if (sample.writeSequence <= this.#state.acceptedWriteSequence) {
+                    return {
+                        kind: 'rejected',
+                        reason: 'stale-write-sequence',
+                        armedCompletion,
+                        originEcho: 'suppressed',
+                    };
+                }
+                return this.#adoptTransportedWrite(impl, sample.history, sample.writeSequence, sample.authoritativeSequence, {
+                    channelId: this.#state.channelId,
+                    entryKind: 'generator-sample',
+                    executionId: sample.executionId,
+                    deliverySequence: sample.authoritativeSequence,
+                }, progress);
+            }
+            case 'tokenless-task-write': {
+                if (sample.writeSequence <= this.#state.acceptedWriteSequence) {
+                    return {
+                        kind: 'rejected',
+                        reason: 'stale-write-sequence',
+                        armedCompletion: 'not-armed',
+                        originEcho: 'suppressed',
+                    };
+                }
+                return this.#adoptTransportedWrite(impl, sample.history, sample.writeSequence, sample.authoritativeSequence, {
+                    channelId: this.#state.channelId,
+                    entryKind: 'tokenless-task-write',
+                    taskKind: sample.taskKind,
+                    taskSequence: sample.taskSequence,
+                    deliverySequence: sample.authoritativeSequence,
+                }, progress);
+            }
+            case 'tokenless-task-callback': {
+                // Replay suppression precedes progress, cache adoption, and callback dispatch: an
+                // already-delivered event sequence is a pure retransmission and mutates nothing.
+                if (sample.eventSequence <= this.#state.deliveredEventWatermark) {
+                    return {
+                        kind: 'event-replay-rejected',
+                        reason: 'stale-event-sequence',
+                        callbackKind: sample.callbackKind,
+                        callbackDelivery: 'suppressed-replay',
+                        candidateCache: 'unchanged',
+                        progress: 'unchanged',
+                        originEcho: 'suppressed',
+                    };
+                }
+                progress.beginEntry({
+                    channelId: this.#state.channelId,
+                    entryKind: 'tokenless-task-callback',
+                    taskKind: sample.taskKind,
+                    callbackKind: sample.callbackKind,
+                    taskSequence: sample.taskSequence,
+                    deliverySequence: sample.authoritativeSequence,
+                });
+                // The callback event is immutable and always deliverable; only its carried cache
+                // candidate is guarded against the write/operation sequences (pinned delayed-terminal
+                // law — the callback must still observe the newer direct state, never a rewind).
+                let candidateCache;
+                if (sample.candidateDirectOperationEpoch < this.#state.directOperationEpoch) {
+                    candidateCache = 'rejected-stale-direct-operation-epoch';
+                }
+                else if (sample.candidateWriteSequence <= this.#state.acceptedWriteSequence) {
+                    candidateCache = 'rejected-stale-write-sequence';
+                }
+                else {
+                    this.#adoptCandidateCacheSilently(impl, sample.history, sample.candidateWriteSequence);
+                    candidateCache = 'adopted';
+                }
+                this.#state.authoritativeSequence = sample.authoritativeSequence;
+                this.#state.deliveredEventWatermark = sample.eventSequence;
+                progress.finalizeDeliveredEventWatermarkAndRetention(this.#state.channelId, sample.eventSequence);
+                progress.clearEntry();
+                return {
+                    kind: 'callback-delivered',
+                    callbackKind: sample.callbackKind,
+                    callbackDelivery: 'required',
+                    candidateCache,
+                    originEcho: 'suppressed',
+                };
+            }
+            default: {
+                const exhaustive = sample;
+                void exhaustive;
+                throw new MotionValueDriverPortInvariantError('transported-sample-kind-unrecognized');
+            }
+        }
+    }
+    /**
+     * One accepted write entry: adopt cache + ledger positions BEFORE notification (observers read
+     * the adopted state), deliver change, then finalize the delivered watermark. A throwing
+     * observer aborts later observers and derived dirtying but never rolls the adoption back: the
+     * watermark still finalizes exactly once (so a retransmission rejects as stale) and the exact
+     * error rethrows unchanged.
+     */
+    #adoptTransportedWrite(impl, history, writeSequence, authoritativeSequence, entry, progress) {
+        progress.beginEntry(entry);
+        const currentValue = history.currentValue;
+        const changed = currentValue !== this.#state.rawCurrentValue;
+        const hadChangeObservers = impl.hasChangeObservers();
+        const hadDerivedDependents = impl.hasDerivedDependentObserver();
+        this.#state.rawCurrentValue = currentValue;
+        this.#state.history = history;
+        this.#state.acceptedWriteSequence = writeSequence;
+        this.#state.authoritativeSequence = authoritativeSequence;
+        progress.markIrreversibleSubphase('cache-history-adopted');
+        try {
+            // Marked BEFORE delivery: observer delivery is irreversible once begun, so an aborting
+            // observer leaves this subphase — never 'dependent-dirtying-complete' — as the resume point.
+            progress.markIrreversibleSubphase('change-observer-delivered');
+            this.#writeExternalSample(impl, history, changed);
+            progress.markIrreversibleSubphase('dependent-dirtying-complete');
+        }
+        catch (error) {
+            progress.finalizeDeliveredWriteWatermarkAndRetention(this.#state.channelId, writeSequence);
+            progress.clearEntry();
+            throw error;
+        }
+        progress.finalizeDeliveredWriteWatermarkAndRetention(this.#state.channelId, writeSequence);
+        progress.clearEntry();
+        return {
+            kind: 'applied',
+            finiteDifferenceVelocity: finiteDifferenceVelocity(history),
+            changeNotification: changed
+                ? hadChangeObservers
+                    ? 'emitted'
+                    : 'suppressed-no-observer'
+                : 'suppressed-equal-value',
+            derivedDependents: changed && hadDerivedDependents ? 'marked-dirty' : 'unchanged',
+            derivedFrame: changed && hadDerivedDependents ? 'requested' : 'not-requested',
+            originEcho: 'suppressed',
+        };
+    }
+    /**
+     * Guarded candidate-cache adoption (pinned callback/cache split): the terminal's carried
+     * snapshot writes the value and history WITHOUT change notification — publication belongs to
+     * the write entries; the candidate exists so callback-time `get()`/`getVelocity()` need no
+     * synchronous origin read.
+     */
+    #adoptCandidateCacheSilently(impl, history, writeSequence) {
+        this.#state.rawCurrentValue = history.currentValue;
+        this.#state.history = history;
+        this.#state.acceptedWriteSequence = writeSequence;
+        this.#writeExternalSample(impl, history, false);
+    }
+    #writeExternalSample(impl, history, notifyChange) {
+        impl.applyExternalNumericSample(history.currentValue, history.kind === 'finite-difference' ? history.previousValue : undefined, history.currentTimestampMs, history.kind === 'finite-difference' ? history.previousTimestampMs : undefined, notifyChange);
+    }
+    adoptSynchronousSnapshot(snapshot) {
+        const impl = this.#requireGraphMotionValue();
+        // Every explicit snapshot read counts, adopted or rejected (the read itself is the demand).
+        this.#state.synchronousSnapshotReadCount += 1;
+        if (snapshot.directOperationEpoch < this.#state.directOperationEpoch) {
+            return {
+                kind: 'synchronous-snapshot-rejected',
+                reason: 'stale-direct-operation-epoch',
+                callbackDelivery: 'silent',
+                demandedWriteSequence: 'unchanged',
+                publicControlSlot: 'unchanged',
+            };
+        }
+        if (snapshot.authoritativeSequence <= this.#state.authoritativeSequence) {
+            return {
+                kind: 'synchronous-snapshot-rejected',
+                reason: 'stale-authoritative-sequence',
+                callbackDelivery: 'silent',
+                demandedWriteSequence: 'unchanged',
+                publicControlSlot: 'unchanged',
+            };
+        }
+        // Callback-silent by contract: the adoption never notifies, never touches the demanded write
+        // sequence or the public control slot, and never consumes an async sequence.
+        this.#state.rawCurrentValue = snapshot.history.currentValue;
+        this.#state.history = snapshot.history;
+        this.#state.authoritativeSequence = snapshot.authoritativeSequence;
+        this.#writeExternalSample(impl, snapshot.history, false);
+        return {
+            kind: 'synchronous-snapshot-adopted',
+            callbackDelivery: 'silent',
+            demandedWriteSequence: 'unchanged',
+            publicControlSlot: 'unchanged',
+        };
+    }
+    readCachedVelocity(atTimestampMs) {
+        const history = this.#state.history;
+        if (history.kind !== 'finite-difference')
+            return 0;
+        // Pinned staleness window: no fresh sample within it reads as at rest.
+        if (atTimestampMs - history.currentTimestampMs > constants_1.MAX_VELOCITY_DELTA_MS)
+            return 0;
+        return finiteDifferenceVelocity(history);
+    }
+    applyTransitionTerminal(event, mailboxPosition, progress) {
+        return this.#applyTerminal(event, {
+            channelId: this.#state.channelId,
+            entryKind: 'transition-terminal',
+            callbackKind: event.kind,
+            executionId: event.executionId,
+            deliverySequence: event.eventSequence,
+        }, mailboxPosition, progress);
+    }
+    applyLifecycleTerminal(event, mailboxPosition, progress) {
+        return this.#applyTerminal(event, {
+            channelId: this.#state.channelId,
+            entryKind: 'lifecycle-terminal',
+            callbackKind: 'animation-complete',
+            executionId: event.executionId,
+            deliverySequence: event.eventSequence,
+        }, mailboxPosition, progress);
+    }
+    /**
+     * One transition/lifecycle terminal at its own ordered mailbox position (pinned candidate
+     * law): drain-order replay is suppressed before any progress or cache work; otherwise the
+     * immutable event delivers unconditionally while its carried candidate is adopted only if its
+     * epoch/lease/write sequence still wins. The mailbox position is the owning drain's
+     * bookkeeping — the port guards by its own ledger sequences.
+     */
+    #applyTerminal(event, entry, mailboxPosition, progress) {
+        void mailboxPosition;
+        if (event.eventSequence <= this.#state.deliveredEventWatermark) {
+            return {
+                kind: 'event-replay-rejected',
+                reason: 'stale-event-sequence',
+                callbackDelivery: 'suppressed-replay',
+                armedCompletion: 'retained',
+            };
+        }
+        const impl = this.#requireGraphMotionValue();
+        progress.beginEntry(entry);
+        let result;
+        if (event.directOperationEpoch < this.#state.directOperationEpoch) {
+            result = {
+                kind: 'candidate-cache-rejected',
+                reason: 'stale-direct-operation-epoch',
+                callbackDelivery: 'required',
+                armedCompletion: 'retained',
+            };
+        }
+        else if (event.executionLease < this.#state.executionLease) {
+            result = {
+                kind: 'candidate-cache-rejected',
+                reason: 'stale-execution-lease',
+                callbackDelivery: 'required',
+                armedCompletion: 'retained',
+            };
+        }
+        else if (event.writeSequence <= this.#state.acceptedWriteSequence) {
+            result = {
+                kind: 'candidate-cache-rejected',
+                reason: 'stale-write-sequence',
+                callbackDelivery: 'required',
+                armedCompletion: 'retained',
+            };
+        }
+        else {
+            this.#adoptCandidateCacheSilently(impl, event.history, event.writeSequence);
+            result = {
+                kind: 'candidate-adopted',
+                callbackDelivery: 'required',
+                armedCompletion: 'retained',
+            };
+        }
+        this.#state.deliveredEventWatermark = event.eventSequence;
+        progress.finalizeDeliveredEventWatermarkAndRetention(this.#state.channelId, event.eventSequence);
+        progress.clearEntry();
+        return result;
+    }
+}
+function initialLocalFrameEventPortState() {
+    return {
+        stagedTransitionEvents: [],
+        drainedEventSequences: [],
+        lastGuardedMailboxPosition: null,
+    };
+}
+class LocalFrameEventPortImpl {
+    // The serializable record is the state; every transition replaces it immutably.
+    #state;
+    #candidateCacheGuard;
+    constructor(state, candidateCacheGuard) {
+        this.#state = state;
+        this.#candidateCacheGuard = candidateCacheGuard;
+    }
+    observe() {
+        return {
+            stagedTransitionEventCount: this.#state.stagedTransitionEvents.length,
+            stagedEventSequences: this.#state.stagedTransitionEvents.map((event) => event.eventSequence),
+            drainedEventSequences: this.#state.drainedEventSequences,
+            lastGuardedMailboxPosition: this.#state.lastGuardedMailboxPosition,
+        };
+    }
+    stageTransitionOnUpdate(event) {
+        this.#stage(event);
+    }
+    stageTransitionOnComplete(event) {
+        this.#stage(event);
+    }
+    #stage(event) {
+        this.#state = {
+            ...this.#state,
+            stagedTransitionEvents: [...this.#state.stagedTransitionEvents, event],
+        };
+    }
+    drainTransitionEvents() {
+        // Delivery order is event-sequence order regardless of staging order; every drained
+        // sequence is recorded so a later drain never replays it.
+        const drained = [...this.#state.stagedTransitionEvents].sort((left, right) => left.eventSequence - right.eventSequence);
+        this.#state = {
+            ...this.#state,
+            stagedTransitionEvents: [],
+            drainedEventSequences: [
+                ...this.#state.drainedEventSequences,
+                ...drained.map((event) => event.eventSequence),
+            ],
+        };
+        return drained;
+    }
+    guardAndAdoptTransitionTerminalCandidateCacheAtMailboxPosition(event, mailboxPosition, progress) {
+        this.#state = { ...this.#state, lastGuardedMailboxPosition: mailboxPosition };
+        return this.#candidateCacheGuard.applyTransitionTerminal(event, mailboxPosition, progress);
+    }
+    guardAndAdoptLifecycleTerminalCandidateCacheAtMailboxPosition(event, mailboxPosition, progress) {
+        this.#state = { ...this.#state, lastGuardedMailboxPosition: mailboxPosition };
+        return this.#candidateCacheGuard.applyLifecycleTerminal(event, mailboxPosition, progress);
+    }
+}
+function createLocalFrameEventPort(options) {
+    return new LocalFrameEventPortImpl(options.initialState ?? initialLocalFrameEventPortState(), options.candidateCacheGuard);
+}
+function createMotionValueDriverPort(options) {
+    const creation = DIRECT_PUBLIC_CREATION.get(options.value) ?? { kind: 'unrecognized' };
+    const state = options.initialState ?? defaultPortState(options.rawSnapshot, options.channelId);
+    const installation = options.initialPublicControlSlotInstallation;
+    if (state.publicControlSlot.kind === 'empty') {
+        if (installation !== undefined) {
+            throw new MotionValueDriverPortInvariantError('rehydrated-public-control-slot-installation-unexpected');
+        }
+    }
+    else if (installation === undefined) {
+        throw new MotionValueDriverPortInvariantError('rehydrated-public-control-slot-installation-required');
+    }
+    else if (installation.controlId !== state.publicControlSlot.controlId ||
+        installation.executionId !== state.publicControlSlot.executionId) {
+        throw new MotionValueDriverPortInvariantError('rehydrated-public-control-slot-reference-mismatch');
+    }
+    return new MotionValueDriverPortImpl(options.value, creation, state, installation ?? null);
+}