@hops-ops/distributed 0.0.0

package/dist/replica/command-runtime/lib/projection.js

@@ -0,0 +1,255 @@
+import {} from '../../../protocol.js';
+import {} from '../../commands.js';
+import { INITIAL_STATUS_POLL_MS, MAX_STATUS_POLL_MS } from '../constants.js';
+import { ReplicaCommandRuntimeError } from '../errors.js';
+import { replicaCommandDirectProjection } from '../symbols.js';
+import { isPlainRecord } from '../../../lib/is-plain-record.js';
+import { cloneOutputJson } from './output.js';
+export function confirmDirectProjection(replica, prepared, output, metadata) {
+    const direct = prepared.directProjection;
+    if (direct === undefined || !isPlainRecord(output)) {
+        throw new ReplicaCommandRuntimeError('REPLICA_COMMAND_PROTOCOL_INVALID', { commandId: prepared.commandId });
+    }
+    const identity = [];
+    for (const field of direct.identityFields) {
+        const value = output[field];
+        if (value === undefined || value === null) {
+            throw new ReplicaCommandRuntimeError('REPLICA_COMMAND_PROTOCOL_INVALID', { commandId: prepared.commandId });
+        }
+        identity.push(value);
+    }
+    const evidence = metadata.records.filter((record) => record.model === direct.model &&
+        !record.tombstone &&
+        (record.path === undefined ||
+            (record.path.length === 1 &&
+                record.path[0] === prepared.transport.mutationField)));
+    if (evidence.length !== 1) {
+        throw new ReplicaCommandRuntimeError('REPLICA_COMMAND_PROTOCOL_INVALID', { commandId: prepared.commandId });
+    }
+    const record = evidence[0];
+    const model = Object.freeze({
+        id: direct.model,
+        identityFields: direct.identityFields
+    });
+    const fields = cloneOutputJson(output, 'projected.output', new Set(), 0);
+    const confirmProtocolProjection = replica[replicaCommandDirectProjection];
+    if (confirmProtocolProjection !== undefined) {
+        confirmProtocolProjection.call(replica, prepared.commandId, {
+            model,
+            identity: Object.freeze(identity),
+            evidence: record,
+            fields
+        });
+        return;
+    }
+    replica.confirmOptimisticLayer(prepared.commandId, (writer) => writer.writeRecord(model, Object.freeze(identity), record.revision, {
+        incarnation: record.incarnation,
+        fields
+    }));
+}
+export function pendingProjection(authority, metadata, prepared) {
+    let resolve;
+    let reject;
+    const promise = new Promise((resolvePromise, rejectPromise) => {
+        resolve = resolvePromise;
+        reject = rejectPromise;
+    });
+    /*
+     * Authority loss or a terminal status can arrive before application code
+     * receives the accepted receipt. Mark the internal lifecycle promise handled
+     * eagerly while preserving its rejection for every explicit awaiter.
+     */
+    void promise.catch(() => undefined);
+    const controller = {
+        commandId: metadata.commandId,
+        causationId: metadata.causationId,
+        authority,
+        resolve,
+        reject,
+        promise,
+        prepared,
+        metadata,
+        settled: false
+    };
+    return controller;
+}
+/**
+ * Generated fact commands converge without application polling. Durable status
+ * is the only completion signal; timers merely schedule reads and never infer a
+ * successful outcome.
+ */
+export function monitorPendingProjection(controller, readStatus, retained, reportError) {
+    if (controller.settled ||
+        !retained() ||
+        projectionAuthorityAborted(controller)) {
+        return;
+    }
+    const monitorAbort = new AbortController();
+    const stopMonitor = () => monitorAbort.abort();
+    controller.stopMonitor = stopMonitor;
+    const signals = controller.authority.signal === undefined
+        ? [monitorAbort.signal]
+        : [controller.authority.signal, monitorAbort.signal];
+    void (async () => {
+        try {
+            let delay = INITIAL_STATUS_POLL_MS;
+            while (!controller.settled &&
+                retained() &&
+                !projectionAuthorityAborted(controller)) {
+                await waitForProjectionPoll(delay, signals);
+                if (controller.settled ||
+                    !retained() ||
+                    projectionAuthorityAborted(controller)) {
+                    return;
+                }
+                try {
+                    await readStatus();
+                }
+                catch (error) {
+                    if (controller.settled ||
+                        !retained() ||
+                        projectionAuthorityAborted(controller)) {
+                        return;
+                    }
+                    reportBackgroundErrorSafely(reportError, error);
+                }
+                delay = Math.min(delay * 2, MAX_STATUS_POLL_MS);
+            }
+        }
+        finally {
+            if (controller.stopMonitor === stopMonitor) {
+                controller.stopMonitor = undefined;
+            }
+            monitorAbort.abort();
+        }
+    })().catch((error) => reportBackgroundErrorSafely(reportError, error));
+}
+export function reportBackgroundErrorSafely(reportError, error) {
+    if (reportError === undefined)
+        return;
+    try {
+        reportError(error);
+    }
+    catch {
+        // Error reporting is a terminal boundary and must never reject detached work.
+    }
+}
+export function projectionAuthorityAborted(controller) {
+    return controller.authority.signal?.aborted === true;
+}
+export function waitForProjectionPoll(delay, signals) {
+    if (signals.some((signal) => signal.aborted))
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        let settled = false;
+        let timer;
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            for (const signal of signals) {
+                signal.removeEventListener('abort', finish);
+            }
+            resolve();
+        };
+        timer = setTimeout(finish, delay);
+        /*
+         * This poll owns the unresolved projected lifecycle. Keep Node's timer
+         * referenced until projection settlement or runtime disposal calls
+         * `finish`, which clears the timer and every abort listener.
+         */
+        for (const signal of signals) {
+            signal.addEventListener('abort', finish, { once: true });
+        }
+        // Close the check/register race if either signal aborted synchronously.
+        if (signals.some((signal) => signal.aborted))
+            finish();
+    });
+}
+export function settleProjectionSuccess(controller) {
+    if (controller.settled)
+        return;
+    controller.settled = true;
+    controller.abort?.();
+    controller.stopMonitor?.();
+    controller.resolve(Object.freeze({
+        commandId: controller.commandId,
+        state: 'projected',
+        metadata: controller.metadata
+    }));
+}
+export function callerProjectedPromise(controller, signal) {
+    if (signal === undefined)
+        return controller.promise;
+    const callerSignal = signal;
+    const promise = new Promise((resolve, reject) => {
+        let settled = false;
+        function settle(complete) {
+            if (settled)
+                return;
+            settled = true;
+            callerSignal.removeEventListener('abort', onAbort);
+            complete();
+        }
+        function onAbort() {
+            /*
+             * Internal causal settlement wins once selected, even if its
+             * promise callbacks have not run yet. Caller cancellation never
+             * mutates that internal lifecycle.
+             */
+            if (controller.settled)
+                return;
+            settle(() => reject(new ReplicaCommandRuntimeError('REPLICA_COMMAND_ABORTED', {
+                commandId: controller.commandId
+            })));
+        }
+        callerSignal.addEventListener('abort', onAbort, { once: true });
+        void controller.promise.then((value) => settle(() => resolve(value)), (error) => settle(() => reject(error)));
+        if (callerSignal.aborted)
+            onAbort();
+    });
+    /*
+     * An AbortSignal can fire during an async `onAccepted` callback, before the
+     * receipt reaches caller code. Keep that legitimate rejection observable
+     * without creating a process-level unhandled-rejection race.
+     */
+    void promise.catch(() => undefined);
+    return promise;
+}
+export function attachAuthorityAbort(controller, onSettled) {
+    const signal = controller.authority.signal;
+    if (signal === undefined)
+        return;
+    const onAbort = () => {
+        settleProjectionFailure(controller, new ReplicaCommandRuntimeError('REPLICA_COMMAND_SCOPE_INVALIDATED', { commandId: controller.commandId }));
+        onSettled();
+    };
+    signal.addEventListener('abort', onAbort, { once: true });
+    controller.abort = () => signal.removeEventListener('abort', onAbort);
+    if (signal.aborted)
+        onAbort();
+}
+export function settleProjectionFailure(controller, error) {
+    if (controller.settled)
+        return;
+    controller.settled = true;
+    controller.abort?.();
+    controller.stopMonitor?.();
+    controller.reject(error);
+}
+export function settleTrackedProjection(tracker, pending) {
+    const controller = tracker.pending;
+    if (controller === undefined || controller.settled)
+        return;
+    settleProjectionSuccess(controller);
+    pending.delete(controller.commandId);
+}
+export function failTrackedProjection(tracker, pending, error) {
+    const controller = tracker.pending;
+    if (controller === undefined)
+        return;
+    settleProjectionFailure(controller, error);
+    pending.delete(controller.commandId);
+}

