foldkit-remote 0.2.0 → 0.4.0

package/dist/index.mjs

@@ -1,7 +1,113 @@
 import { Context, Deferred, Duration, Effect, Layer, Option, Request, RequestResolver, Result, Schema, SchemaGetter, Stream } from "effect";
-import { Requirement } from "foldkit-surface";
+import * as Domain from "foldkit-entity";
+import { Entity as Entity$1, SelectionTypeId } from "foldkit-entity";
+import * as Subscription from "foldkit/subscription";
+import { Metadata } from "foldkit-surface";
 import { Rpc, RpcGroup } from "effect/unstable/rpc";
 import { KeyValueStore } from "effect/unstable/persistence";
+//#region src/requirement.ts
+/**
+* What a Remote Projection needs from the server: entity slices and query
+* connections. They ride on `Projection.metadata` under Remote's own keys, so
+* Surface composes them without knowing their shape.
+*/
+const windowKey$1 = (window) => JSON.stringify([
+	window.first ?? null,
+	window.last ?? null,
+	window.after ?? null,
+	window.before ?? null
+]);
+/**
+* Merges connection requirements for the same connection and window into one,
+* unioning what they select of each item; the first keeps its other properties.
+*/
+function mergeConnections(connections) {
+	const merged = /* @__PURE__ */ new Map();
+	for (const connection of connections) {
+		const key = `${connection.identity}\u0000${windowKey$1(connection.window)}`;
+		const current = merged.get(key);
+		merged.set(key, current === void 0 ? connection : {
+			...current,
+			select: mergeRelation(current.select, connection.select)
+		});
+	}
+	return [...merged.values()];
+}
+/** Unions two relation slices for the same target: fields, windows, and nested relations. */
+function mergeRelation(current, next) {
+	const fields = [...current.fields];
+	const seen = new Set(fields);
+	for (const field of next.fields) {
+		if (seen.has(field)) continue;
+		seen.add(field);
+		fields.push(field);
+	}
+	const windows = {
+		...current.windows,
+		...next.windows
+	};
+	const relations = mergeRelations(current.relations, next.relations);
+	return {
+		entity: current.entity,
+		fields,
+		...Object.keys(windows).length === 0 ? {} : { windows },
+		...relations === void 0 ? {} : { relations }
+	};
+}
+/** Unions two relation maps field by field; a field in both merges recursively. */
+function mergeRelations(current, next) {
+	if (current === void 0) return next;
+	if (next === void 0) return current;
+	const merged = { ...current };
+	for (const [field, relation] of Object.entries(next)) {
+		const existing = merged[field];
+		merged[field] = existing === void 0 ? relation : mergeRelation(existing, relation);
+	}
+	return merged;
+}
+/** Unions requirements for the same entity + id, dropping duplicate fields. */
+function mergeRequirements(requirements) {
+	const grouped = /* @__PURE__ */ new Map();
+	for (const requirement of requirements) {
+		const key = `${requirement.entity}\u0000${requirement.id}`;
+		const group = grouped.get(key);
+		const live = group?.live === true || requirement.live === true;
+		grouped.set(key, {
+			...mergeRelation(group ?? {
+				entity: requirement.entity,
+				fields: []
+			}, requirement),
+			id: requirement.id,
+			...live ? { live } : {}
+		});
+	}
+	return [...grouped.values()];
+}
+/**
+* Requirement helpers, for the packages that plan and serve requirements.
+* `merge` unions same-entity+id requirements; `mergeRelation` unions two
+* slices of one target (fields, windows, nested relations).
+*/
+const Requirement = {
+	merge: mergeRequirements,
+	mergeRelation,
+	mergeConnections
+};
+/** Remote's entity requirements on a Projection, unioned per entity and id as nodes compose. */
+const RemoteRequirements = Metadata.key("remote", {
+	merge: mergeRequirements,
+	summarize: (requirement) => `${requirement.entity}:${requirement.id}`
+});
+/** Remote's query connections on a Projection, unioned per connection and window. */
+const RemoteConnections = Metadata.key("remote.connection", {
+	merge: mergeConnections,
+	summarize: (connection) => connection.identity.split("\0").join(" ")
+});
+/** The entity requirements a Projection carries. */
+const requirementsOf = (projection) => RemoteRequirements.get(projection.metadata);
+/** The query connections a Projection carries. */
+const connectionsOf = (projection) => RemoteConnections.get(projection.metadata);
+//#endregion
 //#region src/store.ts
 /**
 * The pure entity store: values, per-field presence, staleness, and tombstones.
@@ -80,6 +186,7 @@ const setStale = (store, marks, stale) => {
 		for (const field of fields) if (stale) {
 			if (previous.present.has(field)) staleFields.add(field);
 		} else staleFields.delete(field);
+		if (staleFields.size === previous.stale.size) continue;
 		next ??= { ...store };
 		next[key] = {
 			...previous,
@@ -162,6 +269,7 @@ const emptyMutationState = {
 	pending: /* @__PURE__ */ new Set(),
 	applied: /* @__PURE__ */ new Set(),
 	failed: /* @__PURE__ */ new Set(),
