@hops-ops/distributed

The generated, end-to-end typed client for Distributed services.

Rust table, relationship, role, and command definitions produce one authorized 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.

The intended application experience is:

const todos = Todos.use();
const commands = useCommands();
await commands.todo.create({ title });

Reads populate the replica on demand. Every UI consumer reads that same replica. Generated optimistic command effects update it synchronously, and server-issued record/index clocks reconcile the authoritative result without application-authored cache policies.

Install

npm install @hops-ops/distributed graphql

The package is ESM-only and requires Node 20 or newer for server-side use. It also runs in modern browsers. Svelte 5 and React are optional peers used only by the /sveltekit and /react entry points, respectively.

Generate the client surface

The service, not the browser, owns authorization and GraphQL semantics:

distributed client-manifest > target/distributed-client.json

distributed client \
  --manifest target/distributed-client.json \
  --role user \
  --documents 'src/**/*.graphql' \
  --out src/lib/generated/distributed

Use --surface <name> for a named application surface. CI can append --check to validate that committed artifacts are current without rewriting them.

A co-located route document can opt into SSR and live continuation:

query Todos @load @live {
  todos(order_by: [{ status: asc }, { todo_id: asc }]) {
    todo_id
    title
    status
  }
}

Generation validates the document against the selected role/application, injects wire-only identity and revision fields, and emits:

• an exact typed operation and optional live companion;
• normalization, identity, relationship, filter, order, and pagination plans;
• the closed variable codec used before cache lookup or transport;
• a static @load route registry;
• an SSR-safe SvelteKit wrapper with static operation bindings and tree-local client/command access;
• a nested command tree with input defaults, optimistic effects, and causal confirmation contracts;
• an exact schema, protocol, and client-surface binding.

Unsupported or unprovable behavior fails during generation. The runtime does not parse GraphQL documents, guess cache keys, or infer mutation effects.

SvelteKit

Install Svelte and describe each generated authorization surface once:

npm install svelte

// distributed.config.js
const serviceManifestArgs = [
  'client-manifest',
  '--manifest-path',
  '../service/Cargo.toml',
  '--package',
  'service'
];

export const distributedClients = [
  {
    module: '$distributed',
    manifest: { args: serviceManifestArgs },
    surface: 'e2e-ui',
    documents: ['src/routes/(app)/**/*.graphql'],
    out: 'src/lib/generated/distributed'
  },
  {
    module: '$distributed/admin',
    manifest: {
      args: [
        ...serviceManifestArgs,
        '--entrypoint',
        'service::distributed_admin_client_surface'
      ]
    },
    surface: 'e2e-ui-admin',
    documents: ['src/routes/admin/**/*.graphql'],
    out: 'src/lib/generated/distributed-admin'
  }
];

export const distributedViteOptions = {
  clients: distributedClients
};

The common and elevated document sets must not overlap. The route group above 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 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:

// vite.config.ts
import { sveltekit } from '@sveltejs/kit/vite';
import {
  distributedGraphqlProxy,
  distributedSvelteKit
} from '@hops-ops/distributed/sveltekit/vite';
import { defineConfig } from 'vite';
import { distributedViteOptions } from './distributed.config.js';

export default defineConfig({
  plugins: [distributedSvelteKit(distributedViteOptions), sveltekit()],
  server: {
    proxy: distributedGraphqlProxy('http://127.0.0.1:8791')
  }
});

Give SvelteKit’s language tools the identical aliases:

// svelte.config.js
import {
  distributedSvelteKitAliases
} from '@hops-ops/distributed/sveltekit/vite';
import {
  distributedClients,
  distributedViteOptions
} from './distributed.config.js';

export default {
  kit: {
    alias: distributedSvelteKitAliases({
      cwd: distributedViteOptions.cwd,
      clients: distributedClients
    })
  }
};

One-shot scripts use the same configuration and transaction:

import {
  checkDistributedSvelteKit,
  generateDistributedSvelteKit
} from '@hops-ops/distributed/sveltekit/vite';
import { distributedViteOptions } from './distributed.config.js';

await generateDistributedSvelteKit(distributedViteOptions);
await checkDistributedSvelteKit(distributedViteOptions); // never writes

Create one request-local server replica in the root layout:

// src/routes/+layout.server.ts
import {
  createDistributedSvelteKitServer
} from '@hops-ops/distributed/sveltekit';
import {
  DISTRIBUTED_ROUTE_OPERATIONS
} from '$distributed';

const distributed = createDistributedSvelteKitServer({
  routes: DISTRIBUTED_ROUTE_OPERATIONS,
  getSession: ({ locals }) => locals.auth(),
  getRole: (session) => roleFromSession(session)
});

export const load = distributed.load;

The browser layout installs one client in Svelte context for the current authorization lifecycle. The generated module retains no client singleton:

// src/routes/+layout.svelte
import { browser } from '$app/environment';
import {
  createPageDataSessionSource
} from '@hops-ops/distributed/sveltekit';
import { provideDistributed } from '$distributed';

let { data, children } = $props();
const pageData = createPageDataSessionSource(data);

const client = provideDistributed({
  browser,
  session: pageData.session,
  ...(data.distributed !== undefined &&
  data.distributedAuthority !== undefined
    ? {
        hydration: data.distributed,
        authority: data.distributedAuthority
      }
    : {})
});

$effect(() => pageData.set(data));

Route components import only their generated surface. Static operation wrappers resolve the nearest tree-local client when used:

// src/routes/todos/+page.svelte
import { Todos, useCommands } from '$distributed';

const todos = Todos.use(); // generated @live attaches automatically
const commands = useCommands();

