@hops-ops/distributed 0.0.0 → 4.0.1

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

@@ -1,4 +1,4 @@
-export { replicaCommandAuthority, replicaCommandDirectProjection, replicaCommandProjectedLifecycle, replicaResultObservation } from './symbols.js';
+export { replicaCommandAuthority, replicaCommandDirectProjection, replicaCommandProjectionDelta, replicaCommandProjectedLifecycle, replicaCommandReadRecord, replicaResultObservation } from './symbols.js';
 export type { ReplicaBoundCommand, ReplicaBoundCommands, ReplicaCommandAuthorityHost, ReplicaCommandAuthorityRegistration, ReplicaCommandAuthoritySnapshot, ReplicaCommandCallOptions, ReplicaCommandDirectProjection, ReplicaCommandProjectedOutcome, ReplicaCommandReceipt, ReplicaCommandRecoveryReceipt, ReplicaCommandRuntime, ReplicaCommandRuntimeErrorCode, ReplicaCommandRuntimeOptions, ReplicaCommandStatus, ReplicaCommandStatusArtifact, ReplicaCommandStatusRequest, ReplicaCommandSurfaceContract, ReplicaCommandTransport, ReplicaCommandTransportRequest, ReplicaCommandTransportResult, ReplicaResultObservationRegistration } from './types.js';
 export { ReplicaCommandRuntimeError } from './errors.js';
 export { replicaCommandProjectedLifecycleOf } from './lifecycle.js';

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

@@ -1,4 +1,4 @@
-export { replicaCommandAuthority, replicaCommandDirectProjection, replicaCommandProjectedLifecycle, replicaResultObservation } from './symbols.js';
+export { replicaCommandAuthority, replicaCommandDirectProjection, replicaCommandProjectionDelta, replicaCommandProjectedLifecycle, replicaCommandReadRecord, replicaResultObservation } from './symbols.js';
 export { ReplicaCommandRuntimeError } from './errors.js';
 export { replicaCommandProjectedLifecycleOf } from './lifecycle.js';
 export { createReplicaCommandRuntime } from './create.js';

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

@@ -1,11 +1,24 @@
-import { type ReplicaPreparedCommand, type ReplicaPreparedCommandEffect, type ReplicaPreparedEffectKey } from '../../commands.js';
+import { type ReplicaPreparedCommand } from '../../commands.js';
+import type { PreparedProjectionOperation, PreparedProjectionScope, ReplicaPureFunction } from '../../projection-delta/index.js';
 import type { ReplicaIndexSemanticChange } from '../../index-maintenance.js';
-import type { ReplicaModelArtifact, ReplicaOptimisticWriter, ReplicaValue } from '../../types.js';
-export declare function applyOptimisticEffects(writer: ReplicaOptimisticWriter, effects: readonly ReplicaPreparedCommandEffect[]): void;
+import type { ReplicaIdentity, ReplicaModelArtifact, ReplicaOptimisticWriter, ReplicaValue } from '../../types.js';
+export type PureReduceHost = Readonly<{
+    /** Read live cache fields for a known record (pre-layer). Fail-closed on miss. */
+    readRecord?: (model: ReplicaModelArtifact, identity: ReplicaIdentity) => Readonly<Record<string, ReplicaValue>> | undefined;
+    pureFunctions?: Readonly<Record<string, ReplicaPureFunction>>;
+}>;
+/**
+ * Expand pure reducers against known cache rows, then apply ordinary ops.
+ * Missing row / unknown pure / pure null → skip that reduce (no invent).
+ */
+export declare function applyOptimisticEffects(writer: ReplicaOptimisticWriter, effects: readonly PreparedProjectionOperation[], host?: PureReduceHost): void;
 export declare function preparedSemanticChanges<TInput, TOutput>(prepared: ReplicaPreparedCommand<TInput, TOutput>): readonly ReplicaIndexSemanticChange[];
