foldkit-remote 0.1.0

package/dist/index.mjs

@@ -0,0 +1,2919 @@
+import { Context, Deferred, Duration, Effect, Layer, Option, Request, RequestResolver, Result, Schema, SchemaGetter, Stream } from "effect";
+import { Requirement } from "foldkit-surface";
+import { Rpc, RpcGroup } from "effect/unstable/rpc";
+import { KeyValueStore } from "effect/unstable/persistence";
+//#region src/store.ts
+/**
+* The pure entity store: values, per-field presence, staleness, and tombstones.
+*
+* Presence is tracked **separately** from values, so `undefined`/`null`/absent/
+* stale/not-found are distinct states and a missing field is never inferred from
+* `value === undefined`. Nothing here performs I/O; every operation returns a
+* new store.
+*/
+/** The separator keeps an untrusted id from colliding with a prototype key. */
+const entityKey = (entity, id) => `${entity}:${id}`;
+const emptyEntry = {
+	values: {},
+	present: /* @__PURE__ */ new Set(),
+	stale: /* @__PURE__ */ new Set(),
+	tombstone: false,
+	updatedAt: 0,
+	windows: {}
+};
+const emptyStore = {};
+const replace = (store, key, entry) => ({
+	...store,
+	[key]: entry
+});
+const written = (previous, values, now, windows) => {
+	const present = new Set(previous.present);
+	const stale = new Set(previous.stale);
+	const nextWindows = { ...previous.windows };
+	for (const field of Object.keys(values)) {
+		present.add(field);
+		stale.delete(field);
+		const requested = windows?.[field];
+		if (requested !== void 0 && requested !== "") nextWindows[field] = requested;
+		else delete nextWindows[field];
+	}
+	return {
+		values: {
+			...previous.values,
+			...values
+		},
+		present,
+		stale,
+		tombstone: false,
+		updatedAt: now,
+		windows: nextWindows
+	};
+};
+/**
+* Merges known values into many entities, copying the store once. Every
+* written field becomes present and non-stale; a tombstone is cleared because
+* the entity is evidently not absent.
+*/
+const writeEntities = (store, writes, now = 0) => {
+	if (writes.length === 0) return store;
+	const next = { ...store };
+	for (const write of writes) next[write.key] = written(next[write.key] ?? emptyEntry, write.values, now, write.windows);
+	return next;
+};
+/** `writeEntities` for one entity. */
+const writeEntity = (store, key, values, now = 0, windows) => writeEntities(store, [{
+	key,
+	values,
+	windows
+}], now);
+/**
+* Marks present fields stale (`true`) or ends their staleness (`false`) across
+* many entities, copying the store once. A field never present stays missing;
+* an unknown entity is left alone.
+*/
+const setStale = (store, marks, stale) => {
+	let next;
+	for (const [key, fields] of marks) {
+		const previous = (next ?? store)[key];
+		if (previous === void 0) continue;
+		const staleFields = new Set(previous.stale);
+		for (const field of fields) if (stale) {
+			if (previous.present.has(field)) staleFields.add(field);
+		} else staleFields.delete(field);
+		next ??= { ...store };
+		next[key] = {
+			...previous,
+			stale: staleFields
+		};
+	}
+	return next ?? store;
+};
+/** Marks present fields stale; fields that were never present stay missing. */
+const markStale = (store, key, fields) => setStale(store, [[key, fields]], true);
+/** Ends a refresh that did not land: the fields are present again as they were. */
+const clearStale = (store, key, fields) => setStale(store, [[key, fields]], false);
+/** Records that the entity is known to be absent, so it is not refetched. */
+const tombstone = (store, key) => replace(store, key, {
+	values: {},
+	present: /* @__PURE__ */ new Set(),
+	stale: /* @__PURE__ */ new Set(),
+	tombstone: true,
+	updatedAt: 0,
+	windows: {}
+});
+/** Forgets everything known about the entity, including a tombstone. */
+const remove = (store, key) => {
+	if (store[key] === void 0) return store;
+	const next = { ...store };
+	delete next[key];
+	return next;
+};
+const entry = (store, key) => {
+	const value = store[key];
+	return value === void 0 ? Option.none() : Option.some(value);
+};
+const isTombstone = (store, key) => store[key]?.tombstone === true;
+/** A field is known only if it is present and not stale. */
+const hasField = (store, key, field) => {
+	const value = store[key];
+	return value !== void 0 && !value.tombstone && value.present.has(field) && !value.stale.has(field);
+};
+/** A present field whose value may be outdated; absent fields are not stale. */
+const isFieldStale = (store, key, field) => {
+	const value = store[key];
+	return value !== void 0 && !value.tombstone && value.stale.has(field);
+};
+/**
+* Reads a present field, stale or not. Absence and a tombstone both yield
+* `Option.none()`; a present `undefined`/`null` yields `Option.some`.
+*/
+const readField = (store, key, field) => {
+	const value = store[key];
+	if (value === void 0 || value.tombstone || !value.present.has(field)) return Option.none();
+	return Option.some(value.values[field]);
+};
+/**
+* The fields the planner must fetch. A tombstone makes every field known
+* (absent), so it returns an empty list and the entity is not refetched. A
+* requested window that differs from the one a field was fetched with also
+* marks it missing, but only when the stored window is known (never `""`), so a
+* writer that does not record windows cannot cause a refetch loop.
+*/
+const missingFields = (store, key, fields, windows) => {
+	const value = store[key];
+	if (value !== void 0 && value.tombstone) return [];
+	return [...fields].filter((field) => {
+		if (value === void 0 || !value.present.has(field) || value.stale.has(field)) return true;
+		const requested = windows?.[field];
+		const stored = value.windows[field];
+		return requested !== void 0 && stored !== void 0 && stored !== "" && stored !== requested;
+	});
+};
+//#endregion
+//#region src/mutation.ts
+/**
+* Mutation status and idempotent reconciliation.
+*
+* A mutation result is reconciled into the store **at most once per
+* `requestId`**, so a transport retry cannot apply the same change twice. An
+* unknown or already-applied result is a no-op.
+*/
+const emptyMutationState = {
+	pending: /* @__PURE__ */ new Set(),
+	applied: /* @__PURE__ */ new Set(),
+	failed: /* @__PURE__ */ new Set(),
+	sequence: 0
+};
+/**
+* How many settled request ids a mutation state retains. A retry settles well
+* inside this window, so bounding the ledger stops a long-lived application
+* from growing it without limit; a retry older than the window would re-apply
+* its entities.
+*/
+const MUTATION_ID_WINDOW = 1024;
+/** Records `id` as most recent, evicting the oldest once the window is full. */
+const remember = (ids, id) => {
+	const next = new Set(ids);
+	next.delete(id);
+	next.add(id);
+	if (next.size <= MUTATION_ID_WINDOW) return next;
+	return new Set([...next].slice(next.size - MUTATION_ID_WINDOW));
+};
+const beginMutation = (state, requestId) => ({
+	...state,
+	pending: /* @__PURE__ */ new Set([...state.pending, requestId]),
+	sequence: state.sequence + 1
+});
+const failMutation = (state, requestId) => {
+	const pending = new Set(state.pending);
+	pending.delete(requestId);
+	return {
+		...state,
+		pending,
+		failed: remember(state.failed, requestId)
+	};
+};
+/**
+* Applies a mutation result once and marks the request settled. A second call
+* with the same `requestId` (a retry, or a live event describing the same change)
+* does not re-apply the entities, but still clears `pending`.
+*/
+const reconcileMutation = (store, state, requestId, entities) => {
+	const next = state.applied.has(requestId) ? store : entities.reduce((current, entity) => writeEntity(current, entityKey(entity.entity, entity.id), entity.values), store);
+	const applied = remember(state.applied, requestId);
+	const pending = new Set(state.pending);
+	pending.delete(requestId);
+	return {
+		store: next,
+		state: {
+			...state,
+			applied,
+			pending
+		}
+	};
+};
+/** The codec itself, or a `Schema.Struct` over the fields. */
+const schemaOf = (shape) => Schema.isSchema(shape) ? shape : Schema.Struct(shape);
+const Mutation = { 
+/**
+* Declares a mutation. `Input` and `Output` are codecs, or the fields of the
+* `Schema.Struct` they would be (`{ id: ProjectId, name: Schema.String }`).
+*/
+make: (name, config) => ({
+	name,
+	Input: schemaOf(config.Input),
+	Output: schemaOf(config.Output)
+}) };
+//#endregion
+//#region src/query.ts
+/**
+* Queries and connections. A connection's identity is its descriptor plus the
+* canonical encoded filter/sort input — **never** the pagination window, so
+* `first(25)` and `after(cursor).first(25)` address the same logical connection.
+*/
+/** Stable stringify: object keys sorted, undefined-valued keys dropped, so equal inputs encode equally. */
+const stableStringify = (value) => {
+	if (value === void 0) return "null";
+	if (value === null || typeof value !== "object") return JSON.stringify(value);
+	if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+	const record = value;
+	return `{${Object.keys(record).filter((key) => record[key] !== void 0).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`).join(",")}}`;
+};
+const isEntityName = (result) => typeof result === "object" && result !== null && typeof result.name === "string";
+const Query = {
+	/** Declares the entity and options a query's result is a connection over. */
+	connection: (entity, options) => ({
+		entity: entity.name,
+		...options?.edgeKey === void 0 ? {} : { edgeKey: options.edgeKey },
+		...options?.live === void 0 ? {} : { live: options.live }
+	}),
+	/**
+	* Declares a query. `Input` is a codec or the fields of the `Schema.Struct` it
+	* would be; `Result` is a `Query.connection(...)`, or the entity the result is
+	* a connection over.
+	*/
+	make: (name, config) => {
+		const Input = schemaOf(config.Input);
+		const encode = Schema.encodeSync(Input);
+		return {
+			name,
+			Input,
+			Result: isEntityName(config.Result) ? Query.connection(config.Result) : config.Result,
+			ref: (input) => ({
+				query: name,
+				input,
+				Input,
+				window: {},
+				identity: `${name}\u0000${stableStringify(encode(input))}`
+			})
+		};
+	},
+	first: (count) => (ref) => ({
+		...ref,
+		window: {
+			...ref.window,
+			first: count
+		}
+	}),
+	last: (count) => (ref) => ({
+		...ref,
+		window: {
+			...ref.window,
+			last: count
+		}
+	}),
+	after: (cursor) => (ref) => ({
+		...ref,
+		window: {
+			...ref.window,
+			after: cursor
+		}
+	}),
+	before: (cursor) => (ref) => ({
+		...ref,
+		window: {
+			...ref.window,
+			before: cursor
+		}
+	})
+};
+//#endregion
+//#region src/wire.ts
+/**
+* The Remote wire: Effect RPC semantics over `effect/unstable/rpc`. Remote owns
+* the message shapes; Effect owns the transport. `Make`ing reads batch, mutations
+* preserve order, and live data is a stream.
+*/
+/**
+* The read/live protocol version. A batch names the version it speaks and the
+* server refuses a mismatch with `RemoteProtocolError`, so a shape change never
+* drifts silently: bump it whenever `ReadRequest` or `LiveRequirement` change.
+*/
+const REMOTE_PROTOCOL_VERSION = 3;
+var RemoteReadError = class extends Schema.TaggedError()("RemoteReadError", { message: Schema.String }) {};
+var RemoteMutationError = class extends Schema.TaggedError()("RemoteMutationError", { message: Schema.String }) {};
+var RemoteLiveError = class extends Schema.TaggedError()("RemoteLiveError", { message: Schema.String }) {};
+/** The peer speaks another protocol version; nothing was read. */
+var RemoteProtocolError = class extends Schema.TaggedError()("RemoteProtocolError", {
+	message: Schema.String,
+	expected: Schema.Number,
+	received: Schema.Number
+}) {};
+/** A page size: a non-negative integer, refused at decode otherwise rather than defaulted. */
+const PageSize = Schema.Number.check(Schema.isInt(), Schema.isGreaterThanOrEqualTo(0));
+const WindowSchema = Schema.Struct({
+	first: Schema.optional(PageSize),
+	last: Schema.optional(PageSize),
+	after: Schema.optional(Schema.String),
+	before: Schema.optional(Schema.String)
+});
+/** A request may not name more fields of one entity than this; a selection never does. */
+const MAX_FIELDS_PER_REQUEST = 256;
+/** A selection may not nest relations deeper than this; the wire refuses more. */
+const MAX_RELATION_DEPTH = 8;
+const Fields = Schema.Array(Schema.String).check(Schema.isMaxLength(256));
+/**
+* The slice required of a relation's target; the ids come from the parent's
+* refs. Built as `MAX_RELATION_DEPTH` nested structs rather than a recursive
+* schema, so a deeper selection is refused at decode with a schema error.
+*/
+const relationLevel = (depth) => {
+	const slice = {
+		entity: Schema.String,
+		fields: Fields,
+		windows: Schema.optional(Schema.Record(Schema.String, WindowSchema))
+	};
+	return depth === 0 ? Schema.Struct({
+		...slice,
+		relations: Schema.optionalKey(Schema.Never)
+	}) : Schema.Struct({
+		...slice,
+		relations: Schema.optional(Schema.Record(Schema.String, relationLevel(depth - 1)))
+	});
+};
+const RelationRequest = relationLevel(7);
+const ReadRequest = Schema.Struct({
+	entity: Schema.String,
+	id: Schema.String,
+	fields: Fields,
+	/** Pagination window per relation field. */
+	windows: Schema.optional(Schema.Record(Schema.String, WindowSchema)),
+	/** The slice required of each relation field's target, resolved in the same read. */
+	relations: Schema.optional(Schema.Record(Schema.String, RelationRequest))
+});
+const ReadBatch = Schema.Struct({
+	version: Schema.Number,
+	requests: Schema.Array(ReadRequest)
+});
+const NormalizedEntity = Schema.Struct({
+	entity: Schema.String,
+	id: Schema.String,
+	values: Schema.Record(Schema.String, Schema.Unknown)
+});
+const ReadBatchResult = Schema.Struct({ entities: Schema.Array(NormalizedEntity) });
+const MutationRequest = Schema.Struct({
+	/** Stable across transport retries so a mutation is not applied twice. */
+	requestId: Schema.String,
+	mutation: Schema.String,
+	input: Schema.Unknown
+});
+const LiveEdge = Schema.Struct({
+	entity: Schema.String,
+	id: Schema.String,
+	key: Schema.String
+});
+/** A connection change a mutation confirms: the same facts a live event carries, without a cursor. */
+const ConnectionChangeSchema = Schema.Union([Schema.Struct({
+	_tag: Schema.Literal("Insert"),
+	connection: Schema.String,
+	position: Schema.Union([Schema.Literal("prepend"), Schema.Literal("append")]),
+	edge: LiveEdge
+}), Schema.Struct({
+	_tag: Schema.Literal("Remove"),
+	connection: Schema.String,
+	edge: LiveEdge
+})]);
+const MutationResult = Schema.Struct({
+	output: Schema.Unknown,
+	entities: Schema.Array(NormalizedEntity),
+	/** Connection changes the mutation made, applied alongside its entity patches. */
+	connections: Schema.optional(Schema.Array(ConnectionChangeSchema))
+});
+const LiveRequirement = Schema.Struct({
+	version: Schema.Number,
+	requirements: Schema.Array(ReadRequest),
+	/** Resume cursor; events at or before it are duplicates. */
+	after: Schema.Number
+});
+/**
+* A live change. Entity changes update the store; connection changes alter
+* membership and ordering; both carry a per-stream cursor.
+*/
+const LiveChange = Schema.Union([
+	Schema.Struct({
+		_tag: Schema.Literal("EntityPatched"),
+		cursor: Schema.Number,
+		entity: Schema.String,
+		id: Schema.String,
+		values: Schema.Record(Schema.String, Schema.Unknown),
+		changed: Schema.Array(Schema.String)
+	}),
+	Schema.Struct({
+		_tag: Schema.Literal("EntityDeleted"),
+		cursor: Schema.Number,
+		entity: Schema.String,
+		id: Schema.String
+	}),
+	Schema.Struct({
+		_tag: Schema.Literal("ConnectionInsert"),
+		cursor: Schema.Number,
+		connection: Schema.String,
+		position: Schema.Union([Schema.Literal("prepend"), Schema.Literal("append")]),
+		edge: LiveEdge
+	}),
+	Schema.Struct({
+		_tag: Schema.Literal("ConnectionRemove"),
+		cursor: Schema.Number,
+		connection: Schema.String,
+		edge: LiveEdge
+	}),
+	Schema.Struct({
+		_tag: Schema.Literal("ConnectionInvalidate"),
+		cursor: Schema.Number,
+		connection: Schema.String
+	})
+]);
+const Read = Rpc.make("FoldkitRemoteRead", {
+	payload: ReadBatch,
+	success: ReadBatchResult,
+	error: Schema.Union([RemoteReadError, RemoteProtocolError])
+});
+const Mutate = Rpc.make("FoldkitRemoteMutate", {
+	payload: MutationRequest,
+	success: MutationResult,
+	error: RemoteMutationError
+});
+const Live = Rpc.make("FoldkitRemoteLive", {
+	payload: LiveRequirement,
+	success: LiveChange,
+	error: Schema.Union([RemoteLiveError, RemoteProtocolError]),
+	stream: true
+});
+var RemoteQueryError = class extends Schema.TaggedError()("RemoteQueryError", { message: Schema.String }) {};
+const WireBoundary = Schema.Union([
+	Schema.Struct({ _tag: Schema.Literal("Terminal") }),
+	Schema.Struct({
+		_tag: Schema.Literal("Cursor"),
+		cursor: Schema.String
+	}),
+	Schema.Struct({ _tag: Schema.Literal("Unknown") })
+]);
+const QueryRequest = Schema.Struct({
+	query: Schema.String,
+	input: Schema.Unknown,
+	window: WindowSchema
+});
+const QueryEdge = Schema.Struct({
+	entity: Schema.String,
+	id: Schema.String,
+	key: Schema.String
+});
+const QueryResult = Schema.Struct({
+	edges: Schema.Array(QueryEdge),
+	start: WireBoundary,
+	end: WireBoundary
+});
+const QueryRpc = Rpc.make("FoldkitRemoteQuery", {
+	payload: QueryRequest,
+	success: QueryResult,
+	error: RemoteQueryError
+});
+const RemoteRpc = RpcGroup.make(Read, Mutate, QueryRpc, Live);
+//#endregion
+//#region src/coalesce.ts
+/**
+* Read coalescing: every requirement a client asks for goes through one
+* `RequestResolver`, so requirements issued together become one `ReadBatch`
+* (ids batched, fields unioned) and a requirement already in flight is joined
+* rather than re-requested. The planner stays pure; this is the transport
+* seam's concern, and the store is still the only cache.
+*/
+/** A stable key for a requirement, so an equal requirement in flight is joined. */
+const requirementKey = (requirement) => stableStringify([
+	requirement.entity,
+	requirement.id,
+	[...requirement.fields].sort(),
+	requirement.windows ?? null,
+	requirement.relations ?? null
+]);
+/** Whether a requirement pages a relation anywhere in its graph. */
+const hasWindows = (requirement) => requirement.windows !== void 0 || Object.values(requirement.relations ?? {}).some(hasWindows);
+/**
+* The reads a batch runs. Requirements that page nothing union into one read
+* per entity and id, and every waiter may write its whole result, since
+* plain values are the same whoever asked. A requirement that pages a
+* relation reads alone: a page answers exactly one window, and a waiter
+* cannot tell which of two pages for the same entity was its own.
+*/
+const readsOf = (owned) => {
+	const plain = [...owned].filter(([, requirement]) => !hasWindows(requirement));
+	const paged = [...owned].filter(([, requirement]) => hasWindows(requirement));
+	return [...plain.length === 0 ? [] : [{
+		keys: plain.map(([key]) => key),
+		requests: Requirement.merge(plain.map(([, requirement]) => requirement))
+	}], ...paged.map(([key, requirement]) => ({
+		keys: [key],
+		requests: [requirement]
+	}))];
+};
+var QueryRead = class extends Request.Class {};
+/**
+* Wraps a raw query so that an identical query in flight (same query, input,
+* and window) is joined rather than run again; distinct queries run
+* concurrently. A page answers exactly one window, so nothing is batched.
+*/
+const coalesceQueries = (query, options = {}) => Effect.gen(function* () {
+	const runAll = (entries) => Effect.gen(function* () {
+		const distinct = /* @__PURE__ */ new Map();
+		for (const entry of entries) distinct.set(entry.request.key, entry.request.request);
+		const results = /* @__PURE__ */ new Map();
+		yield* Effect.forEach(distinct, ([key, request]) => Effect.exit(query(request)).pipe(Effect.map((exit) => void results.set(key, exit))), {
+			concurrency: "unbounded",
+			discard: true
+		});
+		for (const entry of entries) yield* Request.completeEffect(entry, results.get(entry.request.key));
+	});
+	let resolver = RequestResolver.make(runAll);
+	if (options.window !== void 0) resolver = RequestResolver.setDelay(resolver, Duration.fromInputUnsafe(options.window));
+	return (request) => Effect.request(new QueryRead({
+		key: stableStringify([
+			request.query,
+			request.input,
+			request.window
+		]),
+		request
+	}), resolver);
+});
+var ReadRequirement = class extends Request.Class {};
+/**
+* Wraps a raw batch read so that requirements are batched and deduplicated.
+* Every waiter receives the whole batch result; `Remote.writeRead` is
+* idempotent, so writing it more than once is harmless.
+*/
+const coalesceReads = (read, options = {}) => Effect.gen(function* () {
+	const inFlight = /* @__PURE__ */ new Map();
+	const runAll = (entries) => Effect.gen(function* () {
+		const joins = /* @__PURE__ */ new Map();
+		const own = /* @__PURE__ */ new Map();
+		for (const entry of entries) {
+			const key = entry.request.key;
+			if (joins.has(key)) continue;
+			const existing = inFlight.get(key);
+			if (existing !== void 0) {
+				joins.set(key, existing);
+				continue;
+			}
+			const deferred = yield* Deferred.make();
+			inFlight.set(key, deferred);
+			own.set(key, deferred);
+			joins.set(key, deferred);
+		}
+		if (own.size > 0) {
+			const owned = /* @__PURE__ */ new Map();
+			for (const entry of entries) if (own.has(entry.request.key)) owned.set(entry.request.key, entry.request.requirement);
+			yield* Effect.forEach(readsOf(owned), ({ keys, requests }) => Effect.gen(function* () {
+				const exit = yield* Effect.exit(read({
+					version: 3,
+					requests
+				}));
+				for (const key of keys) {
+					inFlight.delete(key);
+					yield* Deferred.done(own.get(key), exit);
+				}
+			}), {
+				concurrency: "unbounded",
+				discard: true
+			});
+		}
+		for (const entry of entries) yield* Request.completeEffect(entry, Deferred.await(joins.get(entry.request.key)));
+	});
+	let resolver = RequestResolver.make(runAll);
+	if (options.window !== void 0) resolver = RequestResolver.setDelay(resolver, Duration.fromInputUnsafe(options.window));
+	return (batch) => batch.requests.length === 0 ? Effect.succeed({ entities: [] }) : Effect.forEach(batch.requests, (requirement) => Effect.request(new ReadRequirement({
+		key: requirementKey(requirement),
+		requirement
+	}), resolver), { concurrency: "unbounded" }).pipe(Effect.map((results) => ({ entities: [...new Set(results)].flatMap((result) => result.entities) })));
+});
+//#endregion
+//#region src/client.ts
+/**
+* The transport seam: the `RemoteClient` Effect service, the RPC client it is
+* built from, the wire-to-client reconstructions, and the mutation call.
+*/
+/**
+* The transport boundary. `foldkit-remote` never talks to a transport directly;
+* it depends on this Effect service, which a later phase wires to Effect RPC.
+*/
+var RemoteClient = class extends Context.Service()("foldkit-remote/RemoteClient") {};
+/** Reconstructs the client's `ConnectionChange` from the wire's flattened edge. */
+const connectionChangeOf = (change) => {
+	const edge = {
+		key: change.edge.key,
+		ref: {
+			entity: change.edge.entity,
+			id: change.edge.id
+		}
+	};
+	return change._tag === "Insert" ? {
+		_tag: "Insert",
+		connection: change.connection,
+		position: change.position,
+		edge
+	} : {
+		_tag: "Remove",
+		connection: change.connection,
+		edge
+	};
+};
+/** Reconstructs the client's `LiveEvent` from the wire's flattened `LiveChange`. */
+const liveEventOf = (change) => {
+	switch (change._tag) {
+		case "EntityPatched": return {
+			_tag: "EntityPatched",
+			ref: {
+				entity: change.entity,
+				id: change.id
+			},
+			values: change.values,
+			changed: change.changed,
+			cursor: change.cursor
+		};
+		case "EntityDeleted": return {
+			_tag: "EntityDeleted",
+			ref: {
+				entity: change.entity,
+				id: change.id
+			},
+			cursor: change.cursor
+		};
+		case "ConnectionInsert": return {
+			_tag: "ConnectionInsert",
+			connection: change.connection,
+			position: change.position,
+			edge: {
+				key: change.edge.key,
+				ref: {
+					entity: change.edge.entity,
+					id: change.edge.id
+				}
+			},
+			cursor: change.cursor
+		};
+		case "ConnectionRemove": return {
+			_tag: "ConnectionRemove",
+			connection: change.connection,
+			edge: {
+				key: change.edge.key,
+				ref: {
+					entity: change.edge.entity,
+					id: change.edge.id
+				}
+			},
+			cursor: change.cursor
+		};
+		case "ConnectionInvalidate": return {
+			_tag: "ConnectionInvalidate",
+			connection: change.connection,
+			cursor: change.cursor
+		};
+	}
+};
+const remoteError = (error) => ({
+	_tag: error._tag,
+	message: error.message
+});
+const coalescedLayer = (layer, options = {}) => Layer.effect(RemoteClient, Effect.gen(function* () {
+	const client = yield* RemoteClient;
+	const read = yield* coalesceReads(client.read, options);
+	const query = yield* coalesceQueries(client.query, options);
+	return {
+		...client,
+		read,
+		query
+	};
+})).pipe(Layer.provide(layer));
+/**
+* `Remote.mutate` as a standalone effect, so `Remote.mutateInto` can reuse it
+* without the object literal referencing itself.
+*/
+const mutateRemote = Effect.fn("Remote.mutate")(function* (mutation, input, requestId) {
+	yield* Effect.annotateCurrentSpan({
+		mutation: mutation.name,
+		requestId
+	});
+	const client = yield* RemoteClient;
+	const encoded = yield* Schema.encodeUnknownEffect(mutation.Input)(input).pipe(Effect.catchTag("SchemaError", (error) => Effect.fail(new RemoteMutationError({ message: error.message }))));
+	const result = yield* client.mutate({
+		requestId,
+		mutation: mutation.name,
+		input: encoded
+	});
+	return {
+		output: yield* Schema.decodeUnknownEffect(mutation.Output)(result.output).pipe(Effect.catchTag("SchemaError", (error) => Effect.fail(new RemoteMutationError({ message: error.message })))),
+		entities: result.entities,
+		connections: (result.connections ?? []).map(connectionChangeOf)
+	};
+});
+//#endregion
+//#region src/connection.ts
+/**
+* The pure connection model: an ordered normalized structure of edges with
+* explicit known boundaries. Pages, live events, and optimistic inserts are all
+* evidence about one connection; `merge` is the single deterministic reducer and
+* performs no I/O.
+*
+* Optimistic overlays and live state arrive in later phases.
+*/
+const edge = (ref, key = entityKey(ref.entity, ref.id)) => ({
+	key,
+	ref
+});
+const terminal = { _tag: "Terminal" };
+const unknown = { _tag: "Unknown" };
+const cursor = (value) => ({
+	_tag: "Cursor",
+	cursor: value
+});
+const emptyConnection = {
+	segments: [],
+	stale: false
+};
+const segment = (edges, start, end) => ({
+	edges,
+	start,
+	end
+});
+const dedupeEdges = (edges) => {
+	const seen = /* @__PURE__ */ new Set();
+	const out = [];
+	for (const value of edges) {
+		if (seen.has(value.key)) continue;
+		seen.add(value.key);
+		out.push(value);
+	}
+	return out;
+};
+const normalize = (segment) => ({
+	...segment,
+	edges: dedupeEdges(segment.edges)
+});
+/** Longest suffix of `a` that is a prefix of `b`, matched by edge identity. */
+const overlapLength = (a, b) => {
+	const most = Math.min(a.length, b.length);
+	for (let length = most; length > 0; length--) {
+		let matches = true;
+		for (let i = 0; i < length; i++) if (a[a.length - length + i].key !== b[i].key) {
+			matches = false;
+			break;
+		}
+		if (matches) return length;
+	}
+	return 0;
+};
+const cursorJoinable = (a, b) => a._tag === "Cursor" && b._tag === "Cursor" && a.cursor === b.cursor;
+/** Joins `a` immediately before `b`, or returns `undefined` when they are not contiguous. */
+const join = (a, b) => {
+	if (cursorJoinable(a.end, b.start)) return {
+		edges: dedupeEdges([...a.edges, ...b.edges]),
+		start: a.start,
+		end: b.end
+	};
+	if (overlapLength(a.edges, b.edges) > 0) return {
+		edges: dedupeEdges([...a.edges, ...b.edges]),
+		start: a.start,
+		end: b.end
+	};
+};
+/**
+* Global by edge identity: an edge appears once per connection. Dropping a
+* shared edge from the middle of a segment would otherwise imply that its
+* surviving neighbours are adjacent, so a segment with holes is split at each
+* hole and the new inner boundaries are `Unknown`.
+*/
+const dedupeConnection = (segments) => {
+	const seen = /* @__PURE__ */ new Set();
+	const out = [];
+	for (const segmentValue of segments) {
+		const runs = [];
+		let run = [];
+		for (const edgeValue of segmentValue.edges) {
+			if (seen.has(edgeValue.key)) {
+				if (run.length > 0) {
+					runs.push(run);
+					run = [];
+				}
+				continue;
+			}
+			seen.add(edgeValue.key);
+			run.push(edgeValue);
+		}
+		if (run.length > 0) runs.push(run);
+		if (runs.length === 0) continue;
+		if (runs.length === 1) {
+			out.push({
+				...segmentValue,
+				edges: runs[0]
+			});
+			continue;
+		}
+		runs.forEach((edges, index) => {
+			out.push({
+				edges,
+				start: index === 0 ? segmentValue.start : unknown,
+				end: index === runs.length - 1 ? segmentValue.end : unknown
+			});
+		});
+	}
+	return out;
+};
+/** Adds a page to the connection, joining contiguous or overlapping segments. */
+const merge = (current, page) => {
+	const incoming = normalize(page);
+	if (incoming.edges.length === 0) return current;
+	const segments = [...current.segments.map(normalize), incoming];
+	let joined = true;
+	while (joined) {
+		joined = false;
+		outer: for (let i = 0; i < segments.length; i++) for (let j = 0; j < segments.length; j++) {
+			if (i === j) continue;
+			const result = join(segments[i], segments[j]);
+			if (result === void 0) continue;
+			segments[i] = result;
+			segments.splice(j, 1);
+			joined = true;
+			break outer;
+		}
+	}
+	return {
+		...current,
+		segments: orderSegments(dedupeConnection(segments))
+	};
+};
+/**
+* Disjoint segments have no cursor linking them, so their relative order is
+* whatever it was; the two exceptions are known: a segment starting at the
+* terminal boundary is first, one ending at it is last.
+*/
+const orderSegments = (segments) => {
+	const first = segments.filter((value) => value.start._tag === "Terminal");
+	const last = segments.filter((value) => value.end._tag === "Terminal" && !first.includes(value));
+	const middle = segments.filter((value) => !first.includes(value) && !last.includes(value));
+	return [
+		...first,
+		...middle,
+		...last
+	];
+};
+/** Visible edges, segment by segment. */
+const items = (connection) => connection.segments.flatMap((value) => value.edges);
+/** There is more before the known region. Derived from boundaries, never row count. */
+const hasPrevious = (connection) => {
+	const first = connection.segments[0];
+	return first !== void 0 && first.start._tag !== "Terminal";
+};
+/** There is more after the known region. Derived from boundaries, never row count. */
+const hasNext = (connection) => {
+	const last = connection.segments[connection.segments.length - 1];
+	return last !== void 0 && last.end._tag !== "Terminal";
+};
+/** A connection with more than one segment has an explicit unknown gap. */
+const isGapped = (connection) => connection.segments.length > 1;
+//#endregion
+//#region src/inspect.ts
+const inspectEntry = (key, entry) => ({
+	key,
+	present: [...entry.present],
+	stale: [...entry.stale],
+	tombstone: entry.tombstone,
+	updatedAt: entry.updatedAt,
+	windows: { ...entry.windows }
+});
+/** A pure, serializable view of the whole cache. */
+const inspectRemote = (model) => ({
+	entities: Object.entries(model.entities).map(([key, entry]) => inspectEntry(key, entry)),
+	connections: Object.keys(model.connections),
+	live: Object.keys(model.live),
+	gaps: [...model.gaps],
+	mutations: {
+		pending: [...model.mutations.pending],
+		failed: [...model.mutations.failed],
+		applied: model.mutations.applied.size
+	}
+});
+/** A pure, serializable view of one entity, or `undefined` if unknown. */
+const inspectEntity = (model, key) => {
+	const entry = model.entities[key];
+	return entry === void 0 ? void 0 : inspectEntry(key, entry);
+};
+//#endregion
+//#region src/optimistic.ts
+/**
+* Optimistic layers. Pending changes are held as ordered layers over a base
+* store and as overlays over a connection; the visible value is recomputed, never
+* patched with inverses. Settling is remove-the-layer, so overlapping layers
+* rebase for free.
+*/
+const isConnectionChange = (operation) => "_tag" in operation;
+const toOverlays = (id, changes) => changes.map((change) => ({
+	id,
+	connection: change.connection,
+	edges: [change.edge],
+	position: change._tag === "Insert" ? change.position : "remove"
+}));
+const connectionIdentity = (connection) => typeof connection === "string" ? connection : connection.identity;
+const change = (connection, ref, position) => position === "remove" ? {
+	_tag: "Remove",
+	connection: connectionIdentity(connection),
+	edge: edge(ref)
+} : {
+	_tag: "Insert",
+	connection: connectionIdentity(connection),
+	position,
+	edge: edge(ref)
+};
+/**
+* Constructors for connection changes: what a request shows optimistically
+* (`MutateOptions.optimistic`) and what a mutation source reports it made
+* (`MutationOutcome.connections`).
+*/
+const ConnectionChange = {
+	/** Show `ref` at the front of the connection until the request settles. */
+	prepend: (connection, ref) => change(connection, ref, "prepend"),
+	/** Show `ref` at the end of the connection until the request settles. */
+	append: (connection, ref) => change(connection, ref, "append"),
+	/** Hide `ref` from the connection until the request settles. */
+	remove: (connection, ref) => change(connection, ref, "remove")
+};
+/**
+* Applies a request's operations: its patches become one layer and its
+* connection changes become overlays, all owned by `requestId` so settling
+* removes every one of them together.
+*/
+const beginOptimistic = (optimistic, requestId, operations) => {
+	const patches = operations.filter((operation) => !isConnectionChange(operation));
+	const changes = operations.filter(isConnectionChange);
+	return {
+		layers: patches.length === 0 ? optimistic.layers : [...optimistic.layers, {
+			id: requestId,
+			patches
+		}],
+		overlays: [...optimistic.overlays, ...toOverlays(requestId, changes)]
+	};
+};
+/**
+* Replaces a request's overlays with the server-confirmed changes, owned by
+* `id`, in the position the request's overlays held, so a confirmed edge keeps
+* its place among other pending inserts.
+*/
+const confirm = (optimistic, requestId, id, changes) => {
+	const confirmed = toOverlays(id, changes);
+	const at = optimistic.overlays.findIndex((overlay) => overlay.id === requestId);
+	const others = optimistic.overlays.filter((overlay) => overlay.id !== requestId);
+	return {
+		...optimistic,
+		overlays: at === -1 ? [...others, ...confirmed] : [
+			...others.slice(0, at),
+			...confirmed,
+			...others.slice(at)
+		]
+	};
+};
+const emptyOptimistic = {
+	layers: [],
+	overlays: []
+};
+const addLayer = (optimistic, layer) => ({
+	...optimistic,
+	layers: [...optimistic.layers, layer]
+});
+const removeLayer = (optimistic, id) => ({
+	...optimistic,
+	layers: optimistic.layers.filter((layer) => layer.id !== id)
+});
+const addOverlay = (optimistic, overlay) => ({
+	...optimistic,
+	overlays: [...optimistic.overlays, overlay]
+});
+const removeOverlay = (optimistic, id) => ({
+	...optimistic,
+	overlays: optimistic.overlays.filter((overlay) => overlay.id !== id)
+});
+/** Base store with every layer applied in order. Later layers win. */
+const visibleStore = (base, optimistic) => optimistic.layers.reduce((store, layer) => layer.patches.reduce((current, patch) => writeEntity(current, entityKey(patch.entity, patch.id), patch.values), store), base);
+/**
+* A fresh page is newer than any settled overlay it covers: an edge the page
+* carries no longer needs an insert overlay, and a `remove` overlay hiding it
+* is stale (the server says it is back). A pending request's overlays are
+* left alone; they settle with the request.
+*/
+const pruneOverlays = (optimistic, connection, covered, pending) => ({
+	...optimistic,
+	overlays: optimistic.overlays.flatMap((overlay) => {
+		if (overlay.connection !== connection || pending.has(overlay.id)) return [overlay];
+		const edges = overlay.edges.filter((edge) => !covered.has(edge.key));
+		return edges.length === 0 ? [] : [{
+			...overlay,
+			edges
+		}];
+	})
+});
+/** Everything a request owns: its layer and its overlays. */
+const release = (optimistic, requestId) => removeOverlay(removeLayer(optimistic, requestId), requestId);
+/**
+* Applies a result idempotently and releases the request's layer and overlays:
+* a later layer re-wins on rebase. Confirmed connection changes are recorded
+* once per request, as overlays the request no longer owns.
+*/
+const settleSuccess = (base, optimistic, state, requestId, entities, connections = []) => {
+	const reconciled = reconcileMutation(base, state, requestId, entities);
+	return {
+		store: reconciled.store,
+		state: reconciled.state,
+		optimistic: state.applied.has(requestId) ? release(optimistic, requestId) : confirm(removeLayer(optimistic, requestId), requestId, `confirmed:${requestId}`, connections)
+	};
+};
+/** A failed request's layer and overlays are dropped; the base was never mutated. */
+const settleFailure = (optimistic, requestId) => release(optimistic, requestId);
+/**
+* Visible edges for one connection: applicable overlays are placed outside the
+* server-known segments and de-duplicated by edge identity (across overlays too),
+* so a pending insert never corrupts server-known ordering; a `remove` overlay
+* hides its edges wherever they are, and so does a tombstone on the edge's
+* target when `store` is given. A later prepend lands before an earlier one, a
+* later append after, so pending inserts read in the order they were made.
+* Boundaries still come from the connection's segments.
+*/
+const visibleItems = (connection, connectionId, overlays, store) => {
+	const applicable = overlays.filter((overlay) => overlay.connection === connectionId);
+	const hidden = /* @__PURE__ */ new Set();
+	for (const overlay of applicable) for (const edge of overlay.edges) if (overlay.position === "remove") hidden.add(edge.key);
+	else hidden.delete(edge.key);
+	const gone = (edge) => hidden.has(edge.key) || store !== void 0 && isTombstone(store, entityKey(edge.ref.entity, edge.ref.id));
+	const known = items(connection).filter((edge) => !gone(edge));
+	const seen = new Set(known.map((edge) => edge.key));
+	const take = (position) => {
+		const edges = [];
+		const ordered = applicable.filter((value) => value.position === position);
+		for (const overlay of position === "prepend" ? [...ordered].reverse() : ordered) for (const edge of overlay.edges) {
+			if (seen.has(edge.key) || gone(edge)) continue;
+			seen.add(edge.key);
+			edges.push(edge);
+		}
+		return edges;
+	};
+	return [
+		...take("prepend"),
+		...known,
+		...take("append")
+	];
+};
+//#endregion
+//#region src/live.ts
+const emptyLiveState = {
+	cursor: 0,
+	stale: /* @__PURE__ */ new Set(),
+	boundary: {}
+};
+/**
+* Ordering per stream: at most the next cursor; ahead is a gap. Cursor `0` means
+* "no baseline yet" (cursors are 1-based), so the first event of a stream is
+* accepted whatever its cursor — otherwise a stream not starting at 1 would be a
+* spurious gap.
+*/
+const classifyLive = (state, cursor) => cursor <= state.cursor ? "duplicate" : state.cursor === 0 || cursor === state.cursor + 1 ? "applied" : "gap";
+const advance = (state, cursor) => ({
+	...state,
+	cursor
+});
+const recordBoundary = (state, connection, position) => {
+	const current = state.boundary[connection] ?? {
+		before: 0,
+		after: 0
+	};
+	const next = position === "prepend" ? {
+		...current,
+		before: current.before + 1
+	} : {
+		...current,
+		after: current.after + 1
+	};
+	return {
+		...state,
+		boundary: {
+			...state.boundary,
+			[connection]: next
+		}
+	};
+};
+const invalidateConnection = (state, connection) => ({
+	...state,
+	stale: /* @__PURE__ */ new Set([...state.stale, connection])
+});
+/**
+* A subscriber is woken only if the event changed a field it selects. A
+* change to an unselected field is skipped entirely.
+*/
+const shouldWake = (changed, selected) => changed.some((field) => selected.includes(field));
+const applyEntityEvent = (state, store, event, now = 0) => {
+	const outcome = classifyLive(state, event.cursor);
+	if (outcome !== "applied") return {
+		state,
+		store,
+		outcome
+	};
+	const key = entityKey(event.ref.entity, event.ref.id);
+	const next = event._tag === "EntityPatched" ? writeEntity(store, key, event.values, now) : tombstone(store, key);
+	return {
+		state: advance(state, event.cursor),
+		store: next,
+		outcome
+	};
+};
+const removeEdgeOverlays = (optimistic, connection, key) => ({
+	...optimistic,
+	overlays: optimistic.overlays.map((overlay) => overlay.connection !== connection || overlay.position === "remove" ? overlay : {
+		...overlay,
+		edges: overlay.edges.filter((edge) => edge.key !== key)
+	})
+});
+const applyConnectionEvent = (state, optimistic, event, policy = {}) => {
+	const outcome = classifyLive(state, event.cursor);
+	if (outcome !== "applied") return {
+		state,
+		optimistic,
+		outcome
+	};
+	switch (event._tag) {
+		case "ConnectionInsert": switch ((event.position === "prepend" ? policy.prepend : policy.append) ?? "visible") {
+			case "visible": return {
+				state: advance(state, event.cursor),
+				optimistic: addOverlay(optimistic, {
+					id: `live:${event.cursor}`,
+					connection: event.connection,
+					edges: [event.edge],
+					position: event.position
+				}),
+				outcome
+			};
+			case "boundary": return {
+				state: recordBoundary(advance(state, event.cursor), event.connection, event.position),
+				optimistic,
+				outcome
+			};
+			case "invalidate": return {
+				state: invalidateConnection(advance(state, event.cursor), event.connection),
+				optimistic,
+				outcome
+			};
+			case "ignore": return {
+				state: advance(state, event.cursor),
+				optimistic,
+				outcome
+			};
+		}
+		case "ConnectionRemove": return {
+			state: advance(state, event.cursor),
+			optimistic: addOverlay(removeEdgeOverlays(optimistic, event.connection, event.edge.key), {
+				id: `live:${event.cursor}`,
+				connection: event.connection,
+				edges: [event.edge],
+				position: "remove"
+			}),
+			outcome
+		};
+		case "ConnectionInvalidate": return {
+			state: invalidateConnection(advance(state, event.cursor), event.connection),
+			optimistic,
+			outcome
+		};
+	}
+};
+const isStale = (state, connection) => state.stale.has(connection);
+/**
+* Clears a connection's stale mark once a fresh page has been adopted. An
+* invalidating event only records that a refetch is due; whoever merges the
+* refetched page calls this so `isStale` stops reporting.
+*/
+const refreshConnection = (state, connection) => {
+	if (!state.stale.has(connection)) return state;
+	const stale = new Set(state.stale);
+	stale.delete(connection);
+	return {
+		...state,
+		stale
+	};
+};
+/** `hasPrevious` accounting for edges recorded outside the loaded boundary. */
+const liveHasPrevious = (connection, state, connectionId) => hasPrevious(connection) || (state.boundary[connectionId]?.before ?? 0) > 0;
+/** `hasNext` accounting for edges recorded outside the loaded boundary. */
+const liveHasNext = (connection, state, connectionId) => hasNext(connection) || (state.boundary[connectionId]?.after ?? 0) > 0;
+//#endregion
+//#region src/relation.ts
+/** Marks the codec `Entity.ref`/`Entity.refPage` produce, so a Selection can tell the field's shape. */
+const RelationAnnotation = "foldkitRemoteRelation";
+/** The target entity's name on the same codec, so a nested selection of another entity is refused. */
+const RelationEntityAnnotation = "foldkitRemoteRelationEntity";
+/** Splits a ref key (`"Entity:id"`, the store key too) back into its parts. */
+const refParts = (encoded) => {
+	const separator = encoded.indexOf(":");
+	return separator === -1 ? {
+		entity: encoded,
+		id: ""
+	} : {
+		entity: encoded.slice(0, separator),
+		id: encoded.slice(separator + 1)
+	};
+};
+/**
+* The refs a relation value carries, in order. Anything that is not a ref key,
+* an array of them, or a page of them contributes nothing.
+*/
+const refsIn = (value) => {
+	if (typeof value === "string") return [refParts(value)];
+	if (Array.isArray(value)) return value.filter((item) => typeof item === "string").map(refParts);
+	if (value !== null && typeof value === "object") {
+		const refs = value.refs;
+		if (Array.isArray(refs)) return refs.filter((item) => typeof item === "string").map(refParts);
+	}
+	return [];
+};
+/** The refs in a relation value that name the relation's target entity, and no other. */
+const targetsOf = (value, relation) => refsIn(value).filter((ref) => ref.entity === relation.entity);
+const isRefPage = (value) => {
+	if (value === null || typeof value !== "object") return false;
+	const page = value;
+	return Array.isArray(page.refs) && page.refs.every((ref) => typeof ref === "string") && typeof page.hasNext === "boolean" && typeof page.hasPrevious === "boolean";
+};
+/**
+* The relation shape an entity field schema declares: a ref (`one`), a nullable
+* ref, an array of refs (`many`), or a page of refs (`page`). `undefined` for a
+* scalar field, which cannot take a nested selection.
+*/
+const relationShape = (schema) => shapeOf(schema.ast, false);
+const shapeOf = (ast, nullable) => {
+	const annotated = ast.annotations?.[RelationAnnotation];
+	if (annotated === "one" || annotated === "page") return {
+		kind: annotated,
+		nullable,
+		entity: String(ast.annotations?.[RelationEntityAnnotation])
+	};
+	if (ast._tag === "Arrays") {
+		const item = ast.rest?.[0];
+		const inner = item === void 0 ? void 0 : shapeOf(item, false);
+		return inner?.kind === "one" ? {
+			kind: "many",
+			nullable,
+			entity: inner.entity
+		} : void 0;
+	}
+	if (ast._tag === "Union") {
+		const members = ast.types ?? [];
+		const optional = members.some((member) => member._tag === "Null" || member._tag === "Undefined");
+		for (const member of members) {
+			const shape = shapeOf(member, optional);
+			if (shape !== void 0) return shape;
+		}
+	}
+};
+//#endregion
+//#region src/plan.ts
+/**
+* The pure requirement planner.
+*
+* A `Requirement` is plain data: which entity fields a Remote projection needs,
+* and through `relations`, which fields of each relation's target. `plan` diffs
+* requirements against the store and returns only the missing fields, grouped
+* and deterministically ordered. A relation whose field is being fetched keeps
+* its nested requirement on the request, so the server resolves the graph in
+* one read; a relation whose refs the store already holds is followed into
+* concrete requirements for the targets. Time enters through `PlanFreshness`,
+* never from ambient state; `force` plans every field.
+*/
+/** A stable key for a window, so two equal windows compare equal. */
+const windowKey = (window) => stableStringify(window);
+const pickFields = (record, fields) => {
+	if (record === void 0) return void 0;
+	const picked = Object.fromEntries(Object.entries(record).filter(([field]) => fields.has(field)));
+	return Object.keys(picked).length === 0 ? void 0 : picked;
+};
+/** The concrete requirements a known relation value contributes for its targets. */
+const followRelation = (value, relation) => targetsOf(value, relation).map((ref) => ({
+	...relation,
+	id: ref.id
+}));
+const plan = (store, requirements, options = {}) => {
+	const { freshness, force = false } = options;
+	const planned = [];
+	const followed = [];
+	for (const group of Requirement.merge(requirements)) {
+		const key = entityKey(group.entity, group.id);
+		const entry = store[key];
+		const expired = freshness !== void 0 && entry !== void 0 && !entry.tombstone && freshness.now - entry.updatedAt > freshness.freshness;
+		const windowKeys = Object.fromEntries(Object.entries(group.windows ?? {}).map(([field, window]) => [field, windowKey(window)]));
+		const missing = force || expired ? group.fields : missingFields(store, key, group.fields, windowKeys);
+		const missingSet = new Set(missing);
+		for (const [field, relation] of Object.entries(group.relations ?? {})) {
+			if (missingSet.has(field)) continue;
+			const value = readField(store, key, field);
+			if (value._tag === "Some") followed.push(...followRelation(value.value, relation));
+		}
+		if (missing.length === 0) continue;
+		const windows = pickFields(group.windows, missingSet);
+		const relations = pickFields(group.relations, missingSet);
+		planned.push({
+			entity: group.entity,
+			id: group.id,
+			fields: missing,
+			...windows === void 0 ? {} : { windows },
+			...relations === void 0 ? {} : { relations }
+		});
+	}
+	const nested = followed.length === 0 ? [] : plan(store, followed, options);
+	return [...Requirement.merge([...planned, ...nested])].sort((a, b) => entityKey(a.entity, a.id) < entityKey(b.entity, b.id) ? -1 : 1);
+};
+//#endregion
+//#region src/retain.ts
+/**
+* The entity keys the roots reach: each root entity, the targets its retained
+* fields refer to, and recursively the targets a nested relation selects.
+*/
+const reachable = (store, roots, connections, optimistic, pending) => {
+	const kept = /* @__PURE__ */ new Set();
+	const rootConnections = new Set(roots.connections.map((root) => root.identity));
+	const walked = /* @__PURE__ */ new Map();
+	const visit = (key, requirement) => {
+		kept.add(key);
+		const seen = walked.get(key) ?? /* @__PURE__ */ new Set();
+		if (seen.has(requirement)) return;
+		seen.add(requirement);
+		walked.set(key, seen);
+		for (const field of requirement.fields) {
+			const value = readField(store, key, field);
+			if (value._tag === "None") continue;
+			const relation = requirement.relations?.[field];
+			for (const ref of refsIn(value.value)) {
+				const target = entityKey(ref.entity, ref.id);
+				if (relation === void 0 || ref.entity !== relation.entity) {
+					kept.add(target);
+					continue;
+				}
+				visit(target, relation);
+			}
+		}
+	};
+	for (const root of roots.requirements) visit(entityKey(root.entity, root.id), root);
+	for (const { identity, select } of roots.connections) for (const segment of connections[identity]?.segments ?? []) for (const edge of segment.edges) {
+		const target = entityKey(edge.ref.entity, edge.ref.id);
+		if (select === void 0 || edge.ref.entity !== select.entity) kept.add(target);
+		else visit(target, select);
+	}
+	for (const layer of optimistic.layers) {
+		if (!pending.has(layer.id)) continue;
+		for (const patch of layer.patches) kept.add(entityKey(patch.entity, patch.id));
+	}
+	for (const overlay of optimistic.overlays) {
+		if (!pending.has(overlay.id) && !rootConnections.has(overlay.connection)) continue;
+		for (const edge of overlay.edges) kept.add(entityKey(edge.ref.entity, edge.ref.id));
+	}
+	return kept;
+};
+/**
+* Drops every entity the roots do not reach, every connection they do not
+* name, and every settled overlay on a dropped connection, keeping whatever a
+* pending request's layer or overlays touch. Pure.
+*/
+const gc = (state, roots) => {
+	const pending = state.mutations.pending;
+	const kept = reachable(state.entities, roots, state.connections, state.optimistic, pending);
+	const entities = Object.fromEntries(Object.entries(state.entities).filter(([key]) => kept.has(key)));
+	const keptConnections = /* @__PURE__ */ new Set([...roots.connections.map((root) => root.identity), ...state.optimistic.overlays.filter((overlay) => pending.has(overlay.id)).map((overlay) => overlay.connection)]);
+	return {
+		entities,
+		connections: Object.fromEntries(Object.entries(state.connections).filter(([identity]) => keptConnections.has(identity))),
+		optimistic: {
+			layers: state.optimistic.layers,
+			overlays: state.optimistic.overlays.filter((overlay) => pending.has(overlay.id) || keptConnections.has(overlay.connection))
+		}
+	};
+};
+//#endregion
+//#region src/persistence.ts
+/**
+* Remote cache persistence: a snapshot of the entity store and nothing else.
+* Runtime state (connections' live cursors, optimistic layers, the mutation
+* ledger, gaps, retention roots) is never in a snapshot; it belongs to the
+* session that produced it.
+*
+* The cache is server-derived and disposable: an incompatible, oversized, or
+* corrupt snapshot is discarded (and removed from a `KeyValueStore`) so the
+* planner refetches. `dehydrate`/`hydrate` are the string forms, for SSR and
+* any other transport; `save`/`restore` put them behind Effect's
+* `KeyValueStore`, so the backend (memory, filesystem, SQL, Web Storage) is the
+* application's choice.
+*/
+/** Bump when the serialized shape changes; a mismatch discards the cache. */
+const REMOTE_CACHE_VERSION = 3;
+const sorted = (values) => [...values].sort();
+/**
+* The snapshot's data shape. `stableStringify` sorts object keys, and the
+* field sets are sorted here, so equal stores give byte-equal snapshots
+* whatever order they were built in.
+*/
+const serializeStore = (store, scope) => ({
+	version: 3,
+	scope: scope ?? null,
+	entities: Object.fromEntries(Object.entries(store).map(([key, entry]) => [key, {
+		values: entry.values,
+		present: sorted(entry.present),
+		stale: sorted(entry.stale),
+		tombstone: entry.tombstone,
+		updatedAt: entry.updatedAt,
+		windows: entry.windows
+	}]))
+});
+const isStringArray = (value) => Array.isArray(value) && value.every((item) => typeof item === "string");
+const isStringRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value) && Object.values(value).every((item) => typeof item === "string");
+/** Throws on a malformed entry so the whole snapshot is discarded. */
+const parseEntry = (value) => {
+	if (value === null || typeof value !== "object") throw new Error("entry is not an object");
+	const entry = value;
+	if (entry.values === null || typeof entry.values !== "object" || Array.isArray(entry.values)) throw new Error("entry.values is not a record");
+	if (!isStringArray(entry.present)) throw new Error("entry.present is not a string array");
+	if (!isStringArray(entry.stale)) throw new Error("entry.stale is not a string array");
+	if (typeof entry.tombstone !== "boolean") throw new Error("entry.tombstone is not a boolean");
+	if (typeof entry.updatedAt !== "number") throw new Error("entry.updatedAt is not a number");
+	if (!isStringRecord(entry.windows)) throw new Error("entry.windows is not a string record");
+	return {
+		values: entry.values,
+		present: new Set(entry.present),
+		stale: new Set(entry.stale),
+		tombstone: entry.tombstone,
+		updatedAt: entry.updatedAt,
+		windows: entry.windows
+	};
+};
+const deserializeStore = (serialized) => Object.fromEntries(Object.entries(serialized.entities).map(([key, entry]) => [key, parseEntry(entry)]));
+/**
+* The snapshot text, or `undefined` when it would exceed `maxBytes`. Only the
+* entity store goes in; pass `model.entities`, never the whole `RemoteModel`.
+*/
+const dehydrate = (store, options = {}) => {
+	const text = stableStringify(serializeStore(store, options.scope));
+	return exceeds(text, options.maxBytes) ? void 0 : text;
+};
+/**
+* Whether the UTF-8 size of `text` exceeds `maxBytes`. A character is one to
+* three bytes, so most texts are decided from their length alone; only the
+* rest are measured.
+*/
+const exceeds = (text, maxBytes) => {
+	if (maxBytes === void 0) return false;
+	if (text.length > maxBytes) return true;
+	if (text.length * 3 <= maxBytes) return false;
+	return new TextEncoder().encode(text).length > maxBytes;
+};
+/**
+* The store a snapshot text holds, or `undefined` when the text is missing,
+* oversized, not this version, for another scope, or malformed. Hydrating the
+* same text twice yields equal stores.
+*/
+const hydrate = (raw, options = {}) => {
+	if (raw === void 0 || raw === null) return void 0;
+	if (exceeds(raw, options.maxBytes)) return void 0;
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return;
+	}
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return void 0;
+	const candidate = parsed;
+	if (candidate.version !== 3) return void 0;
+	if ((candidate.scope ?? null) !== (options.scope ?? null)) return void 0;
+	if (candidate.entities === null || typeof candidate.entities !== "object") return void 0;
+	if (Array.isArray(candidate.entities)) return void 0;
+	try {
+		return deserializeStore(candidate);
+	} catch {
+		return;
+	}
+};
+/**
+* Brings a snapshot into a store that may already hold entries. `replace`
+* takes the snapshot's entry for every key it has; `preserve-existing` keeps
+* an entry the current store already has (it is at least as fresh as a
+* snapshot taken earlier). Either way, keys only the current store has stay.
+*/
+const mergeStores = (current, snapshot, policy) => policy === "replace" ? {
+	...current,
+	...snapshot
+} : {
+	...snapshot,
+	...current
+};
+const RemotePersistence = {
+	/** The snapshot text, or `undefined` when it would exceed `maxBytes`. */
+	dehydrate,
+	/** The store a snapshot text holds, or `undefined` when it is refused. */
+	hydrate,
+	/** A snapshot brought into a store by policy. */
+	mergeStores,
+	/**
+	* Writes the snapshot under `key`, or removes the key when the store would
+	* exceed `maxBytes`, so a stale smaller snapshot cannot outlive a larger
+	* store it no longer describes.
+	*/
+	save: (store, options) => Effect.gen(function* () {
+		const kv = yield* KeyValueStore.KeyValueStore;
+		const text = dehydrate(store, options);
+		if (text === void 0) yield* kv.remove(options.key);
+		else yield* kv.set(options.key, text);
+	}),
+	/**
+	* Reads the cache. A missing key yields `emptyStore`; anything `hydrate`
+	* refuses yields `emptyStore` and removes the key, so the next `restore` is
+	* clean and the planner refetches.
+	*/
+	restore: (options) => Effect.gen(function* () {
+		const kv = yield* KeyValueStore.KeyValueStore;
+		const raw = yield* kv.get(options.key);
+		if (raw === void 0) return emptyStore;
+		const restored = hydrate(raw, options);
+		if (restored === void 0) {
+			yield* kv.remove(options.key);
+			return emptyStore;
+		}
+		return restored;
+	})
+};
+//#endregion
+//#region src/remoteData.ts
+/** `RemoteData`: the state of a value the store may not hold yet. */
+const remoteErrorSchema = Schema.Struct({
+	_tag: Schema.String,
+	message: Schema.String
+});
+/** A `RemoteData` schema, so a projection that reads remote state is typed. */
+const remoteDataSchemas = /* @__PURE__ */ new WeakMap();
+const remoteDataSchema = (value) => {
+	const cached = remoteDataSchemas.get(value);
+	if (cached !== void 0) return cached;
+	const built = Schema.Union([
+		Schema.Struct({ _tag: Schema.Literal("Initial") }),
+		Schema.Struct({ _tag: Schema.Literal("Loading") }),
+		Schema.Struct({
+			_tag: Schema.Literal("Ready"),
+			value
+		}),
+		Schema.Struct({
+			_tag: Schema.Literal("Refreshing"),
+			value
+		}),
+		Schema.Struct({
+			_tag: Schema.Literal("Failed"),
+			error: remoteErrorSchema,
+			previous: Schema.optional(value)
+		}),
+		Schema.Struct({ _tag: Schema.Literal("NotFound") })
+	]);
+	remoteDataSchemas.set(value, built);
+	return built;
+};
+const RemoteData = {
+	/**
+	* The `RemoteData` schema for a value schema. Exposed so a `RemoteData` can
+	* be embedded in a hand-written Model schema, not only through `Remote.select`.
+	*/
+	schema: (value) => remoteDataSchema(value),
+	/** Exhaustive: omitting a state is a compile error. */
+	match: (data, cases) => {
+		switch (data._tag) {
+			case "Initial": return cases.Initial();
+			case "Loading": return cases.Loading();
+			case "Ready": return cases.Ready(data.value);
+			case "Refreshing": return cases.Refreshing(data.value);
+			case "Failed": return cases.Failed(data.error, data.previous === void 0 ? Option.none() : Option.some(data.previous));
+			case "NotFound": return cases.NotFound();
+		}
+	},
+	map: (data, f) => {
+		switch (data._tag) {
+			case "Ready": return {
+				_tag: "Ready",
+				value: f(data.value)
+			};
+			case "Refreshing": return {
+				_tag: "Refreshing",
+				value: f(data.value)
+			};
+			case "Failed": return data.previous === void 0 ? {
+				_tag: "Failed",
+				error: data.error
+			} : {
+				_tag: "Failed",
+				error: data.error,
+				previous: f(data.previous)
+			};
+			default: return data;
+		}
+	}
+};
+//#endregion
+//#region src/model.ts
+/**
+* The Remote submodel: the store, connections, mutations, live state, and
+* optimistic layers an application keeps in its Model, the Messages that
+* change it, and the pure reducer over them.
+*/
+const initialRemoteModel = {
+	entities: emptyStore,
+	connections: {},
+	optimistic: emptyOptimistic,
+	live: {},
+	mutations: emptyMutationState,
+	gaps: /* @__PURE__ */ new Set()
+};
+/** The entity store and the mutation ledger are runtime values, not wire shapes. */
+const runtimeSchema = Schema.Unknown;
+const remoteModelSchema = () => Schema.Struct({
+	entities: runtimeSchema,
+	connections: Schema.Record(Schema.String, runtimeSchema),
+	optimistic: runtimeSchema,
+	live: Schema.Record(Schema.String, runtimeSchema),
+	mutations: runtimeSchema,
+	gaps: runtimeSchema
+});
+const retentionRootsSchema = Schema.Struct({
+	requirements: Schema.Array(ReadRequest),
+	connections: Schema.Array(Schema.Struct({
+		identity: Schema.String,
+		select: Schema.optional(RelationRequest)
+	}))
+});
+/**
+* The Messages' fields by tag, without `_tag`: what `defineMessageUnion` takes,
+* so an application spreads them into its own union (`Remote.messages`).
+*/
+const remoteMessageCases = {
+	ReadReceived: {
+		requests: Schema.Array(ReadRequest),
+		result: ReadBatchResult,
+		now: Schema.Number
+	},
+	ReadFailed: {
+		requests: Schema.Array(ReadRequest),
+		error: remoteErrorSchema
+	},
+	RefreshStarted: { requests: Schema.Array(ReadRequest) },
+	RetentionChanged: { roots: retentionRootsSchema },
+	Hydrated: {
+		entities: runtimeSchema,
+		merge: Schema.Union([Schema.Literal("replace"), Schema.Literal("preserve-existing")])
+	},
+	MutationStarted: {
+		requestId: Schema.String,
+		optimistic: Schema.optional(Schema.Array(Schema.Unknown))
+	},
+	MutationSucceeded: {
+		requestId: Schema.String,
+		entities: Schema.Array(NormalizedEntity),
+		connections: Schema.optional(Schema.Array(Schema.Unknown))
+	},
+	MutationFailed: {
+		requestId: Schema.String,
+		error: remoteErrorSchema
+	},
+	LiveReceived: {
+		stream: Schema.String,
+		event: Schema.Unknown,
+		policy: Schema.optional(Schema.Unknown),
+		now: Schema.Number
+	},
+	GapCleared: { stream: Schema.String },
+	ConnectionMerged: {
+		connection: Schema.String,
+		page: Schema.Unknown,
+		refreshes: Schema.optional(Schema.Boolean)
+	},
+	ConnectionInvalidated: { connection: Schema.String },
+	ConnectionRefreshed: { connection: Schema.String },
+	QueryFailed: {
+		connection: Schema.String,
+		error: remoteErrorSchema
+	}
+};
+/**
+* Whether a Message is one of Remote's, by tag. Narrows an application's union
+* to its Remote cases, and its complement to the application's own.
+*/
+const isRemoteMessage = (message) => Object.hasOwn(remoteMessageCases, message._tag);
+const remoteMessageSchema = Schema.Union(Object.entries(remoteMessageCases).map(([tag, fields]) => Schema.Struct({
+	_tag: Schema.Literal(tag),
+	...fields
+})));
+const marksOf = (requests) => requests.map((request) => [entityKey(request.entity, request.id), request.fields]);
+const setConnectionStale = (connections, connection, stale) => {
+	const current = connections[connection] ?? emptyConnection;
+	return {
+		...connections,
+		[connection]: {
+			...current,
+			stale
+		}
+	};
+};
+const markGap = (model, stream) => model.gaps.has(stream) ? model : {
+	...model,
+	gaps: /* @__PURE__ */ new Set([...model.gaps, stream])
+};
+const clearGap = (model, stream) => model.gaps.has(stream) ? {
+	...model,
+	gaps: new Set([...model.gaps].filter((entry) => entry !== stream))
+} : model;
+/**
+* The pure reducer all four producers share. A live event that arrives ahead of
+* its cursor is a gap: it is not applied, and the stream is recorded so the host
+* can resubscribe rather than silently miss facts.
+*/
+const updateRemote = (model, message) => {
+	switch (message._tag) {
+		case "ReadReceived": return {
+			...model,
+			entities: writeRead(model.entities, message.requests, message.result, message.now)
+		};
+		case "ReadFailed": return {
+			...model,
+			entities: setStale(model.entities, marksOf(message.requests), false)
+		};
+		case "RetentionChanged": return {
+			...model,
+			...gc(model, message.roots)
+		};
+		case "Hydrated": return {
+			...model,
+			entities: RemotePersistence.mergeStores(model.entities, message.entities, message.merge)
+		};
+		case "RefreshStarted": return {
+			...model,
+			entities: setStale(model.entities, marksOf(message.requests), true)
+		};
+		case "MutationStarted": return {
+			...model,
+			mutations: beginMutation(model.mutations, message.requestId),
+			optimistic: beginOptimistic(model.optimistic, message.requestId, message.optimistic ?? [])
+		};
+		case "MutationSucceeded": {
+			const settled = settleSuccess(model.entities, model.optimistic, model.mutations, message.requestId, message.entities, message.connections ?? []);
+			return {
+				...model,
+				entities: settled.store,
+				mutations: settled.state,
+				optimistic: settled.optimistic
+			};
+		}
+		case "MutationFailed": return {
+			...model,
+			mutations: failMutation(model.mutations, message.requestId),
+			optimistic: settleFailure(model.optimistic, message.requestId)
+		};
+		case "LiveReceived": {
+			const state = model.live[message.stream] ?? emptyLiveState;
+			if (message.event._tag === "EntityPatched" || message.event._tag === "EntityDeleted") {
+				const applied = applyEntityEvent(state, model.entities, message.event, message.now);
+				return applied.outcome === "gap" ? markGap(model, message.stream) : clearGap({
+					...model,
+					entities: applied.store,
+					live: {
+						...model.live,
+						[message.stream]: applied.state
+					}
+				}, message.stream);
+			}
+			const applied = applyConnectionEvent(state, model.optimistic, message.event, message.policy);
+			return applied.outcome === "gap" ? markGap(model, message.stream) : clearGap({
+				...model,
+				optimistic: applied.optimistic,
+				live: {
+					...model.live,
+					[message.stream]: applied.state
+				}
+			}, message.stream);
+		}
+		case "GapCleared": return clearGap(model, message.stream);
+		case "ConnectionMerged": {
+			const current = model.connections[message.connection] ?? emptyConnection;
+			const merged = merge(current, message.page);
+			return {
+				...model,
+				connections: {
+					...model.connections,
+					[message.connection]: message.refreshes === true ? {
+						...merged,
+						stale: false
+					} : merged
+				},
+				optimistic: pruneOverlays(model.optimistic, message.connection, new Set(message.page.edges.map((edge) => edge.key)), model.mutations.pending)
+			};
+		}
+		case "ConnectionInvalidated": return {
+			...model,
+			connections: setConnectionStale(model.connections, message.connection, true)
+		};
+		case "QueryFailed": return message.connection in model.connections ? {
+			...model,
+			connections: setConnectionStale(model.connections, message.connection, false)
+		} : model;
+		case "ConnectionRefreshed": return {
+			...model,
+			connections: setConnectionStale(model.connections, message.connection, false)
+		};
+	}
+};
+/** Appends (after) or prepends (before) an incoming page onto the stored one. */
+const mergeWireRefPages = (current, next, direction) => {
+	const refs = direction === "after" ? [.../* @__PURE__ */ new Set([...current.refs, ...next.refs])] : [.../* @__PURE__ */ new Set([...next.refs, ...current.refs])];
+	return direction === "after" ? {
+		refs,
+		hasNext: next.hasNext,
+		hasPrevious: current.hasPrevious
+	} : {
+		refs,
+		hasNext: current.hasNext,
+		hasPrevious: next.hasPrevious
+	};
+};
+/**
+* Writes a read result into the store, recording each field's applied window so
+* a later request with a different window refetches. A relation page requested
+* with a cursor is merged onto the page already stored, so "load more"
+* accumulates rather than replaces. Every read path should use this rather than
+* reducing `writeEntity` by hand.
+*/
+const writeRead = (store, requests, result, now = 0) => {
+	const returned = /* @__PURE__ */ new Map();
+	for (const entity of result.entities) {
+		const key = entityKey(entity.entity, entity.id);
+		returned.set(key, {
+			...returned.get(key),
+			...entity.values
+		});
+	}
+	const byEntity = /* @__PURE__ */ new Map();
+	const record = (key, windows, relations) => {
+		let entry = byEntity.get(key);
+		if (entry === void 0) {
+			entry = {
+				windows: {},
+				merge: /* @__PURE__ */ new Map()
+			};
+			byEntity.set(key, entry);
+		}
+		for (const [field, window] of Object.entries(windows ?? {})) {
+			entry.windows[field] = windowKey(window);
+			const direction = window.after !== void 0 ? "after" : window.before !== void 0 ? "before" : void 0;
+			if (direction !== void 0) entry.merge.set(field, direction);
+		}
+		const values = returned.get(key);
+		if (values === void 0) return;
+		for (const [field, relation] of Object.entries(relations ?? {})) for (const ref of targetsOf(values[field], relation)) record(entityKey(ref.entity, ref.id), relation.windows, relation.relations);
+	};
+	for (const request of requests) record(entityKey(request.entity, request.id), request.windows, request.relations);
+	const writes = [];
+	const pending = /* @__PURE__ */ new Map();
+	for (const entity of result.entities) {
+		const key = entityKey(entity.entity, entity.id);
+		const entry = byEntity.get(key);
+		let values = entity.values;
+		if (entry !== void 0 && entry.merge.size > 0) {
+			const previous = pending.get(key) ?? store[key]?.values;
+			if (previous !== void 0) {
+				const merged = { ...values };
+				for (const [field, direction] of entry.merge) {
+					const incoming = values[field];
+					const existing = previous[field];
+					if (isRefPage(incoming) && isRefPage(existing)) merged[field] = mergeWireRefPages(existing, incoming, direction);
+				}
+				values = merged;
+			}
+		}
+		pending.set(key, {
+			...pending.get(key),
+			...values
+		});
+		writes.push({
+			key,
+			values,
+			windows: entry?.windows
+		});
+	}
+	return writeEntities(store, writes, now);
+};
+//#endregion
+//#region src/policy.ts
+const RemotePolicy = {
+	/** Fetch only what the store lacks. */
+	cacheFirst: { _tag: "CacheFirst" },
+	/** Keep present values visible, read as `Refreshing`, and refetch an entry older than `maxAge` ms. */
+	staleWhileRevalidate: (options) => ({
+		_tag: "StaleWhileRevalidate",
+		maxAge: options.maxAge
+	}),
+	/** Fetch every selected field regardless of coverage; cached values stay visible meanwhile. */
+	networkOnly: { _tag: "NetworkOnly" },
+	/** The planner options a policy compiles to at `now`. */
+	toPlan: (policy, now) => {
+		switch (policy._tag) {
+			case "CacheFirst": return {};
+			case "StaleWhileRevalidate": return { freshness: {
+				now,
+				freshness: policy.maxAge
+			} };
+			case "NetworkOnly": return { force: true };
+		}
+	},
+	/**
+	* Whether a read under this policy may refetch fields the store already
+	* holds, so an observer marks them stale (read as `Refreshing`) while the
+	* request is pending.
+	*/
+	refreshes: (policy) => policy._tag !== "CacheFirst"
+};
+//#endregion
+//#region src/entity.ts
+/**
+* Entities: the descriptor an application declares, refs, ref pages, and
+* patches, with the codecs that carry refs on the wire.
+*/
+/**
+* Relations are **references**, never inline target schemas: a ref cannot
+* reconstruct a full entity, and dereferencing is a store concern. Because the
+* target schema is not inlined, recursive relations cannot arise through the
+* schema graph.
+*/
+const refCodec = (entity) => Schema.Struct({
+	entity: Schema.String,
+	id: Schema.String
+}).pipe(Schema.encodeTo(Schema.String, {
+	decode: SchemaGetter.transform(refParts),
+	encode: SchemaGetter.transform((ref) => entityKey(ref.entity, ref.id))
+})).annotate({
+	[RelationAnnotation]: "one",
+	[RelationEntityAnnotation]: entity
+});
+const refPageCodec = (entity) => Schema.Struct({
+	refs: Schema.Array(refCodec(entity)),
+	hasNext: Schema.Boolean,
+	hasPrevious: Schema.Boolean
+}).annotate({
+	[RelationAnnotation]: "page",
+	[RelationEntityAnnotation]: entity
+});
+const Entity = {
+	make: (name, schema) => {
+		const descriptor = {
+			name,
+			schema,
+			fields: schema.fields,
+			ref: (id) => ({
+				entity: name,
+				id: String(id)
+			}),
+			select: (selection) => Selection.make(descriptor, selection),
+			patch: (id, values) => ({
+				entity: name,
+				id: String(id),
+				values
+			})
+		};
+		return descriptor;
+	},
+	/** A relation to a known entity, decoded as a reference. */
+	ref: (entity) => refCodec(entity.name),
+	/** A relation by name, for recursive or forward references. */
+	refTo: (name) => refCodec(name),
+	/**
+	* The wire key a relation field carries (`"Entity:id"`). Adapters that read a
+	* foreign key emit this so the ref codec can decode it on the client.
+	*/
+	refKey: (ref) => entityKey(ref.entity, ref.id),
+	/** Splits a ref key back into its entity and id. */
+	refParts,
+	/** A relation value of one authoritative page of refs. */
+	refPage: (entity) => refPageCodec(entity.name),
+	/**
+	* A normalized patch for an entity, typed against its fields' wire shape:
+	* write a relation as its ref key (`Entity.refKey`), as the server does.
+	*/
+	patch: (ref, patch) => ({
+		entity: ref.entity,
+		id: ref.id,
+		values: patch
+	})
+};
+//#endregion
+//#region src/selection.ts
+/**
+* Selections: the fields a Surface picks of an entity (nested through
+* relations, paged through connections), the requirement graph they imply,
+* and their assembly from the normalized store.
+*/
+const pageSchemas = /* @__PURE__ */ new WeakMap();
+const pageSchema = (item) => {
+	const cached = pageSchemas.get(item);
+	if (cached !== void 0) return cached;
+	const built = Schema.Struct({
+		items: Schema.Array(item),
+		hasNext: Schema.Boolean,
+		hasPrevious: Schema.Boolean
+	});
+	pageSchemas.set(item, built);
+	return built;
+};
+/** The requirement a nested selection contributes for its relation's target. */
+const relationOf = (selection) => ({
+	entity: selection.entity,
+	fields: selection.fields,
+	...selection.connections === void 0 ? {} : { windows: selection.connections },
+	...selection.relations === void 0 ? {} : { relations: selection.relations }
+});
+const Selection = {
+	/**
+	* The fields to read of `entity`. A nested `Selection` on a relation field
+	* reads through the ref (or refs, or page of refs) the field holds into the
+	* target's fields; a scalar field cannot take one.
+	*/
+	make: (entity, selection) => {
+		if (Object.keys(selection).length === 0) throw new Error(`Selection.make: a selection of "${entity.name}" picks at least one field`);
+		const picked = {};
+		const connections = {};
+		const relations = {};
+		for (const key of Object.keys(selection)) {
+			const choice = selection[key];
+			if (choice === true) {
+				picked[key] = entity.fields[key];
+				continue;
+			}
+			const nested = choice;
+			const shape = relationShape(entity.fields[key]);
+			if (shape === void 0) throw new Error(`Selection.make: "${key}" on "${entity.name}" is not a relation field, so it cannot take a nested selection`);
+			if (nested.entity !== shape.entity) throw new Error(`Selection.make: "${key}" on "${entity.name}" refers to "${shape.entity}", not "${nested.entity}"`);
+			const nullable = (codec) => shape.nullable ? Schema.NullOr(codec) : codec;
+			if (nested.window !== void 0) {
+				connections[key] = nested.window;
+				picked[key] = nullable(nested.schema);
+				if (nested.fields.length > 0) relations[key] = relationOf(nested);
+				continue;
+			}
+			const item = nested.schema;
+			picked[key] = nullable(shape.kind === "many" ? Schema.Array(item) : shape.kind === "page" ? pageSchema(item) : item);
+			relations[key] = relationOf(nested);
+		}
+		return {
+			entity: entity.name,
+			fields: Object.keys(selection),
+			schema: Schema.Struct(picked),
+			...Object.keys(connections).length === 0 ? {} : { connections },
+			...Object.keys(relations).length === 0 ? {} : { relations }
+		};
+	},
+	/**
+	* A paginated relation: one page of refs to `entity` with a window, or, with
+	* a nested selection, one page of targets assembled through it.
+	*/
+	connection: ((entity, window, selection) => {
+		if (selection !== void 0 && selection.entity !== entity.name) throw new Error(`Selection.connection: a page of "${entity.name}" cannot select "${selection.entity}"`);
+		return {
+			entity: entity.name,
+			fields: selection?.fields ?? [],
+			schema: selection === void 0 ? Entity.refPage(entity) : pageSchema(selection.schema),
+			window,
+			...selection?.connections === void 0 ? {} : { connections: selection.connections },
+			...selection?.relations === void 0 ? {} : { relations: selection.relations }
+		};
+	})
+};
+/**
+* Reads an entity's selected fields out of the store, following each nested
+* relation into its targets. `undefined` means some field, at any depth, is
+* not present yet. A tombstoned target reads as `null` (or is dropped from a
+* list), so the Selection's codec decides whether that is a failure.
+*/
+const assemble = (store, key, requirement) => {
+	const values = {};
+	let refreshing = false;
+	for (const field of requirement.fields) {
+		const value = readField(store, key, field);
+		if (Option.isNone(value)) return void 0;
+		refreshing ||= isFieldStale(store, key, field);
+		const relation = requirement.relations?.[field];
+		if (relation === void 0) {
+			values[field] = value.value;
+			continue;
+		}
+		const nested = assembleRelation(store, value.value, relation);
+		if (nested === void 0) return void 0;
+		values[field] = nested.values;
+		refreshing ||= nested.refreshing;
+	}
+	return {
+		values,
+		refreshing
+	};
+};
+const assembleTarget = (store, ref, relation) => {
+	const key = entityKey(ref.entity, ref.id);
+	return isTombstone(store, key) ? "absent" : assemble(store, key, relation);
+};
+/** Assembles the targets a relation value refers to, in the value's own shape. */
+const assembleRelation = (store, value, relation) => {
+	if (value === null || value === void 0) return {
+		values: null,
+		refreshing: false
+	};
+	const targets = [];
+	let refreshing = false;
+	for (const ref of targetsOf(value, relation)) {
+		const target = assembleTarget(store, ref, relation);
+		if (target === void 0) return void 0;
+		if (target === "absent") continue;
+		targets.push(target.values);
+		refreshing ||= target.refreshing;
+	}
+	if (typeof value === "string") return {
+		values: targets.length === 0 ? null : targets[0],
+		refreshing
+	};
+	if (isRefPage(value)) return {
+		values: {
+			items: targets,
+			hasNext: value.hasNext,
+			hasPrevious: value.hasPrevious
+		},
+		refreshing
+	};
+	return {
+		values: targets,
+		refreshing
+	};
+};
+//#endregion
+//#region src/index.ts
+/**
+* `foldkit-remote` — normalized application-facing server state.
+*
+* The pure core (entities, selections, the store, the planner, connections,
+* live classification, optimistic layers) performs no I/O. The `Remote.*`
+* helpers that read or mutate go through the `RemoteClient` Effect service.
+*/
+/**
+* The store a read or plan sees: the base with every pending optimistic layer
+* applied, so a request's patches show until it settles and a temporary id is
+* not planned as a fetch.
+*/
+const storeOf = (bound, model) => {
+	const remote = bound.store.get(model);
+	return visibleStoreOf(remote.entities, remote.optimistic);
+};
+const visibleStores = /* @__PURE__ */ new WeakMap();
+const visibleStoreOf = (entities, optimistic) => {
+	let byStore = visibleStores.get(optimistic);
+	if (byStore === void 0) {
+		byStore = /* @__PURE__ */ new WeakMap();
+		visibleStores.set(optimistic, byStore);
+	}
+	let visible = byStore.get(entities);
+	if (visible === void 0) {
+		visible = visibleStore(entities, optimistic);
+		byStore.set(entities, visible);
+	}
+	return visible;
+};
+const readResults = /* @__PURE__ */ new WeakMap();
+const memoRead = (snapshot, by, key, compute) => {
+	let byScope = readResults.get(snapshot);
+	if (byScope === void 0) {
+		byScope = /* @__PURE__ */ new WeakMap();
+		readResults.set(snapshot, byScope);
+	}
+	let results = byScope.get(by);
+	if (results === void 0) {
+		results = /* @__PURE__ */ new Map();
+		byScope.set(by, results);
+	}
+	if (results.has(key)) return results.get(key);
+	const value = compute();
+	results.set(key, value);
+	return value;
+};
+/** The default `toMessage`: the application reduces `RemoteMessage` itself. */
+const identityMessage = (message) => message;
+/** A stable key for a live subscription's requirement set. */
+const liveStreamKey = (requirements) => requirements.map((requirement) => `${entityKey(requirement.entity, requirement.id)}:${[...requirement.fields].sort().join(",")}`).sort().join("|");
+/** Declares a Remote domain: its entities, queries, and mutations, plus the submodel. */
+const defineRemote = (config) => ({
+	entities: config.entities,
+	queries: config.queries ?? [],
+	mutations: config.mutations ?? [],
+	Model: remoteModelSchema(),
+	initial: initialRemoteModel,
+	Message: remoteMessageSchema,
+	update: updateRemote,
+	rpc: RemoteRpc,
+	registry: {
+		entities: new Map(config.entities.map((entity) => [entity.name, entity])),
+		queries: new Map((config.queries ?? []).map((query) => [query.name, query])),
+		mutations: new Map((config.mutations ?? []).map((mutation) => [mutation.name, mutation]))
+	}
+});
+/** Binds a Remote domain to its store's location in the application Model. */
+const bindRemote = (definition, store) => ({
+	definition,
+	store,
+	contract: {
+		kind: "remote",
+		name: store.dependency.join(".") || "remote",
+		owner: store.owner,
+		owns: store.dependency.length === 0 ? [] : [store.dependency],
+		observes: store.dependency.length === 0 ? [] : [store.dependency],
+		messages: [],
+		requirements: []
+	}
+});
+/** The runtime half of `Registered`: a descriptor the domain never declared is an error naming both. */
+const assertRegistered = (bound, kind, registered, name) => {
+	if (!registered.has(name)) throw new Error(`Remote: ${kind} "${name}" is not registered with domain "${bound.contract.name}"`);
+};
+const nothingAsked = {
+	requirements: [],
+	connections: []
+};
+const askedOf = (projection) => projection === void 0 ? nothingAsked : projection;
+/**
+* Plans what a projection asks against the Model. A connection the Model holds
+* fresh contributes its visible items' selected fields to the entity plan; one
+* it does not hold, or holds stale, is a query to run (its items are planned
+* once the page arrives).
+*/
+const planAsked = (remote, asked, options) => {
+	const queries = [];
+	const items = [];
+	const connections = Requirement.mergeConnections(asked.connections);
+	for (const connection of connections) {
+		const known = remote.connections[connection.identity];
+		if (known === void 0 || known.stale || options.force === true) {
+			queries.push(connection);
+			continue;
+		}
+		const edges = visibleItems(known, connection.identity, remote.optimistic.overlays, remote.entities);
+		items.push(...itemsOf(edges.map((edge) => edge.ref), connection.select));
+	}
+	return {
+		requirements: plan(visibleStoreOf(remote.entities, remote.optimistic), [...asked.requirements, ...items], options),
+		queries
+	};
+};
+/** The entity requirements a page's edges add under a selection. */
+const itemsOf = (edges, select) => edges.filter((edge) => edge.entity === select.entity).map((edge) => ({
+	...select,
+	id: edge.id
+}));
+/**
+* The wire request of a planned query; a `QueryRef` identity carries the query
+* name and the canonical encoded input. A connection requirement built by hand
+* with another identity cannot be run, and fails as a query would.
+*/
+const queryRequestOf = (query) => {
+	const separator = query.identity.indexOf("\0");
+	if (separator < 0) return Effect.fail(new RemoteQueryError({ message: `connection "${query.identity}" is not a query's: only a QueryRef identity can be run` }));
+	return Effect.try({
+		try: () => ({
+			query: query.identity.slice(0, separator),
+			input: JSON.parse(query.identity.slice(separator + 1)),
+			window: query.window
+		}),
+		catch: () => new RemoteQueryError({ message: `connection "${query.identity}" carries no encoded input` })
+	});
+};
+/**
+* The `ConnectionMerged` for a query result, in the client's edge shape.
+* `refreshes` marks the page as answering the connection's refresh, so one
+* Message both merges it and clears `stale`.
+*/
+const pageMessage = (connection, result, refreshes = false) => ({
+	_tag: "ConnectionMerged",
+	connection,
+	page: {
+		edges: result.edges.map((edge) => ({
+			key: edge.key,
+			ref: {
+				entity: edge.entity,
+				id: edge.id
+			}
+		})),
+		start: result.start,
+		end: result.end
+	},
+	...refreshes ? { refreshes } : {}
+});
+/**
+* The retention roots of some projections: their requirements, their
+* connections (each with the union of what the projections select of its
+* items), and the connections listed by identity alone.
+*/
+const rootsOf = (projections, options) => {
+	const connections = /* @__PURE__ */ new Map();
+	for (const identity of (options.connections ?? []).map(connectionIdentity)) connections.set(identity, { identity });
+	for (const { identity, select } of projections.flatMap((projection) => projection.connections)) {
+		const current = connections.get(identity)?.select;
+		connections.set(identity, {
+			identity,
+			select: current === void 0 ? select : Requirement.mergeRelation(current, select)
+		});
+	}
+	return {
+		requirements: Requirement.merge(projections.flatMap((projection) => projection.requirements)),
+		connections: [...connections.values()].sort((a, b) => a.identity < b.identity ? -1 : 1)
+	};
+};
+/** A query the read entry runs, as its dependencies carry it: plain data Foldkit compares. */
+const PlannedQuery = Schema.Struct({
+	identity: Schema.String,
+	window: WindowSchema,
+	select: RelationRequest
+});
+/**
+* The read entry: plans what `askedOf(model)` asks against the Model and runs
+* the entity read and the queries concurrently. Each Message it emits changes
+* the Model, so Foldkit recomputes the dependencies and restarts the stream
+* (`switchMap`): a merged page's items are planned by that next computation,
+* against the store as it then is, rather than read here unplanned. Nothing
+* the entry needs is spread over two Messages, since the second could be lost
+* to the restart; a page and its refresh are one `ConnectionMerged`.
+*/
+const observeEntry = (bound, askedOf, toMessage, options) => {
+	const { policy = RemotePolicy.cacheFirst, now = Date.now } = options;
+	const read = (requirements) => Effect.gen(function* () {
+		const client = yield* RemoteClient;
+		const at = now();
+		const result = yield* Effect.result(client.read({
+			version: 3,
+			requests: requirements
+		}));
+		return Result.isFailure(result) ? toMessage({
+			_tag: "ReadFailed",
+			requests: requirements,
+			error: remoteError(result.failure)
+		}) : toMessage({
+			_tag: "ReadReceived",
+			requests: requirements,
+			result: result.success,
+			now: at
+		});
+	});
+	const run = (query) => Effect.gen(function* () {
+		const client = yield* RemoteClient;
+		const result = yield* Effect.result(queryRequestOf(query).pipe(Effect.flatMap((request) => client.query(request))));
+		return Result.isFailure(result) ? toMessage({
+			_tag: "QueryFailed",
+			connection: query.identity,
+			error: remoteError(result.failure)
+		}) : toMessage(pageMessage(query.identity, result.success, true));
+	});
+	return {
+		dependenciesSchema: Schema.Struct({
+			requirements: Schema.Array(ReadRequest),
+			queries: Schema.Array(PlannedQuery)
+		}),
+		modelToDependencies: (model) => {
+			const planned = planAsked(bound.store.get(model), askedOf(model), RemotePolicy.toPlan(policy, now()));
+			return {
+				requirements: planned.requirements,
+				queries: planned.queries.map(({ identity, window, select }) => ({
+					identity,
+					window,
+					select
+				}))
+			};
+		},
+		dependenciesToStream: ({ requirements, queries }) => Stream.concat(RemotePolicy.refreshes(policy) && requirements.length > 0 ? Stream.succeed(toMessage({
+			_tag: "RefreshStarted",
+			requests: requirements
+		})) : Stream.empty, Stream.mergeAll([...requirements.length === 0 ? [] : [Stream.fromEffect(read(requirements))], ...queries.map((query) => Stream.fromEffect(run(query)))], { concurrency: "unbounded" }))
+	};
+};
+/** The live entry: subscribes to `requirementsOf(model)` from the Model's resume cursor. */
+const liveEntry = (bound, requirementsOf, toMessage, options) => ({
+	dependenciesSchema: Schema.Struct({
+		requirements: Schema.Array(ReadRequest),
+		cursor: Schema.Number
+	}),
+	modelToDependencies: (model) => {
+		const requirements = requirementsOf(model);
+		const stream = liveStreamKey(requirements);
+		return {
+			requirements,
+			cursor: bound.store.get(model).live[stream]?.cursor ?? 0
+		};
+	},
+	dependenciesToStream: ({ requirements, cursor }) => requirements.length === 0 ? Stream.empty : Stream.unwrap(Effect.gen(function* () {
+		return (yield* RemoteClient).live({
+			requirements,
+			after: cursor
+		});
+	})).pipe(Stream.map((event) => toMessage({
+		_tag: "LiveReceived",
+		stream: liveStreamKey(requirements),
+		event,
+		now: (options.now ?? Date.now)()
+	})), Stream.catchIf((_error) => true, (error) => Stream.succeed(toMessage({
+		_tag: "ReadFailed",
+		requests: requirements,
+		error: remoteError(error)
+	}))))
+});
+/** The projection an active Surface has for this Model, if it is active. */
+const projectionOf = (entry, model) => "projectionOf" in entry ? entry.projectionOf(model) : entry.projection();
+/**
+* `projectionOf` computed once per Model: the read, live, and retain entries
+* all derive their dependencies from the same projection on the same Model
+* change, and a Surface's `model` callback (which lifts and builds schemas)
+* need not run three times for it. Models are objects, so the memo is weak.
+*/
+const memoizedProjectionOf = (entry) => {
+	const cache = /* @__PURE__ */ new WeakMap();
+	return (model) => {
+		const key = model;
+		if (typeof key !== "object" || key === null) return projectionOf(entry, model);
+		if (cache.has(key)) return cache.get(key);
+		const projection = projectionOf(entry, model);
+		cache.set(key, projection);
+		return projection;
+	};
+};
+const Remote = {
+	/** The submodel's schema, the same for every domain; embed it in the application Model. */
+	Model: remoteModelSchema(),
+	/** The submodel's initial value. */
+	initial: initialRemoteModel,
+	/**
+	* Remote's Message cases for `defineMessageUnion`: spread them into the
+	* application's union, and reduce the ones `Remote.reduces` recognizes with
+	* `RemoteDomain.reduce`.
+	*/
+	messages: remoteMessageCases,
+	/** Whether a Message is one of Remote's, by tag. */
+	reduces: isRemoteMessage,
+	/**
+	* Declares a Remote domain and binds it to its place in the application Model
+	* in one step; the result carries the application-facing operations. The
+	* descriptor alone is `Remote.define`, the binding alone `Remote.at`.
+	*/
+	make: (config) => bindDomain(defineRemote(config), config.model),
+	/**
+	* Declares a Remote domain without binding it: its entities, queries, and
+	* mutations, plus the submodel. For a domain reused across applications or
+	* bound in a test; `Remote.make` is the one-step form.
+	*/
+	define: defineRemote,
+	/**
+	* Binds a Remote domain to its store's location in the application Model. The
+	* registered entity names are carried on the returned value, so `Remote.select`
+	* rejects a selection for an entity this domain never declared.
+	*/
+	at: bindRemote,
+	/**
+	* A Projection node that reads a `RemoteData` value out of the store. The id
+	* is supplied by the caller, usually from a Surface's params. The assembled
+	* value is decoded against the Selection, so malformed server data surfaces
+	* as `Failed` instead of being asserted into `Value`. A present value with a
+	* stale field reads as `Refreshing`: an observer is refetching it.
+	*/
+	select: (bound, selection) => {
+		assertRegistered(bound, "Entity", bound.definition.registry.entities, selection.entity);
+		const relation = relationOf(selection);
+		return (id) => ({
+			Model: remoteDataSchema(selection.schema),
+			dependencies: [],
+			requirements: [{
+				...relation,
+				id
+			}],
+			connections: [],
+			read: (root) => {
+				const store = storeOf(bound, root);
+				const key = entityKey(selection.entity, id);
+				return memoRead(store, store, `${key}\u0000${stableStringify(relation)}`, () => {
+					if (isTombstone(store, key)) return { _tag: "NotFound" };
+					const assembled = assemble(store, key, relation);
+					if (assembled === void 0) return { _tag: "Initial" };
+					const decoded = Schema.decodeUnknownResult(selection.schema)(assembled.values);
+					return Result.isFailure(decoded) ? {
+						_tag: "Failed",
+						error: {
+							_tag: "DecodeError",
+							message: decoded.failure.message
+						}
+					} : assembled.refreshing ? {
+						_tag: "Refreshing",
+						value: decoded.success
+					} : {
+						_tag: "Ready",
+						value: decoded.success
+					};
+				});
+			}
+		});
+	},
+	/**
+	* The pure plan for a projection against a Model: the requirements its
+	* remote store does not satisfy, under `options` (freshness, force). A
+	* Surface's projection is `surface.projection(params)`.
+	*/
+	plan: (bound, model, projection, options) => planAsked(bound.store.get(model), projection, options ?? {}).requirements,
+	/**
+	* The queries a projection needs run before its connections read: those the
+	* Model does not hold, or holds stale (every one under `force`).
+	*/
+	planQueries: (bound, model, projection, options) => planAsked(bound.store.get(model), projection, options ?? {}).queries.flatMap((query) => query.ref === void 0 ? [] : [query.ref]),
+	/**
+	* The store reads see: the base store under the pending optimistic layers.
+	* One store is shared by every read and plan of a Model whose remote state
+	* has not changed.
+	*/
+	storeOf: (bound, model) => storeOf(bound, model),
+	/**
+	* Executes the plan against the `RemoteClient` and returns a new store. Used
+	* for SSR route prefetch, hover prefetch, and tests. Never called during render.
+	* `policy` decides what a present field means (default cache-first); `now`
+	* is the clock it reads, so the planner itself stays pure and time-injected.
+	*/
+	prefetch: Effect.fn("Remote.prefetch")(function* (bound, model, projection, options = {}) {
+		const store = storeOf(bound, model);
+		const { policy = RemotePolicy.cacheFirst, now = Date.now } = options;
+		const at = now();
+		const missing = plan(store, projection.requirements, RemotePolicy.toPlan(policy, at));
+		if (missing.length === 0) return store;
+		yield* Effect.annotateCurrentSpan("requirementCount", missing.length);
+		const result = yield* (yield* RemoteClient).read({
+			version: 3,
+			requests: missing
+		});
+		return writeRead(store, missing, result, at);
+	}),
+	/**
+	* Writes a read result into the store, recording each field's applied window.
+	* `requests` are the planned requirements the result answers.
+	*/
+	writeRead,
+	/**
+	* Adapts an Effect RPC client for `RemoteRpc` to `RemoteClient`, so an
+	* application provides the transport's RPC layer instead of writing the
+	* `LiveChange`-to-`LiveEvent` mapping by hand.
+	*/
+	clientLayer: (client, options = {}) => coalescedLayer(Layer.effect(RemoteClient, Effect.gen(function* () {
+		const context = yield* Effect.context();
+		return {
+			read: (batch) => client.FoldkitRemoteRead(batch).pipe(Effect.provideContext(context)),
+			query: (request) => client.FoldkitRemoteQuery(request).pipe(Effect.provideContext(context)),
+			mutate: (request) => client.FoldkitRemoteMutate(request).pipe(Effect.provideContext(context)),
+			live: ({ requirements, after }) => client.FoldkitRemoteLive({
+				version: 3,
+				requirements,
+				after
+			}).pipe(Stream.map(liveEventOf), Stream.provideContext(context))
+		};
+	})), options),
+	/**
+	* Wraps a `RemoteClient` layer so its reads coalesce: requirements issued
+	* together become one batch, and a requirement already in flight is joined.
+	* `Remote.clientLayer` applies this; use it on a hand-written client.
+	*/
+	coalesced: coalescedLayer,
+	/**
+	* A Foldkit Subscription entry that keeps the cache to what the active
+	* Surfaces reach. `projections` are the ones the application observes (the
+	* same it passes to `Remote.observe`), `connections` the query connections
+	* it shows; anything else is collected once the roots have been stable for
+	* `grace`, so a route transition that comes straight back does not thrash.
+	*/
+	retain: (projections, toMessage = identityMessage, options = {}) => {
+		const roots = rootsOf(projections, options);
+		return {
+			dependenciesSchema: retentionRootsSchema,
+			modelToDependencies: () => roots,
+			dependenciesToStream: (current) => Stream.fromEffect(Effect.succeed(toMessage({
+				_tag: "RetentionChanged",
+				roots: current
+			})).pipe(Effect.delay(options.grace ?? 0)))
+		};
+	},
+	/**
+	* Runs a `Query` through `RemoteClient`, encoding its input from the ref.
+	* Pair the result with `Remote.queryMessage` to merge the page into the Model.
+	*/
+	query: Effect.fn("Remote.query")(function* (ref) {
+		const client = yield* RemoteClient;
+		const input = yield* Schema.encodeUnknownEffect(ref.Input)(ref.input).pipe(Effect.catchTag("SchemaError", (error) => Effect.fail(new RemoteQueryError({ message: error.message }))));
+		return yield* client.query({
+			query: ref.query,
+			input,
+			window: ref.window
+		});
+	}),
+	/** The `RemoteMessage` that merges a query page into its connection. */
+	queryMessage: (ref, result) => pageMessage(ref.identity, result),
+	/**
+	* The edges a connection shows: its server-known region with pending and
+	* confirmed overlays placed around it, minus removed edges and edges whose
+	* target is a tombstone.
+	*/
+	visibleItems: (model, connection) => {
+		const identity = connectionIdentity(connection);
+		return visibleItems(model.connections[identity] ?? emptyConnection, identity, model.optimistic.overlays, model.entities);
+	},
+	/** A pure, serializable view of the whole cache. */
+	inspect: inspectRemote,
+	/** A pure, serializable view of one entity, or `undefined` if unknown. */
+	inspectEntity,
+	/**
+	* Runs a mutation through `RemoteClient`, decoding its typed Output and
+	* returning the result's normalized patches so the caller can reconcile them
+	* through `Remote.update`'s `MutationSucceeded` (or `Remote.mutateInto`).
+	*/
+	mutate: mutateRemote,
+	/**
+	* Runs a mutation and reconciles its patches into a `RemoteModel` in one step,
+	* returning the new model alongside the typed Output. The model-level form of
+	* `MutationStarted` → `RemoteClient.mutate` → `MutationSucceeded`; in an
+	* application the three are `update` (with `optimistic`), a Command, and the
+	* Message the Command returns, so the optimistic operations show meanwhile.
+	*/
+	mutateInto: Effect.fn("Remote.mutateInto")(function* (bound, model, mutation, input, requestId, options = {}) {
+		const started = updateRemote(bound.store.get(model), {
+			_tag: "MutationStarted",
+			requestId,
+			...options.optimistic === void 0 ? {} : { optimistic: options.optimistic }
+		});
+		const outcome = yield* mutateRemote(mutation, input, requestId);
+		const settled = updateRemote(started, {
+			_tag: "MutationSucceeded",
+			requestId,
+			entities: outcome.entities,
+			connections: outcome.connections
+		});
+		return {
+			output: outcome.output,
+			model: bound.store.set(model, settled)
+		};
+	}),
+	/**
+	* A Foldkit Subscription entry that plans a Surface's missing fields from the
+	* Model and fetches them through `RemoteClient`, emitting a `RemoteMessage`
+	* per outcome. Wrap it in an application Message (`toMessage`) and reduce it
+	* with the domain's `update`. Under a refreshing `policy` the entry first
+	* emits `RefreshStarted`, so the fields being refetched read as `Refreshing`
+	* while the request is pending.
+	*/
+	observe: (bound, surface, params, toMessage = identityMessage, options = {}) => observeEntry(bound, () => surface.projection(params), toMessage, options),
+	/**
+	* A Foldkit Subscription entry that consumes the live stream for a Surface's
+	* requirements, emitting a `LiveReceived` per event and a `ReadFailed` when
+	* the stream breaks (including `ResumeUnavailable`). The resume cursor is read
+	* from `RemoteModel.live`, so the application tracks no cursor of its own.
+	*/
+	live: (bound, surface, params, toMessage = identityMessage, options = {}) => liveEntry(bound, () => surface.projection(params).requirements, toMessage, options)
+};
+/** The bound domain: the descriptor, the binding, and the operations over them. */
+const bindDomain = (definition, store) => {
+	const bound = bindRemote(definition, store);
+	const reduce = (model, message) => store.set(model, updateRemote(store.get(model), message));
+	return {
+		...definition,
+		...bound,
+		get: (selection, id) => Remote.select(bound, selection)(id),
+		live: (selection, id) => {
+			const projection = Remote.select(bound, selection)(id);
+			return {
+				...projection,
+				requirements: projection.requirements.map((requirement) => ({
+					...requirement,
+					live: true
+				}))
+			};
+		},
+		subscriptions: (active, options = {}) => {
+			const entries = {};
+			const projections = [];
+			for (const [key, entry] of Object.entries(active)) {
+				if (bound.contract.owner !== void 0 && entry.owner !== bound.contract.owner) throw new Error(`Remote: Surface "${entry.name}" belongs to another application than domain "${bound.contract.name}"`);
+				const projectionAt = memoizedProjectionOf(entry);
+				projections.push(projectionAt);
+				const asked = (model) => askedOf(projectionAt(model));
+				entries[`${key}.read`] = observeEntry(bound, asked, identityMessage, options);
+				entries[`${key}.live`] = liveEntry(bound, (model) => asked(model).requirements.filter((requirement) => requirement.live === true), identityMessage, options);
+			}
+			entries.retain = {
+				dependenciesSchema: retentionRootsSchema,
+				modelToDependencies: (model) => rootsOf(projections.flatMap((projectionAt) => {
+					const projection = projectionAt(model);
+					return projection === void 0 ? [] : [projection];
+				}), options),
+				dependenciesToStream: (current) => Stream.fromEffect(Effect.succeed({
+					_tag: "RetentionChanged",
+					roots: current
+				}).pipe(Effect.delay(options.grace ?? 0)))
+			};
+			return entries;
+		},
+		plan: (model, projection, options) => Remote.plan(bound, model, projection, options),
+		storeOf: (model) => storeOf(bound, model),
+		prefetch: (model, projection, options = {}) => Effect.gen(function* () {
+			const { policy = RemotePolicy.cacheFirst, now = Date.now } = options;
+			const client = yield* RemoteClient;
+			const planOptions = RemotePolicy.toPlan(policy, now());
+			let current = model;
+			for (const query of planAsked(store.get(current), projection, planOptions).queries) {
+				const page = yield* queryRequestOf(query).pipe(Effect.flatMap((request) => client.query(request)));
+				current = reduce(current, pageMessage(query.identity, page, true));
+			}
+			const requirements = planAsked(store.get(current), projection, planOptions).requirements;
+			if (requirements.length === 0) return current;
+			const at = now();
+			const result = yield* client.read({
+				version: 3,
+				requests: requirements
+			});
+			return reduce(current, {
+				_tag: "ReadReceived",
+				requests: requirements,
+				result,
+				now: at
+			});
+		}),
+		query: (query, input, options) => {
+			assertRegistered(bound, "Query", definition.registry.queries, query.name);
+			const { select, ...window } = options;
+			for (const [side, size] of [["first", window.first], ["last", window.last]]) if (size !== void 0 && !(Number.isInteger(size) && size >= 0)) throw new Error(`Remote: query "${query.name}" asks for ${side}: ${String(size)}; a page size is a non-negative integer`);
+			const listed = query.Result.entity;
+			if (listed === void 0) throw new Error(`Remote: query "${query.name}" is not a connection over an entity, so it has no page to select`);
+			if (select.entity !== listed) throw new Error(`Remote: the selection is of "${select.entity}", but query "${query.name}" lists "${listed}"`);
+			const ref = {
+				...query.ref(input),
+				window: pickWindow(window)
+			};
+			const relation = relationOf(select);
+			const relationKey = stableStringify(relation);
+			const requirement = {
+				identity: ref.identity,
+				window: ref.window,
+				select: relation,
+				ref
+			};
+			return {
+				Model: remoteDataSchema(pageSchema(select.schema)),
+				dependencies: [],
+				requirements: [],
+				connections: [requirement],
+				ref,
+				read: (root) => {
+					const remote = store.get(root);
+					const connection = remote.connections[ref.identity];
+					if (connection === void 0 || connection.stale && connection.segments.length === 0) return { _tag: "Initial" };
+					const visible = visibleStoreOf(remote.entities, remote.optimistic);
+					return memoRead(visible, connection, `${ref.identity}\u0000${relationKey}`, () => {
+						const items = [];
+						let refreshing = connection.stale;
+						const edges = visibleItems(connection, ref.identity, remote.optimistic.overlays, remote.entities);
+						for (const edge of edges) {
+							const assembled = assemble(visible, entityKey(edge.ref.entity, edge.ref.id), relation);
+							if (assembled === void 0) return { _tag: "Initial" };
+							const decoded = Schema.decodeUnknownResult(select.schema)(assembled.values);
+							if (Result.isFailure(decoded)) return {
+								_tag: "Failed",
+								error: {
+									_tag: "DecodeError",
+									message: decoded.failure.message
+								}
+							};
+							refreshing ||= assembled.refreshing;
+							items.push(decoded.success);
+						}
+						const page = {
+							items,
+							hasNext: hasNext(connection),
+							hasPrevious: hasPrevious(connection)
+						};
+						return refreshing ? {
+							_tag: "Refreshing",
+							value: page
+						} : {
+							_tag: "Ready",
+							value: page
+						};
+					});
+				}
+			};
+		},
+		next: (model, projection) => {
+			const segments = store.get(model).connections[projection.ref.identity]?.segments ?? [];
+			const end = segments[segments.length - 1]?.end;
+			return end?._tag === "Cursor" ? {
+				...projection.ref,
+				window: {
+					...pageSize(projection.ref.window, "first"),
+					after: end.cursor
+				}
+			} : void 0;
+		},
+		previous: (model, projection) => {
+			const start = store.get(model).connections[projection.ref.identity]?.segments[0]?.start;
+			return start?._tag === "Cursor" ? {
+				...projection.ref,
+				window: {
+					...pageSize(projection.ref.window, "last"),
+					before: start.cursor
+				}
+			} : void 0;
+		},
+		fetch: (ref) => ({
+			name: `Remote.query(${ref.query})`,
+			args: {
+				connection: ref.identity,
+				window: ref.window
+			},
+			effect: Remote.query(ref).pipe(Effect.match({
+				onFailure: (error) => ({
+					_tag: "QueryFailed",
+					connection: ref.identity,
+					error: remoteError(error)
+				}),
+				onSuccess: (page) => pageMessage(ref.identity, page)
+			}))
+		}),
+		mutate: (model, mutation, input, options = {}) => {
+			assertRegistered(bound, "Mutation", definition.registry.mutations, mutation.name);
+			const remote = store.get(model);
+			const requestId = options.requestId ?? `${bound.contract.name}-${remote.mutations.sequence + 1}`;
+			const tempId = `${requestId}.tmp`;
+			const optimistic = typeof options.optimistic === "function" ? options.optimistic({
+				requestId,
+				tempId
+			}) : options.optimistic;
+			const started = updateRemote(remote, {
+				_tag: "MutationStarted",
+				requestId,
+				...optimistic === void 0 ? {} : { optimistic }
+			});
+			return {
+				model: store.set(model, started),
+				requestId,
+				tempId,
+				command: {
+					name: `Remote.mutate(${mutation.name})`,
+					args: { requestId },
+					effect: mutateRemote(mutation, input, requestId).pipe(Effect.match({
+						onFailure: (error) => ({
+							_tag: "MutationFailed",
+							requestId,
+							error: remoteError(error)
+						}),
+						onSuccess: (outcome) => ({
+							_tag: "MutationSucceeded",
+							requestId,
+							entities: outcome.entities,
+							connections: outcome.connections
+						})
+					}))
+				}
+			};
+		},
+		reduce,
+		inspect: (model) => inspectRemote(store.get(model))
+	};
+};
+/** The window keys of a `QueryOptions`, and only those, without the undefined ones. */
+const pickWindow = (window) => ({
+	...window.first === void 0 ? {} : { first: window.first },
+	...window.last === void 0 ? {} : { last: window.last },
+	...window.after === void 0 ? {} : { after: window.after },
+	...window.before === void 0 ? {} : { before: window.before }
+});
+/** The page size of a window, carried onto the next or previous page's window under `key`. */
+const pageSize = (window, key) => {
+	const size = window.first ?? window.last;
+	return size === void 0 ? {} : { [key]: size };
+};
+//#endregion
+export { ConnectionChange, ConnectionChangeSchema, Entity, Live, LiveChange, LiveEdge, LiveRequirement, MAX_FIELDS_PER_REQUEST, MAX_RELATION_DEPTH, Mutate, Mutation, MutationRequest, MutationResult, NormalizedEntity, PageSize, Query, QueryEdge, QueryRequest, QueryResult, QueryRpc, REMOTE_CACHE_VERSION, REMOTE_PROTOCOL_VERSION, Read, ReadBatch, ReadBatchResult, ReadRequest, RelationAnnotation, RelationEntityAnnotation, RelationRequest, Remote, RemoteClient, RemoteData, RemoteLiveError, RemoteMutationError, RemotePersistence, RemotePolicy, RemoteProtocolError, RemoteQueryError, RemoteReadError, RemoteRpc, Selection, WindowSchema, WireBoundary, addLayer, addOverlay, applyConnectionEvent, applyEntityEvent, assemble, beginMutation, beginOptimistic, classifyLive, clearStale, coalesceQueries, coalesceReads, coalescedLayer, connectionChangeOf, connectionIdentity, cursor, edge, emptyConnection, emptyLiveState, emptyMutationState, emptyOptimistic, emptyStore, entityKey, entry, failMutation, gc, hasField, hasNext, hasPrevious, initialRemoteModel, inspectEntity, inspectRemote, invalidateConnection, isFieldStale, isGapped, isRefPage, isRemoteMessage, isStale, isTombstone, items, liveEventOf, liveHasNext, liveHasPrevious, markStale, merge, missingFields, mutateRemote, pageSchema, plan, pruneOverlays, reachable, readField, reconcileMutation, refParts, refreshConnection, refsIn, relationOf, relationShape, remoteDataSchema, remoteError, remoteErrorSchema, remoteMessageCases, remoteMessageSchema, remoteModelSchema, remove, removeLayer, removeOverlay, requirementKey, retentionRootsSchema, schemaOf, segment, setStale, settleFailure, settleSuccess, shouldWake, stableStringify, targetsOf, terminal, tombstone, unknown, updateRemote, visibleItems, visibleStore, windowKey, writeEntities, writeEntity, writeRead };
+
+//# sourceMappingURL=index.mjs.map