await commands.todo.create({ title: 'Ship it' });
// $todos.data, $todos.status, $todos.pending

When the Rust command declaration supplies a UUIDv7, ULID, or literal input default, generation makes that field optional and the runtime fills it exactly once. Components do not generate IDs or maintain optimistic/cache recipes.

@load results are normalized on the server, dehydrated, and restored in the browser without a duplicate first request. Hydration cannot authorize itself: 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.

Framework-neutral replica

Other frameworks can bind the same core directly:

import {
  createDistributedReplica,
  createReplicaGraphqlTransport
} from '@hops-ops/distributed/replica';
import { Operation_Todos } from './generated/distributed/index.js';

const transport = createReplicaGraphqlTransport({
  getUrl: () => '/graphql',
  getAuth: () => ({ accessToken: session.accessToken })
});
const replica = createDistributedReplica({ transport });
const todos = replica.watch(Operation_Todos, {}, { live: true });

const unsubscribe = todos.subscribe((snapshot) => {
  render(snapshot.data, snapshot.status);
});

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 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 operation result from that shared state, so a detail read, list read, live frame, or optimistic command can update every affected view in one transaction.

Commands and optimistic UI

Generated createCommands binds the service-owned command artifacts to the 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 (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. 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, 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:

const receipt = await commands.todo.create(
  { title: 'Ship it' },
  { signal: AbortSignal.timeout(5_000) }
);
await receipt.projected;

Before acceptance the signal cancels dispatch. After finite acceptance it rejects only that caller's receipt.projected wait; the optimistic layer and internal causal tracking remain active, and receipt.status() stays available.

React

Install React and use the optional adapter over an application-owned replica:

import {
  DistributedProvider,
  useDistributedQuery
} from '@hops-ops/distributed/react';
import { Operation_Todos } from './generated/distributed/index.js';

function TodosView() {
  const todos = useDistributedQuery(Operation_Todos, {}, { live: true });
  return todos.complete
    ? todos.data.todos.map((todo) => <div key={todo.todo_id}>{todo.title}</div>)
    : null;
}

root.render(
  <DistributedProvider replica={replica}>
    <TodosView />
  </DistributedProvider>
);

The adapter is only a useSyncExternalStore bridge. It does not add another cache, transport, auth lifecycle, or command path. For SSR, create one replica per request and hydrate only under the same authoritative scope.

Persistence and diagnostics

The default replica is memory-only. Optional IndexedDB persistence is explicit, confirmed-state-only, and governed by generated/application model policy. Optimistic layers, command inputs, credentials, cache authority, and live connections are never persisted as replica data.

Diagnostics are also opt-in:

import {
  createReplicaDiagnostics
} from '@hops-ops/distributed/diagnostics';

const diagnostics = createReplicaDiagnostics();
const replica = createDistributedReplica({ transport, diagnostics });
const commands = createCommands(replica, transport, { diagnostics });

Snapshots explain operation artifacts, normalized records, index coverage, optimistic layers, causal receipts, revalidation, response fences, and garbage collection. Defaults pseudonymize identities and omit values, arguments, credentials, trusted presets, raw command inputs, and cache scope. Revealing additional development detail requires an in-process capability plus an explicit redactor.

Protocol and security boundaries

Every accepted artifact and response is protocol v1 and carries an exact schema/client-surface binding. Every response is also bound to a server-issued cache scope, operation ID, and trusted-preset inventory; any supplied record clocks or index vector are bound to that same scope. Missing, malformed, stale-schema, or cross-surface evidence fails closed. An exact authorized payload without a safely comparable index vector may render, but it cannot advance index clocks/vectors, observations, live resume, or optimistic confirmation. Independently valid record clocks remain usable.

OIDC credentials authorize transport requests; decoded client claims never create cache authority. GraphQL remains the API and command proxy layer, while the service's SQL read models remain authoritative.

Normative architecture and API decisions live in the Distributed GitKB, including specs/query-layer/v1/cache-engine. They are intentionally not duplicated as decision documents in this package.

Public entry points

• @hops-ops/distributed — GraphQL HTTP/WebSocket, auth, and protocol primitives.
• @hops-ops/distributed/replica — replica, GraphQL transport, generated command runtime, query-plan helpers, and optional persistence.
• @hops-ops/distributed/diagnostics — redacted support snapshots and artifact inspection.
• @hops-ops/distributed/sveltekit — Svelte stores, SSR route loading, hydration, auth lifecycle, and tree-local generated bindings.
• @hops-ops/distributed/sveltekit/vite — Node-only one-shot/check/watch generation, virtual module aliases, and GraphQL HTTP/WebSocket proxy helpers.
• @hops-ops/distributed/react — provider and query hook over the same replica.

All other subpaths are private and blocked by the package export map.

Pre-release clean break

The earlier pilot API and persistence format are intentionally unsupported. There is no QueryCache, CacheTarget, ListMergeSpec, target/at/by addressing, manual cache-policy map, resource wrapper, document store, legacy command pipeline, or package-owned codegen executable.

To move an existing pilot application:

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;
4. discard prior browser cache and SSR payloads rather than migrating them.

Only protocol-v1 generated artifacts and server envelopes are accepted.

Verification and release

npm ci
npm run quality
npm run release:dry-run

quality typechecks generated consumers, runs behavior and adapter suites, packs and installs the real tarball into clean consumers, verifies bundle boundaries, and runs publint. release:dry-run exercises npm's publish payload without publishing.

Version tags (vX.Y.Z) publish with npm provenance through GitHub Actions trusted publishing. The package currently uses UNLICENSED because the repository has no top-level license file; changing that is an explicit maintainer decision.