@hops-ops/distributed 0.0.0 → 4.0.0

package/README.md

@@ -4,7 +4,7 @@ The generated, end-to-end typed client for
 [Distributed](https://github.com/hops-ops/distributed) services.
 
 Rust table, relationship, role, and command definitions produce one authorized
-client surface. `dctl client` combines that surface with application GraphQL
+client surface. `distributed client` combines that surface with application GraphQL
 documents and emits typed operations, live companions, route-load plans, and
 commands. This package executes those artifacts through one normalized,
 causally consistent browser replica.
@@ -37,9 +37,9 @@ by the `/sveltekit` and `/react` entry points, respectively.
 The service, not the browser, owns authorization and GraphQL semantics:
 
 ```bash
-dctl client-manifest > target/distributed-client.json
+distributed client-manifest > target/distributed-client.json
 
-dctl client \
+distributed client \
   --manifest target/distributed-client.json \
   --role user \
   --documents 'src/**/*.graphql' \
@@ -99,7 +99,7 @@ export const distributedClients = [
   {
     module: '$distributed',
     manifest: { args: serviceManifestArgs },
-    surface: 'fieldnote',
+    surface: 'e2e-ui',
     documents: ['src/routes/(app)/**/*.graphql'],
     out: 'src/lib/generated/distributed'
   },
@@ -112,7 +112,7 @@ export const distributedClients = [
         'service::distributed_admin_client_surface'
       ]
     },
-    surface: 'fieldnote-admin',
+    surface: 'e2e-ui-admin',
     documents: ['src/routes/admin/**/*.graphql'],
     out: 'src/lib/generated/distributed-admin'
   }
@@ -128,7 +128,7 @@ keeps ordinary application documents out of the admin tree; each trust boundary
 has its own Rust manifest entrypoint, generated directory, virtual module, and
 request-local replica. A single-surface application can omit the second entry.
 
-The Vite integration runs `dctl client` at startup/build, watches GraphQL
+The Vite integration runs `distributed client` at startup/build, watches GraphQL
 documents, stages all surfaces, commits a rollback-capable multi-output
 transaction, then triggers one reload. It exposes the generated Svelte wrapper
 through the configured virtual module:
@@ -259,6 +259,11 @@ the server sends a separate authority value, and the adapter requires both
 values to match. Session, token, tenant, or role changes abort HTTP and live
 work, discard the old generation, and reconnect under server-issued scope.
 
+Confirmed records and indexes under an active scope stay until auth/scope
+change, stale+revalidate, or a newer authoritative write. Same-scope soft
+navigation merges a route SSR seed into the warm client and does **not** wipe
+keys the seed omitted (a page dehydrate is only the subset for that route).
+
 Use a separate generated surface and replica for elevated routes. A normal
 client cannot import or mix admin artifacts. Configure it as a separate virtual
 module such as `$distributed/admin` and provide it only in the elevated layout.
@@ -289,7 +294,9 @@ const unsubscribe = todos.subscribe((snapshot) => {
 `watch()` reads synchronously, fetches only missing or stale projections,
 deduplicates work, and optionally maintains the generated live operation.
 `read()` is side-effect-free. `dehydrate()` and `hydrate()` transfer confirmed
-request-local state without exposing a public storage schema.
+state without exposing a public storage schema. Cold `hydrate` seeds an empty
+client; warm same-scope `hydrate` merges so soft navigation cannot discard
+confirmed session data the next route did not re-dehydrate.
 
 The replica stores normalized records and exact argument-sensitive indexes,
 not GraphQL response blobs. Generated selection metadata reconstructs each
@@ -303,16 +310,22 @@ same replica and GraphQL transport. A command call:
 
 1. validates and freezes its typed input;
 2. fills generated UUIDv7, ULID, or literal defaults exactly once;
-3. applies the generated optimistic effect transaction;
+3. applies the generated optimistic effect transaction (from `.applies` /
+   portable mutation IR — works for **Eventual and Direct** when fields are known);
 4. dispatches the exact compiler-owned mutation;
 5. keeps ambiguous commits recoverable by command ID;
 6. confirms or rejects only its own optimistic layer;
-7. resolves projected completion only after exact causal evidence arrives.
+7. retires the layer on the path that placement allows:
+   - **Eventual** — wait for projection obligations (event handler ran
+     async; there is no authoritative row on the command response);
+   - **Atomic / Direct** — normalize the **returned** row
+     (`confirmDirectProjection`) before the call settles. The server waited in
+     the command handler because it could; an event handler cannot.
 
 Applications do not provide list targets, merge functions, mutation update
-callbacks, or invalidation maps. If the compiler cannot prove safe maintenance,
-the generated plan marks the affected projection stale and the replica performs
-one deduplicated revalidation.
+callbacks, board simulators, or invalidation maps. If the compiler cannot prove
+safe maintenance, the generated plan marks the affected projection stale and
+the replica performs one deduplicated revalidation.
 
 Callers may bound their own causal wait without inventing a rollback:
 
@@ -427,7 +440,7 @@ command pipeline, or package-owned codegen executable.
 
 To move an existing pilot application:
 
-1. rerun `dctl client` and import its operation/command artifacts;
+1. rerun `distributed client` and import its operation/command artifacts;
 2. compose one replica through the framework adapter or core transport;
 3. remove handwritten cache targets, merge/update callbacks, and invalidation
    policies;

package/dist/auth-headers.js

@@ -7,7 +7,7 @@ export function buildAuthHeaders(auth = {}) {
     }
     else if (auth.userId) {
         headers['x-user-id'] = auth.userId;
-        headers['x-role'] = auth.role ?? 'user';
+        headers['x-roles'] = auth.role ?? 'user';
     }
     return headers;
 }
@@ -21,7 +21,7 @@ export function wsConnectionInitPayload(auth = {}) {
     }
     else if (auth.userId) {
         payload['x-user-id'] = auth.userId;
-        payload['x-role'] = auth.role ?? 'user';
+        payload['x-roles'] = auth.role ?? 'user';
     }
     return payload;
 }
@@ -31,5 +31,5 @@ export function applyWsDevHeaderParams(url, auth = {}) {
     if (token || !auth.userId)
         return;
     url.searchParams.set('x-user-id', auth.userId);
-    url.searchParams.set('x-role', auth.role ?? 'user');
+    url.searchParams.set('x-roles', auth.role ?? 'user');
 }

package/dist/internal/cache-engine/engine.d.ts

@@ -1,4 +1,4 @@
-import type { BaseCacheWriter, CacheEngine, CacheEngineOptions, CacheEngineSnapshot, CacheListener, CacheSelector, DerivedIndexReconciler, IndexKey, OptimisticCacheWriter, OptimisticLayerContext, OptimisticLayerState, RecordKey, WatchOptions } from './types.js';
+import type { BaseCacheWriter, CacheEngine, CacheEngineOptions, CacheEngineSnapshot, CacheListener, CacheSelector, DerivedIndexReconciler, IndexKey, OptimisticCacheWriter, OptimisticLayerContext, OptimisticLayerReplacement, OptimisticLayerState, RecordKey, WatchOptions } from './types.js';
 /**
  * Minimum purpose-built implementation selected by the executable spike.
  *
@@ -16,6 +16,7 @@ export declare class PurposeBuiltCacheEngine implements CacheEngine {
     watch<T>(selector: CacheSelector<T>, listener: CacheListener<T>, options?: WatchOptions): () => void;
     batch<T>(update: (writer: BaseCacheWriter) => T): T;
     createOptimisticLayer(id: string, update: (writer: OptimisticCacheWriter) => void, context?: OptimisticLayerContext): void;
+    replaceOptimisticLayer(id: string, replacement: OptimisticLayerReplacement, context?: OptimisticLayerContext): boolean;
     setDerivedIndexReconciler(reconciler: DerivedIndexReconciler | undefined): void;
     markOptimisticLayerAccepted(id: string): boolean;
     confirmOptimisticLayer<T>(id: string, update: (writer: BaseCacheWriter) => T): T;
@@ -25,6 +26,7 @@ export declare class PurposeBuiltCacheEngine implements CacheEngine {
     extract(): CacheEngineSnapshot;
     restore(snapshot: CacheEngineSnapshot): void;
     restoreConfirmed(snapshot: CacheEngineSnapshot): void;
+    mergeConfirmed(snapshot: CacheEngineSnapshot): void;
     discardIndexes(keys: readonly IndexKey[]): void;
     retain(key: RecordKey): void;
     release(key: RecordKey): void;

package/dist/internal/cache-engine/engine.js

@@ -1,4 +1,4 @@
-import { CacheRevisionConflictError } from './errors.js';
+import { CacheRevisionConflictError, OptimisticLayerNotFoundError } from './errors.js';
 import { assertName, assertSynchronousResult, assertWriterActive, cloneCacheValue, cloneDerivedIndexOperations, cloneFields, cloneIndexMetadata, cloneLink, cloneLinks, compareRecordTuple, deepEqual, dependenciesChanged, derivedIndexKeys, emptyVisibleRecord, freezeRecord, indexDependency, indexMetadataWithoutStaleReason, isOrderedSubsequence, isVisibleRecordLive, linkKeys, operationDependencies, parseSnapshot, recordFieldDependency, recordSeenDependency, recordWildcardDependency, refinementMetadataCompatible, reportSafely, reportUnhandledWatcherError, revisionString, revisionToken, runDerivedIndexReconciler, validateIndexWrite, validateRecordKey } from './helpers.js';
 /**
  * Minimum purpose-built implementation selected by the executable spike.
@@ -106,6 +106,41 @@ export class PurposeBuiltCacheEngine {
             this.#reconcileDerivedIndexes();
         });
     }
+    replaceOptimisticLayer(id, replacement, context) {
+        assertName(id, 'optimistic layer id');
+        if (typeof replacement !== 'function') {
+            throw new TypeError('optimistic layer replacement must be a function');
+        }
+        return this.#transaction(() => {
+            const targetIndex = this.#layers.findIndex((candidate) => candidate.id === id);
+            if (targetIndex === -1) {
+                throw new OptimisticLayerNotFoundError(id);
+            }
+            const target = this.#layers[targetIndex];
+            const before = this.#materialize();
+            const prefixLayers = this.#layers.slice(0, targetIndex);
+            const prefixDerivedIndexes = this.#deriveIndexOperations(prefixLayers);
+            const prefix = this.#materialize(true, prefixLayers, prefixDerivedIndexes);
+            const operations = [];
+            this.#runOptimisticReplacement(replacement, this.#readerFromGraph(prefix), operations);
+            const stableContext = context === undefined ? target.context : cloneCacheValue(context);
+            if (deepEqual(operations, target.operations) &&
+                deepEqual(stableContext, target.context))
+                return false;
+            const previousOperations = target.operations;
+            target.operations = operations;
+            if (stableContext === undefined)
+                delete target.context;
+            else
+                target.context = stableContext;
+            this.#reconcileDerivedIndexes();
+            const after = this.#materialize();
+            this.#markOverlayChanges([...previousOperations, ...operations], before, after);
+            this.#markIndexGraphChanges(before, after);
+            this.#dirty = true;
+            return true;
+        });
+    }
     setDerivedIndexReconciler(reconciler) {
         if (reconciler !== undefined && typeof reconciler !== 'function') {
             throw new TypeError('derived index reconciler must be a function');
@@ -267,6 +302,24 @@ export class PurposeBuiltCacheEngine {
             this.#reconcileDerivedIndexes();
         });
     }
+    mergeConfirmed(snapshot) {
+        const restored = parseSnapshot(snapshot);
+        this.#transaction(() => {
+            // Seed is authoritative for keys it contains; keys it omits stay.
+            for (const [key, record] of restored.records) {
+                this.#records.set(key, record);
+                this.#changedDependencies.add(recordSeenDependency(key));
+                this.#changedDependencies.add(recordWildcardDependency(key));
+            }
+            for (const [key, index] of restored.indexes) {
+                this.#indexes.set(key, index);
+                this.#changedDependencies.add(indexDependency(key));
+            }
+            this.#derivedIndexOperations = [];
+            this.#dirty = true;
+            this.#reconcileDerivedIndexes();
+        });
+    }
     discardIndexes(keys) {
         const unique = new Set();
         for (const key of keys) {
@@ -348,7 +401,9 @@ export class PurposeBuiltCacheEngine {
         // O(records + indexes + overlay operations) per selector. The private seam
         // keeps this replaceable with an incrementally indexed graph without
         // changing generated artifacts or the public replica API.
-        const { records, indexes } = this.#materialize(includeOptimistic);
+        return this.#readerFromGraph(this.#materialize(includeOptimistic), dependencies);
+    }
+    #readerFromGraph({ records, indexes }, dependencies) {
         return Object.freeze({
             recordMeta(key) {
                 dependencies?.add(recordSeenDependency(key));
@@ -496,7 +551,7 @@ export class PurposeBuiltCacheEngine {
         }
         return reachable;
     }
-    #materialize(includeOptimistic = true) {
+    #materialize(includeOptimistic = true, layers = this.#layers, derivedIndexOperations = this.#derivedIndexOperations) {
         const records = new Map();
         const indexes = new Map();
         for (const [key, record] of this.#records) {
@@ -519,12 +574,12 @@ export class PurposeBuiltCacheEngine {
             });
         }
         if (includeOptimistic) {
-            for (const layer of this.#layers) {
+            for (const layer of layers) {
                 for (const operation of layer.operations) {
                     this.#applyOverlay(records, indexes, layer.sequence, operation);
                 }
             }
-            for (const operation of this.#derivedIndexOperations) {
+            for (const operation of derivedIndexOperations) {
                 this.#applyDerivedIndexOperation(records, indexes, operation);
             }
         }
@@ -538,6 +593,9 @@ export class PurposeBuiltCacheEngine {
                 for (const name of Object.keys(operation.write.fields ?? {})) {
                     this.#changedDependencies.add(recordFieldDependency(key, `field:${name}`));
                 }
+                for (const name of operation.write.unset ?? []) {
+                    this.#changedDependencies.add(recordFieldDependency(key, `field:${name}`));
+                }
                 for (const name of Object.keys(operation.write.links ?? {})) {
                     this.#changedDependencies.add(recordFieldDependency(key, `link:${name}`));
                 }
@@ -558,10 +616,24 @@ export class PurposeBuiltCacheEngine {
             this.#changedDependencies.add(indexDependency(operation.kind === 'write-index' ? operation.write.key : operation.key));
         }
     }
+    #markIndexGraphChanges(before, after) {
+        for (const key of new Set([
+            ...before.indexes.keys(),
+            ...after.indexes.keys()
+        ])) {
+            if (deepEqual(before.indexes.get(key), after.indexes.get(key))) {
+                continue;
+            }
+            this.#changedDependencies.add(indexDependency(key));
+        }
+    }
     #applyOverlay(records, indexes, sequence, operation) {
         if (operation.kind === 'write-record') {
-            const { key, fields = {}, links = {} } = operation.write;
+            const { key, fields = {}, links = {}, unset = [] } = operation.write;
             let record = records.get(key);
+            if (operation.write.ifPresent === true && (!record || record.tombstoned)) {
+                return;
+            }
             let wrote = false;
             for (const [name, value] of Object.entries(fields)) {
                 if (sequence <= this.#recordFieldFloor(key, `field:${name}`))
@@ -579,6 +651,14 @@ export class PurposeBuiltCacheEngine {
                 record.links.set(name, value);
                 wrote = true;
             }
+            for (const name of unset) {
+                if (sequence <= this.#recordFieldFloor(key, `field:${name}`))
+                    continue;
+                if (!record || !record.fields.has(name))
+                    continue;
+                record.fields.delete(name);
+                wrote = true;
+            }
             if (wrote && record) {
                 record.tombstoned = false;
                 records.set(key, record);
@@ -707,6 +787,22 @@ export class PurposeBuiltCacheEngine {
         });
     }
     #reconcileDerivedIndexes() {
+        const next = this.#deriveIndexOperations(this.#layers);
+        const before = this.#materialize();
+        const previous = this.#derivedIndexOperations;
+        this.#derivedIndexOperations = [...next];
+        const after = this.#materialize();
+        let changed = false;
+        for (const key of derivedIndexKeys([...previous, ...next])) {
+            if (deepEqual(before.indexes.get(key), after.indexes.get(key)))
+                continue;
+            this.#changedDependencies.add(indexDependency(key));
+            changed = true;
+        }
+        if (changed)
+            this.#dirty = true;
+    }
+    #deriveIndexOperations(layers) {
         if (this.#reconcilingDerivedIndexes) {
             throw new Error('derived index reconciliation cannot be re-entered');
         }
@@ -717,7 +813,7 @@ export class PurposeBuiltCacheEngine {
             next =
                 reconciler === undefined
                     ? []
-                    : cloneDerivedIndexOperations(runDerivedIndexReconciler(reconciler, this.extract(), this.#layers.map((layer) => Object.freeze({
+                    : cloneDerivedIndexOperations(runDerivedIndexReconciler(reconciler, this.extract(), layers.map((layer) => Object.freeze({
                         id: layer.id,
                         sequence: layer.sequence,
                         state: layer.state,
@@ -729,19 +825,7 @@ export class PurposeBuiltCacheEngine {
         finally {
             this.#reconcilingDerivedIndexes = false;
         }
-        const before = this.#materialize();
-        const previous = this.#derivedIndexOperations;
-        this.#derivedIndexOperations = [...next];
-        const after = this.#materialize();
-        let changed = false;
-        for (const key of derivedIndexKeys([...previous, ...next])) {
-            if (deepEqual(before.indexes.get(key), after.indexes.get(key)))
-                continue;
-            this.#changedDependencies.add(indexDependency(key));
-            changed = true;
-        }
-        if (changed)
-            this.#dirty = true;
+        return next;
     }
     #recordFieldFloor(key, field) {
         return Math.max(this.#confirmedFloors.get(recordWildcardDependency(key)) ?? 0, this.#confirmedFloors.get(recordFieldDependency(key, field)) ?? 0);
@@ -793,9 +877,29 @@ export class PurposeBuiltCacheEngine {
                 validateRecordKey(write.key);
                 const fields = cloneFields(write.fields);
                 const links = cloneLinks(write.links);
-                if (Object.keys(fields).length === 0 && Object.keys(links).length === 0)
+                const unset = Object.freeze([...(write.unset ?? [])]);
+                for (const name of unset)
+                    assertName(name, 'record field');
+                if (new Set(unset).size !== unset.length) {
+                    throw new TypeError('record unset fields must be unique');
+                }
+                if (unset.some((name) => Object.hasOwn(fields, name))) {
+                    throw new TypeError('record field cannot be set and unset');
+                }
+                if (Object.keys(fields).length === 0 &&
+                    Object.keys(links).length === 0 &&
+                    unset.length === 0)
                     return;
-                operations.push({ kind: 'write-record', write: { key: write.key, fields, links } });
+                operations.push({
+                    kind: 'write-record',
+                    write: {
+                        key: write.key,
+                        fields,
+                        links,
+                        ...(unset.length === 0 ? {} : { unset }),
+                        ...(write.ifPresent === true ? { ifPresent: true } : {})
+                    }
+                });
             },
             tombstoneRecord(key) {
                 assertWriterActive(isActive());
@@ -847,6 +951,17 @@ export class PurposeBuiltCacheEngine {
             active = false;
         }
     }
+    #runOptimisticReplacement(replacement, reader, operations) {
+        let active = true;
+        const writer = this.#optimisticWriter(operations, () => active);
+        try {
+            const result = replacement(reader, writer);
+            assertSynchronousResult(result, 'optimistic layer replacement');
+        }
+        finally {
+            active = false;
+        }
+    }
     #writeBaseRecord(write, touched) {
         validateRecordKey(write.key);
         const revision = revisionToken(write.revision);

package/dist/internal/cache-engine/errors.d.ts

@@ -3,3 +3,7 @@ export declare class CacheRevisionConflictError extends Error {
     readonly revision: string;
     constructor(dependency: string, revision: bigint);
 }
+export declare class OptimisticLayerNotFoundError extends Error {
+    readonly layerId: string;
+    constructor(layerId: string);
+}

package/dist/internal/cache-engine/errors.js

@@ -8,3 +8,11 @@ export class CacheRevisionConflictError extends Error {
         this.revision = revision.toString(10);
     }
 }
+export class OptimisticLayerNotFoundError extends Error {
+    layerId;
+    constructor(layerId) {
+        super(`optimistic layer not found: ${layerId}`);
+        this.name = 'OptimisticLayerNotFoundError';
+        this.layerId = layerId;
+    }
+}

package/dist/internal/cache-engine/index.d.ts

@@ -1,3 +1,3 @@
-export type { BaseCacheWriter, BaseRecordClock, CacheEngine, CacheEngineOptions, CacheEngineSnapshot, CacheIndex, CacheIndexCoverage, CacheIndexMetadata, CacheListener, CachePresence, CacheReader, CacheSelector, CacheValue, DerivedIndexMutation, DerivedIndexReconciler, IndexKey, IndexWrite, OptimisticCacheWriter, OptimisticIndexWrite, OptimisticLayerContext, OptimisticLayerState, OptimisticLayerView, OptimisticRecordWrite, RecordKey, RecordLink, RecordWrite, Revision, SparseRecord, SparseRecordMeta, WatchOptions } from './types.js';
-export { CacheRevisionConflictError } from './errors.js';
+export type { BaseCacheWriter, BaseRecordClock, CacheEngine, CacheEngineOptions, CacheEngineSnapshot, CacheIndex, CacheIndexCoverage, CacheIndexMetadata, CacheListener, CachePresence, CacheReader, CacheSelector, CacheValue, DerivedIndexMutation, DerivedIndexReconciler, IndexKey, IndexWrite, OptimisticCacheWriter, OptimisticIndexWrite, OptimisticLayerContext, OptimisticLayerReplacement, OptimisticLayerState, OptimisticLayerView, OptimisticRecordWrite, RecordKey, RecordLink, RecordWrite, Revision, SparseRecord, SparseRecordMeta, WatchOptions } from './types.js';
+export { CacheRevisionConflictError, OptimisticLayerNotFoundError } from './errors.js';
 export { cacheIndexKey, createCacheEngine } from './create.js';

package/dist/internal/cache-engine/index.js

@@ -1,2 +1,2 @@
-export { CacheRevisionConflictError } from './errors.js';
+export { CacheRevisionConflictError, OptimisticLayerNotFoundError } from './errors.js';
 export { cacheIndexKey, createCacheEngine } from './create.js';

package/dist/internal/cache-engine/types.d.ts

@@ -12,6 +12,10 @@ export type RecordWrite = {
     incarnation?: Revision;
     /** Omitted fields stay absent. A present `null` remains present. */
     fields?: Readonly<Record<string, CacheValue>>;
+    /** Optimistic-only field removals; base writes never use this member. */
+    unset?: readonly string[];
+    /** Optimistic-only guard which suppresses the whole write when absent. */
+    ifPresent?: boolean;
     /** Relationship identities are stored separately from scalar/JSON fields. */
     links?: Readonly<Record<string, RecordLink>>;
 };
@@ -113,6 +117,7 @@ export interface OptimisticCacheWriter {
     writeIndex(write: OptimisticIndexWrite): void;
     deleteIndex(key: IndexKey): void;
 }
+export type OptimisticLayerReplacement = (reader: CacheReader, writer: OptimisticCacheWriter) => void;
 export type CacheSelector<T> = (reader: CacheReader) => T;
 export type CacheListener<T> = (value: T, previous: T | undefined) => void;
 export type WatchOptions = {
@@ -191,6 +196,11 @@ export interface CacheEngine {
     watch<T>(selector: CacheSelector<T>, listener: CacheListener<T>, options?: WatchOptions): () => void;
     batch<T>(update: (writer: BaseCacheWriter) => T): T;
     createOptimisticLayer(id: string, update: (writer: OptimisticCacheWriter) => void, context?: OptimisticLayerContext): void;
+    /**
+     * Atomically replace a layer in place. The replacement evaluates against
+     * confirmed state plus only the optimistic layers below the target.
+     */
+    replaceOptimisticLayer(id: string, replacement: OptimisticLayerReplacement, context?: OptimisticLayerContext): boolean;
     setDerivedIndexReconciler(reconciler: DerivedIndexReconciler | undefined): void;
     markOptimisticLayerAccepted(id: string): boolean;
     confirmOptimisticLayer<T>(id: string, update: (writer: BaseCacheWriter) => T): T;
@@ -204,6 +214,12 @@ export interface CacheEngine {
      * their acceptance state, and causal sequencing floors.
      */
     restoreConfirmed(snapshot: CacheEngineSnapshot): void;
+    /**
+     * Upsert confirmed records/indexes from a same-scope seed without deleting
+     * keys the seed omitted. Used when a warm SPA client re-receives a
+     * route-local SSR dehydrate that is a subset of the session cache.
+     */
+    mergeConfirmed(snapshot: CacheEngineSnapshot): void;
     /**
      * Drop incomparable/reset base indexes without assigning them a fabricated
      * revision. Pending optimistic overlays remain layered above the new gap.

package/dist/internal/cache-engine.d.ts

@@ -1,3 +1,3 @@
 /** Private cache engine; implementation lives in ./cache-engine/. */
-export { CacheRevisionConflictError, cacheIndexKey, createCacheEngine } from './cache-engine/index.js';
-export type { BaseCacheWriter, BaseRecordClock, CacheEngine, CacheEngineOptions, CacheEngineSnapshot, CacheIndex, CacheIndexCoverage, CacheIndexMetadata, CacheListener, CachePresence, CacheReader, CacheSelector, CacheValue, DerivedIndexMutation, DerivedIndexReconciler, IndexKey, IndexWrite, OptimisticCacheWriter, OptimisticIndexWrite, OptimisticLayerContext, OptimisticLayerState, OptimisticLayerView, OptimisticRecordWrite, RecordKey, RecordLink, RecordWrite, Revision, SparseRecord, SparseRecordMeta, WatchOptions } from './cache-engine/index.js';
+export { CacheRevisionConflictError, OptimisticLayerNotFoundError, cacheIndexKey, createCacheEngine } from './cache-engine/index.js';
+export type { BaseCacheWriter, BaseRecordClock, CacheEngine, CacheEngineOptions, CacheEngineSnapshot, CacheIndex, CacheIndexCoverage, CacheIndexMetadata, CacheListener, CachePresence, CacheReader, CacheSelector, CacheValue, DerivedIndexMutation, DerivedIndexReconciler, IndexKey, IndexWrite, OptimisticCacheWriter, OptimisticIndexWrite, OptimisticLayerContext, OptimisticLayerReplacement, OptimisticLayerState, OptimisticLayerView, OptimisticRecordWrite, RecordKey, RecordLink, RecordWrite, Revision, SparseRecord, SparseRecordMeta, WatchOptions } from './cache-engine/index.js';

package/dist/internal/cache-engine.js

@@ -1,2 +1,2 @@
 /** Private cache engine; implementation lives in ./cache-engine/. */
-export { CacheRevisionConflictError, cacheIndexKey, createCacheEngine } from './cache-engine/index.js';
+export { CacheRevisionConflictError, OptimisticLayerNotFoundError, cacheIndexKey, createCacheEngine } from './cache-engine/index.js';

package/dist/protocol.d.ts

@@ -6,6 +6,7 @@
  * positions remain opaque strings: the JavaScript client compares or returns
  * them, but never parses them as numbers or reconstructs server scopes.
  */
+import { type CommandProjectionMetadata } from './replica/projection-delta/index.js';
 /** The only Distributed GraphQL protocol version understood by this package. */
 export declare const DISTRIBUTED_PROTOCOL_VERSION: 1;
 declare const opaqueDistributedString: unique symbol;
@@ -18,8 +19,10 @@ export type DistributedOpaqueString = string & {
 export type DistributedDecimalString = string & {
     readonly [distributedDecimalString]: true;
 };
-export type DistributedCommandState = 'in_progress' | 'accepted' | 'accepted_pending_projection' | 'projected' | 'rejected' | 'projection_failed' | 'expired' | 'unknown';
-export type DistributedCommandConsistency = 'accepted' | 'fact' | 'projected';
+export type DistributedCommandState = 'in_progress' | 'succeeded' | 'succeeded_pending_projection' | 'atomic' | 'rejected' | 'projection_failed' | 'expired' | 'unknown';
+export type DistributedCommandConsistency = 'succeeded' | 'eventual' | 'atomic';
+/** Current-scope handling for authenticated historical projector evidence. */
+export type DistributedProjectionDisposition = 'revalidate';
 /** Closed wire codecs for server-derived, client-visible trusted presets. */
 export type DistributedTrustedPresetCodec = 'string' | 'string_unvalidated_timestamp' | 'base64' | 'boolean' | 'int32' | 'float64' | 'json_number_precision_limited' | 'json';
 /** JSON value accepted by the Distributed protocol parser. */
@@ -107,16 +110,20 @@ export type DistributedCommandMetadata = Readonly<Record<string, unknown> & {
     causationId: DistributedOpaqueString;
     state: DistributedCommandState;
     consistency: DistributedCommandConsistency;
+    projectionDisposition?: DistributedProjectionDisposition;
     expects: readonly DistributedProjectionExpectation[];
     /** Defaults to an empty array when omitted by the compact wire format. */
     observations: readonly DistributedProjectionObservation[];
     /** Defaults to an empty array when omitted by the compact wire format. */
     records: readonly DistributedRecordRevision[];
+    /** Exact modeled projection delta and opaque observation obligations. */
+    projection?: CommandProjectionMetadata;
 }>;
 /** Canonical contents of top-level `extensions.distributed`. */
 export type DistributedProtocolEnvelope = Readonly<Record<string, unknown> & {
     protocolVersion: typeof DISTRIBUTED_PROTOCOL_VERSION;
     schemaHash: string;
+    authorizationGeneration: string;
     cacheScope: DistributedOpaqueString;
     operation?: string;
     command?: DistributedCommandMetadata;

package/dist/protocol.js

@@ -6,6 +6,7 @@
  * positions remain opaque strings: the JavaScript client compares or returns
  * them, but never parses them as numbers or reconstructs server scopes.
  */
+import { parseCommandProjectionMetadata } from './replica/projection-delta/index.js';
 /** The only Distributed GraphQL protocol version understood by this package. */
 export const DISTRIBUTED_PROTOCOL_VERSION = 1;
 /** Safe parse failure that reports structure, never hidden server values. */
@@ -23,18 +24,18 @@ export class DistributedProtocolError extends Error {
 }
 const COMMAND_STATES = new Set([
     'in_progress',
-    'accepted',
-    'accepted_pending_projection',
-    'projected',
+    'succeeded',
+    'succeeded_pending_projection',
+    'atomic',
     'rejected',
     'projection_failed',
     'expired',
     'unknown'
 ]);
 const COMMAND_CONSISTENCIES = new Set([
-    'accepted',
-    'fact',
-    'projected'
+    'succeeded',
+    'eventual',
+    'atomic'
 ]);
 const MAX_PUBLIC_NAME_LENGTH = 512;
 const MAX_OPAQUE_STRING_LENGTH = 16_384;
@@ -79,6 +80,7 @@ export function parseDistributedProtocolEnvelope(value) {
         invalid('extensions.distributed.protocolVersion');
     }
     const schemaHash = publicString(envelope.schemaHash, 'extensions.distributed.schemaHash');
+    const authorizationGeneration = publicString(envelope.authorizationGeneration, 'extensions.distributed.authorizationGeneration');
     const cacheScope = opaqueString(envelope.cacheScope, 'extensions.distributed.cacheScope');
     const operation = envelope.operation === undefined
         ? undefined
@@ -98,6 +100,7 @@ export function parseDistributedProtocolEnvelope(value) {
         ...envelope,
         protocolVersion: DISTRIBUTED_PROTOCOL_VERSION,
         schemaHash,
+        authorizationGeneration,
         cacheScope,
         ...(operation === undefined ? {} : { operation }),
         ...(command === undefined ? {} : { command }),
@@ -184,6 +187,14 @@ function parseCommand(value) {
     });
     const observations = parseOptionalEvidenceArray(command.observations, 'extensions.distributed.command.observations', parseProjectionObservation);
     const records = parseOptionalEvidenceArray(command.records, 'extensions.distributed.command.records', parseRecordRevision);
+    const projection = command.projection === undefined
+        ? undefined
+        : parseCommandProjectionMetadata(command.projection);
+    const projectionDisposition = command.projectionDisposition === undefined
+        ? undefined
+        : command.projectionDisposition === 'revalidate'
+            ? 'revalidate'
+            : invalid('extensions.distributed.command.projectionDisposition');
     const commandId = opaqueString(command.commandId, 'extensions.distributed.command.commandId');
     const causationId = opaqueString(command.causationId, 'extensions.distributed.command.causationId');
     const expectationKeys = new Set(expects.map(projectionExpectationKey));
@@ -197,15 +208,32 @@ function parseCommand(value) {
         }
         seenObservations.add(key);
     }
+    if (projectionDisposition === 'revalidate' &&
+        (projection !== undefined ||
+            expects.length !== 0 ||
+            observations.length !== 0 ||
+            records.length !== 0 ||
+            ![
+                'succeeded',
+                'succeeded_pending_projection',
+                'atomic',
+                'projection_failed'
+            ].includes(state))) {
+        invalid('extensions.distributed.command.projectionDisposition');
+    }
     return Object.freeze({
         ...command,
         commandId,
         causationId,
         state,
         consistency,
+        ...(projectionDisposition === undefined
+            ? {}
+            : { projectionDisposition }),
         expects: Object.freeze(expects),
         observations,
-        records
+        records,
+        ...(projection === undefined ? {} : { projection })
     });
 }
 function parseSnapshot(value) {