package/dist/replica/command-runtime/lib/status.d.ts

@@ -0,0 +1,7 @@
+import { type DistributedCommandMetadata, type DistributedCommandState } from '../../../protocol.js';
+import { type ReplicaPreparedCommand } from '../../commands.js';
+import type { CapturedAuthority, ReplicaCommandStatus, ReplicaCommandStatusArtifact, ReplicaCommandSurfaceContract, ReplicaCommandTransportResult } from '../types.js';
+export declare function requireStatusEnvelope<TInput, TOutput>(result: ReplicaCommandTransportResult, artifact: ReplicaCommandStatusArtifact, prepared: ReplicaPreparedCommand<TInput, TOutput>, authority: CapturedAuthority, contract: ReplicaCommandSurfaceContract): ReplicaCommandStatus;
+export declare function commandStatusOutput(data: Readonly<Record<string, unknown>> | null | undefined): DistributedCommandState;
+export declare function validateStatusProgression(previousState: DistributedCommandState | undefined, previous: DistributedCommandMetadata | undefined, current: ReplicaCommandStatus): void;
+export declare function isStatusTransition(previous: DistributedCommandState, next: DistributedCommandState): boolean;

package/dist/replica/command-runtime/lib/status.js

@@ -0,0 +1,127 @@
+import { parseGraphqlResponseExtensions } from '../../../protocol.js';
+import { matchReplicaTrustedPresetInventory, verifyReplicaCommandReceipt } from '../../commands.js';
+import { isPlainRecord } from '../../../lib/is-plain-record.js';
+import { isStringSubset, projectionExpectationFingerprint, projectionObservationFingerprint, recordRevisionFingerprint, sameStringMultiset } from './output.js';
+export function requireStatusEnvelope(result, artifact, prepared, authority, contract) {
+    if (!Number.isSafeInteger(result.status) ||
+        result.status < 200 ||
+        result.status >= 300 ||
+        (result.errors?.length ?? 0) !== 0) {
+        throw new Error('command status request did not succeed');
+    }
+    const state = commandStatusOutput(result.data);
+    const distributed = parseGraphqlResponseExtensions(result.extensions)?.distributed;
+    if (distributed === undefined ||
+        distributed.operation !== artifact.operationHash ||
+        distributed.protocolVersion !== authority.scope.protocolVersion ||
+        distributed.schemaHash !== authority.scope.schemaHash ||
+        distributed.cacheScope !== authority.scope.cacheScope ||
+        distributed.snapshot !== undefined ||
+        distributed.live !== undefined) {
+        throw new Error('command status response does not match its generated scope');
+    }
+    matchReplicaTrustedPresetInventory(contract.trustedPresets, distributed.trustedPresets);
+    const metadata = distributed.command;
+    if (metadata === undefined) {
+        if (state !== 'unknown' && state !== 'expired') {
+            throw new Error('command status omitted required causal metadata');
+        }
+        return Object.freeze({
+            commandId: prepared.commandId,
+            state
+        });
+    }
+    verifyReplicaCommandReceipt(prepared, metadata);
+    if (metadata.state !== state) {
+        throw new Error('command status data and causal metadata disagree');
+    }
+    return Object.freeze({
+        commandId: prepared.commandId,
+        state,
+        metadata
+    });
+}
+export function commandStatusOutput(data) {
+    if (data === undefined ||
+        data === null ||
+        !isPlainRecord(data) ||
+        Reflect.ownKeys(data).length !== 1 ||
+        !Object.prototype.hasOwnProperty.call(data, 'commandStatus')) {
+        throw new Error('command status data has an invalid root shape');
+    }
+    const value = data.commandStatus;
+    if (!isPlainRecord(value) ||
+        Reflect.ownKeys(value).length !== 1 ||
+        !Object.prototype.hasOwnProperty.call(value, 'state')) {
+        throw new Error('command status data has an invalid result shape');
+    }
+    switch (value.state) {
+        case 'in_progress':
+        case 'accepted':
+        case 'accepted_pending_projection':
+        case 'projected':
+        case 'rejected':
+        case 'projection_failed':
+        case 'expired':
+        case 'unknown':
+            return value.state;
+        default:
+            throw new Error('command status data has an invalid state');
+    }
+}
+export function validateStatusProgression(previousState, previous, current) {
+    if (previousState !== undefined &&
+        !isStatusTransition(previousState, current.state)) {
+        throw new Error('command status regressed or changed terminal outcome');
+    }
+    const next = current.metadata;
+    if (next === undefined) {
+        if ((current.state !== 'unknown' && current.state !== 'expired') ||
+            (previous !== undefined && current.state === 'unknown')) {
+            throw new Error('command status lost causal metadata');
+        }
+        return;
+    }
+    if (next.state !== current.state) {
+        throw new Error('command status metadata has an inconsistent state');
+    }
+    if (previous === undefined)
+        return;
+    if (next.commandId !== previous.commandId ||
+        next.causationId !== previous.causationId ||
+        next.consistency !== previous.consistency) {
+        throw new Error('command status changed causal identity');
+    }
+    if (!(previous.state === 'in_progress' &&
+        previous.expects.length === 0) &&
+        !sameStringMultiset(previous.expects.map(projectionExpectationFingerprint), next.expects.map(projectionExpectationFingerprint))) {
+        throw new Error('command status changed projection expectations');
+    }
+    if (!isStringSubset(previous.observations.map(projectionObservationFingerprint), next.observations.map(projectionObservationFingerprint)) ||
+        !isStringSubset(previous.records.map(recordRevisionFingerprint), next.records.map(recordRevisionFingerprint))) {
+        throw new Error('command status lost causal evidence');
+    }
+}
+export function isStatusTransition(previous, next) {
+    switch (previous) {
+        case 'unknown':
+            return true;
+        case 'in_progress':
+            return next !== 'unknown';
+        case 'accepted':
+            return next === 'accepted' || next === 'expired';
+        case 'accepted_pending_projection':
+            return (next === 'accepted_pending_projection' ||
+                next === 'projected' ||
+                next === 'projection_failed' ||
+                next === 'expired');
+        case 'projected':
+            return next === 'projected' || next === 'expired';
+        case 'rejected':
+            return next === 'rejected' || next === 'expired';
+        case 'projection_failed':
+            return next === 'projection_failed' || next === 'expired';
+        case 'expired':
+            return next === 'expired';
+    }
+}