+	errors: /* @__PURE__ */ new Map(),
 	sequence: 0
 };
 /**
@@ -184,13 +292,26 @@ const beginMutation = (state, requestId) => ({
 	pending: /* @__PURE__ */ new Set([...state.pending, requestId]),
 	sequence: state.sequence + 1
 });
-const failMutation = (state, requestId) => {
+const failMutation = (state, requestId, error) => {
 	const pending = new Set(state.pending);
 	pending.delete(requestId);
+	const failed = remember(state.failed, requestId);
+	const errors = new Map([...state.errors, [requestId, error]]);
+	for (const id of errors.keys()) if (!failed.has(id)) errors.delete(id);
 	return {
 		...state,
 		pending,
-		failed: remember(state.failed, requestId)
+		failed,
+		errors
+	};
+};
+const mutationStatus = (state, requestId) => {
+	if (state.pending.has(requestId)) return { _tag: "Pending" };
+	if (state.applied.has(requestId)) return { _tag: "Applied" };
+	const error = state.errors.get(requestId);
+	return error === void 0 ? { _tag: "Unknown" } : {
+		_tag: "Failed",
+		error
 	};
 };
 /**
@@ -198,8 +319,8 @@ const failMutation = (state, requestId) => {
 * 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 reconcileMutation = (store, state, requestId, entities, deleted = []) => {
+	const next = state.applied.has(requestId) ? store : deleted.reduce((current, gone) => tombstone(current, entityKey(gone.entity, gone.id)), 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);
@@ -397,7 +518,12 @@ 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))
+	connections: Schema.optional(Schema.Array(ConnectionChangeSchema)),
+	/** Entities the mutation deleted; the client knows them absent from then on. */
+	deleted: Schema.optional(Schema.Array(Schema.Struct({
+		entity: Schema.String,
+		id: Schema.String
+	})))
 });
 const LiveRequirement = Schema.Struct({
 	version: Schema.Number,
@@ -721,7 +847,8 @@ const mutateRemote = Effect.fn("Remote.mutate")(function* (mutation, input, requ
 	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)
+		connections: (result.connections ?? []).map(connectionChangeOf),
+		deleted: result.deleted ?? []
 	};
 });
 //#endregion
@@ -889,1324 +1016,1383 @@ const hasNext = (connection) => {
 /** 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);
+//#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)
+	};
 };
-//#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.
+* 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 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)
+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 [];
 };
-/**
-* 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")
+/** 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";
 };
 /**
-* 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.
+* 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 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)]
+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/selection.ts
 /**
-* 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.
+* 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 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 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;
 };
-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
-		}];
-	})
+/** 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 }
 });
-/** 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);
+const Selection = {
+	/**
+	* The Remote Selection of a `foldkit-entity` Selection: the same members, read
+	* from Remote's store. `true` on a relation reads its refs, as it does here.
+	*/
+	from: (selection) => {
+		const spec = {};
+		for (const [key, selected] of Object.entries(selection.members)) spec[key] = selected === true ? true : Domain.SelectionPageTypeId in selected ? Selection.connection(Entity.from(selected.selection.entity), selected.window, Selection.from(selected.selection)) : Selection.from(selected);
+		return Selection.make(Entity.from(selection.entity), spec);
+	},
+	/**
+	* 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 edges;
-	};
-	return [
-		...take("prepend"),
-		...known,
-		...take("append")
-	];
-};
-//#endregion
-//#region src/live.ts
-const emptyLiveState = {
-	cursor: 0,
-	stale: /* @__PURE__ */ new Set(),
-	boundary: {}
+		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 }
+		};
+	})
 };
 /**
-* 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.
+* 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 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 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 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);
+		const nested = assembleRelation(store, value.value, relation);
+		if (nested === void 0) return void 0;
+		values[field] = nested.values;
+		refreshing ||= nested.refreshing;
+	}
 	return {
-		state: advance(state, event.cursor),
-		store: next,
-		outcome
+		values,
+		refreshing
 	};
 };
-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
+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
 	};
-	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 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;
 	}
-};
-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);
+	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 {
-		...state,
-		stale
+		values: targets,
+		refreshing
 	};
 };
-/** `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)
-	};
-};
+//#region src/entity.ts
 /**
-* 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.
+* Entities: the descriptor an application declares, refs, ref pages, and
+* patches, with the codecs that carry refs on the wire.
 */
