foldkit-remote 0.7.0 → 0.8.0

package/dist/index.mjs

@@ -1,6 +1,8 @@
 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, evaluate } from "foldkit-entity";
+import { mapMessage } from "foldkit/command";
+import { defineMessageUnion } from "foldkit/message";
 import * as Subscription from "foldkit/subscription";
 import { Metadata } from "foldkit-surface";
 import { Rpc, RpcGroup } from "effect/unstable/rpc";
@@ -208,6 +210,7 @@ const emptyEntry = {
 	values: {},
 	present: /* @__PURE__ */ new Set(),
 	stale: /* @__PURE__ */ new Set(),
+	unavailable: /* @__PURE__ */ new Set(),
 	tombstone: false,
 	updatedAt: 0,
 	windows: {}
@@ -220,10 +223,12 @@ const replace = (store, key, entry) => ({
 const written = (previous, values, now, windows) => {
 	const present = new Set(previous.present);
 	const stale = new Set(previous.stale);
+	const unavailable = new Set(previous.unavailable);
 	const nextWindows = { ...previous.windows };
 	for (const field of Object.keys(values)) {
 		present.add(field);
 		stale.delete(field);
+		unavailable.delete(field);
 		const requested = windows?.[field];
 		if (requested !== void 0 && requested !== "") nextWindows[field] = requested;
 		else delete nextWindows[field];
@@ -238,6 +243,7 @@ const written = (previous, values, now, windows) => {
 		},
 		present,
 		stale,
+		unavailable,
 		tombstone: false,
 		updatedAt: now,
 		windows: nextWindows
@@ -287,11 +293,40 @@ const setStale = (store, marks, stale) => {
 const markStale = (store, key, fields) => setStale(store, [[key, fields]], true);
 /** Ends a refresh that did not land: the fields are present again as they were. */
 const clearStale = (store, key, fields) => setStale(store, [[key, fields]], false);
+/**
+* Records fields the server settled without a value. A present field is left
+* as it is: the answer that settled it was not about the value it holds.
+* `false` forgets the marks, which is how a refresh asks again.
+*/
+const setUnavailable = (store, marks, unavailable) => {
+	let next;
+	for (const [key, fields] of marks) {
+		const previous = (next ?? store)[key] ?? emptyEntry;
+		if (previous.tombstone) continue;
+		const marked = new Set(previous.unavailable);
+		for (const field of fields) if (unavailable) {
+			if (!previous.present.has(field)) marked.add(field);
+		} else marked.delete(field);
+		if (marked.size === previous.unavailable.size) continue;
+		next ??= { ...store };
+		next[key] = {
+			...previous,
+			unavailable: marked
+		};
+	}
+	return next ?? store;
+};
+/** Whether the server settled this field without a value, and nothing has written it since. */
+const isFieldUnavailable = (store, key, field) => {
+	const value = store[key];
+	return value !== void 0 && !value.tombstone && value.unavailable.has(field);
+};
 /** Records that the entity is known to be absent, so it is not refetched. */
 const tombstone = (store, key) => replace(store, key, {
 	values: {},
 	present: /* @__PURE__ */ new Set(),
 	stale: /* @__PURE__ */ new Set(),
+	unavailable: /* @__PURE__ */ new Set(),
 	tombstone: true,
 	updatedAt: 0,
 	windows: {}
@@ -329,7 +364,8 @@ const readField = (store, key, field) => {
 };
 /**
 * The fields the planner must fetch. A tombstone makes every field known
-* (absent), so it returns an empty list and the entity is not refetched. A
+* (absent), so it returns an empty list and the entity is not refetched, and a
+* field the server settled without a value is known the same way. A
 * requested window that differs from the one a field was fetched with also
 * marks it missing, but only when the stored window is known (never `""`), so a
 * writer that does not record windows cannot cause a refetch loop.
@@ -338,7 +374,9 @@ const missingFields = (store, key, fields, windows) => {
 	const value = store[key];
 	if (value !== void 0 && value.tombstone) return [];
 	return [...fields].filter((field) => {
-		if (value === void 0 || !value.present.has(field) || value.stale.has(field)) return true;
+		if (value === void 0) return true;
+		if (!value.present.has(field)) return !value.unavailable.has(field);
+		if (value.stale.has(field)) return true;
 		const requested = windows?.[field];
 		const stored = value.windows[field];
 		return requested !== void 0 && stored !== void 0 && stored !== "" && stored !== requested;
@@ -588,7 +626,7 @@ const Query = {
 * server refuses a mismatch with `RemoteProtocolError`, so a shape change never
 * drifts silently: bump it whenever `ReadRequest` or `LiveRequirement` change.
 */
-const REMOTE_PROTOCOL_VERSION = 3;
+const REMOTE_PROTOCOL_VERSION = 4;
 var RemoteReadError = class extends Schema.TaggedError()("RemoteReadError", { message: Schema.String }) {};
 var RemoteMutationError = class extends Schema.TaggedError()("RemoteMutationError", { message: Schema.String }) {};
 var RemoteLiveError = class extends Schema.TaggedError()("RemoteLiveError", { message: Schema.String }) {};
@@ -649,7 +687,20 @@ const NormalizedEntity = Schema.Struct({
 	id: Schema.String,
 	values: Schema.Record(Schema.String, Schema.Unknown)
 });
-const ReadBatchResult = Schema.Struct({ entities: Schema.Array(NormalizedEntity) });
+/**
+* Fields a read asked for that the server answered without, and will not
+* answer with: the client stops asking. It says nothing about why, so a rule
+* that withholds a field is not itself on the wire.
+*/
+const SettledFields = Schema.Struct({
+	entity: Schema.String,
+	id: Schema.String,
+	fields: Schema.Array(Schema.String)
+});
+const ReadBatchResult = Schema.Struct({
+	entities: Schema.Array(NormalizedEntity),
+	settled: Schema.Array(SettledFields)
+});
 const MutationRequest = Schema.Struct({
 	/** Stable across transport retries so a mutation is not applied twice. */
 	requestId: Schema.String,
@@ -867,7 +918,7 @@ const coalesceReads = (read, options = {}) => Effect.gen(function* () {
 			for (const entry of entries) if (own.has(entry.request.key)) owned.set(entry.request.key, entry.request.requirement);
 			yield* Effect.forEach(readsOf(owned), ({ keys, requests }) => Effect.gen(function* () {
 				const exit = yield* Effect.exit(read({
-					version: 3,
+					version: 4,
 					requests
 				}));
 				for (const key of keys) {
@@ -883,10 +934,19 @@ const coalesceReads = (read, options = {}) => Effect.gen(function* () {
 	});
 	let resolver = RequestResolver.make(runAll);
 	if (options.window !== void 0) resolver = RequestResolver.setDelay(resolver, Duration.fromInputUnsafe(options.window));
-	return (batch) => batch.requests.length === 0 ? Effect.succeed({ entities: [] }) : Effect.forEach(batch.requests, (requirement) => Effect.request(new ReadRequirement({
+	return (batch) => batch.requests.length === 0 ? Effect.succeed({
+		entities: [],
+		settled: []
+	}) : Effect.forEach(batch.requests, (requirement) => Effect.request(new ReadRequirement({
 		key: requirementKey(requirement),
 		requirement
-	}), resolver), { concurrency: "unbounded" }).pipe(Effect.map((results) => ({ entities: [...new Set(results)].flatMap((result) => result.entities) })));
+	}), resolver), { concurrency: "unbounded" }).pipe(Effect.map((results) => {
+		const distinct = [...new Set(results)];
+		return {
+			entities: distinct.flatMap((result) => result.entities),
+			settled: distinct.flatMap((result) => result.settled)
+		};
+	}));
 });
 //#endregion
 //#region src/client.ts
@@ -1302,6 +1362,24 @@ const assemble = (store, key, requirement) => {
 		refreshing
 	};
 };
+/**
+* The first field `requirement` reads, at any depth, that the server settled
+* without a value, as `Entity:id.field`. A read that consults it says why it
+* cannot assemble rather than waiting on a field nothing will fetch.
+*/
+const unavailableOf = (store, key, requirement) => {
+	for (const field of requirement.fields) {
+		if (isFieldUnavailable(store, key, field)) return `${key}.${field}`;
+		const relation = requirement.relations?.[field];
+		if (relation === void 0) continue;
+		const value = readField(store, key, field);
+		if (Option.isNone(value) || value.value === null || value.value === void 0) continue;
+		for (const ref of targetsOf(value.value, relation)) {
+			const found = unavailableOf(store, entityKey(ref.entity, ref.id), relation);
+			if (found !== void 0) return found;
+		}
+	}
+};
 const assembleTarget = (store, ref, relation) => {
 	const key = entityKey(ref.entity, ref.id);
 	return isTombstone(store, key) ? "absent" : assemble(store, key, relation);
@@ -1545,6 +1623,7 @@ const inspectEntry = (key, entry) => ({
 	key,
 	present: [...entry.present],
 	stale: [...entry.stale],
+	unavailable: [...entry.unavailable],
 	tombstone: entry.tombstone,
 	updatedAt: entry.updatedAt,
 	windows: { ...entry.windows }
@@ -1878,6 +1957,41 @@ const followRelation = (value, relation) => targetsOf(value, relation).map((ref)
 	...relation,
 	id: ref.id
 }));
+/**
+* The earliest moment a value `requirements` read, following the relations the
+* store holds as `plan` does, goes stale under `freshness`, with the
+* requirements of the entities that go stale then. Nothing when no value is
+* both present and still fresh: what is already expired or stale is planned,
+* not awaited, which is what keeps a timer from firing on what it already
+* fired on.
+*/
+const deadlineOf = (store, requirements, freshness) => {
+	let at;
+	let due = [];
+	const walk = (group) => {
+		const key = entityKey(group.entity, group.id);
+		const entry = store[key];
+		if (entry === void 0 || entry.tombstone) return;
+		if (group.fields.some((field) => entry.present.has(field) && !entry.stale.has(field))) {
+			const expires = entry.updatedAt + freshness.freshness;
+			if (expires > freshness.now) {
+				if (at === void 0 || expires < at) {
+					at = expires;
+					due = [group];
+				} else if (expires === at) due.push(group);
+			}
+		}
+		for (const [field, relation] of Object.entries(group.relations ?? {})) {
+			const value = readField(store, key, field);
+			if (value._tag === "Some") for (const next of followRelation(value.value, relation)) walk(next);
+		}
+	};
+	for (const group of Requirement.merge(requirements)) walk(group);
+	return at === void 0 ? void 0 : {
+		at,
+		due: Requirement.merge(due)
+	};
+};
 const plan = (store, requirements, options = {}) => {
 	const { freshness, force = false } = options;
 	const planned = [];
@@ -1989,7 +2103,7 @@ const gc = (state, roots) => {
 * application's choice.
 */
 /** Bump when the serialized shape changes; a mismatch discards the cache. */
-const REMOTE_CACHE_VERSION = 4;
+const REMOTE_CACHE_VERSION = 5;
 /**
 * A snapshot of a Model, keeping the entity cache and only the connections
 * named.
@@ -2012,13 +2126,14 @@ const sorted = (values) => [...values].sort();
 * whatever order they were built in.
 */
 const serializeStore = (snapshot, scope) => ({
-	version: 4,
+	version: 5,
 	scope: scope ?? null,
 	connections: snapshot.connections,
 	entities: Object.fromEntries(Object.entries(snapshot.entities).map(([key, entry]) => [key, {
 		values: entry.values,
 		present: sorted(entry.present),
 		stale: sorted(entry.stale),
+		unavailable: sorted(entry.unavailable),
 		tombstone: entry.tombstone,
 		updatedAt: entry.updatedAt,
 		windows: entry.windows
@@ -2033,6 +2148,7 @@ const parseEntry = (value) => {
 	if (entry.values === null || typeof entry.values !== "object" || Array.isArray(entry.values)) throw new Error("entry.values is not a record");
 	if (!isStringArray(entry.present)) throw new Error("entry.present is not a string array");
 	if (!isStringArray(entry.stale)) throw new Error("entry.stale is not a string array");
+	if (!isStringArray(entry.unavailable)) throw new Error("entry.unavailable is not a string array");
 	if (typeof entry.tombstone !== "boolean") throw new Error("entry.tombstone is not a boolean");
 	if (typeof entry.updatedAt !== "number") throw new Error("entry.updatedAt is not a number");
 	if (!isStringRecord(entry.windows)) throw new Error("entry.windows is not a string record");
@@ -2040,6 +2156,7 @@ const parseEntry = (value) => {
 		values: entry.values,
 		present: new Set(entry.present),
 		stale: new Set(entry.stale),
+		unavailable: new Set(entry.unavailable),
 		tombstone: entry.tombstone,
 		updatedAt: entry.updatedAt,
 		windows: entry.windows
@@ -2098,7 +2215,7 @@ const hydrate = (raw, options = {}) => {
 	}
 	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return void 0;
 	const candidate = parsed;
-	if (candidate.version !== 4) return void 0;
+	if (candidate.version !== 5) return void 0;
 	if ((candidate.scope ?? null) !== (options.scope ?? null)) return void 0;
 	if (candidate.entities === null || typeof candidate.entities !== "object") return void 0;
 	if (Array.isArray(candidate.entities)) return void 0;
@@ -2293,7 +2410,32 @@ const noFailures = {
 const emptyRefresh = {
 	generation: 0,
 	requested: /* @__PURE__ */ new Map(),
-	started: /* @__PURE__ */ new Map()
+	started: /* @__PURE__ */ new Map(),
+	floor: 0
+};
+/**
+* The Model with everything the server told it forgotten: values, tombstones,
+* unavailable fields, connections, live cursors, failures, and what is in
+* flight. For a change of principal, whose facts these were. The mutation
+* sequence is kept, so request ids stay unique, and a mutation in flight is
+* treated as applied: its answer, when it comes, writes nothing here.
+*/
+const forgetRemote = (model) => {
+	const generation = model.refresh.generation + 1;
+	return {
+		...initialRemoteModel,
+		refresh: {
+			generation,
+			requested: /* @__PURE__ */ new Map(),
+			started: /* @__PURE__ */ new Map(),
+			floor: generation
+		},
+		mutations: {
+			...emptyMutationState,
+			sequence: model.mutations.sequence,
+			applied: /* @__PURE__ */ new Set([...model.mutations.applied, ...model.mutations.pending])
+		}
+	};
 };
 const initialRemoteModel = {
 	entities: emptyStore,
@@ -2487,7 +2629,7 @@ const prunedRefresh = (refresh, retained) => {
 * anything else is.
 */
 const refreshedAt = (refresh, requests, connections = []) => {
-	let at = 0;
+	let at = refresh.floor;
 	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;
@@ -2619,7 +2761,8 @@ const updateRemote = (model, message) => {
 		}
 		case "RefreshStarted": {
 			const asked = message.requests.reduce((store, request) => isTombstone(store, entityKey(request.entity, request.id)) ? remove(store, entityKey(request.entity, request.id)) : store, model.entities);
-			const entities = setStale(asked, marksOf(message.requests), true);
+			const marks = marksOf(message.requests);
+			const entities = setUnavailable(setStale(asked, marks, true), marks, false);
 			const failures = withoutFieldFailures(model.failures, reachedMarks(model.entities, message.requests));
 			return entities === model.entities && failures === model.failures ? model : {
 				...model,
@@ -2974,12 +3117,13 @@ const writeRead = (store, requests, result, now = 0) => {
 			windows: entry?.windows
 		});
 	}
+	const settled = new Set(result.settled.map((entry) => entityKey(entry.entity, entry.id)));
 	let answered = store;
 	for (const request of requests) {
 		const key = entityKey(request.entity, request.id);
-		if (!returned.has(key)) answered = tombstone(answered, key);
+		if (!returned.has(key) && !settled.has(key)) answered = tombstone(answered, key);
 	}
-	return writeEntities(answered, writes, now);
+	return setUnavailable(writeEntities(answered, writes, now), result.settled.map((entry) => [entityKey(entry.entity, entry.id), entry.fields]), true);
 };
 //#endregion
 //#region src/policy.ts
@@ -3012,6 +3156,221 @@ const RemotePolicy = {
 	refreshes: (policy) => policy._tag !== "CacheFirst"
 };
 //#endregion
+//#region src/resume.ts
+/**
+* What of Remote's state crosses from a server render to the browser.
+*
+* A page rendered a moment ago sends exactly what its active Surfaces read:
+* for each requirement the fields it names, following relations through the
+* refs the store holds, and each connection whole, with its boundaries, so
+* "load more" knows where the server stopped. A live subscription's cursor
+* crosses with the entities it covers, so a subscription started in the
+* browser resumes where the server's left off.
+*
+* This is not a `Snapshot`, which is built for a cache that survived a reload
+* and deliberately keeps no cursors. Nothing else of `RemoteModel` crosses:
+* loading marks, failures, the mutation ledger, optimistic layers, gaps and
+* retention start from their initial values in the browser.
+*/
+const CapturedEntry = Schema.Struct({
+	values: Schema.Record(Schema.String, Schema.Unknown),
+	present: Schema.Array(Schema.String),
+	stale: Schema.Array(Schema.String),
+	unavailable: Schema.Array(Schema.String),
+	windows: Schema.Record(Schema.String, Schema.String),
+	tombstone: Schema.Boolean,
+	updatedAt: Schema.Number
+});
+const CapturedBoundary = Schema.Union([
+	Schema.TaggedStruct("Terminal", {}),
+	Schema.TaggedStruct("Cursor", { cursor: Schema.String }),
+	Schema.TaggedStruct("Unknown", {})
+]);
+const CapturedConnection = Schema.Struct({
+	segments: Schema.Array(Schema.Struct({
+		edges: Schema.Array(Schema.Struct({
+			key: Schema.String,
+			ref: Schema.Struct({
+				entity: Schema.String,
+				id: Schema.String
+			})
+		})),
+		start: CapturedBoundary,
+		end: CapturedBoundary
+	})),
+	stale: Schema.Boolean
+});
+const CapturedLive = Schema.Struct({
+	cursor: Schema.Number,
+	boundary: Schema.Record(Schema.String, Schema.Struct({
+		before: Schema.Number,
+		after: Schema.Number
+	}))
+});
+/**
+* Marks a Subscription entry Remote built as one that may start late under
+* `foldkit-ssr`'s deferred boot (its decision 10): a read with resumed data
+* plans nothing, a live subscription resumes from the cursor the envelope
+* carries, and retention running late collects late. Non-enumerable, so the
+* runtime's iteration of an entry never sees it.
+*/
+const DEFERRABLE = Symbol.for("foldkit-remote/deferrable");
+/** Marks every entry of a record Remote built, lifted or not. */
+const markAll = (entries) => {
+	for (const entry of Object.values(entries)) Object.defineProperty(entry, DEFERRABLE, {
+		value: true,
+		enumerable: false
+	});
+	return entries;
+};
+/** The captured part of a Remote store, as JSON. */
+const RemoteCapture = Schema.Struct({
+	entities: Schema.Record(Schema.String, CapturedEntry),
+	connections: Schema.Record(Schema.String, CapturedConnection),
+	live: Schema.Record(Schema.String, CapturedLive)
+});
+/** What some projections read, from their metadata. */
+const askedOf$1 = (projections) => ({
+	requirements: projections.flatMap((projection) => RemoteRequirements.get(projection.metadata)),
+	connections: projections.flatMap((projection) => RemoteConnections.get(projection.metadata))
+});
+/** Whether every `entity:id:fields` part of a live stream key was captured with those fields. */
+const liveCovered = (stream, entries) => stream.split("|").every((part) => {
+	const split = part.lastIndexOf(":");
+	const entry = entries.get(part.slice(0, split));
+	const fields = part.slice(split + 1).split(",").filter((field) => field !== "");
+	return entry !== void 0 && fields.every((field) => entry.present.has(field));
+});
+/**
+* Captures what some projections read from a store: the fields each
+* requirement names, through its relations; each connection whole, and the
+* fields its selection reads of each item; and each live cursor whose
+* entities were all captured with the fields it follows.
+*/
+const captureRemote = (remote, projections) => {
+	const store = remote.entities;
+	const entries = /* @__PURE__ */ new Map();
+	const walked = /* @__PURE__ */ new Map();
+	const walk = (entity, id, requirement) => {
+		const key = entityKey(entity, id);
+		const seen = walked.get(key) ?? /* @__PURE__ */ new Set();
+		if (seen.has(requirement)) return;
+		seen.add(requirement);
+		walked.set(key, seen);
+		const stored = store[key];
+		if (stored === void 0) return;
+		const entry = entries.get(key) ?? {
+			values: {},
+			present: /* @__PURE__ */ new Set(),
+			stale: /* @__PURE__ */ new Set(),
+			unavailable: /* @__PURE__ */ new Set(),
+			windows: {},
+			tombstone: stored.tombstone,
+			updatedAt: stored.updatedAt
+		};
+		entries.set(key, entry);
+		for (const field of requirement.fields) {
+			if (stored.unavailable.has(field)) entry.unavailable.add(field);
+			if (!stored.present.has(field)) continue;
+			entry.values[field] = stored.values[field];
+			entry.present.add(field);
+			if (stored.stale.has(field)) entry.stale.add(field);
+			const window = stored.windows[field];
+			if (window !== void 0) entry.windows[field] = window;
+			const nested = requirement.relations?.[field];
+			if (nested === void 0) continue;
+			const value = readField(store, key, field);
+			if (value._tag === "None") continue;
+			for (const ref of targetsOf(value.value, nested)) walk(ref.entity, ref.id, nested);
+		}
+	};
+	const asked = askedOf$1(projections);
+	for (const requirement of asked.requirements) walk(requirement.entity, requirement.id, requirement);
+	const connections = {};
+	for (const { identity, select } of asked.connections) {
+		const connection = remote.connections[identity];
+		if (connection === void 0) continue;
+		connections[identity] = connection;
+		for (const segment of connection.segments) for (const edge of segment.edges) walk(edge.ref.entity, edge.ref.id, select);
+	}
+	const live = {};
+	for (const [stream, state] of Object.entries(remote.live)) if (liveCovered(stream, entries)) live[stream] = state;
+	return {
+		entities: Object.fromEntries([...entries].map(([key, entry]) => [key, {
+			values: entry.values,
+			present: [...entry.present],
+			stale: [...entry.stale],
+			unavailable: [...entry.unavailable],
+			windows: entry.windows,
+			tombstone: entry.tombstone,
+			updatedAt: entry.updatedAt
+		}])),
+		connections: Object.fromEntries(Object.entries(connections).map(([identity, connection]) => [identity, {
+			segments: connection.segments.map((segment) => ({
+				edges: segment.edges.map((edge) => ({
+					key: edge.key,
+					ref: edge.ref
+				})),
+				start: segment.start,
+				end: segment.end
+			})),
+			stale: connection.stale
+		}])),
+		live
+	};
+};
+/**
+* Sets a capture onto a store: its entities, connections and live cursors
+* replace any held under the same keys, and nothing else of the store changes.
+*/
+const restoreRemote = (remote, capture) => ({
+	...remote,
+	entities: {
+		...remote.entities,
+		...Object.fromEntries(Object.entries(capture.entities).map(([key, entry]) => [key, {
+			values: entry.values,
+			present: new Set(entry.present),
+			stale: new Set(entry.stale),
+			unavailable: new Set(entry.unavailable),
+			windows: entry.windows,
+			tombstone: entry.tombstone,
+			updatedAt: entry.updatedAt
+		}]))
+	},
+	connections: {
+		...remote.connections,
+		...Object.fromEntries(Object.entries(capture.connections).map(([identity, connection]) => [identity, {
+			segments: connection.segments.map((segment) => ({
+				edges: segment.edges,
+				start: segment.start,
+				end: segment.end
+			})),
+			stale: connection.stale
+		}]))
+	},
+	live: {
+		...remote.live,
+		...capture.live
+	}
+});
+const encodeCapture = Schema.encodeSync(RemoteCapture);
+const decodeCapture = Schema.decodeUnknownResult(RemoteCapture);
+/**
+* The resume part for a Remote domain, for `SSR.plan`'s `parts`: it sends
+* what the plan's active Surfaces read from this domain's store, and nothing
+* else of it. `id` tells two domains in one application apart.
+*/
+const resumePart = (domain, options = {}) => ({
+	id: options.id ?? "remote",
+	covers: [RemoteRequirements.name, RemoteConnections.name],
+	deferrable: (_key, entry) => typeof entry === "object" && entry !== null && DEFERRABLE in entry,
+	capture: (model, projections) => encodeCapture(captureRemote(domain.store.get(model), projections)),
+	restore: (model, value) => Result.match(decodeCapture(value), {
+		onFailure: (error) => Result.fail(`Remote's state does not decode: ${error.message}`),
+		onSuccess: (capture) => Result.succeed(domain.store.set(model, restoreRemote(domain.store.get(model), capture)))
+	})
+});
+//#endregion
 //#region src/index.ts
 /**
 * `foldkit-remote` — normalized application-facing server state.
@@ -3061,6 +3420,22 @@ const visibleStoreOf = (entities, optimistic) => {
 	}
 	return visible;
 };
+/**
+* `Failed` naming a field the server settled without a value, when one is
+* among what `relation` reads of the entity; otherwise nothing, and the store
+* merely lacks the value. The reason stays with the server, so a view shows
+* the field it cannot have, not why.
+*/
+const unavailableFailure = (store, key, relation) => {
+	const field = unavailableOf(store, key, relation);
+	return field === void 0 ? void 0 : {
+		_tag: "Failed",
+		error: {
+			_tag: "Unavailable",
+			message: `The server answered without ${field}, and will not answer with it: the field is not available to this client.`
+		}
+	};
+};
 const readResults = /* @__PURE__ */ new WeakMap();
 const memoRead = (snapshot, by, key, compute) => {
 	let byScope = readResults.get(snapshot);
@@ -3171,10 +3546,13 @@ const planAsked = (remote, asked, options) => {
 		const edges = visibleItems(known, connection.identity, remote.optimistic.overlays, remote.entities);
 		items.push(...itemsOf(edges.map((edge) => edge.ref), connection.select));
 	}
-	const planned = plan(visibleStoreOf(remote.entities, remote.optimistic), [...asked.requirements, ...items], options);
+	const visible = visibleStoreOf(remote.entities, remote.optimistic);
+	const read = [...asked.requirements, ...items];
+	const planned = plan(visible, read, options);
 	return {
 		requirements: options.force === true ? planned : withoutFailedFields(remote, planned),
-		queries
+		queries,
+		expires: options.freshness === void 0 ? null : deadlineOf(visible, read, options.freshness) ?? null
 	};
 };
 /**
@@ -3301,7 +3679,7 @@ const readMessage = (requirements, now) => Effect.gen(function* () {
 	const client = yield* RemoteClient;
 	const at = now();
 	const result = yield* Effect.result(client.read({
-		version: 3,
+		version: 4,
 		requests: requirements
 	}));
 	return Result.isFailure(result) ? {
@@ -3348,7 +3726,11 @@ const observeEntry = (bound, askedOf, toMessage, options) => {
 		dependenciesSchema: Schema.Struct({
 			requirements: Schema.Array(ReadRequest),
 			queries: Schema.Array(PlannedQuery),
-			refresh: Schema.Number
+			refresh: Schema.Number,
+			expires: Schema.NullOr(Schema.Struct({
+				at: Schema.Number,
+				due: Schema.Array(ReadRequest)
+			}))
 		}),
 		modelToDependencies: (model) => {
 			const remote = bound.store.get(model);
@@ -3360,10 +3742,11 @@ const observeEntry = (bound, askedOf, toMessage, options) => {
 					identity,
 					window,
 					select
-				}))
+				})),
+				expires: planned.expires
 			};
 		},
-		dependenciesToStream: ({ requirements, queries, refresh }) => Stream.concat(Stream.fromIterable([...requirements.length === 0 ? [] : [toMessage({
+		dependenciesToStream: ({ requirements, queries, refresh, expires }) => Stream.concat(Stream.fromIterable([...requirements.length === 0 ? [] : [toMessage({
 			_tag: "ReadStarted",
 			requests: requirements,
 			refresh
@@ -3373,21 +3756,27 @@ const observeEntry = (bound, askedOf, toMessage, options) => {
 		})] : []], ...queries.length === 0 ? [] : [toMessage({
 			_tag: "QueryStarted",
 			connections: queries.map((query) => query.identity)
-		})]]), Stream.mergeAll([...requirements.length === 0 ? [] : [Stream.fromEffect(read(requirements))], ...queries.map((query) => Stream.fromEffect(run(query)))], { concurrency: "unbounded" }))
+		})]]), Stream.merge(Stream.mergeAll([...requirements.length === 0 ? [] : [Stream.fromEffect(read(requirements))], ...queries.map((query) => Stream.fromEffect(run(query)))], { concurrency: "unbounded" }), expires === null ? Stream.empty : Stream.fromEffect(Effect.as(Effect.sleep(Math.max(0, expires.at - now())), toMessage({
+			_tag: "RefreshStarted",
+			requests: expires.due
+		})))))
 	};
 };
 /** The live entry: subscribes to `requirementsOf(model)` from the Model's resume cursor. */
 const liveEntry = (bound, requirementsOf, toMessage, options) => ({
 	dependenciesSchema: Schema.Struct({
 		requirements: Schema.Array(ReadRequest),
-		cursor: Schema.Number
+		cursor: Schema.Number,
+		floor: Schema.Number
 	}),
 	modelToDependencies: (model) => {
 		const requirements = requirementsOf(model);
 		const stream = liveStreamKey(requirements);
+		const remote = bound.store.get(model);
 		return {
 			requirements,
-			cursor: bound.store.get(model).live[stream]?.cursor ?? 0
+			cursor: remote.live[stream]?.cursor ?? 0,
+			floor: remote.refresh.floor
 		};
 	},
 	dependenciesToStream: ({ requirements, cursor }) => requirements.length === 0 ? Stream.empty : Stream.unwrap(Effect.gen(function* () {
@@ -3440,6 +3829,52 @@ const Remote = {
 	/** Whether a Message is one of Remote's, by tag. */
 	reduces: isRemoteMessage,
 	/**
+	* Remote's Messages as one Schema, for a wrapper variant in the
+	* application's union: `GotRemoteMessage: { message: Remote.Message }`. With
+	* a wrapper, `update` matches the application's union exhaustively and
+	* `Remote.fold` reduces what arrives inside it.
+	*/
+	Message: defineMessageUnion(remoteMessageCases),
+	/**
+	* A bound domain under one wrapper variant of the application's union, the
+	* same shape Foldkit gives a Submodel: `toParentMessage` wraps Remote's
+	* Messages, the fold reduces them, and its `fetch`, `mutate`, and
+	* `subscriptions` yield the wrapper. Spreading `Remote.messages` and
+	* narrowing with `Remote.reduces` remains the shorter path for an
+	* application whose `update` only reduces.
+	*
+	* @example
+	* ```ts
+	* const Message = defineMessageUnion({ GotRemoteMessage: { message: Remote.Message } })
+	* const foldData = Remote.fold(Data, message => Message.GotRemoteMessage({ message }))
+	*
+	* const update = (model: Model, message: Message): Return =>
+	*   Message.match(message, {
+	*     GotRemoteMessage: ({ message }) => foldData(model, message),
+	*   })
+	* const subscriptions = Subscription.make<Model, Message, RemoteClient>()(() =>
+	*   foldData.subscriptions({ page: Surface.at(ProjectPage, …) }),
+	* )
+	* ```
+	*/
+	fold: (domain, toParentMessage) => {
+		const fold = (model, message) => ({ model: domain.reduce(model, message) });
+		return Object.assign(fold, {
+			fetch: (ref) => mapMessage(domain.fetch(ref), toParentMessage),
+			mutate: (...args) => {
+				const started = domain.mutate(...args);
+				return {
+					...started,
+					command: mapMessage(started.command, toParentMessage)
+				};
+			},
+			subscriptions: (active, options) => markAll(Subscription.lift(brandEntries(domain.subscriptions(active, options)))({
+				toChildModel: (model) => model,
+				toParentMessage
+			}))
+		});
+	},
+	/**
 	* A patch of one entity's values, for a mutation's `optimistic` list or an
 	* overlay. Takes a `foldkit-entity` Entity or a Remote descriptor alike, so
 	* the domain you declared once is the one you patch:
@@ -3473,6 +3908,13 @@ const Remote = {
 	*/
 	at: bindRemote,
 	/**
+	* The resume part for this domain, for `foldkit-ssr`'s `SSR.plan({ parts })`:
+	* a server render sends what the plan's active Surfaces read from the store,
+	* each connection with its boundaries and each live cursor with it, and
+	* nothing else. `id` tells two domains in one application apart.
+	*/
+	resume: resumePart,
+	/**
 	* A Projection node that reads a `RemoteData` value out of the store. The id
 	* is supplied by the caller, usually from a Surface's params. The assembled
 	* value is decoded against the Selection, so malformed server data surfaces
@@ -3496,7 +3938,7 @@ const Remote = {
 				const present = memoRead(store, store, `${key}\u0000${stableStringify(relation)}`, () => {
 					if (isTombstone(store, key)) return { _tag: "NotFound" };
 					const assembled = assemble(store, key, relation);
-					if (assembled === void 0) return void 0;
+					if (assembled === void 0) return unavailableFailure(store, key, relation);
 					const decoded = Schema.decodeUnknownResult(selection.schema)(assembled.values);
 					return Result.isFailure(decoded) ? {
 						_tag: "Failed",
@@ -3564,7 +4006,7 @@ const Remote = {
 		if (missing.length === 0) return store;
 		yield* Effect.annotateCurrentSpan("requirementCount", missing.length);
 		const result = yield* (yield* RemoteClient).read({
-			version: 3,
+			version: 4,
 			requests: missing
 		});
 		return writeRead(store, missing, result, at);
@@ -3617,6 +4059,17 @@ const Remote = {
 		});
 	},
 	/**
+	* Forgets everything the server told this Model: values, tombstones,
+	* unavailable fields, connections, live cursors, failures. What is known is
+	* known for a principal, and this is the one boundary for a login, a logout
+	* or a switch of organization: called from `update`, it performs no I/O, and
+	* every active Surface's read and live entries restart, so the screen asks
+	* again as whoever the client now is. A read or stream begun before is
+	* interrupted rather than landing after. A mutation in flight is treated as
+	* applied: its answer writes nothing here.
+	*/
+	forget: (bound, model) => bound.store.set(model, forgetRemote(bound.store.get(model))),
+	/**
 	* Writes a read result into the store, recording each field's applied window.
 	* `requests` are the planned requirements the result answers.
 	*/
@@ -3633,7 +4086,7 @@ const Remote = {
 			query: (request) => client.FoldkitRemoteQuery(request).pipe(Effect.provideContext(context)),
 			mutate: (request) => client.FoldkitRemoteMutate(request).pipe(Effect.provideContext(context)),
 			live: ({ requirements, after }) => client.FoldkitRemoteLive({
-				version: 3,
+				version: 4,
 				requirements,
 				after
 			}).pipe(Stream.map(liveEventOf), Stream.provideContext(context))
@@ -3824,6 +4277,7 @@ const bindDomain = (definition, store) => {
 					roots: current
 				}).pipe(Effect.delay(options.grace ?? 0)))
 			};
+			markAll(entries);
 			return entries;
 		},
 		plan: (model, projection, options) => Remote.plan(bound, model, projection, options),
@@ -3842,7 +4296,7 @@ const bindDomain = (definition, store) => {
 			if (requirements.length === 0) return current;
 			const at = now();
 			const result = yield* client.read({
-				version: 3,
+				version: 4,
 				requests: requirements
 			});
 			return reduce(current, {
@@ -3891,8 +4345,9 @@ const bindDomain = (definition, store) => {
 					let refreshing = connection.stale;
 					const edges = visibleItems(connection, ref.identity, remote.optimistic.overlays, remote.entities);
 					for (const edge of edges) {
-						const assembled = assemble(visible, entityKey(edge.ref.entity, edge.ref.id), relation);
-						if (assembled === void 0) return void 0;
+						const key = entityKey(edge.ref.entity, edge.ref.id);
+						const assembled = assemble(visible, key, relation);
+						if (assembled === void 0) return unavailableFailure(visible, key, relation);
 						const decoded = Schema.decodeUnknownResult(select.schema)(assembled.values);
 						if (Result.isFailure(decoded)) return {
 							_tag: "Failed",
@@ -4048,7 +4503,7 @@ const bindDomain = (definition, store) => {
 				};
 				case "Failed": return {
 					state: state._tag,
-					message: state.error._tag === "DecodeError" ? `What the server sent does not decode against the Selection: ${state.error.message}` : `Its request failed: ${state.error.message}. Nothing retries a failed read on its own; Data.refresh asks again.`,
+					message: state.error._tag === "DecodeError" ? `What the server sent does not decode against the Selection: ${state.error.message}` : state.error._tag === "Unavailable" ? `${state.error.message} Select without it, or Data.refresh asks again.` : `Its request failed: ${state.error.message}. Nothing retries a failed read on its own; Data.refresh asks again.`,
 					...withSurfaces
 				};
 				case "Initial":
@@ -4101,6 +4556,7 @@ const bindDomain = (definition, store) => {
 			};
 		},
 		refresh: (model, target) => Remote.refresh(bound, model, target),
+		forget: (model) => Remote.forget(bound, model),
 		overlay: (model, id, optimistic) => bound.store.set(model, updateRemote(bound.store.get(model), {
 			_tag: "OverlayShown",
 			id,
@@ -4193,6 +4649,6 @@ const pageSize = (window, key) => {
 	return size === void 0 ? {} : { [key]: size };
 };
 //#endregion
-export { ConnectionChange, ConnectionChangeSchema, Entity, IDENTITY_SEPARATOR, Live, LiveChange, LiveEdge, LiveRequirement, MAX_FIELDS_PER_REQUEST, MAX_RELATION_DEPTH, Mutate, Mutation, MutationRequest, MutationResult, NormalizedEntity, PageSize, Query, QueryEdge, QueryRequest, QueryResult, QueryRpc, RELATION_ALIAS, REMOTE_CACHE_VERSION, REMOTE_PROTOCOL_VERSION, Read, ReadBatch, ReadBatchResult, ReadRequest, RelationAnnotation, RelationEntityAnnotation, RelationRequest, Remote, RemoteClient, RemoteConnections, RemoteData, RemoteLiveError, RemoteMutationError, RemotePersistence, RemotePolicy, RemoteProtocolError, RemoteQueryError, RemoteReadError, RemoteRequirements, RemoteRpc, Requirement, Selection, WindowSchema, WireBoundary, addLayer, addOverlay, aliasedField, applyConnectionEvent, applyEntityEvent, assemble, beginMutation, beginOptimistic, belongsEncoded, classifyLive, clearStale, coalesceQueries, coalesceReads, coalescedLayer, connectionChangeOf, connectionIdentity, connectionsOf, cursor, edge, emptyConnection, emptyLiveState, emptyMutationState, emptyOptimistic, emptyRefresh, emptyStore, entityKey, entry, failMutation, failureOf, gc, hasField, hasNext, hasPrevious, initialRemoteModel, inspectEntity, inspectRemote, isFieldFailed, isFieldStale, isGapped, isLoading, isLoadingThrough, isQueryLoading, isRefPage, isRemoteMessage, isTombstone, items, liveEventOf, liveHasNext, liveHasPrevious, markStale, matching, merge, missingFields, mutateRemote, mutationStatus, noFailures, pageSchema, plan, pruneOverlays, reachable, readField, reconcileMutation, refParts, refreshIsInFlight, refreshedAt, refsIn, relationAlias, relationOf, relationShape, remoteDataSchema, remoteError, remoteErrorSchema, remoteMessageCases, remoteMessageSchema, remoteModelSchema, remove, removeLayer, removeOverlay, requirementKey, requirementsOf, retentionRootsSchema, schemaOf, segment, setStale, settleFailure, settleSuccess, shouldWake, stableStringify, targetsOf, terminal, tombstone, unknown, updateRemote, visibleItems, visibleStore, windowKey, withRefreshRequested, writeEntities, writeEntity, writeRead };
+export { ConnectionChange, ConnectionChangeSchema, Entity, IDENTITY_SEPARATOR, Live, LiveChange, LiveEdge, LiveRequirement, MAX_FIELDS_PER_REQUEST, MAX_RELATION_DEPTH, Mutate, Mutation, MutationRequest, MutationResult, NormalizedEntity, PageSize, Query, QueryEdge, QueryRequest, QueryResult, QueryRpc, RELATION_ALIAS, REMOTE_CACHE_VERSION, REMOTE_PROTOCOL_VERSION, Read, ReadBatch, ReadBatchResult, ReadRequest, RelationAnnotation, RelationEntityAnnotation, RelationRequest, Remote, RemoteClient, RemoteConnections, RemoteData, RemoteLiveError, RemoteMutationError, RemotePersistence, RemotePolicy, RemoteProtocolError, RemoteQueryError, RemoteReadError, RemoteRequirements, RemoteRpc, Requirement, Selection, SettledFields, WindowSchema, WireBoundary, addLayer, addOverlay, aliasedField, applyConnectionEvent, applyEntityEvent, assemble, beginMutation, beginOptimistic, belongsEncoded, classifyLive, clearStale, coalesceQueries, coalesceReads, coalescedLayer, connectionChangeOf, connectionIdentity, connectionsOf, cursor, deadlineOf, edge, emptyConnection, emptyLiveState, emptyMutationState, emptyOptimistic, emptyRefresh, emptyStore, entityKey, entry, failMutation, failureOf, forgetRemote, gc, hasField, hasNext, hasPrevious, initialRemoteModel, inspectEntity, inspectRemote, isFieldFailed, isFieldStale, isFieldUnavailable, isGapped, isLoading, isLoadingThrough, isQueryLoading, isRefPage, isRemoteMessage, isTombstone, items, liveEventOf, liveHasNext, liveHasPrevious, markStale, matching, merge, missingFields, mutateRemote, mutationStatus, noFailures, pageSchema, plan, pruneOverlays, reachable, readField, reconcileMutation, refParts, refreshIsInFlight, refreshedAt, refsIn, relationAlias, relationOf, relationShape, remoteDataSchema, remoteError, remoteErrorSchema, remoteMessageCases, remoteMessageSchema, remoteModelSchema, remove, removeLayer, removeOverlay, requirementKey, requirementsOf, retentionRootsSchema, schemaOf, segment, setStale, setUnavailable, settleFailure, settleSuccess, shouldWake, stableStringify, targetsOf, terminal, tombstone, unavailableOf, unknown, updateRemote, visibleItems, visibleStore, windowKey, withRefreshRequested, writeEntities, writeEntity, writeRead };
 
 //# sourceMappingURL=index.mjs.map