foldkit-remote 0.3.0 → 0.5.0

package/dist/index.mjs

@@ -1,4 +1,7 @@
 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 * as Subscription from "foldkit/subscription";
 import { Metadata } from "foldkit-surface";
 import { Rpc, RpcGroup } from "effect/unstable/rpc";
 import { KeyValueStore } from "effect/unstable/persistence";
@@ -105,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.
@@ -139,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: {
@@ -266,6 +357,7 @@ const emptyMutationState = {
 	pending: /* @__PURE__ */ new Set(),
 	applied: /* @__PURE__ */ new Set(),
 	failed: /* @__PURE__ */ new Set(),
+	errors: /* @__PURE__ */ new Map(),
 	sequence: 0
 };
 /**
@@ -288,13 +380,26 @@ const beginMutation = (state, requestId) => ({
 	pending: /* @__PURE__ */ new Set([...state.pending, requestId]),
 	sequence: state.sequence + 1
 });
-const failMutation = (state, requestId) => {
+const failMutation = (state, requestId, error) => {
 	const pending = new Set(state.pending);
 	pending.delete(requestId);
+	const failed = remember(state.failed, requestId);
+	const errors = new Map([...state.errors, [requestId, error]]);
+	for (const id of errors.keys()) if (!failed.has(id)) errors.delete(id);
 	return {
 		...state,
 		pending,
-		failed: remember(state.failed, requestId)
+		failed,
+		errors
+	};
+};
+const mutationStatus = (state, requestId) => {
+	if (state.pending.has(requestId)) return { _tag: "Pending" };
+	if (state.applied.has(requestId)) return { _tag: "Applied" };
+	const error = state.errors.get(requestId);
+	return error === void 0 ? { _tag: "Unknown" } : {
+		_tag: "Failed",
+		error
 	};
 };
 /**
@@ -302,8 +407,8 @@ const failMutation = (state, requestId) => {
 * with the same `requestId` (a retry, or a live event describing the same change)
 * does not re-apply the entities, but still clears `pending`.
 */
-const reconcileMutation = (store, state, requestId, entities) => {
-	const next = state.applied.has(requestId) ? store : entities.reduce((current, entity) => writeEntity(current, entityKey(entity.entity, entity.id), entity.values), store);
+const reconcileMutation = (store, state, requestId, entities, deleted = []) => {
+	const next = state.applied.has(requestId) ? store : deleted.reduce((current, gone) => tombstone(current, entityKey(gone.entity, gone.id)), entities.reduce((current, entity) => writeEntity(current, entityKey(entity.entity, entity.id), entity.values), store));
 	const applied = remember(state.applied, requestId);
 	const pending = new Set(state.pending);
 	pending.delete(requestId);
@@ -344,7 +449,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,
@@ -372,6 +502,41 @@ const Query = {
 			})
 		};
 	},
+	/**
+	* 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: {
@@ -501,7 +666,12 @@ const MutationResult = Schema.Struct({
 	output: Schema.Unknown,
 	entities: Schema.Array(NormalizedEntity),
 	/** Connection changes the mutation made, applied alongside its entity patches. */
