foldkit-remote 0.5.0 → 0.7.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, Expr, Query as Query$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";
@@ -440,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";
@@ -498,7 +508,7 @@ const Query = {
 				input,
 				Input,
 				window: {},
-				identity: `${name}\u0000${stableStringify(encode(input))}`
+				identity: `${name}${stableStringify(encode(input))}`
 			})
 		};
 	},
@@ -1334,12 +1344,6 @@ const assembleRelation = (store, value, relation) => {
 * Entities: the descriptor an application declares, refs, ref pages, and
 * patches, with the codecs that carry refs on the wire.
 */
-/**
-* Relations are **references**, never inline target schemas: a ref cannot
-* reconstruct a full entity, and dereferencing is a store concern. Because the
-* target schema is not inlined, recursive relations cannot arise through the
-* schema graph.
-*/
 const refCodec = (entity) => Schema.Struct({
 	entity: Schema.String,
 	id: Schema.String
@@ -1424,6 +1428,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,
@@ -1440,6 +1556,7 @@ const inspectRemote = (model) => ({
 	live: Object.keys(model.live),
 	gaps: [...model.gaps],
 	loading: [...model.loading],
+	failures: model.failures,
 	mutations: {
 		pending: [...model.mutations.pending],
 		failed: [...model.mutations.failed],
@@ -1617,7 +1734,6 @@ const visibleItems = (connection, connectionId, overlays, store) => {
 //#region src/live.ts
 const emptyLiveState = {
 	cursor: 0,
-	stale: /* @__PURE__ */ new Set(),
 	boundary: {}
 };
 /**
@@ -1651,10 +1767,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.
@@ -1707,9 +1819,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),
@@ -1728,27 +1841,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. */
@@ -1890,17 +1989,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),
@@ -1930,9 +2045,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;
 }
 /**
@@ -1962,7 +2098,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;
@@ -1985,37 +2121,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;
 	})
@@ -2138,6 +2286,10 @@ 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(),
@@ -2151,7 +2303,8 @@ const initialRemoteModel = {
 	mutations: emptyMutationState,
 	gaps: /* @__PURE__ */ new Set(),
 	loading: /* @__PURE__ */ new Set(),
-	refresh: emptyRefresh
+	refresh: emptyRefresh,
+	failures: noFailures
 };
 /** The entity store and the mutation ledger are runtime values, not wire shapes. */
 const runtimeSchema = Schema.Unknown;
@@ -2163,7 +2316,11 @@ const remoteModelSchema = () => Schema.Struct({
 	mutations: runtimeSchema,
 	gaps: runtimeSchema,
 	loading: runtimeSchema,
-	refresh: runtimeSchema
+	refresh: runtimeSchema,
+	failures: Schema.Struct({
+		connections: Schema.Record(Schema.String, remoteErrorSchema),
+		fields: Schema.Record(Schema.String, remoteErrorSchema)
+	})
 });
 const retentionRootsSchema = Schema.Struct({
 	requirements: Schema.Array(ReadRequest),
@@ -2184,15 +2341,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")])
 	},
@@ -2277,6 +2437,26 @@ const withoutLoading = (loading, requests) => {
 */
 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 prunedLoading = (loading, roots, reached) => {
+	if (loading.size === 0) return loading;
+	const named = new Set(roots.connections.map((root) => connectionMark(root.identity)));
+	const kept = [...loading].filter((mark) => mark.startsWith(connectionPrefix) ? named.has(mark) : reached().has(markEntity(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
@@ -2391,31 +2571,68 @@ 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)
+			loading: withoutLoading(model.loading, message.requests),
+			failures: withoutFieldFailures(model.failures, [...fieldMarks(message.requests), ...patchedMarks(message.result.entities)])
 		};
+		case "ReadFailed":
+			if (message.stream !== void 0) return markGap(model, message.stream);
+			return {
+				...model,
+				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);
+			let reachedKeys;
+			const reached = () => reachedKeys ??= reachable(model.entities, message.roots, model.connections, model.optimistic, model.mutations.pending);
 			return {
 				...model,
 				...retained,
-				refresh: prunedRefresh(model.refresh, retained)
+				refresh: prunedRefresh(model.refresh, retained),
+				failures: prunedFailures(model.failures, message.roots, reached),
+				loading: prunedLoading(model.loading, message.roots, reached)
+			};
+		}
+		case "Hydrated": {
+			const restored = Object.entries(message.connections ?? {}).map(([identity, segments]) => [identity, {
+				segments: segments.map((edges) => ({
+					edges: [...edges],
+					start: unknown,
+					end: unknown
+				})),
+				stale: true
+			}]);
+			const written = Object.entries(message.entities).flatMap(([key, entry]) => message.merge === "replace" || !(key in model.entities) ? [...entry.present].map((field) => `${key}\u0000${field}`) : []);
+			return {
+				...model,
+				entities: RemotePersistence.mergeStores(model.entities, message.entities, message.merge),
+				failures: withoutFieldFailures(model.failures, written),
+				connections: message.merge === "replace" ? {
+					...model.connections,
+					...Object.fromEntries(restored)
+				} : {
+					...Object.fromEntries(restored),
+					...model.connections
+				}
 			};
 		}
-		case "Hydrated": return {
-			...model,
-			entities: RemotePersistence.mergeStores(model.entities, message.entities, message.merge)
-		};
 		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);
-			return entities === model.entities ? model : {
+			const failures = withoutFieldFailures(model.failures, reachedMarks(model.entities, 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,
-				entities
+				loading
 			};
 		}
 		case "ReadStarted": return {
@@ -2434,7 +2651,8 @@ 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 {
@@ -2456,18 +2674,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: {
@@ -2475,10 +2701,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 {
@@ -2490,25 +2722,181 @@ 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;
+			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);
+};
+/**
+* Every field a read's requests reach: their own, and through each relation
+* the store already holds, the fields they ask of its targets. A request with
+* a relation riding on it names no target id; the store does, and a failure
+* recorded on a target is reached only this way.
+*/
+const reachedMarks = (store, requests) => {
+	const marks = [];
+	const walked = /* @__PURE__ */ new Map();
+	const walk = (entity, id, requirement) => {
+		const key = entityKey(entity, id);
+		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) {
+			marks.push(fieldMark(entity, id, field));
+			const nested = requirement.relations?.[field];
+			if (nested === void 0) continue;
+			const value = readField(store, key, field);
+			if (value._tag === "None") continue;
+			for (const ref of targetsOf(value.value, nested)) walk(ref.entity, ref.id, nested);
+		}
+	};
+	for (const request of requests) walk(request.entity, request.id, request);
+	return marks;
+};
+/** The entity key a field mark belongs to. */
+const markEntity = (mark) => mark.slice(0, mark.indexOf("\0"));
+/**
+* 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 = (failures, roots, reached) => {
+	const named = new Set(roots.connections.map((root) => root.identity));
+	const connections = Object.entries(failures.connections).filter(([identity]) => named.has(identity));
+	const fields = Object.keys(failures.fields).length === 0 ? [] : Object.entries(failures.fields).filter(([mark]) => reached().has(markEntity(mark)));
+	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;
+/**
+* Whether a read is fetching any field `relation` reads of an entity, its own
+* or, through each relation the store holds, its targets'. A value whose owner
+* is being fetched is loading, not `Initial`: nothing is missing a fetch.
+*/
+const isLoadingThrough = (model, entity, id, relation) => {
+	if (model.loading.size === 0) return false;
+	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 false;
+		seen.add(requirement);
+		walked.set(key, seen);
+		for (const field of requirement.fields) {
+			if (model.loading.has(fieldMark(target, targetId, field))) return true;
+			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)) if (walk(ref.entity, ref.id, nested)) return true;
+		}
+		return false;
+	};
+	return walk(entity, id, relation);
+};
+/**
+* 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])];
@@ -2740,10 +3128,34 @@ const askedOf = (projection) => projection === void 0 ? nothingAsked : {
 	connections: connectionsOf(projection)
 };
 /**
+* Whether `outer` asks for everything `inner` does of one entity: each field,
+* each relation's own slice of its target, and each page window alike.
+*/
+const sliceCovers = (outer, inner) => outer.entity === inner.entity && inner.fields.every((field) => outer.fields.includes(field)) && Object.entries(inner.relations ?? {}).every(([field, relation]) => {
+	const wider = outer.relations?.[field];
+	return wider !== void 0 && sliceCovers(wider, relation);
+}) && Object.entries(inner.windows ?? {}).every(([field, window]) => outer.windows?.[field] !== void 0 && stableStringify(outer.windows[field]) === stableStringify(window));
+/**
+* Whether what `outer` asks includes everything `inner` asks: each list with
+* the slice it selects of its rows, and each entity with the slice it reads,
+* relations included. A Surface that shows a read is one whose projection
+* asks for all of it; one that reads part of it cannot be why it is fetched.
+* A Surface that asks for one entity in several pieces is already one
+* requirement here: projection metadata unions them per entity and id.
+*/
+const covers = (outer, inner) => {
+	const { connections, requirements } = outer;
+	return inner.connections.every((connection) => connections.some((wider) => wider.identity === connection.identity && (connection.select === void 0 || wider.select !== void 0 && sliceCovers(wider.select, connection.select)))) && inner.requirements.every((requirement) => requirements.some((wider) => wider.id === requirement.id && sliceCovers(wider, requirement)));
+};
+/**
 * Plans what a projection asks against the Model. A connection the Model holds
 * fresh contributes its visible items' selected fields to the entity plan; one
 * it does not hold, or holds stale, is a query to run (its items are planned
 * once the page arrives).
+*
+* 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 = [];
@@ -2751,18 +3163,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,
@@ -2790,22 +3230,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
@@ -2853,7 +3323,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({
@@ -2893,14 +3363,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. */
@@ -2930,7 +3403,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. */
@@ -2966,6 +3440,21 @@ const Remote = {
 	/** Whether a Message is one of Remote's, by tag. */
 	reduces: isRemoteMessage,
 	/**
+	* A patch of one entity's values, for a mutation's `optimistic` list or an
+	* overlay. Takes a `foldkit-entity` Entity or a Remote descriptor alike, so
+	* the domain you declared once is the one you patch:
+	* `Remote.patch(Project, 'p1', { name: 'Apollo II' })`. Values are the
+	* fields' wire shape, as the server writes them; a relation is its ref key
+	* (`'User:u1'`).
+	*/
+	patch: (entity, id, values) => descriptorOf(entity).patch(id, values),
+	/**
+	* A reference to one entity, for `ConnectionChange` and anything else that
+	* names a row: `Remote.ref(Project, 'p3')`. Either kind of entity, as with
+	* `Remote.patch`.
+	*/
+	ref: (entity, id) => descriptorOf(entity).ref(id),
+	/**
 	* Declares a Remote domain and binds it to its place in the application Model
 	* in one step; the result carries the application-facing operations. The
 	* descriptor alone is `Remote.define`, the binding alone `Remote.at`.
@@ -3023,8 +3512,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 (isLoadingThrough(remote, selection.entity, id, relation)) return { _tag: "Loading" };
+				return failure === void 0 ? { _tag: "Initial" } : {
+					_tag: "Failed",
+					error: failure
+				};
 			}
 		});
 	},
@@ -3083,6 +3582,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
@@ -3098,7 +3600,7 @@ 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).map((connection) => connection.identity);
+		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
@@ -3175,7 +3677,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
@@ -3232,8 +3734,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)
@@ -3242,7 +3746,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,
@@ -3291,7 +3836,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;
@@ -3321,6 +3866,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 (isLoadingThrough(remote, edge.ref.entity, edge.ref.id, relation)) 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,
@@ -3332,42 +3929,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
+						};
+					}
+					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
 						};
-						return refreshing ? {
-							_tag: "Refreshing",
-							value: page
-						} : {
-							_tag: "Ready",
-							value: page
+						case "Failed": return read;
+						default: return {
+							_tag: "Failed",
+							error: failure
 						};
-					});
+					}
 				}
 			};
 		},
@@ -3392,6 +3988,118 @@ 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
+					}])
+				}
+			};
+		},
+		why: (model, projection, options) => {
+			const state = projection.read(model);
+			const asked = askedOf(projection);
+			const reading = options?.surfaces === void 0 ? void 0 : Object.values(options.surfaces).filter((active) => {
+				const shown = active.projectionOf(model);
+				return shown !== void 0 && covers(askedOf(shown), asked);
+			}).map((active) => active.name);
+			const withSurfaces = reading === void 0 ? {} : { surfaces: reading };
+			switch (state._tag) {
+				case "Ready": return {
+					state: state._tag,
+					message: "Everything it selects is here.",
+					...withSurfaces
+				};
+				case "Refreshing": return {
+					state: state._tag,
+					message: "It is shown while a newer value is fetched.",
+					...withSurfaces
+				};
+				case "Loading": return {
+					state: state._tag,
+					message: "A request for it is in flight.",
+					...withSurfaces
+				};
+				case "NotFound": return {
+					state: state._tag,
+					message: "The server answered without it: it does not exist, or this principal may not see it.",
+					...withSurfaces
+				};
+				case "Failed": return {
+					state: state._tag,
+					message: state.error._tag === "DecodeError" ? `What the server sent does not decode against the Selection: ${state.error.message}` : `Its request failed: ${state.error.message}. Nothing retries a failed read on its own; Data.refresh asks again.`,
+					...withSurfaces
+				};
+				case "Initial":
+					if (reading === void 0) return {
+						state: state._tag,
+						reason: "Unknown",
+						message: "Nothing is fetching it. Pass the active record you give Data.subscriptions as `surfaces` to tell whether an active Surface reads it."
+					};
+					return reading.length === 0 ? {
+						state: state._tag,
+						reason: "NotObserved",
+						message: "No active Surface reads it, so nothing fetches it. Include it in a Surface that is active for this Model, in the record given to Data.subscriptions.",
+						surfaces: reading
+					} : {
+						state: state._tag,
+						reason: "NotFetching",
+						message: `${reading.join(", ")} ${reading.length === 1 ? "reads it and is" : "read it and are"} active, yet nothing is fetching it. Remote's Subscriptions are most likely not installed: give the runtime Data.subscriptions (or Data.wiring) and a RemoteClient.`,
+						surfaces: reading
+					};
+			}
+		},
+		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",
@@ -3418,7 +4126,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 = {}) => {
@@ -3485,6 +4193,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, 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, classifyLive, clearStale, coalesceQueries, coalesceReads, coalescedLayer, connectionChangeOf, connectionIdentity, connectionsOf, cursor, edge, emptyConnection, emptyLiveState, emptyMutationState, emptyOptimistic, emptyRefresh, 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, 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 };
+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, isLoadingThrough, 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