package/dist/replica/command-runtime/lib/transport.d.ts

@@ -0,0 +1,16 @@
+import { type DistributedProtocolEnvelope } from '../../../protocol.js';
+import type { GqlError } from '../../../types.js';
+import { type ReplicaPreparedCommand } from '../../commands.js';
+import type { CapturedAuthority, ReplicaCommandStatusArtifact, ReplicaCommandStatusRequest, ReplicaCommandTransport, ReplicaCommandTransportRequest, ReplicaCommandTransportResult } from '../types.js';
+export declare function commandTransportRequest<TInput, TOutput>(prepared: ReplicaPreparedCommand<TInput, TOutput>, signal: AbortSignal | undefined): ReplicaCommandTransportRequest;
+export declare function commandStatusRequest(artifact: ReplicaCommandStatusArtifact, commandId: string, signal: AbortSignal | undefined): ReplicaCommandStatusRequest;
+export declare function dispatchPrepared(transport: ReplicaCommandTransport, request: ReplicaCommandTransportRequest, retries: number, onAttempt: () => void): Promise<ReplicaCommandTransportResult>;
+export declare function requireCommandEnvelope<TInput, TOutput>(result: ReplicaCommandTransportResult, prepared: ReplicaPreparedCommand<TInput, TOutput>, authority: CapturedAuthority): DistributedProtocolEnvelope;
+/**
+ * Domain rejection happens before a command receipt exists, so GraphQL cannot
+ * attach `distributed.command`. It still has to prove the exact generated
+ * operation and authoritative cache scope before the runtime may classify the
+ * response as a normal rejection instead of a protocol failure.
+ */
+export declare function requireCommandRejectionEnvelope<TInput, TOutput>(result: ReplicaCommandTransportResult, prepared: ReplicaPreparedCommand<TInput, TOutput>, authority: CapturedAuthority): DistributedProtocolEnvelope;
+export declare function graphqlCommandRejection(result: ReplicaCommandTransportResult): GqlError | undefined;