-	connections: Schema.optional(Schema.Array(ConnectionChangeSchema))
+	connections: Schema.optional(Schema.Array(ConnectionChangeSchema)),
+	/** Entities the mutation deleted; the client knows them absent from then on. */
+	deleted: Schema.optional(Schema.Array(Schema.Struct({
+		entity: Schema.String,
+		id: Schema.String
+	})))
 });
 const LiveRequirement = Schema.Struct({
 	version: Schema.Number,
@@ -825,7 +995,8 @@ const mutateRemote = Effect.fn("Remote.mutate")(function* (mutation, input, requ
 	return {
 		output: yield* Schema.decodeUnknownEffect(mutation.Output)(result.output).pipe(Effect.catchTag("SchemaError", (error) => Effect.fail(new RemoteMutationError({ message: error.message })))),
 		entities: result.entities,
-		connections: (result.connections ?? []).map(connectionChangeOf)
+		connections: (result.connections ?? []).map(connectionChangeOf),
+		deleted: result.deleted ?? []
 	};
 });
 //#endregion
@@ -993,6 +1164,266 @@ 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/selection.ts
+/**
+* Selections: the fields a Surface picks of an entity (nested through
+* relations, paged through connections), the requirement graph they imply,
+* and their assembly from the normalized store.
+*/
+const pageSchemas = /* @__PURE__ */ new WeakMap();
+const pageSchema = (item) => {
+	const cached = pageSchemas.get(item);
+	if (cached !== void 0) return cached;
+	const built = Schema.Struct({
+		items: Schema.Array(item),
+		hasNext: Schema.Boolean,
+		hasPrevious: Schema.Boolean
+	});
+	pageSchemas.set(item, built);
+	return built;
+};
+/** The requirement a nested selection contributes for its relation's target. */
+const relationOf = (selection) => ({
+	entity: selection.entity,
+	fields: selection.fields,
+	...selection.connections === void 0 ? {} : { windows: selection.connections },
+	...selection.relations === void 0 ? {} : { relations: selection.relations }
+});
+const 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);
+		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
+	* reads through the ref (or refs, or page of refs) the field holds into the
+	* target's fields; a scalar field cannot take one.
+	*/
+	make: (entity, selection) => {
+		if (Object.keys(selection).length === 0) throw new Error(`Selection.make: a selection of "${entity.name}" picks at least one field`);
+		const picked = {};
+		const 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;
+			const shape = relationShape(entity.fields[key]);
+			if (shape === void 0) throw new Error(`Selection.make: "${key}" on "${entity.name}" is not a relation field, so it cannot take a nested selection`);
+			if (nested.entity !== shape.entity) throw new Error(`Selection.make: "${key}" on "${entity.name}" refers to "${shape.entity}", not "${nested.entity}"`);
+			const nullable = (codec) => shape.nullable ? Schema.NullOr(codec) : codec;
+			if (nested.window !== void 0) {
+				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[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: names,
+			schema: Schema.Struct(picked),
+			...Object.keys(connections).length === 0 ? {} : { connections },
+			...Object.keys(relations).length === 0 ? {} : { relations }
+		};
+	},
+	/**
+	* A paginated relation: one page of refs to `entity` with a window, or, with
+	* a nested selection, one page of targets assembled through it.
+	*/
+	connection: ((entity, window, selection) => {
+		if (selection !== void 0 && selection.entity !== entity.name) throw new Error(`Selection.connection: a page of "${entity.name}" cannot select "${selection.entity}"`);
+		return {
+			entity: entity.name,
+			fields: selection?.fields ?? [],
+			schema: selection === void 0 ? Entity.refPage(entity) : pageSchema(selection.schema),
+			window,
+			...selection?.connections === void 0 ? {} : { connections: selection.connections },
+			...selection?.relations === void 0 ? {} : { relations: selection.relations }
+		};
+	})
+};
+/**
+* Reads an entity's selected fields out of the store, following each nested
+* relation into its targets. `undefined` means some field, at any depth, is
+* not present yet. A tombstoned target reads as `null` (or is dropped from a
+* list), so the Selection's codec decides whether that is a failure.
+*/
+const assemble = (store, key, requirement) => {
+	const values = {};
+	let refreshing = false;
+	for (const field of requirement.fields) {
+		const value = readField(store, key, field);
+		if (Option.isNone(value)) return void 0;
+		refreshing ||= isFieldStale(store, key, field);
+		const relation = requirement.relations?.[field];
+		if (relation === void 0) {
+			values[aliasedField(field)] = value.value;
+			continue;
+		}
+		const nested = assembleRelation(store, value.value, relation);
+		if (nested === void 0) return void 0;
+		values[aliasedField(field)] = nested.values;
+		refreshing ||= nested.refreshing;
+	}
+	return {
+		values,
+		refreshing
+	};
+};
+const assembleTarget = (store, ref, relation) => {
+	const key = entityKey(ref.entity, ref.id);
+	return isTombstone(store, key) ? "absent" : assemble(store, key, relation);
+};
+/** Assembles the targets a relation value refers to, in the value's own shape. */
+const assembleRelation = (store, value, relation) => {
+	if (value === null || value === void 0) return {
+		values: null,
+		refreshing: false
+	};
+	const targets = [];
+	let refreshing = false;
+	for (const ref of targetsOf(value, relation)) {
+		const target = assembleTarget(store, ref, relation);
+		if (target === void 0) return void 0;
+		if (target === "absent") continue;
+		targets.push(target.values);
+		refreshing ||= target.refreshing;
+	}
+	if (typeof value === "string") return {
+		values: targets.length === 0 ? null : targets[0],
+		refreshing
+	};
+	if (isRefPage(value)) return {
+		values: {
+			items: targets,
+			hasNext: value.hasNext,
+			hasPrevious: value.hasPrevious
+		},
+		refreshing
+	};
+	return {
+		values: targets,
+		refreshing
+	};
+};
+//#endregion
+//#region src/entity.ts
+/**
+* Entities: the descriptor an application declares, refs, ref pages, and
+* patches, with the codecs that carry refs on the wire.
+*/
+/**
+* Relations are **references**, never inline target schemas: a ref cannot
+* reconstruct a full entity, and dereferencing is a store concern. Because the
+* target schema is not inlined, recursive relations cannot arise through the
+* schema graph.
+*/
+const refCodec = (entity) => Schema.Struct({
+	entity: Schema.String,
+	id: Schema.String
+}).pipe(Schema.encodeTo(Schema.String, {
+	decode: SchemaGetter.transform(refParts),
+	encode: SchemaGetter.transform((ref) => entityKey(ref.entity, ref.id))
+})).annotate({
+	[RelationAnnotation]: "one",
+	[RelationEntityAnnotation]: entity
+});
+const refPageCodec = (entity) => Schema.Struct({
+	refs: Schema.Array(refCodec(entity)),
+	hasNext: Schema.Boolean,
+	hasPrevious: Schema.Boolean
+}).annotate({
+	[RelationAnnotation]: "page",
+	[RelationEntityAnnotation]: entity
+});
+const descriptors = /* @__PURE__ */ new WeakMap();
+const relationField = (relation) => {
+	const ref = refCodec(relation.target().name);
+	return relation.cardinality === "many" ? Schema.Array(ref) : relation.optional ? Schema.NullOr(ref) : ref;
+};
+const Entity = {
+	/**
+	* The Remote descriptor of a `foldkit-entity` Entity. Relations declared with
+	* `Entity.relate` become ref fields, so the store, the planner, and the server
+	* treat it as they treat an `Entity.make` descriptor.
+	*/
+	from: (entity) => {
+		const cached = descriptors.get(entity);
+		if (cached !== void 0) return cached;
+		const members = entity.members;
+		if (members.id?._tag !== "Field") throw new Error(`Entity.from: "${entity.name}" needs an "id" field for Remote to key it by`);
+		const fields = {};
+		for (const [key, member] of Object.entries(members)) fields[key] = member._tag === "Relation" ? relationField(member) : member.schema;
+		const descriptor = Entity.make(entity.name, Schema.Struct(fields));
+		descriptors.set(entity, descriptor);
+		return descriptor;
+	},
+	make: (name, schema) => {
+		const 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,
+			fields: schema.fields,
+			ref: (id) => ({
+				entity: name,
+				id: String(id)
+			}),
+			select: (selection) => Selection.make(descriptor, selection),
+			patch: (id, values) => ({
+				entity: name,
+				id: String(id),
+				values
+			})
+		};
+		return descriptor;
+	},
+	/** A relation to a known entity, decoded as a reference. */
+	ref: (entity) => refCodec(entity.name),
+	/** A relation by name, for recursive or forward references. */
+	refTo: (name) => refCodec(name),
+	/**
+	* The wire key a relation field carries (`"Entity:id"`). Adapters that read a
+	* foreign key emit this so the ref codec can decode it on the client.
+	*/
+	refKey: (ref) => entityKey(ref.entity, ref.id),
+	/** Splits a ref key back into its entity and id. */
+	refParts,
+	/** A relation value of one authoritative page of refs. */
+	refPage: (entity) => refPageCodec(entity.name),
+	/**
+	* A normalized patch for an entity, typed against its fields' wire shape:
+	* write a relation as its ref key (`Entity.refKey`), as the server does.
+	*/
+	patch: (ref, patch) => ({
+		entity: ref.entity,
+		id: ref.id,
+		values: patch
+	})
+};
+//#endregion
 //#region src/inspect.ts
 const inspectEntry = (key, entry) => ({
 	key,
@@ -1008,6 +1439,7 @@ const inspectRemote = (model) => ({
 	connections: Object.keys(model.connections),
 	live: Object.keys(model.live),
 	gaps: [...model.gaps],
+	loading: [...model.loading],
 	mutations: {
 		pending: [...model.mutations.pending],
 		failed: [...model.mutations.failed],
@@ -1138,8 +1570,8 @@ const release = (optimistic, requestId) => removeOverlay(removeLayer(optimistic,
 * a later layer re-wins on rebase. Confirmed connection changes are recorded
 * once per request, as overlays the request no longer owns.
 */
-const settleSuccess = (base, optimistic, state, requestId, entities, connections = []) => {
-	const reconciled = reconcileMutation(base, state, requestId, entities);
+const settleSuccess = (base, optimistic, state, requestId, entities, connections = [], deleted = []) => {
+	const reconciled = reconcileMutation(base, state, requestId, entities, deleted);
 	return {
 		store: reconciled.store,
 		state: reconciled.state,
@@ -1322,74 +1754,6 @@ const liveHasPrevious = (connection, state, connectionId) => hasPrevious(connect
 /** `hasNext` accounting for edges recorded outside the loaded boundary. */
 const liveHasNext = (connection, state, connectionId) => hasNext(connection) || (state.boundary[connectionId]?.after ?? 0) > 0;
 //#endregion
-//#region src/relation.ts
-/** Marks the codec `Entity.ref`/`Entity.refPage` produce, so a Selection can tell the field's shape. */
-const RelationAnnotation = "foldkitRemoteRelation";
-/** The target entity's name on the same codec, so a nested selection of another entity is refused. */
-const RelationEntityAnnotation = "foldkitRemoteRelationEntity";
-/** Splits a ref key (`"Entity:id"`, the store key too) back into its parts. */
-const refParts = (encoded) => {
-	const separator = encoded.indexOf(":");
-	return separator === -1 ? {
-		entity: encoded,
-		id: ""
-	} : {
-		entity: encoded.slice(0, separator),
-		id: encoded.slice(separator + 1)
-	};
-};
-/**
-* The refs a relation value carries, in order. Anything that is not a ref key,
-* an array of them, or a page of them contributes nothing.
-*/
-const refsIn = (value) => {
-	if (typeof value === "string") return [refParts(value)];
-	if (Array.isArray(value)) return value.filter((item) => typeof item === "string").map(refParts);
-	if (value !== null && typeof value === "object") {
-		const refs = value.refs;
-		if (Array.isArray(refs)) return refs.filter((item) => typeof item === "string").map(refParts);
-	}
-	return [];
-};
-/** The refs in a relation value that name the relation's target entity, and no other. */
-const targetsOf = (value, relation) => refsIn(value).filter((ref) => ref.entity === relation.entity);
-const isRefPage = (value) => {
-	if (value === null || typeof value !== "object") return false;
-	const page = value;
-	return Array.isArray(page.refs) && page.refs.every((ref) => typeof ref === "string") && typeof page.hasNext === "boolean" && typeof page.hasPrevious === "boolean";
-};
-/**
-* The relation shape an entity field schema declares: a ref (`one`), a nullable
-* ref, an array of refs (`many`), or a page of refs (`page`). `undefined` for a
-* scalar field, which cannot take a nested selection.
-*/
-const relationShape = (schema) => shapeOf(schema.ast, false);
-const shapeOf = (ast, nullable) => {
-	const annotated = ast.annotations?.[RelationAnnotation];
-	if (annotated === "one" || annotated === "page") return {
-		kind: annotated,
-		nullable,
-		entity: String(ast.annotations?.[RelationEntityAnnotation])
-	};
-	if (ast._tag === "Arrays") {
-		const item = ast.rest?.[0];
-		const inner = item === void 0 ? void 0 : shapeOf(item, false);
-		return inner?.kind === "one" ? {
-			kind: "many",
-			nullable,
-			entity: inner.entity
-		} : void 0;
-	}
-	if (ast._tag === "Union") {
-		const members = ast.types ?? [];
-		const optional = members.some((member) => member._tag === "Null" || member._tag === "Undefined");
-		for (const member of members) {
-			const shape = shapeOf(member, optional);
-			if (shape !== void 0) return shape;
-		}
-	}
-};
-//#endregion
 //#region src/plan.ts
 /**
 * The pure requirement planner.
@@ -1659,6 +2023,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
@@ -1706,6 +2072,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 {
@@ -1735,6 +2138,11 @@ const RemoteData = {
 * optimistic layers an application keeps in its Model, the Messages that
 * change it, and the pure reducer over them.
 */
+const emptyRefresh = {
+	generation: 0,
+	requested: /* @__PURE__ */ new Map(),
+	started: /* @__PURE__ */ new Map()
+};
 const initialRemoteModel = {
 	entities: emptyStore,
 	connections: {},
@@ -1743,10 +2151,7 @@ const initialRemoteModel = {
 	mutations: emptyMutationState,
 	gaps: /* @__PURE__ */ new Set(),
 	loading: /* @__PURE__ */ new Set(),
-	refresh: {
-		requested: 0,
-		started: 0
-	}
+	refresh: emptyRefresh
 };
 /** The entity store and the mutation ledger are runtime values, not wire shapes. */
 const runtimeSchema = Schema.Unknown;
@@ -1758,10 +2163,7 @@ const remoteModelSchema = () => Schema.Struct({
 	mutations: runtimeSchema,
 	gaps: runtimeSchema,
 	loading: runtimeSchema,
-	refresh: Schema.Struct({
-		requested: Schema.Number,
-		started: Schema.Number
-	})
+	refresh: runtimeSchema
 });
 const retentionRootsSchema = Schema.Struct({
 	requirements: Schema.Array(ReadRequest),
@@ -1801,12 +2203,21 @@ const remoteMessageCases = {
 	MutationSucceeded: {
 		requestId: Schema.String,
 		entities: Schema.Array(NormalizedEntity),
-		connections: Schema.optional(Schema.Array(Schema.Unknown))
+		connections: Schema.optional(Schema.Array(Schema.Unknown)),
+		deleted: Schema.optional(Schema.Array(Schema.Struct({
+			entity: Schema.String,
+			id: Schema.String
+		})))
 	},
 	MutationFailed: {
 		requestId: Schema.String,
 		error: remoteErrorSchema
 	},
+	OverlayShown: {
+		id: Schema.String,
+		optimistic: Schema.Array(Schema.Unknown)
+	},
+	OverlayLifted: { id: Schema.String },
 	LiveReceived: {
 		stream: Schema.String,
 		event: Schema.Unknown,
@@ -1835,39 +2246,122 @@ 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}`;
+/**
+* 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;
@@ -1904,39 +2398,38 @@ const updateRemote = (model, message) => {
 			entities: setStale(model.entities, marksOf(message.requests), false),
 			loading: withoutLoading(model.loading, message.requests)
 		};
-		case "RetentionChanged": return {
-			...model,
-			...gc(model, message.roots)
-		};
+		case "RetentionChanged": {
+			const retained = gc(model, message.roots);
+			return {
+				...model,
+				...retained,
+				refresh: prunedRefresh(model.refresh, retained)
+			};
+		}
 		case "Hydrated": return {
 			...model,
 			entities: RemotePersistence.mergeStores(model.entities, message.entities, message.merge)
 		};
 		case "RefreshStarted": {
-			const entities = setStale(model.entities, marksOf(message.requests), true);
+			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 : {
 				...model,
 				entities
 			};
 		}
-		case "ReadStarted": {
-			const started = Math.max(model.refresh.started, message.refresh ?? 0);
-			return {
-				...model,
-				loading: withLoading(model.loading, message.requests),
-				refresh: started === model.refresh.started ? model.refresh : {
-					...model.refresh,
-					started
-				}
-			};
-		}
+		case "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),
 			optimistic: beginOptimistic(model.optimistic, message.requestId, message.optimistic ?? [])
 		};
 		case "MutationSucceeded": {
-			const settled = settleSuccess(model.entities, model.optimistic, model.mutations, message.requestId, message.entities, message.connections ?? []);
+			const settled = settleSuccess(model.entities, model.optimistic, model.mutations, message.requestId, message.entities, message.connections ?? [], message.deleted ?? []);
 			return {
 				...model,
 				entities: settled.store,
@@ -1944,9 +2437,20 @@ const updateRemote = (model, message) => {
 				optimistic: settled.optimistic
 			};
 		}
+		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 {
 			...model,
-			mutations: failMutation(model.mutations, message.requestId),
+			mutations: failMutation(model.mutations, message.requestId, message.error),
 			optimistic: settleFailure(model.optimistic, message.requestId)
 		};
 		case "LiveReceived": {
@@ -2082,7 +2586,12 @@ const writeRead = (store, requests, result, now = 0) => {
 			windows: entry?.windows
 		});
 	}
-	return writeEntities(store, writes, now);
+	let answered = store;
+	for (const request of requests) {
+		const key = entityKey(request.entity, request.id);
+		if (!returned.has(key)) answered = tombstone(answered, key);
+	}
+	return writeEntities(answered, writes, now);
 };
 //#endregion
 //#region src/policy.ts
@@ -2115,224 +2624,6 @@ const RemotePolicy = {
 	refreshes: (policy) => policy._tag !== "CacheFirst"
 };
 //#endregion
-//#region src/entity.ts
-/**
-* Entities: the descriptor an application declares, refs, ref pages, and
-* patches, with the codecs that carry refs on the wire.
-*/
-/**
-* Relations are **references**, never inline target schemas: a ref cannot
-* reconstruct a full entity, and dereferencing is a store concern. Because the
-* target schema is not inlined, recursive relations cannot arise through the
-* schema graph.
-*/
-const refCodec = (entity) => Schema.Struct({
-	entity: Schema.String,
-	id: Schema.String
-}).pipe(Schema.encodeTo(Schema.String, {
-	decode: SchemaGetter.transform(refParts),
-	encode: SchemaGetter.transform((ref) => entityKey(ref.entity, ref.id))
-})).annotate({
-	[RelationAnnotation]: "one",
-	[RelationEntityAnnotation]: entity
-});
-const refPageCodec = (entity) => Schema.Struct({
-	refs: Schema.Array(refCodec(entity)),
-	hasNext: Schema.Boolean,
-	hasPrevious: Schema.Boolean
-}).annotate({
-	[RelationAnnotation]: "page",
-	[RelationEntityAnnotation]: entity
-});
-const Entity = {
-	make: (name, schema) => {
-		const descriptor = {
-			name,
-			schema,
-			fields: schema.fields,
-			ref: (id) => ({
-				entity: name,
-				id: String(id)
-			}),
-			select: (selection) => Selection.make(descriptor, selection),
-			patch: (id, values) => ({
-				entity: name,
-				id: String(id),
-				values
-			})
-		};
-		return descriptor;
-	},
-	/** A relation to a known entity, decoded as a reference. */
-	ref: (entity) => refCodec(entity.name),
-	/** A relation by name, for recursive or forward references. */
-	refTo: (name) => refCodec(name),
-	/**
-	* The wire key a relation field carries (`"Entity:id"`). Adapters that read a
-	* foreign key emit this so the ref codec can decode it on the client.
-	*/
-	refKey: (ref) => entityKey(ref.entity, ref.id),
-	/** Splits a ref key back into its entity and id. */
-	refParts,
-	/** A relation value of one authoritative page of refs. */
-	refPage: (entity) => refPageCodec(entity.name),
-	/**
-	* A normalized patch for an entity, typed against its fields' wire shape:
-	* write a relation as its ref key (`Entity.refKey`), as the server does.
-	*/
-	patch: (ref, patch) => ({
-		entity: ref.entity,
-		id: ref.id,
-		values: patch
-	})
-};
-//#endregion
-//#region src/selection.ts
-/**
-* Selections: the fields a Surface picks of an entity (nested through
-* relations, paged through connections), the requirement graph they imply,
-* and their assembly from the normalized store.
-*/
-const pageSchemas = /* @__PURE__ */ new WeakMap();
-const pageSchema = (item) => {
-	const cached = pageSchemas.get(item);
-	if (cached !== void 0) return cached;
-	const built = Schema.Struct({
-		items: Schema.Array(item),
-		hasNext: Schema.Boolean,
-		hasPrevious: Schema.Boolean
-	});
-	pageSchemas.set(item, built);
-	return built;
-};
-/** The requirement a nested selection contributes for its relation's target. */
-const relationOf = (selection) => ({
-	entity: selection.entity,
-	fields: selection.fields,
-	...selection.connections === void 0 ? {} : { windows: selection.connections },
-	...selection.relations === void 0 ? {} : { relations: selection.relations }
-});
-const Selection = {
-	/**
-	* The fields to read of `entity`. A nested `Selection` on a relation field
-	* reads through the ref (or refs, or page of refs) the field holds into the
-	* target's fields; a scalar field cannot take one.
-	*/
-	make: (entity, selection) => {
-		if (Object.keys(selection).length === 0) throw new Error(`Selection.make: a selection of "${entity.name}" picks at least one field`);
-		const picked = {};
-		const connections = {};
-		const relations = {};
-		for (const key of Object.keys(selection)) {
-			const choice = selection[key];
-			if (choice === true) {
-				picked[key] = entity.fields[key];
-				continue;
-			}
-			const nested = choice;
-			const shape = relationShape(entity.fields[key]);
-			if (shape === void 0) throw new Error(`Selection.make: "${key}" on "${entity.name}" is not a relation field, so it cannot take a nested selection`);
-			if (nested.entity !== shape.entity) throw new Error(`Selection.make: "${key}" on "${entity.name}" refers to "${shape.entity}", not "${nested.entity}"`);
-			const nullable = (codec) => shape.nullable ? Schema.NullOr(codec) : codec;
-			if (nested.window !== void 0) {
-				connections[key] = nested.window;
-				picked[key] = nullable(nested.schema);
-				if (nested.fields.length > 0) relations[key] = relationOf(nested);
-				continue;
-			}
-			const item = nested.schema;
-			picked[key] = nullable(shape.kind === "many" ? Schema.Array(item) : shape.kind === "page" ? pageSchema(item) : item);
-			relations[key] = relationOf(nested);
-		}
-		return {
-			entity: entity.name,
-			fields: Object.keys(selection),
-			schema: Schema.Struct(picked),
-			...Object.keys(connections).length === 0 ? {} : { connections },
-			...Object.keys(relations).length === 0 ? {} : { relations }
-		};
-	},
-	/**
-	* A paginated relation: one page of refs to `entity` with a window, or, with
-	* a nested selection, one page of targets assembled through it.
-	*/
-	connection: ((entity, window, selection) => {
-		if (selection !== void 0 && selection.entity !== entity.name) throw new Error(`Selection.connection: a page of "${entity.name}" cannot select "${selection.entity}"`);
-		return {
-			entity: entity.name,
-			fields: selection?.fields ?? [],
-			schema: selection === void 0 ? Entity.refPage(entity) : pageSchema(selection.schema),
-			window,
-			...selection?.connections === void 0 ? {} : { connections: selection.connections },
-			...selection?.relations === void 0 ? {} : { relations: selection.relations }
-		};
-	})
-};
-/**
-* Reads an entity's selected fields out of the store, following each nested
-* relation into its targets. `undefined` means some field, at any depth, is
-* not present yet. A tombstoned target reads as `null` (or is dropped from a
-* list), so the Selection's codec decides whether that is a failure.
-*/
-const assemble = (store, key, requirement) => {
-	const values = {};
-	let refreshing = false;
-	for (const field of requirement.fields) {
-		const value = readField(store, key, field);
-		if (Option.isNone(value)) return void 0;
-		refreshing ||= isFieldStale(store, key, field);
-		const relation = requirement.relations?.[field];
-		if (relation === void 0) {
-			values[field] = value.value;
-			continue;
-		}
-		const nested = assembleRelation(store, value.value, relation);
-		if (nested === void 0) return void 0;
-		values[field] = nested.values;
-		refreshing ||= nested.refreshing;
-	}
-	return {
-		values,
-		refreshing
-	};
-};
-const assembleTarget = (store, ref, relation) => {
-	const key = entityKey(ref.entity, ref.id);
-	return isTombstone(store, key) ? "absent" : assemble(store, key, relation);
-};
-/** Assembles the targets a relation value refers to, in the value's own shape. */
-const assembleRelation = (store, value, relation) => {
-	if (value === null || value === void 0) return {
-		values: null,
-		refreshing: false
-	};
-	const targets = [];
-	let refreshing = false;
-	for (const ref of targetsOf(value, relation)) {
-		const target = assembleTarget(store, ref, relation);
-		if (target === void 0) return void 0;
-		if (target === "absent") continue;
-		targets.push(target.values);
-		refreshing ||= target.refreshing;
-	}
-	if (typeof value === "string") return {
-		values: targets.length === 0 ? null : targets[0],
-		refreshing
-	};
-	if (isRefPage(value)) return {
-		values: {
-			items: targets,
-			hasNext: value.hasNext,
-			hasPrevious: value.hasPrevious
-		},
-		refreshing
-	};
-	return {
-		values: targets,
-		refreshing
-	};
-};
-//#endregion
 //#region src/index.ts
 /**
 * `foldkit-remote` — normalized application-facing server state.
@@ -2341,6 +2632,8 @@ const assembleRelation = (store, value, relation) => {
 * live classification, optimistic layers) performs no I/O. The `Remote.*`
 * helpers that read or mutate go through the `RemoteClient` Effect service.
 */
+const descriptorOf = (entity) => Entity$1.is(entity) ? Entity.from(entity) : entity;
+const selectionOf = (selection) => SelectionTypeId in selection ? Selection.from(selection) : selection;
 /**
 * The store a read or plan sees: the base with every pending optimistic layer
 * applied, so a request's patches show until it settles and a temporary id is
@@ -2350,6 +2643,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);
@@ -2386,21 +2695,24 @@ const identityMessage = (message) => message;
 /** A stable key for a live subscription's requirement set. */
 const liveStreamKey = (requirements) => requirements.map((requirement) => `${entityKey(requirement.entity, requirement.id)}:${[...requirement.fields].sort().join(",")}`).sort().join("|");
 /** Declares a Remote domain: its entities, queries, and mutations, plus the submodel. */
-const defineRemote = (config) => ({
-	entities: config.entities,
-	queries: config.queries ?? [],
-	mutations: config.mutations ?? [],
-	Model: remoteModelSchema(),
-	initial: initialRemoteModel,
-	Message: remoteMessageSchema,
-	update: updateRemote,
-	rpc: RemoteRpc,
-	registry: {
-		entities: new Map(config.entities.map((entity) => [entity.name, entity])),
-		queries: new Map((config.queries ?? []).map((query) => [query.name, query])),
-		mutations: new Map((config.mutations ?? []).map((mutation) => [mutation.name, mutation]))
-	}
-});
+const defineRemote = (config) => {
+	const entities = config.entities.map(descriptorOf);
+	return {
+		entities,
+		queries: config.queries ?? [],
+		mutations: config.mutations ?? [],
+		Model: remoteModelSchema(),
+		initial: initialRemoteModel,
+		Message: remoteMessageSchema,
+		update: updateRemote,
+		rpc: RemoteRpc,
+		registry: {
+			entities: new Map(entities.map((entity) => [entity.name, entity])),
+			queries: new Map((config.queries ?? []).map((query) => [query.name, query])),
+			mutations: new Map((config.mutations ?? []).map((mutation) => [mutation.name, mutation]))
+		}
+	};
+};
 /** Binds a Remote domain to its store's location in the application Model. */
 const bindRemote = (definition, store) => ({
 	definition,
@@ -2572,7 +2884,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,
@@ -2678,7 +2990,8 @@ const Remote = {
 	* as `Failed` instead of being asserted into `Value`. A present value with a
 	* stale field reads as `Refreshing`: an observer is refetching it.
 	*/
-	select: (bound, selection) => {
+	select: (bound, given) => {
+		const selection = selectionOf(given);
 		assertRegistered(bound, "Entity", bound.definition.registry.entities, selection.entity);
 		const relation = relationOf(selection);
 		return (id) => ({
@@ -2733,6 +3046,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`
@@ -2779,19 +3098,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).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
@@ -2896,7 +3213,8 @@ const Remote = {
 			_tag: "MutationSucceeded",
 			requestId,
 			entities: outcome.entities,
-			connections: outcome.connections
+			connections: outcome.connections,
+			deleted: outcome.deleted
 		});
 		return {
 			output: outcome.output,
@@ -2920,11 +3238,12 @@ const Remote = {
 	*/
 	live: (bound, surface, params, toMessage = identityMessage, options = {}) => liveEntry(bound, () => requirementsOf(surface.projection(params)), toMessage, options)
 };
+const brandEntries = (entries) => Subscription.make()(() => entries);
 /** The bound domain: the descriptor, the binding, and the operations over them. */
 const bindDomain = (definition, store) => {
 	const bound = bindRemote(definition, store);
 	const reduce = (model, message) => store.set(model, updateRemote(store.get(model), message));
-	return {
+	const domain = {
 		...definition,
 		...bound,
 		get: (selection, id) => Remote.select(bound, selection)(id),
@@ -2964,6 +3283,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;
@@ -2989,7 +3309,8 @@ const bindDomain = (definition, store) => {
 		}),
 		query: (query, input, options) => {
 			assertRegistered(bound, "Query", definition.registry.queries, query.name);
-			const { select, ...window } = options;
+			const { select: given, ...window } = options;
+			const select = selectionOf(given);
 			for (const [side, size] of [["first", window.first], ["last", window.last]]) if (size !== void 0 && !(Number.isInteger(size) && size >= 0)) throw new Error(`Remote: query "${query.name}" asks for ${side}: ${String(size)}; a page size is a non-negative integer`);
 			const listed = query.Result.entity;
 			if (listed === void 0) throw new Error(`Remote: query "${query.name}" is not a connection over an entity, so it has no page to select`);
@@ -3072,6 +3393,19 @@ const bindDomain = (definition, store) => {
 			} : void 0;
 		},
 		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: {
@@ -3118,15 +3452,25 @@ const bindDomain = (definition, store) => {
 							_tag: "MutationSucceeded",
 							requestId,
 							entities: outcome.entities,
-							connections: outcome.connections
+							connections: outcome.connections,
+							deleted: outcome.deleted
 						})
 					}))
 				}
 			};
 		},
+		mutation: (model, requestId) => mutationStatus(store.get(model).mutations, requestId),
 		reduce,
-		inspect: (model) => inspectRemote(store.get(model))
+		inspect: (model) => inspectRemote(store.get(model)),
+		wiring: (active, options) => ({
+			key: `remote:${bound.contract.name}`,
+			handles: Object.keys(remoteMessageCases),
+			route: (model, message) => isRemoteMessage(message) ? Option.some({ model: reduce(model, message) }) : Option.none(),
+			subscriptions: brandEntries(domain.subscriptions(active, options)),
+			contract: bound.contract
+		})
 	};
+	return domain;
 };
 /** The window keys of a `QueryOptions`, and only those, without the undefined ones. */
 const pickWindow = (window) => ({
@@ -3141,6 +3485,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, 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, 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 };
 
 //# sourceMappingURL=index.mjs.map