@hops-ops/distributed 0.0.0 → 4.0.1

package/dist/replica/distributed-replica/impl-diagnostics.d.ts

@@ -19,4 +19,4 @@ export declare function syncDiagnostics(host: DiagnosticsHost): void;
 export declare function diagnosticEvent(host: DiagnosticsHost, event: ReplicaDiagnosticEventInput): void;
 export declare function diagnosticOperation<TData, TVariables extends GraphqlVariables>(host: DiagnosticsHost, artifact: ReplicaOperationArtifact<TData, TVariables>): void;
 export declare function diagnosticScopeTransition(host: DiagnosticsHost, previous: ProtocolGeneration | undefined, next: ProtocolGeneration): void;
-export declare function retireDiagnosticLayer(host: DiagnosticsHost, id: string, action: 'retired' | 'rejected', receiptState: 'projected' | 'rejected', receipt?: OptimisticReceiptState): void;
+export declare function retireDiagnosticLayer(host: DiagnosticsHost, id: string, action: 'retired' | 'rejected', receiptState: 'atomic' | 'rejected', receipt?: OptimisticReceiptState): void;

package/dist/replica/distributed-replica/impl-diagnostics.js

@@ -85,8 +85,8 @@ export function syncDiagnostics(host) {
                 state: receipt === undefined
                     ? 'optimistic'
                     : receipt.expectations.size === 0
-                        ? 'accepted'
-                        : 'accepted_pending_projection',
+                        ? 'succeeded'
+                        : 'succeeded_pending_projection',
                 expectations: receipt === undefined
                     ? Object.freeze([])
                     : diagnosticReceiptExpectations(receipt)
@@ -142,7 +142,8 @@ export function diagnosticScopeTransition(host, previous, next) {
         return;
     if (previous !== undefined &&
         previous.cacheScope === next.cacheScope &&
-        previous.schemaHash === next.schemaHash) {
+        previous.schemaHash === next.schemaHash &&
+        previous.authorizationGeneration === next.authorizationGeneration) {
         return;
     }
     diagnosticEvent(host, Object.freeze({

package/dist/replica/distributed-replica/impl-hydration-orchestrate.d.ts

@@ -1,5 +1,5 @@
 import { type CacheEngine, type CacheEngineSnapshot } from '../../internal/cache-engine.js';
-import type { DistributedOpaqueString, DistributedTrustedPreset } from '../../protocol.js';
+import { type DistributedOpaqueString, type DistributedTrustedPreset } from '../../protocol.js';
 import type { ReplicaDiagnosticEventInput } from '../diagnostics.js';
 import type { ReplicaIndexPlanRegistration } from '../index-maintenance.js';
 import type { ReplicaAuthoritativeScope, ReplicaDehydratedState } from '../types.js';

package/dist/replica/distributed-replica/impl-hydration-orchestrate.js

@@ -1,4 +1,5 @@
 import { createCacheEngine } from '../../internal/cache-engine.js';
+import { compareDistributedDecimal } from '../../protocol.js';
 import { matchReplicaTrustedPresetInventory } from '../commands.js';
 import { replicaIndexKey, resolveArguments } from '../identity.js';
 import { runtimeRoot } from '../selection.js';
@@ -170,6 +171,7 @@ export function dehydrateReplica(host) {
         scope: Object.freeze({
             protocolVersion: 1,
             schemaHash: scope.schemaHash,
+            authorizationGeneration: scope.authorizationGeneration,
             cacheScope: scope.cacheScope
         }),
         payload
@@ -191,6 +193,8 @@ export function hydrateReplica(host, state, authoritativeScope) {
     }
     if (parsed.scope.protocolVersion !== expectedScope.protocolVersion ||
         parsed.scope.schemaHash !== expectedScope.schemaHash ||
+        parsed.scope.authorizationGeneration !==
+            expectedScope.authorizationGeneration ||
         parsed.scope.cacheScope !== expectedScope.cacheScope) {
         return rejected('scope-mismatch');
     }
@@ -203,6 +207,8 @@ export function hydrateReplica(host, state, authoritativeScope) {
     if (current !== undefined &&
         (current.protocolVersion !== parsed.scope.protocolVersion ||
             current.schemaHash !== parsed.scope.schemaHash ||
+            current.authorizationGeneration !==
+                parsed.scope.authorizationGeneration ||
             current.cacheScope !== parsed.scope.cacheScope)) {
         return rejected('active-scope-mismatch');
     }
@@ -230,54 +236,82 @@ export function hydrateReplica(host, state, authoritativeScope) {
         return rejected('metadata-mismatch');
     }
     if (preserveLocalCommandState) {
+        // Warm same-scope re-hydrate (soft nav / second SSR seed): keep confirmed
+        // records and indexes the route seed omitted. Seed keys upsert; purge only
+        // happens on auth/scope change (closeAuthorizationGeneration path).
         host.closeActiveTransports();
+        host.queryStates.clear();
+        for (const [key, group] of parsed.operationProtocols) {
+            host.operationProtocols.set(key, group);
+        }
+        for (const [key, generation] of parsed.operationGenerations) {
+            host.operationGenerations.set(key, generation);
+        }
+        for (const [key, clock] of parsed.recordClocks) {
+            host.recordClocks.set(key, clock);
+        }
+        for (const [scopeToken, key] of parsed.recordKeysByScope) {
+            host.recordKeysByScope.set(scopeToken, key);
+        }
+        for (const [scopeToken, clock] of parsed.anonymousRecordClocks) {
+            host.anonymousRecordClocks.set(scopeToken, clock);
+        }
+        host.setTrustedPresets(parsed.trustedPresets);
+        if (compareDistributedDecimal(parsed.nextIndexRevision, host.getNextIndexRevision()) > 0) {
+            host.setNextIndexRevision(parsed.nextIndexRevision);
+        }
+        host.setProtocolGeneration(parsed.scope);
+        host.setArtifactBinding(Object.freeze({
+            version: 1,
+            schemaHash: parsed.scope.schemaHash,
+            ...(binding?.surfaceIdentity !== undefined
+                ? { surfaceIdentity: binding.surfaceIdentity }
+                : {}),
+            ...(binding?.trustedPresets !== undefined
+                ? { trustedPresets: binding.trustedPresets }
+                : {})
+        }));
+        host.engine.mergeConfirmed(parsed.cache);
     }
     else {
         host.closeAuthorizationGeneration();
-    }
-    host.queryStates.clear();
-    host.operationProtocols.clear();
-    for (const [key, group] of parsed.operationProtocols) {
-        host.operationProtocols.set(key, group);
-    }
-    host.operationGenerations.clear();
-    for (const [key, generation] of parsed.operationGenerations) {
-        host.operationGenerations.set(key, generation);
-    }
-    host.recordClocks.clear();
-    for (const [key, clock] of parsed.recordClocks) {
-        host.recordClocks.set(key, clock);
-    }
-    host.recordKeysByScope.clear();
-    for (const [scopeToken, key] of parsed.recordKeysByScope) {
-        host.recordKeysByScope.set(scopeToken, key);
-    }
-    host.anonymousRecordClocks.clear();
-    for (const [scopeToken, clock] of parsed.anonymousRecordClocks) {
-        host.anonymousRecordClocks.set(scopeToken, clock);
-    }
-    if (!preserveLocalCommandState) {
+        host.queryStates.clear();
+        host.operationProtocols.clear();
+        for (const [key, group] of parsed.operationProtocols) {
+            host.operationProtocols.set(key, group);
+        }
+        host.operationGenerations.clear();
+        for (const [key, generation] of parsed.operationGenerations) {
+            host.operationGenerations.set(key, generation);
+        }
+        host.recordClocks.clear();
+        for (const [key, clock] of parsed.recordClocks) {
+            host.recordClocks.set(key, clock);
+        }
+        host.recordKeysByScope.clear();
+        for (const [scopeToken, key] of parsed.recordKeysByScope) {
+            host.recordKeysByScope.set(scopeToken, key);
+        }
+        host.anonymousRecordClocks.clear();
+        for (const [scopeToken, clock] of parsed.anonymousRecordClocks) {
+            host.anonymousRecordClocks.set(scopeToken, clock);
+        }
         host.optimisticReceipts.clear();
         host.diagnosticLayers?.clear();
         host.setDiagnosticLayerSequence(0);
-    }
-    host.setTrustedPresets(parsed.trustedPresets);
-    host.setNextIndexRevision(parsed.nextIndexRevision);
-    host.setProtocolGeneration(parsed.scope);
-    host.setArtifactBinding(Object.freeze({
-        version: 1,
-        schemaHash: parsed.scope.schemaHash,
-        ...(binding?.surfaceIdentity !== undefined
-            ? { surfaceIdentity: binding.surfaceIdentity }
-            : {}),
-        ...(binding?.trustedPresets !== undefined
-            ? { trustedPresets: binding.trustedPresets }
-            : {})
-    }));
-    if (preserveLocalCommandState) {
-        host.engine.restoreConfirmed(parsed.cache);
-    }
-    else {
+        host.setTrustedPresets(parsed.trustedPresets);
+        host.setNextIndexRevision(parsed.nextIndexRevision);
+        host.setProtocolGeneration(parsed.scope);
+        host.setArtifactBinding(Object.freeze({
+            version: 1,
+            schemaHash: parsed.scope.schemaHash,
+            ...(binding?.surfaceIdentity !== undefined
+                ? { surfaceIdentity: binding.surfaceIdentity }
+                : {}),
+            ...(binding?.trustedPresets !== undefined
+                ? { trustedPresets: binding.trustedPresets }
+                : {})
+        }));
         host.engine.restore(parsed.cache);
     }
     host.resumeLiveWatches();
@@ -286,7 +320,7 @@ export function hydrateReplica(host, state, authoritativeScope) {
         host.diagnosticEvent(Object.freeze({
             kind: 'hydration',
             action: 'accepted',
-            reason: 'accepted'
+            reason: preserveLocalCommandState ? 'same-scope-merge' : 'accepted'
         }));
         host.diagnosticEvent(Object.freeze({
             kind: 'scope',

package/dist/replica/distributed-replica/impl-optimistic.d.ts

@@ -1,4 +1,4 @@
-import type { CacheEngine } from '../../internal/cache-engine.js';
+import type { CacheEngine, OptimisticLayerReplacement } from '../../internal/cache-engine.js';
 import { type DistributedCommandMetadata, type DistributedProjectionObservation } from '../../protocol.js';
 import type { ReplicaDiagnosticEventInput, ReplicaDiagnosticLayerInput } from '../diagnostics.js';
 import type { ReplicaIndexSemanticChange } from '../index-maintenance.js';
@@ -18,9 +18,18 @@ export type OptimisticHost = {
     setDiagnosticLayerSequence(value: number): void;
     diagnosticEvent(event: ReplicaDiagnosticEventInput): void;
     syncDiagnostics(): void;
-    retireDiagnosticLayer(id: string, action: 'retired' | 'rejected', receiptState: 'projected' | 'rejected', receipt?: OptimisticReceiptState): void;
+    retireDiagnosticLayer(id: string, action: 'retired' | 'rejected', receiptState: 'atomic' | 'rejected', receipt?: OptimisticReceiptState): void;
 };
 export declare function createOptimisticLayerOn(host: OptimisticHost, id: string, update: (writer: ReplicaOptimisticWriter) => void, semanticChanges?: readonly ReplicaIndexSemanticChange[]): void;
+/**
+ * Package-private correction seam for projection-aware command runtimes.
+ *
+ * Receipts and diagnostics remain attached to the stable layer identity. The
+ * cache engine owns atomic prefix evaluation and preserves the layer context.
+ */
+export declare function replaceOptimisticLayerOn(host: OptimisticHost, id: string, replacement: OptimisticLayerReplacement, context?: import('../../internal/cache-engine.js').OptimisticLayerContext): boolean;
+/** Atomically replace both record operations and semantic index context. */
+export declare function replaceReplicaOptimisticLayerOn(host: OptimisticHost, id: string, update: (writer: ReplicaOptimisticWriter) => void, semanticChanges: readonly ReplicaIndexSemanticChange[]): boolean;
 export declare function markOptimisticLayerAcceptedOn(host: OptimisticHost, id: string, receipt?: DistributedCommandMetadata): boolean;
 export declare function confirmOptimisticLayerOn<T>(host: OptimisticHost, id: string, update: (writer: ReplicaBaseWriter) => T): T;
 export declare function rejectOptimisticLayerOn(host: OptimisticHost, id: string): boolean;

package/dist/replica/distributed-replica/impl-optimistic.js

@@ -44,6 +44,22 @@ export function createOptimisticLayerOn(host, id, update, semanticChanges = Obje
         host.syncDiagnostics();
     }
 }
+/**
+ * Package-private correction seam for projection-aware command runtimes.
+ *
+ * Receipts and diagnostics remain attached to the stable layer identity. The
+ * cache engine owns atomic prefix evaluation and preserves the layer context.
+ */
+export function replaceOptimisticLayerOn(host, id, replacement, context) {
+    assertReplicaOptimisticLayerId(id);
+    return host.engine.replaceOptimisticLayer(id, replacement, context);
+}
+/** Atomically replace both record operations and semantic index context. */
+export function replaceReplicaOptimisticLayerOn(host, id, update, semanticChanges) {
+    assertReplicaOptimisticLayerId(id);
+    const captured = captureReplicaOptimisticUpdate(id, update, semanticChanges);
+    return host.engine.replaceOptimisticLayer(id, (_reader, writer) => replayReplicaOptimisticUpdate(writer, captured.operations), captured.context);
+}
 export function markOptimisticLayerAcceptedOn(host, id, receipt) {
     if (receipt !== undefined && receipt.commandId !== id) {
         throw new TypeError('optimistic layer id must equal the causal command id');
@@ -67,7 +83,7 @@ export function markOptimisticLayerAcceptedOn(host, id, receipt) {
             host.diagnosticEvent(Object.freeze({
                 kind: 'receipt',
                 command: id,
-                state: 'accepted',
+                state: 'succeeded',
                 obligations: 0,
                 observed: 0
             }));
@@ -87,8 +103,8 @@ export function markOptimisticLayerAcceptedOn(host, id, receipt) {
             kind: 'receipt',
             command: id,
             state: counts.obligations === 0
-                ? 'accepted'
-                : 'accepted_pending_projection',
+                ? 'succeeded'
+                : 'succeeded_pending_projection',
             obligations: counts.obligations,
             observed: counts.observed
         }));
@@ -98,7 +114,7 @@ export function markOptimisticLayerAcceptedOn(host, id, receipt) {
 }
 export function confirmOptimisticLayerOn(host, id, update) {
     const result = host.engine.confirmOptimisticLayer(id, (writer) => update(baseWriter(writer)));
-    host.retireDiagnosticLayer(id, 'retired', 'projected');
+    host.retireDiagnosticLayer(id, 'retired', 'atomic');
     host.optimisticReceipts.delete(id);
     host.syncDiagnostics();
     return result;
@@ -162,8 +178,8 @@ export function applyReceiptOnly(host, command) {
                 kind: 'receipt',
                 command: id,
                 state: counts.obligations === 0
-                    ? 'accepted'
-                    : 'accepted_pending_projection',
+                    ? 'succeeded'
+                    : 'succeeded_pending_projection',
                 obligations: counts.obligations,
                 observed: counts.observed
             }));

package/dist/replica/distributed-replica/impl-protocol.js

@@ -25,13 +25,15 @@ export function stageProtocolGeneration(host, envelope) {
     const next = {
         protocolVersion: 1,
         cacheScope: envelope.cacheScope,
-        schemaHash: envelope.schemaHash
+        schemaHash: envelope.schemaHash,
+        authorizationGeneration: envelope.authorizationGeneration
     };
     const current = host.getProtocolGeneration();
     if (current === undefined)
         return next;
     if (current.cacheScope === next.cacheScope &&
-        current.schemaHash === next.schemaHash) {
+        current.schemaHash === next.schemaHash &&
+        current.authorizationGeneration === next.authorizationGeneration) {
         return current;
     }
     purgeProtocolGeneration(host);

package/dist/replica/distributed-replica/impl.d.ts

@@ -1,9 +1,9 @@
 import type { GraphqlVariables } from '../../types.js';
 import { type DistributedCommandMetadata } from '../../protocol.js';
-import { replicaCommandAuthority, replicaCommandDirectProjection, replicaResultObservation, type ReplicaCommandAuthorityRegistration, type ReplicaCommandDirectProjection, type ReplicaCommandSurfaceContract, type ReplicaResultObservationRegistration } from '../command-runtime.js';
+import { replicaCommandAuthority, replicaCommandDirectProjection, replicaCommandProjectionDelta, replicaCommandReadRecord, replicaResultObservation, type ReplicaCommandAuthorityRegistration, type ReplicaCommandDirectProjection, type ReplicaCommandSurfaceContract, type ReplicaResultObservationRegistration } from '../command-runtime.js';
 import { type MaterializedReplicaResult } from '../materialize.js';
 import { type ReplicaIndexSemanticChange } from '../index-maintenance.js';
-import type { DistributedReplicaOptions, DistributedReplica as DistributedReplicaApi, ReplicaAuthoritativeScope, ReplicaBaseWriter, ReplicaDehydratedState, ReplicaIdentity, ReplicaIndexInspection, ReplicaIndexTarget, ReplicaModelArtifact, ReplicaOperationArtifact, ReplicaOptimisticWriter, ReplicaRecordInspection, ReplicaRevalidationPlan, ReplicaRevision, ReplicaResultEnvelope, ReplicaSnapshot, ReplicaWatch, ReplicaWriteSource, WatchReplicaOptions } from '../types.js';
+import type { DistributedReplicaOptions, DistributedReplica as DistributedReplicaApi, ReplicaAuthoritativeScope, ReplicaBaseWriter, ReplicaDehydratedState, ReplicaIdentity, ReplicaIndexInspection, ReplicaIndexTarget, ReplicaModelArtifact, ReplicaOperationArtifact, ReplicaOptimisticWriter, ReplicaRecordInspection, ReplicaRevalidationPlan, ReplicaRevision, ReplicaResultEnvelope, ReplicaSnapshot, ReplicaValue, ReplicaWatch, ReplicaWriteSource, WatchReplicaOptions } from '../types.js';
 import type { QueryState } from './types.js';
 import { ReplicaWatchState } from './watch.js';
 export declare class DistributedReplicaImpl implements DistributedReplicaApi {
@@ -14,6 +14,7 @@ export declare class DistributedReplicaImpl implements DistributedReplicaApi {
     [replicaCommandAuthority](contract: ReplicaCommandSurfaceContract): ReplicaCommandAuthorityRegistration;
     [replicaResultObservation](observer: (envelope: ReplicaResultEnvelope<unknown>) => void): ReplicaResultObservationRegistration;
     [replicaCommandDirectProjection](commandId: string, projection: ReplicaCommandDirectProjection): void;
+    [replicaCommandProjectionDelta](commandId: string, update: (writer: ReplicaOptimisticWriter) => void, semanticChanges: readonly ReplicaIndexSemanticChange[]): boolean;
     read<TData, TVariables extends GraphqlVariables>(artifact: ReplicaOperationArtifact<TData, TVariables>, variables: TVariables): ReplicaSnapshot<TData>;
     watch<TData, TVariables extends GraphqlVariables>(artifact: ReplicaOperationArtifact<TData, TVariables>, variables: TVariables, options?: WatchReplicaOptions): ReplicaWatch<TData>;
     writeResult<TData, TVariables extends GraphqlVariables>(artifact: ReplicaOperationArtifact<TData, TVariables>, variables: TVariables, envelope: ReplicaResultEnvelope<TData>, source: ReplicaWriteSource): void;
@@ -31,6 +32,11 @@ export declare class DistributedReplicaImpl implements DistributedReplicaApi {
     releaseRecord(model: ReplicaModelArtifact, identity: ReplicaIdentity): void;
     gc(): readonly string[];
     inspectRecord(model: ReplicaModelArtifact, identity: ReplicaIdentity): ReplicaRecordInspection | undefined;
+    /**
+     * Package-private live fields for pure-reduce optimism.
+     * @internal
+     */
+    [replicaCommandReadRecord](model: ReplicaModelArtifact, identity: ReplicaIdentity): Readonly<Record<string, ReplicaValue>> | undefined;
     inspectIndex(target: ReplicaIndexTarget): ReplicaIndexInspection | undefined;
     /** Package-internal hook used by one watched operation. */
     _register<TData, TVariables extends GraphqlVariables>(watch: ReplicaWatchState<TData, TVariables>): () => void;

package/dist/replica/distributed-replica/impl.js

@@ -1,7 +1,7 @@
 import { CacheRevisionConflictError, createCacheEngine } from '../../internal/cache-engine.js';
 import { compareDistributedDecimal, DistributedProtocolError, parseGraphqlResponseExtensions } from '../../protocol.js';
 import { matchReplicaTrustedPresetInventory } from '../commands.js';
-import { replicaCommandAuthority, replicaCommandDirectProjection, replicaResultObservation } from '../command-runtime.js';
+import { replicaCommandAuthority, replicaCommandDirectProjection, replicaCommandProjectionDelta, replicaCommandReadRecord, replicaResultObservation } from '../command-runtime.js';
 import { canonicalizeOperationVariables, replicaIndexKey, replicaRecordKey, resolveArguments } from '../identity.js';
 import { materializeReplicaOperation } from '../materialize.js';
 import { normalizeReplicaResult } from '../normalize.js';
@@ -15,7 +15,7 @@ import { assertWriteSource, indexKeyFromTarget, indexMaintenanceSnapshot, indexS
 import { ReplicaWatchState } from './watch.js';
 import { closeActiveTransports as closeActiveTransportsOn, emitWatchState, fetchWatch, releaseLive as releaseLiveOn, restartLive as restartLiveOn, retainLive as retainLiveOn, resumeLiveWatches as resumeLiveWatchesOn } from './impl-fetch-live.js';
 import { closeAuthorizationGeneration as closeAuthorizationGenerationOn, purgeProtocolGeneration as purgeProtocolGenerationOn, stageProtocolGeneration as stageProtocolGenerationOn, stageTrustedPresets as stageTrustedPresetsOn, validateProtocolBinding as validateProtocolBindingOn } from './impl-protocol.js';
-import { applyReceiptOnly as applyReceiptOnlyOn, confirmOptimisticLayerOn, createOptimisticLayerOn, markOptimisticLayerAcceptedOn, planOptimisticReceipts as planOptimisticReceiptsOn, rejectOptimisticLayerOn } from './impl-optimistic.js';
+import { applyReceiptOnly as applyReceiptOnlyOn, confirmOptimisticLayerOn, createOptimisticLayerOn, markOptimisticLayerAcceptedOn, planOptimisticReceipts as planOptimisticReceiptsOn, rejectOptimisticLayerOn, replaceReplicaOptimisticLayerOn } from './impl-optimistic.js';
 import { dehydrateReplica, finishDehydration as finishDehydrationOn, hydrateReplica } from './impl-hydration-orchestrate.js';
 import { diagnosticEvent as diagnosticEventOn, diagnosticOperation as diagnosticOperationOn, diagnosticScopeTransition as diagnosticScopeTransitionOn, retireDiagnosticLayer as retireDiagnosticLayerOn, syncDiagnostics as syncDiagnosticsOn } from './impl-diagnostics.js';
 export class DistributedReplicaImpl {
@@ -337,6 +337,7 @@ export class DistributedReplicaImpl {
             : Object.freeze({
                 protocolVersion: scope.protocolVersion,
                 schemaHash: scope.schemaHash,
+                authorizationGeneration: scope.authorizationGeneration,
                 cacheScope: scope.cacheScope
             });
     }
@@ -477,6 +478,9 @@ export class DistributedReplicaImpl {
             }));
         }
     }
+    [replicaCommandProjectionDelta](commandId, update, semanticChanges) {
+        return replaceReplicaOptimisticLayerOn(this.#optimisticHost(), commandId, update, semanticChanges);
+    }
     read(artifact, variables) {
         this.#bindArtifact(artifact);
         const stableVariables = canonicalizeOperationVariables(artifact, variables);
@@ -927,7 +931,7 @@ export class DistributedReplicaImpl {
         }
         for (const [id, receipt] of receiptPlan.updates) {
             if (receiptPlan.satisfied.includes(id)) {
-                this.#retireDiagnosticLayer(id, 'retired', 'projected', receipt);
+                this.#retireDiagnosticLayer(id, 'retired', 'atomic', receipt);
                 this.#optimisticReceipts.delete(id);
             }
             else {
@@ -943,8 +947,8 @@ export class DistributedReplicaImpl {
                         kind: 'receipt',
                         command: id,
                         state: counts.obligations === 0
-                            ? 'accepted'
-                            : 'accepted_pending_projection',
+                            ? 'succeeded'
+                            : 'succeeded_pending_projection',
                         obligations: counts.obligations,
                         observed: counts.observed
                     }));
@@ -1105,6 +1109,19 @@ export class DistributedReplicaImpl {
             });
         });
     }
+    /**
+     * Package-private live fields for pure-reduce optimism.
+     * @internal
+     */
+    [replicaCommandReadRecord](model, identity) {
+        const key = replicaRecordKey(model, identity);
+        return this.#engine.read((reader) => {
+            const record = reader.record(key);
+            if (!record)
+                return undefined;
+            return Object.freeze({ ...record.fields });
+        });
+    }
     inspectIndex(target) {
         const key = indexKeyFromTarget(target);
         return this.#engine.read((reader) => {

package/dist/replica/distributed-replica/optimistic.js

@@ -85,18 +85,29 @@ export function captureReplicaOptimisticUpdate(id, update, semanticChanges) {
             const key = replicaRecordKey(model, identity);
             const fields = cloneOptimisticFields(patch.fields);
             const links = cloneOptimisticLinks(patch.links);
-            if (Object.keys(fields).length === 0 && Object.keys(links).length === 0) {
+            const unset = cloneOptimisticUnset(patch.unset, fields);
+            if (Object.keys(fields).length === 0 &&
+                Object.keys(links).length === 0 &&
+                unset.length === 0) {
                 return;
             }
             operations.push(Object.freeze({
                 kind: 'write-record',
-                write: Object.freeze({ key, fields, links })
+                write: Object.freeze({
+                    key,
+                    fields,
+                    links,
+                    ...(unset.length === 0 ? {} : { unset }),
+                    ...(patch.ifPresent === true ? { ifPresent: true } : {})
+                })
             }));
             changes.push(Object.freeze({
                 kind: 'upsert',
                 model: model.id,
                 key,
-                fields
+                fields,
+                ...(unset.length === 0 ? {} : { unset }),
+                ...(patch.ifPresent === true ? { ifPresent: true } : {})
             }));
         },
         tombstoneRecord(model, identity) {
@@ -174,6 +185,23 @@ export function cloneOptimisticFields(fields) {
         return [name, cloneJsonValue(value)];
     })));
 }
+function cloneOptimisticUnset(unset, fields) {
+    if (unset === undefined)
+        return Object.freeze([]);
+    if (!Array.isArray(unset))
+        throw new TypeError('record unset must be an array');
+    const result = unset.map((name) => {
+        assertReplicaName(name, 'record unset field');
+        if (Object.hasOwn(fields, name)) {
+            throw new TypeError('record field cannot be set and unset');
+        }
+        return name;
+    });
+    if (new Set(result).size !== result.length) {
+        throw new TypeError('record unset fields must be unique');
+    }
+    return Object.freeze(result);
+}
 export function cloneOptimisticLinks(links) {
     if (links === undefined)
         return Object.freeze({});

package/dist/replica/distributed-replica/types.d.ts

@@ -20,6 +20,7 @@ export type ProtocolGeneration = {
     protocolVersion: 1;
     cacheScope: DistributedOpaqueString;
     schemaHash: string;
+    authorizationGeneration: string;
 };
 export type RenderedOperation = {
     readonly artifact: ReplicaOperationArtifact<unknown, GraphqlVariables>;

package/dist/replica/index-maintenance/engine.js

@@ -199,13 +199,19 @@ export function applyLayers(base, layers) {
                 continue;
             }
             const current = records.get(change.key);
+            if (change.ifPresent === true && current === undefined) {
+                continue;
+            }
             if (current !== undefined && current.model !== change.model) {
                 throw new TypeError(`record model changed for ${change.key}`);
             }
+            const fields = { ...(current?.fields ?? {}), ...change.fields };
+            for (const field of change.unset ?? [])
+                delete fields[field];
             records.set(change.key, {
                 key: change.key,
                 model: change.model,
-                fields: { ...(current?.fields ?? {}), ...change.fields }
+                fields
             });
         }
     }
@@ -421,10 +427,8 @@ export function maintainEntityIndex(planValue, index, changes, trustedPresets) {
         index.metadata.coverage.offset === 0 &&
         index.metadata.coverage.limit !== undefined &&
         records.length > index.metadata.coverage.limit) {
-        // Locality above is possible only because the base first page was
-        // non-full, so this is the complete optimistic ordered set. Preserve the
-        // operation's exact window when stacked optimistic inserts cross its
-        // limit.
+        // First-page inserts re-sort known members then clamp to the operation
+        // window so a full live page still shows optimistic rows that sort in.
         records = records.slice(0, index.metadata.coverage.limit);
     }
     return sameStringList(records, current)
@@ -451,6 +455,10 @@ export function certifyOffsetCoverage(planValue, index, confirmedRecords, change
         typeof artifact.maxLimit === 'number'
         ? Math.min(configuredLimit, artifact.maxLimit)
         : configuredLimit;
+    // First-page inserts remain local even when hasNext is true: membership is
+    // re-sorted and truncated to the limit among known rows. Delete/reorder on a
+    // page with a next boundary still fail closed (unseen fill-in).
+    const hasNextBlocksLocality = coverage.hasNext === true && changeKind !== 'insert';
     if (typeof expectedOffset !== 'number' ||
         !Number.isSafeInteger(expectedOffset) ||
         expectedOffset < 0 ||
@@ -461,7 +469,7 @@ export function certifyOffsetCoverage(planValue, index, confirmedRecords, change
         coverage.offset !== expectedOffset ||
         coverage.limit !== expectedLimit ||
         coverage.returned !== confirmedRecords ||
-        coverage.hasNext === true) {
+        hasNextBlocksLocality) {
         return reason('invalid_index_metadata', ['indexes', index.key, 'coverage'], 'offset coverage does not match the request, confirmed index size, or observed page boundary');
     }
     return undefined;

package/dist/replica/index.d.ts

@@ -10,8 +10,12 @@ export { createReplicaIndexedDbPersistence, REPLICA_OFFLINE_COMMAND_OUTBOX_SUPPO
 export type { ReplicaBoundCommand, ReplicaBoundCommands, ReplicaCommandCallOptions, ReplicaCommandProjectedOutcome, ReplicaCommandReceipt, ReplicaCommandRecoveryReceipt, ReplicaCommandRuntime, ReplicaCommandRuntimeErrorCode, ReplicaCommandRuntimeOptions, ReplicaCommandStatus, ReplicaCommandStatusArtifact, ReplicaCommandStatusRequest, ReplicaCommandTransport, ReplicaCommandTransportRequest, ReplicaCommandTransportResult } from './command-runtime.js';
 export type { ReplicaIndexedDbFactory, ReplicaIndexedDbPersistence, ReplicaIndexedDbPersistenceOptions, ReplicaPersistenceModelPolicy, ReplicaPersistencePolicy } from './persistence.js';
 export type { PrepareReplicaCommandOptions, ReplicaCommandArtifact, ReplicaCommandConfirmation, ReplicaCommandConfirmations, ReplicaCommandContractErrorCode, ReplicaCommandDirectProjection, ReplicaCommandEffect, ReplicaCommandEffectExpression, ReplicaCommandEffectField, ReplicaCommandEffectKey, ReplicaCommandEffectRelationship, ReplicaCommandEffects, ReplicaCommandGenerators, ReplicaCommandInputDefault, ReplicaCommandInputDefaults, ReplicaCommandRevalidationPlan, ReplicaCommandScalarCodec, ReplicaCommandShape, ReplicaCommandTypeDefinition, ReplicaCommandTypeField, ReplicaCommandVariables, ReplicaTrustedPresetDescriptor, ReplicaPreparedCommand, ReplicaPreparedCommandEffect, ReplicaPreparedConfirmation, ReplicaPreparedConfirmations, ReplicaPreparedEffectField, ReplicaPreparedEffectKey, ReplicaReceiptVerification } from './commands.js';
+export { createWasmJsonPure } from './projection-delta/index.js';
+export type { CreateWasmJsonPureOptions, PreparedCommandProjection, PreparedProjectionOperation, ReplicaCommandProjection, WasmJsonModule, WasmJsonPureHost } from './projection-delta/index.js';
 export { compareReplicaOrder, decideReplicaPaginationMaintenance, evaluateReplicaFilter } from './query-plan.js';
 export { createReplicaIndexMaintenanceRegistry, formatReplicaIndexStaleReason } from './index-maintenance.js';
 export type { ReplicaIndexDependencyChange, ReplicaIndexMaintenanceDecision, ReplicaIndexMaintenanceIndex, ReplicaIndexMaintenanceReason, ReplicaIndexMaintenanceReasonCode, ReplicaIndexMaintenanceRecord, ReplicaIndexMaintenanceRegistry, ReplicaIndexMaintenanceSnapshot, ReplicaIndexPlanRegistration, ReplicaIndexRecordChange, ReplicaIndexRelationshipChange, ReplicaIndexSemanticChange, ReplicaIndexSemanticLayer } from './index-maintenance.js';
 export type { ReplicaFilterEvaluation, ReplicaFilterEvaluationOptions, ReplicaOrderComparison, ReplicaPaginationChange, ReplicaPaginationMaintenanceDecision, ReplicaQueryPlanPath, ReplicaQueryPlanReason, ReplicaQueryPlanReasonCode, ReplicaRelationshipFilterRequest } from './query-plan.js';
 export type { DistributedReplicaOptions, DistributedReplica, ReplicaArgumentsArtifact, ReplicaArgumentValue, ReplicaAuthoritativeScope, ReplicaBaseWriter, ReplicaBranchSemantic, ReplicaClientSurface, ReplicaCoverageArtifact, ReplicaDehydratedState, ReplicaFilterArtifact, ReplicaFilterExpression, ReplicaFilterFieldArtifact, ReplicaFilterLiteral, ReplicaFilterOperand, ReplicaFilterOperator, ReplicaIdentity, ReplicaIndexCoverage, ReplicaIndexInspection, ReplicaIndexTarget, ReplicaListValue, ReplicaLiveObserver, ReplicaLiveState, ReplicaLiteralValue, ReplicaModelArtifact, ReplicaObjectBranch, ReplicaObjectMember, ReplicaObjectSelection, ReplicaObjectValue, ReplicaOperationArtifact, ReplicaOperationSourceLocation, ReplicaOperationProtocol, ReplicaOrderArtifact, ReplicaOrderFieldArtifact, ReplicaOrderTieBreakerArtifact, ReplicaOptimisticWriter, ReplicaPaginationArtifact, ReplicaPaginationDisposition, ReplicaProtocolOperationArtifact, ReplicaRecordInspection, ReplicaRecordPatch, ReplicaRevalidationPlan, ReplicaRevalidationRelationship, ReplicaRevision, ReplicaRelationshipArtifact, ReplicaRelationshipKeyMapping, ReplicaRelationshipKind, ReplicaResultEnvelope, ReplicaRowPolicyArtifact, ReplicaRootSelection, ReplicaScalarSelection, ReplicaSelectionStorage, ReplicaSparse, ReplicaSnapshot, ReplicaStatus, ReplicaTransport, ReplicaTransportRequest, ReplicaVariableValue, ReplicaVariableCodecArtifact, ReplicaVariableEnumInputRef, ReplicaVariableFilterInputDefinition, ReplicaVariableFilterInputField, ReplicaVariableFilterInputRelationship, ReplicaVariableFilterInputTarget, ReplicaVariableInputDefinition, ReplicaVariableInputRef, ReplicaVariableListInputRef, ReplicaVariableNamedInputRef, ReplicaVariableOrderInputDefinition, ReplicaVariableOrderInputField, ReplicaVariableScalarInputRef, ReplicaValue, ReplicaWatch, ReplicaWriteSource, WatchReplicaOptions } from './types.js';
+export { lowerMutationCache, MUTATION_CACHE_VISIBILITY_FULL, MUTATION_CACHE_VISIBILITY_UNAUTHORIZED, } from './mutation-cache.js';
+export type { MutationCacheEffect, MutationCacheProgram, MutationCacheVisibility, MutationField, MutationOperation, MutationProgram, MutationTarget, } from './mutation-cache.js';

package/dist/replica/index.js

@@ -5,5 +5,7 @@ export { canonicalizeOperationVariables, replicaIndexKey, replicaRecordKey } fro
 export { prepareReplicaCommand, ReplicaCommandContractError, verifyReplicaCommandReceipt } from './commands.js';
 export { createReplicaCommandRuntime, ReplicaCommandRuntimeError } from './command-runtime.js';
 export { createReplicaIndexedDbPersistence, REPLICA_OFFLINE_COMMAND_OUTBOX_SUPPORTED } from './persistence.js';
+export { createWasmJsonPure } from './projection-delta/index.js';
 export { compareReplicaOrder, decideReplicaPaginationMaintenance, evaluateReplicaFilter } from './query-plan.js';
 export { createReplicaIndexMaintenanceRegistry, formatReplicaIndexStaleReason } from './index-maintenance.js';
+export { lowerMutationCache, MUTATION_CACHE_VISIBILITY_FULL, MUTATION_CACHE_VISIBILITY_UNAUTHORIZED, } from './mutation-cache.js';

package/dist/replica/materialize.js

@@ -54,6 +54,16 @@ function materializeBranch(reader, selection, index, variables) {
     if (selection.cardinality === 'one') {
         const key = index.records[0];
         if (key === undefined) {
+            // Empty relationship edge: null when the selection allows it.
+            if (selection.nullable) {
+                return {
+                    value: null,
+                    present: true,
+                    complete: indexComplete,
+                    stale,
+                    identitySignature: `null:${index.metadata.staleReason ?? ''}`
+                };
+            }
             return {
                 present: false,
                 complete: false,
@@ -144,6 +154,21 @@ function materializeNestedBranch(reader, parentKey, parentIncarnation, selection
     });
     const index = reader.index(indexKey);
     if (index?.metadata?.parentIncarnation !== parentIncarnation) {
+        /*
+         * Optimistic parent upserts often write the FK row before a relationship
+         * index exists. For nullable joins (e.g. ChatMessages.author), treat the
+         * missing edge as an authorized null so the parent list stays complete
+         * and visible. Required relationships still fail closed as incomplete.
+         */
+        if (selection.nullable) {
+            return {
+                value: null,
+                present: true,
+                complete: true,
+                stale: index !== undefined,
+                identitySignature: `null-missing-edge:${selection.field}`
+            };
+        }
         return {
             present: false,
             complete: false,