@hops-ops/distributed 0.0.0 → 4.0.0

package/dist/replica/projection-delta/wasm-pure.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Framework host for pure reduces backed by a wasm-bindgen module.
+ *
+ * Domain pures validate record/args and return assign fields (or null).
+ * This helper only: lazy-load, JSON bridge, fail-closed on any host error.
+ */
+import type { ReplicaPureFunction } from './types.js';
+/** Minimal wasm-bindgen module shape used by {@link createWasmJsonPure}. */
+export type WasmJsonModule = {
+    default: () => Promise<unknown>;
+    [exportName: string]: unknown;
+};
+export type CreateWasmJsonPureOptions = Readonly<{
+    /** Dynamic import of the wasm-pack module (e.g. `() => import('./pkg/x.js')`). */
+    load: () => Promise<WasmJsonModule>;
+    /**
+     * Named export that accepts `(recordJson: string, argsJson: string)` and
+     * returns a JSON object string of assign fields, or undefined/null to skip.
+     */
+    exportName: string;
+    /** When true (default in browsers), start loading immediately. */
+    warm?: boolean;
+}>;
+export type WasmJsonPureHost = Readonly<{
+    /** Resolve when the module is instantiated (no-op on non-browser). */
+    ensureReady: () => Promise<void>;
+    /** Sync pure for `pureFunctions` / pureReduces. */
+    pure: ReplicaPureFunction;
+}>;
+/**
+ * Build a {@link ReplicaPureFunction} that JSON-roundtrips through a WASM export.
+ *
+ * All field validation belongs in the WASM/domain pure. The host never inspects
+ * individual record/arg keys — missing module or throw → null (fail closed).
+ */
+export declare function createWasmJsonPure(options: CreateWasmJsonPureOptions): WasmJsonPureHost;

package/dist/replica/projection-delta/wasm-pure.js

@@ -0,0 +1,71 @@
+/**
+ * Framework host for pure reduces backed by a wasm-bindgen module.
+ *
+ * Domain pures validate record/args and return assign fields (or null).
+ * This helper only: lazy-load, JSON bridge, fail-closed on any host error.
+ */
+function isBrowser() {
+    return typeof globalThis !== 'undefined' && 'window' in globalThis;
+}
+/**
+ * Build a {@link ReplicaPureFunction} that JSON-roundtrips through a WASM export.
+ *
+ * All field validation belongs in the WASM/domain pure. The host never inspects
+ * individual record/arg keys — missing module or throw → null (fail closed).
+ */
+export function createWasmJsonPure(options) {
+    let module = null;
+    let initPromise = null;
+    const ensureReady = () => {
+        if (!isBrowser()) {
+            return Promise.resolve();
+        }
+        if (module) {
+            return Promise.resolve();
+        }
+        if (initPromise) {
+            return initPromise;
+        }
+        initPromise = options
+            .load()
+            .then(async (loaded) => {
+            await loaded.default();
+            module = loaded;
+        })
+            .catch((error) => {
+            initPromise = null;
+            module = null;
+            throw error;
+        });
+        return initPromise;
+    };
+    if (options.warm !== false && isBrowser()) {
+        void ensureReady().catch(() => {
+            /* fail closed on first pure call */
+        });
+    }
+    const pure = (record, args) => {
+        if (!module) {
+            return null;
+        }
+        const fn = module[options.exportName];
+        if (typeof fn !== 'function') {
+            return null;
+        }
+        try {
+            const out = fn(JSON.stringify(record), JSON.stringify(args));
+            if (out === undefined || out === null || out === '') {
+                return null;
+            }
+            const parsed = JSON.parse(out);
+            if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+                return null;
+            }
+            return Object.freeze(parsed);
+        }
+        catch {
+            return null;
+        }
+    };
+    return Object.freeze({ ensureReady, pure });
+}

package/dist/replica/query-plan/pagination.js