package/dist/replica/command-runtime/lib/transport.js

@@ -0,0 +1,112 @@
+import { parseGraphqlResponseExtensions } from '../../../protocol.js';
+import { verifyReplicaCommandReceipt } from '../../commands.js';
+import { ReplicaCommandRuntimeError } from '../errors.js';
+import { cloneSurface, waitForCommandOperation } from './util.js';
+export function commandTransportRequest(prepared, signal) {
+    const surface = prepared.transport.protocol.surface;
+    if (surface === undefined) {
+        throw new ReplicaCommandRuntimeError('REPLICA_COMMAND_PROTOCOL_INVALID', { commandId: prepared.commandId });
+    }
+    return Object.freeze({
+        operation: 'mutation',
+        commandName: prepared.name,
+        commandId: prepared.commandId,
+        mutationField: prepared.transport.mutationField,
+        document: prepared.transport.document,
+        operationHash: prepared.transport.operationHash,
+        variables: prepared.transport.variables,
+        extensions: Object.freeze({
+            distributed: Object.freeze({
+                client: Object.freeze({
+                    surface: cloneSurface(surface),
+                    schemaHash: prepared.transport.protocol.schemaHash
+                })
+            })
+        }),
+        ...(signal === undefined ? {} : { signal })
+    });
+}
+export function commandStatusRequest(artifact, commandId, signal) {
+    return Object.freeze({
+        operation: 'status',
+        commandId,
+        name: artifact.name,
+        document: artifact.document,
+        operationHash: artifact.operationHash,
+        variables: Object.freeze({ commandId }),
+        extensions: Object.freeze({
+            distributed: Object.freeze({
+                client: Object.freeze({
+                    surface: cloneSurface(artifact.protocol.surface),
+                    schemaHash: artifact.protocol.schemaHash
+                })
+            })
+        }),
+        ...(signal === undefined ? {} : { signal })
+    });
+}
+export async function dispatchPrepared(transport, request, retries, onAttempt) {
+    let error;
+    for (let attempt = 0; attempt <= retries; attempt += 1) {
+        if (request.signal?.aborted) {
+            throw request.signal.reason ?? new Error('command request aborted');
+        }
+        try {
+            onAttempt();
+            return await waitForCommandOperation(transport.dispatch(request), request.signal);
+        }
+        catch (candidate) {
+            error = candidate;
+            if (request.signal?.aborted)
+                throw candidate;
+        }
+    }
+    throw error;
+}
+export function requireCommandEnvelope(result, prepared, authority) {
+    const distributed = parseGraphqlResponseExtensions(result.extensions)?.distributed;
+    if (distributed === undefined ||
+        distributed.command === undefined ||
+        distributed.operation !== prepared.transport.operationHash ||
+        distributed.protocolVersion !== authority.scope.protocolVersion ||
+        distributed.schemaHash !== authority.scope.schemaHash ||
+        distributed.cacheScope !== authority.scope.cacheScope) {
+        throw new Error('command response does not match its generated scope');
+    }
+    verifyReplicaCommandReceipt(prepared, distributed.command);
+    return distributed;
+}
+/**
+ * Domain rejection happens before a command receipt exists, so GraphQL cannot
+ * attach `distributed.command`. It still has to prove the exact generated
+ * operation and authoritative cache scope before the runtime may classify the
+ * response as a normal rejection instead of a protocol failure.
+ */
+export function requireCommandRejectionEnvelope(result, prepared, authority) {
+    const distributed = parseGraphqlResponseExtensions(result.extensions)?.distributed;
+    if (!Number.isSafeInteger(result.status) ||
+        result.status < 200 ||
+        result.status >= 300 ||
+        result.data !== null ||
+        graphqlCommandRejection(result) === undefined ||
+        distributed === undefined ||
+        distributed.command !== undefined ||
+        distributed.operation !== prepared.transport.operationHash ||
+        distributed.protocolVersion !== authority.scope.protocolVersion ||
+        distributed.schemaHash !== authority.scope.schemaHash ||
+        distributed.cacheScope !== authority.scope.cacheScope) {
+        throw new Error('command rejection does not match its generated scope');
+    }
+    return distributed;
+}
+export function graphqlCommandRejection(result) {
+    const errors = result.errors;
+    if (parseGraphqlResponseExtensions(result.extensions)?.distributed?.command !==
+        undefined ||
+        errors === undefined ||
+        errors.length === 0 ||
+        !errors.every((error) => error.extensions?.code === 'REJECTED')) {
+        return undefined;
+    }
+    return errors[0];
+}

