foldkit-remote 0.1.0 → 0.3.0

package/dist/index.mjs

@@ -1,7 +1,110 @@
 import { Context, Deferred, Duration, Effect, Layer, Option, Request, RequestResolver, Result, Schema, SchemaGetter, Stream } from "effect";
-import { Requirement } from "foldkit-surface";
+import { Metadata } from "foldkit-surface";
 import { Rpc, RpcGroup } from "effect/unstable/rpc";
 import { KeyValueStore } from "effect/unstable/persistence";
+//#region src/requirement.ts
+/**
+* What a Remote Projection needs from the server: entity slices and query
+* connections. They ride on `Projection.metadata` under Remote's own keys, so
+* Surface composes them without knowing their shape.
+*/
+const windowKey$1 = (window) => JSON.stringify([
+	window.first ?? null,
+	window.last ?? null,
+	window.after ?? null,
+	window.before ?? null
+]);
+/**
+* Merges connection requirements for the same connection and window into one,
+* unioning what they select of each item; the first keeps its other properties.
+*/
+function mergeConnections(connections) {
+	const merged = /* @__PURE__ */ new Map();
+	for (const connection of connections) {
+		const key = `${connection.identity}\u0000${windowKey$1(connection.window)}`;
+		const current = merged.get(key);
+		merged.set(key, current === void 0 ? connection : {
+			...current,
+			select: mergeRelation(current.select, connection.select)
+		});
+	}
+	return [...merged.values()];
+}
+/** Unions two relation slices for the same target: fields, windows, and nested relations. */
+function mergeRelation(current, next) {
+	const fields = [...current.fields];
+	const seen = new Set(fields);
+	for (const field of next.fields) {
+		if (seen.has(field)) continue;
+		seen.add(field);
+		fields.push(field);
+	}
+	const windows = {
+		...current.windows,
+		...next.windows
+	};
+	const relations = mergeRelations(current.relations, next.relations);
+	return {
+		entity: current.entity,
+		fields,
+		...Object.keys(windows).length === 0 ? {} : { windows },
+		...relations === void 0 ? {} : { relations }
+	};
+}
+/** Unions two relation maps field by field; a field in both merges recursively. */
+function mergeRelations(current, next) {
+	if (current === void 0) return next;
+	if (next === void 0) return current;
+	const merged = { ...current };
+	for (const [field, relation] of Object.entries(next)) {
+		const existing = merged[field];
+		merged[field] = existing === void 0 ? relation : mergeRelation(existing, relation);
+	}
+	return merged;
+}
+/** Unions requirements for the same entity + id, dropping duplicate fields. */
+function mergeRequirements(requirements) {
+	const grouped = /* @__PURE__ */ new Map();
+	for (const requirement of requirements) {
+		const key = `${requirement.entity}\u0000${requirement.id}`;
+		const group = grouped.get(key);
+		const live = group?.live === true || requirement.live === true;
+		grouped.set(key, {
+			...mergeRelation(group ?? {
+				entity: requirement.entity,
+				fields: []
+			}, requirement),
+			id: requirement.id,
+			...live ? { live } : {}
+		});
+	}
+	return [...grouped.values()];
+}
+/**
+* Requirement helpers, for the packages that plan and serve requirements.
+* `merge` unions same-entity+id requirements; `mergeRelation` unions two
+* slices of one target (fields, windows, nested relations).
+*/
+const Requirement = {
+	merge: mergeRequirements,
+	mergeRelation,
+	mergeConnections
+};
+/** Remote's entity requirements on a Projection, unioned per entity and id as nodes compose. */
+const RemoteRequirements = Metadata.key("remote", {
+	merge: mergeRequirements,
+	summarize: (requirement) => `${requirement.entity}:${requirement.id}`
+});
+/** Remote's query connections on a Projection, unioned per connection and window. */
+const RemoteConnections = Metadata.key("remote.connection", {
+	merge: mergeConnections,
+	summarize: (connection) => connection.identity.split("\0").join(" ")
+});
+/** The entity requirements a Projection carries. */
+const requirementsOf = (projection) => RemoteRequirements.get(projection.metadata);
+/** The query connections a Projection carries. */
+const connectionsOf = (projection) => RemoteConnections.get(projection.metadata);
+//#endregion
 //#region src/store.ts
 /**
 * The pure entity store: values, per-field presence, staleness, and tombstones.
@@ -80,6 +183,7 @@ const setStale = (store, marks, stale) => {
 		for (const field of fields) if (stale) {
 			if (previous.present.has(field)) staleFields.add(field);
 		} else staleFields.delete(field);
+		if (staleFields.size === previous.stale.size) continue;
 		next ??= { ...store };
 		next[key] = {
 			...previous,
@@ -1463,14 +1567,10 @@ const parseEntry = (value) => {
 	};
 };
 const deserializeStore = (serialized) => Object.fromEntries(Object.entries(serialized.entities).map(([key, entry]) => [key, parseEntry(entry)]));
-/**
-* The snapshot text, or `undefined` when it would exceed `maxBytes`. Only the
-* entity store goes in; pass `model.entities`, never the whole `RemoteModel`.
-*/
-const dehydrate = (store, options = {}) => {
+function dehydrate(store, options = {}) {
 	const text = stableStringify(serializeStore(store, options.scope));
 	return exceeds(text, options.maxBytes) ? void 0 : text;
-};
+}
 /**
 * Whether the UTF-8 size of `text` exceeds `maxBytes`. A character is one to
 * three bytes, so most texts are decided from their length alone; only the
@@ -1641,7 +1741,12 @@ const initialRemoteModel = {
 	optimistic: emptyOptimistic,
 	live: {},
 	mutations: emptyMutationState,
-	gaps: /* @__PURE__ */ new Set()
+	gaps: /* @__PURE__ */ new Set(),
+	loading: /* @__PURE__ */ new Set(),
+	refresh: {
+		requested: 0,
+		started: 0
+	}
 };
 /** The entity store and the mutation ledger are runtime values, not wire shapes. */
 const runtimeSchema = Schema.Unknown;