-export declare function modelFromKey(model: string, key: ReplicaPreparedEffectKey): ReplicaModelArtifact;
-export declare function identityFromKey(key: ReplicaPreparedEffectKey): readonly ReplicaValue[];
-export declare function fieldsFromEffect(model: string, key: ReplicaPreparedEffectKey, fields: readonly {
-    readonly field: string;
-    readonly value: ReplicaValue;
-}[]): Readonly<Record<string, ReplicaValue>>;
+/**
+ * Exact record identities whose aggregate-facing command dispatches must retain
+ * invocation order. Optimistic layers still apply immediately; only transport
+ * waits for an earlier command touching the same modeled record to settle.
+ */
+export declare function preparedDispatchKeys<TInput, TOutput>(prepared: ReplicaPreparedCommand<TInput, TOutput>): readonly string[];
+export declare function modelFromKey(scope: PreparedProjectionScope): ReplicaModelArtifact;
+export declare function identityFromKey(key: PreparedProjectionScope): readonly ReplicaValue[];
+export declare function fieldsFromEffect(scope: PreparedProjectionScope, fields: Readonly<Record<string, ReplicaValue>>): Readonly<Record<string, ReplicaValue>>;

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

@@ -1,29 +1,90 @@
 import {} from '../../commands.js';
 import { replicaRecordKey } from '../../identity.js';