package/dist/replica/command-runtime/lib/util.d.ts

@@ -0,0 +1,16 @@
+import type { ReplicaAuthoritativeScope, ReplicaClientSurface } from '../../types.js';
+import { compareCodeUnits } from '../../../lib/compare-code-units.js';
+import { isPlainRecord } from '../../../lib/is-plain-record.js';
+export declare function normalizeRetries(value: number | undefined): number;
+export declare function cloneScope(scope: ReplicaAuthoritativeScope): ReplicaAuthoritativeScope;
+export declare function sameScope(left: ReplicaAuthoritativeScope, right: ReplicaAuthoritativeScope): boolean;
+export declare function sameSurface(left: ReplicaClientSurface | undefined, right: ReplicaClientSurface): boolean;
+export declare function cloneSurface(surface: ReplicaClientSurface): ReplicaClientSurface;
+export declare function linkAbortSignals(signals: readonly (AbortSignal | undefined)[]): Readonly<{
+    signal: AbortSignal | undefined;
+    dispose(): void;
+}>;
+export declare function waitForCommandOperation<T>(operation: Promise<T> | T, signal: AbortSignal | undefined): Promise<T>;
+export declare function outputInvalid(path: string): never;
+export declare function comparePropertyKeys(left: PropertyKey, right: PropertyKey): number;
+export { compareCodeUnits, isPlainRecord };

