foldkit-remote 0.3.0 → 0.4.0

package/dist/index.mjs

@@ -1,4 +1,7 @@
 import { Context, Deferred, Duration, Effect, Layer, Option, Request, RequestResolver, Result, Schema, SchemaGetter, Stream } from "effect";
+import * as Domain from "foldkit-entity";
+import { Entity as Entity$1, SelectionTypeId } from "foldkit-entity";
+import * as Subscription from "foldkit/subscription";
 import { Metadata } from "foldkit-surface";
 import { Rpc, RpcGroup } from "effect/unstable/rpc";
 import { KeyValueStore } from "effect/unstable/persistence";
@@ -266,6 +269,7 @@ const emptyMutationState = {
 	pending: /* @__PURE__ */ new Set(),
 	applied: /* @__PURE__ */ new Set(),
 	failed: /* @__PURE__ */ new Set(),
+	errors: /* @__PURE__ */ new Map(),
 	sequence: 0
 };
 /**
@@ -288,13 +292,26 @@ const beginMutation = (state, requestId) => ({
 	pending: /* @__PURE__ */ new Set([...state.pending, requestId]),
 	sequence: state.sequence + 1
 });
-const failMutation = (state, requestId) => {
+const failMutation = (state, requestId, error) => {
 	const pending = new Set(state.pending);
 	pending.delete(requestId);
+	const failed = remember(state.failed, requestId);
+	const errors = new Map([...state.errors, [requestId, error]]);
+	for (const id of errors.keys()) if (!failed.has(id)) errors.delete(id);
 	return {
 		...state,
 		pending,
-		failed: remember(state.failed, requestId)
+		failed,
+		errors
+	};
+};
+const mutationStatus = (state, requestId) => {
+	if (state.pending.has(requestId)) return { _tag: "Pending" };
+	if (state.applied.has(requestId)) return { _tag: "Applied" };
+	const error = state.errors.get(requestId);
+	return error === void 0 ? { _tag: "Unknown" } : {
+		_tag: "Failed",
+		error
 	};
 };
 /**
@@ -302,8 +319,8 @@ const failMutation = (state, requestId) => {
 * with the same `requestId` (a retry, or a live event describing the same change)
 * does not re-apply the entities, but still clears `pending`.
 */
-const reconcileMutation = (store, state, requestId, entities) => {
-	const next = state.applied.has(requestId) ? store : entities.reduce((current, entity) => writeEntity(current, entityKey(entity.entity, entity.id), entity.values), store);
+const reconcileMutation = (store, state, requestId, entities, deleted = []) => {
+	const next = state.applied.has(requestId) ? store : deleted.reduce((current, gone) => tombstone(current, entityKey(gone.entity, gone.id)), entities.reduce((current, entity) => writeEntity(current, entityKey(entity.entity, entity.id), entity.values), store));
 	const applied = remember(state.applied, requestId);
 	const pending = new Set(state.pending);
 	pending.delete(requestId);
@@ -501,7 +518,12 @@ const MutationResult = Schema.Struct({
 	output: Schema.Unknown,
 	entities: Schema.Array(NormalizedEntity),
 	/** Connection changes the mutation made, applied alongside its entity patches. */
-	connections: Schema.optional(Schema.Array(ConnectionChangeSchema))
+	connections: Schema.optional(Schema.Array(ConnectionChangeSchema)),
+	/** Entities the mutation deleted; the client knows them absent from then on. */
+	deleted: Schema.optional(Schema.Array(Schema.Struct({
+		entity: Schema.String,
+		id: Schema.String
+	})))
 });
 const LiveRequirement = Schema.Struct({
 	version: Schema.Number,
@@ -825,7 +847,8 @@ const mutateRemote = Effect.fn("Remote.mutate")(function* (mutation, input, requ
 	return {
 		output: yield* Schema.decodeUnknownEffect(mutation.Output)(result.output).pipe(Effect.catchTag("SchemaError", (error) => Effect.fail(new RemoteMutationError({ message: error.message })))),
 		entities: result.entities,
-		connections: (result.connections ?? []).map(connectionChangeOf)
+		connections: (result.connections ?? []).map(connectionChangeOf),
+		deleted: result.deleted ?? []
 	};
 });
 //#endregion
@@ -993,6 +1016,322 @@ 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
+* relations, paged through connections), the requirement graph they imply,
+* and their assembly from the normalized store.
+*/
+const pageSchemas = /* @__PURE__ */ new WeakMap();
+const pageSchema = (item) => {
+	const cached = pageSchemas.get(item);
+	if (cached !== void 0) return cached;
+	const built = Schema.Struct({
+		items: Schema.Array(item),
+		hasNext: Schema.Boolean,
+		hasPrevious: Schema.Boolean
+	});
+	pageSchemas.set(item, built);
+	return built;
+};
+/** The requirement a nested selection contributes for its relation's target. */
+const relationOf = (selection) => ({
+	entity: selection.entity,
+	fields: selection.fields,
+	...selection.connections === void 0 ? {} : { windows: selection.connections },
+	...selection.relations === void 0 ? {} : { relations: selection.relations }
+});
+const Selection = {
+	/**
+	* The 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 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);
+	},
+	/**
+	* The fields to read of `entity`. A nested `Selection` on a relation field
+	* reads through the ref (or refs, or page of refs) the field holds into the
+	* target's fields; a scalar field cannot take one.
+	*/
+	make: (entity, selection) => {
+		if (Object.keys(selection).length === 0) throw new Error(`Selection.make: a selection of "${entity.name}" picks at least one field`);
+		const picked = {};
+		const connections = {};
+		const relations = {};
+		for (const key of Object.keys(selection)) {
+			const choice = selection[key];
+			if (choice === true) {
+				picked[key] = entity.fields[key];
+				continue;
+			}
+			const nested = choice;
+			const shape = relationShape(entity.fields[key]);
+			if (shape === void 0) throw new Error(`Selection.make: "${key}" on "${entity.name}" is not a relation field, so it cannot take a nested selection`);
+			if (nested.entity !== shape.entity) throw new Error(`Selection.make: "${key}" on "${entity.name}" refers to "${shape.entity}", not "${nested.entity}"`);
+			const nullable = (codec) => shape.nullable ? Schema.NullOr(codec) : codec;
+			if (nested.window !== void 0) {
+				connections[key] = nested.window;
+				picked[key] = nullable(nested.schema);
+				if (nested.fields.length > 0) relations[key] = relationOf(nested);
+				continue;
+			}
+			const item = nested.schema;
+			picked[key] = nullable(shape.kind === "many" ? Schema.Array(item) : shape.kind === "page" ? pageSchema(item) : item);
+			relations[key] = relationOf(nested);
+		}
+		return {
+			entity: entity.name,
+			fields: Object.keys(selection),
+			schema: Schema.Struct(picked),
+			...Object.keys(connections).length === 0 ? {} : { connections },
+			...Object.keys(relations).length === 0 ? {} : { relations }
+		};
+	},
+	/**
+	* A paginated relation: one page of refs to `entity` with a window, or, with
+	* a nested selection, one page of targets assembled through it.
+	*/
+	connection: ((entity, window, selection) => {
+		if (selection !== void 0 && selection.entity !== entity.name) throw new Error(`Selection.connection: a page of "${entity.name}" cannot select "${selection.entity}"`);
+		return {
+			entity: entity.name,
+			fields: selection?.fields ?? [],
+			schema: selection === void 0 ? Entity.refPage(entity) : pageSchema(selection.schema),
+			window,
+			...selection?.connections === void 0 ? {} : { connections: selection.connections },
+			...selection?.relations === void 0 ? {} : { relations: selection.relations }
+		};
+	})
+};
+/**
+* Reads an entity's selected fields out of the store, following each nested
+* relation into its targets. `undefined` means some field, at any depth, is
+* not present yet. A tombstoned target reads as `null` (or is dropped from a
+* list), so the Selection's codec decides whether that is a failure.
+*/
+const assemble = (store, key, requirement) => {
+	const values = {};
+	let refreshing = false;
+	for (const field of requirement.fields) {
+		const value = readField(store, key, field);
+		if (Option.isNone(value)) return void 0;
+		refreshing ||= isFieldStale(store, key, field);
+		const relation = requirement.relations?.[field];
+		if (relation === void 0) {
+			values[field] = value.value;
+			continue;
+		}
+		const nested = assembleRelation(store, value.value, relation);
+		if (nested === void 0) return void 0;
+		values[field] = nested.values;
+		refreshing ||= nested.refreshing;
+	}
+	return {
+		values,
+		refreshing
+	};
+};
+const assembleTarget = (store, ref, relation) => {
+	const key = entityKey(ref.entity, ref.id);
+	return isTombstone(store, key) ? "absent" : assemble(store, key, relation);
+};
+/** Assembles the targets a relation value refers to, in the value's own shape. */
+const assembleRelation = (store, value, relation) => {
+	if (value === null || value === void 0) return {
+		values: null,
+		refreshing: false
+	};
+	const targets = [];
+	let refreshing = false;
+	for (const ref of targetsOf(value, relation)) {
+		const target = assembleTarget(store, ref, relation);
+		if (target === void 0) return void 0;
+		if (target === "absent") continue;
+		targets.push(target.values);
+		refreshing ||= target.refreshing;
+	}
+	if (typeof value === "string") return {
+		values: targets.length === 0 ? null : targets[0],
+		refreshing
+	};
+	if (isRefPage(value)) return {
+		values: {
+			items: targets,
+			hasNext: value.hasNext,
+			hasPrevious: value.hasPrevious
+		},
+		refreshing
+	};
+	return {
+		values: targets,
+		refreshing
+	};
+};
+//#endregion
+//#region src/entity.ts
+/**
+* Entities: the descriptor an application declares, refs, ref pages, and
+* patches, with the codecs that carry refs on the wire.
+*/
+/**
+* Relations are **references**, never inline target schemas: a ref cannot
+* reconstruct a full entity, and dereferencing is a store concern. Because the
+* target schema is not inlined, recursive relations cannot arise through the
+* schema graph.
+*/
+const refCodec = (entity) => Schema.Struct({
+	entity: Schema.String,
+	id: Schema.String
+}).pipe(Schema.encodeTo(Schema.String, {
+	decode: SchemaGetter.transform(refParts),
+	encode: SchemaGetter.transform((ref) => entityKey(ref.entity, ref.id))
+})).annotate({
+	[RelationAnnotation]: "one",
+	[RelationEntityAnnotation]: entity
+});
+const refPageCodec = (entity) => Schema.Struct({
+	refs: Schema.Array(refCodec(entity)),
+	hasNext: Schema.Boolean,
+	hasPrevious: Schema.Boolean
+}).annotate({
+	[RelationAnnotation]: "page",
+	[RelationEntityAnnotation]: entity
+});
+const descriptors = /* @__PURE__ */ new WeakMap();
+const relationField = (relation) => {
+	const ref = refCodec(relation.target().name);
+	return relation.cardinality === "many" ? Schema.Array(ref) : relation.optional ? Schema.NullOr(ref) : ref;
+};
+const Entity = {
+	/**
+	* The Remote descriptor of a `foldkit-entity` Entity. Relations declared with
+	* `Entity.relate` become ref fields, so the store, the planner, and the server
+	* treat it as they treat an `Entity.make` descriptor.
+	*/
+	from: (entity) => {
+		const cached = descriptors.get(entity);
+		if (cached !== void 0) return cached;
+		const members = entity.members;
+		if (members.id?._tag !== "Field") throw new Error(`Entity.from: "${entity.name}" needs an "id" field for Remote to key it by`);
+		const fields = {};
+		for (const [key, member] of Object.entries(members)) fields[key] = member._tag === "Relation" ? relationField(member) : member.schema;
+		const descriptor = Entity.make(entity.name, Schema.Struct(fields));
+		descriptors.set(entity, descriptor);
+		return descriptor;
+	},
+	make: (name, schema) => {
+		const descriptor = {
+			name,
+			schema,
+			fields: schema.fields,
+			ref: (id) => ({
+				entity: name,
+				id: String(id)
+			}),
+			select: (selection) => Selection.make(descriptor, selection),
+			patch: (id, values) => ({
+				entity: name,
+				id: String(id),
+				values
+			})
+		};
+		return descriptor;
+	},
+	/** A relation to a known entity, decoded as a reference. */
+	ref: (entity) => refCodec(entity.name),
+	/** A relation by name, for recursive or forward references. */
+	refTo: (name) => refCodec(name),
+	/**
+	* The wire key a relation field carries (`"Entity:id"`). Adapters that read a
+	* foreign key emit this so the ref codec can decode it on the client.
+	*/
+	refKey: (ref) => entityKey(ref.entity, ref.id),
+	/** Splits a ref key back into its entity and id. */
+	refParts,
+	/** A relation value of one authoritative page of refs. */
+	refPage: (entity) => refPageCodec(entity.name),
+	/**
+	* A normalized patch for an entity, typed against its fields' wire shape:
+	* write a relation as its ref key (`Entity.refKey`), as the server does.
+	*/
+	patch: (ref, patch) => ({
+		entity: ref.entity,
+		id: ref.id,
+		values: patch
+	})
+};
+//#endregion
 //#region src/inspect.ts
 const inspectEntry = (key, entry) => ({
 	key,
@@ -1138,8 +1477,8 @@ const release = (optimistic, requestId) => removeOverlay(removeLayer(optimistic,
 * a later layer re-wins on rebase. Confirmed connection changes are recorded
 * once per request, as overlays the request no longer owns.
 */
-const settleSuccess = (base, optimistic, state, requestId, entities, connections = []) => {
-	const reconciled = reconcileMutation(base, state, requestId, entities);
+const settleSuccess = (base, optimistic, state, requestId, entities, connections = [], deleted = []) => {
+	const reconciled = reconcileMutation(base, state, requestId, entities, deleted);
 	return {
 		store: reconciled.store,
 		state: reconciled.state,
@@ -1294,101 +1633,33 @@ const applyConnectionEvent = (state, optimistic, event, policy = {}) => {
 				position: "remove"
 			}),
 			outcome
-		};
-		case "ConnectionInvalidate": return {
-			state: invalidateConnection(advance(state, event.cursor), event.connection),
-			optimistic,
-			outcome
-		};
-	}
-};
-const isStale = (state, connection) => state.stale.has(connection);
-/**
-* Clears a connection's stale mark once a fresh page has been adopted. An
-* invalidating event only records that a refetch is due; whoever merges the
-* refetched page calls this so `isStale` stops reporting.
-*/
-const refreshConnection = (state, connection) => {
-	if (!state.stale.has(connection)) return state;
-	const stale = new Set(state.stale);
-	stale.delete(connection);
-	return {
-		...state,
-		stale
-	};
-};
-/** `hasPrevious` accounting for edges recorded outside the loaded boundary. */
-const liveHasPrevious = (connection, state, connectionId) => hasPrevious(connection) || (state.boundary[connectionId]?.before ?? 0) > 0;
-/** `hasNext` accounting for edges recorded outside the loaded boundary. */
-const liveHasNext = (connection, state, connectionId) => hasNext(connection) || (state.boundary[connectionId]?.after ?? 0) > 0;
-//#endregion
-//#region src/relation.ts
-/** Marks the codec `Entity.ref`/`Entity.refPage` produce, so a Selection can tell the field's shape. */
-const RelationAnnotation = "foldkitRemoteRelation";
-/** The target entity's name on the same codec, so a nested selection of another entity is refused. */
-const RelationEntityAnnotation = "foldkitRemoteRelationEntity";
-/** Splits a ref key (`"Entity:id"`, the store key too) back into its parts. */
-const refParts = (encoded) => {
-	const separator = encoded.indexOf(":");
-	return separator === -1 ? {
-		entity: encoded,
-		id: ""
-	} : {
-		entity: encoded.slice(0, separator),
-		id: encoded.slice(separator + 1)
-	};
-};
-/**
-* The refs a relation value carries, in order. Anything that is not a ref key,
-* an array of them, or a page of them contributes nothing.
-*/
-const refsIn = (value) => {
-	if (typeof value === "string") return [refParts(value)];
-	if (Array.isArray(value)) return value.filter((item) => typeof item === "string").map(refParts);
-	if (value !== null && typeof value === "object") {
-		const refs = value.refs;
-		if (Array.isArray(refs)) return refs.filter((item) => typeof item === "string").map(refParts);
-	}
-	return [];
-};
-/** The refs in a relation value that name the relation's target entity, and no other. */
-const targetsOf = (value, relation) => refsIn(value).filter((ref) => ref.entity === relation.entity);
-const isRefPage = (value) => {
-	if (value === null || typeof value !== "object") return false;
-	const page = value;
-	return Array.isArray(page.refs) && page.refs.every((ref) => typeof ref === "string") && typeof page.hasNext === "boolean" && typeof page.hasPrevious === "boolean";
-};
-/**
-* The relation shape an entity field schema declares: a ref (`one`), a nullable
-* ref, an array of refs (`many`), or a page of refs (`page`). `undefined` for a
-* scalar field, which cannot take a nested selection.
-*/
-const relationShape = (schema) => shapeOf(schema.ast, false);
-const shapeOf = (ast, nullable) => {
-	const annotated = ast.annotations?.[RelationAnnotation];
-	if (annotated === "one" || annotated === "page") return {
-		kind: annotated,
-		nullable,
-		entity: String(ast.annotations?.[RelationEntityAnnotation])
-	};
-	if (ast._tag === "Arrays") {
-		const item = ast.rest?.[0];
-		const inner = item === void 0 ? void 0 : shapeOf(item, false);
-		return inner?.kind === "one" ? {
-			kind: "many",
-			nullable,
-			entity: inner.entity
-		} : void 0;
-	}
-	if (ast._tag === "Union") {
-		const members = ast.types ?? [];
-		const optional = members.some((member) => member._tag === "Null" || member._tag === "Undefined");
-		for (const member of members) {
-			const shape = shapeOf(member, optional);
-			if (shape !== void 0) return shape;
-		}
+		};
+		case "ConnectionInvalidate": return {
+			state: invalidateConnection(advance(state, event.cursor), event.connection),
+			optimistic,
+			outcome
+		};
 	}
 };
+const isStale = (state, connection) => state.stale.has(connection);
+/**
+* Clears a connection's stale mark once a fresh page has been adopted. An
+* invalidating event only records that a refetch is due; whoever merges the
+* refetched page calls this so `isStale` stops reporting.
+*/
+const refreshConnection = (state, connection) => {
+	if (!state.stale.has(connection)) return state;
+	const stale = new Set(state.stale);
+	stale.delete(connection);
+	return {
+		...state,
+		stale
+	};
+};
+/** `hasPrevious` accounting for edges recorded outside the loaded boundary. */
+const liveHasPrevious = (connection, state, connectionId) => hasPrevious(connection) || (state.boundary[connectionId]?.before ?? 0) > 0;
+/** `hasNext` accounting for edges recorded outside the loaded boundary. */
+const liveHasNext = (connection, state, connectionId) => hasNext(connection) || (state.boundary[connectionId]?.after ?? 0) > 0;
 //#endregion
 //#region src/plan.ts
 /**
@@ -1801,7 +2072,11 @@ const remoteMessageCases = {
 	MutationSucceeded: {
 		requestId: Schema.String,
 		entities: Schema.Array(NormalizedEntity),
-		connections: Schema.optional(Schema.Array(Schema.Unknown))
+		connections: Schema.optional(Schema.Array(Schema.Unknown)),
+		deleted: Schema.optional(Schema.Array(Schema.Struct({
+			entity: Schema.String,
+			id: Schema.String
+		})))
 	},
 	MutationFailed: {
 		requestId: Schema.String,
@@ -1936,7 +2211,7 @@ const updateRemote = (model, message) => {
 			optimistic: beginOptimistic(model.optimistic, message.requestId, message.optimistic ?? [])
 		};
 		case "MutationSucceeded": {
-			const settled = settleSuccess(model.entities, model.optimistic, model.mutations, message.requestId, message.entities, message.connections ?? []);
+			const settled = settleSuccess(model.entities, model.optimistic, model.mutations, message.requestId, message.entities, message.connections ?? [], message.deleted ?? []);
 			return {
 				...model,
 				entities: settled.store,
@@ -1946,7 +2221,7 @@ const updateRemote = (model, message) => {
 		}
 		case "MutationFailed": return {
 			...model,
-			mutations: failMutation(model.mutations, message.requestId),
+			mutations: failMutation(model.mutations, message.requestId, message.error),
 			optimistic: settleFailure(model.optimistic, message.requestId)
 		};
 		case "LiveReceived": {
@@ -2082,7 +2357,12 @@ const writeRead = (store, requests, result, now = 0) => {
 			windows: entry?.windows
 		});
 	}
-	return writeEntities(store, writes, now);
+	let answered = store;
+	for (const request of requests) {
+		const key = entityKey(request.entity, request.id);
+		if (!returned.has(key)) answered = tombstone(answered, key);
+	}
+	return writeEntities(answered, writes, now);
 };
 //#endregion
 //#region src/policy.ts
@@ -2115,224 +2395,6 @@ const RemotePolicy = {
 	refreshes: (policy) => policy._tag !== "CacheFirst"
 };
 //#endregion
-//#region src/entity.ts
-/**
-* Entities: the descriptor an application declares, refs, ref pages, and
-* patches, with the codecs that carry refs on the wire.
-*/
-/**
-* Relations are **references**, never inline target schemas: a ref cannot
-* reconstruct a full entity, and dereferencing is a store concern. Because the
-* target schema is not inlined, recursive relations cannot arise through the
-* schema graph.
-*/
-const refCodec = (entity) => Schema.Struct({
-	entity: Schema.String,
-	id: Schema.String
-}).pipe(Schema.encodeTo(Schema.String, {
-	decode: SchemaGetter.transform(refParts),
-	encode: SchemaGetter.transform((ref) => entityKey(ref.entity, ref.id))
-})).annotate({
-	[RelationAnnotation]: "one",
-	[RelationEntityAnnotation]: entity
-});
-const refPageCodec = (entity) => Schema.Struct({
-	refs: Schema.Array(refCodec(entity)),
-	hasNext: Schema.Boolean,
-	hasPrevious: Schema.Boolean
-}).annotate({
-	[RelationAnnotation]: "page",
-	[RelationEntityAnnotation]: entity
-});
-const Entity = {
-	make: (name, schema) => {
-		const descriptor = {
-			name,
-			schema,
-			fields: schema.fields,
-			ref: (id) => ({
-				entity: name,
-				id: String(id)
-			}),
-			select: (selection) => Selection.make(descriptor, selection),
-			patch: (id, values) => ({
-				entity: name,
-				id: String(id),
-				values
-			})
-		};
-		return descriptor;
-	},
-	/** A relation to a known entity, decoded as a reference. */
-	ref: (entity) => refCodec(entity.name),
-	/** A relation by name, for recursive or forward references. */
-	refTo: (name) => refCodec(name),
-	/**
-	* The wire key a relation field carries (`"Entity:id"`). Adapters that read a
-	* foreign key emit this so the ref codec can decode it on the client.
-	*/
-	refKey: (ref) => entityKey(ref.entity, ref.id),
-	/** Splits a ref key back into its entity and id. */
-	refParts,
-	/** A relation value of one authoritative page of refs. */
-	refPage: (entity) => refPageCodec(entity.name),
-	/**
-	* A normalized patch for an entity, typed against its fields' wire shape:
-	* write a relation as its ref key (`Entity.refKey`), as the server does.
-	*/
-	patch: (ref, patch) => ({
-		entity: ref.entity,
-		id: ref.id,
-		values: patch
-	})
-};
-//#endregion
-//#region src/selection.ts
-/**
-* Selections: the fields a Surface picks of an entity (nested through
-* relations, paged through connections), the requirement graph they imply,
-* and their assembly from the normalized store.
-*/
-const pageSchemas = /* @__PURE__ */ new WeakMap();
-const pageSchema = (item) => {
-	const cached = pageSchemas.get(item);
-	if (cached !== void 0) return cached;
-	const built = Schema.Struct({
-		items: Schema.Array(item),
-		hasNext: Schema.Boolean,
-		hasPrevious: Schema.Boolean
-	});
-	pageSchemas.set(item, built);
-	return built;
-};
-/** The requirement a nested selection contributes for its relation's target. */
-const relationOf = (selection) => ({
-	entity: selection.entity,
-	fields: selection.fields,
-	...selection.connections === void 0 ? {} : { windows: selection.connections },
-	...selection.relations === void 0 ? {} : { relations: selection.relations }
-});
-const Selection = {
-	/**
-	* The fields to read of `entity`. A nested `Selection` on a relation field
-	* reads through the ref (or refs, or page of refs) the field holds into the
-	* target's fields; a scalar field cannot take one.
-	*/
-	make: (entity, selection) => {
-		if (Object.keys(selection).length === 0) throw new Error(`Selection.make: a selection of "${entity.name}" picks at least one field`);
-		const picked = {};
-		const connections = {};
-		const relations = {};
-		for (const key of Object.keys(selection)) {
-			const choice = selection[key];
-			if (choice === true) {
-				picked[key] = entity.fields[key];
-				continue;
-			}
-			const nested = choice;
-			const shape = relationShape(entity.fields[key]);
-			if (shape === void 0) throw new Error(`Selection.make: "${key}" on "${entity.name}" is not a relation field, so it cannot take a nested selection`);
-			if (nested.entity !== shape.entity) throw new Error(`Selection.make: "${key}" on "${entity.name}" refers to "${shape.entity}", not "${nested.entity}"`);
-			const nullable = (codec) => shape.nullable ? Schema.NullOr(codec) : codec;
-			if (nested.window !== void 0) {
-				connections[key] = nested.window;
-				picked[key] = nullable(nested.schema);
-				if (nested.fields.length > 0) relations[key] = relationOf(nested);
-				continue;
-			}
-			const item = nested.schema;
-			picked[key] = nullable(shape.kind === "many" ? Schema.Array(item) : shape.kind === "page" ? pageSchema(item) : item);
-			relations[key] = relationOf(nested);
-		}
-		return {
-			entity: entity.name,
-			fields: Object.keys(selection),
-			schema: Schema.Struct(picked),
-			...Object.keys(connections).length === 0 ? {} : { connections },
-			...Object.keys(relations).length === 0 ? {} : { relations }
-		};
-	},
-	/**
-	* A paginated relation: one page of refs to `entity` with a window, or, with
-	* a nested selection, one page of targets assembled through it.
-	*/
-	connection: ((entity, window, selection) => {
-		if (selection !== void 0 && selection.entity !== entity.name) throw new Error(`Selection.connection: a page of "${entity.name}" cannot select "${selection.entity}"`);
-		return {
-			entity: entity.name,
-			fields: selection?.fields ?? [],
-			schema: selection === void 0 ? Entity.refPage(entity) : pageSchema(selection.schema),
-			window,
-			...selection?.connections === void 0 ? {} : { connections: selection.connections },
-			...selection?.relations === void 0 ? {} : { relations: selection.relations }
-		};
-	})
-};
-/**
-* Reads an entity's selected fields out of the store, following each nested
-* relation into its targets. `undefined` means some field, at any depth, is
-* not present yet. A tombstoned target reads as `null` (or is dropped from a
-* list), so the Selection's codec decides whether that is a failure.
-*/
-const assemble = (store, key, requirement) => {
-	const values = {};
-	let refreshing = false;
-	for (const field of requirement.fields) {
-		const value = readField(store, key, field);
-		if (Option.isNone(value)) return void 0;
-		refreshing ||= isFieldStale(store, key, field);
-		const relation = requirement.relations?.[field];
-		if (relation === void 0) {
-			values[field] = value.value;
-			continue;
-		}
-		const nested = assembleRelation(store, value.value, relation);
-		if (nested === void 0) return void 0;
-		values[field] = nested.values;
-		refreshing ||= nested.refreshing;
-	}
-	return {
-		values,
-		refreshing
-	};
-};
-const assembleTarget = (store, ref, relation) => {
-	const key = entityKey(ref.entity, ref.id);
-	return isTombstone(store, key) ? "absent" : assemble(store, key, relation);
-};
-/** Assembles the targets a relation value refers to, in the value's own shape. */
-const assembleRelation = (store, value, relation) => {
-	if (value === null || value === void 0) return {
-		values: null,
-		refreshing: false
-	};
-	const targets = [];
-	let refreshing = false;
-	for (const ref of targetsOf(value, relation)) {
-		const target = assembleTarget(store, ref, relation);
-		if (target === void 0) return void 0;
-		if (target === "absent") continue;
-		targets.push(target.values);
-		refreshing ||= target.refreshing;
-	}
-	if (typeof value === "string") return {
-		values: targets.length === 0 ? null : targets[0],
-		refreshing
-	};
-	if (isRefPage(value)) return {
-		values: {
-			items: targets,
-			hasNext: value.hasNext,
-			hasPrevious: value.hasPrevious
-		},
-		refreshing
-	};
-	return {
-		values: targets,
-		refreshing
-	};
-};
-//#endregion
 //#region src/index.ts
 /**
 * `foldkit-remote` — normalized application-facing server state.
@@ -2341,6 +2403,8 @@ const assembleRelation = (store, value, relation) => {
 * live classification, optimistic layers) performs no I/O. The `Remote.*`
 * helpers that read or mutate go through the `RemoteClient` Effect service.
 */
+const descriptorOf = (entity) => Entity$1.is(entity) ? Entity.from(entity) : entity;
+const selectionOf = (selection) => SelectionTypeId in selection ? Selection.from(selection) : selection;
 /**
 * The store a read or plan sees: the base with every pending optimistic layer
 * applied, so a request's patches show until it settles and a temporary id is
@@ -2386,21 +2450,24 @@ const identityMessage = (message) => message;
 /** A stable key for a live subscription's requirement set. */
 const liveStreamKey = (requirements) => requirements.map((requirement) => `${entityKey(requirement.entity, requirement.id)}:${[...requirement.fields].sort().join(",")}`).sort().join("|");
 /** Declares a Remote domain: its entities, queries, and mutations, plus the submodel. */
-const defineRemote = (config) => ({
-	entities: config.entities,
-	queries: config.queries ?? [],
-	mutations: config.mutations ?? [],
-	Model: remoteModelSchema(),
-	initial: initialRemoteModel,
-	Message: remoteMessageSchema,
-	update: updateRemote,
-	rpc: RemoteRpc,
-	registry: {
-		entities: new Map(config.entities.map((entity) => [entity.name, entity])),
-		queries: new Map((config.queries ?? []).map((query) => [query.name, query])),
-		mutations: new Map((config.mutations ?? []).map((mutation) => [mutation.name, mutation]))
-	}
-});
+const defineRemote = (config) => {
+	const entities = config.entities.map(descriptorOf);
+	return {
+		entities,
+		queries: config.queries ?? [],
+		mutations: config.mutations ?? [],
+		Model: remoteModelSchema(),
+		initial: initialRemoteModel,
+		Message: remoteMessageSchema,
+		update: updateRemote,
+		rpc: RemoteRpc,
+		registry: {
+			entities: new Map(entities.map((entity) => [entity.name, entity])),
+			queries: new Map((config.queries ?? []).map((query) => [query.name, query])),
+			mutations: new Map((config.mutations ?? []).map((mutation) => [mutation.name, mutation]))
+		}
+	};
+};
 /** Binds a Remote domain to its store's location in the application Model. */
 const bindRemote = (definition, store) => ({
 	definition,
@@ -2678,7 +2745,8 @@ const Remote = {
 	* as `Failed` instead of being asserted into `Value`. A present value with a
 	* stale field reads as `Refreshing`: an observer is refetching it.
 	*/
-	select: (bound, selection) => {
+	select: (bound, given) => {
+		const selection = selectionOf(given);
 		assertRegistered(bound, "Entity", bound.definition.registry.entities, selection.entity);
 		const relation = relationOf(selection);
 		return (id) => ({
@@ -2896,7 +2964,8 @@ const Remote = {
 			_tag: "MutationSucceeded",
 			requestId,
 			entities: outcome.entities,
-			connections: outcome.connections
+			connections: outcome.connections,
+			deleted: outcome.deleted
 		});
 		return {
 			output: outcome.output,
@@ -2920,11 +2989,12 @@ const Remote = {
 	*/
 	live: (bound, surface, params, toMessage = identityMessage, options = {}) => liveEntry(bound, () => requirementsOf(surface.projection(params)), toMessage, options)
 };
+const brandEntries = (entries) => Subscription.make()(() => entries);
 /** The bound domain: the descriptor, the binding, and the operations over them. */
 const bindDomain = (definition, store) => {
 	const bound = bindRemote(definition, store);
 	const reduce = (model, message) => store.set(model, updateRemote(store.get(model), message));
-	return {
+	const domain = {
 		...definition,
 		...bound,
 		get: (selection, id) => Remote.select(bound, selection)(id),
@@ -2989,7 +3059,8 @@ const bindDomain = (definition, store) => {
 		}),
 		query: (query, input, options) => {
 			assertRegistered(bound, "Query", definition.registry.queries, query.name);
-			const { select, ...window } = options;
+			const { select: given, ...window } = options;
+			const select = selectionOf(given);
 			for (const [side, size] of [["first", window.first], ["last", window.last]]) if (size !== void 0 && !(Number.isInteger(size) && size >= 0)) throw new Error(`Remote: query "${query.name}" asks for ${side}: ${String(size)}; a page size is a non-negative integer`);
 			const listed = query.Result.entity;
 			if (listed === void 0) throw new Error(`Remote: query "${query.name}" is not a connection over an entity, so it has no page to select`);
@@ -3118,15 +3189,25 @@ const bindDomain = (definition, store) => {
 							_tag: "MutationSucceeded",
 							requestId,
 							entities: outcome.entities,
-							connections: outcome.connections
+							connections: outcome.connections,
+							deleted: outcome.deleted
 						})
 					}))
 				}
 			};
 		},
+		mutation: (model, requestId) => mutationStatus(store.get(model).mutations, requestId),
 		reduce,
-		inspect: (model) => inspectRemote(store.get(model))
+		inspect: (model) => inspectRemote(store.get(model)),
+		wiring: (active, options) => ({
+			key: `remote:${bound.contract.name}`,
+			handles: Object.keys(remoteMessageCases),
+			route: (model, message) => isRemoteMessage(message) ? Option.some({ model: reduce(model, message) }) : Option.none(),
+			subscriptions: brandEntries(domain.subscriptions(active, options)),
+			contract: bound.contract
+		})
 	};
+	return domain;
 };
 /** The window keys of a `QueryOptions`, and only those, without the undefined ones. */
 const pickWindow = (window) => ({
@@ -3141,6 +3222,6 @@ const pageSize = (window, key) => {
 	return size === void 0 ? {} : { [key]: size };
 };
 //#endregion
-export { ConnectionChange, ConnectionChangeSchema, Entity, Live, LiveChange, LiveEdge, LiveRequirement, MAX_FIELDS_PER_REQUEST, MAX_RELATION_DEPTH, Mutate, Mutation, MutationRequest, MutationResult, NormalizedEntity, PageSize, Query, QueryEdge, QueryRequest, QueryResult, QueryRpc, REMOTE_CACHE_VERSION, REMOTE_PROTOCOL_VERSION, Read, ReadBatch, ReadBatchResult, ReadRequest, RelationAnnotation, RelationEntityAnnotation, RelationRequest, Remote, RemoteClient, RemoteConnections, RemoteData, RemoteLiveError, RemoteMutationError, RemotePersistence, RemotePolicy, RemoteProtocolError, RemoteQueryError, RemoteReadError, RemoteRequirements, RemoteRpc, Requirement, Selection, WindowSchema, WireBoundary, addLayer, addOverlay, applyConnectionEvent, applyEntityEvent, assemble, beginMutation, beginOptimistic, classifyLive, clearStale, coalesceQueries, coalesceReads, coalescedLayer, connectionChangeOf, connectionIdentity, connectionsOf, cursor, edge, emptyConnection, emptyLiveState, emptyMutationState, emptyOptimistic, emptyStore, entityKey, entry, failMutation, gc, hasField, hasNext, hasPrevious, initialRemoteModel, inspectEntity, inspectRemote, invalidateConnection, isFieldStale, isGapped, isLoading, isRefPage, isRemoteMessage, isStale, isTombstone, items, liveEventOf, liveHasNext, liveHasPrevious, markStale, merge, missingFields, mutateRemote, pageSchema, plan, pruneOverlays, reachable, readField, reconcileMutation, refParts, refreshConnection, refsIn, relationOf, relationShape, remoteDataSchema, remoteError, remoteErrorSchema, remoteMessageCases, remoteMessageSchema, remoteModelSchema, remove, removeLayer, removeOverlay, requirementKey, requirementsOf, retentionRootsSchema, schemaOf, segment, setStale, settleFailure, settleSuccess, shouldWake, stableStringify, targetsOf, terminal, tombstone, unknown, updateRemote, visibleItems, visibleStore, windowKey, writeEntities, writeEntity, writeRead };
+export { ConnectionChange, ConnectionChangeSchema, Entity, Live, LiveChange, LiveEdge, LiveRequirement, MAX_FIELDS_PER_REQUEST, MAX_RELATION_DEPTH, Mutate, Mutation, MutationRequest, MutationResult, NormalizedEntity, PageSize, Query, QueryEdge, QueryRequest, QueryResult, QueryRpc, 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 };
 
 //# sourceMappingURL=index.mjs.map