foldkit-remote 0.4.0 → 0.6.0

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { Context, Deferred, Duration, Effect, Layer, Option, Request, RequestResolver, Result, Schema, SchemaGetter, Stream } from "effect";
 import * as Domain from "foldkit-entity";
-import { Entity as Entity$1, SelectionTypeId } from "foldkit-entity";
+import { Entity as Entity$1, Expr, Query as Query$1, SelectionTypeId, evaluate } from "foldkit-entity";
 import * as Subscription from "foldkit/subscription";
 import { Metadata } from "foldkit-surface";
 import { Rpc, RpcGroup } from "effect/unstable/rpc";
@@ -108,6 +108,91 @@ const requirementsOf = (projection) => RemoteRequirements.get(projection.metadat
 /** The query connections a Projection carries. */
 const connectionsOf = (projection) => RemoteConnections.get(projection.metadata);
 //#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";
+/**
+* A page of a relation that is a whole list is read under a name of its own, the
+* field's name and the page's size: `comments@first=10`. It is a field like any
+* other to the store, the planner, and the wire, so the whole list and a page of
+* it are held side by side, merged, marked stale, and persisted each on its own.
+* The server reads the name apart, reads the relation with the window, and
+* answers under the alias. A cursor is not part of the name: a page read from a
+* cursor merges onto the page it continues.
+*/
+const RELATION_ALIAS = "@";
+/** The alias a relation field is read under, for a window of this size. */
+const relationAlias = (field, window) => `${field}@${window.last !== void 0 ? `last=${window.last}` : `first=${window.first ?? ""}`}`;
+/** The field an alias reads; a name that is no alias is its own field. */
+const aliasedField = (name) => {
+	const at = name.indexOf("@");
+	return at === -1 ? name : name.slice(0, at);
+};
+/** Splits a ref key (`"Entity:id"`, the store key too) back into its parts. */
+const refParts = (encoded) => {
+	const separator = encoded.indexOf(":");
+	return separator === -1 ? {
+		entity: encoded,
+		id: ""
+	} : {
+		entity: encoded.slice(0, separator),
+		id: encoded.slice(separator + 1)
+	};
+};
+/**
+* The refs a relation value carries, in order. Anything that is not a ref key,
+* an array of them, or a page of them contributes nothing.
+*/
+const refsIn = (value) => {
+	if (typeof value === "string") return [refParts(value)];
+	if (Array.isArray(value)) return value.filter((item) => typeof item === "string").map(refParts);
+	if (value !== null && typeof value === "object") {
+		const refs = value.refs;
+		if (Array.isArray(refs)) return refs.filter((item) => typeof item === "string").map(refParts);
+	}
+	return [];
+};
+/** The refs in a relation value that name the relation's target entity, and no other. */
+const targetsOf = (value, relation) => refsIn(value).filter((ref) => ref.entity === relation.entity);
+const isRefPage = (value) => {
+	if (value === null || typeof value !== "object") return false;
+	const page = value;
+	return Array.isArray(page.refs) && page.refs.every((ref) => typeof ref === "string") && typeof page.hasNext === "boolean" && typeof page.hasPrevious === "boolean";
+};
+/**
+* The relation shape an entity field schema declares: a ref (`one`), a nullable
+* ref, an array of refs (`many`), or a page of refs (`page`). `undefined` for a
+* scalar field, which cannot take a nested selection.
+*/
+const relationShape = (schema) => shapeOf(schema.ast, false);
+const shapeOf = (ast, nullable) => {
+	const annotated = ast.annotations?.[RelationAnnotation];
+	if (annotated === "one" || annotated === "page") return {
+		kind: annotated,
+		nullable,
+		entity: String(ast.annotations?.[RelationEntityAnnotation])
+	};
+	if (ast._tag === "Arrays") {
+		const item = ast.rest?.[0];
+		const inner = item === void 0 ? void 0 : shapeOf(item, false);
+		return inner?.kind === "one" ? {
+			kind: "many",
+			nullable,
+			entity: inner.entity
+		} : void 0;
+	}
+	if (ast._tag === "Union") {
+		const members = ast.types ?? [];
+		const optional = members.some((member) => member._tag === "Null" || member._tag === "Undefined");
+		for (const member of members) {
+			const shape = shapeOf(member, optional);
+			if (shape !== void 0) return shape;
+		}
+	}
+};
+//#endregion
 //#region src/store.ts
 /**
 * The pure entity store: values, per-field presence, staleness, and tombstones.
@@ -142,6 +227,9 @@ const written = (previous, values, now, windows) => {
 		const requested = windows?.[field];
 		if (requested !== void 0 && requested !== "") nextWindows[field] = requested;
 		else delete nextWindows[field];
+		if (!field.includes("@")) {
+			for (const held of present) if (held.startsWith(`${field}@`) && !(held in values)) stale.add(held);
+		}
 	}
 	return {
 		values: {
@@ -352,6 +440,16 @@ make: (name, config) => ({
 * canonical encoded filter/sort input — **never** the pagination window, so
 * `first(25)` and `after(cursor).first(25)` address the same logical connection.
 */
+/**
+* What separates a query's name from its canonical encoded input in a
+* connection identity.
+*
+* NUL, because `JSON.stringify` escapes it inside a string (`\u0000`) and a
+* query name is a TypeScript identifier — so the first occurrence is always the
+* boundary, and a name or an input value cannot forge one. Anything recovering
+* the query from an identity splits here.
+*/
+const IDENTITY_SEPARATOR = "\0";
 /** Stable stringify: object keys sorted, undefined-valued keys dropped, so equal inputs encode equally. */
 const stableStringify = (value) => {
 	if (value === void 0) return "null";
@@ -361,7 +459,32 @@ const stableStringify = (value) => {
 	return `{${Object.keys(record).filter((key) => record[key] !== void 0).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`).join(",")}}`;
 };
 const isEntityName = (result) => typeof result === "object" && result !== null && typeof result.name === "string";
+/**
+* The relational half comes from `foldkit-entity`, so one `Query` namespace
+* holds both what a query means (`from`, `where`, `orderBy`) and how this
+* client addresses it (`make`, `connection`, the window steps). They are one
+* vocabulary in use — a definition's body is composed and then named — and two
+* namespaces of the same name in one file would be a trap.
+*/
+/**
+* One placeholder per key of the input's schema, each carrying that key's own
+* codec so a comparison against it is checked.
+*
+* A codec that is not a `Schema.Struct` exposes no keys to stand for, while its
+* *type* may well have them — so the body would be handed an empty object,
+* `input.slug` would be `undefined`, and the comparison would silently be
+* against nothing while the types all agreed. That is a wrong query rather than
+* a missing one, so it is refused where the query is declared.
+*/
+const inputsOf = (name, schema) => {
+	const fields = schema.fields;
+	if (fields === void 0) throw new Error(`[foldkit-remote] Query.define: the Input of "${name}" is not a Schema.Struct, so its body has no inputs to read. Declare it as fields (\`{ slug: Schema.String }\`) or a plain \`Schema.Struct\`.`);
+	const inputs = {};
+	for (const key of Object.keys(fields)) inputs[key] = Expr.input(key, fields[key]);
+	return Object.freeze(inputs);
+};
 const Query = {
+	...Query$1,
 	/** Declares the entity and options a query's result is a connection over. */
 	connection: (entity, options) => ({
 		entity: entity.name,
@@ -385,10 +508,45 @@ const Query = {
 				input,
 				Input,
 				window: {},
-				identity: `${name}\u0000${stableStringify(encode(input))}`
+				identity: `${name}${stableStringify(encode(input))}`
 			})
 		};
 	},