-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.
+* 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 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;
-		}
+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 descriptors = /* @__PURE__ */ new WeakMap();
+const relationField = (relation) => {
+	const ref = refCodec(relation.target().name);
+	return relation.cardinality === "many" ? Schema.Array(ref) : relation.optional ? Schema.NullOr(ref) : ref;
+};
+const Entity = {
+	/**
+	* The Remote descriptor of a `foldkit-entity` Entity. Relations declared with
+	* `Entity.relate` become ref fields, so the store, the planner, and the server
+	* treat it as they treat an `Entity.make` descriptor.
+	*/
+	from: (entity) => {
+		const cached = descriptors.get(entity);
+		if (cached !== void 0) return cached;
+		const members = entity.members;
+		if (members.id?._tag !== "Field") throw new Error(`Entity.from: "${entity.name}" needs an "id" field for Remote to key it by`);
+		const fields = {};
+		for (const [key, member] of Object.entries(members)) fields[key] = member._tag === "Relation" ? relationField(member) : member.schema;
+		const descriptor = Entity.make(entity.name, Schema.Struct(fields));
+		descriptors.set(entity, descriptor);
+		return descriptor;
+	},
+	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/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/plan.ts
+//#region src/optimistic.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.
+* 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.
 */
-/** 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 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 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);
+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)
 };
-//#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.
+* Constructors for connection changes: what a request shows optimistically
+* (`MutateOptions.optimistic`) and what a mutation source reports it made
+* (`MutationOutcome.connections`).
 */
-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;
+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")
 };
 /**
-* 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.
+* 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 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)]);
+const beginOptimistic = (optimistic, requestId, operations) => {
+	const patches = operations.filter((operation) => !isConnectionChange(operation));
+	const changes = operations.filter(isConnectionChange);
 	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))
-		}
+		layers: patches.length === 0 ? optimistic.layers : [...optimistic.layers, {
+			id: requestId,
+			patches
+		}],
+		overlays: [...optimistic.overlays, ...toOverlays(requestId, changes)]
 	};
 };
-//#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.
+* 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.
 */
-/** Bump when the serialized shape changes; a mismatch discards the cache. */
-const REMOTE_CACHE_VERSION = 3;
-const sorted = (values) => [...values].sort();
+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);
 /**
-* 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.
+* 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 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 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
+		}];
+	})
 });
-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");
+/** 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 = [], deleted = []) => {
+	const reconciled = reconcileMutation(base, state, requestId, entities, deleted);
 	return {
-		values: entry.values,
-		present: new Set(entry.present),
-		stale: new Set(entry.stale),
-		tombstone: entry.tombstone,
-		updatedAt: entry.updatedAt,
-		windows: entry.windows
+		store: reconciled.store,
+		state: reconciled.state,
+		optimistic: state.applied.has(requestId) ? release(optimistic, requestId) : confirm(removeLayer(optimistic, requestId), requestId, `confirmed:${requestId}`, connections)
 	};
 };
-const deserializeStore = (serialized) => Object.fromEntries(Object.entries(serialized.entities).map(([key, entry]) => [key, parseEntry(entry)]));
+/** A failed request's layer and overlays are dropped; the base was never mutated. */
+const settleFailure = (optimistic, requestId) => release(optimistic, requestId);
 /**
-* The snapshot text, or `undefined` when it would exceed `maxBytes`. Only the
-* entity store goes in; pass `model.entities`, never the whole `RemoteModel`.
+* 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 dehydrate = (store, options = {}) => {
-	const text = stableStringify(serializeStore(store, options.scope));
-	return exceeds(text, options.maxBytes) ? void 0 : text;
+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: {}
 };
 /**
-* 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.
+* 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 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;
+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])
+});
 /**
-* 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.
+* A subscriber is woken only if the event changed a field it selects. A
+* change to an unselected field is skipped entirely.
 */
-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 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 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;
+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)
 	})
-};
-//#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)
+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 "Refreshing": return {
-				_tag: "Refreshing",
-				value: f(data.value)
+			case "boundary": return {
+				state: recordBoundary(advance(state, event.cursor), event.connection, event.position),
+				optimistic,
+				outcome
 			};
-			case "Failed": return data.previous === void 0 ? {
-				_tag: "Failed",
-				error: data.error
-			} : {
-				_tag: "Failed",
-				error: data.error,
-				previous: f(data.previous)
+			case "invalidate": return {
+				state: invalidateConnection(advance(state, event.cursor), event.connection),
+				optimistic,
+				outcome
+			};
+			case "ignore": return {
+				state: advance(state, event.cursor),
+				optimistic,
+				outcome
 			};
-			default: return data;
 		}
+		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
+		};
 	}
 };
