@hops-ops/distributed 0.0.0 → 4.0.1

package/dist/replica/command-runtime/create.js

@@ -1,8 +1,185 @@
 import { parseGraphqlResponseExtensions } from '../../protocol.js';
 import { matchReplicaTrustedPresetInventory, prepareReplicaCommandWithTrustedPresets, verifyReplicaCommandReceipt } from '../commands.js';
-import { applyOptimisticEffects, attachAuthorityAbort, callerProjectedPromise, cloneScope, commandOutput, commandStatusArtifact, commandStatusRequest, commandSurfaceContract, commandTransportRequest, confirmDirectProjection, defineBoundCommand, dispatchPrepared, failTrackedProjection, freezeCommandTree, graphqlCommandRejection, linkAbortSignals, monitorPendingProjection, normalizeInventory, normalizeRetries, pendingProjection, preparedSemanticChanges, requireCommandEnvelope, requireCommandRejectionEnvelope, requireStatusEnvelope, sameScope, settleProjectionFailure, settleProjectionSuccess, settleTrackedProjection, validateStatusProgression, waitForCommandOperation } from './lib/index.js';
+import { applyOptimisticEffects, attachAuthorityAbort, callerProjectedPromise, cloneScope, commandOutput, commandStatusArtifact, commandStatusRequest, commandSurfaceContract, commandTransportRequest, confirmDirectProjection, defineBoundCommand, dispatchPrepared, failTrackedProjection, freezeCommandTree, graphqlCommandRejection, linkAbortSignals, monitorPendingProjection, normalizeInventory, normalizeRetries, pendingProjection, preparedDispatchKeys, preparedSemanticChanges, requireCommandEnvelope, requireCommandRejectionEnvelope, requireStatusEnvelope, sameScope, settleProjectionFailure, settleProjectionSuccess, settleTrackedProjection, validateStatusProgression, waitForCommandOperation } from './lib/index.js';
 import { ReplicaCommandRuntimeError } from './errors.js';
