@hops-ops/distributed 4.1.1 → 4.3.0

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

@@ -1,2 +1,4 @@
-/** Create a browser/Node UUIDv7 command identity. */
-export declare function createReplicaCommandId(): string;
+/** Create a browser/Node UUIDv7 identity for commands or generated record IDs. */
+export declare function createReplicaUuidV7(): string;
+/** Package-internal semantic alias used while preparing command envelopes. */
+export declare const createReplicaCommandId: typeof createReplicaUuidV7;

package/dist/replica/command-id.js

@@ -1,5 +1,5 @@
-/** Create a browser/Node UUIDv7 command identity. */
-export function createReplicaCommandId() {
+/** Create a browser/Node UUIDv7 identity for commands or generated record IDs. */
+export function createReplicaUuidV7() {
     const crypto = globalThis.crypto;
     if (!crypto || typeof crypto.getRandomValues !== 'function') {
         throw new Error('replica commands require crypto.getRandomValues');
@@ -17,3 +17,5 @@ export function createReplicaCommandId() {
         .slice(6, 8)
         .join('')}-${hex.slice(8, 10).join('')}-${hex.slice(10).join('')}`;
 }
+/** Package-internal semantic alias used while preparing command envelopes. */
+export const createReplicaCommandId = createReplicaUuidV7;

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

@@ -288,7 +288,7 @@ export function createReplicaCommandRuntime(replica, transport, entries, options
                 throw new Error('projection delta changed during command replay');
             }
             return Object.freeze({
-                requiresRevalidation: actual.revalidate || actual.obligations.length === 0
+                requiresRevalidation: actual.revalidate
             });
         }
         assertActualProjectionCapabilities(prepared.projection.contract, actual.delta);
@@ -300,10 +300,10 @@ export function createReplicaCommandRuntime(replica, transport, entries, options
         return Object.freeze({
             canonical,
             operations,
-            revalidation: actual.revalidate || actual.obligations.length === 0
+            revalidation: actual.revalidate
                 ? actualProjectionRevalidation(prepared.revalidation, actual.delta)
                 : undefined,
-            requiresRevalidation: actual.revalidate || actual.obligations.length === 0
+            requiresRevalidation: actual.revalidate
         });
     };
     const commitActualProjection = (prepared, validated) => {
@@ -595,6 +595,17 @@ export function createReplicaCommandRuntime(replica, transport, entries, options
                             settleTrackedProjection(tracker, pending);
                         }
                     }
+                    else if (metadata.state === 'atomic' &&
+                        !prepared.revalidation.required &&
+                        !statusRequiresRevalidation) {
+                        /*
+                         * An exact terminal delta proves delivery but carries no
+                         * canonical revision. Keep its accepted overlay until a later
+                         * comparable authoritative result seals it, without racing
+                         * sibling commands with a command-triggered query.
+                         */
+                        settleTrackedProjection(tracker, pending);
+                    }
                     else if (metadata.state === 'atomic' ||
                         (metadata.state === 'succeeded' &&
                             metadata.expects.length === 0 &&
@@ -1051,9 +1062,16 @@ export function createReplicaCommandRuntime(replica, transport, entries, options
              * DistributedReplica is the authority on whether this frame's
              * snapshot/observations were admissible. This callback runs only
              * after that exact frame committed.
+             *
+             * Eventual list membership fences may keep the optimistic overlay
+             * until @live includes the new row. `projected` is delivery, not
+             * overlay retirement. Query/live frames have no command payload;
+             * settle those so Send/busy can clear. Frames that name a command
+             * still wait for overlay retirement or the command-state paths
+             * above (status regression must be able to reject `projected`).
              */
             const remainsPending = replica.markOptimisticLayerAccepted(commandId);
-            if (!remainsPending) {
+            if (!remainsPending || command === undefined) {
                 settleProjectionSuccess(controller);
                 pending.delete(commandId);
             }

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

@@ -1,4 +1,4 @@
-import type { CacheEngine, OptimisticLayerReplacement } from '../../internal/cache-engine.js';
+import type { BaseCacheWriter, 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';
@@ -32,6 +32,8 @@ export declare function replaceOptimisticLayerOn(host: OptimisticHost, id: strin
 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;
+/** Internal confirmation seam for protocol code that must atomically seal indexes. */
+export declare function confirmOptimisticLayerWithCacheWriterOn<T>(host: OptimisticHost, id: string, update: (writer: BaseCacheWriter) => T): T;
 export declare function rejectOptimisticLayerOn(host: OptimisticHost, id: string): boolean;
 export declare function planOptimisticReceipts(host: OptimisticHost, command: DistributedCommandMetadata | undefined, observations: readonly DistributedProjectionObservation[], satisfactionAdmissible: boolean): {
     updates: Map<string, OptimisticReceiptState>;

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

@@ -113,7 +113,11 @@ export function markOptimisticLayerAcceptedOn(host, id, receipt) {
     return true;
 }
 export function confirmOptimisticLayerOn(host, id, update) {
-    const result = host.engine.confirmOptimisticLayer(id, (writer) => update(baseWriter(writer)));
+    return confirmOptimisticLayerWithCacheWriterOn(host, id, (writer) => update(baseWriter(writer)));
+}
+/** Internal confirmation seam for protocol code that must atomically seal indexes. */
+export function confirmOptimisticLayerWithCacheWriterOn(host, id, update) {
+    const result = host.engine.confirmOptimisticLayer(id, update);
     host.retireDiagnosticLayer(id, 'retired', 'atomic');
     host.optimisticReceipts.delete(id);
     host.syncDiagnostics();

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

@@ -17,6 +17,8 @@ export type ProtocolHost = {
     readonly recordClocks: Map<string, RecordProtocolClock>;
     readonly recordKeysByScope: Map<DistributedOpaqueString, string>;
     readonly projectedRecordFences: Map<string, ProjectedRecordFence>;
+    readonly membershipFences: Map<string, Map<string, Set<string>>>;
+    readonly deferredMembershipConfirms: Set<string>;
     readonly anonymousRecordClocks: Map<DistributedOpaqueString, AnonymousRecordProtocolClock>;
     readonly optimisticReceipts: Map<string, OptimisticReceiptState>;
     readonly diagnosticLayers: Map<string, ReplicaDiagnosticLayerInput> | undefined;

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

@@ -73,6 +73,8 @@ export function purgeProtocolGeneration(host) {
     host.recordClocks.clear();
     host.recordKeysByScope.clear();
     host.projectedRecordFences.clear();
+    host.membershipFences.clear();
+    host.deferredMembershipConfirms.clear();
     host.anonymousRecordClocks.clear();
     host.optimisticReceipts.clear();
     host.diagnosticLayers?.clear();

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

@@ -11,11 +11,11 @@ import { createReplicaIndexMaintenanceRegistry, formatReplicaIndexStaleReason }
 import { EMPTY_ERRORS, EMPTY_TRUSTED_PRESETS, MAX_ANONYMOUS_RECORD_CLOCKS } from './constants.js';
 import { compareCanonicalDecimalStrings, compareEvidenceToProjectedFence, compareIndexVector, compareProjectedRecordFields, compareRecordClock, compareSnapshotToOperationState, incrementCanonicalDecimal, indexClockMap, isComparableHandoffDisposition, latestCursors, protocolInvalid, recordKeyMatchesModel, responsePathKey, sameRecordClock, sameRecordRevision } from './clocks.js';
 import { diagnosticReceiptCounts } from './optimistic.js';
-import { assertWriteSource, indexKeyFromTarget, indexMaintenanceSnapshot, indexSemanticLayer, operationKey, prepareRecordEvidence, protocolOperationSource, replicaResultIndexKeys, reportSafely, reportUnhandledObserverError, snapshotFrom, stableErrors, trustedPresetDescriptorFingerprint, validatedCommandAuthorityContract } from './helpers.js';
+import { assertWriteSource, baseWriter, indexKeyFromTarget, indexMaintenanceSnapshot, indexSemanticLayer, operationKey, prepareRecordEvidence, protocolOperationSource, replicaResultIndexKeys, reportSafely, reportUnhandledObserverError, snapshotFrom, stableErrors, trustedPresetDescriptorFingerprint, validatedCommandAuthorityContract } from './helpers.js';
 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, replaceReplicaOptimisticLayerOn } from './impl-optimistic.js';
+import { applyReceiptOnly as applyReceiptOnlyOn, confirmOptimisticLayerOn, confirmOptimisticLayerWithCacheWriterOn, 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 {
@@ -34,6 +34,14 @@ export class DistributedReplicaImpl {
     #recordClocks = new Map();
     #recordKeysByScope = new Map();
     #projectedRecordFences = new Map();
+    /**
+     * Record keys inserted by Eventual projection-delta. A later complete
+     * query/live index that omits them is behind command confirmation and
+     * must not shrink the visible list. Atomic rows use projected-record
+     * fences only — they have no @live that would otherwise clear this map.
+     */
+    #membershipFences = new Map();
+    #deferredMembershipConfirms = new Set();
     #anonymousRecordClocks = new Map();
     #optimisticReceipts = new Map();
     #renderedOperations = new Map();
@@ -160,6 +168,12 @@ export class DistributedReplicaImpl {
             get projectedRecordFences() {
                 return self.#projectedRecordFences;
             },
+            get membershipFences() {
+                return self.#membershipFences;
+            },
+            get deferredMembershipConfirms() {
+                return self.#deferredMembershipConfirms;
+            },
             get anonymousRecordClocks() {
                 return self.#anonymousRecordClocks;
             },
@@ -435,13 +449,46 @@ export class DistributedReplicaImpl {
         const pendingAnonymousRecordClocks = new Map();
         const consumedAnonymousRecordClocks = new Set();
         const apply = this.#resolveRecordEvidence(recordKey, evidence, pendingRecordClocks, pendingRecordScopes, pendingAnonymousRecordClocks, consumedAnonymousRecordClocks);
-        this.confirmOptimisticLayer(commandId, (writer) => {
+        /*
+         * The Atomic output is a complete authoritative row. Seal every active
+         * collection membership that the compiler plan can prove from that row in
+         * the same base transaction; otherwise the record exists by key while a
+         * warm @load index still omits it until refresh.
+         */
+        const indexMutations = apply
+            ? this.#directProjectionIndexMutations(commandId, model, recordKey, fields)
+            : Object.freeze([]);
+        const indexRevision = indexMutations.length === 0
+            ? undefined
+            : this.#allocateIndexRevision();
+        confirmOptimisticLayerWithCacheWriterOn(this.#optimisticHost(), commandId, (writer) => {
             if (!apply)
                 return false;
-            return writer.writeRecord(model, identity, evidence.revision, {
+            const wrote = writer.writeRecord({
+                key: recordKey,
+                revision: evidence.revision,
                 incarnation: evidence.incarnation,
                 fields
             });
+            if (indexRevision !== undefined) {
+                for (const mutation of indexMutations) {
+                    switch (mutation.kind) {
+                        case 'write':
+                            writer.writeIndex({
+                                ...mutation.write,
+                                revision: indexRevision
+                            });
+                            break;
+                        case 'stale':
+                            writer.markIndexStale(mutation.key, mutation.reason, indexRevision);
+                            break;
+                        case 'delete':
+                            writer.deleteIndex(mutation.key, indexRevision);
+                            break;
+                    }
+                }
+            }
+            return wrote;
         });
         for (const [key, clock] of pendingRecordClocks) {
             this.#recordClocks.set(key, clock);
@@ -465,6 +512,11 @@ export class DistributedReplicaImpl {
              * model necessarily catches up. Retain its complete row and causal
              * clock as a write fence until a query acknowledges it or a newer
              * record/tombstone supersedes it.
+             *
+             * Do not also take a membership fence: Atomic lists are @load, not
+             * @live. A membership fence would reject later complete snapshots
+             * until a live frame that never comes, stalling blob/new games and
+             * client-side navigations.
              */
             this.#projectedRecordFences.set(recordKey, Object.freeze({
                 fields: Object.freeze({ ...fields }),
@@ -479,7 +531,7 @@ export class DistributedReplicaImpl {
         }
     }
     [replicaCommandProjectionDelta](commandId, update, semanticChanges) {
-        return replaceReplicaOptimisticLayerOn(this.#optimisticHost(), commandId, update, semanticChanges);
+        return replaceReplicaOptimisticLayerOn(this.#optimisticHost(), commandId, (writer) => update(this.#capturingOptimisticWriter(commandId, writer)), semanticChanges);
     }
     read(artifact, variables) {
         this.#bindArtifact(artifact);
@@ -882,14 +934,15 @@ export class DistributedReplicaImpl {
         let summary;
         try {
             const update = (writer) => {
-                this.#applyTombstoneEvidence(writer, recordEvidence.tombstones, operationState, pendingRecordClocks, pendingRecordScopes, pendingAnonymousRecordClocks, consumedAnonymousRecordClocks, consumedRecordPaths, pendingProjectedRecordFenceClears);
-                const normalized = normalizeReplicaResult(writer, artifact, stableVariables, envelope, normalizationProtocol);
+                const guarded = this.#guardIndexWriter(writer);
+                this.#applyTombstoneEvidence(guarded, recordEvidence.tombstones, operationState, pendingRecordClocks, pendingRecordScopes, pendingAnonymousRecordClocks, consumedAnonymousRecordClocks, consumedRecordPaths, pendingProjectedRecordFenceClears);
+                const normalized = normalizeReplicaResult(guarded, artifact, stableVariables, envelope, normalizationProtocol);
                 for (const path of recordEvidence.livePaths) {
                     if (!consumedRecordPaths.has(path)) {
                         protocolInvalid('extensions.distributed.snapshot.records.path');
                     }
                 }
-                this.#applyPathlessEvidence(writer, recordEvidence.pathless, recordEvidence.byPath, consumedRecordPaths, pendingRecordClocks, pendingRecordScopes, pendingAnonymousRecordClocks, consumedAnonymousRecordClocks, pendingProjectedRecordFenceClears);
+                this.#applyPathlessEvidence(guarded, recordEvidence.pathless, recordEvidence.byPath, consumedRecordPaths, pendingRecordClocks, pendingRecordScopes, pendingAnonymousRecordClocks, consumedAnonymousRecordClocks, pendingProjectedRecordFenceClears);
                 return normalized;
             };
             summary =
@@ -986,6 +1039,7 @@ export class DistributedReplicaImpl {
         this.#protocolGeneration = nextProtocolGeneration;
         this.#resumeLiveWatches();
         this.#emitState(key, false);
+        this.#flushDeferredMembershipConfirms();
         if (this.#diagnostics !== undefined) {
             const cache = this.#engine.extract();
             this.#diagnosticEvent(Object.freeze({
@@ -1051,11 +1105,143 @@ export class DistributedReplicaImpl {
         return markOptimisticLayerAcceptedOn(this.#optimisticHost(), id, receipt);
     }
     confirmOptimisticLayer(id, update) {
+        if (this.#commandHasMembershipFence(id)) {
+            this.#deferredMembershipConfirms.add(id);
+            return this.#engine.batch((writer) => update(baseWriter(writer)));
+        }
         return confirmOptimisticLayerOn(this.#optimisticHost(), id, update);
     }
     rejectOptimisticLayer(id) {
+        this.#clearMembershipFencesForCommand(id);
+        this.#deferredMembershipConfirms.delete(id);
         return rejectOptimisticLayerOn(this.#optimisticHost(), id);
     }
+    #capturingOptimisticWriter(commandId, writer) {
+        const touchedRecords = new Set();
+        return {
+            writeRecord: (model, identity, patch) => {
+                touchedRecords.add(replicaRecordKey(model, identity));
+                writer.writeRecord(model, identity, patch);
+            },
+            tombstoneRecord: (model, identity) => {
+                const recordKey = replicaRecordKey(model, identity);
+                touchedRecords.delete(recordKey);
+                this.#clearMembershipFenceOwner(commandId, recordKey);
+                writer.tombstoneRecord(model, identity);
+            },
+            writeIndex: (target, records) => {
+                const indexKey = indexKeyFromTarget(target);
+                for (const recordKey of records) {
+                    if (!touchedRecords.has(recordKey))
+                        continue;
+                    let recordsForIndex = this.#membershipFences.get(indexKey);
+                    if (recordsForIndex === undefined) {
+                        recordsForIndex = new Map();
+                        this.#membershipFences.set(indexKey, recordsForIndex);
+                    }
+                    let owners = recordsForIndex.get(recordKey);
+                    if (owners === undefined) {
+                        owners = new Set();
+                        recordsForIndex.set(recordKey, owners);
+                    }
+                    owners.add(commandId);
+                }
+                writer.writeIndex(target, records);
+            },
+            deleteIndex: (target) => {
+                const indexKey = indexKeyFromTarget(target);
+                const recordsForIndex = this.#membershipFences.get(indexKey);
+                if (recordsForIndex !== undefined) {
+                    for (const [recordKey, owners] of recordsForIndex) {
+                        owners.delete(commandId);
+                        if (owners.size === 0)
+                            recordsForIndex.delete(recordKey);
+                    }
+                    if (recordsForIndex.size === 0) {
+                        this.#membershipFences.delete(indexKey);
+                    }
+                }
+                writer.deleteIndex(target);
+            }
+        };
+    }
+    #commandHasMembershipFence(commandId) {
+        for (const recordsForIndex of this.#membershipFences.values()) {
+            for (const owners of recordsForIndex.values()) {
+                if (owners.has(commandId))
+                    return true;
+            }
+        }
+        return false;
+    }
+    #clearMembershipFencesForCommand(commandId) {
+        for (const [indexKey, recordsForIndex] of this.#membershipFences) {
+            for (const [recordKey, owners] of recordsForIndex) {
+                owners.delete(commandId);
+                if (owners.size === 0)
+                    recordsForIndex.delete(recordKey);
+            }
+            if (recordsForIndex.size === 0) {
+                this.#membershipFences.delete(indexKey);
+            }
+        }
+    }
+    #clearMembershipFenceOwner(commandId, recordKey) {
+        for (const [indexKey, recordsForIndex] of this.#membershipFences) {
+            const owners = recordsForIndex.get(recordKey);
+            if (owners === undefined)
+                continue;
+            owners.delete(commandId);
+            if (owners.size === 0)
+                recordsForIndex.delete(recordKey);
+            if (recordsForIndex.size === 0) {
+                this.#membershipFences.delete(indexKey);
+            }
+        }
+    }
+    #guardIndexWriter(writer) {
+        return {
+            recordClock: (key) => writer.recordClock(key),
+            writeRecord: (write) => writer.writeRecord(write),
+            tombstoneRecord: (key, revision, incarnation) => writer.tombstoneRecord(key, revision, incarnation),
+            discardRecord: (key) => writer.discardRecord(key),
+            writeIndex: (write) => {
+                const recordsForIndex = this.#membershipFences.get(write.key);
+                if (write.complete === true && recordsForIndex !== undefined) {
+                    const visible = this.#engine.read((reader) => reader.index(write.key)?.records) ?? [];
+                    for (const recordKey of recordsForIndex.keys()) {
+                        if (visible.includes(recordKey) &&
+                            !write.records.includes(recordKey)) {
+                            return false;
+                        }
+                    }
+                }
+                const wrote = writer.writeIndex(write);
+                if (wrote && recordsForIndex !== undefined) {
+                    for (const recordKey of write.records) {
+                        recordsForIndex.delete(recordKey);
+                    }
+                    if (recordsForIndex.size === 0) {
+                        this.#membershipFences.delete(write.key);
+                    }
+                }
+                return wrote;
+            },
+            markIndexStale: (key, reason, revision) => writer.markIndexStale(key, reason, revision),
+            deleteIndex: (key, revision) => writer.deleteIndex(key, revision)
+        };
+    }
+    #flushDeferredMembershipConfirms() {
+        for (const commandId of [...this.#deferredMembershipConfirms]) {
+            if (this.#commandHasMembershipFence(commandId))
+                continue;
+            this.#deferredMembershipConfirms.delete(commandId);
+            if (this.#engine.optimisticLayerState(commandId) === undefined) {
+                continue;
+            }
+            confirmOptimisticLayerOn(this.#optimisticHost(), commandId, () => undefined);
+        }
+    }
     tombstoneRecord(model, identity, revision) {
         const wrote = this.#engine.batch((writer) => writer.tombstoneRecord(replicaRecordKey(model, identity), revision));
         if (wrote)
@@ -1268,6 +1454,24 @@ export class DistributedReplicaImpl {
         }
         return Object.freeze(mutations);
     }
+    #directProjectionIndexMutations(commandId, model, recordKey, fields) {
+        const change = Object.freeze({
+            kind: 'upsert',
+            model: model.id,
+            key: recordKey,
+            fields
+        });
+        const layer = Object.freeze({
+            id: commandId,
+            sequence: Number.MAX_SAFE_INTEGER,
+            state: 'accepted',
+            context: Object.freeze({
+                id: commandId,
+                changes: Object.freeze([change])
+            })
+        });
+        return this.#deriveMaintainedIndexes(this.#engine.extract(), [layer]);
+    }
     #operationProtocol(key, operation, source) {
         let group = this.#operationProtocols.get(key);
         if (group === undefined) {

package/dist/replica/index.d.ts

@@ -2,6 +2,7 @@ export { createDistributedReplica } from './distributed-replica.js';
 export { createReplicaDevelopmentCapability, createReplicaDiagnostics, inspectReplicaCommandArtifact, inspectReplicaOperationArtifact } from './diagnostics.js';
 export type { ReplicaArtifactSourceLocation, ReplicaCommandArtifactInspection, ReplicaCommandEffectInspection, ReplicaDevelopmentCapability, ReplicaDiagnosticEvent, ReplicaDiagnosticEventInput, ReplicaDiagnosticFieldValueContext, ReplicaDiagnosticFieldValuePolicy, ReplicaDiagnosticIndex, ReplicaDiagnosticIndexInput, ReplicaDiagnosticLayer, ReplicaDiagnosticLayerInput, ReplicaDiagnosticReceipt, ReplicaDiagnosticReceiptExpectationInput, ReplicaDiagnosticReceiptInput, ReplicaDiagnosticRecord, ReplicaDiagnosticRecordInput, ReplicaDiagnosticReasonContext, ReplicaDiagnosticReasonPolicy, ReplicaDiagnostics, ReplicaDiagnosticsOptions, ReplicaDiagnosticsSink, ReplicaDiagnosticsSnapshot, ReplicaDiagnosticScopeInput, ReplicaDiagnosticStateInput, ReplicaOperationArtifactInspection, ReplicaOperationIndexInspection, ReplicaOperationInjectedFieldInspection } from './diagnostics.js';
 export { createReplicaGraphqlTransport } from './graphql-transport.js';
+export { createReplicaUuidV7 } from './command-id.js';
 export type { ReplicaGraphqlTransport, ReplicaGraphqlTransportOptions } from './graphql-transport.js';
 export { canonicalizeOperationVariables, replicaIndexKey, replicaRecordKey } from './identity.js';
 export { prepareReplicaCommand, ReplicaCommandContractError, verifyReplicaCommandReceipt } from './commands.js';

package/dist/replica/index.js

@@ -1,6 +1,7 @@
 export { createDistributedReplica } from './distributed-replica.js';
 export { createReplicaDevelopmentCapability, createReplicaDiagnostics, inspectReplicaCommandArtifact, inspectReplicaOperationArtifact } from './diagnostics.js';
 export { createReplicaGraphqlTransport } from './graphql-transport.js';
+export { createReplicaUuidV7 } from './command-id.js';
 export { canonicalizeOperationVariables, replicaIndexKey, replicaRecordKey } from './identity.js';
 export { prepareReplicaCommand, ReplicaCommandContractError, verifyReplicaCommandReceipt } from './commands.js';
 export { createReplicaCommandRuntime, ReplicaCommandRuntimeError } from './command-runtime.js';

package/dist/replica/projection-delta/resolve.js

@@ -8,7 +8,7 @@ export function prepareCommandProjection(contract, input, trustedPresets) {
         return Object.freeze({
             contract,
             preview: Object.freeze([...preview, ...pure]),
-            revalidate: contract.preview.recoveries.length !== 0
+            revalidate: contract.preview.recoveries.some((recovery) => recovery.condition === 'always')
         });
     }
     catch {

package/dist/sveltekit/context.js

@@ -53,6 +53,11 @@ export function defineDistributedSvelteKitOperation(artifact) {
             return useDistributedSvelteKitClient()
                 .operation(artifact)
                 .read(variables);
+        },
+        prefetch(variables) {
+            return useDistributedSvelteKitClient()
+                .operation(artifact)
+                .prefetch(variables);
         }
     });
 }

package/dist/sveltekit/index.d.ts

@@ -1,4 +1,4 @@
 export { authFromPageData, type PageGraphqlData } from './auth.js';
 export { defineDistributedSvelteKitOperation, provideDistributedSvelteKitClient, useDistributedSvelteKitClient, useDistributedSvelteKitCommands } from './context.js';
 export { bindSveltekitOperation, createPageDataSessionSource, createDistributedSvelteKit, sessionSourceFromPageData, type CreateDistributedSvelteKitOptions, type DistributedSvelteKitClient, type SveltekitBoundOperation, type SveltekitCommandRuntimeFactory, type SveltekitCommandRuntimeFactoryOptions, type SveltekitCommandRuntimeLike, type SveltekitDistributedPageData, type SveltekitPageDataSessionSource, type SveltekitPageDataSource, type SveltekitQuerySnapshot, type SveltekitQueryStore, type SveltekitReplicaAuthority, type SveltekitReplicaHydration, type SveltekitSessionSource, type UseSveltekitOperationOptions } from './replica.js';
-export { createDistributedSvelteKitServer, registerDistributedRoute, type CreateDistributedSvelteKitServerOptions, type DistributedRouteOperation, type DistributedRoutePlan, type DistributedRouteVariables, type DistributedSvelteKitServer, type SveltekitServerLoadEventLike } from './server-replica.js';
+export { createDistributedSvelteKitServer, matchDistributedRoute, registerDistributedRoute, type CreateDistributedSvelteKitServerOptions, type DistributedRouteOperation, type DistributedRoutePlan, type DistributedRouteVariables, type DistributedSvelteKitServer, type SveltekitServerLoadEventLike } from './server-replica.js';

package/dist/sveltekit/index.js

@@ -1,4 +1,4 @@
 export { authFromPageData } from './auth.js';
 export { defineDistributedSvelteKitOperation, provideDistributedSvelteKitClient, useDistributedSvelteKitClient, useDistributedSvelteKitCommands } from './context.js';
 export { bindSveltekitOperation, createPageDataSessionSource, createDistributedSvelteKit, sessionSourceFromPageData } from './replica.js';
-export { createDistributedSvelteKitServer, registerDistributedRoute } from './server-replica.js';
+export { createDistributedSvelteKitServer, matchDistributedRoute, registerDistributedRoute } from './server-replica.js';

package/dist/sveltekit/replica.d.ts

@@ -105,6 +105,8 @@ export type SveltekitBoundOperation<TData, TVariables extends GraphqlVariables>
     artifact: ReplicaOperationArtifact<TData, TVariables>;
     use(...args: UseOperationArguments<TVariables>): SveltekitQueryStore<TData>;
     read(variables: TVariables): ReplicaSnapshot<TData>;
+    /** Client-side hover/nav warmup; no-ops when the replica already has a complete snapshot. */
+    prefetch(variables: TVariables): Promise<void>;
 }>;
 export type DistributedSvelteKitClient<TCommands> = Readonly<{
     replica: DistributedReplica;
@@ -116,6 +118,7 @@ export type DistributedSvelteKitClient<TCommands> = Readonly<{
      * generation and returns false so the bound operation refetches.
      */
     hydrate(hydration: SveltekitReplicaHydration, authority: SveltekitReplicaAuthority): boolean;
+    prefetch(artifact: ReplicaOperationArtifact<unknown, GraphqlVariables>, variables: GraphqlVariables): Promise<void>;
     invalidateAuthorization(): void;
     destroy(): void;
 }>;

package/dist/sveltekit/replica.js

@@ -86,6 +86,9 @@ export function createDistributedSvelteKit(options) {
         commands,
         operation,
         hydrate,
+        prefetch(artifact, variables) {
+            return prefetchReplicaOperation(replica, artifact, variables);
+        },
         invalidateAuthorization() {
             if (!destroyed)
                 replica.invalidateAuthorization();
@@ -171,9 +174,17 @@ function bindOperation(replica, artifact, pending, lifecycle) {
     return Object.freeze({
         artifact,
         use,
-        read: (variables) => replica.read(artifact, variables)
+        read: (variables) => replica.read(artifact, variables),
+        prefetch: (variables) => prefetchReplicaOperation(replica, artifact, variables)
     });
 }
+function prefetchReplicaOperation(replica, artifact, variables) {
+    const snapshot = replica.read(artifact, variables);
+    if (snapshot.complete && !snapshot.stale)
+        return Promise.resolve();
+    const watch = replica.watch(artifact, variables, { live: false });
+    return watch.refresh().finally(() => watch.destroy());
+}
 class SveltekitQueryStoreImpl {
     #replica;
     #artifact;

package/dist/sveltekit/server-replica.d.ts

@@ -20,6 +20,12 @@ export type SveltekitServerLoadEventLike<TLocals = unknown> = Readonly<{
     }>;
     url?: URL;
     fetch?: FetchLike;
+    /**
+     * SvelteKit client-side navigation and hover preload (`__data.json`).
+     * Document SSR is `false`/`undefined`; those navigations must not wait on
+     * a fresh GraphQL replica — the browser replica already owns the cache.
+     */
+    isDataRequest?: boolean;
 }>;
 export type DistributedRouteVariables<TEvent extends SveltekitServerLoadEventLike> = Readonly<Record<string, (event: TEvent) => GraphqlVariables | Promise<GraphqlVariables>>>;
 export type CreateDistributedSvelteKitServerOptions<TSession extends NonNullable<PageGraphqlData['session']>, TEvent extends SveltekitServerLoadEventLike = SveltekitServerLoadEventLike> = Readonly<{
@@ -50,3 +56,7 @@ export declare function createDistributedSvelteKitServer<TSession extends NonNul
  * equivalent `--route Operation=/route-id` registration.
  */
 export declare function registerDistributedRoute<TData, TVariables extends GraphqlVariables>(route: string, operation: string, artifact: ReplicaOperationArtifact<TData, TVariables>): DistributedRouteOperation;
+/**
+ * Match a SvelteKit route id (`/blob/[[gameId]]`) to a browser pathname.
+ */
+export declare function matchDistributedRoute(routeId: string, pathname: string): boolean;

package/dist/sveltekit/server-replica.js

@@ -17,6 +17,12 @@ export function createDistributedSvelteKitServer(options) {
                 accessToken,
                 engineRole
             };
+            if (event.isDataRequest === true) {
+                return {
+                    ...pageData,
+                    gqlError: null
+                };
+            }
             const auth = options.getAuth?.(pageData, event) ?? authFromPageData(pageData);
             const routeId = routeIdentity(event);
             const selected = routes.filter(({ plan }) => plan.route === routeId);
@@ -117,6 +123,68 @@ function hydrationTransfer(state, operations) {
         })
     });
 }
+/**
+ * Match a SvelteKit route id (`/blob/[[gameId]]`) to a browser pathname.
+ */
+export function matchDistributedRoute(routeId, pathname) {
+    const route = normalizeRoute(routeId);
+    const path = normalizePathname(pathname);
+    if (route === path)
+        return true;
+    const routeParts = route
+        .split('/')
+        .filter(Boolean)
+        .filter((part) => !(part.startsWith('(') && part.endsWith(')')));
+    const pathParts = path.split('/').filter(Boolean);
+    const failed = new Set();
+    const matches = (routeIndex, pathIndex) => {
+        const state = routeIndex + ':' + pathIndex;
+        if (failed.has(state))
+            return false;
+        if (routeIndex === routeParts.length) {
+            return pathIndex === pathParts.length;
+        }
+        const part = routeParts[routeIndex];
+        const optionalRest = part.startsWith('[[...') && part.endsWith(']]');
+        const rest = part.startsWith('[...') && part.endsWith(']');
+        if (optionalRest || rest) {
+            for (let next = pathIndex; next <= pathParts.length; next += 1) {
+                if (matches(routeIndex + 1, next))
+                    return true;
+            }
+            failed.add(state);
+            return false;
+        }
+        const optional = part.startsWith('[[') && part.endsWith(']]');
+        if (optional) {
+            if (matches(routeIndex + 1, pathIndex))
+                return true;
+            if (pathIndex < pathParts.length &&
+                matches(routeIndex + 1, pathIndex + 1)) {
+                return true;
+            }
+            failed.add(state);
+            return false;
+        }
+        const parameter = part.startsWith('[') && part.endsWith(']');
+        if ((parameter && pathIndex < pathParts.length) ||
+            (!parameter &&
+                pathIndex < pathParts.length &&
+                pathParts[pathIndex] === part)) {
+            if (matches(routeIndex + 1, pathIndex + 1))
+                return true;
+        }
+        failed.add(state);
+        return false;
+    };
+    return matches(0, 0);
+}
+function normalizePathname(pathname) {
+    if (typeof pathname !== 'string' || pathname.length === 0)
+        return '/';
+    const trimmed = pathname.replace(/\/+$/, '');
+    return trimmed.length === 0 ? '/' : trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+}
 function validateRoutes(value) {
     if (!Array.isArray(value)) {
         throw new TypeError('createDistributedSvelteKitServer requires generated DISTRIBUTED_ROUTE_OPERATIONS');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hops-ops/distributed",
-  "version": "4.1.1",
+  "version": "4.3.0",
   "description": "Typed GraphQL client, causal replica, command runtime, and framework adapters for Distributed services",
   "type": "module",
   "license": "UNLICENSED",