-//#endregion
-//#region src/model.ts
+const isStale = (state, connection) => state.stale.has(connection);
 /**
-* 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.
+* 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 initialRemoteModel = {
-	entities: emptyStore,
-	connections: {},
-	optimistic: emptyOptimistic,
-	live: {},
-	mutations: emptyMutationState,
-	gaps: /* @__PURE__ */ new Set(),
-	loading: /* @__PURE__ */ new Set()
+const refreshConnection = (state, connection) => {
+	if (!state.stale.has(connection)) return state;
+	const stale = new Set(state.stale);
+	stale.delete(connection);
+	return {
+		...state,
+		stale
+	};
 };
-/** 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,
-	loading: runtimeSchema
-});
-const retentionRootsSchema = Schema.Struct({
-	requirements: Schema.Array(ReadRequest),
-	connections: Schema.Array(Schema.Struct({
-		identity: Schema.String,
-		select: Schema.optional(RelationRequest)
-	}))
-});
+/** `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/plan.ts
 /**
-* The Messages' fields by tag, without `_tag`: what `defineMessageUnion` takes,
-* so an application spreads them into its own union (`Remote.messages`).
+* 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.
 */
-const remoteMessageCases = {
-	ReadReceived: {
-		requests: Schema.Array(ReadRequest),
-		result: ReadBatchResult,
-		now: Schema.Number
-	},
-	ReadFailed: {
-		requests: Schema.Array(ReadRequest),
-		error: remoteErrorSchema
-	},
-	RefreshStarted: { requests: Schema.Array(ReadRequest) },
-	ReadStarted: { 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
+/** 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
 /**
-* 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]);
-/**
-* One mark per requested field. A read is identified by what it asks for, not by
-* a request id: two reads asking for one field share its mark, so the first
-* answer clears it. Over-clearing shows `Initial` rather than a spinner, which
-* is the safer way to be wrong.
+* 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 loadingMarks = function* (requests) {
-	for (const request of requests) {
-		const key = entityKey(request.entity, request.id);
-		for (const field of request.fields) yield `${key}\u0000${field}`;
+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);
 	}
-};
-const withLoading = (loading, requests) => {
-	const next = new Set(loading);
-	for (const mark of loadingMarks(requests)) next.add(mark);
-	return next;
-};
-const withoutLoading = (loading, requests) => {
-	if (loading.size === 0) return loading;
-	const next = new Set(loading);
-	for (const mark of loadingMarks(requests)) next.delete(mark);
-	return next;
+	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;
 };
 /**
-* Whether a read is fetching any of `fields` for this entity. Consulted only
-* when the store lacks the value, which is what separates `Loading` from
-* `Initial`.
+* 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 isLoading = (model, entity, id, fields) => {
-	if (model.loading.size === 0) return false;
-	const key = entityKey(entity, id);
-	return fields.some((field) => model.loading.has(`${key}\u0000${field}`));
-};
-const setConnectionStale = (connections, connection, stale) => {
-	const current = connections[connection] ?? emptyConnection;
+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 {
-		...connections,
-		[connection]: {
-			...current,
-			stale
+		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))
 		}
 	};
 };
-const markGap = (model, stream) => model.gaps.has(stream) ? model : {
-	...model,
-	gaps: /* @__PURE__ */ new Set([...model.gaps, stream])
+//#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 clearGap = (model, stream) => model.gaps.has(stream) ? {
-	...model,
-	gaps: new Set([...model.gaps].filter((entry) => entry !== stream))
-} : model;
+const deserializeStore = (serialized) => Object.fromEntries(Object.entries(serialized.entities).map(([key, entry]) => [key, parseEntry(entry)]));
+function dehydrate(store, options = {}) {
+	const text = stableStringify(serializeStore(store, options.scope));
+	return exceeds(text, options.maxBytes) ? void 0 : text;
+}
 /**
-* 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.
+* 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 updateRemote = (model, message) => {
-	switch (message._tag) {
-		case "ReadReceived": return {
-			...model,
-			entities: writeRead(model.entities, message.requests, message.result, message.now),
-			loading: withoutLoading(model.loading, message.requests)
-		};
-		case "ReadFailed": return {
-			...model,
-			entities: setStale(model.entities, marksOf(message.requests), false),
-			loading: withoutLoading(model.loading, message.requests)
-		};
-		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 "ReadStarted": return {
-			...model,
-			loading: withLoading(model.loading, message.requests)
-		};
-		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
-	};
+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;
 };
 /**
-* 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.
+* 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 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 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;
 	}
-	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);
+	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;
 		}
-		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);
+		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();
 		}
-		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;
-			}
+	},
+	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;
 		}
-		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 };
-		}
+//#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(),
+	loading: /* @__PURE__ */ new Set(),
+	refresh: {
+		requested: 0,
+		started: 0
+	}
+};
+/** 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,
+	loading: runtimeSchema,
+	refresh: Schema.Struct({
+		requested: Schema.Number,
+		started: Schema.Number
+	})
+});
+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) },
+	ReadStarted: {
+		requests: Schema.Array(ReadRequest),
+		refresh: Schema.optional(Schema.Number)
+	},
+	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)),
+		deleted: Schema.optional(Schema.Array(Schema.Struct({
+			entity: Schema.String,
+			id: Schema.String
+		})))
+	},
+	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)
 	},
-	/**
-	* 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"
+	ConnectionInvalidated: { connection: Schema.String },
+	ConnectionRefreshed: { connection: Schema.String },
+	QueryFailed: {
+		connection: Schema.String,
+		error: remoteErrorSchema
+	}
 };
-//#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.
+* 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]);
 /**
-* 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.
+* One mark per requested field. A read is identified by what it asks for, not by
+* a request id: two reads asking for one field share its mark, so the first
+* answer clears it. Over-clearing shows `Initial` rather than a spinner, which
+* is the safer way to be wrong.
 */