@@ -1651,7 +1756,12 @@ const remoteModelSchema = () => Schema.Struct({
 	optimistic: runtimeSchema,
 	live: Schema.Record(Schema.String, runtimeSchema),
 	mutations: runtimeSchema,
-	gaps: runtimeSchema
+	gaps: runtimeSchema,
+	loading: runtimeSchema,
+	refresh: Schema.Struct({
+		requested: Schema.Number,
+		started: Schema.Number
+	})
 });
 const retentionRootsSchema = Schema.Struct({
 	requirements: Schema.Array(ReadRequest),
@@ -1675,6 +1785,10 @@ const remoteMessageCases = {
 		error: remoteErrorSchema
 	},
 	RefreshStarted: { requests: Schema.Array(ReadRequest) },
+	ReadStarted: {
+		requests: Schema.Array(ReadRequest),
+		refresh: Schema.optional(Schema.Number)
+	},
 	RetentionChanged: { roots: retentionRootsSchema },
 	Hydrated: {
 		entities: runtimeSchema,
@@ -1722,6 +1836,39 @@ const remoteMessageSchema = Schema.Union(Object.entries(remoteMessageCases).map(
 	...fields
 })));
 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.
+*/
+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 withLoading = (loading, requests) => {
+	const next = new Set(loading);
+	for (const mark of loadingMarks(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);
+	return next;
+};
+/**
+* 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}`));
+};
 const setConnectionStale = (connections, connection, stale) => {
 	const current = connections[connection] ?? emptyConnection;
 	return {
@@ -1749,11 +1896,13 @@ const updateRemote = (model, message) => {
 	switch (message._tag) {
 		case "ReadReceived": return {
 			...model,
-			entities: writeRead(model.entities, message.requests, message.result, message.now)
+			entities: writeRead(model.entities, message.requests, message.result, message.now),
+			loading: withoutLoading(model.loading, message.requests)
 		};
 		case "ReadFailed": return {
 			...model,
-			entities: setStale(model.entities, marksOf(message.requests), false)
+			entities: setStale(model.entities, marksOf(message.requests), false),
+			loading: withoutLoading(model.loading, message.requests)
 		};
 		case "RetentionChanged": return {
 			...model,
@@ -1763,10 +1912,24 @@ const updateRemote = (model, message) => {
 			...model,
 			entities: RemotePersistence.mergeStores(model.entities, message.entities, message.merge)
 		};
-		case "RefreshStarted": return {
-			...model,
-			entities: setStale(model.entities, marksOf(message.requests), true)
-		};
+		case "RefreshStarted": {
+			const entities = setStale(model.entities, 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 "MutationStarted": return {
 			...model,
 			mutations: beginMutation(model.mutations, message.requestId),
@@ -1812,7 +1975,8 @@ const updateRemote = (model, message) => {
 		case "GapCleared": return clearGap(model, message.stream);
 		case "ConnectionMerged": {
 			const current = model.connections[message.connection] ?? emptyConnection;
-			const merged = merge(current, message.page);
+			const replaces = message.refreshes === true && current.stale;
+			const merged = merge(replaces ? emptyConnection : current, message.page);
 			return {
 				...model,
 				connections: {
@@ -1825,10 +1989,12 @@ const updateRemote = (model, message) => {
 				optimistic: pruneOverlays(model.optimistic, message.connection, new Set(message.page.edges.map((edge) => edge.key)), model.mutations.pending)
 			};
 		}
-		case "ConnectionInvalidated": return {
-			...model,
-			connections: setConnectionStale(model.connections, message.connection, true)
-		};
+		case "ConnectionInvalidated":
+			if (model.connections[message.connection]?.stale === true) return model;
+			return {
+				...model,
+				connections: setConnectionStale(model.connections, message.connection, true)
+			};
 		case "QueryFailed": return message.connection in model.connections ? {
 			...model,
 			connections: setConnectionStale(model.connections, message.connection, false)
@@ -2246,7 +2412,7 @@ const bindRemote = (definition, store) => ({
 		owns: store.dependency.length === 0 ? [] : [store.dependency],
 		observes: store.dependency.length === 0 ? [] : [store.dependency],
 		messages: [],
-		requirements: []
+		metadata: []
 	}
 });
 /** The runtime half of `Registered`: a descriptor the domain never declared is an error naming both. */
@@ -2257,7 +2423,10 @@ const nothingAsked = {
 	requirements: [],
 	connections: []
 };
-const askedOf = (projection) => projection === void 0 ? nothingAsked : projection;
+const askedOf = (projection) => projection === void 0 ? nothingAsked : {
+	requirements: requirementsOf(projection),
+	connections: connectionsOf(projection)
+};
 /**
 * Plans what a projection asks against the Model. A connection the Model holds
 * fresh contributes its visible items' selected fields to the entity plan; one
@@ -2333,7 +2502,7 @@ const pageMessage = (connection, result, refreshes = false) => ({
 const rootsOf = (projections, options) => {
 	const connections = /* @__PURE__ */ new Map();
 	for (const identity of (options.connections ?? []).map(connectionIdentity)) connections.set(identity, { identity });
-	for (const { identity, select } of projections.flatMap((projection) => projection.connections)) {
+	for (const { identity, select } of projections.flatMap(connectionsOf)) {
 		const current = connections.get(identity)?.select;
 		connections.set(identity, {
 			identity,
@@ -2341,10 +2510,39 @@ const rootsOf = (projections, options) => {
 		});
 	}
 	return {
-		requirements: Requirement.merge(projections.flatMap((projection) => projection.requirements)),
+		requirements: Requirement.merge(projections.flatMap(requirementsOf)),
 		connections: [...connections.values()].sort((a, b) => a.identity < b.identity ? -1 : 1)
 	};
 };
+/** Reads requirements and reports the Message that settles them. Never fails. */
+const readMessage = (requirements, now) => Effect.gen(function* () {
+	const client = yield* RemoteClient;
+	const at = now();
+	const result = yield* Effect.result(client.read({
+		version: 3,
+		requests: requirements
+	}));
+	return Result.isFailure(result) ? {
+		_tag: "ReadFailed",
+		requests: requirements,
+		error: remoteError(result.failure)
+	} : {
+		_tag: "ReadReceived",
+		requests: requirements,
+		result: result.success,
+		now: at
+	};
+});
+/** Runs a query and reports the page that refreshes its connection, or the failure. Never fails. */
+const queryMessage = (query) => Effect.gen(function* () {
+	const client = yield* RemoteClient;
+	const result = yield* Effect.result(queryRequestOf(query).pipe(Effect.flatMap((request) => client.query(request))));
+	return Result.isFailure(result) ? {
+		_tag: "QueryFailed",
+		connection: query.identity,
+		error: remoteError(result.failure)
+	} : pageMessage(query.identity, result.success, true);
+});
 /** A query the read entry runs, as its dependencies carry it: plain data Foldkit compares. */
 const PlannedQuery = Schema.Struct({
 	identity: Schema.String,
@@ -2362,41 +2560,19 @@ const PlannedQuery = Schema.Struct({
 */
 const observeEntry = (bound, askedOf, toMessage, options) => {
 	const { policy = RemotePolicy.cacheFirst, now = Date.now } = options;
-	const read = (requirements) => Effect.gen(function* () {
-		const client = yield* RemoteClient;
-		const at = now();
-		const result = yield* Effect.result(client.read({
-			version: 3,
-			requests: requirements
-		}));
-		return Result.isFailure(result) ? toMessage({
-			_tag: "ReadFailed",
-			requests: requirements,
-			error: remoteError(result.failure)
-		}) : toMessage({
-			_tag: "ReadReceived",
-			requests: requirements,
-			result: result.success,
-			now: at
-		});
-	});
-	const run = (query) => Effect.gen(function* () {
-		const client = yield* RemoteClient;
-		const result = yield* Effect.result(queryRequestOf(query).pipe(Effect.flatMap((request) => client.query(request))));
-		return Result.isFailure(result) ? toMessage({
-			_tag: "QueryFailed",
-			connection: query.identity,
-			error: remoteError(result.failure)
-		}) : toMessage(pageMessage(query.identity, result.success, true));
-	});
+	const read = (requirements) => Effect.map(readMessage(requirements, now), toMessage);
+	const run = (query) => Effect.map(queryMessage(query), toMessage);
 	return {
 		dependenciesSchema: Schema.Struct({
 			requirements: Schema.Array(ReadRequest),
-			queries: Schema.Array(PlannedQuery)
+			queries: Schema.Array(PlannedQuery),
+			refresh: Schema.Number
 		}),
 		modelToDependencies: (model) => {
-			const planned = planAsked(bound.store.get(model), askedOf(model), RemotePolicy.toPlan(policy, now()));
+			const remote = bound.store.get(model);
+			const planned = planAsked(remote, askedOf(model), RemotePolicy.toPlan(policy, now()));
 			return {
+				refresh: remote.refresh.requested,
 				requirements: planned.requirements,
 				queries: planned.queries.map(({ identity, window, select }) => ({
 					identity,
@@ -2405,10 +2581,14 @@ const observeEntry = (bound, askedOf, toMessage, options) => {
 				}))
 			};
 		},
-		dependenciesToStream: ({ requirements, queries }) => Stream.concat(RemotePolicy.refreshes(policy) && requirements.length > 0 ? Stream.succeed(toMessage({
+		dependenciesToStream: ({ requirements, queries, refresh }) => Stream.concat(requirements.length === 0 ? Stream.empty : Stream.fromIterable([toMessage({
+			_tag: "ReadStarted",
+			requests: requirements,
+			refresh
+		}), ...RemotePolicy.refreshes(policy) ? [toMessage({
 			_tag: "RefreshStarted",
 			requests: requirements
-		})) : Stream.empty, Stream.mergeAll([...requirements.length === 0 ? [] : [Stream.fromEffect(read(requirements))], ...queries.map((query) => Stream.fromEffect(run(query)))], { concurrency: "unbounded" }))
+		})] : []]), Stream.mergeAll([...requirements.length === 0 ? [] : [Stream.fromEffect(read(requirements))], ...queries.map((query) => Stream.fromEffect(run(query)))], { concurrency: "unbounded" }))
 	};
 };
 /** The live entry: subscribes to `requirementsOf(model)` from the Model's resume cursor. */
@@ -2504,18 +2684,17 @@ const Remote = {
 		return (id) => ({
 			Model: remoteDataSchema(selection.schema),
 			dependencies: [],
-			requirements: [{
+			metadata: RemoteRequirements.of({
 				...relation,
 				id
-			}],
-			connections: [],
+			}),
 			read: (root) => {
 				const store = storeOf(bound, root);
 				const key = entityKey(selection.entity, id);
-				return memoRead(store, store, `${key}\u0000${stableStringify(relation)}`, () => {
+				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 { _tag: "Initial" };
+					if (assembled === void 0) return void 0;
 					const decoded = Schema.decodeUnknownResult(selection.schema)(assembled.values);
 					return Result.isFailure(decoded) ? {
 						_tag: "Failed",
@@ -2531,6 +2710,8 @@ const Remote = {
 						value: decoded.success
 					};
 				});
+				if (present !== void 0) return present;
+				return isLoading(bound.store.get(root), selection.entity, id, relation.fields) ? { _tag: "Loading" } : { _tag: "Initial" };
 			}
 		});
 	},
@@ -2539,12 +2720,12 @@ const Remote = {
 	* remote store does not satisfy, under `options` (freshness, force). A
 	* Surface's projection is `surface.projection(params)`.
 	*/
-	plan: (bound, model, projection, options) => planAsked(bound.store.get(model), projection, options ?? {}).requirements,
+	plan: (bound, model, projection, options) => planAsked(bound.store.get(model), askedOf(projection), options ?? {}).requirements,
 	/**
 	* The queries a projection needs run before its connections read: those the
 	* Model does not hold, or holds stale (every one under `force`).
 	*/
-	planQueries: (bound, model, projection, options) => planAsked(bound.store.get(model), projection, options ?? {}).queries.flatMap((query) => query.ref === void 0 ? [] : [query.ref]),
+	planQueries: (bound, model, projection, options) => planAsked(bound.store.get(model), askedOf(projection), options ?? {}).queries.flatMap((query) => query.ref === void 0 ? [] : [query.ref]),
 	/**
 	* The store reads see: the base store under the pending optimistic layers.
 	* One store is shared by every read and plan of a Model whose remote state
@@ -2561,7 +2742,7 @@ const Remote = {
 		const store = storeOf(bound, model);
 		const { policy = RemotePolicy.cacheFirst, now = Date.now } = options;
 		const at = now();
-		const missing = plan(store, projection.requirements, RemotePolicy.toPlan(policy, at));
+		const missing = plan(store, requirementsOf(projection), RemotePolicy.toPlan(policy, at));
 		if (missing.length === 0) return store;
 		yield* Effect.annotateCurrentSpan("requirementCount", missing.length);
 		const result = yield* (yield* RemoteClient).read({
@@ -2571,6 +2752,52 @@ const Remote = {
 		return writeRead(store, missing, result, at);
 	}),
 	/**
+	* Marks what a projection, or a Surface without params, requires as due again.
+	* Called from `update`: every selected field the store holds reads `Refreshing`,
+	* and every loaded query connection is invalidated. Nothing is fetched here.
+	* The read entries `Data.subscriptions` derives refetch it, because a stale
+	* field or connection is planned again under every policy, so a refresh never
+	* sends a request beside the entry already observing the same data.
+	*
+	* A refreshed connection's page replaces its pages, so items the server removed
+	* or reordered follow it; pages loaded past the first are dropped and paged
+	* again with `next`/`previous`. The read entries restart, so a read or query
+	* sent before the refresh is not applied after it.
+	*
+	* The projection must be observed, which it is while it is on screen. Live
+	* subscriptions are left as they are. For data nothing observes (SSR, tests),
+	* use `Remote.prefetch` with `RemotePolicy.networkOnly`. Refreshing what is
+	* already being refreshed returns the same Model.
+	*/
+	refresh: (bound, model, target) => {
+		const projection = "read" in target ? target : target.projection(void 0);
+		const remote = bound.store.get(model);
+		const asked = askedOf(projection);
+		const connections = Requirement.mergeConnections(asked.connections);
+		const items = connections.flatMap((connection) => {
+			const known = remote.connections[connection.identity];
+			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 marked = [...requirements.length === 0 ? [] : [{
+			_tag: "RefreshStarted",
+			requests: requirements
+		}], ...connections.filter((connection) => remote.connections[connection.identity] !== void 0).map((connection) => ({
+			_tag: "ConnectionInvalidated",
+			connection: connection.identity
+		}))].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));
+		if (marked === remote && !inFlight) return model;
+		const refresh = {
+			...marked.refresh,
+			requested: marked.refresh.requested + 1
+		};
+		return bound.store.set(model, {
+			...marked,
+			refresh
+		});
+	},
+	/**
 	* Writes a read result into the store, recording each field's applied window.
 	* `requests` are the planned requirements the result answers.
 	*/
@@ -2648,7 +2875,7 @@ const Remote = {
 	/**
 	* Runs a mutation through `RemoteClient`, decoding its typed Output and
 	* returning the result's normalized patches so the caller can reconcile them
-	* through `Remote.update`'s `MutationSucceeded` (or `Remote.mutateInto`).
+	* through `updateRemote`'s `MutationSucceeded` (or `Remote.mutateInto`).
 	*/
 	mutate: mutateRemote,
 	/**
@@ -2684,14 +2911,14 @@ const Remote = {
 	* emits `RefreshStarted`, so the fields being refetched read as `Refreshing`
 	* while the request is pending.
 	*/
-	observe: (bound, surface, params, toMessage = identityMessage, options = {}) => observeEntry(bound, () => surface.projection(params), toMessage, options),
+	observe: (bound, surface, params, toMessage = identityMessage, options = {}) => observeEntry(bound, () => askedOf(surface.projection(params)), toMessage, options),
 	/**
 	* A Foldkit Subscription entry that consumes the live stream for a Surface's
 	* requirements, emitting a `LiveReceived` per event and a `ReadFailed` when
 	* the stream breaks (including `ResumeUnavailable`). The resume cursor is read
 	* from `RemoteModel.live`, so the application tracks no cursor of its own.
 	*/
-	live: (bound, surface, params, toMessage = identityMessage, options = {}) => liveEntry(bound, () => surface.projection(params).requirements, toMessage, options)
+	live: (bound, surface, params, toMessage = identityMessage, options = {}) => liveEntry(bound, () => requirementsOf(surface.projection(params)), toMessage, options)
 };
 /** The bound domain: the descriptor, the binding, and the operations over them. */
 const bindDomain = (definition, store) => {
@@ -2705,10 +2932,10 @@ const bindDomain = (definition, store) => {
 			const projection = Remote.select(bound, selection)(id);
 			return {
 				...projection,
-				requirements: projection.requirements.map((requirement) => ({
+				metadata: RemoteRequirements.of(...requirementsOf(projection).map((requirement) => ({
 					...requirement,
 					live: true
-				}))
+				})))
 			};
 		},
 		subscriptions: (active, options = {}) => {
@@ -2742,11 +2969,11 @@ const bindDomain = (definition, store) => {
 			const client = yield* RemoteClient;
 			const planOptions = RemotePolicy.toPlan(policy, now());
 			let current = model;
-			for (const query of planAsked(store.get(current), projection, planOptions).queries) {
+			for (const query of planAsked(store.get(current), askedOf(projection), planOptions).queries) {
 				const page = yield* queryRequestOf(query).pipe(Effect.flatMap((request) => client.query(request)));
 				current = reduce(current, pageMessage(query.identity, page, true));
 			}
-			const requirements = planAsked(store.get(current), projection, planOptions).requirements;
+			const requirements = planAsked(store.get(current), askedOf(projection), planOptions).requirements;
 			if (requirements.length === 0) return current;
 			const at = now();
 			const result = yield* client.read({
@@ -2782,8 +3009,7 @@ const bindDomain = (definition, store) => {
 			return {
 				Model: remoteDataSchema(pageSchema(select.schema)),
 				dependencies: [],
-				requirements: [],
-				connections: [requirement],
+				metadata: RemoteConnections.of(requirement),
 				ref,
 				read: (root) => {
 					const remote = store.get(root);
@@ -2845,6 +3071,7 @@ const bindDomain = (definition, store) => {
 				}
 			} : void 0;
 		},
+		refresh: (model, target) => Remote.refresh(bound, model, target),
 		fetch: (ref) => ({
 			name: `Remote.query(${ref.query})`,
 			args: {
@@ -2914,6 +3141,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, RemoteData, RemoteLiveError, RemoteMutationError, RemotePersistence, RemotePolicy, RemoteProtocolError, RemoteQueryError, RemoteReadError, RemoteRpc, Selection, WindowSchema, WireBoundary, addLayer, addOverlay, applyConnectionEvent, applyEntityEvent, assemble, beginMutation, beginOptimistic, classifyLive, clearStale, coalesceQueries, coalesceReads, coalescedLayer, connectionChangeOf, connectionIdentity, cursor, edge, emptyConnection, emptyLiveState, emptyMutationState, emptyOptimistic, emptyStore, entityKey, entry, failMutation, gc, hasField, hasNext, hasPrevious, initialRemoteModel, inspectEntity, inspectRemote, invalidateConnection, isFieldStale, isGapped, 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, 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, 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 };
 
 //# sourceMappingURL=index.mjs.map