-export function applyOptimisticEffects(writer, effects) {
-    for (const effect of effects) {
+/**
+ * Expand pure reducers against known cache rows, then apply ordinary ops.
+ * Missing row / unknown pure / pure null → skip that reduce (no invent).
+ */
+export function applyOptimisticEffects(writer, effects, host = {}) {
+    const expanded = expandReduceKnownRecord(effects, host);
+    for (const effect of expanded) {
         switch (effect.kind) {
             case 'upsert':
             case 'patch': {
-                const model = modelFromKey(effect.model, effect.key);
-                writer.writeRecord(model, identityFromKey(effect.key), {
-                    fields: fieldsFromEffect(effect.model, effect.key, effect.fields)
+                const model = modelFromKey(effect.scope);
+                const fields = fieldsFromEffect(effect.scope, effect.fields);
+                const unset = effect.kind === 'upsert'
+                    ? effect.replace.filter((field) => !Object.hasOwn(effect.fields, field))
+                    : effect.unset;
+                writer.writeRecord(model, identityFromKey(effect.scope), {
+                    fields,
+                    ...(unset.length === 0 ? {} : { unset }),
+                    ...(effect.kind === 'patch' ? { ifPresent: true } : {})
                 });
                 break;
             }
             case 'delete':
-                writer.tombstoneRecord(modelFromKey(effect.model, effect.key), identityFromKey(effect.key));
+                writer.tombstoneRecord(modelFromKey(effect.scope), identityFromKey(effect.scope));
                 break;
             case 'link':
             case 'unlink':
             case 'invalidate_model':
             case 'invalidate_relationship':
+            case 'reduce_known_record':
                 // Task 8 consumes the exact semantic context. Guessing a to-one
                 // record link for a to-many relationship would corrupt truth.
+                // reduce_known_record is expanded above.
                 break;
         }
     }
 }
+function expandReduceKnownRecord(effects, host) {
+    const out = [];
+    for (const effect of effects) {
+        if (effect.kind !== 'reduce_known_record') {
+            out.push(effect);
+            continue;
+        }
+        const pure = host.pureFunctions?.[effect.fn];
+        const read = host.readRecord;
+        if (pure === undefined || read === undefined) {
+            continue;
+        }
+        const model = modelFromKey(effect.scope);
+        const identity = identityFromKey(effect.scope);
+        const current = read(model, identity);
+        if (current === undefined) {
+            continue;
+        }
+        let next;
+        try {
+            next = pure(current, effect.args);
+        }
+        catch {
+            continue;
+        }
+        if (next === null) {
+            continue;
+        }
+        const fields = Object.create(null);
+        for (const field of effect.assign) {
+            if (!Object.prototype.hasOwnProperty.call(next, field)) {
+                continue;
+            }
+            fields[field] = next[field];
+        }
+        if (Object.keys(fields).length === 0) {
+            continue;
+        }
+        out.push(Object.freeze({
+            kind: 'patch',
+            scope: effect.scope,
+            fields: Object.freeze(fields),
+            unset: Object.freeze([]),
+            ifPresent: true
+        }));
+    }
+    return Object.freeze(out);
+}
 export function preparedSemanticChanges(prepared) {
     const dependencies = Object.freeze([...prepared.revalidation.dependencies]);
     const changes = [];
@@ -32,19 +93,20 @@ export function preparedSemanticChanges(prepared) {
             case 'upsert':
             case 'patch':
             case 'delete':
+            case 'reduce_known_record':
                 // DistributedReplica captures ordinary writer mutations into the
                 // same layer context. Supplying them again would double-apply the
-                // semantic record operation.
+                // semantic record operation. Pure reduce expands to patch first.
                 break;
             case 'link':
             case 'unlink': {
-                const source = modelFromKey(effect.relationship.sourceModel, effect.source);
-                const target = modelFromKey(effect.relationship.targetModel, effect.target);
+                const source = modelFromKey(effect.source);
+                const target = modelFromKey(effect.target);
                 changes.push(Object.freeze({
                     kind: effect.kind,
-                    sourceModel: effect.relationship.sourceModel,
-                    field: effect.relationship.field,
-                    targetModel: effect.relationship.targetModel,
+                    sourceModel: effect.source.model,
+                    field: effect.relationship,
+                    targetModel: effect.target.model,
                     sourceKey: replicaRecordKey(source, identityFromKey(effect.source)),
                     targetKey: replicaRecordKey(target, identityFromKey(effect.target)),
                     dependencies
@@ -62,21 +124,57 @@ export function preparedSemanticChanges(prepared) {
     }
     return Object.freeze(changes);
 }
-export function modelFromKey(model, key) {
+/**
+ * Exact record identities whose aggregate-facing command dispatches must retain
+ * invocation order. Optimistic layers still apply immediately; only transport
+ * waits for an earlier command touching the same modeled record to settle.
+ */
+export function preparedDispatchKeys(prepared) {
+    const keys = new Set();
+    const addScope = (scope) => {
+        keys.add(replicaRecordKey(modelFromKey(scope), identityFromKey(scope)));
+    };
+    for (const effect of prepared.optimistic.operations) {
+        switch (effect.kind) {
+            case 'upsert':
+            case 'patch':
+            case 'delete':
+            case 'reduce_known_record':
+                addScope(effect.scope);
+                break;
+            case 'link':
+            case 'unlink':
+                addScope(effect.source);
+                addScope(effect.target);
+                break;
+            case 'invalidate_relationship':
+                addScope(effect.source);
+                break;
+            case 'invalidate_model':
+                /*
+                 * A model invalidation has no compiler-proven aggregate
+                 * identity. It cannot safely participate in a record queue.
+                 */
+                break;
+        }
+    }
+    return Object.freeze([...keys].sort());
+}
+export function modelFromKey(scope) {
     return Object.freeze({
-        id: model,
-        identityFields: Object.freeze(key.fields.map(({ field }) => field))
+        id: scope.model,
+        identityFields: Object.freeze(scope.key.map(({ field }) => field))
     });
 }
 export function identityFromKey(key) {
-    return Object.freeze(key.fields.map(({ value }) => value));
+    return Object.freeze(key.key.map(({ value }) => value));
 }
-export function fieldsFromEffect(model, key, fields) {
+export function fieldsFromEffect(scope, fields) {
     const result = Object.create(null);
     for (const field of [
-        { field: '__typename', value: model },
-        ...key.fields,
-        ...fields
+        { field: '__typename', value: scope.model },
+        ...scope.key,
+        ...Object.entries(fields).map(([field, value]) => ({ field, value }))
     ]) {
         Object.defineProperty(result, field.field, {
             enumerable: true,

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

@@ -2,9 +2,9 @@ import { type DistributedCommandMetadata } from '../../../protocol.js';
 import { type ReplicaPreparedCommand } from '../../commands.js';
 import type { CapturedAuthority, CommandStatusTracker, PendingProjection, ReplicaCommandAuthorityHost, ReplicaCommandProjectedOutcome, ReplicaCommandStatus } from '../types.js';
 export declare function confirmDirectProjection<TInput, TOutput>(replica: ReplicaCommandAuthorityHost, prepared: ReplicaPreparedCommand<TInput, TOutput>, output: TOutput, metadata: DistributedCommandMetadata): void;
-export declare function pendingProjection(authority: CapturedAuthority, metadata: DistributedCommandMetadata, prepared: ReplicaPreparedCommand<unknown, unknown>): PendingProjection;
+export declare function pendingProjection(authority: CapturedAuthority, metadata: DistributedCommandMetadata, prepared: ReplicaPreparedCommand<unknown, unknown>, tracker: CommandStatusTracker): PendingProjection;
 /**
- * Generated fact commands converge without application polling. Durable status
+ * Generated causal commands converge without application polling. Durable status
  * is the only completion signal; timers merely schedule reads and never infer a
  * successful outcome.
  */

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

@@ -31,7 +31,14 @@ export function confirmDirectProjection(replica, prepared, output, metadata) {
         id: direct.model,
         identityFields: direct.identityFields
     });
-    const fields = cloneOutputJson(output, 'projected.output', new Set(), 0);
+    const outputFields = cloneOutputJson(output, 'projected.output', new Set(), 0);
+    const fields = Object.freeze({
+        ...outputFields,
+        // Query normalization always supplies the generated model identity. Atomic
+        // command rows must be canonicalized the same way or a new record remains
+        // incomplete until a later query/reload contributes `__typename`.
+        __typename: direct.model
+    });
     const confirmProtocolProjection = replica[replicaCommandDirectProjection];
     if (confirmProtocolProjection !== undefined) {
         confirmProtocolProjection.call(replica, prepared.commandId, {
@@ -47,7 +54,7 @@ export function confirmDirectProjection(replica, prepared, output, metadata) {
         fields
     }));
 }
-export function pendingProjection(authority, metadata, prepared) {
+export function pendingProjection(authority, metadata, prepared, tracker) {
     let resolve;
     let reject;
     const promise = new Promise((resolvePromise, rejectPromise) => {
@@ -56,7 +63,7 @@ export function pendingProjection(authority, metadata, prepared) {
     });
     /*
      * Authority loss or a terminal status can arrive before application code
-     * receives the accepted receipt. Mark the internal lifecycle promise handled
+     * receives the succeeded receipt. Mark the internal lifecycle promise handled
      * eagerly while preserving its rejection for every explicit awaiter.
      */
     void promise.catch(() => undefined);
@@ -64,6 +71,7 @@ export function pendingProjection(authority, metadata, prepared) {
         commandId: metadata.commandId,
         causationId: metadata.causationId,
         authority,
+        tracker,
         resolve,
         reject,
         promise,
@@ -74,7 +82,7 @@ export function pendingProjection(authority, metadata, prepared) {
     return controller;
 }
 /**
- * Generated fact commands converge without application polling. Durable status
+ * Generated causal commands converge without application polling. Durable status
  * is the only completion signal; timers merely schedule reads and never infer a
  * successful outcome.
  */
@@ -176,7 +184,7 @@ export function settleProjectionSuccess(controller) {
     controller.stopMonitor?.();
     controller.resolve(Object.freeze({
         commandId: controller.commandId,
-        state: 'projected',
+        state: 'atomic',
         metadata: controller.metadata
     }));
 }
@@ -211,7 +219,7 @@ export function callerProjectedPromise(controller, signal) {
             onAbort();
     });
     /*
-     * An AbortSignal can fire during an async `onAccepted` callback, before the
+     * An AbortSignal can fire during an async `onSucceeded` callback, before the
      * receipt reaches caller code. Keep that legitimate rejection observable
      * without creating a process-level unhandled-rejection race.
      */

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

@@ -15,6 +15,8 @@ export function requireStatusEnvelope(result, artifact, prepared, authority, con
         distributed.operation !== artifact.operationHash ||
         distributed.protocolVersion !== authority.scope.protocolVersion ||
         distributed.schemaHash !== authority.scope.schemaHash ||
+        distributed.authorizationGeneration !==
+            authority.scope.authorizationGeneration ||
         distributed.cacheScope !== authority.scope.cacheScope ||
         distributed.snapshot !== undefined ||
         distributed.live !== undefined) {
@@ -57,9 +59,9 @@ export function commandStatusOutput(data) {
     }
     switch (value.state) {
         case 'in_progress':
-        case 'accepted':
-        case 'accepted_pending_projection':
-        case 'projected':
+        case 'succeeded':
+        case 'succeeded_pending_projection':
+        case 'atomic':
         case 'rejected':
         case 'projection_failed':
         case 'expired':
@@ -92,6 +94,12 @@ export function validateStatusProgression(previousState, previous, current) {
         next.consistency !== previous.consistency) {
         throw new Error('command status changed causal identity');
     }
+    if (previous.projectionDisposition === 'revalidate' &&
+        next.projectionDisposition !== 'revalidate') {
+        throw new Error('command status lost projection disposition');
+    }
+    if (next.projectionDisposition === 'revalidate')
+        return;
     if (!(previous.state === 'in_progress' &&
         previous.expects.length === 0) &&
         !sameStringMultiset(previous.expects.map(projectionExpectationFingerprint), next.expects.map(projectionExpectationFingerprint))) {
@@ -108,15 +116,15 @@ export function isStatusTransition(previous, next) {
             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' ||
+        case 'succeeded':
+            return next === 'succeeded' || next === 'expired';
+        case 'succeeded_pending_projection':
+            return (next === 'succeeded_pending_projection' ||
+                next === 'atomic' ||
                 next === 'projection_failed' ||
                 next === 'expired');
-        case 'projected':
-            return next === 'projected' || next === 'expired';
+        case 'atomic':
+            return next === 'atomic' || next === 'expired';
         case 'rejected':
             return next === 'rejected' || next === 'expired';
         case 'projection_failed':

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

@@ -70,6 +70,8 @@ export function requireCommandEnvelope(result, prepared, authority) {
         distributed.operation !== prepared.transport.operationHash ||
         distributed.protocolVersion !== authority.scope.protocolVersion ||
         distributed.schemaHash !== authority.scope.schemaHash ||
+        distributed.authorizationGeneration !==
+            authority.scope.authorizationGeneration ||
         distributed.cacheScope !== authority.scope.cacheScope) {
         throw new Error('command response does not match its generated scope');
     }
@@ -94,6 +96,8 @@ export function requireCommandRejectionEnvelope(result, prepared, authority) {
         distributed.operation !== prepared.transport.operationHash ||
         distributed.protocolVersion !== authority.scope.protocolVersion ||
         distributed.schemaHash !== authority.scope.schemaHash ||
+        distributed.authorizationGeneration !==
+            authority.scope.authorizationGeneration ||
         distributed.cacheScope !== authority.scope.cacheScope) {
         throw new Error('command rejection does not match its generated scope');
     }

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

@@ -14,12 +14,14 @@ export function cloneScope(scope) {
     return Object.freeze({
         protocolVersion: 1,
         schemaHash: scope.schemaHash,
+        authorizationGeneration: scope.authorizationGeneration,
         cacheScope: scope.cacheScope
     });
 }
 export function sameScope(left, right) {
     return (left.protocolVersion === right.protocolVersion &&
         left.schemaHash === right.schemaHash &&
+        left.authorizationGeneration === right.authorizationGeneration &&
         left.cacheScope === right.cacheScope);
 }
 export function sameSurface(left, right) {
@@ -30,8 +32,10 @@ export function sameSurface(left, right) {
     }
     return (left.kind === 'role' ||
         (right.kind === 'application' &&
-            left.roles.length === right.roles.length &&
-            left.roles.every((role, index) => role === right.roles[index])));
+            left.eligible_roles.length === right.eligible_roles.length &&
+            left.eligible_roles.every((role, index) => role === right.eligible_roles[index]) &&
+            left.schema_roles.length === right.schema_roles.length &&
+            left.schema_roles.every((role, index) => role === right.schema_roles[index])));
 }
 export function cloneSurface(surface) {
     return surface.kind === 'role'
@@ -39,7 +43,8 @@ export function cloneSurface(surface) {
         : Object.freeze({
             kind: 'application',
             name: surface.name,
-            roles: Object.freeze([...surface.roles])
+            eligible_roles: Object.freeze([...surface.eligible_roles]),
+            schema_roles: Object.freeze([...surface.schema_roles])
         });
 }
 export function linkAbortSignals(signals) {

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

@@ -26,5 +26,14 @@ export declare const replicaResultObservation: unique symbol;
  * @internal
  */
 export declare const replicaCommandDirectProjection: unique symbol;
+/** @internal Atomic preview-to-actual optimistic layer replacement. */
+export declare const replicaCommandProjectionDelta: unique symbol;
 /** @internal Package-private; intentionally absent from the public barrel. */
 export declare const replicaCommandProjectedLifecycle: unique symbol;
+/**
+ * Package-private live-record field read for pure reduce optimism.
+ * Returns undefined when the record is not present (fail closed).
+ *
+ * @internal
+ */
+export declare const replicaCommandReadRecord: unique symbol;

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

@@ -26,5 +26,14 @@ export const replicaResultObservation = Symbol('distributed.replica.result-obser
  * @internal
  */
 export const replicaCommandDirectProjection = Symbol('distributed.replica.command-direct-projection');
+/** @internal Atomic preview-to-actual optimistic layer replacement. */
+export const replicaCommandProjectionDelta = Symbol('distributed.replica.command-projection-delta');
 /** @internal Package-private; intentionally absent from the public barrel. */
 export const replicaCommandProjectedLifecycle = Symbol('distributed.replica.command-projected-lifecycle');
+/**
+ * Package-private live-record field read for pure reduce optimism.
+ * Returns undefined when the record is not present (fail closed).
+ *
+ * @internal
+ */
+export const replicaCommandReadRecord = Symbol('distributed.replica.command-read-record');

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

@@ -4,7 +4,8 @@ import type { PrepareReplicaCommandOptions, ReplicaCommandArtifact, ReplicaPrepa
 import type { ReplicaDiagnosticsSink } from '../diagnostics.js';
 import type { ReplicaIndexSemanticChange } from '../index-maintenance.js';
 import type { DistributedReplica, ReplicaAuthoritativeScope, ReplicaClientSurface, ReplicaIdentity, ReplicaModelArtifact, ReplicaOptimisticWriter, ReplicaResultEnvelope, ReplicaValue } from '../types.js';
-import { replicaCommandAuthority, replicaCommandDirectProjection, replicaCommandProjectedLifecycle, replicaResultObservation } from './symbols.js';
+import type { ReplicaPureFunction } from '../projection-delta/index.js';
+import { replicaCommandAuthority, replicaCommandDirectProjection, replicaCommandProjectionDelta, replicaCommandProjectedLifecycle, replicaCommandReadRecord, replicaResultObservation } from './symbols.js';
 export type ReplicaCommandSurfaceContract = Readonly<{
     protocolVersion: 1;
     schemaHash: string;
@@ -36,6 +37,8 @@ export type ReplicaCommandAuthorityHost = DistributedReplica & {
     readonly [replicaCommandAuthority]?: (contract: ReplicaCommandSurfaceContract) => ReplicaCommandAuthorityRegistration;
     readonly [replicaResultObservation]?: (observer: (envelope: ReplicaResultEnvelope<unknown>) => void) => ReplicaResultObservationRegistration;
     readonly [replicaCommandDirectProjection]?: (commandId: string, projection: ReplicaCommandDirectProjection) => void;
+    readonly [replicaCommandProjectionDelta]?: (commandId: string, update: (writer: ReplicaOptimisticWriter) => void, semanticChanges: readonly ReplicaIndexSemanticChange[]) => boolean;
+    readonly [replicaCommandReadRecord]?: (model: ReplicaModelArtifact, identity: ReplicaIdentity) => Readonly<Record<string, ReplicaValue>> | undefined;
 };
 export type ReplicaCommandTransportRequest = Readonly<{
     operation: 'mutation';
@@ -87,8 +90,8 @@ export interface ReplicaCommandTransport {
 }
 export type ReplicaCommandProjectedOutcome<TOutput> = Readonly<{
     commandId: string;
-    state: 'projected';
-    /** Present for same-transaction Projected<T>, absent for async facts. */
+    state: 'atomic';
+    /** Present for same-transaction Atomic<T>, absent for async facts. */
     result?: TOutput;
     metadata?: DistributedCommandMetadata;
 }>;
@@ -103,14 +106,14 @@ export type ReplicaCommandStatus = Readonly<{
 }>;
 export type ReplicaCommandReceipt<TOutput> = Readonly<{
     commandId: string;
-    state: Extract<DistributedCommandState, 'accepted' | 'accepted_pending_projection' | 'projected'>;
+    state: Extract<DistributedCommandState, 'succeeded' | 'succeeded_pending_projection' | 'atomic'>;
     /** Typed application payload returned by the generated mutation. */
     result: TOutput;
     metadata: DistributedCommandMetadata;
     /** One exact generated status read. Calls coalesce while in flight. */
     status(): Promise<ReplicaCommandStatus>;
     /**
-     * Causal visibility awaitable. It is omitted when no finite projection
+     * Eventual visibility awaitable. It is omitted when no finite projection
      * contract exists and never resolves because a wall-clock timer elapsed.
      */
     projected?: Promise<ReplicaCommandProjectedOutcome<TOutput>>;
@@ -149,7 +152,7 @@ export type ReplicaCommandCallOptions<TOutput> = PrepareReplicaCommandOptions &
     signal?: AbortSignal;
     /** Exact same prepared request retries after thrown/ambiguous transport. */
     transportRetries?: number;
-    onAccepted?: (receipt: ReplicaCommandReceipt<TOutput>) => void | Promise<void>;
+    onSucceeded?: (receipt: ReplicaCommandReceipt<TOutput>) => void | Promise<void>;
 }>;
 export type ReplicaCommandRuntimeErrorCode = 'REPLICA_COMMAND_ABORTED' | 'REPLICA_COMMAND_AUTHORITY_UNAVAILABLE' | 'REPLICA_COMMAND_DISPOSED' | 'REPLICA_COMMAND_OUTCOME_PENDING' | 'REPLICA_COMMAND_PROJECTION_FAILED' | 'REPLICA_COMMAND_PROTOCOL_INVALID' | 'REPLICA_COMMAND_REJECTED' | 'REPLICA_COMMAND_SCOPE_INVALIDATED' | 'REPLICA_COMMAND_STATUS_UNAVAILABLE' | 'REPLICA_COMMAND_TRANSPORT_AMBIGUOUS';
 export type AnyCommandArtifact = ReplicaCommandArtifact<unknown, unknown>;
@@ -180,6 +183,11 @@ export type ReplicaCommandRuntimeOptions = Readonly<{
     status?: ReplicaCommandStatusArtifact;
     /** Optional shared replica diagnostics sink used only for static artifact inspection. */
     diagnostics?: ReplicaDiagnosticsSink;
+    /**
+     * Named pure functions referenced by `artifact.projection.pureReduces`.
+     * Generated clients ship their inventory; apps do not invent board sims ad hoc.
+     */
+    pureFunctions?: Readonly<Record<string, ReplicaPureFunction>>;
 }>;
 export interface ReplicaCommandRuntime<TEntries extends Readonly<Record<string, CommandEntry>>> {
     readonly commands: ReplicaBoundCommands<TEntries>;
@@ -202,6 +210,7 @@ export type PendingProjection = {
     readonly commandId: string;
     readonly causationId: string;
     readonly authority: CapturedAuthority;
+    readonly tracker: CommandStatusTracker;
     readonly resolve: (value: ReplicaCommandProjectedOutcome<unknown>) => void;
     readonly reject: (error: unknown) => void;
     readonly promise: Promise<ReplicaCommandProjectedOutcome<unknown>>;

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

@@ -1 +1 @@
-import { replicaCommandAuthority, replicaCommandDirectProjection, replicaCommandProjectedLifecycle, replicaResultObservation } from './symbols.js';
+import { replicaCommandAuthority, replicaCommandDirectProjection, replicaCommandProjectionDelta, replicaCommandProjectedLifecycle, replicaCommandReadRecord, replicaResultObservation } from './symbols.js';

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

@@ -1,3 +1,3 @@
 /** Public entry for command runtime; implementation lives in ./command-runtime/. */
-export { createReplicaCommandRuntime, ReplicaCommandRuntimeError, replicaCommandAuthority, replicaCommandDirectProjection, replicaCommandProjectedLifecycle, replicaCommandProjectedLifecycleOf, replicaResultObservation } from './command-runtime/index.js';
+export { createReplicaCommandRuntime, ReplicaCommandRuntimeError, replicaCommandAuthority, replicaCommandDirectProjection, replicaCommandProjectionDelta, replicaCommandProjectedLifecycle, replicaCommandProjectedLifecycleOf, replicaCommandReadRecord, replicaResultObservation } from './command-runtime/index.js';
 export type { ReplicaBoundCommand, ReplicaBoundCommands, ReplicaCommandAuthorityHost, ReplicaCommandAuthorityRegistration, ReplicaCommandAuthoritySnapshot, ReplicaCommandCallOptions, ReplicaCommandDirectProjection, ReplicaCommandProjectedOutcome, ReplicaCommandReceipt, ReplicaCommandRecoveryReceipt, ReplicaCommandRuntime, ReplicaCommandRuntimeErrorCode, ReplicaCommandRuntimeOptions, ReplicaCommandStatus, ReplicaCommandStatusArtifact, ReplicaCommandStatusRequest, ReplicaCommandSurfaceContract, ReplicaCommandTransport, ReplicaCommandTransportRequest, ReplicaCommandTransportResult, ReplicaResultObservationRegistration } from './command-runtime/index.js';

package/dist/replica/command-runtime.js

@@ -1,2 +1,2 @@
 /** Public entry for command runtime; implementation lives in ./command-runtime/. */
-export { createReplicaCommandRuntime, ReplicaCommandRuntimeError, replicaCommandAuthority, replicaCommandDirectProjection, replicaCommandProjectedLifecycle, replicaCommandProjectedLifecycleOf, replicaResultObservation } from './command-runtime/index.js';
+export { createReplicaCommandRuntime, ReplicaCommandRuntimeError, replicaCommandAuthority, replicaCommandDirectProjection, replicaCommandProjectionDelta, replicaCommandProjectedLifecycle, replicaCommandProjectedLifecycleOf, replicaCommandReadRecord, replicaResultObservation } from './command-runtime/index.js';

package/dist/replica/commands/clone.js

@@ -8,7 +8,8 @@ export function cloneClientSurface(surface) {
         : Object.freeze({
             kind: 'application',
             name: surface.name,
-            roles: Object.freeze([...surface.roles])
+            eligible_roles: Object.freeze([...surface.eligible_roles]),
+            schema_roles: Object.freeze([...surface.schema_roles])
         });
 }
 export function cloneTrustedPresetDescriptors(value) {

package/dist/replica/commands/index.d.ts

@@ -3,3 +3,4 @@ export { matchReplicaTrustedPresetInventory } from './presets.js';
 export { verifyReplicaCommandReceipt } from './receipt.js';
 export { ReplicaCommandContractError } from './errors.js';
 export type { PrepareReplicaCommandOptions, ReplicaCommandArtifact, ReplicaCommandConfirmation, ReplicaCommandConfirmations, ReplicaCommandContractErrorCode, ReplicaCommandDirectProjection, ReplicaCommandEffect, ReplicaCommandEffectExpression, ReplicaCommandEffectField, ReplicaCommandEffectKey, ReplicaCommandEffectRelationship, ReplicaCommandEffects, ReplicaCommandGenerators, ReplicaCommandInputDefault, ReplicaCommandInputDefaults, ReplicaCommandRevalidationPlan, ReplicaCommandScalarCodec, ReplicaCommandShape, ReplicaCommandTypeDefinition, ReplicaCommandTypeField, ReplicaCommandVariables, ReplicaMatchedTrustedPresetInventory, ReplicaPreparedCommand, ReplicaPreparedCommandEffect, ReplicaPreparedConfirmation, ReplicaPreparedConfirmations, ReplicaPreparedEffectField, ReplicaPreparedEffectKey, ReplicaReceiptVerification, ReplicaTrustedPresetDescriptor } from './types.js';
+export type { PreparedCommandProjection, PreparedProjectionOperation, ReplicaCommandProjection } from '../projection-delta/index.js';

package/dist/replica/commands/prepare.js

@@ -1,7 +1,8 @@
 import { createReplicaCommandId } from '../command-id.js';
 import { validateArtifact } from './validate.js';
 import { selectReplicaTrustedPresetInventory } from './presets.js';
-import { materializeInput, resolveConfirmations, resolveDirectProjection, resolveEffect } from './resolve.js';
+import { materializeInput, resolveDirectProjection } from './resolve.js';
+import { prepareCommandProjection, validateCommandProjectionArtifact } from '../projection-delta/index.js';
 import { cloneClientSurface, cloneRevalidation, cloneTrustedPresetDescriptors } from './clone.js';
 import { validateUuidV7 } from './util.js';
 export function prepareReplicaCommand(artifact, input, options = {}) {
@@ -36,8 +37,10 @@ export function prepareReplicaCommandInternal(artifact, input, options, authorit
         commandId,
         ...(artifact.input.kind === 'none' ? {} : { input: finalizedInput })
     });
-    const operations = Object.freeze(artifact.effects.operations.map((effect, index) => resolveEffect(effect, finalizedInput, `artifact.effects.operations[${index}]`, trustedPresets)));
-    const confirmations = resolveConfirmations(artifact.confirmations, finalizedInput, trustedPresets);
+    const projection = artifact.projection === undefined
+        ? undefined
+        : prepareCommandProjection(validateCommandProjectionArtifact(artifact.projection), finalizedInput, trustedPresets?.values ?? []);
+    const operations = projection?.preview ?? Object.freeze([]);
     const directProjection = resolveDirectProjection(artifact.directProjection, finalizedInput, trustedPresets);
     const protocol = Object.freeze({
         ...artifact.protocol,
@@ -62,7 +65,7 @@ export function prepareReplicaCommandInternal(artifact, input, options, authorit
             operations,
             fallback: 'revalidate'
         }),
-        ...(confirmations === undefined ? {} : { confirmations }),
+        ...(projection === undefined ? {} : { projection }),
         ...(directProjection === undefined ? {} : { directProjection }),
         revalidation
     });