-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
-	})
+const loadingMarks = function* (requests) {
+	for (const request of requests) {
+		const key = entityKey(request.entity, request.id);
+		for (const field of request.fields) yield `${key}\u0000${field}`;
+	}
+};
+const withLoading = (loading, requests) => {
+	const next = new Set(loading);
+	for (const mark of loadingMarks(requests)) next.add(mark);
+	return next;
+};
+const withoutLoading = (loading, requests) => {
+	if (loading.size === 0) return loading;
+	const next = new Set(loading);
+	for (const mark of loadingMarks(requests)) next.delete(mark);
+	return next;
 };
-//#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.
+* Whether a read is fetching any of `fields` for this entity. Consulted only
+* when the store lacks the value, which is what separates `Loading` from
+* `Initial`.
 */
-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;
+const isLoading = (model, entity, id, fields) => {
+	if (model.loading.size === 0) return false;
+	const key = entityKey(entity, id);
+	return fields.some((field) => model.loading.has(`${key}\u0000${field}`));
 };
-/** 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 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),
+			loading: withoutLoading(model.loading, message.requests)
+		};
+		case "ReadFailed": return {
+			...model,
+			entities: setStale(model.entities, marksOf(message.requests), false),
+			loading: withoutLoading(model.loading, message.requests)
+		};
+		case "RetentionChanged": return {
+			...model,
+			...gc(model, message.roots)
+		};
+		case "Hydrated": return {
+			...model,
+			entities: RemotePersistence.mergeStores(model.entities, message.entities, message.merge)
+		};
+		case "RefreshStarted": {
+			const entities = setStale(model.entities, marksOf(message.requests), true);
+			return entities === model.entities ? model : {
+				...model,
+				entities
+			};
+		}
+		case "ReadStarted": {
+			const started = Math.max(model.refresh.started, message.refresh ?? 0);
+			return {
+				...model,
+				loading: withLoading(model.loading, message.requests),
+				refresh: started === model.refresh.started ? model.refresh : {
+					...model.refresh,
+					started
+				}
+			};
+		}
+		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 ?? [], message.deleted ?? []);
+			return {
+				...model,
+				entities: settled.store,
+				mutations: settled.state,
+				optimistic: settled.optimistic
+			};
+		}
+		case "MutationFailed": return {
+			...model,
+			mutations: failMutation(model.mutations, message.requestId, message.error),
+			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 item = nested.schema;
-			picked[key] = nullable(shape.kind === "many" ? Schema.Array(item) : shape.kind === "page" ? pageSchema(item) : item);
-			relations[key] = relationOf(nested);
+			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);
 		}
-		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 }
+		case "GapCleared": return clearGap(model, message.stream);
+		case "ConnectionMerged": {
+			const current = model.connections[message.connection] ?? emptyConnection;
+			const replaces = message.refreshes === true && current.stale;
+			const merged = merge(replaces ? emptyConnection : 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":
+			if (model.connections[message.connection]?.stale === true) return model;
+			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
+	};
 };
 /**
-* 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.
+* 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 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;
+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
+		});
 	}
-	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 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);
 	};
-	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;
+	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
+		});
 	}
-	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
-	};
+	let answered = store;
+	for (const request of requests) {
+		const key = entityKey(request.entity, request.id);
+		if (!returned.has(key)) answered = tombstone(answered, key);
+	}
+	return writeEntities(answered, 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/index.ts
@@ -2217,6 +2403,8 @@ const assembleRelation = (store, value, relation) => {
 * live classification, optimistic layers) performs no I/O. The `Remote.*`
 * helpers that read or mutate go through the `RemoteClient` Effect service.
 */
