@gleanql/client 0.1.0

package/dist/index.mjs

@@ -0,0 +1,1412 @@
+import { argAliasSuffix, canonicalArgs, responseKey } from "@gleanql/core";
+//#region src/adapter-shared.ts
+/** Build a `GraphResult`, omitting empty `data`/`errors` keys. */
+function result(data, errors) {
+	return {
+		...data != null ? { data } : {},
+		...errors && errors.length > 0 ? { errors } : {}
+	};
+}
+/**
+* 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.
+*/
+function pushPullIterator(onReturn) {
+	const queue = [];
+	let waiting = null;
+	let done = false;
+	const ended = () => ({
+		value: void 0,
+		done: true
+	});
+	const finish = () => {
+		if (done) return;
+		done = true;
+		if (waiting) {
+			waiting(ended());
+			waiting = null;
+		}
+	};
+	return {
+		push(value) {
+			if (done) return;
+			if (waiting) {
+				waiting({
+					value,
+					done: false
+				});
+				waiting = null;
+			} else queue.push(value);
+		},
+		finish,
+		next() {
+			if (queue.length > 0) return Promise.resolve({
+				value: queue.shift(),
+				done: false
+			});
+			if (done) return Promise.resolve(ended());
+			return new Promise((resolve) => {
+				waiting = resolve;
+			});
+		},
+		return() {
+			onReturn?.();
+			finish();
+			return Promise.resolve(ended());
+		}
+	};
+}
+//#endregion
+//#region src/adapter.ts
+/**
+* Client adapter interface. The graph runtime owns cache identity, Suspense,
+* batching and normalization; an adapter owns transport (HTTP, auth, retries).
+* Ships a plain fetch adapter; any transport (graphql-ws for subscriptions, or a
+* urql/Apollo client if an app already runs one) slots in behind this interface.
+*/
+/** Minimal fetch transport. Context is used only to build headers; it is never serialized into the body. */
+function createFetchAdapter(options) {
+	const doFetch = options.fetch ?? fetch;
+	return {
+		async execute(operation, variables, context) {
+			const post = async (body) => {
+				const res = await doFetch(options.endpoint, {
+					method: "POST",
+					headers: {
+						"content-type": "application/json",
+						...options.headers ? options.headers(context) : {}
+					},
+					body: JSON.stringify(body)
+				});
+				const parsed = await res.json().catch(() => void 0);
+				if (parsed === void 0) throw new Error(`graph fetch: non-JSON response (${res.status} ${res.statusText}) from ${options.endpoint}`);
+				return parsed;
+			};
+			if (options.persisted && operation.hash) {
+				const extensions = { persistedQuery: {
+					version: 1,
+					sha256Hash: operation.hash
+				} };
+				const first = await post({
+					operationName: operation.name,
+					variables,
+					extensions
+				});
+				if (first.errors?.some((e) => e.message === "PersistedQueryNotFound")) {
+					options.onPersistedRetry?.(operation.name);
+					return post({
+						query: operation.document,
+						operationName: operation.name,
+						variables,
+						extensions
+					});
+				}
+				return first;
+			}
+			return post({
+				query: operation.document,
+				variables,
+				operationName: operation.name
+			});
+		},
+		subscribe(operation, variables) {
+			return sseIterable(options.subscriptionEndpoint ?? `${options.endpoint}/stream`, operation.document, variables, operation.name);
+		}
+	};
+}
+/** Bridge a Server-Sent Events stream into an `AsyncIterable<GraphResult>`. */
+function sseIterable(url, document, variables, operationName) {
+	return { [Symbol.asyncIterator]() {
+		if (typeof EventSource === "undefined") return { next: () => Promise.resolve({
+			value: void 0,
+			done: true
+		}) };
+		const qs = `query=${encodeURIComponent(document)}&operationName=${encodeURIComponent(operationName)}&variables=${encodeURIComponent(JSON.stringify(variables ?? {}))}`;
+		const es = new EventSource(`${url}?${qs}`);
+		const it = pushPullIterator(() => es.close());
+		es.onmessage = (e) => {
+			try {
+				it.push(JSON.parse(e.data));
+			} catch {}
+		};
+		es.onerror = () => it.push({ errors: [{ message: "subscription stream error" }] });
+		return it;
+	} };
+}
+//#endregion
+//#region src/cache.ts
+/** Separator joining a record key + field key into one field-tracking key (NUL — never in a key). */
+const FIELD_SEP = "\0";
+function fieldTrackingKey(recordKey, fieldKey) {
+	return recordKey + FIELD_SEP + fieldKey;
+}
+var GraphCache = class GraphCache {
+	maxRecords;
+	records = /* @__PURE__ */ new Map();
+	/**
+	* 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) {
+		this.maxRecords = maxRecords;
+	}
+	/**
+	* 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.
+	*/
+	_version = 0;
+	listeners = /* @__PURE__ */ new Set();
+	/**
+	* 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}.
+	*/
+	recordVersions = /* @__PURE__ */ new Map();
+	fieldVersions = /* @__PURE__ */ new Map();
+	/** Current version of a record (0 if never written). */
+	recordVersion(key) {
+		return this.recordVersions.get(key) ?? 0;
+	}
+	/** Current version of a single field on a record (0 if never written). */
+	fieldVersion(recordKey, fieldKey) {
+		return this.fieldVersions.get(fieldTrackingKey(recordKey, fieldKey)) ?? 0;
+	}
+	/** The opaque tracking key a field read records; resolve it with {@link trackedVersion}. */
+	fieldTrackingKey(recordKey, fieldKey) {
+		return fieldTrackingKey(recordKey, fieldKey);
+	}
+	/** Version of a tracked key: a bare record key, or `record\0field` for a single field. */
+	trackedVersion(trackingKey) {
+		return trackingKey.includes(FIELD_SEP) ? this.fieldVersions.get(trackingKey) ?? 0 : this.recordVersion(trackingKey);
+	}
+	/** Bump a record's version + (optionally) one of its fields' versions. */
+	bumpRecord(key, fieldKey) {
+		this.recordVersions.set(key, (this.recordVersions.get(key) ?? 0) + 1);
+		if (fieldKey !== void 0) this.bumpField(key, fieldKey);
+	}
+	bumpField(recordKey, fieldKey) {
+		const k = fieldTrackingKey(recordKey, fieldKey);
+		this.fieldVersions.set(k, (this.fieldVersions.get(k) ?? 0) + 1);
+	}
+	get version() {
+		return this._version;
+	}
+	subscribe(listener) {
+		this.listeners.add(listener);
+		return () => this.listeners.delete(listener);
+	}
+	bump() {
+		this._version++;
+		for (const listener of this.listeners) listener();
+	}
+	/** Public notify: bump the version + run listeners (e.g. after `absorbRecords`). */
+	notify() {
+		this.bump();
+	}
+	/** Stable storage key for a ref: entity identity wins over path identity. */
+	recordKey(ref) {
+		if (ref.__typename != null && ref.id != null) return `${ref.__typename}:${ref.id}`;
+		if (ref.path != null) return `path:${ref.path}`;
+		throw new Error("GraphRef requires either (__typename + id) or path");
+	}
+	/**
+	* 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.
+	*/
+	retainCounts = /* @__PURE__ */ new Map();
+	/** Pin a record. Returns the matching release; calling it twice is a no-op. */
+	retain(key) {
+		this.stamp(key);
+		this.retainCounts.set(key, (this.retainCounts.get(key) ?? 0) + 1);
+		let released = false;
+		return () => {
+			if (released) return;
+			released = true;
+			const n = this.retainCounts.get(key) ?? 0;
+			if (n <= 1) this.retainCounts.delete(key);
+			else this.retainCounts.set(key, n - 1);
+		};
+	}
+	isRetained(key) {
+		return this.retainCounts.has(key);
+	}
+	/** The record key a tracked key belongs to (strips the `\0field` part, if any). */
+	trackedRecordKey(trackingKey) {
+		const i = trackingKey.indexOf(FIELD_SEP);
+		return i === -1 ? trackingKey : trackingKey.slice(0, i);
+	}
+	/**
+	* 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.
+	*/
+	epoch = 0;
+	lastActive = /* @__PURE__ */ new Map();
+	/** Advance the generation clock (call on navigation). Returns the new epoch. */
+	advanceEpoch() {
+		return ++this.epoch;
+	}
+	stamp(key) {
+		this.lastActive.set(key, this.epoch);
+	}
+	/**
+	* 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 = {}) {
+		const { keepEpochs } = options;
+		let dropped = 0;
+		for (const key of [...this.records.keys()]) {
+			if (this.retainCounts.has(key)) continue;
+			if (keepEpochs != null && this.epoch - (this.lastActive.get(key) ?? 0) < keepEpochs) continue;
+			this.records.delete(key);
+			this.lastActive.delete(key);
+			dropped++;
+		}
+		if (dropped > 0) this.bump();
+		return dropped;
+	}
+	hasRecord(ref) {
+		return this.records.has(this.recordKey(ref));
+	}
+	/** Mark a key most-recently-used (Map keeps insertion order; re-insert to bump). No-op when unbounded. */
+	touch(key) {
+		if (!this.maxRecords) return;
+		const rec = this.records.get(key);
+		if (rec) {
+			this.records.delete(key);
+			this.records.set(key, rec);
+		}
+	}
+	/**
+	* 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.
+	*/
+	evict() {
+		if (!this.maxRecords) return;
+		let over = this.records.size - this.maxRecords;
+		if (over <= 0) return;
+		for (const key of [...this.records.keys()]) {
+			if (over <= 0) break;
+			if (this.retainCounts.has(key)) continue;
+			this.records.delete(key);
+			over--;
+		}
+	}
+	/** Get-or-create the record map for a storage key. */
+	ensureRecord(key) {
+		this.stamp(key);
+		let rec = this.records.get(key);
+		if (!rec) {
+			rec = /* @__PURE__ */ new Map();
+			this.records.set(key, rec);
+		} else this.touch(key);
+		return rec;
+	}
+	getField(ref, fieldKey) {
+		const key = this.recordKey(ref);
+		const rec = this.records.get(key);
+		if (rec && rec.has(fieldKey)) {
+			this.touch(key);
+			this.stamp(key);
+			return {
+				status: "ready",
+				value: rec.get(fieldKey)
+			};
+		}
+		return { status: "missing" };
+	}
+	setField(ref, fieldKey, value) {
+		const key = this.recordKey(ref);
+		this.ensureRecord(key).set(fieldKey, value);
+		this.bumpRecord(key, fieldKey);
+		this.evict();
+		this.bump();
+	}
+	/** Merge a flat record of fields into the entity/path record. */
+	merge(ref, fields) {
+		const key = this.recordKey(ref);
+		const rec = this.ensureRecord(key);
+		for (const [k, v] of Object.entries(fields)) {
+			rec.set(k, v);
+			this.bumpField(key, k);
+		}
+		this.bumpRecord(key);
+		this.evict();
+		this.bump();
+	}
+	/** Drop a whole record (mutation invalidation). */
+	invalidate(ref) {
+		const key = this.recordKey(ref);
+		for (const fieldKey of this.records.get(key)?.keys() ?? []) this.bumpField(key, fieldKey);
+		this.records.delete(key);
+		this.bumpRecord(key);
+		this.bump();
+	}
+	/** Drop a single field so the next read re-fetches it. */
+	invalidateField(ref, fieldKey) {
+		const key = this.recordKey(ref);
+		this.records.get(key)?.delete(fieldKey);
+		this.bumpRecord(key, fieldKey);
+		this.bump();
+	}
+	/**
+	* 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) {
+		let changed = false;
+		for (const [key, fields] of Object.entries(snapshot)) {
+			const rec = this.ensureRecord(key);
+			let recordChanged = false;
+			for (const [k, v] of Object.entries(fields)) if (!rec.has(k) || rec.get(k) !== v) {
+				rec.set(k, v);
+				this.bumpField(key, k);
+				recordChanged = true;
+			}
+			if (recordChanged) {
+				this.bumpRecord(key);
+				changed = true;
+			}
+		}
+		this.evict();
+		return changed;
+	}
+	/** Serialize the whole cache (for hydration). */
+	snapshot() {
+		const out = {};
+		for (const [key, rec] of this.records) out[key] = Object.fromEntries(rec);
+		return out;
+	}
+	static fromSnapshot(snapshot, maxRecords) {
+		const cache = new GraphCache(maxRecords);
+		for (const [key, rec] of Object.entries(snapshot)) cache.records.set(key, new Map(Object.entries(rec)));
+		cache.evict();
+		return cache;
+	}
+};
+//#endregion
+//#region src/normalize.ts
+const defaultKeyOf = (_t, obj) => obj.id != null ? String(obj.id) : void 0;
+function normalizeValue(cache, value, anchor, field, keyOf = defaultKeyOf, seen = /* @__PURE__ */ new WeakSet()) {
+	if (value === null || typeof value !== "object") return value;
+	if (seen.has(value)) throw new Error(`normalizeValue: circular reference at ${anchor}.${field} — cannot normalize cyclic data`);
+	seen.add(value);
+	try {
+		return normalizeNonCyclic(cache, value, anchor, field, keyOf, seen);
+	} finally {
+		seen.delete(value);
+	}
+}
+function normalizeNonCyclic(cache, value, anchor, field, keyOf, seen) {
+	if (Array.isArray(value)) return value.map((item, i) => normalizeValue(cache, item, anchor, `${field}.${i}`, keyOf, seen));
+	const obj = value;
+	const typename = typeof obj.__typename === "string" ? obj.__typename : void 0;
+	const identity = typename != null ? keyOf(typename, obj) : void 0;
+	if (typename != null && identity != null) {
+		const ref = {
+			__typename: typename,
+			id: identity
+		};
+		const entityAnchor = cache.recordKey(ref);
+		for (const [key, v] of Object.entries(obj)) cache.setField(ref, key, normalizeValue(cache, v, entityAnchor, key, keyOf, seen));
+		return ref;
+	}
+	const ref = { path: `${anchor}.${field}` };
+	for (const [key, v] of Object.entries(obj)) cache.setField(ref, key, normalizeValue(cache, v, anchor, `${field}.${key}`, keyOf, seen));
+	return ref;
+}
+/** Seed an operation result; returns each root field's ref for reading. */
+function seedResult(cache, data, options = {}) {
+	const rootPath = options.rootPath ?? "Query";
+	const roots = {};
+	for (const [field, value] of Object.entries(data)) roots[field] = normalizeValue(cache, value, rootPath, field, options.keyOf);
+	return roots;
+}
+//#endregion
+//#region src/runtime.ts
+var GraphRuntime = class GraphRuntime {
+	options;
+	cache;
+	pending = /* @__PURE__ */ new Map();
+	queue = [];
+	flushScheduled = false;
+	constructor(options) {
+		this.options = options;
+		this.cache = options.cache ?? new GraphCache(options.maxCacheRecords);
+	}
+	/** Synchronous on hit; throws a (cached) promise on miss. */
+	readField(ref, fieldKey, debug) {
+		const got = this.cache.getField(ref, fieldKey);
+		if (got.status === "ready") return got.value;
+		this.reportMiss(ref, fieldKey, debug);
+		const pkey = this.pendingKey(ref, fieldKey);
+		const existing = this.pending.get(pkey);
+		if (existing) throw existing.promise;
+		const entry = this.makeDeferred();
+		this.pending.set(pkey, entry);
+		this.queue.push({
+			ref,
+			fieldKey
+		});
+		this.scheduleFlush();
+		throw entry.promise;
+	}
+	/** Seed a record's fields (e.g. from the compiled operation result). */
+	seed(ref, fields) {
+		this.cache.merge(ref, fields);
+	}
+	/** Normalize a full operation result into the cache; returns root refs. */
+	seedResult(data, options) {
+		return seedResult(this.cache, data, {
+			keyOf: this.options.keyOf,
+			...options
+		});
+	}
+	/**
+	* 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, page, mergeRefs) {
+		const keyOf = this.options.keyOf;
+		const anchor = this.cache.recordKey(connectionRef);
+		const existing = this.cache.getField(connectionRef, "nodes");
+		const prior = existing.status === "ready" && Array.isArray(existing.value) ? existing.value : [];
+		if (Array.isArray(page.nodes)) {
+			const fresh = page.nodes.map((n, i) => normalizeValue(this.cache, n, anchor, `nodes.${prior.length + i}`, keyOf));
+			const merged = mergeRefs ? mergeRefs(prior, fresh) : [...prior, ...fresh];
+			this.cache.setField(connectionRef, "nodes", [...merged]);
+		}
+		if (page.pageInfo != null) this.cache.setField(connectionRef, "pageInfo", normalizeValue(this.cache, page.pageInfo, anchor, "pageInfo", keyOf));
+	}
+	/** Invalidate a record (e.g. after a mutation) and clear its pending reads. */
+	invalidate(ref) {
+		const prefix = `${this.cache.recordKey(ref)}.`;
+		this.cache.invalidate(ref);
+		for (const key of [...this.pending.keys()]) if (key.startsWith(prefix)) this.pending.delete(key);
+	}
+	/** Serialize the cache for hydration across the server/client boundary. */
+	snapshot() {
+		return this.cache.snapshot();
+	}
+	/**
+	* 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) {
+		return this.cache.absorbRecords(snapshot);
+	}
+	/** Notify subscribers after one or more `absorbRecords` calls. */
+	notify() {
+		this.cache.notify();
+	}
+	/** Convenience: absorb a snapshot and notify if it changed (non-React callers). */
+	absorb(snapshot) {
+		const changed = this.cache.absorbRecords(snapshot);
+		if (changed) this.cache.notify();
+		return changed;
+	}
+	static hydrate(snapshot, options) {
+		return new GraphRuntime({
+			...options,
+			cache: GraphCache.fromSnapshot(snapshot, options.maxCacheRecords)
+		});
+	}
+	reportMiss(ref, fieldKey, debug) {
+		const mode = this.options.unexpectedMissingField ?? "allow";
+		if (mode === "allow") return;
+		const where = debug?.component ? ` (read by ${debug.component})` : "";
+		const message = `Runtime graph field miss: ${this.cache.recordKey(ref)}.${fieldKey}${where} was not in the compiled operation.`;
+		if (mode === "error") throw new Error(message);
+		(this.options.onWarn ?? ((m) => console.warn(m)))(message);
+	}
+	scheduleFlush() {
+		if (this.flushScheduled) return;
+		this.flushScheduled = true;
+		(this.options.schedule ?? queueMicrotask)(() => void this.flush());
+	}
+	async flush() {
+		this.flushScheduled = false;
+		const misses = this.queue;
+		this.queue = [];
+		if (misses.length === 0) return;
+		try {
+			const results = await this.options.fetchMissing(misses);
+			for (const r of results) this.cache.setField(r.ref, r.fieldKey, r.value);
+			for (const miss of misses) {
+				const pkey = this.pendingKey(miss.ref, miss.fieldKey);
+				this.pending.get(pkey)?.resolve();
+				this.pending.delete(pkey);
+			}
+		} catch (error) {
+			for (const miss of misses) {
+				const pkey = this.pendingKey(miss.ref, miss.fieldKey);
+				this.pending.get(pkey)?.reject(error);
+				this.pending.delete(pkey);
+			}
+		}
+	}
+	/** Stable key for a pending (ref, field) read — also the `invalidate` prefix base. */
+	pendingKey(ref, fieldKey) {
+		return `${this.cache.recordKey(ref)}.${fieldKey}`;
+	}
+	makeDeferred() {
+		let resolve;
+		let reject;
+		return {
+			promise: new Promise((res, rej) => {
+				resolve = res;
+				reject = rej;
+			}),
+			resolve,
+			reject
+		};
+	}
+};
+//#endregion
+//#region src/proxy.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. */
+const GRAPH_REF = Symbol.for("graph.ref");
+const GRAPH_TYPE = Symbol.for("graph.type");
+const GRAPH_TRAIL = Symbol.for("graph.trail");
+/**
+* Read tracking for fine-grained reactivity. Every field read records the record
+* key it touched into the active tracker; the tracking hook's `useSyncExternalStore`
+* snapshot is then a digest of just those records' versions.
+*
+* Attribution is primarily PER BINDING: `useGlean` binds the graph with its render's
+* own `affected` set (see `GraphBinding.tracker`), so reads through that render's
+* proxies record into that set directly — fiber-local, safe under concurrent/
+* interleaved rendering. This ambient global is only a fallback for proxies created
+* without a binding tracker (the server / isomorphic accessor), where no re-render
+* depends on attribution.
+*/
+let currentTracker = null;
+/** Install (or clear) the active read tracker. Returns the previous one. */
+function setReadTracker(tracker) {
+	const prev = currentTracker;
+	currentTracker = tracker;
+	return prev;
+}
+/** A value is a `GraphRef` if it carries entity identity or a path. */
+function isGraphRef(value) {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+	const v = value;
+	return v.__typename != null && v.id != null || typeof v.path === "string";
+}
+function toArgValue(value) {
+	if (value === null) return {
+		kind: "literal",
+		value: null
+	};
+	if (Array.isArray(value)) return {
+		kind: "list",
+		items: value.map(toArgValue)
+	};
+	if (typeof value === "object") return {
+		kind: "object",
+		fields: Object.entries(value).map(([k, v]) => [k, toArgValue(v)])
+	};
+	return {
+		kind: "literal",
+		value
+	};
+}
+/** Plain runtime args (`{ first: 12 }`) -> IR `ArgMap`, reusing core's canonicalization. */
+function toArgMap(args) {
+	if (!args) return [];
+	return Object.entries(args).map(([k, v]) => [k, toArgValue(v)]);
+}
+/**
+* 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.
+*/
+function responseKeyCandidates(name, argMap) {
+	if (argMap.length === 0) return [name];
+	const suffix = argAliasSuffix(argMap);
+	return suffix ? [`${name}_${suffix}`, name] : [name];
+}
+/** Read a field on a ref, resolving the right response key, and wrap object/list results. */
+function readField(state, fieldName, args) {
+	const { binding, ref, type } = state;
+	const runtime = binding.getRuntime();
+	const fieldDef = binding.schema.getField(type, fieldName);
+	const candidates = responseKeyCandidates(fieldName, toArgMap(args));
+	let key = candidates[0];
+	for (const candidate of candidates) if (runtime.cache.getField(ref, candidate).status === "ready") {
+		key = candidate;
+		break;
+	}
+	const tracker = binding.tracker ?? currentTracker;
+	if (tracker) try {
+		tracker.add(runtime.cache.fieldTrackingKey(runtime.cache.recordKey(ref), key));
+	} catch {}
+	const raw = runtime.readField(ref, key);
+	const childTrail = [...state.trail, {
+		name: fieldName,
+		...args ? { args } : {}
+	}];
+	return wrap(binding, raw, fieldDef?.type, childTrail);
+}
+/** Wrap a raw cache value as a child proxy (object), array of proxies (list), or scalar. */
+function wrap(binding, value, declaredType, trail) {
+	if (Array.isArray(value)) return value.map((item) => wrap(binding, item, declaredType, trail));
+	if (isGraphRef(value)) return createGraphProxy(binding, value, value.__typename ?? declaredType ?? "Unknown", trail);
+	return value;
+}
+const handler = {
+	get(target, prop) {
+		const { state } = target;
+		if (prop === GRAPH_REF) return state.ref;
+		if (prop === GRAPH_TYPE) return state.type;
+		if (prop === GRAPH_TRAIL) return state.trail;
+		if (prop === "selection") return {
+			ref: state.ref,
+			type: state.type
+		};
+		if (typeof prop === "symbol") return void 0;
+		if (prop === "__typename") return state.ref.__typename ?? readField(state, "__typename");
+		const fieldName = prop;
+		const fieldDef = state.binding.schema.getField(state.type, fieldName);
+		if (fieldDef?.args && fieldDef.args.length > 0) return (args) => readField(state, fieldName, args);
+		return readField(state, fieldName);
+	},
+	has(target, prop) {
+		if (prop === GRAPH_REF || prop === GRAPH_TYPE || prop === GRAPH_TRAIL || prop === "selection") return true;
+		return typeof prop === "string" && !!target.state.binding.schema.getField(target.state.type, prop);
+	},
+	set() {
+		throw new Error("graph values are read-only");
+	},
+	ownKeys() {
+		return [];
+	}
+};
+function createGraphProxy(binding, ref, type, trail = []) {
+	return new Proxy({ state: {
+		binding,
+		ref,
+		type,
+		trail
+	} }, handler);
+}
+/** Read the hidden selection token off any graph proxy. */
+function selectionOf(value) {
+	if (value && typeof value === "object" && GRAPH_REF in value) {
+		const v = value;
+		return {
+			ref: v[GRAPH_REF],
+			type: v[GRAPH_TYPE]
+		};
+	}
+}
+/** Read the root→value path off any graph proxy (for `usePaginated`/`fetchMore`). */
+function trailOf(value) {
+	if (value && typeof value === "object" && GRAPH_TRAIL in value) return value[GRAPH_TRAIL];
+}
+function bindGraph(options) {
+	const binding = {
+		schema: options.schema,
+		getRuntime: options.getRuntime,
+		...options.tracker ? { tracker: options.tracker } : {}
+	};
+	const queryType = options.schema.queryType;
+	const rootFields = options.schema.getType(queryType)?.fields ?? {};
+	const graph = {};
+	for (const [fieldName, fieldDef] of Object.entries(rootFields)) graph[fieldName] = (args) => {
+		const seeded = (typeof options.roots === "function" ? options.roots() : options.roots)?.[fieldName];
+		const trail = [{
+			name: fieldName,
+			...args ? { args } : {}
+		}];
+		if (fieldDef.list) return (Array.isArray(seeded) ? seeded : []).map((item) => wrap(binding, item, fieldDef.type, trail));
+		return createGraphProxy(binding, isGraphRef(seeded) ? seeded : { path: `${queryType}.${fieldName}(${canonicalArgs(toArgMap(args))})` }, fieldDef.type, trail);
+	};
+	return graph;
+}
+//#endregion
+//#region src/cache-resolve.ts
+/**
+* Cache-first resolution.
+*
+* Before executing an operation over the network, check whether the normalized
+* cache already satisfies its entire selection. The link from a root call to its
+* entity (`product(handle:"x") -> Product:123`) is persisted under the root
+* record, so a re-run, a back-navigation, or data another writer already filled
+* (mutation, subscription, sibling query) resolves with zero requests. Coverage
+* is all-or-nothing here; partial gaps fall back to a full fetch (a future
+* `node(id:)` patch could fetch only the missing fields).
+*/
+const ROOT = "Query";
+function resolveArg(v, vars) {
+	if (v.kind === "var") return {
+		kind: "literal",
+		value: vars[v.name] ?? null
+	};
+	if (v.kind === "list") return {
+		kind: "list",
+		items: v.items.map((i) => resolveArg(i, vars))
+	};
+	if (v.kind === "object") return {
+		kind: "object",
+		fields: v.fields.map(([k, fv]) => [k, resolveArg(fv, vars)])
+	};
+	return v;
+}
+/** Stable per-root-call key (`product(handle:"x")`), with operation variables substituted. */
+function rootLinkKey(field, vars) {
+	const resolved = (field.args ?? []).map(([k, v]) => [k, resolveArg(v, vars)]);
+	return `${field.name}(${canonicalArgs(resolved)})`;
+}
+/** Record each root field's resolved ref so a later run finds the entity without a fetch. */
+function persistRootLinks(cache, selection, vars, roots, rootPath = ROOT) {
+	const rec = { path: rootPath };
+	for (const field of selection.fields) {
+		const key = responseKey(field);
+		if (key in roots) cache.setField(rec, rootLinkKey(field, vars), roots[key]);
+	}
+}
+/** Does `ref`'s record cover every field in `selection` (recursively)? */
+function covers(cache, ref, selection) {
+	for (const field of selection.fields) {
+		const got = cache.getField(ref, responseKey(field));
+		if (got.status !== "ready") return false;
+		if (field.selection && !coversValue(cache, got.value, field.selection)) return false;
+	}
+	for (const frag of selection.inlineFragments ?? []) if (ref.__typename === frag.onType && !covers(cache, ref, frag.selection)) return false;
+	return true;
+}
+function coversValue(cache, value, selection) {
+	if (value == null) return true;
+	if (Array.isArray(value)) return value.every((v) => coversValue(cache, v, selection));
+	if (isGraphRef(value)) return covers(cache, value, selection);
+	return true;
+}
+/**
+* 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.
+*/
+function resolveFromCache(cache, selection, vars, rootPath = ROOT) {
+	const rec = { path: rootPath };
+	const roots = {};
+	for (const field of selection.fields) {
+		const link = cache.getField(rec, rootLinkKey(field, vars));
+		if (link.status !== "ready") return {
+			covered: false,
+			roots: {}
+		};
+		const ref = link.value;
+		if (ref == null) {
+			roots[responseKey(field)] = null;
+			continue;
+		}
+		if (field.selection && (!isGraphRef(ref) || !covers(cache, ref, field.selection))) return {
+			covered: false,
+			roots: {}
+		};
+		roots[responseKey(field)] = ref;
+	}
+	return {
+		covered: true,
+		roots
+	};
+}
+//#endregion
+//#region src/route.ts
+/** Execute a compiled operation and seed the runtime cache (steps 2–5 of the route flow). */
+async function runRoute(args) {
+	const variables = args.operation.variables(args.routeContext);
+	const selection = args.operation.selection;
+	if ((args.options?.cacheFirst ?? true) && selection) {
+		const hit = resolveFromCache(args.runtime.cache, selection, variables);
+		if (hit.covered) return {
+			variables,
+			roots: hit.roots
+		};
+	}
+	const result = await args.adapter.execute({
+		name: args.operation.name,
+		kind: args.operation.kind,
+		document: args.operation.document
+	}, variables, args.context);
+	const roots = result.data ? args.runtime.seedResult(result.data) : {};
+	if (selection && result.data) persistRootLinks(args.runtime.cache, selection, variables, roots);
+	return {
+		variables,
+		roots,
+		errors: result.errors
+	};
+}
+/**
+* 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.
+*/
+function refetch(args) {
+	return runRoute({
+		...args,
+		options: { cacheFirst: false }
+	});
+}
+//#endregion
+//#region src/scope.ts
+var GraphScope = class {
+	singleton;
+	als;
+	constructor(als) {
+		this.als = als;
+	}
+	/**
+	* 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) {
+		this.als = als;
+	}
+	/** The active graph, or throw a clear error if read outside any scope. */
+	current() {
+		const active = this.als?.getStore() ?? this.singleton;
+		if (!active) throw new Error("No active graph runtime. On the server wrap rendering in scope.run(active, fn); on the client call scope.set(active) after hydration.");
+		return active;
+	}
+	/** Run `fn` with `active` as the request-scoped runtime (server). */
+	run(active, fn) {
+		if (this.als) return this.als.run(active, fn);
+		const prev = this.singleton;
+		this.singleton = active;
+		try {
+			return fn();
+		} finally {
+			this.singleton = prev;
+		}
+	}
+	/** Install the active graph as a singleton (client, post-hydration). */
+	set(active) {
+		this.singleton = active;
+	}
+};
+/**
+* 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());
+* ```
+*/
+function bindScope(als) {
+	const scope = new GraphScope(als);
+	return {
+		scope,
+		activeGraph: () => scope.current()
+	};
+}
+//#endregion
+//#region src/mutation.ts
+/**
+* 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`).
+*/
+var MutationTransaction = class {
+	cache;
+	undo = [];
+	constructor(cache) {
+		this.cache = cache;
+	}
+	/** Optimistically write a field, remembering how to undo it. */
+	set(ref, fieldKey, value) {
+		const before = this.cache.getField(ref, fieldKey);
+		if (before.status === "ready") {
+			const prev = before.value;
+			this.undo.push(() => this.cache.setField(ref, fieldKey, prev));
+		} else this.undo.push(() => this.cache.invalidateField(ref, fieldKey));
+		this.cache.setField(ref, fieldKey, value);
+	}
+	/** Roll back every write in reverse order. */
+	rollback() {
+		for (let i = this.undo.length - 1; i >= 0; i--) this.undo[i]();
+		this.undo.length = 0;
+	}
+};
+/**
+* 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`.
+*/
+async function runMutation(options) {
+	const { runtime, adapter, context, variables } = options;
+	const tx = new MutationTransaction(runtime.cache);
+	if (options.optimistic) options.optimistic(tx);
+	let result;
+	try {
+		result = await adapter.execute({
+			name: options.operation.name,
+			kind: "mutation",
+			document: options.operation.document
+		}, variables, context);
+	} catch (error) {
+		tx.rollback();
+		return {
+			userErrors: [],
+			errors: [{ message: errorMessage(error) }],
+			ok: false
+		};
+	}
+	if (result.errors && result.errors.length > 0) {
+		tx.rollback();
+		return {
+			userErrors: [],
+			errors: result.errors,
+			ok: false
+		};
+	}
+	const data = result.data;
+	const userErrors = data ? extractUserErrors(data) : [];
+	if (userErrors.length > 0) {
+		tx.rollback();
+		return {
+			data,
+			userErrors,
+			ok: false
+		};
+	}
+	if (data) runtime.seedResult(data);
+	if (options.update && data) options.update(data, tx);
+	if (options.invalidate && data) for (const target of options.invalidate(data)) {
+		const ref = toRef(target);
+		if (ref) runtime.invalidate(ref);
+	}
+	return {
+		data,
+		userErrors: [],
+		ok: true
+	};
+}
+/** Invalidate a record by graph value (proxy) or raw ref — next read re-fetches. */
+function invalidateValue(runtime, value) {
+	const ref = toRef(value);
+	if (ref) runtime.invalidate(ref);
+}
+/** Collect `userErrors` from each top-level mutation payload in the result. */
+function extractUserErrors(data) {
+	const out = [];
+	for (const value of Object.values(data)) if (value && typeof value === "object" && !Array.isArray(value)) {
+		const ue = value.userErrors;
+		if (Array.isArray(ue)) {
+			for (const e of ue) if (e && typeof e === "object") out.push(e);
+		}
+	}
+	return out;
+}
+function toRef(value) {
+	const selection = selectionOf(value);
+	if (selection) return selection.ref;
+	if (value && typeof value === "object") {
+		const v = value;
+		if (v.__typename != null && v.id != null || typeof v.path === "string") return v;
+	}
+}
+/** One rule for stringifying unknown errors, shared across hooks and transports. */
+function errorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+//#endregion
+//#region src/mutator.ts
+function createMutator(options) {
+	const mutate = {};
+	for (const [name, operation] of Object.entries(options.operations)) {
+		if (operation.kind !== "mutation") continue;
+		const mutationOp = {
+			name: operation.name,
+			kind: "mutation",
+			document: operation.document
+		};
+		mutate[name] = (variables, opts) => runMutation({
+			operation: mutationOp,
+			variables,
+			adapter: options.adapter,
+			context: options.context,
+			runtime: options.runtime,
+			...opts
+		});
+	}
+	return mutate;
+}
+//#endregion
+//#region src/context.ts
+/**
+* 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`).
+*/
+function buildRouteContext(requestInfo, options = {}) {
+	const url = new URL(requestInfo.request.url);
+	return {
+		...options.context?.(requestInfo) ?? {},
+		params: requestInfo.params,
+		search: url.searchParams,
+		request: requestInfo.request
+	};
+}
+//#endregion
+//#region src/integration.ts
+/**
+* RedwoodSDK integration.
+*
+* Answers the four questions the brief asks of a framework adapter:
+*  - Which operation drives this entrypoint?  -> `resolveOperationName` / explicit name
+*  - How do we read params/search/request/env? -> `buildRouteContext`
+*  - How do we preload + seed?                 -> `runRoute` into a fresh per-request cache
+*  - How do we expose the graph to components? -> attach a bound graph to `ctx`
+*
+* Per request: pick the operation, compute variables, execute via the client
+* adapter, seed a fresh cache, and attach `{ runtime, graph, ... }` to
+* `requestInfo.ctx` so Pages/components read graph fields with cache hits. Unseeded
+* (lazy) fields fall through to the Suspense runtime.
+*/
+const CTX_KEY = "__graph";
+function createGraphIntegration(options) {
+	const keyOf = (typename, obj) => options.schema.identityOf(typename, obj);
+	function makeRuntime(requestContext) {
+		return new GraphRuntime({
+			keyOf,
+			unexpectedMissingField: options.unexpectedMissingField,
+			onWarn: options.onWarn,
+			fetchMissing: async (misses) => options.fetchMissing ? options.fetchMissing(misses, requestContext) : missesUnresolved(misses)
+		});
+	}
+	async function preload(requestInfo, operationName) {
+		const name = operationName ?? options.resolveOperationName?.(requestInfo);
+		const operation = name ? options.operations[name] : void 0;
+		if (!operation) return void 0;
+		const requestContext = buildRouteContext(requestInfo, options);
+		const runtime = makeRuntime(requestContext);
+		const { variables, roots, errors } = await runRoute({
+			operation,
+			routeContext: requestContext,
+			adapter: options.adapter,
+			context: requestContext,
+			runtime
+		});
+		const active = {
+			runtime,
+			graph: bindGraph({
+				schema: options.schema,
+				getRuntime: () => runtime,
+				roots
+			}),
+			mutate: createMutator({
+				operations: options.operations,
+				adapter: options.adapter,
+				runtime,
+				context: requestContext
+			}),
+			roots,
+			operation,
+			variables,
+			requestContext,
+			...errors ? { errors } : {}
+		};
+		requestInfo.ctx[CTX_KEY] = active;
+		return active;
+	}
+	function getActive(requestInfo) {
+		return requestInfo.ctx[CTX_KEY];
+	}
+	async function refetch(requestInfo, operationName) {
+		const active = getActive(requestInfo);
+		if (!active) return;
+		const operation = options.operations[operationName ?? active.operation.name];
+		if (!operation) return;
+		await runRoute({
+			operation,
+			routeContext: active.requestContext,
+			adapter: options.adapter,
+			context: active.requestContext,
+			runtime: active.runtime,
+			options: { cacheFirst: false }
+		});
+	}
+	function getGraph(requestInfo) {
+		const active = getActive(requestInfo);
+		if (!active) throw new Error("No graph attached to this request. Call integration.preload(requestInfo) before rendering (e.g. in a middleware or at the top of the Page).");
+		return active.graph;
+	}
+	function getMutator(requestInfo) {
+		const active = getActive(requestInfo);
+		if (!active) throw new Error("No graph attached to this request. Call integration.preload(requestInfo) first.");
+		return active.mutate;
+	}
+	function invalidate(requestInfo, value) {
+		const active = getActive(requestInfo);
+		if (active) invalidateValue(active.runtime, value);
+	}
+	function runInScope(requestInfo, fn) {
+		const active = getActive(requestInfo);
+		if (!active || !options.scope) return fn();
+		return options.scope.run({
+			runtime: active.runtime,
+			graph: active.graph
+		}, fn);
+	}
+	return {
+		preload,
+		getGraph,
+		getMutator,
+		invalidate,
+		getActive,
+		refetch,
+		runInScope
+	};
+}
+/** Default missing-field resolution: leave each miss undefined (hybrid allow/warn). */
+function missesUnresolved(misses) {
+	return misses.map((m) => ({
+		ref: m.ref,
+		fieldKey: m.fieldKey,
+		value: void 0
+	}));
+}
+//#endregion
+//#region src/serialize.ts
+/** Build the JSON-safe hydration payload from an active request. */
+function serializeGraph(active, options = {}) {
+	const allow = new Set(options.clientSafeContext ?? []);
+	const context = {};
+	for (const key of allow) if (key in active.requestContext) context[key] = active.requestContext[key];
+	return {
+		operationName: active.operation.name,
+		variables: active.variables,
+		snapshot: active.runtime.snapshot(),
+		roots: active.roots,
+		context
+	};
+}
+const DEFAULT_GLOBAL = "__GRAPH_STATE__";
+/**
+* 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).
+*/
+function renderGraphHydrationScript(payload, options = {}) {
+	return `<script${options.nonce ? ` nonce="${options.nonce}"` : ""}>${graphHydrationScriptContent(payload, options.globalKey)}<\/script>`;
+}
+/**
+* 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.
+*/
+function graphHydrationScriptContent(payload, globalKey = DEFAULT_GLOBAL) {
+	const json = JSON.stringify(payload).replace(/</g, "\\u003c").replace(/>/g, "\\u003e").replace(/&/g, "\\u0026").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
+	return `window[${JSON.stringify(globalKey)}]=${json}`;
+}
+/** Read the hydration payload published by `renderGraphHydrationScript` (client). */
+function readGraphHydrationPayload(globalKey = DEFAULT_GLOBAL) {
+	return globalThis[globalKey];
+}
+/**
+* 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.
+*/
+function hydrateGraph(payload, options) {
+	const runtime = GraphRuntime.hydrate(payload.snapshot, {
+		keyOf: (typename, obj) => options.schema.identityOf(typename, obj),
+		unexpectedMissingField: options.unexpectedMissingField,
+		onWarn: options.onWarn,
+		fetchMissing: async (misses) => options.fetchMissing ? options.fetchMissing(misses, payload.context) : misses.map((m) => ({
+			ref: m.ref,
+			fieldKey: m.fieldKey,
+			value: void 0
+		}))
+	});
+	const graph = bindGraph({
+		schema: options.schema,
+		getRuntime: () => runtime,
+		roots: payload.roots
+	});
+	const active = {
+		runtime,
+		graph,
+		roots: payload.roots,
+		context: payload.context
+	};
+	options.scope?.set({
+		runtime,
+		graph
+	});
+	return active;
+}
+/**
+* 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.
+*/
+function absorbHydrationPayload(runtime, payload) {
+	return runtime.absorbRecords(payload.snapshot);
+}
+/** Derive the current-page pointer from a payload (drives `refresh()`). */
+function pagePointer(payload) {
+	return {
+		operationName: payload.operationName,
+		variables: payload.variables,
+		context: payload.context,
+		roots: payload.roots
+	};
+}
+//#endregion
+//#region src/adapter-ws.ts
+function toErrors(error) {
+	if (Array.isArray(error)) return error.map((e) => ({ message: String(e?.message ?? e) }));
+	if (error instanceof Error) return [{ message: error.message }];
+	if (error && typeof error === "object" && "reason" in error) return [{ message: String(error.reason) || "subscription socket closed" }];
+	return [{ message: String(error) }];
+}
+function createGraphWsAdapter(options) {
+	const { client } = options;
+	const payloadFor = (operation, variables, context) => {
+		const extensions = options.extensions?.(context);
+		return {
+			query: operation.document,
+			variables: variables ?? {},
+			operationName: operation.name,
+			...extensions && Object.keys(extensions).length > 0 ? { extensions } : {}
+		};
+	};
+	return {
+		execute(operation, variables, context) {
+			return new Promise((resolve) => {
+				let settled = false;
+				let dispose;
+				const settle = (r) => {
+					if (settled) return;
+					settled = true;
+					resolve(r);
+					dispose?.();
+				};
+				dispose = client.subscribe(payloadFor(operation, variables, context), {
+					next: (value) => settle(value),
+					error: (error) => settle({ errors: toErrors(error) }),
+					complete: () => settle({})
+				});
+				if (settled) dispose?.();
+			});
+		},
+		subscribe(operation, variables, context) {
+			return { [Symbol.asyncIterator]() {
+				let dispose;
+				const it = pushPullIterator(() => dispose?.());
+				dispose = client.subscribe(payloadFor(operation, variables, context), {
+					next: (value) => it.push(value),
+					error: (error) => {
+						it.push({ errors: toErrors(error) });
+						it.finish();
+					},
+					complete: () => it.finish()
+				});
+				return it;
+			} };
+		}
+	};
+}
+//#endregion
+//#region src/persisted.ts
+function createPersistedResolver(operations, options = {}) {
+	const byHash = /* @__PURE__ */ new Map();
+	const documents = /* @__PURE__ */ new Set();
+	for (const op of Object.values(operations)) {
+		documents.add(op.document);
+		if (op.hash) byHash.set(op.hash, op.document);
+	}
+	return (body) => {
+		const hash = body.extensions?.persistedQuery?.sha256Hash;
+		if (hash) {
+			const document = byHash.get(hash);
+			if (document) return {
+				kind: "ok",
+				document
+			};
+			if (body.query) return documents.has(body.query) || options.allowUnpersisted ? {
+				kind: "ok",
+				document: body.query
+			} : { kind: "rejected" };
+			return { kind: "not-found" };
+		}
+		if (body.query) return documents.has(body.query) || options.allowUnpersisted ? {
+			kind: "ok",
+			document: body.query
+		} : { kind: "rejected" };
+		return { kind: "rejected" };
+	};
+}
+//#endregion
+export { GRAPH_REF, GRAPH_TRAIL, GRAPH_TYPE, GraphCache, GraphRuntime, GraphScope, MutationTransaction, 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 };