package/dist/replica/command-runtime/lib/util.js

@@ -0,0 +1,127 @@
+import { MAX_TRANSPORT_RETRIES } from '../constants.js';
+import { ReplicaCommandRuntimeError } from '../errors.js';
+import { compareCodeUnits } from '../../../lib/compare-code-units.js';
+import { isPlainRecord } from '../../../lib/is-plain-record.js';
+export function normalizeRetries(value) {
+    if (value === undefined)
+        return 0;
+    if (!Number.isSafeInteger(value) || value < 0 || value > MAX_TRANSPORT_RETRIES) {
+        throw new TypeError(`transportRetries must be an integer between 0 and ${MAX_TRANSPORT_RETRIES}`);
+    }
+    return value;
+}
+export function cloneScope(scope) {
+    return Object.freeze({
+        protocolVersion: 1,
+        schemaHash: scope.schemaHash,
+        cacheScope: scope.cacheScope
+    });
+}
+export function sameScope(left, right) {
+    return (left.protocolVersion === right.protocolVersion &&
+        left.schemaHash === right.schemaHash &&
+        left.cacheScope === right.cacheScope);
+}
+export function sameSurface(left, right) {
+    if (left === undefined ||
+        left.kind !== right.kind ||
+        left.name !== right.name) {
+        return false;
+    }
+    return (left.kind === 'role' ||
+        (right.kind === 'application' &&
+            left.roles.length === right.roles.length &&
+            left.roles.every((role, index) => role === right.roles[index])));
+}
+export function cloneSurface(surface) {
+    return surface.kind === 'role'
+        ? Object.freeze({ kind: 'role', name: surface.name })
+        : Object.freeze({
+            kind: 'application',
+            name: surface.name,
+            roles: Object.freeze([...surface.roles])
+        });
+}
+export function linkAbortSignals(signals) {
+    const sources = [
+        ...new Set(signals.filter((signal) => signal !== undefined))
+    ];
+    if (sources.length === 0) {
+        return Object.freeze({
+            signal: undefined,
+            dispose() { }
+        });
+    }
+    if (sources.length === 1) {
+        return Object.freeze({
+            signal: sources[0],
+            dispose() { }
+        });
+    }
+    const controller = new AbortController();
+    const listeners = new Map();
+    let disposed = false;
+    const dispose = () => {
+        if (disposed)
+            return;
+        disposed = true;
+        for (const [source, listener] of listeners) {
+            source.removeEventListener('abort', listener);
+        }
+        listeners.clear();
+    };
+    const abort = (signal) => {
+        if (!controller.signal.aborted) {
+            controller.abort(signal.reason);
+        }
+        dispose();
+    };
+    for (const source of sources) {
+        if (source.aborted) {
+            abort(source);
+            break;
+        }
+        const listener = () => abort(source);
+        listeners.set(source, listener);
+        source.addEventListener('abort', listener, { once: true });
+        // Close the check/register race if a source aborted synchronously.
+        if (source.aborted) {
+            listener();
+            break;
+        }
+    }
+    return Object.freeze({ signal: controller.signal, dispose });
+}
+export function waitForCommandOperation(operation, signal) {
+    const result = Promise.resolve(operation);
+    if (signal === undefined)
+        return result;
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (complete) => {
+            if (settled)
+                return;
+            settled = true;
+            signal.removeEventListener('abort', onAbort);
+            complete();
+        };
+        const onAbort = () => {
+            finish(() => reject(signal.reason ??
+                new ReplicaCommandRuntimeError('REPLICA_COMMAND_ABORTED')));
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+        void result.then((value) => finish(() => resolve(value)), (error) => finish(() => reject(error)));
+        // Close the check/register race if the signal aborted synchronously.
+        if (signal.aborted)
+            onAbort();
+    });
+}
+export function outputInvalid(path) {
+    throw new ReplicaCommandRuntimeError('REPLICA_COMMAND_PROTOCOL_INVALID', {
+        cause: new TypeError(`invalid command output at ${path}`)
+    });
+}
+export function comparePropertyKeys(left, right) {
+    return compareCodeUnits(String(left), String(right));
+}
+export { compareCodeUnits, isPlainRecord };

package/dist/replica/command-runtime/lifecycle.d.ts

@@ -0,0 +1,11 @@
+import type { ReplicaCommandProjectedOutcome, ReplicaCommandReceipt } from './types.js';
+/**
+ * Package-private causal lifecycle used by framework adapters.
+ *
+ * A caller-scoped `receipt.projected` can reject when its AbortSignal fires
+ * after acceptance. The underlying command remains globally pending until
+ * canonical projection evidence settles this independent promise.
+ *
+ * @internal
+ */
+export declare function replicaCommandProjectedLifecycleOf(receipt: ReplicaCommandReceipt<unknown>): Promise<ReplicaCommandProjectedOutcome<unknown>> | undefined;