+const descriptorOf = (entity) => Entity$1.is(entity) ? Entity.from(entity) : entity;
+const selectionOf = (selection) => SelectionTypeId in selection ? Selection.from(selection) : selection;
 /**
 * 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
@@ -2262,21 +2450,24 @@ 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]))
-	}
-});
+const defineRemote = (config) => {
+	const entities = config.entities.map(descriptorOf);
+	return {
+		entities,
+		queries: config.queries ?? [],
+		mutations: config.mutations ?? [],
+		Model: remoteModelSchema(),
+		initial: initialRemoteModel,
+		Message: remoteMessageSchema,
+		update: updateRemote,
+		rpc: RemoteRpc,
+		registry: {
+			entities: new Map(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,
@@ -2288,7 +2479,7 @@ const bindRemote = (definition, store) => ({
 		owns: store.dependency.length === 0 ? [] : [store.dependency],
 		observes: store.dependency.length === 0 ? [] : [store.dependency],
 		messages: [],
-		requirements: []
+		metadata: []
 	}
 });
 /** The runtime half of `Registered`: a descriptor the domain never declared is an error naming both. */
@@ -2299,7 +2490,10 @@ const nothingAsked = {
 	requirements: [],
 	connections: []
 };
-const askedOf = (projection) => projection === void 0 ? nothingAsked : projection;
+const askedOf = (projection) => projection === void 0 ? nothingAsked : {
+	requirements: requirementsOf(projection),
+	connections: connectionsOf(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
@@ -2375,7 +2569,7 @@ const pageMessage = (connection, result, refreshes = false) => ({
 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)) {
+	for (const { identity, select } of projections.flatMap(connectionsOf)) {
 		const current = connections.get(identity)?.select;
 		connections.set(identity, {
 			identity,
@@ -2383,10 +2577,39 @@ const rootsOf = (projections, options) => {
 		});
 	}
 	return {
-		requirements: Requirement.merge(projections.flatMap((projection) => projection.requirements)),
+		requirements: Requirement.merge(projections.flatMap(requirementsOf)),
 		connections: [...connections.values()].sort((a, b) => a.identity < b.identity ? -1 : 1)
 	};
 };
+/** Reads requirements and reports the Message that settles them. Never fails. */
+const readMessage = (requirements, now) => 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) ? {
+		_tag: "ReadFailed",
+		requests: requirements,
+		error: remoteError(result.failure)
+	} : {
+		_tag: "ReadReceived",
+		requests: requirements,
+		result: result.success,
+		now: at
+	};
+});
+/** Runs a query and reports the page that refreshes its connection, or the failure. Never fails. */
+const queryMessage = (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) ? {
+		_tag: "QueryFailed",
+		connection: query.identity,
+		error: remoteError(result.failure)
+	} : pageMessage(query.identity, result.success, true);
+});
 /** A query the read entry runs, as its dependencies carry it: plain data Foldkit compares. */
 const PlannedQuery = Schema.Struct({
 	identity: Schema.String,
@@ -2404,41 +2627,19 @@ const PlannedQuery = Schema.Struct({
 */
 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));
-	});
+	const read = (requirements) => Effect.map(readMessage(requirements, now), toMessage);
+	const run = (query) => Effect.map(queryMessage(query), toMessage);
 	return {
 		dependenciesSchema: Schema.Struct({
 			requirements: Schema.Array(ReadRequest),
-			queries: Schema.Array(PlannedQuery)
+			queries: Schema.Array(PlannedQuery),
+			refresh: Schema.Number
 		}),
 		modelToDependencies: (model) => {
-			const planned = planAsked(bound.store.get(model), askedOf(model), RemotePolicy.toPlan(policy, now()));
+			const remote = bound.store.get(model);
+			const planned = planAsked(remote, askedOf(model), RemotePolicy.toPlan(policy, now()));
 			return {
+				refresh: remote.refresh.requested,
 				requirements: planned.requirements,
 				queries: planned.queries.map(({ identity, window, select }) => ({
 					identity,
@@ -2447,9 +2648,10 @@ const observeEntry = (bound, askedOf, toMessage, options) => {
 				}))
 			};
 		},
-		dependenciesToStream: ({ requirements, queries }) => Stream.concat(requirements.length === 0 ? Stream.empty : Stream.fromIterable([toMessage({
+		dependenciesToStream: ({ requirements, queries, refresh }) => Stream.concat(requirements.length === 0 ? Stream.empty : Stream.fromIterable([toMessage({
 			_tag: "ReadStarted",
-			requests: requirements
+			requests: requirements,
+			refresh
 		}), ...RemotePolicy.refreshes(policy) ? [toMessage({
 			_tag: "RefreshStarted",
 			requests: requirements
@@ -2543,17 +2745,17 @@ const Remote = {
 	* 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) => {
+	select: (bound, given) => {
+		const selection = selectionOf(given);
 		assertRegistered(bound, "Entity", bound.definition.registry.entities, selection.entity);
 		const relation = relationOf(selection);
 		return (id) => ({
 			Model: remoteDataSchema(selection.schema),
 			dependencies: [],
-			requirements: [{
+			metadata: RemoteRequirements.of({
 				...relation,
 				id
-			}],
-			connections: [],
+			}),
 			read: (root) => {
 				const store = storeOf(bound, root);
 				const key = entityKey(selection.entity, id);
@@ -2586,12 +2788,12 @@ const Remote = {
 	* 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,
+	plan: (bound, model, projection, options) => planAsked(bound.store.get(model), askedOf(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]),
+	planQueries: (bound, model, projection, options) => planAsked(bound.store.get(model), askedOf(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
@@ -2608,7 +2810,7 @@ const Remote = {
 		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));
+		const missing = plan(store, requirementsOf(projection), RemotePolicy.toPlan(policy, at));
 		if (missing.length === 0) return store;
 		yield* Effect.annotateCurrentSpan("requirementCount", missing.length);
 		const result = yield* (yield* RemoteClient).read({
@@ -2618,6 +2820,52 @@ const Remote = {
 		return writeRead(store, missing, result, at);
 	}),
 	/**
+	* Marks what a projection, or a Surface without params, requires as due again.
+	* Called from `update`: every selected field the store holds reads `Refreshing`,
+	* and every loaded query connection is invalidated. Nothing is fetched here.
+	* The read entries `Data.subscriptions` derives refetch it, because a stale
+	* field or connection is planned again under every policy, so a refresh never
+	* sends a request beside the entry already observing the same data.
+	*
+	* A refreshed connection's page replaces its pages, so items the server removed
+	* or reordered follow it; pages loaded past the first are dropped and paged
+	* again with `next`/`previous`. The read entries restart, so a read or query
+	* sent before the refresh is not applied after it.
+	*
+	* The projection must be observed, which it is while it is on screen. Live
+	* subscriptions are left as they are. For data nothing observes (SSR, tests),
+	* use `Remote.prefetch` with `RemotePolicy.networkOnly`. Refreshing what is
+	* already being refreshed returns the same Model.
+	*/
+	refresh: (bound, model, target) => {
+		const projection = "read" in target ? target : target.projection(void 0);
+		const remote = bound.store.get(model);
+		const asked = askedOf(projection);
+		const connections = Requirement.mergeConnections(asked.connections);
+		const items = connections.flatMap((connection) => {
+			const known = remote.connections[connection.identity];
+			return known === void 0 ? [] : itemsOf(visibleItems(known, connection.identity, remote.optimistic.overlays, remote.entities).map((edge) => edge.ref), connection.select);
+		});
+		const requirements = plan(visibleStoreOf(remote.entities, remote.optimistic), [...asked.requirements, ...items], { force: true });
+		const marked = [...requirements.length === 0 ? [] : [{
+			_tag: "RefreshStarted",
+			requests: requirements
+		}], ...connections.filter((connection) => remote.connections[connection.identity] !== void 0).map((connection) => ({
+			_tag: "ConnectionInvalidated",
+			connection: connection.identity
+		}))].reduce(updateRemote, remote);
+		const inFlight = remote.refresh.started === remote.refresh.requested && requirements.some((requirement) => requirement.fields.some((field) => remote.entities[entityKey(requirement.entity, requirement.id)]?.stale.has(field) === true));
+		if (marked === remote && !inFlight) return model;
+		const refresh = {
+			...marked.refresh,
+			requested: marked.refresh.requested + 1
+		};
+		return bound.store.set(model, {
+			...marked,
+			refresh
+		});
+	},
+	/**
 	* Writes a read result into the store, recording each field's applied window.
 	* `requests` are the planned requirements the result answers.
 	*/
@@ -2716,7 +2964,8 @@ const Remote = {
 			_tag: "MutationSucceeded",
 			requestId,
 			entities: outcome.entities,
-			connections: outcome.connections
+			connections: outcome.connections,
+			deleted: outcome.deleted
 		});
 		return {
 			output: outcome.output,
@@ -2731,20 +2980,21 @@ const Remote = {
 	* 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),
+	observe: (bound, surface, params, toMessage = identityMessage, options = {}) => observeEntry(bound, () => askedOf(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)
+	live: (bound, surface, params, toMessage = identityMessage, options = {}) => liveEntry(bound, () => requirementsOf(surface.projection(params)), toMessage, options)
 };
+const brandEntries = (entries) => Subscription.make()(() => entries);
 /** 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 {
+	const domain = {
 		...definition,
 		...bound,
 		get: (selection, id) => Remote.select(bound, selection)(id),
@@ -2752,10 +3002,10 @@ const bindDomain = (definition, store) => {
 			const projection = Remote.select(bound, selection)(id);
 			return {
 				...projection,
-				requirements: projection.requirements.map((requirement) => ({
+				metadata: RemoteRequirements.of(...requirementsOf(projection).map((requirement) => ({
 					...requirement,
 					live: true
-				}))
+				})))
 			};
 		},
 		subscriptions: (active, options = {}) => {
@@ -2789,11 +3039,11 @@ const bindDomain = (definition, store) => {
 			const client = yield* RemoteClient;
 			const planOptions = RemotePolicy.toPlan(policy, now());
 			let current = model;
-			for (const query of planAsked(store.get(current), projection, planOptions).queries) {
+			for (const query of planAsked(store.get(current), askedOf(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;
+			const requirements = planAsked(store.get(current), askedOf(projection), planOptions).requirements;
 			if (requirements.length === 0) return current;
 			const at = now();
 			const result = yield* client.read({
@@ -2809,7 +3059,8 @@ const bindDomain = (definition, store) => {
 		}),
 		query: (query, input, options) => {
 			assertRegistered(bound, "Query", definition.registry.queries, query.name);
-			const { select, ...window } = options;
+			const { select: given, ...window } = options;
+			const select = selectionOf(given);
 			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`);
@@ -2829,8 +3080,7 @@ const bindDomain = (definition, store) => {
 			return {
 				Model: remoteDataSchema(pageSchema(select.schema)),
 				dependencies: [],
-				requirements: [],
-				connections: [requirement],
+				metadata: RemoteConnections.of(requirement),
 				ref,
 				read: (root) => {
 					const remote = store.get(root);
@@ -2892,6 +3142,7 @@ const bindDomain = (definition, store) => {
 				}
 			} : void 0;
 		},
+		refresh: (model, target) => Remote.refresh(bound, model, target),
 		fetch: (ref) => ({
 			name: `Remote.query(${ref.query})`,
 			args: {
@@ -2938,15 +3189,25 @@ const bindDomain = (definition, store) => {
 							_tag: "MutationSucceeded",
 							requestId,
 							entities: outcome.entities,
-							connections: outcome.connections
+							connections: outcome.connections,
+							deleted: outcome.deleted
 						})
 					}))
 				}
 			};
 		},
+		mutation: (model, requestId) => mutationStatus(store.get(model).mutations, requestId),
 		reduce,
-		inspect: (model) => inspectRemote(store.get(model))
+		inspect: (model) => inspectRemote(store.get(model)),
+		wiring: (active, options) => ({
+			key: `remote:${bound.contract.name}`,
+			handles: Object.keys(remoteMessageCases),
+			route: (model, message) => isRemoteMessage(message) ? Option.some({ model: reduce(model, message) }) : Option.none(),
+			subscriptions: brandEntries(domain.subscriptions(active, options)),
+			contract: bound.contract
+		})
 	};
+	return domain;
 };
 /** The window keys of a `QueryOptions`, and only those, without the undefined ones. */
 const pickWindow = (window) => ({
@@ -2961,6 +3222,6 @@ const pageSize = (window, key) => {
 	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, isLoading, 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 };
+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, RemoteConnections, RemoteData, RemoteLiveError, RemoteMutationError, RemotePersistence, RemotePolicy, RemoteProtocolError, RemoteQueryError, RemoteReadError, RemoteRequirements, RemoteRpc, Requirement, Selection, WindowSchema, WireBoundary, addLayer, addOverlay, applyConnectionEvent, applyEntityEvent, assemble, beginMutation, beginOptimistic, classifyLive, clearStale, coalesceQueries, coalesceReads, coalescedLayer, connectionChangeOf, connectionIdentity, connectionsOf, cursor, edge, emptyConnection, emptyLiveState, emptyMutationState, emptyOptimistic, emptyStore, entityKey, entry, failMutation, gc, hasField, hasNext, hasPrevious, initialRemoteModel, inspectEntity, inspectRemote, invalidateConnection, isFieldStale, isGapped, isLoading, isRefPage, isRemoteMessage, isStale, isTombstone, items, liveEventOf, liveHasNext, liveHasPrevious, markStale, merge, missingFields, mutateRemote, mutationStatus, pageSchema, plan, pruneOverlays, reachable, readField, reconcileMutation, refParts, refreshConnection, refsIn, relationOf, relationShape, remoteDataSchema, remoteError, remoteErrorSchema, remoteMessageCases, remoteMessageSchema, remoteModelSchema, remove, removeLayer, removeOverlay, requirementKey, requirementsOf, retentionRootsSchema, schemaOf, segment, setStale, settleFailure, settleSuccess, shouldWake, stableStringify, targetsOf, terminal, tombstone, unknown, updateRemote, visibleItems, visibleStore, windowKey, writeEntities, writeEntity, writeRead };
 
 //# sourceMappingURL=index.mjs.map