@gleanql/client 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,954 @@
+import { ArgMap, SchemaModel, SelectionSet } from "@gleanql/core";
+
+//#region src/adapter.d.ts
+interface GraphOperation<_TData = unknown, _TVariables = unknown> {
+  readonly name: string;
+  readonly kind: "query" | "mutation" | "subscription";
+  readonly document: string;
+  /** SHA-256 hex of `document` — the persisted-operation ID (present on compiled operations). */
+  readonly hash?: string;
+}
+interface GraphRequestContext {
+  readonly [key: string]: unknown;
+}
+interface GraphResult<TData> {
+  readonly data?: TData;
+  readonly errors?: ReadonlyArray<{
+    message: string;
+  }>;
+}
+interface GraphClientAdapter {
+  execute<TData, TVariables>(operation: GraphOperation<TData, TVariables>, variables: TVariables, context: GraphRequestContext): Promise<GraphResult<TData>>;
+  subscribe?<TData, TVariables>(operation: GraphOperation<TData, TVariables>, variables: TVariables, context: GraphRequestContext): AsyncIterable<GraphResult<TData>>;
+}
+interface FetchAdapterOptions {
+  readonly endpoint: string;
+  readonly fetch?: typeof fetch;
+  /** Build request headers from context (auth, shop domain, locale, ...). */
+  readonly headers?: (context: GraphRequestContext) => Record<string, string>;
+  /**
+   * Endpoint for subscriptions, consumed as a Server-Sent Events stream via the
+   * browser's `EventSource`. Defaults to `${endpoint}/stream`. A production app
+   * that prefers WebSockets can drop a `graphql-ws` adapter into the same
+   * `subscribe` seam instead.
+   */
+  readonly subscriptionEndpoint?: string;
+  /**
+   * Send operations BY HASH instead of by document (`extensions.persistedQuery.
+   * sha256Hash` — the Apollo APQ wire shape, which `createPersistedResolver`
+   * understands server-side). The document never rides the request, so the
+   * server can enforce a build-produced allowlist. If the server answers
+   * `PersistedQueryNotFound` (e.g. an APQ cache that hasn't seen the hash), the
+   * request retries ONCE with the full document so the server can register it.
+   * Operations without a `hash` fall back to sending the document.
+   */
+  readonly persisted?: boolean;
+  /** Observability hook: a persisted hash was unknown to the server and the document was re-sent (APQ register). */
+  readonly onPersistedRetry?: (operationName: string) => void;
+}
+/** Minimal fetch transport. Context is used only to build headers; it is never serialized into the body. */
+declare function createFetchAdapter(options: FetchAdapterOptions): GraphClientAdapter;
+//#endregion
+//#region src/cache.d.ts
+/**
+ * Graph cache with two storage identities (per the brief):
+ *  - Normalized entity storage, keyed by `__typename + id`.
+ *  - Operation/path storage, keyed by `root + args + path`, for objects with
+ *    no `id`.
+ * Two query paths returning the same `__typename + id` resolve to one record,
+ * so an update through any path is visible through all of them.
+ */
+/** A reference to a cached record: an identified entity or a path-anchored object. */
+interface GraphRef {
+  readonly __typename?: string;
+  readonly id?: string | number;
+  /** Path identity, e.g. `Query.product(handle).featuredImage`. */
+  readonly path?: string;
+}
+type FieldValue = unknown;
+type FieldLookup = {
+  readonly status: "ready";
+  readonly value: FieldValue;
+} | {
+  readonly status: "missing";
+};
+declare class GraphCache {
+  private readonly maxRecords?;
+  private readonly records;
+  /**
+   * Optional LRU cap. The client cache accumulates entities across navigations; a
+   * long session would otherwise grow without bound. When set, the least-recently
+   * used records are evicted past the cap. Unset (default) = unbounded, so the
+   * server's per-request cache and existing callers are unchanged.
+   */
+  constructor(maxRecords?: number | undefined);
+  /**
+   * Reactivity substrate. Every write bumps `version` and notifies listeners, so
+   * UI can re-render after a mutation, refetch, or peer-tab/subscription update.
+   * `version` + `subscribe` are exactly the `useSyncExternalStore` contract.
+   */
+  private _version;
+  private readonly listeners;
+  /**
+   * Version counters for fine-grained reactivity, at two granularities. A component
+   * tracks the keys it read during render; its `useSyncExternalStore` snapshot is a
+   * digest of those keys' versions, so a global notify only re-renders the components
+   * whose keys actually changed (valtio's approach — no per-key subscription fan-out).
+   *
+   *  - `recordVersions` bumps on ANY write to a record (record-level trackers, e.g.
+   *    `usePaginated` watching a connection).
+   *  - `fieldVersions` bumps only the written field (field-level trackers, e.g.
+   *    `useGlean`, so reading `product.title` ignores a write to `product.views`).
+   *
+   * The global `version`/`subscribe` stay the notify channel; both granularities are
+   * resolved through {@link trackedVersion}.
+   */
+  private readonly recordVersions;
+  private readonly fieldVersions;
+  /** Current version of a record (0 if never written). */
+  recordVersion(key: string): number;
+  /** Current version of a single field on a record (0 if never written). */
+  fieldVersion(recordKey: string, fieldKey: string): number;
+  /** The opaque tracking key a field read records; resolve it with {@link trackedVersion}. */
+  fieldTrackingKey(recordKey: string, fieldKey: string): string;
+  /** Version of a tracked key: a bare record key, or `record\0field` for a single field. */
+  trackedVersion(trackingKey: string): number;
+  /** Bump a record's version + (optionally) one of its fields' versions. */
+  private bumpRecord;
+  private bumpField;
+  get version(): number;
+  subscribe(listener: () => void): () => void;
+  private bump;
+  /** Public notify: bump the version + run listeners (e.g. after `absorbRecords`). */
+  notify(): void;
+  /** Stable storage key for a ref: entity identity wins over path identity. */
+  recordKey(ref: GraphRef): string;
+  /**
+   * Reference-counted retention (Relay-style). A mounted reader retains the
+   * records it displays; retained records are never LRU-evicted and survive
+   * {@link gc}. The tracking hooks do this automatically — each component
+   * retains what it read while mounted — so `gc()` is safe to call any time
+   * (e.g. on navigation): it can only drop records nothing on screen reads.
+   */
+  private readonly retainCounts;
+  /** Pin a record. Returns the matching release; calling it twice is a no-op. */
+  retain(key: string): () => void;
+  isRetained(key: string): boolean;
+  /** The record key a tracked key belongs to (strips the `\0field` part, if any). */
+  trackedRecordKey(trackingKey: string): string;
+  /**
+   * Generation clock for staleness-aware GC. The glue advances it on each page
+   * navigation; every read/write/retain stamps the record with the current
+   * epoch. "Unretained" alone is NOT a reason to drop data (a back-navigation
+   * should hit a warm cache) — `gc({ keepEpochs })` drops only records that are
+   * unretained AND haven't been touched for that many generations.
+   */
+  private epoch;
+  private readonly lastActive;
+  /** Advance the generation clock (call on navigation). Returns the new epoch. */
+  advanceEpoch(): number;
+  private stamp;
+  /**
+   * Drop unretained records; returns how many were dropped. Version counters
+   * survive, so if a dropped record is refetched its trackers still see
+   * monotonic versions.
+   *
+   * - `gc()` — drop EVERY unretained record (a full reset, e.g. logout).
+   * - `gc({ keepEpochs: N })` — drop only records also untouched for ≥ N
+   *   generations (see {@link advanceEpoch}); recently-used data stays warm
+   *   for back-navigation even though nothing on screen retains it.
+   */
+  gc(options?: {
+    keepEpochs?: number;
+  }): number;
+  hasRecord(ref: GraphRef): boolean;
+  /** Mark a key most-recently-used (Map keeps insertion order; re-insert to bump). No-op when unbounded. */
+  private touch;
+  /**
+   * Evict least-recently-used records past the cap (Map's first key is the
+   * oldest), skipping retained records — a record someone on screen reads is
+   * never the eviction victim, even if it's the coldest. If retained records
+   * alone exceed the cap, the cache temporarily runs over it.
+   */
+  private evict;
+  /** Get-or-create the record map for a storage key. */
+  private ensureRecord;
+  getField(ref: GraphRef, fieldKey: string): FieldLookup;
+  setField(ref: GraphRef, fieldKey: string, value: FieldValue): void;
+  /** Merge a flat record of fields into the entity/path record. */
+  merge(ref: GraphRef, fields: Readonly<Record<string, FieldValue>>): void;
+  /** Drop a whole record (mutation invalidation). */
+  invalidate(ref: GraphRef): void;
+  /** Drop a single field so the next read re-fetches it. */
+  invalidateField(ref: GraphRef, fieldKey: string): void;
+  /**
+   * Fold a serialized snapshot into THIS cache, field-by-field, WITHOUT replacing
+   * existing records and WITHOUT notifying. Returns whether anything was
+   * added/changed. The caller decides when to `notify()` — so a render-phase merge
+   * can write records (visible to synchronous reads) yet defer the subscriber bump
+   * to a commit-phase effect. Idempotent: re-absorbing the same snapshot is a no-op.
+   */
+  absorbRecords(snapshot: Record<string, Record<string, FieldValue>>): boolean;
+  /** Serialize the whole cache (for hydration). */
+  snapshot(): Record<string, Record<string, FieldValue>>;
+  static fromSnapshot(snapshot: Record<string, Record<string, FieldValue>>, maxRecords?: number): GraphCache;
+}
+//#endregion
+//#region src/normalize.d.ts
+/**
+ * Normalize a GraphQL JSON result into the cache.
+ *
+ * Every object selection includes `__typename` (and `id` when the type has one),
+ * so the result alone carries enough to choose an identity:
+ *  - `__typename + id` -> normalized entity record, deduped across queries.
+ *  - id-less object     -> embedded under its *owning entity* at the field path
+ *    since that entity (`Product:123.priceRange`), NOT the query path. So the same
+ *    nested object reached through two different queries resolves to one record —
+ *    update it once and every reader sees it, and a second query needn't refetch.
+ *  - id-less with no entity ancestor (root objects) -> anchored at the operation
+ *    path (`Query.search(q)`), which is the only correct identity for them.
+ * Scalars store inline; object fields store a `GraphRef`; lists store an array.
+ *
+ * `anchor` is the nearest owning entity's record key (or the root path); `field`
+ * is the path from that anchor.
+ */
+/**
+ * Resolve an object's identity value from its `__typename`, or undefined when
+ * the object is id-less (and must be embedded). Defaults to the `id` field;
+ * supply a schema-derived resolver to key types by another field (`sku`, `slug`)
+ * or a composite.
+ */
+type KeyOf = (typename: string, obj: Record<string, unknown>) => string | undefined;
+declare function normalizeValue(cache: GraphCache, value: unknown, anchor: string, field: string, keyOf?: KeyOf, seen?: WeakSet<object>): FieldValue;
+/** Seed an operation result; returns each root field's ref for reading. */
+declare function seedResult(cache: GraphCache, data: Readonly<Record<string, unknown>>, options?: {
+  rootPath?: string;
+  keyOf?: KeyOf;
+}): Record<string, FieldValue>;
+//#endregion
+//#region src/runtime.d.ts
+/**
+ * Suspense-aware graph runtime.
+ *
+ * A field read is synchronous on a cache hit. On a miss it enqueues the missing
+ * (ref, field), creates exactly one cached promise for it, and throws that
+ * promise (the Suspense contract). Multiple misses in the same tick batch into
+ * a single `fetchMissing` call. Re-reading a pending field throws the same
+ * promise — no duplicate request, stable across React render retries.
+ */
+interface MissingFieldRead {
+  readonly ref: GraphRef;
+  readonly fieldKey: string;
+}
+interface MissingFieldResult {
+  readonly ref: GraphRef;
+  readonly fieldKey: string;
+  readonly value: FieldValue;
+}
+type MissingFieldMode = "allow" | "warn" | "error";
+interface GraphRuntimeOptions {
+  /** Batched fetcher for fields not present in the seeded operation. */
+  readonly fetchMissing: (misses: readonly MissingFieldRead[]) => Promise<readonly MissingFieldResult[]>;
+  readonly cache?: GraphCache;
+  /** How to identify entities during normalization (defaults to the `id` field). */
+  readonly keyOf?: KeyOf;
+  /** Behavior when a field absent from the compiled operation is read. */
+  readonly unexpectedMissingField?: MissingFieldMode;
+  /** dev-only: warn with component/field context. */
+  readonly onWarn?: (message: string) => void;
+  /** Microtask scheduler (overridable in tests). */
+  readonly schedule?: (cb: () => void) => void;
+  /** Optional LRU cap for the cache (least-recently-used records evicted past it). */
+  readonly maxCacheRecords?: number;
+}
+declare class GraphRuntime {
+  private readonly options;
+  readonly cache: GraphCache;
+  private readonly pending;
+  private queue;
+  private flushScheduled;
+  constructor(options: GraphRuntimeOptions);
+  /** Synchronous on hit; throws a (cached) promise on miss. */
+  readField(ref: GraphRef, fieldKey: string, debug?: {
+    component?: string;
+  }): FieldValue;
+  /** Seed a record's fields (e.g. from the compiled operation result). */
+  seed(ref: GraphRef, fields: Readonly<Record<string, FieldValue>>): void;
+  /** Normalize a full operation result into the cache; returns root refs. */
+  seedResult(data: Readonly<Record<string, unknown>>, options?: {
+    rootPath?: string;
+  }): Record<string, FieldValue>;
+  /**
+   * Low-level pagination primitive: append a freshly-fetched page onto a cached
+   * connection. Normalizes the page's `nodes` and concats them after the existing
+   * ones, and (if present) replaces `pageInfo`. Every reader of the connection
+   * re-renders with the longer `nodes` array. This makes no assumptions about HOW
+   * the page was fetched or which cursor convention the schema uses — the app fetches
+   * the next page however it likes (the connection's ref is available via
+   * `selectionOf(value)`), then hands the page object here to merge it in.
+   */
+  appendConnection(connectionRef: GraphRef, page: Record<string, unknown>, mergeRefs?: (existing: readonly FieldValue[], incoming: readonly FieldValue[]) => readonly FieldValue[]): void;
+  /** Invalidate a record (e.g. after a mutation) and clear its pending reads. */
+  invalidate(ref: GraphRef): void;
+  /** Serialize the cache for hydration across the server/client boundary. */
+  snapshot(): Record<string, Record<string, FieldValue>>;
+  /**
+   * Fold a snapshot into the live cache (write only, no notify); returns whether
+   * anything changed. Use for a per-navigation merge where the notify is deferred
+   * to a commit-phase effect (see `serialize.ts#absorbHydrationPayload`).
+   */
+  absorbRecords(snapshot: Record<string, Record<string, FieldValue>>): boolean;
+  /** Notify subscribers after one or more `absorbRecords` calls. */
+  notify(): void;
+  /** Convenience: absorb a snapshot and notify if it changed (non-React callers). */
+  absorb(snapshot: Record<string, Record<string, FieldValue>>): boolean;
+  static hydrate(snapshot: Record<string, Record<string, FieldValue>>, options: Omit<GraphRuntimeOptions, "cache">): GraphRuntime;
+  private reportMiss;
+  private scheduleFlush;
+  private flush;
+  /** Stable key for a pending (ref, field) read — also the `invalidate` prefix base. */
+  private pendingKey;
+  private makeDeferred;
+}
+//#endregion
+//#region src/route.d.ts
+/**
+ * Framework-integration seam. A compiled operation (the artifact the compiler
+ * emits) plus a client adapter and a request context is enough to drive a
+ * route: compute variables, execute, seed the cache. A framework adapter
+ * (RWSDK first) answers "which operation for this entrypoint?" and "how do I
+ * build the request context?".
+ */
+interface CompiledOperation<RouteContext = unknown, TVariables = Record<string, unknown>> {
+  readonly name: string;
+  readonly kind: "query" | "mutation" | "subscription";
+  readonly document: string;
+  readonly hash?: string;
+  readonly variables: (ctx: RouteContext) => TVariables;
+  readonly readMap?: Record<string, readonly string[]>;
+  /** Merged selection tree; enables cache-first resolution when present. */
+  readonly selection?: SelectionSet;
+}
+interface RunRouteOptions {
+  /**
+   * Cache-first: if the cache already satisfies the operation's full selection,
+   * skip the network. Defaults to true; pass false to always fetch (e.g. an
+   * explicit refresh that must hit the server).
+   */
+  readonly cacheFirst?: boolean;
+}
+interface RunRouteResult<TVariables> {
+  readonly variables: TVariables;
+  readonly roots: Record<string, FieldValue>;
+  readonly errors?: ReadonlyArray<{
+    message: string;
+  }>;
+}
+/** Execute a compiled operation and seed the runtime cache (steps 2–5 of the route flow). */
+declare function runRoute<RouteContext, TVariables extends Record<string, unknown>>(args: {
+  operation: CompiledOperation<RouteContext, TVariables>;
+  routeContext: RouteContext;
+  adapter: GraphClientAdapter;
+  context: GraphRequestContext;
+  runtime: GraphRuntime;
+  options?: RunRouteOptions;
+}): Promise<RunRouteResult<TVariables>>;
+/**
+ * Re-run an operation against the network, bypassing cache-first, and re-seed.
+ * The re-seed writes through the cache, bumping its version and notifying
+ * subscribers — so a `useSyncExternalStore` (`cache.subscribe`) re-renders the
+ * UI with the fresh data. Use for an explicit "Refresh" / post-mutation refetch.
+ */
+declare function refetch<RouteContext, TVariables extends Record<string, unknown>>(args: {
+  operation: CompiledOperation<RouteContext, TVariables>;
+  routeContext: RouteContext;
+  adapter: GraphClientAdapter;
+  context: GraphRequestContext;
+  runtime: GraphRuntime;
+}): Promise<RunRouteResult<TVariables>>;
+//#endregion
+//#region src/cache-resolve.d.ts
+/** Record each root field's resolved ref so a later run finds the entity without a fetch. */
+declare function persistRootLinks(cache: GraphCache, selection: SelectionSet, vars: Record<string, unknown>, roots: Record<string, FieldValue>, rootPath?: string): void;
+interface CacheResolution {
+  readonly covered: boolean;
+  readonly roots: Record<string, FieldValue>;
+}
+/**
+ * Try to satisfy an operation entirely from cache. `covered` is true only when
+ * every root link exists and every selected field beneath it is present.
+ */
+declare function resolveFromCache(cache: GraphCache, selection: SelectionSet, vars: Record<string, unknown>, rootPath?: string): CacheResolution;
+//#endregion
+//#region src/proxy.d.ts
+/**
+ * Runtime graph proxies.
+ *
+ * The compiler statically infers what fields a route needs; this layer is what
+ * makes ordinary reads (`product.title`, `product.featuredImage?.url`,
+ * `collection.products({ first: 12 }).nodes`) actually *execute* at runtime.
+ *
+ * A graph value is a Proxy over a cache `GraphRef`. Property access routes
+ * through the Suspense-aware runtime:
+ *  - scalar field  -> `runtime.readField(ref, key)` (sync hit, or throws a promise)
+ *  - object field  -> the stored `GraphRef`, re-wrapped as a child proxy
+ *  - list field    -> an array of child proxies/scalars
+ *  - callable field -> a function `(args) => value` (field arguments)
+ *
+ * The proxy is intentionally transparent: parent components pass it as a normal
+ * prop, child components read fields off it, and nothing in userland sees a ref,
+ * a selection object, or a promise (the promise is thrown to Suspense).
+ */
+/** Escape-hatch / brand keys exposed on every graph proxy. */
+declare const GRAPH_REF: unique symbol;
+declare const GRAPH_TYPE: unique symbol;
+declare const GRAPH_TRAIL: unique symbol;
+/** Install (or clear) the active read tracker. Returns the previous one. */
+declare function setReadTracker(tracker: Set<string> | null): Set<string> | null;
+/** One object-field hop from a Query root: the field name + the args it was called with. */
+interface PathStep {
+  readonly name: string;
+  readonly args?: Record<string, unknown>;
+}
+/** The hidden selection token (brief: `product.selection`). */
+interface GraphSelection {
+  readonly ref: GraphRef;
+  readonly type: string;
+}
+/** A value is a `GraphRef` if it carries entity identity or a path. */
+declare function isGraphRef(value: unknown): value is GraphRef;
+/** Plain runtime args (`{ first: 12 }`) -> IR `ArgMap`, reusing core's canonicalization. */
+declare function toArgMap(args: Record<string, unknown> | undefined): ArgMap;
+/**
+ * Candidate response keys for a (possibly callable) field, most-specific first.
+ * A callable field that coexisted with a differently-argued sibling was aliased
+ * by the merger (`url_transformMaxWidth300`); a lone callable field keeps its
+ * plain name. The proxy tries the alias key first, then the plain name, which
+ * is correct for both shapes without the proxy having to know about conflicts.
+ */
+declare function responseKeyCandidates(name: string, argMap: ArgMap): readonly string[];
+interface GraphBinding {
+  readonly schema: SchemaModel;
+  /** Resolve the active runtime lazily (per request on the server). */
+  readonly getRuntime: () => GraphRuntime;
+  /**
+   * Per-binding read tracker. When a `useGlean` render binds the graph with its own
+   * `affected` set, every proxy created from this binding records reads into THAT set
+   * — not the ambient global — so concurrent/interleaved renders can't misattribute.
+   * Absent (server / isomorphic accessor) → reads fall back to the ambient tracker.
+   */
+  readonly tracker?: Set<string>;
+}
+declare function createGraphProxy(binding: GraphBinding, ref: GraphRef, type: string, trail?: readonly PathStep[]): unknown;
+/** Read the hidden selection token off any graph proxy. */
+declare function selectionOf(value: unknown): GraphSelection | undefined;
+/** Read the root→value path off any graph proxy (for `usePaginated`/`fetchMore`). */
+declare function trailOf(value: unknown): readonly PathStep[] | undefined;
+/**
+ * The runtime `graph` object: one callable per Query root field, each returning
+ * a graph proxy. Root values resolve to the ref the operation seeded (via the
+ * `roots` map) so reads hit the warm cache; an unseeded root falls back to a
+ * path-identity ref and suspends.
+ */
+interface BoundGraph {
+  readonly [rootField: string]: (args?: Record<string, unknown>) => unknown;
+}
+interface BindGraphOptions {
+  readonly schema: SchemaModel;
+  readonly getRuntime: () => GraphRuntime;
+  /**
+   * Root field -> seeded ref, from `runRoute`/`seedResult`. A function form is
+   * resolved per call, so the bound graph can follow page-current roots that
+   * change across client navigations (the RSC hydrator updates them per nav).
+   */
+  readonly roots?: Record<string, FieldValue> | (() => Record<string, FieldValue> | undefined);
+  /**
+   * A read tracker scoping this binding's reads to one render (see `GraphBinding`).
+   * `useGlean` passes its render's `affected` set so attribution is fiber-local;
+   * the server/isomorphic accessor omits it.
+   */
+  readonly tracker?: Set<string>;
+}
+declare function bindGraph(options: BindGraphOptions): BoundGraph;
+//#endregion
+//#region src/scope.d.ts
+/**
+ * Request-scoped runtime resolution.
+ *
+ * A module-level `import { graph } from "~/graph"` must resolve to *the runtime
+ * for the current request* on the server (concurrent requests must not share a
+ * cache) and to a single client runtime in the browser. `GraphScope` is the tiny
+ * seam that makes that possible without threading a runtime through every prop.
+ *
+ * On the server, a framework adapter (RWSDK) wraps request handling in
+ * `scope.run(active, fn)`. If the host exposes AsyncLocalStorage, concurrent
+ * requests are isolated automatically; otherwise the adapter should resolve the
+ * runtime from its own per-request context (`getGraph(requestInfo)`), which never
+ * relies on a shared mutable global. On the client, `scope.set(active)` installs
+ * the singleton after hydration.
+ */
+interface ActiveGraph {
+  readonly runtime: GraphRuntime;
+  readonly graph: BoundGraph;
+}
+interface AsyncLocalStorageLike<T> {
+  getStore(): T | undefined;
+  run<R>(store: T, fn: () => R): R;
+}
+declare class GraphScope {
+  private singleton;
+  private als;
+  constructor(als?: AsyncLocalStorageLike<ActiveGraph>);
+  /**
+   * Attach an AsyncLocalStorage after construction — for isomorphic frameworks
+   * (e.g. React Router) where the *same* `graph` accessor module loads in both
+   * bundles: construct `new GraphScope()` in a universal, client-safe module (no
+   * `node:async_hooks`), then a server-only module calls `attachAls(...)` to
+   * upgrade it to per-request ALS isolation. `run`/`current` read `als`
+   * dynamically, so the upgrade takes effect immediately; the client keeps using
+   * the singleton set by `set()`.
+   */
+  attachAls(als: AsyncLocalStorageLike<ActiveGraph>): void;
+  /** The active graph, or throw a clear error if read outside any scope. */
+  current(): ActiveGraph;
+  /** Run `fn` with `active` as the request-scoped runtime (server). */
+  run<R>(active: ActiveGraph, fn: () => R): R;
+  /** Install the active graph as a singleton (client, post-hydration). */
+  set(active: ActiveGraph): void;
+}
+/**
+ * Pair a {@link GraphScope} with a zero-arg resolver — the framework-agnostic
+ * binding for the generated accessor. An app exports `activeGraph` and points
+ * `@gleanql/vite`'s `requestScope: { import: "activeGraph", from: "..." }` at it,
+ * then wraps server rendering in `scope.run(active, fn)` (or
+ * `integration.runInScope`). Pass an `AsyncLocalStorage` to isolate concurrent
+ * server requests; omit it for the client singleton.
+ *
+ * ```ts
+ * import { AsyncLocalStorage } from "node:async_hooks";
+ * export const { scope, activeGraph } = bindScope(new AsyncLocalStorage());
+ * ```
+ */
+declare function bindScope(als?: AsyncLocalStorageLike<ActiveGraph>): {
+  scope: GraphScope;
+  activeGraph: () => ActiveGraph;
+};
+//#endregion
+//#region src/mutation.d.ts
+/**
+ * Mutations + invalidation.
+ *
+ * Reads were the first milestone; this is the write side. A mutation is run
+ * through the same client adapter as a query, and its result is normalized into
+ * the cache — so any entity it returns (`__typename + id`) updates *in place* and
+ * every read of that entity, through any path, reflects the change for free.
+ * That is the payoff of the normalized cache the brief asked for.
+ *
+ * On top of that the engine adds: GraphQL-style `userErrors`, optimistic writes
+ * with automatic rollback, and invalidation of affected graph values/roots.
+ */
+/** A GraphQL `userErrors` entry (Shopify-style mutation payloads). */
+interface UserError {
+  readonly field?: readonly string[];
+  readonly message: string;
+  readonly code?: string;
+}
+interface MutationResult<TData = unknown> {
+  readonly data?: TData;
+  /** Logical, per-mutation errors returned in the payload (not transport errors). */
+  readonly userErrors: readonly UserError[];
+  /** Transport/GraphQL execution errors. */
+  readonly errors?: ReadonlyArray<{
+    message: string;
+  }>;
+  /** True when there were no transport errors and no userErrors. */
+  readonly ok: boolean;
+}
+/**
+ * A reversible batch of cache writes. Optimistic updates record the prior value
+ * of every field they touch so the whole batch can be rolled back if the
+ * mutation fails (transport error or `userErrors`).
+ */
+declare class MutationTransaction {
+  private readonly cache;
+  private readonly undo;
+  constructor(cache: GraphCache);
+  /** Optimistically write a field, remembering how to undo it. */
+  set(ref: GraphRef, fieldKey: string, value: FieldValue): void;
+  /** Roll back every write in reverse order. */
+  rollback(): void;
+}
+interface RunMutationOptions<TData = unknown> {
+  readonly operation: CompiledOperation<unknown, Record<string, unknown>> | {
+    readonly name: string;
+    readonly kind: "mutation";
+    readonly document: string;
+  };
+  readonly variables: Record<string, unknown>;
+  readonly adapter: GraphClientAdapter;
+  readonly context: GraphRequestContext;
+  readonly runtime: GraphRuntime;
+  /** Optimistically patch the cache before the request; rolled back on failure. */
+  readonly optimistic?: (tx: MutationTransaction) => void;
+  /** Apply the server result (e.g. prepend to a connection) after normalization. */
+  readonly update?: (data: TData, tx: MutationTransaction) => void;
+  /** Graph values / refs to invalidate on success (refetch on next read). */
+  readonly invalidate?: (data: TData) => ReadonlyArray<GraphRef | unknown>;
+}
+/**
+ * Execute a mutation, normalize its result into the cache, surface userErrors,
+ * and apply optimistic/invalidation policy. The returned promise never rejects
+ * for logical failures — inspect `ok`/`userErrors`/`errors`.
+ */
+declare function runMutation<TData = Record<string, unknown>>(options: RunMutationOptions<TData>): Promise<MutationResult<TData>>;
+/** Invalidate a record by graph value (proxy) or raw ref — next read re-fetches. */
+declare function invalidateValue(runtime: GraphRuntime, value: GraphRef | unknown): void;
+/** One rule for stringifying unknown errors, shared across hooks and transports. */
+declare function errorMessage(error: unknown): string;
+//#endregion
+//#region src/mutator.d.ts
+/** The minimal operation shape the mutator needs (any CompiledOperation satisfies it). */
+interface MutationOperationLike {
+  readonly name: string;
+  readonly kind: "query" | "mutation" | "subscription";
+  readonly document: string;
+}
+/**
+ * The `graph.mutate.*` namespace.
+ *
+ * Mutations are compiled operations like queries; this binds one callable per
+ * compiled mutation operation so app code writes:
+ *
+ *   await graph.mutate.cartLinesAdd({ cartId, lines }, {
+ *     optimistic: (tx) => tx.set(cartRef, "totalQuantity", n + 1),
+ *     invalidate: (data) => [cartRef],
+ *   });
+ *
+ * Each call runs the mutation, folds the result into the cache, and applies the
+ * optimistic/invalidation policy (see runMutation).
+ */
+type MutateFn = (variables: Record<string, unknown>, options?: Omit<Parameters<typeof runMutation>[0], "operation" | "variables" | "adapter" | "context" | "runtime">) => Promise<MutationResult>;
+type BoundMutations = Record<string, MutateFn>;
+interface CreateMutatorOptions {
+  /** Compiled operations; only `kind: "mutation"` entries are bound. */
+  readonly operations: Record<string, MutationOperationLike>;
+  readonly adapter: GraphClientAdapter;
+  readonly runtime: GraphRuntime;
+  /** The request context (auth/locale/env) passed to the transport. */
+  readonly context: GraphRequestContext;
+}
+declare function createMutator(options: CreateMutatorOptions): BoundMutations;
+//#endregion
+//#region src/context.d.ts
+/**
+ * Structural RWSDK types.
+ *
+ * This package never imports `rwsdk` — like `@gleanql/vite`, it is decoupled from
+ * the host framework and matches its shapes structurally, so it can be tested in
+ * isolation and won't pin a framework version. A RedwoodSDK route handler / Page
+ * receives a `RequestInfo`:
+ *   route("/product/:handle", ({ request, params, ctx }) => <ProductRoute ... />)
+ */
+interface RequestInfo<Ctx extends Record<string, unknown> = Record<string, unknown>> {
+  readonly request: Request;
+  /** Dynamic route segments, e.g. `params.handle`, `params.$0`. */
+  readonly params: Record<string, string>;
+  /** Per-request mutable app context populated by middleware. */
+  readonly ctx: Ctx;
+  /** RedwoodSDK-specific context (opaque here). */
+  readonly rw?: unknown;
+  /** Cloudflare ExecutionContext. */
+  readonly cf?: unknown;
+  /** Mutable ResponseInit (status/headers). */
+  readonly response?: ResponseInit;
+}
+/**
+ * The route context object handed to the compiled variables factory *and* used
+ * as the transport `GraphRequestContext`. The compiler emits factories that read
+ * `ctx.params.handle`, `ctx.search.get(...)`, etc., so this shape is the contract
+ * between the generated code and the adapter.
+ */
+interface GraphRouteContext extends GraphRequestContext {
+  readonly params: Record<string, string>;
+  readonly search: URLSearchParams;
+  readonly request: Request;
+  /** Application context contributed by `options.context` (auth, locale, env, ...). */
+  readonly [key: string]: unknown;
+}
+interface BuildRouteContextOptions<Ctx extends Record<string, unknown>> {
+  /**
+   * Contribute application context (shop domain, access token, locale, market,
+   * preview mode, Cloudflare env). Anything returned here is available to the
+   * variables factory and to the transport adapter's header builder.
+   */
+  readonly context?: (requestInfo: RequestInfo<Ctx>) => Record<string, unknown>;
+}
+/**
+ * Build the route/request context from a RequestInfo. `params` and `search` come
+ * from the URL; everything else is contributed by `options.context`. The raw
+ * `request` is included for header derivation but is *not* serialized to the
+ * client (see `serializeGraph`).
+ */
+declare function buildRouteContext<Ctx extends Record<string, unknown>>(requestInfo: RequestInfo<Ctx>, options?: BuildRouteContextOptions<Ctx>): GraphRouteContext;
+//#endregion
+//#region src/integration.d.ts
+interface ActiveRequestGraph extends GraphRequestContext {
+  readonly runtime: GraphRuntime;
+  readonly graph: BoundGraph;
+  /** `graph.mutate.*` — one callable per compiled mutation operation. */
+  readonly mutate: BoundMutations;
+  readonly roots: Record<string, FieldValue>;
+  readonly operation: CompiledOperation<GraphRouteContext>;
+  readonly variables: Record<string, unknown>;
+  /** The route/request context (used for transport + missing-field fetches). */
+  readonly requestContext: GraphRouteContext;
+  readonly errors?: ReadonlyArray<{
+    message: string;
+  }>;
+}
+interface GraphIntegrationOptions<Ctx extends Record<string, unknown> = Record<string, unknown>> extends BuildRouteContextOptions<Ctx> {
+  readonly schema: SchemaModel;
+  /** Compiled operations, keyed by name (e.g. from `virtual:graph/operations`). */
+  readonly operations: Record<string, CompiledOperation<GraphRouteContext>>;
+  /** Transport: a fetch/graphql-request adapter. */
+  readonly adapter: GraphClientAdapter;
+  /** Map a request to its operation name when `preload` is called without one. */
+  readonly resolveOperationName?: (requestInfo: RequestInfo<Ctx>) => string | undefined;
+  /**
+   * Fetch fields absent from the compiled operation (lazy boundaries, dynamic
+   * misses). Receives the batched misses + request context; returns resolved
+   * values. If omitted, misses are allowed/warned per `unexpectedMissingField`
+   * (hybrid mode) and resolve to `undefined`.
+   */
+  readonly fetchMissing?: (misses: readonly MissingFieldRead[], context: GraphRequestContext) => Promise<readonly MissingFieldResult[]>;
+  readonly unexpectedMissingField?: MissingFieldMode;
+  readonly onWarn?: (message: string) => void;
+  /** Allow-list of `context` keys that are safe to serialize to the client. */
+  readonly clientSafeContext?: readonly string[];
+  /** Optional scope to make a module-level `graph` import resolve this runtime. */
+  readonly scope?: GraphScope;
+}
+interface GraphIntegration<Ctx extends Record<string, unknown>> {
+  /** Preload + seed the operation for a request; attaches the graph to `ctx`. */
+  preload(requestInfo: RequestInfo<Ctx>, operationName?: string): Promise<ActiveRequestGraph | undefined>;
+  /** Read the active graph attached to a request (throws if not preloaded). */
+  getGraph(requestInfo: RequestInfo<Ctx>): BoundGraph;
+  /** The `graph.mutate.*` namespace for this request (throws if not preloaded). */
+  getMutator(requestInfo: RequestInfo<Ctx>): BoundMutations;
+  /** Invalidate a graph value / ref in this request's cache (refetch on next read). */
+  invalidate(requestInfo: RequestInfo<Ctx>, value: GraphRef | unknown): void;
+  /** Read the full active request state (runtime, roots, variables, ...). */
+  getActive(requestInfo: RequestInfo<Ctx>): ActiveRequestGraph | undefined;
+  /** Re-run the active (or named) operation, bypassing cache-first, into the same cache. */
+  refetch(requestInfo: RequestInfo<Ctx>, operationName?: string): Promise<void>;
+  /** Run `fn` with this request's runtime installed on the scope (server render). */
+  runInScope<R>(requestInfo: RequestInfo<Ctx>, fn: () => R): R;
+}
+declare function createGraphIntegration<Ctx extends Record<string, unknown> = Record<string, unknown>>(options: GraphIntegrationOptions<Ctx>): GraphIntegration<Ctx>;
+//#endregion
+//#region src/serialize.d.ts
+/**
+ * Server -> client serialization.
+ *
+ * Graph values are proxies, not JSON, so we don't serialize them. We serialize
+ * the *cache* (normalized records + path records) plus the root refs and the
+ * operation identity. On the client we rebuild a runtime from that snapshot and
+ * re-bind the graph, so client components read the same fields with cache hits;
+ * fields absent from the snapshot fetch through the client adapter.
+ *
+ * Secrets stay server-side: only `clientSafeContext` keys are serialized.
+ */
+interface GraphHydrationPayload {
+  readonly operationName: string;
+  readonly variables: Record<string, unknown>;
+  readonly snapshot: Record<string, Record<string, FieldValue>>;
+  readonly roots: Record<string, FieldValue>;
+  /** Allow-listed, client-safe slice of the request context. */
+  readonly context: Record<string, unknown>;
+}
+interface SerializeGraphOptions {
+  /** Keys of the request context that are safe to ship to the client. */
+  readonly clientSafeContext?: readonly string[];
+}
+/** Build the JSON-safe hydration payload from an active request. */
+declare function serializeGraph(active: ActiveRequestGraph, options?: SerializeGraphOptions): GraphHydrationPayload;
+/**
+ * Render a `<script>` that publishes the payload on `window[globalKey]` for
+ * client hydration. JSON is escaped so it cannot break out of the script element
+ * or be interpreted as HTML (`<`, `>`, `&`, U+2028/U+2029).
+ */
+declare function renderGraphHydrationScript(payload: GraphHydrationPayload, options?: {
+  globalKey?: string;
+  nonce?: string;
+}): string;
+/**
+ * Just the inner JS of the hydration script (no `<script>` wrapper), for JSX
+ * hosts that inject via `dangerouslySetInnerHTML` and set the nonce themselves.
+ * JSON is escaped so it can't break out of the script element or be parsed as HTML.
+ */
+declare function graphHydrationScriptContent(payload: GraphHydrationPayload, globalKey?: string): string;
+/** Read the hydration payload published by `renderGraphHydrationScript` (client). */
+declare function readGraphHydrationPayload(globalKey?: string): GraphHydrationPayload | undefined;
+interface HydrateGraphOptions {
+  readonly schema: SchemaModel;
+  readonly adapter: GraphClientAdapter;
+  /** Fetch fields absent from the hydrated snapshot (lazy/dynamic reads). */
+  readonly fetchMissing?: (misses: readonly MissingFieldRead[], context: GraphRequestContext) => Promise<readonly MissingFieldResult[]>;
+  readonly unexpectedMissingField?: MissingFieldMode;
+  readonly onWarn?: (message: string) => void;
+  /** Install the hydrated runtime on this scope as the client singleton. */
+  readonly scope?: GraphScope;
+}
+interface HydratedGraph {
+  readonly runtime: GraphRuntime;
+  readonly graph: BoundGraph;
+  readonly roots: Record<string, FieldValue>;
+  readonly context: Record<string, unknown>;
+}
+/**
+ * Rebuild the runtime + bound graph on the client from a hydration payload.
+ * Reads present in the snapshot resolve synchronously; missing fields suspend and
+ * fetch through the client adapter.
+ */
+declare function hydrateGraph(payload: GraphHydrationPayload, options: HydrateGraphOptions): HydratedGraph;
+/**
+ * RSC-native hydration (vs. the `<script>`/`window` model above).
+ *
+ * Under React Server Components the `Document` shell is rendered once, but each
+ * client navigation re-streams only the page subtree. So a one-shot global can't
+ * keep client islands warm across navigation. Instead the payload rides the RSC
+ * flight stream as a prop of a client component (it is plain JSON by
+ * construction), and on every (re)render that component folds it into a single
+ * long-lived client runtime — the cache accumulates across navigations.
+ */
+/** The page-current pointer islands read for `refresh()` (which operation + vars). */
+interface GraphPagePointer {
+  readonly operationName: string;
+  readonly variables: Record<string, unknown>;
+  readonly context: Record<string, unknown>;
+  readonly roots: Record<string, FieldValue>;
+}
+/**
+ * Render-phase merge: fold a payload's snapshot into a live runtime, write-only
+ * (no subscriber notify — the caller bumps in a commit-phase effect). Idempotent.
+ * Returns whether anything changed.
+ */
+declare function absorbHydrationPayload(runtime: GraphRuntime, payload: GraphHydrationPayload): boolean;
+/** Derive the current-page pointer from a payload (drives `refresh()`). */
+declare function pagePointer(payload: GraphHydrationPayload): GraphPagePointer;
+//#endregion
+//#region src/adapter-shared.d.ts
+/**
+ * Shared helpers for client adapters.
+ *
+ * Every adapter implements the same `GraphClientAdapter.execute` contract; the
+ * runtime owns cache identity and Suspense, so an adapter is *only* transport.
+ * These helpers keep error/response mapping consistent across clients.
+ */
+interface GraphQLError {
+  readonly message: string;
+}
+/** Build a `GraphResult`, omitting empty `data`/`errors` keys. */
+declare function result<TData>(data: TData | null | undefined, errors?: readonly GraphQLError[]): GraphResult<TData>;
+/** A push→pull async iterator: the transport pushes, the consumer pulls. */
+interface PushPullIterator<T> extends AsyncIterator<T> {
+  /** Deliver the next value to the consumer (ignored once finished). */
+  push(value: T): void;
+  /** End the stream; the consumer's next pull resolves `{ done: true }`. */
+  finish(): void;
+}
+/**
+ * Bridge a push-based transport (SSE `onmessage`, a graphql-ws sink) into the
+ * pull-based `AsyncIterator` the runtime consumes. The transport wires its callbacks
+ * to `push`/`finish`; the consumer's `return()` (cleanup) calls `onReturn` to tear the
+ * transport down. Values pushed with no pending pull queue up and drain in order.
+ */
+declare function pushPullIterator<T>(onReturn?: () => void): PushPullIterator<T>;
+//#endregion
+//#region src/adapter-ws.d.ts
+/**
+ * A `graphql-ws` transport for the same `GraphClientAdapter` seam the fetch
+ * adapter implements. WebSockets carry every operation kind — a query/mutation is
+ * a single-result stream that completes, a subscription is a long-lived one — so
+ * this adapter drives both `execute` and `subscribe` off one `graphql-ws` client.
+ *
+ * We do NOT bundle `graphql-ws`: the app installs it, calls its `createClient({ url })`,
+ * and passes the result here. The client is typed structurally (the subset we use)
+ * so the dependency stays optional and the adapter is trivially testable with a fake.
+ *
+ *   import { createClient } from "graphql-ws";
+ *   const adapter = createGraphWsAdapter({ client: createClient({ url: "wss://…/graphql" }) });
+ */
+/** Sink graphql-ws pushes results into — mirrors its `Sink`. */
+interface GraphWsSink<T = unknown> {
+  next: (value: T) => void;
+  error: (error: unknown) => void;
+  complete: () => void;
+}
+/** Operation payload graphql-ws subscribes with — mirrors its `SubscribePayload`. */
+interface GraphWsPayload {
+  readonly query: string;
+  readonly variables?: Record<string, unknown> | null;
+  readonly operationName?: string | null;
+  readonly extensions?: Record<string, unknown>;
+}
+/** Structural subset of graphql-ws's `Client` we depend on. */
+interface GraphWsClient {
+  subscribe<T = GraphResult<unknown>>(payload: GraphWsPayload, sink: GraphWsSink<T>): () => void;
+  dispose?: () => void | Promise<void>;
+}
+interface GraphWsAdapterOptions {
+  /** A graphql-ws client, e.g. `createClient({ url })`. */
+  readonly client: GraphWsClient;
+  /**
+   * Per-request `extensions` from context (auth token, shop domain, locale). The
+   * connection-level params belong on the client; this rides each operation.
+   */
+  readonly extensions?: (context: GraphRequestContext) => Record<string, unknown>;
+}
+declare function createGraphWsAdapter(options: GraphWsAdapterOptions): GraphClientAdapter;
+//#endregion
+//#region src/persisted.d.ts
+/**
+ * Server-side persisted-operation allowlist.
+ *
+ * The build already knows every operation the app can send (the compiled
+ * `operations` map carries each document + its SHA-256 hash), so the server can
+ * refuse anything else. `createPersistedResolver(operations)` turns an incoming
+ * request body into the document to execute — by hash (`extensions.
+ * persistedQuery.sha256Hash`, the Apollo APQ wire shape the fetch adapter's
+ * `persisted: true` mode sends) or by exact-document match — and rejects
+ * free-form queries unless explicitly allowed.
+ */
+/** The slice of a compiled operation the resolver needs (the generated `operations` map satisfies it). */
+interface PersistedLookupOperation {
+  readonly document: string;
+  readonly hash?: string;
+}
+/** A GraphQL-over-HTTP request body, as parsed from JSON. */
+interface PersistedRequestBody {
+  readonly query?: string;
+  readonly operationName?: string;
+  readonly variables?: unknown;
+  readonly extensions?: {
+    readonly persistedQuery?: {
+      readonly version?: number;
+      readonly sha256Hash?: string;
+    };
+  };
+}
+type PersistedResolution = /** Execute this document. */{
+  readonly kind: "ok";
+  readonly document: string;
+} /** Unknown hash and no usable document — reply `PersistedQueryNotFound` so an APQ client retries with the query. */ | {
+  readonly kind: "not-found";
+} /** Free-form (or mismatched) query outside the allowlist — reply 4xx. */ | {
+  readonly kind: "rejected";
+};
+interface PersistedResolverOptions {
+  /** Execute documents that aren't in the allowlist (turns the allowlist into hash-only transport compression). */
+  readonly allowUnpersisted?: boolean;
+}
+declare function createPersistedResolver(operations: Readonly<Record<string, PersistedLookupOperation>>, options?: PersistedResolverOptions): (body: PersistedRequestBody) => PersistedResolution;
+//#endregion
+export { ActiveGraph, ActiveRequestGraph, BindGraphOptions, BoundGraph, BoundMutations, BuildRouteContextOptions, CacheResolution, CompiledOperation, CreateMutatorOptions, FetchAdapterOptions, FieldLookup, FieldValue, GRAPH_REF, GRAPH_TRAIL, GRAPH_TYPE, GraphBinding, GraphCache, GraphClientAdapter, GraphHydrationPayload, GraphIntegration, GraphIntegrationOptions, GraphOperation, GraphPagePointer, GraphQLError, GraphRef, GraphRequestContext, GraphResult, GraphRouteContext, GraphRuntime, GraphRuntimeOptions, GraphScope, GraphSelection, GraphWsAdapterOptions, GraphWsClient, GraphWsPayload, GraphWsSink, HydrateGraphOptions, HydratedGraph, KeyOf, MissingFieldMode, MissingFieldRead, MissingFieldResult, MutateFn, MutationOperationLike, MutationResult, MutationTransaction, PathStep, PersistedLookupOperation, PersistedRequestBody, PersistedResolution, PersistedResolverOptions, PushPullIterator, RequestInfo, RunMutationOptions, RunRouteOptions, RunRouteResult, SerializeGraphOptions, UserError, absorbHydrationPayload, bindGraph, bindScope, buildRouteContext, createFetchAdapter, createGraphIntegration, createGraphProxy, createGraphWsAdapter, createMutator, createPersistedResolver, errorMessage, graphHydrationScriptContent, hydrateGraph, invalidateValue, isGraphRef, normalizeValue, pagePointer, persistRootLinks, pushPullIterator, readGraphHydrationPayload, refetch, renderGraphHydrationScript, resolveFromCache, responseKeyCandidates, result, runMutation, runRoute, seedResult, selectionOf, serializeGraph, setReadTracker, toArgMap, trailOf };