+	/**
+	* Declares a query by what it means. The body is built once, here, and the
+	* `input` it is given holds placeholders rather than values — there is
+	* nothing yet to branch on, so a condition that depends on what was passed is
+	* a comparison over the placeholder:
+	*
+	* ```ts
+	* const PostsBySlug = Query.define('PostsBySlug', { slug: Schema.String }, ({ input }) =>
+	*   Query.from(Post).pipe(
+	*     Query.where(Expr.eq(Post.fields.slug, input.slug)),
+	*     Query.orderBy(Order.asc(Post.fields.id)),
+	*   ),
+	* )
+	* ```
+	*
+	* What comes back is an ordinary `QueryDescriptor` — the same name, `Input`,
+	* `ref` and connection identity `Query.make` gives — carrying its `body`
+	* besides. A server can compile that body instead of being told the same
+	* thing again in its own dialect, and one that would rather answer the query
+	* its own way still can.
+	*
+	* The result is a connection over the Entity the body reads, so it is not
+	* named twice.
+	*/
+	define: (name, Input, body, options) => {
+		const schema = schemaOf(Input);
+		const built = body({ input: inputsOf(name, schema) });
+		return {
+			...Query.make(name, {
+				Input,
+				Result: Query.connection(built.entity, options)
+			}),
+			body: built
+		};
+	},
 	first: (count) => (ref) => ({
 		...ref,
 		window: {
@@ -1016,74 +1174,6 @@ 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/relation.ts
-/** Marks the codec `Entity.ref`/`Entity.refPage` produce, so a Selection can tell the field's shape. */
-const RelationAnnotation = "foldkitRemoteRelation";
-/** The target entity's name on the same codec, so a nested selection of another entity is refused. */
-const RelationEntityAnnotation = "foldkitRemoteRelationEntity";
-/** Splits a ref key (`"Entity:id"`, the store key too) back into its parts. */
-const refParts = (encoded) => {
-	const separator = encoded.indexOf(":");
-	return separator === -1 ? {
-		entity: encoded,
-		id: ""
-	} : {
-		entity: encoded.slice(0, separator),
-		id: encoded.slice(separator + 1)
-	};
-};
-/**
-* The refs a relation value carries, in order. Anything that is not a ref key,
-* an array of them, or a page of them contributes nothing.
-*/
-const refsIn = (value) => {
-	if (typeof value === "string") return [refParts(value)];
-	if (Array.isArray(value)) return value.filter((item) => typeof item === "string").map(refParts);
-	if (value !== null && typeof value === "object") {
-		const refs = value.refs;
-		if (Array.isArray(refs)) return refs.filter((item) => typeof item === "string").map(refParts);
-	}
-	return [];
-};
-/** The refs in a relation value that name the relation's target entity, and no other. */
-const targetsOf = (value, relation) => refsIn(value).filter((ref) => ref.entity === relation.entity);
-const isRefPage = (value) => {
-	if (value === null || typeof value !== "object") return false;
-	const page = value;
-	return Array.isArray(page.refs) && page.refs.every((ref) => typeof ref === "string") && typeof page.hasNext === "boolean" && typeof page.hasPrevious === "boolean";
-};
-/**
-* The relation shape an entity field schema declares: a ref (`one`), a nullable
-* ref, an array of refs (`many`), or a page of refs (`page`). `undefined` for a
-* scalar field, which cannot take a nested selection.
-*/
-const relationShape = (schema) => shapeOf(schema.ast, false);
-const shapeOf = (ast, nullable) => {
-	const annotated = ast.annotations?.[RelationAnnotation];
-	if (annotated === "one" || annotated === "page") return {
-		kind: annotated,
-		nullable,
-		entity: String(ast.annotations?.[RelationEntityAnnotation])
-	};
-	if (ast._tag === "Arrays") {
-		const item = ast.rest?.[0];
-		const inner = item === void 0 ? void 0 : shapeOf(item, false);
-		return inner?.kind === "one" ? {
-			kind: "many",
-			nullable,
-			entity: inner.entity
-		} : void 0;
-	}
-	if (ast._tag === "Union") {
-		const members = ast.types ?? [];
-		const optional = members.some((member) => member._tag === "Null" || member._tag === "Undefined");
-		for (const member of members) {
-			const shape = shapeOf(member, optional);
-			if (shape !== void 0) return shape;
-		}
-	}
-};
-//#endregion
 //#region src/selection.ts
 /**
 * Selections: the fields a Surface picks of an entity (nested through
@@ -1109,15 +1199,20 @@ const relationOf = (selection) => ({
 	...selection.connections === void 0 ? {} : { windows: selection.connections },
 	...selection.relations === void 0 ? {} : { relations: selection.relations }
 });
+const fromEntitySelections = /* @__PURE__ */ new WeakMap();
 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 compiled = fromEntitySelections.get(selection);
+		if (compiled !== void 0) return compiled;
 		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);
+		const made = Selection.make(Entity.from(selection.entity), spec);
+		fromEntitySelections.set(selection, made);
+		return made;
 	},
 	/**
 	* The fields to read of `entity`. A nested `Selection` on a relation field
@@ -1127,12 +1222,14 @@ const Selection = {
 	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 names = [];
 		const connections = {};
 		const relations = {};
 		for (const key of Object.keys(selection)) {
 			const choice = selection[key];
 			if (choice === true) {
 				picked[key] = entity.fields[key];
+				names.push(key);
 				continue;
 			}
 			const nested = choice;
@@ -1141,18 +1238,21 @@ const 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;
+				const name = shape.kind === "many" ? relationAlias(key, nested.window) : key;
+				names.push(name);
+				connections[name] = nested.window;
 				picked[key] = nullable(nested.schema);
-				if (nested.fields.length > 0) relations[key] = relationOf(nested);
+				if (nested.fields.length > 0) relations[name] = relationOf(nested);
 				continue;
 			}
+			names.push(key);
 			const item = nested.schema;
 			picked[key] = nullable(shape.kind === "many" ? Schema.Array(item) : shape.kind === "page" ? pageSchema(item) : item);
 			relations[key] = relationOf(nested);
 		}
 		return {
 			entity: entity.name,
-			fields: Object.keys(selection),
+			fields: names,
 			schema: Schema.Struct(picked),
 			...Object.keys(connections).length === 0 ? {} : { connections },
 			...Object.keys(relations).length === 0 ? {} : { relations }
@@ -1189,12 +1289,12 @@ const assemble = (store, key, requirement) => {
 		refreshing ||= isFieldStale(store, key, field);
 		const relation = requirement.relations?.[field];
 		if (relation === void 0) {
-			values[field] = value.value;
+			values[aliasedField(field)] = value.value;
 			continue;
 		}
 		const nested = assembleRelation(store, value.value, relation);
 		if (nested === void 0) return void 0;
-		values[field] = nested.values;
+		values[aliasedField(field)] = nested.values;
 		refreshing ||= nested.refreshing;
 	}
 	return {
@@ -1291,6 +1391,8 @@ const Entity = {
 		return descriptor;
 	},
 	make: (name, schema) => {
+		const reserved = Object.keys(schema.fields).find((field) => field.includes("@"));
+		if (reserved !== void 0) throw new Error(`Entity.make: field "${reserved}" of "${name}" contains "@", which names a page of a relation`);
 		const descriptor = {
 			name,
 			schema,
@@ -1332,6 +1434,118 @@ const Entity = {
 	})
 };
 //#endregion
+//#region src/matching.ts
+/**
+* Running a query body against the rows the client already holds.
+*
+* local-execution-DESIGN phase 3. A connection's rows are edges the server
+* delivered, and until now nothing on the client ever evaluated a body — which
+* is why an optimistic insert has to guess between `prepend` and `append`, and
+* why `LivePolicy` exists to be told in advance what to do with a row nobody
+* could judge.
+*
+* This judges them. It is pure, it performs no I/O, and it reuses the reference
+* interpreter in `foldkit-entity` rather than reimplementing the semantics —
+* so a body means here exactly what it means on the server, checked by the same
+* conformance suite.
+*
+* **It answers "which of the rows I hold match", never "which rows match".**
+* Those are different questions and the difference is not recoverable from the
+* result, so it is in the shape: `matched` is what satisfied the body, and
+* `skipped` is what was held but could not be judged. A caller that knows it
+* holds the whole population — a connection terminal at both ends — is the one
+* that can turn this into a complete answer. Nothing here can.
+*
+* **It is not authorization.** On the server a compiled `where` is conjoined
+* with the binding's `visible` rule. There is no `visible` here, and this is
+* safe only because the client holds only rows the server already released to
+* it. A local filter is not an access decision.
+*/
+/**
+* The fields of the body's own Entity that a row must have for the body to be
+* decidable about it — its predicates and its ordering terms.
+*
+* `id` is never among them: it is the key, so it is known for every row in the
+* store whether or not anything fetched it as a field.
+*/
+const decidableOn = (body) => Query$1.dependencies(body).fields.filter((field) => field.entity === body.entity.name && field.key !== "id").map((field) => field.key);
+/**
+* The rows of `descriptor`'s Entity that the store holds and the body matches.
+*
+* The input is given **decoded**, as an application writes it, and encoded here
+* through the descriptor's own `Input` codec. That is deliberate and is the
+* whole reason this takes a descriptor rather than a bare body: a store holds
+* wire values, so an input has to be in that space to be compared against them,
+* and handing an interpreter a decoded value is a mistake **no runtime error
+* catches** — the reference interpreter answers "no rows", which reads exactly
+* like a correct answer. Doing it here means a caller cannot get it wrong.
+*
+* Literals in the body are deliberately *not* encoded. A literal written in
+* domain terms is already broken against the server, which binds it to a column
+* the same way; accepting it here would make the client quietly more permissive
+* than the thing it has to agree with.
+*/
+const matching = (store, descriptor, input, options = {}) => matchingEncoded(store, descriptor, Schema.encodeSync(descriptor.Input)(input), options);
+/**
+* As `matching`, for the callers in this module that already hold the input
+* **encoded**. Not exported: `matching` is the way in, and it cannot be given
+* the wrong space.
+*/
+const matchingEncoded = (store, descriptor, encoded, options = {}) => {
+	const body = descriptor.body;
+	if (body === void 0) throw new Error(`[foldkit-remote] Remote.matching: query "${descriptor.name}" carries no body, so there is nothing to judge rows against. Declare it with Query.define.`);
+	const prefix = `${body.entity.name}:`;
+	const needed = decidableOn(body);
+	const candidates = options.among ?? Object.keys(store).filter((key) => key.startsWith(prefix));
+	const rows = [];
+	const skipped = [];
+	for (const key of candidates) {
+		if (!key.startsWith(prefix)) continue;
+		const entry = store[key];
+		if (entry === void 0) {
+			skipped.push(key);
+			continue;
+		}
+		if (entry.tombstone) continue;
+		if (needed.some((field) => !entry.present.has(field))) {
+			skipped.push(key);
+			continue;
+		}
+		rows.push("id" in entry.values ? {
+			...entry.values,
+			__key: key
+		} : {
+			...entry.values,
+			id: key.slice(prefix.length),
+			__key: key
+		});
+	}
+	return {
+		matched: evaluate(body, encoded, rows).map((row) => row.__key),
+		skipped
+	};
+};
+/**
+* Takes the input **encoded**, because its one caller holds it that way: a
+* connection identity carries the canonical encoded input, and making it decode
+* only for this to encode again would be a round trip that can fail.
+*
+* A decoded-input sibling was written first and deleted: nothing called it. The
+* asymmetry with `matching`, which takes a decoded input, is the shape of the
+* two real callers rather than an oversight.
+*/
+const belongsEncoded = (store, descriptor, encoded, key) => {
+	const entry = store[key];
+	if (entry === void 0) return "unknown";
+	if (entry.tombstone) return "no";
+	const body = descriptor.body;
+	if (body !== void 0 && decidableOn(body).some((field) => entry.stale.has(field))) return "unknown";
+	const judged = matchingEncoded(store, descriptor, encoded, { among: [key] });
+	if (judged.matched.includes(key)) return "yes";
+	if (judged.skipped.includes(key)) return "unknown";
+	return "no";
+};
+//#endregion
 //#region src/inspect.ts
 const inspectEntry = (key, entry) => ({
 	key,
@@ -1347,6 +1561,8 @@ const inspectRemote = (model) => ({
 	connections: Object.keys(model.connections),
 	live: Object.keys(model.live),
 	gaps: [...model.gaps],
+	loading: [...model.loading],
+	failures: model.failures,
 	mutations: {
 		pending: [...model.mutations.pending],
 		failed: [...model.mutations.failed],
@@ -1524,7 +1740,6 @@ const visibleItems = (connection, connectionId, overlays, store) => {
 //#region src/live.ts
 const emptyLiveState = {
 	cursor: 0,
-	stale: /* @__PURE__ */ new Set(),
 	boundary: {}
 };
 /**
@@ -1558,10 +1773,6 @@ const recordBoundary = (state, connection, position) => {
 		}
 	};
 };
-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.
@@ -1614,9 +1825,10 @@ const applyConnectionEvent = (state, optimistic, event, policy = {}) => {
 				outcome
 			};
 			case "invalidate": return {
-				state: invalidateConnection(advance(state, event.cursor), event.connection),
+				state: advance(state, event.cursor),
 				optimistic,
-				outcome
+				outcome,
+				invalidated: event.connection
 			};
 			case "ignore": return {
 				state: advance(state, event.cursor),
@@ -1635,27 +1847,13 @@ const applyConnectionEvent = (state, optimistic, event, policy = {}) => {
 			outcome
 		};
 		case "ConnectionInvalidate": return {
-			state: invalidateConnection(advance(state, event.cursor), event.connection),
+			state: advance(state, event.cursor),
+			invalidated: event.connection,
 			optimistic,
 			outcome
 		};
 	}
 };
-const isStale = (state, connection) => state.stale.has(connection);
-/**
-* Clears a connection's stale mark once a fresh page has been adopted. An
-* invalidating event only records that a refetch is due; whoever merges the
-* refetched page calls this so `isStale` stops reporting.
-*/
-const refreshConnection = (state, connection) => {
-	if (!state.stale.has(connection)) return state;
-	const stale = new Set(state.stale);
-	stale.delete(connection);
-	return {
-		...state,
-		stale
-	};
-};
 /** `hasPrevious` accounting for edges recorded outside the loaded boundary. */
 const liveHasPrevious = (connection, state, connectionId) => hasPrevious(connection) || (state.boundary[connectionId]?.before ?? 0) > 0;
 /** `hasNext` accounting for edges recorded outside the loaded boundary. */
@@ -1797,17 +1995,33 @@ const gc = (state, roots) => {
 * application's choice.
 */
 /** Bump when the serialized shape changes; a mismatch discards the cache. */
-const REMOTE_CACHE_VERSION = 3;
+const REMOTE_CACHE_VERSION = 4;
+/**
+* A snapshot of a Model, keeping the entity cache and only the connections
+* named.
+*
+* Naming none — the default — is exactly what Remote did before connections
+* could be kept at all: a disposable, server-derived cache.
+*/
+const snapshotOf = (model, options = {}) => ({
+	entities: model.entities,
+	connections: Object.fromEntries((options.connections ?? []).flatMap((connection) => {
+		const identity = connectionIdentity(connection);
+		const held = model.connections[identity];
+		return held === void 0 ? [] : [[identity, held.segments.map((segment) => segment.edges)]];
+	}))
+});
 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,
+const serializeStore = (snapshot, scope) => ({
+	version: 4,
 	scope: scope ?? null,
-	entities: Object.fromEntries(Object.entries(store).map(([key, entry]) => [key, {
+	connections: snapshot.connections,
+	entities: Object.fromEntries(Object.entries(snapshot.entities).map(([key, entry]) => [key, {
 		values: entry.values,
 		present: sorted(entry.present),
 		stale: sorted(entry.stale),
@@ -1837,9 +2051,30 @@ const parseEntry = (value) => {
 		windows: entry.windows
 	};
 };
-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));
+/** Throws on a malformed edge so the whole snapshot is discarded. */
+const parseEdges = (value) => {
+	if (!Array.isArray(value)) throw new Error("segment is not an array of edges");
+	return value.map((edge) => {
+		const candidate = edge;
+		if (typeof candidate.key !== "string" || typeof candidate.ref?.entity !== "string" || typeof candidate.ref?.id !== "string") throw new Error("edge is not { key, ref: { entity, id } }");
+		return {
+			key: candidate.key,
+			ref: {
+				entity: candidate.ref.entity,
+				id: candidate.ref.id
+			}
+		};
+	});
+};
+const deserializeStore = (serialized) => ({
+	entities: Object.fromEntries(Object.entries(serialized.entities).map(([key, entry]) => [key, parseEntry(entry)])),
+	connections: Object.fromEntries(Object.entries(serialized.connections ?? {}).map(([key, segments]) => {
+		if (!Array.isArray(segments)) throw new Error("connection is not an array of segments");
+		return [key, segments.map(parseEdges)];
+	}))
+});
+function dehydrate(snapshot, options = {}) {
+	const text = stableStringify(serializeStore(snapshot, options.scope));
 	return exceeds(text, options.maxBytes) ? void 0 : text;
 }
 /**
@@ -1869,7 +2104,7 @@ const hydrate = (raw, options = {}) => {
 	}
 	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return void 0;
 	const candidate = parsed;
-	if (candidate.version !== 3) return void 0;
+	if (candidate.version !== 4) 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;
@@ -1892,37 +2127,49 @@ const mergeStores = (current, snapshot, policy) => policy === "replace" ? {
 	...snapshot,
 	...current
 };
+/** An empty snapshot: the cache as a fresh session has it. */
+const emptySnapshot = {
+	entities: emptyStore,
+	connections: {}
+};
 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. */
+	/** What a snapshot text holds, or `undefined` when it is refused. */
 	hydrate,
-	/** A snapshot brought into a store by policy. */
+	/**
+	* What to keep of a Model, naming the connections that should survive a
+	* reload. Naming none is the default and is what Remote always did.
+	*/
+	snapshotOf,
+	/** A snapshot's entities brought into a store by policy. */
 	mergeStores,
+	/** The cache as a fresh session has it; what a refused `restore` yields. */
+	emptySnapshot,
 	/**
 	* 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* () {
+	save: (snapshot, options) => Effect.gen(function* () {
 		const kv = yield* KeyValueStore.KeyValueStore;
-		const text = dehydrate(store, options);
+		const text = dehydrate(snapshot, 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.
+	* Reads the cache. A missing key yields `emptySnapshot`; anything `hydrate`
+	* refuses yields `emptySnapshot` 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;
+		if (raw === void 0) return emptySnapshot;
 		const restored = hydrate(raw, options);
 		if (restored === void 0) {
 			yield* kv.remove(options.key);
-			return emptyStore;
+			return emptySnapshot;
 		}
 		return restored;
 	})
@@ -1930,6 +2177,8 @@ const RemotePersistence = {
 //#endregion
 //#region src/remoteData.ts
 /** `RemoteData`: the state of a value the store may not hold yet. */
+const fresh = { _tag: "Fresh" };
+const refreshing = { _tag: "Refreshing" };
 const remoteErrorSchema = Schema.Struct({
 	_tag: Schema.String,
 	message: Schema.String
@@ -1977,6 +2226,43 @@ const RemoteData = {
 			case "NotFound": return cases.NotFound();
 		}
 	},
+	/**
+	* The view-oriented fold: the six states as the three things a view actually
+	* draws, under the policy that useful data stays on screen. A value that is
+	* being refetched, or that a later read failed to replace, still reaches
+	* `data` — with `freshness` saying which — instead of being replaced by a
+	* spinner or an error the reader cannot act on.
+	*
+	* ```ts
+	* RemoteData.render(model.user, {
+	*   loading: () => UserSkeleton(),
+	*   notFound: () => NoSuchUser(),
+	*   failed: error => ErrorView(error),
+	*   data: (user, freshness) => UserView({ user, dimmed: freshness._tag !== 'Fresh' }),
+	* })
+	* ```
+	*
+	* `notFound` is its own branch and not optional: a row the server answered
+	* for and does not have is neither loading nor a failure, and drawing it as
+	* either is a spinner that never ends or an error nobody can fix.
+	*
+	* This does not replace `match`, which is the exhaustive fold over the states
+	* themselves. Reach for `match` when the six states really do draw
+	* differently, and for this when they draw the usual three ways.
+	*/
+	render: (data, cases) => {
+		switch (data._tag) {
+			case "Initial":
+			case "Loading": return cases.loading();
+			case "NotFound": return cases.notFound();
+			case "Ready": return cases.data(data.value, fresh);
+			case "Refreshing": return cases.data(data.value, refreshing);
+			case "Failed": return data.previous === void 0 ? cases.failed(data.error) : cases.data(data.previous, {
+				_tag: "Stale",
+				error: data.error
+			});
+		}
+	},
 	map: (data, f) => {
 		switch (data._tag) {
 			case "Ready": return {
@@ -2006,6 +2292,15 @@ const RemoteData = {
 * optimistic layers an application keeps in its Model, the Messages that
 * change it, and the pure reducer over them.
 */
+const noFailures = {
+	connections: {},
+	fields: {}
+};
+const emptyRefresh = {
+	generation: 0,
+	requested: /* @__PURE__ */ new Map(),
+	started: /* @__PURE__ */ new Map()
+};
 const initialRemoteModel = {
 	entities: emptyStore,
 	connections: {},
@@ -2014,10 +2309,8 @@ const initialRemoteModel = {
 	mutations: emptyMutationState,
 	gaps: /* @__PURE__ */ new Set(),
 	loading: /* @__PURE__ */ new Set(),
-	refresh: {
-		requested: 0,
-		started: 0
-	}
+	refresh: emptyRefresh,
+	failures: noFailures
 };
 /** The entity store and the mutation ledger are runtime values, not wire shapes. */
 const runtimeSchema = Schema.Unknown;
@@ -2029,9 +2322,10 @@ const remoteModelSchema = () => Schema.Struct({
 	mutations: runtimeSchema,
 	gaps: runtimeSchema,
 	loading: runtimeSchema,
-	refresh: Schema.Struct({
-		requested: Schema.Number,
-		started: Schema.Number
+	refresh: runtimeSchema,
+	failures: Schema.Struct({
+		connections: Schema.Record(Schema.String, remoteErrorSchema),
+		fields: Schema.Record(Schema.String, remoteErrorSchema)
 	})
 });
 const retentionRootsSchema = Schema.Struct({
@@ -2053,15 +2347,18 @@ const remoteMessageCases = {
 	},
 	ReadFailed: {
 		requests: Schema.Array(ReadRequest),
-		error: remoteErrorSchema
+		error: remoteErrorSchema,
+		stream: Schema.optional(Schema.String)
 	},
 	RefreshStarted: { requests: Schema.Array(ReadRequest) },
 	ReadStarted: {
 		requests: Schema.Array(ReadRequest),
 		refresh: Schema.optional(Schema.Number)
 	},
+	QueryStarted: { connections: Schema.Array(Schema.String) },
 	RetentionChanged: { roots: retentionRootsSchema },
 	Hydrated: {
+		connections: Schema.optional(Schema.Unknown),
 		entities: runtimeSchema,
 		merge: Schema.Union([Schema.Literal("replace"), Schema.Literal("preserve-existing")])
 	},
@@ -2082,6 +2379,11 @@ const remoteMessageCases = {
 		requestId: Schema.String,
 		error: remoteErrorSchema
 	},
+	OverlayShown: {
+		id: Schema.String,
+		optimistic: Schema.Array(Schema.Unknown)
+	},
+	OverlayLifted: { id: Schema.String },
 	LiveReceived: {
 		stream: Schema.String,
 		event: Schema.Unknown,
@@ -2110,39 +2412,141 @@ const remoteMessageSchema = Schema.Union(Object.entries(remoteMessageCases).map(
 	_tag: Schema.Literal(tag),
 	...fields
 })));
+/** An overlay's layer, named apart from every request's: a request id is the application's to choose too. */
+const overlayLayer = (id) => `overlay:${id}`;
 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.
+* One mark per requested field, `entity\0id\0field`. 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 refresh generations
+* below key off the same marks, so "what a read asks for" means one thing.
 */
-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 fieldMark = (entity, id, field) => `${entityKey(entity, id)}\u0000${field}`;
+const fieldMarks = function* (requests) {
+	for (const request of requests) for (const field of request.fields) yield fieldMark(request.entity, request.id, field);
 };
 const withLoading = (loading, requests) => {
 	const next = new Set(loading);
-	for (const mark of loadingMarks(requests)) next.add(mark);
+	for (const mark of fieldMarks(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);
+	for (const mark of fieldMarks(requests)) next.delete(mark);
 	return next;
 };
 /**
+* A connection's mark. The leading separator keeps it out of the field marks'
+* space, whatever a connection identity happens to spell.
+*/
+const connectionPrefix = "\0connection\0";
+const connectionMark = (identity) => `${connectionPrefix}${identity}`;
+/** Whether a query for this connection is in flight. */
+const isQueryLoading = (model, identity) => model.loading.size !== 0 && model.loading.has(connectionMark(identity));
+const withoutQueryLoading = (loading, identity) => {
+	if (!loading.has(connectionMark(identity))) return loading;
+	const next = new Set(loading);
+	next.delete(connectionMark(identity));
+	return next;
+};
+/**
+* The in-flight marks of connections the roots still name. A query the entry
+* stopped waiting for — it was restarted or deactivated before an answer came —
+* leaves its mark behind, and a connection released with that mark would read
+* `Loading` forever the next time something asked for it before sending.
+*/
+const prunedQueryLoading = (loading, roots) => {
+	const named = new Set(roots.connections.map((root) => connectionMark(root.identity)));
+	const kept = [...loading].filter((mark) => !mark.startsWith(connectionPrefix) || named.has(mark));
+	return kept.length === loading.size ? loading : new Set(kept);
+};
+/**
+* Drops the refresh marks of entities and connections that were collected.
+* Nothing observes a collected entity — the retention roots are the active
+* Surfaces — so no read entry's generation can fall back when its mark goes.
+* Without this the generations would be bounded by how many things the
+* application has ever refreshed rather than by what it currently holds, which
+* for a list refreshed on a timer is the same as not bounded at all.
+*/
+const prunedRefresh = (refresh, retained) => {
+	const live = (mark) => mark.startsWith(connectionPrefix) ? retained.connections[mark.slice(12)] !== void 0 : retained.entities[mark.slice(0, mark.indexOf("\0"))] !== void 0;
+	const keep = (marks) => {
+		const next = /* @__PURE__ */ new Map();
+		for (const [mark, generation] of marks) if (live(mark)) next.set(mark, generation);
+		return next.size === marks.size ? marks : next;
+	};
+	const requested = keep(refresh.requested);
+	const started = keep(refresh.started);
+	return requested === refresh.requested && started === refresh.started ? refresh : {
+		...refresh,
+		requested,
+		started
+	};
+};
+/**
+* The generation a read is planned under: the highest any of the fields it
+* reads or connections it runs was refreshed at. A read entry carries this as a
+* dependency, so it restarts when what it observes is refreshed and not when
+* anything else is.
+*/
+const refreshedAt = (refresh, requests, connections = []) => {
+	let at = 0;
+	for (const mark of fieldMarks(requests)) at = Math.max(at, refresh.requested.get(mark) ?? 0);
+	for (const identity of connections) at = Math.max(at, refresh.requested.get(connectionMark(identity)) ?? 0);
+	return at;
+};
+/**
+* Marks every field of `requests` and every connection in `connections`
+* refreshed at the next generation.
+*/
+const withRefreshRequested = (refresh, requests, connections = []) => {
+	const generation = refresh.generation + 1;
+	const requested = new Map(refresh.requested);
+	for (const mark of fieldMarks(requests)) requested.set(mark, generation);
+	for (const identity of connections) requested.set(connectionMark(identity), generation);
+	return {
+		...refresh,
+		generation,
+		requested
+	};
+};
+/**
+* Records that a read of `requests` began under `generation`. A read that
+* carries no generation began under none, and leaves the marks as they are.
+*/
+const withRefreshStarted = (refresh, requests, generation) => {
+	if (generation === void 0 || generation === 0) return refresh;
+	let started;
+	for (const mark of fieldMarks(requests)) {
+		if ((refresh.started.get(mark) ?? 0) >= generation) continue;
+		started ??= new Map(refresh.started);
+		started.set(mark, generation);
+	}
+	return started === void 0 ? refresh : {
+		...refresh,
+		started
+	};
+};
+/**
+* Whether one field's read already began under the generation that field was
+* last refreshed at. Such a read is in flight and would otherwise outlive the
+* refresh, so the refresh takes a new generation to restart it even though the
+* field is already stale.
+*/
+const refreshIsInFlight = (refresh, request, field) => {
+	const mark = fieldMark(request.entity, request.id, field);
+	return (refresh.started.get(mark) ?? 0) === (refresh.requested.get(mark) ?? 0);
+};
+/**
 * 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 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}`));
+	return fields.some((field) => model.loading.has(fieldMark(entity, id, field)));
 };
 const setConnectionStale = (connections, connection, stale) => {
 	const current = connections[connection] ?? emptyConnection;
@@ -2172,39 +2576,71 @@ const updateRemote = (model, message) => {
 		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)
+			loading: withoutLoading(model.loading, message.requests),
+			failures: withoutFieldFailures(model.failures, [...fieldMarks(message.requests), ...patchedMarks(message.result.entities)])
 		};
-		case "RefreshStarted": {
-			const entities = setStale(model.entities, marksOf(message.requests), true);
-			return entities === model.entities ? model : {
+		case "ReadFailed":
+			if (message.stream !== void 0) return markGap(model, message.stream);
+			return {
 				...model,
-				entities
+				entities: setStale(model.entities, marksOf(message.requests), false),
+				loading: withoutLoading(model.loading, message.requests),
+				failures: withFieldFailures(model.failures, message.requests, message.error)
+			};
+		case "RetentionChanged": {
+			const retained = gc(model, message.roots);
+			return {
+				...model,
+				...retained,
+				refresh: prunedRefresh(model.refresh, retained),
+				failures: prunedFailures(model, message.roots),
+				loading: prunedQueryLoading(model.loading, message.roots)
 			};
 		}
-		case "ReadStarted": {
-			const started = Math.max(model.refresh.started, message.refresh ?? 0);
+		case "Hydrated": {
+			const restored = Object.entries(message.connections ?? {}).map(([identity, segments]) => [identity, {
+				segments: segments.map((edges) => ({
+					edges: [...edges],
+					start: unknown,
+					end: unknown
+				})),
+				stale: true
+			}]);
 			return {
 				...model,
-				loading: withLoading(model.loading, message.requests),
-				refresh: started === model.refresh.started ? model.refresh : {
-					...model.refresh,
-					started
+				entities: RemotePersistence.mergeStores(model.entities, message.entities, message.merge),
+				connections: message.merge === "replace" ? {
+					...model.connections,
+					...Object.fromEntries(restored)
+				} : {
+					...Object.fromEntries(restored),
+					...model.connections
 				}
 			};
 		}
+		case "RefreshStarted": {
+			const asked = message.requests.reduce((store, request) => isTombstone(store, entityKey(request.entity, request.id)) ? remove(store, entityKey(request.entity, request.id)) : store, model.entities);
+			const entities = setStale(asked, marksOf(message.requests), true);
+			const failures = withoutFieldFailures(model.failures, fieldMarks(message.requests));
+			return entities === model.entities && failures === model.failures ? model : {
+				...model,
+				entities,
+				failures
+			};
+		}
+		case "QueryStarted": {
+			const loading = new Set(model.loading);
+			for (const identity of message.connections) loading.add(connectionMark(identity));
+			return loading.size === model.loading.size ? model : {
+				...model,
+				loading
+			};
+		}
+		case "ReadStarted": return {
+			...model,
+			loading: withLoading(model.loading, message.requests),
+			refresh: withRefreshStarted(model.refresh, message.requests, message.refresh)
+		};
 		case "MutationStarted": return {
 			...model,
 			mutations: beginMutation(model.mutations, message.requestId),
@@ -2216,7 +2652,19 @@ const updateRemote = (model, message) => {
 				...model,
 				entities: settled.store,
 				mutations: settled.state,
-				optimistic: settled.optimistic
+				optimistic: settled.optimistic,
+				failures: withoutFieldFailures(model.failures, [...patchedMarks(message.entities), ...(message.deleted ?? []).flatMap((ref) => entityFailureMarks(model.failures, entityKey(ref.entity, ref.id)))])
+			};
+		}
+		case "OverlayShown": return {
+			...model,
+			optimistic: beginOptimistic(settleFailure(model.optimistic, overlayLayer(message.id)), overlayLayer(message.id), message.optimistic)
+		};
+		case "OverlayLifted": {
+			const optimistic = settleFailure(model.optimistic, overlayLayer(message.id));
+			return optimistic.layers.length === model.optimistic.layers.length && optimistic.overlays.length === model.optimistic.overlays.length ? model : {
+				...model,
+				optimistic
 			};
 		}
 		case "MutationFailed": return {
@@ -2227,18 +2675,26 @@ const updateRemote = (model, message) => {
 		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({
+				const event = message.event;
+				const applied = applyEntityEvent(state, model.entities, event, message.now);
+				if (applied.outcome === "gap") return markGap(model, message.stream);
+				const settled = applied.outcome !== "applied" ? [] : event._tag === "EntityPatched" ? [...patchedMarks([{
+					...event.ref,
+					values: event.values
+				}])] : entityFailureMarks(model.failures, entityKey(event.ref.entity, event.ref.id));
+				return clearGap({
 					...model,
 					entities: applied.store,
 					live: {
 						...model.live,
 						[message.stream]: applied.state
-					}
+					},
+					failures: withoutFieldFailures(model.failures, settled)
 				}, message.stream);
 			}
 			const applied = applyConnectionEvent(state, model.optimistic, message.event, message.policy);
-			return applied.outcome === "gap" ? markGap(model, message.stream) : clearGap({
+			if (applied.outcome === "gap") return markGap(model, message.stream);
+			const next = clearGap({
 				...model,
 				optimistic: applied.optimistic,
 				live: {
@@ -2246,10 +2702,16 @@ const updateRemote = (model, message) => {
 					[message.stream]: applied.state
 				}
 			}, message.stream);
+			return applied.invalidated === void 0 ? next : updateRemote(next, {
+				_tag: "ConnectionInvalidated",
+				connection: applied.invalidated
+			});
 		}
 		case "GapCleared": return clearGap(model, message.stream);
 		case "ConnectionMerged": {
 			const current = model.connections[message.connection] ?? emptyConnection;
+			const failures = withoutConnectionFailure(model.failures, message.connection);
+			const loading = withoutQueryLoading(model.loading, message.connection);
 			const replaces = message.refreshes === true && current.stale;
 			const merged = merge(replaces ? emptyConnection : current, message.page);
 			return {
@@ -2261,25 +2723,129 @@ const updateRemote = (model, message) => {
 						stale: false
 					} : merged
 				},
-				optimistic: pruneOverlays(model.optimistic, message.connection, new Set(message.page.edges.map((edge) => edge.key)), model.mutations.pending)
+				optimistic: pruneOverlays(model.optimistic, message.connection, new Set(message.page.edges.map((edge) => edge.key)), model.mutations.pending),
+				failures,
+				loading
 			};
 		}
 		case "ConnectionInvalidated":
-			if (model.connections[message.connection]?.stale === true) return model;
+			if (model.connections[message.connection]?.stale === true && !(message.connection in model.failures.connections)) return model;
 			return {
 				...model,
-				connections: setConnectionStale(model.connections, message.connection, true)
+				connections: setConnectionStale(model.connections, message.connection, true),
+				failures: withoutConnectionFailure(model.failures, message.connection)
 			};
-		case "QueryFailed": return message.connection in model.connections ? {
+		case "QueryFailed": return {
 			...model,
-			connections: setConnectionStale(model.connections, message.connection, false)
-		} : model;
+			connections: message.connection in model.connections ? setConnectionStale(model.connections, message.connection, false) : model.connections,
+			failures: {
+				...model.failures,
+				connections: {
+					...model.failures.connections,
+					[message.connection]: message.error
+				}
+			},
+			loading: withoutQueryLoading(model.loading, message.connection)
+		};
 		case "ConnectionRefreshed": return {
 			...model,
 			connections: setConnectionStale(model.connections, message.connection, false)
 		};
 	}
 };
+/** The failures without one connection's, keeping identity when it had none. */
+const withoutConnectionFailure = (failures, connection) => {
+	if (!(connection in failures.connections)) return failures;
+	const { [connection]: _settled, ...connections } = failures.connections;
+	return {
+		...failures,
+		connections
+	};
+};
+/** The failures with every field a read asked for failed with `error`. */
+const withFieldFailures = (failures, requests, error) => {
+	const fields = { ...failures.fields };
+	for (const mark of fieldMarks(requests)) fields[mark] = error;
+	return {
+		...failures,
+		fields
+	};
+};
+/**
+* The failures without the fields `settled` names, keeping identity when none
+* of them had failed, which is nearly always: this runs on every write.
+*/
+const withoutFieldFailures = (failures, settled) => {
+	if (Object.keys(failures.fields).length === 0) return failures;
+	const marks = [...settled].filter((mark) => mark in failures.fields);
+	if (marks.length === 0) return failures;
+	const fields = { ...failures.fields };
+	for (const mark of marks) delete fields[mark];
+	return {
+		...failures,
+		fields
+	};
+};
+/** Every failed field of one entity: what deleting the entity settles. */
+const entityFailureMarks = (failures, key) => Object.keys(failures.fields).filter((mark) => mark.startsWith(`${key}\u0000`));
+/** The field marks of written values: each patch settles the fields it carries. */
+const patchedMarks = function* (patches) {
+	for (const patch of patches) for (const field of Object.keys(patch.values)) yield fieldMark(patch.entity, patch.id, field);
+};
+/**
+* The failures of what the roots still reach. A released connection's or
+* entity's failure goes with it, so asking for it again later asks the server
+* again rather than repeating an error that may no longer hold.
+*
+* Reached is retention's own walk, taken over the Model before collection. It
+* counts a relation's target and a list's row that the store does not hold,
+* which is exactly a value whose first read failed: it is still on screen,
+* behind the parent that refers to it.
+*/
+const prunedFailures = (model, roots) => {
+	const { failures } = model;
+	const named = new Set(roots.connections.map((root) => root.identity));
+	const connections = Object.entries(failures.connections).filter(([identity]) => named.has(identity));
+	const kept = Object.keys(failures.fields).length === 0 ? /* @__PURE__ */ new Set() : reachable(model.entities, roots, model.connections, model.optimistic, model.mutations.pending);
+	const fields = Object.entries(failures.fields).filter(([mark]) => kept.has(mark.slice(0, mark.indexOf("\0"))));
+	return connections.length === Object.keys(failures.connections).length && fields.length === Object.keys(failures.fields).length ? failures : {
+		connections: Object.fromEntries(connections),
+		fields: Object.fromEntries(fields)
+	};
+};
+/** Whether this field's last read failed and nothing has settled it since. */
+const isFieldFailed = (model, entity, id, field) => fieldMark(entity, id, field) in model.failures.fields;
+/**
+* The first failure among the fields `relation` reads of an entity, following
+* each relation the store holds into its targets, as `assemble` does. A read
+* that consults it shows `Failed` for a related entity's failure too, rather
+* than waiting on a field nothing will fetch.
+*/
+const failureOf = (model, entity, id, relation) => {
+	const failed = model.failures.fields;
+	if (Object.keys(failed).length === 0) return void 0;
+	const walked = /* @__PURE__ */ new Map();
+	const walk = (target, targetId, requirement) => {
+		const key = entityKey(target, targetId);
+		const seen = walked.get(key) ?? /* @__PURE__ */ new Set();
+		if (seen.has(requirement)) return void 0;
+		seen.add(requirement);
+		walked.set(key, seen);
+		for (const field of requirement.fields) {
+			const error = failed[fieldMark(target, targetId, field)];
+			if (error !== void 0) return error;
+			const nested = requirement.relations?.[field];
+			if (nested === void 0) continue;
+			const value = readField(model.entities, key, field);
+			if (value._tag === "None") continue;
+			for (const ref of targetsOf(value.value, nested)) {
+				const found = walk(ref.entity, ref.id, nested);
+				if (found !== void 0) return found;
+			}
+		}
+	};
+	return walk(entity, id, relation);
+};
 /** 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])];
@@ -2414,6 +2980,22 @@ const storeOf = (bound, model) => {
 	const remote = bound.store.get(model);
 	return visibleStoreOf(remote.entities, remote.optimistic);
 };
+/**
+* The Model as it would be with nothing optimistic pending. Every read reaches
+* the layers through the Model it is given, so dropping them here is what makes
+* a read confirmed — no read has to know it is being read confirmed.
+*/
+const withoutOptimistic = (bound, model) => {
+	const remote = bound.store.get(model);
+	return remote.optimistic.layers.length === 0 && remote.optimistic.overlays.length === 0 ? model : bound.store.set(model, {
+		...remote,
+		optimistic: emptyOptimistic
+	});
+};
+const confirmed = (bound, projection) => ({
+	...projection,
+	read: (root) => projection.read(withoutOptimistic(bound, root))
+});
 const visibleStores = /* @__PURE__ */ new WeakMap();
 const visibleStoreOf = (entities, optimistic) => {
 	let byStore = visibleStores.get(optimistic);
@@ -2499,6 +3081,10 @@ const askedOf = (projection) => projection === void 0 ? nothingAsked : {
 * fresh contributes its visible items' selected fields to the entity plan; one
 * it does not hold, or holds stale, is a query to run (its items are planned
 * once the page arrives).
+*
+* A connection whose query failed is not run again here, short of `force`: the
+* failure is what its read shows, and retrying is `Remote.refresh`'s to ask
+* for. The rows it already holds are still planned, since they are on screen.
 */
 const planAsked = (remote, asked, options) => {
 	const queries = [];
@@ -2506,18 +3092,46 @@ const planAsked = (remote, asked, options) => {
 	const connections = Requirement.mergeConnections(asked.connections);
 	for (const connection of connections) {
 		const known = remote.connections[connection.identity];
-		if (known === void 0 || known.stale || options.force === true) {
+		if (!(options.force !== true && connection.identity in remote.failures.connections) && (known === void 0 || known.stale || options.force === true)) {
 			queries.push(connection);
 			continue;
 		}
+		if (known === void 0) continue;
 		const edges = visibleItems(known, connection.identity, remote.optimistic.overlays, remote.entities);
 		items.push(...itemsOf(edges.map((edge) => edge.ref), connection.select));
 	}
+	const planned = plan(visibleStoreOf(remote.entities, remote.optimistic), [...asked.requirements, ...items], options);
 	return {
-		requirements: plan(visibleStoreOf(remote.entities, remote.optimistic), [...asked.requirements, ...items], options),
+		requirements: options.force === true ? planned : withoutFailedFields(remote, planned),
 		queries
 	};
 };
+/**
+* The plan without the fields whose last read failed. Like a failed query,
+* a failed field is shown rather than retried on its own, so a persistent
+* error is not asked again on every unrelated restart of the read entry. A
+* field leaving the request takes its window and its relation with it.
+*/
+const withoutFailedFields = (remote, planned) => {
+	if (Object.keys(remote.failures.fields).length === 0) return planned;
+	return planned.flatMap((requirement) => {
+		const fields = requirement.fields.filter((field) => !isFieldFailed(remote, requirement.entity, requirement.id, field));
+		if (fields.length === requirement.fields.length) return [requirement];
+		if (fields.length === 0) return [];
+		const kept = new Set(fields);
+		const only = (record) => record === void 0 ? void 0 : Object.fromEntries(Object.entries(record).filter(([field]) => kept.has(field)));
+		const windows = only(requirement.windows);
+		const relations = only(requirement.relations);
+		return [{
+			entity: requirement.entity,
+			id: requirement.id,
+			fields,
+			...windows === void 0 || Object.keys(windows).length === 0 ? {} : { windows },
+			...relations === void 0 || Object.keys(relations).length === 0 ? {} : { relations },
+			...requirement.live === void 0 ? {} : { live: requirement.live }
+		}];
+	});
+};
 /** The entity requirements a page's edges add under a selection. */
 const itemsOf = (edges, select) => edges.filter((edge) => edge.entity === select.entity).map((edge) => ({
 	...select,
@@ -2545,22 +3159,52 @@ const queryRequestOf = (query) => {
 * `refreshes` marks the page as answering the connection's refresh, so one
 * Message both merges it and clears `stale`.
 */
-const pageMessage = (connection, result, refreshes = false) => ({
-	_tag: "ConnectionMerged",
-	connection,
-	page: {
-		edges: result.edges.map((edge) => ({
-			key: edge.key,
-			ref: {
-				entity: edge.entity,
-				id: edge.id
-			}
-		})),
-		start: result.start,
-		end: result.end
-	},
-	...refreshes ? { refreshes } : {}
-});
+/**
+* The page a window asked for, or the number of edges that came back instead.
+*
+* A window is a request the client made and the server answered, so more edges
+* than were asked for is a protocol disagreement rather than a windfall: the
+* client cannot tell which of them the window meant, the connection's
+* boundaries stop describing what it holds, and a `first: 25` that quietly
+* becomes a thousand is a memory event with no error attached to it.
+*
+* `undefined` when the page is within its window, or when no size was asked
+* for — `after`/`before` with no `first`/`last` bounds nothing.
+*/
+const overrun = (window, edges) => {
+	const asked = window.first ?? window.last;
+	return asked !== void 0 && edges.length > asked ? {
+		asked,
+		got: edges.length
+	} : void 0;
+};
+const pageMessage = (connection, result, refreshes = false, window = {}) => {
+	const over = overrun(window, result.edges);
+	if (over !== void 0) return {
+		_tag: "QueryFailed",
+		connection,
+		error: {
+			_tag: "RemoteProtocolError",
+			message: `the server returned ${over.got} edges for a window of ${over.asked}`
+		}
+	};
+	return {
+		_tag: "ConnectionMerged",
+		connection,
+		page: {
+			edges: result.edges.map((edge) => ({
+				key: edge.key,
+				ref: {
+					entity: edge.entity,
+					id: edge.id
+				}
+			})),
+			start: result.start,
+			end: result.end
+		},
+		...refreshes ? { refreshes } : {}
+	};
+};
 /**
 * The retention roots of some projections: their requirements, their
 * connections (each with the union of what the projections select of its
@@ -2608,7 +3252,7 @@ const queryMessage = (query) => Effect.gen(function* () {
 		_tag: "QueryFailed",
 		connection: query.identity,
 		error: remoteError(result.failure)
-	} : pageMessage(query.identity, result.success, true);
+	} : pageMessage(query.identity, result.success, true, query.window);
 });
 /** A query the read entry runs, as its dependencies carry it: plain data Foldkit compares. */
 const PlannedQuery = Schema.Struct({
@@ -2639,7 +3283,7 @@ const observeEntry = (bound, askedOf, toMessage, options) => {
 			const remote = bound.store.get(model);
 			const planned = planAsked(remote, askedOf(model), RemotePolicy.toPlan(policy, now()));
 			return {
-				refresh: remote.refresh.requested,
+				refresh: refreshedAt(remote.refresh, planned.requirements, planned.queries.map((query) => query.identity)),
 				requirements: planned.requirements,
 				queries: planned.queries.map(({ identity, window, select }) => ({
 					identity,
@@ -2648,14 +3292,17 @@ const observeEntry = (bound, askedOf, toMessage, options) => {
 				}))
 			};
 		},
-		dependenciesToStream: ({ requirements, queries, refresh }) => Stream.concat(requirements.length === 0 ? Stream.empty : Stream.fromIterable([toMessage({
+		dependenciesToStream: ({ requirements, queries, refresh }) => Stream.concat(Stream.fromIterable([...requirements.length === 0 ? [] : [toMessage({
 			_tag: "ReadStarted",
 			requests: requirements,
 			refresh
 		}), ...RemotePolicy.refreshes(policy) ? [toMessage({
 			_tag: "RefreshStarted",
 			requests: requirements
-		})] : []]), Stream.mergeAll([...requirements.length === 0 ? [] : [Stream.fromEffect(read(requirements))], ...queries.map((query) => Stream.fromEffect(run(query)))], { concurrency: "unbounded" }))
+		})] : []], ...queries.length === 0 ? [] : [toMessage({
+			_tag: "QueryStarted",
+			connections: queries.map((query) => query.identity)
+		})]]), Stream.mergeAll([...requirements.length === 0 ? [] : [Stream.fromEffect(read(requirements))], ...queries.map((query) => Stream.fromEffect(run(query)))], { concurrency: "unbounded" }))
 	};
 };
 /** The live entry: subscribes to `requirementsOf(model)` from the Model's resume cursor. */
@@ -2685,7 +3332,8 @@ const liveEntry = (bound, requirementsOf, toMessage, options) => ({
 	})), Stream.catchIf((_error) => true, (error) => Stream.succeed(toMessage({
 		_tag: "ReadFailed",
 		requests: requirements,
-		error: remoteError(error)
+		error: remoteError(error),
+		stream: liveStreamKey(requirements)
 	}))))
 });
 /** The projection an active Surface has for this Model, if it is active. */
@@ -2778,8 +3426,18 @@ const Remote = {
 						value: decoded.success
 					};
 				});
-				if (present !== void 0) return present;
-				return isLoading(bound.store.get(root), selection.entity, id, relation.fields) ? { _tag: "Loading" } : { _tag: "Initial" };
+				const remote = bound.store.get(root);
+				const failure = failureOf(remote, selection.entity, id, relation);
+				if (present !== void 0) return failure !== void 0 && (present._tag === "Ready" || present._tag === "Refreshing") ? {
+					_tag: "Failed",
+					error: failure,
+					previous: present.value
+				} : present;
+				if (isLoading(remote, selection.entity, id, relation.fields)) return { _tag: "Loading" };
+				return failure === void 0 ? { _tag: "Initial" } : {
+					_tag: "Failed",
+					error: failure
+				};
 			}
 		});
 	},
@@ -2801,6 +3459,12 @@ const Remote = {
 	*/
 	storeOf: (bound, model) => storeOf(bound, model),
 	/**
+	* The projection read against the server-derived store alone: the same
+	* requirements, planned the same way, with the pending optimistic layers and
+	* connection overlays left off. See the bound `Remote.confirmed`.
+	*/
+	confirmed: (bound, projection) => confirmed(bound, projection),
+	/**
 	* Executes the plan against the `RemoteClient` and returns a new store. Used
 	* for SSR route prefetch, hover prefetch, and tests. Never called during render.
 	* `policy` decides what a present field means (default cache-first); `now`
@@ -2832,6 +3496,9 @@ const Remote = {
 	* again with `next`/`previous`. The read entries restart, so a read or query
 	* sent before the refresh is not applied after it.
 	*
+	* It is also how a failed query is retried: a connection whose query failed
+	* is not run again on its own, so its read stays `Failed` until this asks.
+	*
 	* 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
@@ -2847,19 +3514,17 @@ const Remote = {
 			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 invalidated = connections.filter((connection) => remote.connections[connection.identity] !== void 0 || connection.identity in remote.failures.connections).map((connection) => connection.identity);
 		const marked = [...requirements.length === 0 ? [] : [{
 			_tag: "RefreshStarted",
 			requests: requirements
-		}], ...connections.filter((connection) => remote.connections[connection.identity] !== void 0).map((connection) => ({
+		}], ...invalidated.map((connection) => ({
 			_tag: "ConnectionInvalidated",
-			connection: connection.identity
+			connection
 		}))].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));
+		const inFlight = requirements.some((requirement) => requirement.fields.some((field) => remote.entities[entityKey(requirement.entity, requirement.id)]?.stale.has(field) === true && refreshIsInFlight(remote.refresh, requirement, field)));
 		if (marked === remote && !inFlight) return model;
-		const refresh = {
-			...marked.refresh,
-			requested: marked.refresh.requested + 1
-		};
+		const refresh = withRefreshRequested(marked.refresh, requirements, invalidated);
 		return bound.store.set(model, {
 			...marked,
 			refresh
@@ -2926,7 +3591,7 @@ const Remote = {
 		});
 	}),
 	/** The `RemoteMessage` that merges a query page into its connection. */
-	queryMessage: (ref, result) => pageMessage(ref.identity, result),
+	queryMessage: (ref, result) => pageMessage(ref.identity, result, false, ref.window),
 	/**
 	* The edges a connection shows: its server-known region with pending and
 	* confirmed overlays placed around it, minus removed edges and edges whose
@@ -2983,8 +3648,10 @@ const Remote = {
 	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
+	* requirements, emitting a `LiveReceived` per event and a `ReadFailed`
+	* carrying its `stream` when the stream breaks (including
+	* `ResumeUnavailable`). That records a gap on the stream rather than a failed
+	* read, since nothing was being read. 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, () => requirementsOf(surface.projection(params)), toMessage, options)
@@ -2993,7 +3660,48 @@ 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));
+	/**
+	* What to do with a row a live event says was inserted into a connection.
+	*
+	* Resolved here rather than in the pure reducer because this is the only
+	* place with both the Model and the registry, and two separate things needed
+	* one or the other.
+	*
+	* **The declared policy reaches the decision.** `Query.connection(E, { live })`
+	* has always been typed, documented, carried on the descriptor and encoded in
+	* the Message schema — and nothing ever put it on a Message, so every live
+	* insert took the default whatever an application asked for. It does now.
+	*
+	* **A row the client can judge does not need a policy.** The policy exists
+	* because nothing could tell whether an inserted row belonged to the query.
+	* Where the body says it does not, `ignore` is not a guess. Where the body
+	* says it does, or the client cannot tell — a row it never fetched, or holds
+	* without a field the body reads — the declared policy is the answer, exactly
+	* as it was meant to be.
+	*
+	* Only membership is decided here. *Where* a row sorts needs text collation,
+	* which is the backend's, so the position the event carries stands.
+	*/
+	const livePolicyFor = (model, event) => {
+		if (event._tag !== "ConnectionInsert") return void 0;
+		const identity = event.connection;
+		const descriptor = definition.registry.queries.get(identity.slice(0, identity.indexOf("\0")));
+		const declared = (descriptor?.Result)?.live;
+		if (descriptor?.body === void 0) return declared;
+		const encoded = JSON.parse(identity.slice(identity.indexOf("\0") + 1));
+		return belongsEncoded(storeOf(bound, model), descriptor, encoded, entityKey(event.edge.ref.entity, event.edge.ref.id)) === "no" ? {
+			prepend: "ignore",
+			append: "ignore"
+		} : declared;
+	};
+	const reduce = (model, message) => {
+		const live = message._tag === "LiveReceived" ? message : void 0;
+		const resolved = live === void 0 || live.policy !== void 0 ? message : {
+			...live,
+			policy: livePolicyFor(model, live.event)
+		};
+		return store.set(model, updateRemote(store.get(model), resolved));
+	};
 	const domain = {
 		...definition,
 		...bound,
@@ -3034,6 +3742,7 @@ const bindDomain = (definition, store) => {
 		},
 		plan: (model, projection, options) => Remote.plan(bound, model, projection, options),
 		storeOf: (model) => storeOf(bound, model),
+		confirmed: (projection) => confirmed(bound, projection),
 		prefetch: (model, projection, options = {}) => Effect.gen(function* () {
 			const { policy = RemotePolicy.cacheFirst, now = Date.now } = options;
 			const client = yield* RemoteClient;
@@ -3041,7 +3750,7 @@ const bindDomain = (definition, store) => {
 			let current = model;
 			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));
+				current = reduce(current, pageMessage(query.identity, page, true, query.window));
 			}
 			const requirements = planAsked(store.get(current), askedOf(projection), planOptions).requirements;
 			if (requirements.length === 0) return current;
@@ -3071,6 +3780,58 @@ const bindDomain = (definition, store) => {
 			};
 			const relation = relationOf(select);
 			const relationKey = stableStringify(relation);
+			const failedItem = (remote, connection) => {
+				if (Object.keys(remote.failures.fields).length === 0) return void 0;
+				for (const edge of visibleItems(connection, ref.identity, remote.optimistic.overlays, remote.entities)) {
+					if (edge.ref.entity !== relation.entity) continue;
+					const error = failureOf(remote, edge.ref.entity, edge.ref.id, relation);
+					if (error !== void 0) return {
+						_tag: "Failed",
+						error
+					};
+				}
+			};
+			const loadingItem = (remote, connection) => {
+				if (remote.loading.size === 0) return void 0;
+				for (const edge of visibleItems(connection, ref.identity, remote.optimistic.overlays, remote.entities)) {
+					if (edge.ref.entity !== relation.entity) continue;
+					if (isLoading(remote, edge.ref.entity, edge.ref.id, relation.fields)) return { _tag: "Loading" };
+				}
+			};
+			const readPage = (remote, connection) => {
+				const visible = visibleStoreOf(remote.entities, remote.optimistic);
+				return memoRead(visible, connection, `${ref.identity}\u0000${relationKey}`, () => {
+					const items = [];
+					let refreshing = connection.stale;
+					const edges = visibleItems(connection, ref.identity, remote.optimistic.overlays, remote.entities);
+					for (const edge of edges) {
+						const assembled = assemble(visible, entityKey(edge.ref.entity, edge.ref.id), relation);
+						if (assembled === void 0) return void 0;
+						const decoded = Schema.decodeUnknownResult(select.schema)(assembled.values);
+						if (Result.isFailure(decoded)) return {
+							_tag: "Failed",
+							error: {
+								_tag: "DecodeError",
+								message: decoded.failure.message
+							}
+						};
+						refreshing ||= assembled.refreshing;
+						items.push(decoded.success);
+					}
+					const page = {
+						items,
+						hasNext: hasNext(connection),
+						hasPrevious: hasPrevious(connection)
+					};
+					return refreshing ? {
+						_tag: "Refreshing",
+						value: page
+					} : {
+						_tag: "Ready",
+						value: page
+					};
+				});
+			};
 			const requirement = {
 				identity: ref.identity,
 				window: ref.window,
@@ -3082,42 +3843,41 @@ const bindDomain = (definition, store) => {
 				dependencies: [],
 				metadata: RemoteConnections.of(requirement),
 				ref,
+				selection: select,
 				read: (root) => {
 					const remote = store.get(root);
 					const connection = remote.connections[ref.identity];
-					if (connection === void 0 || connection.stale && connection.segments.length === 0) return { _tag: "Initial" };
-					const visible = visibleStoreOf(remote.entities, remote.optimistic);
-					return memoRead(visible, connection, `${ref.identity}\u0000${relationKey}`, () => {
-						const items = [];
-						let refreshing = connection.stale;
-						const edges = visibleItems(connection, ref.identity, remote.optimistic.overlays, remote.entities);
-						for (const edge of edges) {
-							const assembled = assemble(visible, entityKey(edge.ref.entity, edge.ref.id), relation);
-							if (assembled === void 0) return { _tag: "Initial" };
-							const decoded = Schema.decodeUnknownResult(select.schema)(assembled.values);
-							if (Result.isFailure(decoded)) return {
-								_tag: "Failed",
-								error: {
-									_tag: "DecodeError",
-									message: decoded.failure.message
-								}
-							};
-							refreshing ||= assembled.refreshing;
-							items.push(decoded.success);
-						}
-						const page = {
-							items,
-							hasNext: hasNext(connection),
-							hasPrevious: hasPrevious(connection)
+					const failure = remote.failures.connections[ref.identity];
+					if (connection === void 0 || connection.stale && connection.segments.length === 0) {
+						if (isQueryLoading(remote, ref.identity)) return { _tag: "Loading" };
+						return failure === void 0 ? { _tag: "Initial" } : {
+							_tag: "Failed",
+							error: failure
 						};
-						return refreshing ? {
-							_tag: "Refreshing",
-							value: page
-						} : {
-							_tag: "Ready",
-							value: page
+					}
+					const read = readPage(remote, connection) ?? failedItem(remote, connection) ?? loadingItem(remote, connection) ?? { _tag: "Initial" };
+					if (failure === void 0) {
+						if (read._tag !== "Ready" && read._tag !== "Refreshing") return read;
+						const item = failedItem(remote, connection);
+						return item === void 0 ? read : {
+							_tag: "Failed",
+							error: item.error,
+							previous: read.value
 						};
-					});
+					}
+					switch (read._tag) {
+						case "Ready":
+						case "Refreshing": return {
+							_tag: "Failed",
+							error: failure,
+							previous: read.value
+						};
+						case "Failed": return read;
+						default: return {
+							_tag: "Failed",
+							error: failure
+						};
+					}
 				}
 			};
 		},
@@ -3142,7 +3902,79 @@ const bindDomain = (definition, store) => {
 				}
 			} : void 0;
 		},
+		explain: (model, projection, options) => {
+			const { ref } = projection;
+			const reading = Object.values(options?.surfaces ?? {}).filter((active) => {
+				const active_ = active.projectionOf(model);
+				return active_ !== void 0 && connectionsOf(active_).some((connection) => connection.identity === ref.identity);
+			});
+			const body = definition.registry.queries.get(ref.query)?.body;
+			const [connection] = RemoteConnections.get(projection.metadata);
+			return {
+				domain: bound.contract.name,
+				query: ref.query,
+				input: Schema.encodeSync(ref.Input)(ref.input),
+				identity: ref.identity,
+				window: ref.window,
+				select: connection.select,
+				...body === void 0 ? {} : {
+					body: Query$1.show(body),
+					dependencies: Query$1.dependencies(body)
+				},
+				state: projection.read(model)._tag,
+				...options?.surfaces === void 0 ? {} : {
+					surfaces: reading.map((active) => active.name),
+					activation: reading.flatMap((active) => active.activation === void 0 ? [] : [{
+						surface: active.name,
+						...active.activation
+					}])
+				}
+			};
+		},
+		filtered: (model, over, by, input) => {
+			assertRegistered(bound, "Query", definition.registry.queries, by.name);
+			const filters = by.body?.entity.name;
+			if (filters !== void 0 && filters !== over.selection.entity) throw new Error(`Remote: query "${by.name}" is over "${filters}", but the list is of "${over.selection.entity}", so it cannot filter it`);
+			const remote = store.get(model);
+			const connection = remote.connections[over.ref.identity];
+			const visible = visibleStoreOf(remote.entities, remote.optimistic);
+			const among = (connection === void 0 ? [] : visibleItems(connection, over.ref.identity, remote.optimistic.overlays, remote.entities)).map((edge) => entityKey(edge.ref.entity, edge.ref.id));
+			const judged = matching(visible, by, input, { among });
+			const relation = relationOf(over.selection);
+			const items = [];
+			let assembledAll = true;
+			for (const key of judged.matched) {
+				const assembled = assemble(visible, key, relation);
+				if (assembled === void 0) {
+					assembledAll = false;
+					continue;
+				}
+				const decoded = Schema.decodeUnknownResult(over.selection.schema)(assembled.values);
+				if (Result.isFailure(decoded)) {
+					assembledAll = false;
+					continue;
+				}
+				items.push(decoded.success);
+			}
+			return {
+				items,
+				complete: judged.skipped.length === 0 && assembledAll && connection !== void 0 && !isGapped(connection) && !hasNext(connection) && !hasPrevious(connection)
+			};
+		},
 		refresh: (model, target) => Remote.refresh(bound, model, target),
+		overlay: (model, id, optimistic) => bound.store.set(model, updateRemote(bound.store.get(model), {
+			_tag: "OverlayShown",
+			id,
+			optimistic
+		})),
+		lift: (model, id) => {
+			const remote = bound.store.get(model);
+			const lifted = updateRemote(remote, {
+				_tag: "OverlayLifted",
+				id
+			});
+			return lifted === remote ? model : bound.store.set(model, lifted);
+		},
 		fetch: (ref) => ({
 			name: `Remote.query(${ref.query})`,
 			args: {
@@ -3155,7 +3987,7 @@ const bindDomain = (definition, store) => {
 					connection: ref.identity,
 					error: remoteError(error)
 				}),
-				onSuccess: (page) => pageMessage(ref.identity, page)
+				onSuccess: (page) => pageMessage(ref.identity, page, false, ref.window)
 			}))
 		}),
 		mutate: (model, mutation, input, options = {}) => {
@@ -3222,6 +4054,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, 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 };
+export { ConnectionChange, ConnectionChangeSchema, Entity, IDENTITY_SEPARATOR, Live, LiveChange, LiveEdge, LiveRequirement, MAX_FIELDS_PER_REQUEST, MAX_RELATION_DEPTH, Mutate, Mutation, MutationRequest, MutationResult, NormalizedEntity, PageSize, Query, QueryEdge, QueryRequest, QueryResult, QueryRpc, RELATION_ALIAS, 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, aliasedField, applyConnectionEvent, applyEntityEvent, assemble, beginMutation, beginOptimistic, belongsEncoded, classifyLive, clearStale, coalesceQueries, coalesceReads, coalescedLayer, connectionChangeOf, connectionIdentity, connectionsOf, cursor, edge, emptyConnection, emptyLiveState, emptyMutationState, emptyOptimistic, emptyRefresh, emptyStore, entityKey, entry, failMutation, failureOf, gc, hasField, hasNext, hasPrevious, initialRemoteModel, inspectEntity, inspectRemote, isFieldFailed, isFieldStale, isGapped, isLoading, isQueryLoading, isRefPage, isRemoteMessage, isTombstone, items, liveEventOf, liveHasNext, liveHasPrevious, markStale, matching, merge, missingFields, mutateRemote, mutationStatus, noFailures, pageSchema, plan, pruneOverlays, reachable, readField, reconcileMutation, refParts, refreshIsInFlight, refreshedAt, refsIn, relationAlias, 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, withRefreshRequested, writeEntities, writeEntity, writeRead };
 
 //# sourceMappingURL=index.mjs.map