foldkit-remote 0.4.0 → 0.5.0

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { Context, Deferred, Duration, Effect, Layer, Option, Request, RequestResolver, Result, Schema, SchemaGetter, Stream } from "effect";
 import * as Domain from "foldkit-entity";
-import { Entity as Entity$1, SelectionTypeId } from "foldkit-entity";
+import { Entity as Entity$1, Expr, Query as Query$1, SelectionTypeId } from "foldkit-entity";
 import * as Subscription from "foldkit/subscription";
 import { Metadata } from "foldkit-surface";
 import { Rpc, RpcGroup } from "effect/unstable/rpc";
@@ -108,6 +108,91 @@ const requirementsOf = (projection) => RemoteRequirements.get(projection.metadat
 /** The query connections a Projection carries. */
 const connectionsOf = (projection) => RemoteConnections.get(projection.metadata);
 //#endregion
+//#region src/relation.ts
+/** Marks the codec `Entity.ref`/`Entity.refPage` produce, so a Selection can tell the field's shape. */
+const RelationAnnotation = "foldkitRemoteRelation";
+/** The target entity's name on the same codec, so a nested selection of another entity is refused. */
+const RelationEntityAnnotation = "foldkitRemoteRelationEntity";
+/**
+* A page of a relation that is a whole list is read under a name of its own, the
+* field's name and the page's size: `comments@first=10`. It is a field like any
+* other to the store, the planner, and the wire, so the whole list and a page of
+* it are held side by side, merged, marked stale, and persisted each on its own.
+* The server reads the name apart, reads the relation with the window, and
+* answers under the alias. A cursor is not part of the name: a page read from a
+* cursor merges onto the page it continues.
+*/
+const RELATION_ALIAS = "@";
+/** The alias a relation field is read under, for a window of this size. */
+const relationAlias = (field, window) => `${field}@${window.last !== void 0 ? `last=${window.last}` : `first=${window.first ?? ""}`}`;
+/** The field an alias reads; a name that is no alias is its own field. */
+const aliasedField = (name) => {
+	const at = name.indexOf("@");
+	return at === -1 ? name : name.slice(0, at);
+};
+/** Splits a ref key (`"Entity:id"`, the store key too) back into its parts. */
+const refParts = (encoded) => {
+	const separator = encoded.indexOf(":");
+	return separator === -1 ? {
+		entity: encoded,
+		id: ""
+	} : {
+		entity: encoded.slice(0, separator),
+		id: encoded.slice(separator + 1)
+	};
+};
+/**
+* The refs a relation value carries, in order. Anything that is not a ref key,
+* an array of them, or a page of them contributes nothing.
+*/
+const refsIn = (value) => {
+	if (typeof value === "string") return [refParts(value)];
+	if (Array.isArray(value)) return value.filter((item) => typeof item === "string").map(refParts);
+	if (value !== null && typeof value === "object") {
+		const refs = value.refs;
+		if (Array.isArray(refs)) return refs.filter((item) => typeof item === "string").map(refParts);
+	}
+	return [];
+};
+/** The refs in a relation value that name the relation's target entity, and no other. */
+const targetsOf = (value, relation) => refsIn(value).filter((ref) => ref.entity === relation.entity);
+const isRefPage = (value) => {
+	if (value === null || typeof value !== "object") return false;
+	const page = value;
+	return Array.isArray(page.refs) && page.refs.every((ref) => typeof ref === "string") && typeof page.hasNext === "boolean" && typeof page.hasPrevious === "boolean";
+};
+/**
+* The relation shape an entity field schema declares: a ref (`one`), a nullable
+* ref, an array of refs (`many`), or a page of refs (`page`). `undefined` for a
+* scalar field, which cannot take a nested selection.
+*/
+const relationShape = (schema) => shapeOf(schema.ast, false);
+const shapeOf = (ast, nullable) => {
+	const annotated = ast.annotations?.[RelationAnnotation];
+	if (annotated === "one" || annotated === "page") return {
+		kind: annotated,
+		nullable,
+		entity: String(ast.annotations?.[RelationEntityAnnotation])
+	};
+	if (ast._tag === "Arrays") {
+		const item = ast.rest?.[0];
+		const inner = item === void 0 ? void 0 : shapeOf(item, false);
+		return inner?.kind === "one" ? {
+			kind: "many",
+			nullable,
+			entity: inner.entity
+		} : void 0;
+	}
+	if (ast._tag === "Union") {
+		const members = ast.types ?? [];
+		const optional = members.some((member) => member._tag === "Null" || member._tag === "Undefined");
+		for (const member of members) {
+			const shape = shapeOf(member, optional);
+			if (shape !== void 0) return shape;
+		}
+	}
+};
+//#endregion
 //#region src/store.ts
 /**
 * The pure entity store: values, per-field presence, staleness, and tombstones.
@@ -142,6 +227,9 @@ const written = (previous, values, now, windows) => {
 		const requested = windows?.[field];
 		if (requested !== void 0 && requested !== "") nextWindows[field] = requested;
 		else delete nextWindows[field];
+		if (!field.includes("@")) {
+			for (const held of present) if (held.startsWith(`${field}@`) && !(held in values)) stale.add(held);
+		}
 	}
 	return {
 		values: {
@@ -361,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,
@@ -389,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: {
@@ -1016,74 +1164,6 @@ const hasNext = (connection) => {
 /** A connection with more than one segment has an explicit unknown gap. */
 const isGapped = (connection) => connection.segments.length > 1;
 //#endregion
-//#region src/relation.ts
-/** Marks the codec `Entity.ref`/`Entity.refPage` produce, so a Selection can tell the field's shape. */
-const RelationAnnotation = "foldkitRemoteRelation";
-/** The target entity's name on the same codec, so a nested selection of another entity is refused. */
-const RelationEntityAnnotation = "foldkitRemoteRelationEntity";
-/** Splits a ref key (`"Entity:id"`, the store key too) back into its parts. */
-const refParts = (encoded) => {
-	const separator = encoded.indexOf(":");
-	return separator === -1 ? {
-		entity: encoded,
-		id: ""
-	} : {
-		entity: encoded.slice(0, separator),
-		id: encoded.slice(separator + 1)
-	};
-};
-/**
-* The refs a relation value carries, in order. Anything that is not a ref key,
-* an array of them, or a page of them contributes nothing.
-*/
-const refsIn = (value) => {
-	if (typeof value === "string") return [refParts(value)];
-	if (Array.isArray(value)) return value.filter((item) => typeof item === "string").map(refParts);
-	if (value !== null && typeof value === "object") {
-		const refs = value.refs;
-		if (Array.isArray(refs)) return refs.filter((item) => typeof item === "string").map(refParts);
-	}
-	return [];
-};
-/** The refs in a relation value that name the relation's target entity, and no other. */
-const targetsOf = (value, relation) => refsIn(value).filter((ref) => ref.entity === relation.entity);
-const isRefPage = (value) => {
-	if (value === null || typeof value !== "object") return false;
-	const page = value;
-	return Array.isArray(page.refs) && page.refs.every((ref) => typeof ref === "string") && typeof page.hasNext === "boolean" && typeof page.hasPrevious === "boolean";
-};
-/**
-* The relation shape an entity field schema declares: a ref (`one`), a nullable
-* ref, an array of refs (`many`), or a page of refs (`page`). `undefined` for a
-* scalar field, which cannot take a nested selection.
-*/
-const relationShape = (schema) => shapeOf(schema.ast, false);
-const shapeOf = (ast, nullable) => {
-	const annotated = ast.annotations?.[RelationAnnotation];
-	if (annotated === "one" || annotated === "page") return {
-		kind: annotated,
-		nullable,
-		entity: String(ast.annotations?.[RelationEntityAnnotation])
-	};
-	if (ast._tag === "Arrays") {
-		const item = ast.rest?.[0];
-		const inner = item === void 0 ? void 0 : shapeOf(item, false);
-		return inner?.kind === "one" ? {
-			kind: "many",
-			nullable,
-			entity: inner.entity
-		} : void 0;
-	}
-	if (ast._tag === "Union") {
-		const members = ast.types ?? [];
-		const optional = members.some((member) => member._tag === "Null" || member._tag === "Undefined");
-		for (const member of members) {
-			const shape = shapeOf(member, optional);
-			if (shape !== void 0) return shape;
-		}
-	}
-};
-//#endregion
 //#region src/selection.ts
 /**
 * Selections: the fields a Surface picks of an entity (nested through
@@ -1109,15 +1189,20 @@ const relationOf = (selection) => ({
 	...selection.connections === void 0 ? {} : { windows: selection.connections },
 	...selection.relations === void 0 ? {} : { relations: selection.relations }
 });
+const fromEntitySelections = /* @__PURE__ */ new WeakMap();
 const Selection = {
 	/**
 	* The Remote Selection of a `foldkit-entity` Selection: the same members, read
 	* from Remote's store. `true` on a relation reads its refs, as it does here.
 	*/
 	from: (selection) => {
+		const compiled = fromEntitySelections.get(selection);
+		if (compiled !== void 0) return compiled;
 		const spec = {};
 		for (const [key, selected] of Object.entries(selection.members)) spec[key] = selected === true ? true : Domain.SelectionPageTypeId in selected ? Selection.connection(Entity.from(selected.selection.entity), selected.window, Selection.from(selected.selection)) : Selection.from(selected);
-		return Selection.make(Entity.from(selection.entity), spec);
+		const made = Selection.make(Entity.from(selection.entity), spec);
+		fromEntitySelections.set(selection, made);
+		return made;
 	},
 	/**
 	* The fields to read of `entity`. A nested `Selection` on a relation field
@@ -1127,12 +1212,14 @@ const Selection = {
 	make: (entity, selection) => {
 		if (Object.keys(selection).length === 0) throw new Error(`Selection.make: a selection of "${entity.name}" picks at least one field`);
 		const picked = {};
+		const names = [];
 		const connections = {};
 		const relations = {};
 		for (const key of Object.keys(selection)) {
 			const choice = selection[key];
 			if (choice === true) {
 				picked[key] = entity.fields[key];
+				names.push(key);
 				continue;
 			}
 			const nested = choice;
@@ -1141,18 +1228,21 @@ const Selection = {
 			if (nested.entity !== shape.entity) throw new Error(`Selection.make: "${key}" on "${entity.name}" refers to "${shape.entity}", not "${nested.entity}"`);
 			const nullable = (codec) => shape.nullable ? Schema.NullOr(codec) : codec;
 			if (nested.window !== void 0) {
-				connections[key] = nested.window;
+				const name = shape.kind === "many" ? relationAlias(key, nested.window) : key;
+				names.push(name);
+				connections[name] = nested.window;
 				picked[key] = nullable(nested.schema);
-				if (nested.fields.length > 0) relations[key] = relationOf(nested);
+				if (nested.fields.length > 0) relations[name] = relationOf(nested);
 				continue;
 			}
+			names.push(key);
 			const item = nested.schema;
 			picked[key] = nullable(shape.kind === "many" ? Schema.Array(item) : shape.kind === "page" ? pageSchema(item) : item);
 			relations[key] = relationOf(nested);
 		}
 		return {
 			entity: entity.name,
-			fields: Object.keys(selection),
+			fields: names,
 			schema: Schema.Struct(picked),
 			...Object.keys(connections).length === 0 ? {} : { connections },
 			...Object.keys(relations).length === 0 ? {} : { relations }
@@ -1189,12 +1279,12 @@ const assemble = (store, key, requirement) => {
 		refreshing ||= isFieldStale(store, key, field);
 		const relation = requirement.relations?.[field];
 		if (relation === void 0) {
-			values[field] = value.value;
+			values[aliasedField(field)] = value.value;
 			continue;
 		}
 		const nested = assembleRelation(store, value.value, relation);
 		if (nested === void 0) return void 0;
-		values[field] = nested.values;
+		values[aliasedField(field)] = nested.values;
 		refreshing ||= nested.refreshing;
 	}
 	return {
@@ -1291,6 +1381,8 @@ const Entity = {
 		return descriptor;
 	},
 	make: (name, schema) => {
+		const reserved = Object.keys(schema.fields).find((field) => field.includes("@"));
+		if (reserved !== void 0) throw new Error(`Entity.make: field "${reserved}" of "${name}" contains "@", which names a page of a relation`);
 		const descriptor = {
 			name,
 			schema,
@@ -1347,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],
@@ -1930,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
@@ -1977,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 {
@@ -2006,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: {},
@@ -2014,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;
@@ -2029,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),
@@ -2082,6 +2213,11 @@ const remoteMessageCases = {
 		requestId: Schema.String,
 		error: remoteErrorSchema
 	},
+	OverlayShown: {
+		id: Schema.String,
+		optimistic: Schema.Array(Schema.Unknown)
+	},
+	OverlayLifted: { id: Schema.String },
 	LiveReceived: {
 		stream: Schema.String,
 		event: Schema.Unknown,
@@ -2110,39 +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;
@@ -2179,32 +2398,31 @@ 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),
@@ -2219,6 +2437,17 @@ 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, message.error),
@@ -2414,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);
@@ -2639,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,
@@ -2801,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`
@@ -2847,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
@@ -3034,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;
@@ -3143,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: {
@@ -3222,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, mutationStatus, pageSchema, plan, pruneOverlays, reachable, readField, reconcileMutation, refParts, refreshConnection, refsIn, relationOf, relationShape, remoteDataSchema, remoteError, remoteErrorSchema, remoteMessageCases, remoteMessageSchema, remoteModelSchema, remove, removeLayer, removeOverlay, requirementKey, requirementsOf, retentionRootsSchema, schemaOf, segment, setStale, settleFailure, settleSuccess, shouldWake, stableStringify, targetsOf, terminal, tombstone, unknown, updateRemote, visibleItems, visibleStore, windowKey, writeEntities, writeEntity, writeRead };
+export { ConnectionChange, ConnectionChangeSchema, Entity, 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