-import { replicaCommandAuthority, replicaCommandProjectedLifecycle, replicaResultObservation } from './symbols.js';
+import { replicaCommandAuthority, replicaCommandProjectionDelta, replicaCommandProjectedLifecycle, replicaCommandReadRecord, replicaResultObservation } from './symbols.js';
+import { operationsFromProjectionDelta, validateProjectionMetadataAuthority } from '../projection-delta/index.js';
+function assertActualProjectionCapabilities(contract, delta) {
+    for (let ordinal = 0; ordinal < delta.occurrences.length; ordinal += 1) {
+        const references = new Set();
+        for (const item of [...delta.operations, ...delta.recoveries]) {
+            if (item.occurrence_ordinal !== ordinal)
+                continue;
+            for (const reference of item.projection_refs)
+                references.add(reference);
+        }
+        let selectedEvent;
+        for (const reference of references) {
+            const operations = delta.operations.filter((item) => item.occurrence_ordinal === ordinal &&
+                item.projection_refs.includes(reference));
+            const recoveries = delta.recoveries.filter((item) => item.occurrence_ordinal === ordinal &&
+                item.projection_refs.includes(reference));
+            const candidates = contract.capabilities.arms.filter((arm) => arm.projection_ref === reference &&
+                operations.every(({ mutation }) => capabilityAllowsMutation(arm, mutation)) &&
+                recoveries.every(({ target }) => capabilityAllowsRecovery(arm, target)));
+            if (candidates.length !== 1) {
+                throw new Error('actual projection delta does not identify one generated event arm');
+            }
+            const event = candidates[0].event;
+            if (selectedEvent !== undefined &&
+                (event.id !== selectedEvent.id ||
+                    event.name !== selectedEvent.name ||
+                    event.version !== selectedEvent.version)) {
+                throw new Error('actual projection refs disagree on their generated event arm');
+            }
+            selectedEvent = event;
+        }
+    }
+}
+function capabilityAllowsMutation(arm, mutation) {
+    switch (mutation.op) {
+        case 'upsert': {
+            const capabilities = recordCapabilities(arm, mutation.scope);
+            const replace = capabilities[0]?.replace;
+            return (capabilities.some(({ upsert }) => upsert) &&
+                replace !== undefined &&
+                capabilities.every((capability) => sameStrings(capability.replace, replace)) &&
+                sameStrings(mutation.replace, replace) &&
+                sameStrings(mutation.fields.map(({ field }) => field), replace) &&
+                sameStrings(unionNames(capabilities.flatMap(({ fields }) => fields)), replace));
+        }
+        case 'patch': {
+            const capabilities = recordCapabilities(arm, mutation.scope);
+            const allowed = new Set(capabilities
+                .filter(({ patch }) => patch)
+                .flatMap(({ fields }) => fields));
+            return (allowed.size !== 0 &&
+                [...mutation.set.map(({ field }) => field), ...mutation.unset].every((field) => allowed.has(field)));
+        }
+        case 'delete':
+            return recordCapabilities(arm, mutation.scope).some(({ delete: allowed }) => allowed);
+        case 'link':
+        case 'unlink':
+            return arm.mutations.some((capability) => capability.kind === 'relationship' &&
+                capability.relationship === mutation.relationship &&
+                (mutation.op === 'link' ? capability.link : capability.unlink) &&
+                capabilityAllowsScope(arm, mutation.source, capability.source_model, capability.source_key) &&
+                capabilityAllowsScope(arm, mutation.target, capability.target_model, capability.target_key));
+        case 'invalidate_model':
+            return (capabilityAllowsPartition(arm, mutation.partition) &&
+                arm.mutations.some((capability) => capability.kind === 'model' &&
+                    capability.model === mutation.model));
+        case 'invalidate_relationship':
+            return arm.mutations.some((capability) => capability.kind === 'relationship' &&
+                capability.relationship === mutation.relationship &&
+                capabilityAllowsScope(arm, mutation.source, capability.source_model, capability.source_key));
+    }
+}
+function capabilityAllowsRecovery(arm, target) {
+    switch (target.kind) {
+        case 'record':
+            return recordCapabilities(arm, target.scope).length !== 0;
+        case 'relationship':
+            return arm.mutations.some((capability) => capability.kind === 'relationship' &&
+                capability.relationship === target.relationship &&
+                capabilityAllowsScope(arm, target.source, capability.source_model, capability.source_key));
+        case 'model':
+            return (capabilityAllowsPartition(arm, target.partition) &&
+                arm.mutations.some((capability) => capability.kind === 'model' &&
+                    capability.model === target.model));
+    }
+}
+function recordCapabilities(arm, scope) {
+    if (!capabilityAllowsPartition(arm, scope.partition))
+        return [];
+    return arm.mutations.filter((capability) => capability.kind === 'record' &&
+        capability.model === scope.model &&
+        sameStrings(capability.key, scope.key.map(({ field }) => field)));
+}
+function capabilityAllowsScope(arm, scope, model, key) {
+    return (capabilityAllowsPartition(arm, scope.partition) &&
+        scope.model === model &&
+        sameStrings(key, scope.key.map(({ field }) => field)));
+}
+function capabilityAllowsPartition(arm, partition) {
+    return arm.partition.kind === 'unit'
+        ? partition?.kind === 'unit'
+        : partition === undefined || partition.kind === 'opaque';
+}
+function unionNames(values) {
+    return Object.freeze([...new Set(values)].sort(compareCodeUnits));
+}
+function compareCodeUnits(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function sameStrings(left, right) {
+    return (left.length === right.length &&
+        left.every((value, index) => value === right[index]));
+}
+function actualProjectionRevalidation(base, delta) {
+    const models = new Set(base.models);
+    const relationships = new Map(base.relationships.map((relationship) => [
+        JSON.stringify([
+            relationship.sourceModel,
+            relationship.field,
+            relationship.targetModel
+        ]),
+        relationship
+    ]));
+    const addRelationship = (sourceModel, field, targetModel) => {
+        const relationship = Object.freeze({ sourceModel, field, targetModel });
+        relationships.set(JSON.stringify([sourceModel, field, targetModel]), relationship);
+    };
+    for (const { mutation } of delta.operations) {
+        switch (mutation.op) {
+            case 'upsert':
+            case 'patch':
+            case 'delete':
+                models.add(mutation.scope.model);
+                break;
+            case 'link':
+            case 'unlink':
+                models.add(mutation.source.model);
+                models.add(mutation.target.model);
+                addRelationship(mutation.source.model, mutation.relationship, mutation.target.model);
+                break;
+            case 'invalidate_model':
+                models.add(mutation.model);
+                break;
+            case 'invalidate_relationship':
+                models.add(mutation.source.model);
+                break;
+        }
+    }
+    for (const { target } of delta.recoveries) {
+        switch (target.kind) {
+            case 'record':
+                models.add(target.scope.model);
+                break;
+            case 'relationship':
+                models.add(target.source.model);
+                break;
+            case 'model':
+                models.add(target.model);
+                break;
+        }
+    }
+    return Object.freeze({
+        version: 1,
+        required: true,
+        dependencies: Object.freeze([...base.dependencies]),
+        models: Object.freeze([...models].sort(compareCodeUnits)),
+        relationships: Object.freeze([...relationships.values()].sort((left, right) => compareCodeUnits(JSON.stringify([
+            left.sourceModel,
+            left.field,
+            left.targetModel
+        ]), JSON.stringify([
+            right.sourceModel,
+            right.field,
+            right.targetModel
+        ]))))
+    });
+}
 export function createReplicaCommandRuntime(replica, transport, entries, options = {}) {
     const inventory = normalizeInventory(entries);
     if (options.diagnostics !== undefined) {
@@ -26,14 +203,145 @@ export function createReplicaCommandRuntime(replica, transport, entries, options
         throw new TypeError('generated command status artifact requires transport.status');
     }
     if (replicaRevalidate === undefined &&
-        inventory.some(({ artifact }) => artifact.revalidation.required)) {
-        throw new TypeError('generated command revalidation plan requires replica.revalidate');
+        inventory.some(({ artifact }) => artifact.projection !== undefined ||
+            artifact.revalidation.required)) {
+        throw new TypeError('generated modeled projection or required revalidation plan requires replica.revalidate');
     }
     const registration = replica[replicaCommandAuthority]?.(contract);
     const pending = new Map();
+    const projectionReplays = new Map();
+    const projectionRevalidations = new Map();
+    const dispatchTails = new Map();
     const unmanagedLayers = new Set();
     const runtimeAbort = new AbortController();
     let disposed = false;
+    const reserveDispatch = (prepared) => {
+        const keys = preparedDispatchKeys(prepared);
+        if (keys.length === 0) {
+            return Object.freeze({
+                wait: Promise.resolve(),
+                release() { }
+            });
+        }
+        const predecessors = keys.flatMap((key) => {
+            const predecessor = dispatchTails.get(key);
+            return predecessor === undefined ? [] : [predecessor];
+        });
+        let resolve;
+        const tail = new Promise((settled) => {
+            resolve = settled;
+        });
+        for (const key of keys)
+            dispatchTails.set(key, tail);
+        let released = false;
+        return Object.freeze({
+            wait: Promise.all(predecessors).then(() => undefined),
+            release() {
+                if (released)
+                    return;
+                released = true;
+                for (const key of keys) {
+                    if (dispatchTails.get(key) === tail)
+                        dispatchTails.delete(key);
+                }
+                resolve();
+            }
+        });
+    };
+    const validateActualProjection = (prepared, metadata, authority) => {
+        if (prepared.projection === undefined) {
+            if (metadata.projection !== undefined || metadata.expects.length !== 0) {
+                throw new Error('unmodeled command returned a projection delta');
+            }
+            return Object.freeze({ requiresRevalidation: false });
+        }
+        const actual = metadata.projection;
+        if (actual === undefined) {
+            throw new Error('modeled command omitted its projection delta');
+        }
+        const canonical = validateProjectionMetadataAuthority(actual, prepared.projection.contract, {
+            surface: prepared.transport.protocol.surface,
+            schemaHash: prepared.transport.protocol.schemaHash,
+            protocolHash: prepared.transport.protocol.protocolHash,
+            authorizationGeneration: authority.scope.authorizationGeneration,
+            cacheScope: authority.scope.cacheScope,
+            causationId: metadata.causationId
+        });
+        const expected = actual.obligations.map((obligation) => ({
+            projection: actual.delta.projections[obligation.projectionRef].program_id,
+            model: obligation.model,
+            scopeToken: obligation.scopeToken
+        }));
+        if (expected.length !== metadata.expects.length ||
+            expected.some((item, index) => {
+                const candidate = metadata.expects[index];
+                return (candidate === undefined ||
+                    candidate.projection !== item.projection ||
+                    candidate.model !== item.model ||
+                    candidate.scopeToken !== item.scopeToken);
+            })) {
+            throw new Error('projection obligations do not match command expectations');
+        }
+        const previous = projectionReplays.get(prepared.commandId);
+        if (previous !== undefined) {
+            if (previous !== canonical) {
+                throw new Error('projection delta changed during command replay');
+            }
+            return Object.freeze({
+                requiresRevalidation: actual.revalidate || actual.obligations.length === 0
+            });
+        }
+        assertActualProjectionCapabilities(prepared.projection.contract, actual.delta);
+        const operations = operationsFromProjectionDelta(actual.delta.operations);
+        const seam = replica[replicaCommandProjectionDelta];
+        if (seam === undefined) {
+            throw new Error('replica does not implement projection delta replacement');
+        }
+        return Object.freeze({
+            canonical,
+            operations,
+            revalidation: actual.revalidate || actual.obligations.length === 0
+                ? actualProjectionRevalidation(prepared.revalidation, actual.delta)
+                : undefined,
+            requiresRevalidation: actual.revalidate || actual.obligations.length === 0
+        });
+    };
+    const commitActualProjection = (prepared, validated) => {
+        if (validated.canonical === undefined ||
+            validated.operations === undefined) {
+            return validated.requiresRevalidation;
+        }
+        const seam = replica[replicaCommandProjectionDelta];
+        const actualPrepared = Object.freeze({
+            ...prepared,
+            optimistic: Object.freeze({
+                version: 1,
+                operations: validated.operations,
+                fallback: 'revalidate'
+            })
+        });
+        seam.call(replica, prepared.commandId, (writer) => applyOptimisticEffects(writer, validated.operations), preparedSemanticChanges(actualPrepared));
+        projectionReplays.set(prepared.commandId, validated.canonical);
+        if (validated.revalidation !== undefined) {
+            projectionRevalidations.set(prepared.commandId, validated.revalidation);
+        }
+        return validated.requiresRevalidation;
+    };
+    const applyActualProjection = (prepared, metadata, authority) => commitActualProjection(prepared, validateActualProjection(prepared, metadata, authority));
+    const validateProjectionForState = (prepared, metadata, authority) => {
+        switch (metadata.state) {
+            case 'succeeded':
+            case 'succeeded_pending_projection':
+            case 'atomic':
+                return validateActualProjection(prepared, metadata, authority);
+            case 'in_progress':
+            case 'rejected':
+            case 'projection_failed':
+            case 'expired':
+            case 'unknown':
+                return Object.freeze({ requiresRevalidation: false });
+        }
+    };
     const rejectUnmanagedLayer = (commandId) => {
         unmanagedLayers.delete(commandId);
         return replica.rejectOptimisticLayer(commandId);
@@ -87,7 +395,8 @@ export function createReplicaCommandRuntime(replica, transport, entries, options
             runtimeAbort.signal
         ]);
         try {
-            await waitForCommandOperation(replicaRevalidate(prepared.revalidation), revalidationSignals.signal);
+            await waitForCommandOperation(replicaRevalidate(projectionRevalidations.get(prepared.commandId) ??
+                prepared.revalidation), revalidationSignals.signal);
             return true;
         }
         catch (error) {
@@ -119,6 +428,29 @@ export function createReplicaCommandRuntime(replica, transport, entries, options
         })
             .catch(() => undefined);
     };
+    const revalidateDispositionAndRetireInBackground = (controller) => {
+        void revalidate(controller.prepared, controller.authority.signal)
+            .then((refreshed) => {
+            if (refreshed &&
+                !controller.settled &&
+                stillCurrent(controller.authority) &&
+                pending.get(controller.commandId) === controller) {
+                retireLayerAfterAuthoritativeRevalidation(controller.commandId);
+                settleProjectionSuccess(controller);
+                pending.delete(controller.commandId);
+            }
+        })
+            .catch(() => undefined);
+    };
+    const commitStatusProgression = (tracker, status) => {
+        tracker.state = status.state;
+        if (status.metadata !== undefined) {
+            tracker.metadata = status.metadata;
+            if (tracker.pending !== undefined) {
+                tracker.pending.metadata = status.metadata;
+            }
+        }
+    };
     const statusReader = (prepared, authority, tracker) => {
         const read = async () => {
             if (disposed) {
@@ -155,21 +487,40 @@ export function createReplicaCommandRuntime(replica, transport, entries, options
                 throw new ReplicaCommandRuntimeError('REPLICA_COMMAND_SCOPE_INVALIDATED', { commandId: prepared.commandId });
             }
             let status;
+            let statusRequiresRevalidation = false;
             try {
                 status = requireStatusEnvelope(result, statusArtifact, prepared, authority, contract);
                 validateStatusProgression(tracker.state, tracker.metadata, status);
+                if (status.metadata !== undefined) {
+                    if (tracker.pending !== undefined &&
+                        status.metadata.causationId !==
+                            tracker.pending.causationId) {
+                        throw new Error('command status changed pending causation identity');
+                    }
+                    if (status.metadata.projectionDisposition === 'revalidate') {
+                        /*
+                         * This is current-envelope authority to refetch, never
+                         * authority to validate or apply the omitted old-scope
+                         * delta.
+                         */
+                        statusRequiresRevalidation = true;
+                    }
+                    else if (prepared.consistency !== 'atomic') {
+                        // Atomic rows are confirmed on the mutation response,
+                        // not via async projection-delta status envelopes.
+                        const validated = validateProjectionForState(prepared, status.metadata, authority);
+                        statusRequiresRevalidation = commitActualProjection(prepared, validated);
+                    }
+                }
             }
             catch (error) {
+                const failure = new ReplicaCommandRuntimeError('REPLICA_COMMAND_PROTOCOL_INVALID', { commandId: prepared.commandId, cause: error });
+                rejectUnmanagedLayer(prepared.commandId);
                 revalidateInBackground(prepared, authority);
-                throw new ReplicaCommandRuntimeError('REPLICA_COMMAND_PROTOCOL_INVALID', { commandId: prepared.commandId, cause: error });
-            }
-            tracker.state = status.state;
-            if (status.metadata !== undefined) {
-                tracker.metadata = status.metadata;
-                if (tracker.pending !== undefined) {
-                    tracker.pending.metadata = status.metadata;
-                }
+                failTrackedProjection(tracker, pending, failure);
+                throw failure;
             }
+            commitStatusProgression(tracker, status);
             switch (status.state) {
                 case 'rejected':
                     rejectUnmanagedLayer(prepared.commandId);
@@ -187,10 +538,56 @@ export function createReplicaCommandRuntime(replica, transport, entries, options
                         state: status.state
                     }));
                     break;
-                case 'accepted':
-                case 'accepted_pending_projection':
-                case 'projected': {
+                case 'succeeded':
+                case 'succeeded_pending_projection':
+                case 'atomic': {
                     const metadata = status.metadata;
+                    if (metadata.projectionDisposition === 'revalidate') {
+                        if (metadata.state === 'succeeded_pending_projection') {
+                            /*
+                             * Historical evidence is still pending. Refresh
+                             * canonical current-scope queries opportunistically,
+                             * but retain optimism and keep polling until the
+                             * server reports a terminal state.
+                             */
+                            revalidateInBackground(prepared, authority);
+                            break;
+                        }
+                        let refreshed = false;
+                        try {
+                            refreshed = await revalidate(prepared, authority.signal);
+                        }
+                        catch (error) {
+                            if (disposed) {
+                                throw new ReplicaCommandRuntimeError('REPLICA_COMMAND_DISPOSED', {
+                                    commandId: prepared.commandId,
+                                    cause: error
+                                });
+                            }
+                            if (authority.signal?.aborted ||
+                                !stillCurrent(authority)) {
+                                throw new ReplicaCommandRuntimeError('REPLICA_COMMAND_SCOPE_INVALIDATED', {
+                                    commandId: prepared.commandId,
+                                    cause: error
+                                });
+                            }
+                            // The retained monitor will retry this exact
+                            // current-scope revalidation on the next status read.
+                        }
+                        if (refreshed && stillCurrent(authority)) {
+                            const controller = tracker.pending;
+                            if (controller !== undefined &&
+                                !controller.settled &&
+                                pending.get(prepared.commandId) === controller) {
+                                retireLayerAfterAuthoritativeRevalidation(prepared.commandId);
+                                settleTrackedProjection(tracker, pending);
+                            }
+                            else if (unmanagedLayers.has(prepared.commandId)) {
+                                retireLayerAfterAuthoritativeRevalidation(prepared.commandId);
+                            }
+                        }
+                        break;
+                    }
                     const remainsPending = replica.markOptimisticLayerAccepted(prepared.commandId, metadata);
                     if (!remainsPending) {
                         unmanagedLayers.delete(prepared.commandId);
@@ -198,14 +595,15 @@ export function createReplicaCommandRuntime(replica, transport, entries, options
                             settleTrackedProjection(tracker, pending);
                         }
                     }
-                    else if (metadata.state === 'projected' ||
-                        (metadata.state === 'accepted' &&
-                            prepared.confirmations === undefined &&
-                            prepared.revalidation.required)) {
+                    else if (metadata.state === 'atomic' ||
+                        (metadata.state === 'succeeded' &&
+                            metadata.expects.length === 0 &&
+                            (prepared.revalidation.required ||
+                                statusRequiresRevalidation))) {
                         /*
                          * Status is causal truth, but it carries no canonical
                          * query payload. `projected` fences asynchronous
-                         * projection; `accepted` is terminal when the generated
+                         * projection; `succeeded` is terminal when the generated
                          * contract has no confirmations. In both cases, only a
                          * query started after that fence may retire optimism.
                          */
@@ -295,7 +693,11 @@ export function createReplicaCommandRuntime(replica, transport, entries, options
                 : 'REPLICA_COMMAND_SCOPE_INVALIDATED', { commandId: prepared.commandId, cause: request.signal.reason });
         }
         try {
-            replica.createOptimisticLayer(prepared.commandId, (writer) => applyOptimisticEffects(writer, prepared.optimistic.operations), semanticChanges);
+            const pureHost = {
+                readRecord: replica[replicaCommandReadRecord]?.bind(replica),
+                pureFunctions: options.pureFunctions
+            };
+            replica.createOptimisticLayer(prepared.commandId, (writer) => applyOptimisticEffects(writer, prepared.optimistic.operations, pureHost), semanticChanges);
         }
         catch (error) {
             requestSignals.dispose();
@@ -326,9 +728,11 @@ export function createReplicaCommandRuntime(replica, transport, entries, options
             }
             return undefined;
         };
+        const dispatchReservation = reserveDispatch(prepared);
         let result;
         let dispatchAttempted = false;
         try {
+            await dispatchReservation.wait;
             result = await dispatchPrepared(transport, request, transportRetries, () => {
                 dispatchAttempted = true;
             });
@@ -357,6 +761,7 @@ export function createReplicaCommandRuntime(replica, transport, entries, options
             });
         }
         finally {
+            dispatchReservation.release();
             requestSignals.dispose();
         }
         if (!stillCurrent(authority)) {
@@ -397,8 +802,6 @@ export function createReplicaCommandRuntime(replica, transport, entries, options
             });
         }
         const metadata = distributed.command;
-        statusTracker.state = metadata.state;
-        statusTracker.metadata = metadata;
         if (metadata.state === 'rejected') {
             rejectUnmanagedLayer(prepared.commandId);
             throw new ReplicaCommandRuntimeError('REPLICA_COMMAND_REJECTED', {
@@ -412,6 +815,8 @@ export function createReplicaCommandRuntime(replica, transport, entries, options
             throw new ReplicaCommandRuntimeError('REPLICA_COMMAND_PROJECTION_FAILED', { commandId: prepared.commandId, state: metadata.state });
         }
         if (metadata.state === 'unknown' || metadata.state === 'in_progress') {
+            statusTracker.state = metadata.state;
+            statusTracker.metadata = metadata;
             throw new ReplicaCommandRuntimeError('REPLICA_COMMAND_OUTCOME_PENDING', {
                 commandId: prepared.commandId,
                 state: metadata.state,
@@ -424,42 +829,51 @@ export function createReplicaCommandRuntime(replica, transport, entries, options
             throw new ReplicaCommandRuntimeError('REPLICA_COMMAND_PROJECTION_FAILED', { commandId: prepared.commandId, state: metadata.state });
         }
         if ((result.errors?.length ?? 0) > 0) {
-            let retainedRecovery;
-            if (prepared.confirmations?.kind === 'finite') {
-                replica.markOptimisticLayerAccepted(prepared.commandId, metadata);
-                retainedRecovery = recoveryForRetainedLayer();
-            }
-            else {
-                rejectUnmanagedLayer(prepared.commandId);
-            }
+            rejectUnmanagedLayer(prepared.commandId);
             revalidateInBackground(prepared, authority);
-            throw new ReplicaCommandRuntimeError('REPLICA_COMMAND_PROTOCOL_INVALID', { commandId: prepared.commandId, recovery: retainedRecovery });
+            throw new ReplicaCommandRuntimeError('REPLICA_COMMAND_PROTOCOL_INVALID', { commandId: prepared.commandId });
         }
         let output;
         try {
             output = commandOutput(artifact, result.data, prepared.transport.mutationField);
         }
         catch (error) {
-            let retainedRecovery;
-            if (prepared.consistency === 'projected' ||
-                prepared.confirmations?.kind !== 'finite') {
-                rejectUnmanagedLayer(prepared.commandId);
-            }
-            else {
-                replica.markOptimisticLayerAccepted(prepared.commandId, metadata);
-                retainedRecovery = recoveryForRetainedLayer();
-            }
+            rejectUnmanagedLayer(prepared.commandId);
             revalidateInBackground(prepared, authority);
             throw new ReplicaCommandRuntimeError('REPLICA_COMMAND_PROTOCOL_INVALID', {
                 commandId: prepared.commandId,
                 cause: error,
-                recovery: retainedRecovery
+                ...(statusArtifact === undefined ? {} : { recovery })
             });
         }
+        /*
+         * Ship contract: Atomic seals from the atomic GraphQL row +
+         * direct `records` (confirmDirectProjection). Eventual applies
+         * projection-delta when present. Both strategies start from the same
+         * compiler-derived event→mutation preview — different response proof by
+         * design.
+         */
+        let actualRequiresRevalidation = false;
+        if (prepared.consistency !== 'atomic') {
+            try {
+                actualRequiresRevalidation = applyActualProjection(prepared, metadata, authority);
+            }
+            catch (error) {
+                rejectUnmanagedLayer(prepared.commandId);
+                revalidateInBackground(prepared, authority);
+                throw new ReplicaCommandRuntimeError('REPLICA_COMMAND_PROTOCOL_INVALID', {
+                    commandId: prepared.commandId,
+                    cause: error,
+                    ...(statusArtifact === undefined ? {} : { recovery })
+                });
+            }
+        }
         let projected;
         let projectionLifecycle;
-        if (prepared.consistency === 'projected') {
-            if (metadata.state !== 'projected') {
+        if (prepared.consistency === 'atomic') {
+            if (metadata.state !== 'atomic') {
+                statusTracker.state = metadata.state;
+                statusTracker.metadata = metadata;
                 throw new ReplicaCommandRuntimeError('REPLICA_COMMAND_OUTCOME_PENDING', {
                     commandId: prepared.commandId,
                     state: metadata.state,
@@ -473,19 +887,27 @@ export function createReplicaCommandRuntime(replica, transport, entries, options
             catch (error) {
                 rejectUnmanagedLayer(prepared.commandId);
                 revalidateInBackground(prepared, authority);
-                throw new ReplicaCommandRuntimeError('REPLICA_COMMAND_PROTOCOL_INVALID', { commandId: prepared.commandId, cause: error });
+                throw new ReplicaCommandRuntimeError('REPLICA_COMMAND_PROTOCOL_INVALID', {
+                    commandId: prepared.commandId,
+                    cause: error,
+                    ...(statusArtifact === undefined ? {} : { recovery })
+                });
             }
+            statusTracker.state = metadata.state;
+            statusTracker.metadata = metadata;
             projected = Promise.resolve(Object.freeze({
                 commandId: prepared.commandId,
-                state: 'projected',
+                state: 'atomic',
                 result: output,
                 metadata
             }));
         }
         else {
+            statusTracker.state = metadata.state;
+            statusTracker.metadata = metadata;
             const remainsPending = replica.markOptimisticLayerAccepted(prepared.commandId, metadata);
-            if (prepared.confirmations?.kind === 'finite') {
-                const controller = pendingProjection(authority, metadata, prepared);
+            if (metadata.expects.length > 0) {
+                const controller = pendingProjection(authority, metadata, prepared, statusTracker);
                 statusTracker.pending = controller;
                 if (!remainsPending) {
                     unmanagedLayers.delete(prepared.commandId);
@@ -511,7 +933,7 @@ export function createReplicaCommandRuntime(replica, transport, entries, options
                 projected = callerProjectedPromise(controller, callOptions.signal);
             }
         }
-        if (prepared.revalidation.required) {
+        if (prepared.revalidation.required || actualRequiresRevalidation) {
             revalidateAndConfirmUnmanagedInBackground(prepared, authority);
         }
         const receiptValue = {
@@ -532,7 +954,7 @@ export function createReplicaCommandRuntime(replica, transport, entries, options
         }
         const receipt = Object.freeze(receiptValue);
         try {
-            await callOptions.onAccepted?.(receipt);
+            await callOptions.onSucceeded?.(receipt);
         }
         catch (error) {
             options.onBackgroundError?.(error);
@@ -567,6 +989,8 @@ export function createReplicaCommandRuntime(replica, transport, entries, options
                 continue;
             }
             if (distributed.schemaHash !== controller.authority.scope.schemaHash ||
+                distributed.authorizationGeneration !==
+                    controller.authority.scope.authorizationGeneration ||
                 distributed.cacheScope !== controller.authority.scope.cacheScope) {
                 continue;
             }
@@ -574,19 +998,28 @@ export function createReplicaCommandRuntime(replica, transport, entries, options
             if (command?.commandId === commandId) {
                 try {
                     verifyReplicaCommandReceipt(controller.prepared, command);
+                    if (command.causationId !== controller.causationId) {
+                        throw new Error('live command changed pending causation identity');
+                    }
+                    const status = Object.freeze({
+                        commandId,
+                        state: command.state,
+                        metadata: command
+                    });
+                    validateStatusProgression(controller.tracker.state, controller.tracker.metadata, status);
+                    if (command.projectionDisposition !== 'revalidate') {
+                        const validated = validateProjectionForState(controller.prepared, command, controller.authority);
+                        commitActualProjection(controller.prepared, validated);
+                    }
+                    commitStatusProgression(controller.tracker, status);
                 }
                 catch (error) {
+                    replica.rejectOptimisticLayer(commandId);
                     revalidateInBackground(controller.prepared, controller.authority);
                     settleProjectionFailure(controller, new ReplicaCommandRuntimeError('REPLICA_COMMAND_PROTOCOL_INVALID', { commandId, cause: error }));
                     pending.delete(commandId);
                     continue;
                 }
-                if (command.causationId !== controller.causationId) {
-                    settleProjectionFailure(controller, new ReplicaCommandRuntimeError('REPLICA_COMMAND_PROTOCOL_INVALID', { commandId }));
-                    pending.delete(commandId);
-                    continue;
-                }
-                controller.metadata = command;
                 if (command.state === 'projection_failed') {
                     replica.rejectOptimisticLayer(commandId);
                     revalidateInBackground(controller.prepared, controller.authority);
@@ -604,6 +1037,15 @@ export function createReplicaCommandRuntime(replica, transport, entries, options
                     pending.delete(commandId);
                     continue;
                 }
+                if (command.projectionDisposition === 'revalidate') {
+                    if (command.state === 'succeeded_pending_projection') {
+                        revalidateInBackground(controller.prepared, controller.authority);
+                    }
+                    else {
+                        revalidateDispositionAndRetireInBackground(controller);
+                    }
+                    continue;
+                }
             }
             /*
              * DistributedReplica is the authority on whether this frame's