@@ -21,19 +21,29 @@ export function decideReplicaPaginationMaintenance(artifact, coverage, change) {
         }
         if (coverage.kind === 'offset' &&
             coverage.offset === 0 &&
-            coverage.limit !== undefined &&
-            coverage.returned !== undefined &&
-            coverage.returned < coverage.limit) {
-            // A non-full first page proves that the server returned the complete
-            // ordered set. The index runtime can therefore apply all optimistic
-            // membership/order changes and truncate back to the declared limit.
-            return PAGINATION_LOCAL;
+            coverage.limit !== undefined) {
+            /*
+             * First-page (offset 0) locality:
+             * - insert: always local when a limit is known. The maintainer
+             *   re-sorts known members and truncates to the window, so a full
+             *   lobby page still shows an optimistic chat/todo at the front.
+             * - delete/reorder: only when the page is non-full (complete ordered
+             *   set). A full page with hasNext cannot prove the next boundary
+             *   after a delete or order change.
+             */
+            if (change.kind === 'insert') {
+                return PAGINATION_LOCAL;
+            }
+            if (coverage.returned !== undefined &&
+                coverage.returned < coverage.limit) {
+                return PAGINATION_LOCAL;
+            }
         }
     }
     const [code, message] = change.kind === 'insert'
         ? [
             'insert_changes_offset_window',
-            'an insert is local only for a proven non-full first offset page'
+            'an insert is local only for the first offset page (offset 0) with a known limit'
         ]
         : change.kind === 'delete'
             ? [

package/dist/replica/types.d.ts

@@ -10,6 +10,8 @@ export type ReplicaIndexRecordChange = {
     readonly model: string;
     readonly key: string;
     readonly fields: Readonly<Record<string, ReplicaValue>>;
+    readonly unset?: readonly string[];
+    readonly ifPresent?: boolean;
     readonly dependencies?: readonly string[];
 } | {
     readonly kind: 'delete';
@@ -432,7 +434,8 @@ export type ReplicaClientSurface = {
 } | {
     readonly kind: 'application';
     readonly name: string;
-    readonly roles: readonly string[];
+    readonly eligible_roles: readonly string[];
+    readonly schema_roles: readonly string[];
 };
 /** Compiler-owned causal artifact. Protocol and variable identity are inseparable. */
 export type ReplicaProtocolOperationArtifact<TData = Record<string, unknown>, TVariables extends GraphqlVariables = GraphqlVariables> = ReplicaOperationArtifactBase<TData, TVariables> & {
@@ -441,7 +444,7 @@ export type ReplicaProtocolOperationArtifact<TData = Record<string, unknown>, TV
     readonly variableCodec: ReplicaVariableCodecArtifact;
 };
 export type ReplicaOperationArtifact<TData = Record<string, unknown>, TVariables extends GraphqlVariables = GraphqlVariables> = ReplicaProtocolOperationArtifact<TData, TVariables>;
-export type ReplicaWriteSource = 'network' | 'live' | 'ssr' | 'restore' | 'projected';
+export type ReplicaWriteSource = 'network' | 'live' | 'ssr' | 'restore' | 'atomic';
 export type ReplicaResultEnvelope<TData = unknown> = {
     readonly data?: TData | null;
     readonly errors?: readonly GqlError[];
@@ -536,6 +539,7 @@ export type DistributedReplicaOptions = {
 export type ReplicaAuthoritativeScope = {
     readonly protocolVersion: 1;
     readonly schemaHash: string;
+    readonly authorizationGeneration: string;
     readonly cacheScope: string;
 };
 /**
@@ -597,6 +601,8 @@ export type ReplicaIndexTarget = {
 };
 export type ReplicaRecordPatch = {
     readonly fields?: Readonly<Record<string, ReplicaValue>>;
+    readonly unset?: readonly string[];
+    readonly ifPresent?: boolean;
     readonly links?: Readonly<Record<string, string | readonly string[] | null>>;
 };
 export interface ReplicaOptimisticWriter {
@@ -640,6 +646,11 @@ export interface DistributedReplica {
      * scope for the current SSR response. Returns false on scope/schema mismatch
      * and never partially restores malformed state. Persisted state must wait for
      * a fresh server scope and pass that scope here.
+     *
+     * Cold clients (no active scope) replace from the seed. Warm same-scope
+     * re-hydrate merges seed records/indexes and retains confirmed keys the seed
+     * omitted—soft navigation must not wipe session cache because a route only
+     * dehydrated its page subset. Auth/scope change still purges.
      */
     hydrate(state: ReplicaDehydratedState, authoritativeScope: ReplicaAuthoritativeScope): boolean;
     createOptimisticLayer(id: string, update: (writer: ReplicaOptimisticWriter) => void, semanticChanges?: readonly ReplicaIndexSemanticChange[]): void;

package/dist/sveltekit/replica.d.ts

@@ -68,7 +68,7 @@ export type CreateDistributedSvelteKitOptions<TCommands = Readonly<Record<never,
 export type SveltekitQuerySnapshot<TData> = ReplicaSnapshot<TData> & Readonly<{
     loading: boolean;
     error?: GqlError;
-    /** Causally accepted commands still waiting for projection visibility. */
+    /** Successful causal commands still waiting for projection visibility. */
     pending: readonly ReplicaCommandReceipt<unknown>[];
     refetch(): Promise<void>;
 }>;

package/dist/sveltekit/replica.js

@@ -478,6 +478,8 @@ function validatedHydrationAuthority(value) {
         scope.protocolVersion !== 1 ||
         typeof scope.schemaHash !== 'string' ||
         scope.schemaHash.length === 0 ||
+        typeof scope.authorizationGeneration !== 'string' ||
+        scope.authorizationGeneration.length === 0 ||
         typeof scope.cacheScope !== 'string' ||
         scope.cacheScope.length === 0) {
         throw new TypeError('Distributed SvelteKit hydration authority is invalid');
@@ -487,5 +489,6 @@ function validatedHydrationAuthority(value) {
 function sameReplicaScope(left, right) {
     return (left.protocolVersion === right.protocolVersion &&
         left.schemaHash === right.schemaHash &&
+        left.authorizationGeneration === right.authorizationGeneration &&
         left.cacheScope === right.cacheScope);
 }

package/dist/sveltekit/vite.d.ts

@@ -12,7 +12,7 @@ export declare function distributedGraphqlProxy(options: DistributedGraphqlProxy
 }>;
 export type DistributedSvelteKitManifestSource = string | Readonly<{
     /**
-     * Arguments passed to the configured dctl command. The first value
+     * Arguments passed to the configured distributed command. The first value
      * must be `client-manifest`; stdout becomes ephemeral compiler input.
      */
     args: readonly string[];
@@ -20,13 +20,13 @@ export type DistributedSvelteKitManifestSource = string | Readonly<{
 export type DistributedSvelteKitClientCompiler = Readonly<{
     /** `$distributed` or an explicit elevated entrypoint such as `$distributed/admin`. */
     module: string;
-    /** Existing manifest path, or canonical `dctl client-manifest` argv. */
+    /** Existing manifest path, or canonical `distributed client-manifest` argv. */
     manifest: DistributedSvelteKitManifestSource;
     /** Verify exactly one concrete role. Mutually exclusive with `surface`. */
     role?: string;
     /** Verify exactly one Rust-declared application surface. */
     surface?: string;
-    /** GraphQL globs passed verbatim as repeated `dctl client --documents`. */
+    /** GraphQL globs passed verbatim as repeated `distributed client --documents`. */
     documents: readonly string[];
     /** Explicit `OPERATION=/route` fallbacks. */
     routes?: readonly string[];
@@ -34,9 +34,9 @@ export type DistributedSvelteKitClientCompiler = Readonly<{
     out: string;
 }>;
 export type DistributedSvelteKitViteOptions = Readonly<{
-    /** Project root used for dctl cwd, document globs, and output containment. */
+    /** Project root used for distributed cwd, document globs, and output containment. */
     cwd?: string;
-    /** Executable invoked without a shell. Defaults to `dctl`. */
+    /** Executable invoked without a shell. Defaults to `distributed`. */
     command?: string;
     /** Prefix argv, e.g. `cargo run ... --`; never interpreted by a shell. */
     commandArgs?: readonly string[];
@@ -83,7 +83,7 @@ export type DistributedSvelteKitVitePlugin = Readonly<{
 }>;
 /** Generate every configured surface through the same transaction used by Vite. */
 export declare function generateDistributedSvelteKit(options: DistributedSvelteKitViteOptions): Promise<void>;
-/** Check every configured surface through canonical `dctl client --check`; never write. */
+/** Check every configured surface through canonical `distributed client --check`; never write. */
 export declare function checkDistributedSvelteKit(options: DistributedSvelteKitViteOptions): Promise<void>;
 /**
  * Compiler-watching Vite integration for one or more authorization surfaces.

package/dist/sveltekit/vite.js

@@ -26,7 +26,7 @@ export function distributedGraphqlProxy(options) {
 export async function generateDistributedSvelteKit(options) {
     await runCompilerOnce(options, 'generate');
 }
-/** Check every configured surface through canonical `dctl client --check`; never write. */
+/** Check every configured surface through canonical `distributed client --check`; never write. */
 export async function checkDistributedSvelteKit(options) {
     await runCompilerOnce(options, 'check');
 }
@@ -219,7 +219,7 @@ async function runCompilerOnce(options, mode) {
  * generation and is safe to call from `svelte.config.js`.
  */
 export function distributedSvelteKitAliases(options) {
-    const integration = resolveIntegration({ ...options, command: 'dctl', commandArgs: [] }, options.cwd ?? process.cwd());
+    const integration = resolveIntegration({ ...options, command: 'distributed', commandArgs: [] }, options.cwd ?? process.cwd());
     validateResolvedPathsSync(integration);
     return Object.freeze(Object.fromEntries([...integration.clients]
         .sort((left, right) => right.module.length - left.module.length ||
@@ -231,7 +231,7 @@ function resolveIntegration(options, fallbackCwd) {
         throw new TypeError('distributedSvelteKit requires configuration');
     }
     const cwd = resolve(options.cwd ?? fallbackCwd);
-    const command = (options.command ?? 'dctl').trim();
+    const command = (options.command ?? 'distributed').trim();
     if (command.length === 0) {
         throw new TypeError('Distributed SvelteKit command must not be empty');
     }
@@ -467,7 +467,7 @@ async function materializeManifest(integration, client, transaction, index, chil
         JSON.parse(result.stdout);
     }
     catch (error) {
-        throw new Error(`dctl client-manifest for ${client.module} did not emit valid JSON`, { cause: error });
+        throw new Error(`distributed client-manifest for ${client.module} did not emit valid JSON`, { cause: error });
     }
     const temporary = join(transaction, `manifest-${index}.json.tmp`);
     const manifest = join(transaction, `manifest-${index}.json`);
@@ -483,11 +483,11 @@ async function validateGeneratedEntrypoint(cwd, output, module) {
     const entry = join(output, GENERATED_SVELTEKIT_MODULE);
     const metadata = await lstat(entry);
     if (metadata.isSymbolicLink() || !metadata.isFile()) {
-        throw new Error(`dctl client for ${module} did not emit a regular ${GENERATED_SVELTEKIT_MODULE}`);
+        throw new Error(`distributed client for ${module} did not emit a regular ${GENERATED_SVELTEKIT_MODULE}`);
     }
     const canonical = await realpath(entry);
     if (!isWithin(root, canonical)) {
-        throw new Error(`dctl client entrypoint ${canonical} escaped project root ${root}`);
+        throw new Error(`distributed client entrypoint ${canonical} escaped project root ${root}`);
     }
 }
 async function commitOutputs(integration, staged, signal) {

package/package.json

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