foldkit-remote 0.2.0 → 0.4.0

package/dist/index.d.mts

@@ -1,9 +1,64 @@
 import { Context, Duration, Effect, Layer, Option, Schema, Stream } from "effect";
-import { ActiveSurface, ConnectionRequirement, Contract, Invalid, ModelRef, Projection, RelationRequirement, RelationRequirement as RelationRequirement$1, Requirement, Requirement as Requirement$1, Surface } from "foldkit-surface";
+import * as Domain from "foldkit-entity";
+import { EntryWithoutKeepAlive } from "foldkit/subscription";
+import { ActiveSurface, Contract, Invalid, Metadata, ModelRef, Projection, Surface, Wiring } from "foldkit-surface";
 import { Rpc, RpcGroup } from "effect/unstable/rpc";
 import { KeyValueStore } from "effect/unstable/persistence";
 import { Command } from "foldkit/command";
-import { EntryWithoutKeepAlive } from "foldkit/subscription";
+//#region ../metadata/dist/index.d.mts
+//#region src/index.d.ts
+/** Marks a `Metadata` value. Its entries are private to this module. */
+declare const MetadataTypeId: unique symbol;
+type MetadataTypeId = typeof MetadataTypeId;
+/**
+ * Declarative facts an interpreter attaches to a node it does not own, such as
+ * the server data a Remote selection needs. The carrier holds and combines
+ * them without knowing what they mean; a package reads only the key it owns.
+ *
+ * Opaque: only a key's `of` and `Metadata.combine` make one, so entries cannot
+ * be forged past a key's type or `merge`, and they are frozen.
+ */
+interface Metadata$1 {
+  readonly [MetadataTypeId]: MetadataTypeId;
+}
+/**
+ * An interpreter's typed slot in `Metadata`. Lookup is by the key object, never
+ * its `name`, so two packages cannot collide by choosing the same string.
+ */
+interface MetadataKey<A> {
+  /** For tooling output only. */
+  readonly name: string;
+  /** Normalizes the entries gathered from combined values, e.g. unioning duplicates. */
+  readonly merge: (values: ReadonlyArray<A>) => ReadonlyArray<A>;
+  /** One line per entry for tooling output. */
+  readonly summarize: (value: A) => string;
+  readonly of: (...values: ReadonlyArray<A>) => Metadata$1;
+  readonly get: (metadata: Metadata$1) => ReadonlyArray<A>;
+}
+/** One key's entries as serializable text, named by the key. */
+interface MetadataSummary {
+  readonly name: string;
+  readonly entries: readonly string[];
+}
+declare const Metadata$1: {
+  /**
+   * Declares an interpreter's slot. Call once per package, at module level:
+   * entries are found by the key object, so two copies of a package (a
+   * duplicated install, a reloaded module) do not see each other's entries.
+   */
+  key: <A>(name: string, options: {
+    readonly merge: (values: ReadonlyArray<A>) => ReadonlyArray<A>;
+    readonly summarize: (value: A) => string;
+  }) => MetadataKey<A>;
+  empty: Metadata$1;
+  /** True only for a value this module made; a copy or a hand-built brand is not one. */
+  is: (value: unknown) => value is Metadata$1;
+  /** Gathers every part's entries and runs each key's `merge` over its group. */
+  combine: (parts: ReadonlyArray<Metadata$1>) => Metadata$1;
+  summarize: (metadata: Metadata$1) => readonly MetadataSummary[];
+};
+//#endregion
+//#endregion
 //#region src/connection.d.ts
 export interface EdgeRef {
   readonly entity: string;
@@ -49,6 +104,51 @@ export declare const hasNext: (connection: Connection) => boolean;
 /** A connection with more than one segment has an explicit unknown gap. */
 export declare const isGapped: (connection: Connection) => boolean;
 //#endregion
+//#region src/remoteData.d.ts
+export interface RemoteError {
+  readonly _tag: string;
+  readonly message: string;
+}
+export type RemoteData<A> = {
+  readonly _tag: 'Initial';
+} | {
+  readonly _tag: 'Loading';
+} | {
+  readonly _tag: 'Ready';
+  readonly value: A;
+} | {
+  readonly _tag: 'Refreshing';
+  readonly value: A;
+} | {
+  readonly _tag: 'Failed';
+  readonly error: RemoteError;
+  readonly previous?: A;
+} | {
+  readonly _tag: 'NotFound';
+};
+export declare const remoteErrorSchema: Schema.Struct<{
+  readonly _tag: Schema.String;
+  readonly message: Schema.String;
+}>;
+export declare const remoteDataSchema: <A>(value: Schema.Schema<A>) => Schema.Codec<RemoteData<A>, unknown>;
+export declare const RemoteData: {
+  /**
+   * The `RemoteData` schema for a value schema. Exposed so a `RemoteData` can
+   * be embedded in a hand-written Model schema, not only through `Remote.select`.
+   */
+  schema: <A>(value: Schema.Schema<A>) => Schema.Schema<RemoteData<A>>;
+  /** Exhaustive: omitting a state is a compile error. */
+  match: <A, R>(data: RemoteData<A>, cases: {
+    readonly Initial: () => R;
+    readonly Loading: () => R;
+    readonly Ready: (value: A) => R;
+    readonly Refreshing: (value: A) => R;
+    readonly Failed: (error: RemoteError, previous: Option.Option<A>) => R;
+    readonly NotFound: () => R;
+  }) => R;
+  map: <A, B>(data: RemoteData<A>, f: (value: A) => B) => RemoteData<B>;
+};
+//#endregion
 //#region src/store.d.ts
 export type EntityKey = string;
 export interface EntityEntry {
@@ -128,6 +228,8 @@ export interface MutationState {
   readonly pending: ReadonlySet<string>;
   readonly applied: ReadonlySet<string>;
   readonly failed: ReadonlySet<string>;
+  /** Why each request in `failed` failed, kept exactly as long as `failed` keeps its id. */
+  readonly errors: ReadonlyMap<string, RemoteError>;
   /**
    * How many mutations this model has started. A bound domain takes its next
    * request id from here, so `update` stays pure and the id exists before the
@@ -137,7 +239,21 @@ export interface MutationState {
 }
 export declare const emptyMutationState: MutationState;
 export declare const beginMutation: (state: MutationState, requestId: string) => MutationState;
-export declare const failMutation: (state: MutationState, requestId: string) => MutationState;
+export declare const failMutation: (state: MutationState, requestId: string, error: RemoteError) => MutationState;
+/** What Remote knows of one mutation request, by the id `mutate` returned. */
+export type MutationStatus =
+/** Never started here, or settled so long ago its id has left the window. */
+{
+  readonly _tag: 'Unknown';
+} | {
+  readonly _tag: 'Pending';
+} | {
+  readonly _tag: 'Applied';
+} | {
+  readonly _tag: 'Failed';
+  readonly error: RemoteError;
+};
+export declare const mutationStatus: (state: MutationState, requestId: string) => MutationStatus;
 export interface Reconciled {
   readonly store: EntityStore;
   readonly state: MutationState;
@@ -147,7 +263,10 @@ export interface Reconciled {
  * with the same `requestId` (a retry, or a live event describing the same change)
  * does not re-apply the entities, but still clears `pending`.
  */
-export declare const reconcileMutation: (store: EntityStore, state: MutationState, requestId: string, entities: ReadonlyArray<NormalizedPatch>) => Reconciled;
+export declare const reconcileMutation: (store: EntityStore, state: MutationState, requestId: string, entities: ReadonlyArray<NormalizedPatch>, deleted?: ReadonlyArray<{
+  readonly entity: string;
+  readonly id: string;
+}>) => Reconciled;
 /** A mutation an application declares: its name and input/output codecs. */
 export interface MutationDescriptor<Name extends string, Input, Output> {
   readonly name: Name;
@@ -171,6 +290,130 @@ export declare const Mutation: {
   }) => MutationDescriptor<Name, TypeOf<Input>, TypeOf<Output>>;
 };
 //#endregion
+//#region src/query.d.ts
+export type LiveInsertion = 'visible' | 'boundary' | 'invalidate' | 'ignore';
+export interface LivePolicy {
+  readonly prepend?: LiveInsertion;
+  readonly append?: LiveInsertion;
+}
+export interface ConnectionSpec<Entity extends string = string> {
+  readonly entity: Entity;
+  readonly edgeKey?: Schema.Schema<unknown>;
+  readonly live?: LivePolicy;
+}
+export interface QueryWindow {
+  readonly first?: number | undefined;
+  readonly last?: number | undefined;
+  readonly after?: Cursor | undefined;
+  readonly before?: Cursor | undefined;
+}
+export interface QueryRef<Name extends string, Input> {
+  readonly query: Name;
+  readonly input: Input;
+  /** The input codec, so a `QueryRef` can encode itself without its descriptor. */
+  readonly Input: Schema.Codec<Input>;
+  readonly window: QueryWindow;
+  /** Connection identity: descriptor + canonical input, excluding the window. */
+  readonly identity: string;
+}
+export interface QueryDescriptor<Name extends string, Input, Result> {
+  readonly name: Name;
+  readonly Input: Schema.Codec<Input>;
+  readonly Result: Result;
+  readonly ref: (input: Input) => QueryRef<Name, Input>;
+}
+/** Stable stringify: object keys sorted, undefined-valued keys dropped, so equal inputs encode equally. */
+export declare const stableStringify: (value: unknown) => string;
+/**
+ * `Result: Project` (or anything with the entity's `name`, as `Query.connection`
+ * takes) means a connection over it; a `ConnectionSpec` names its `entity`
+ * instead and is the result as given.
+ */
+export type ResultOf<Result> = Result extends {
+  readonly name: infer Entity extends string;
+} ? ConnectionSpec<Entity> : Result;
+export declare const Query: {
+  /** Declares the entity and options a query's result is a connection over. */
+  connection: <Entity extends string>(entity: {
+    readonly name: Entity;
+  }, options?: {
+    readonly edgeKey?: Schema.Schema<unknown>;
+    readonly live?: LivePolicy;
+  }) => ConnectionSpec<Entity>;
+  /**
+   * Declares a query. `Input` is a codec or the fields of the `Schema.Struct` it
+   * would be; `Result` is a `Query.connection(...)`, or the entity the result is
+   * a connection over.
+   */
+  make: <const Name extends string, Input extends SchemaOrFields, Result>(name: Name, config: {
+    readonly Input: Input;
+    readonly Result: Result;
+  }) => QueryDescriptor<Name, TypeOf<Input>, ResultOf<Result>>;
+  first: (count: number) => <R extends QueryRef<string, unknown>>(ref: R) => R;
+  last: (count: number) => <R extends QueryRef<string, unknown>>(ref: R) => R;
+  after: (cursor: Cursor) => <R extends QueryRef<string, unknown>>(ref: R) => R;
+  before: (cursor: Cursor) => <R extends QueryRef<string, unknown>>(ref: R) => R;
+};
+//#endregion
+//#region src/requirement.d.ts
+/**
+ * The slice required of an entity. `windows` carries a pagination window per
+ * relation field, and `relations` the slice required of each relation's
+ * target, so one requirement describes a whole selection graph.
+ */
+export interface RelationRequirement {
+  readonly entity: string;
+  readonly fields: readonly string[];
+  readonly windows?: Readonly<Record<string, QueryWindow>> | undefined;
+  readonly relations?: Readonly<Record<string, RelationRequirement>> | undefined;
+}
+export interface Requirement extends RelationRequirement {
+  readonly id: string;
+  /** The projection also subscribes to changes of this entity (`Data.live`). */
+  readonly live?: boolean | undefined;
+}
+/**
+ * A query connection a projection reads: the page it first asks for and the
+ * slice it selects of each item. `identity` is the connection's (query plus
+ * canonical input, excluding the window).
+ */
+export interface ConnectionRequirement {
+  readonly identity: string;
+  readonly window: QueryWindow;
+  readonly select: RelationRequirement;
+}
+/**
+ * Merges connection requirements for the same connection and window into one,
+ * unioning what they select of each item; the first keeps its other properties.
+ */
+declare function mergeConnections(connections: readonly ConnectionRequirement[]): readonly ConnectionRequirement[];
+/** Unions two relation slices for the same target: fields, windows, and nested relations. */
+declare function mergeRelation(current: RelationRequirement, next: RelationRequirement): RelationRequirement;
+/** Unions requirements for the same entity + id, dropping duplicate fields. */
+declare function mergeRequirements(requirements: readonly Requirement[]): readonly Requirement[];
+/**
+ * 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).
+ */
+export declare const Requirement: {
+  merge: typeof mergeRequirements;
+  mergeRelation: typeof mergeRelation;
+  mergeConnections: typeof mergeConnections;
+};
+/** Remote's entity requirements on a Projection, unioned per entity and id as nodes compose. */
+export declare const RemoteRequirements: MetadataKey<Requirement>;
+/** Remote's query connections on a Projection, unioned per connection and window. */
+export declare const RemoteConnections: MetadataKey<ConnectionRequirement>;
+/** The entity requirements a Projection carries. */
+export declare const requirementsOf: (projection: {
+  readonly metadata: Metadata;
+}) => ReadonlyArray<Requirement>;
+/** The query connections a Projection carries. */
+export declare const connectionsOf: (projection: {
+  readonly metadata: Metadata;
+}) => ReadonlyArray<ConnectionRequirement>;
+//#endregion
 //#region src/optimistic.d.ts
 export interface EntityLayer {
   readonly id: string;
@@ -257,7 +500,10 @@ export declare const pruneOverlays: (optimistic: OptimisticState, connection: st
  * a later layer re-wins on rebase. Confirmed connection changes are recorded
  * once per request, as overlays the request no longer owns.
  */
-export declare const settleSuccess: (base: EntityStore, optimistic: OptimisticState, state: MutationState, requestId: string, entities: ReadonlyArray<NormalizedPatch>, connections?: ReadonlyArray<ConnectionChange>) => {
+export declare const settleSuccess: (base: EntityStore, optimistic: OptimisticState, state: MutationState, requestId: string, entities: ReadonlyArray<NormalizedPatch>, connections?: ReadonlyArray<ConnectionChange>, deleted?: ReadonlyArray<{
+  readonly entity: string;
+  readonly id: string;
+}>) => {
   readonly store: EntityStore;
   readonly state: MutationState;
   readonly optimistic: OptimisticState;
@@ -275,71 +521,6 @@ export declare const settleFailure: (optimistic: OptimisticState, requestId: str
  */
 export declare const visibleItems: (connection: Connection, connectionId: string, overlays: ReadonlyArray<ConnectionOverlay>, store?: EntityStore) => ReadonlyArray<Edge>;
 //#endregion
-//#region src/query.d.ts
-export type LiveInsertion = 'visible' | 'boundary' | 'invalidate' | 'ignore';
-export interface LivePolicy {
-  readonly prepend?: LiveInsertion;
-  readonly append?: LiveInsertion;
-}
-export interface ConnectionSpec<Entity extends string = string> {
-  readonly entity: Entity;
-  readonly edgeKey?: Schema.Schema<unknown>;
-  readonly live?: LivePolicy;
-}
-export interface QueryWindow {
-  readonly first?: number | undefined;
-  readonly last?: number | undefined;
-  readonly after?: Cursor | undefined;
-  readonly before?: Cursor | undefined;
-}
-export interface QueryRef<Name extends string, Input> {
-  readonly query: Name;
-  readonly input: Input;
-  /** The input codec, so a `QueryRef` can encode itself without its descriptor. */
-  readonly Input: Schema.Codec<Input>;
-  readonly window: QueryWindow;
-  /** Connection identity: descriptor + canonical input, excluding the window. */
-  readonly identity: string;
-}
-export interface QueryDescriptor<Name extends string, Input, Result> {
-  readonly name: Name;
-  readonly Input: Schema.Codec<Input>;
-  readonly Result: Result;
-  readonly ref: (input: Input) => QueryRef<Name, Input>;
-}
-/** Stable stringify: object keys sorted, undefined-valued keys dropped, so equal inputs encode equally. */
-export declare const stableStringify: (value: unknown) => string;
-/**
- * `Result: Project` (or anything with the entity's `name`, as `Query.connection`
- * takes) means a connection over it; a `ConnectionSpec` names its `entity`
- * instead and is the result as given.
- */
-export type ResultOf<Result> = Result extends {
-  readonly name: infer Entity extends string;
-} ? ConnectionSpec<Entity> : Result;
-export declare const Query: {
-  /** Declares the entity and options a query's result is a connection over. */
-  connection: <Entity extends string>(entity: {
-    readonly name: Entity;
-  }, options?: {
-    readonly edgeKey?: Schema.Schema<unknown>;
-    readonly live?: LivePolicy;
-  }) => ConnectionSpec<Entity>;
-  /**
-   * Declares a query. `Input` is a codec or the fields of the `Schema.Struct` it
-   * would be; `Result` is a `Query.connection(...)`, or the entity the result is
-   * a connection over.
-   */
-  make: <const Name extends string, Input extends SchemaOrFields, Result>(name: Name, config: {
-    readonly Input: Input;
-    readonly Result: Result;
-  }) => QueryDescriptor<Name, TypeOf<Input>, ResultOf<Result>>;
-  first: (count: number) => <R extends QueryRef<string, unknown>>(ref: R) => R;
-  last: (count: number) => <R extends QueryRef<string, unknown>>(ref: R) => R;
-  after: (cursor: Cursor) => <R extends QueryRef<string, unknown>>(ref: R) => R;
-  before: (cursor: Cursor) => <R extends QueryRef<string, unknown>>(ref: R) => R;
-};
-//#endregion
 //#region src/live.d.ts
 export type LiveCursor = number;
 export type LiveEvent = {
@@ -427,10 +608,10 @@ export declare const liveHasNext: (connection: Connection, state: LiveState, con
 /** A connection to keep: its identity, and what a page of it selects of each item, if a projection reads it. */
 export interface ConnectionRoot {
   readonly identity: string;
-  readonly select?: RelationRequirement$1 | undefined;
+  readonly select?: RelationRequirement | undefined;
 }
 export interface RetentionRoots {
-  readonly requirements: ReadonlyArray<Requirement$1>;
+  readonly requirements: ReadonlyArray<Requirement>;
   /** Connections (`QueryRef.identity`) to keep, with their edges' targets and what `select` reaches through them. */
   readonly connections: ReadonlyArray<ConnectionRoot>;
 }
@@ -468,9 +649,17 @@ export interface SnapshotOptions {
 }
 /** How a snapshot meets a store that already has entries. */
 export type MergePolicy = 'replace' | 'preserve-existing';
+/**
+ * The snapshot text, or `undefined` when it would exceed `maxBytes`. Only the
+ * entity store goes in; pass `model.entities`, never the whole `RemoteModel`.
+ */
+declare function dehydrate(store: EntityStore, options?: SnapshotOptions & {
+  readonly maxBytes?: undefined;
+}): string;
+declare function dehydrate(store: EntityStore, options?: SnapshotOptions): string | undefined;
 export declare const RemotePersistence: {
   /** The snapshot text, or `undefined` when it would exceed `maxBytes`. */
-  dehydrate: (store: EntityStore, options?: SnapshotOptions) => string | undefined;
+  dehydrate: typeof dehydrate;
   /** The store a snapshot text holds, or `undefined` when it is refused. */
   hydrate: (raw: string | undefined | null, options?: SnapshotOptions) => EntityStore | undefined;
   /** A snapshot brought into a store by policy. */
@@ -531,11 +720,11 @@ export declare const WindowSchema: Schema.Struct<{
 export declare const MAX_FIELDS_PER_REQUEST = 256;
 /** A selection may not nest relations deeper than this; the wire refuses more. */
 export declare const MAX_RELATION_DEPTH = 8;
-export declare const RelationRequest: Schema.Codec<RelationRequirement$1, RelationRequirement$1, never, never>;
-export declare const ReadRequest: Schema.Codec<Requirement$1, Requirement$1>;
+export declare const RelationRequest: Schema.Codec<RelationRequirement, RelationRequirement, never, never>;
+export declare const ReadRequest: Schema.Codec<Requirement, Requirement>;
 export declare const ReadBatch: Schema.Struct<{
   readonly version: Schema.Number;
-  readonly requests: Schema.$Array<Schema.Codec<Requirement$1, Requirement$1, never, never>>;
+  readonly requests: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
 }>;
 export declare const NormalizedEntity: Schema.Struct<{
   readonly entity: Schema.String;
@@ -605,10 +794,15 @@ export declare const MutationResult: Schema.Struct<{
       readonly key: Schema.String;
     }>;
   }>]>>>;
+  /** Entities the mutation deleted; the client knows them absent from then on. */
+  readonly deleted: Schema.optional<Schema.$Array<Schema.Struct<{
+    readonly entity: Schema.String;
+    readonly id: Schema.String;
+  }>>>;
 }>;
 export declare const LiveRequirement: Schema.Struct<{
   readonly version: Schema.Number;
-  readonly requirements: Schema.$Array<Schema.Codec<Requirement$1, Requirement$1, never, never>>;
+  readonly requirements: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
   /** Resume cursor; events at or before it are duplicates. */
   readonly after: Schema.Number;
 }>;
@@ -654,7 +848,7 @@ export declare const LiveChange: Schema.Union<readonly [Schema.Struct<{
 }>]>;
 export declare const Read: Rpc.Rpc<"FoldkitRemoteRead", Schema.Struct<{
   readonly version: Schema.Number;
-  readonly requests: Schema.$Array<Schema.Codec<Requirement$1, Requirement$1, never, never>>;
+  readonly requests: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
 }>, Schema.Struct<{
   readonly entities: Schema.$Array<Schema.Struct<{
     readonly entity: Schema.String;
@@ -693,10 +887,15 @@ export declare const Mutate: Rpc.Rpc<"FoldkitRemoteMutate", Schema.Struct<{
       readonly key: Schema.String;
     }>;
   }>]>>>;
+  /** Entities the mutation deleted; the client knows them absent from then on. */
+  readonly deleted: Schema.optional<Schema.$Array<Schema.Struct<{
+    readonly entity: Schema.String;
+    readonly id: Schema.String;
+  }>>>;
 }>, typeof RemoteMutationError, never, never>;
 export declare const Live: Rpc.Rpc<"FoldkitRemoteLive", Schema.Struct<{
   readonly version: Schema.Number;
-  readonly requirements: Schema.$Array<Schema.Codec<Requirement$1, Requirement$1, never, never>>;
+  readonly requirements: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
   /** Resume cursor; events at or before it are duplicates. */
   readonly after: Schema.Number;
 }>, import("effect/unstable/rpc/RpcSchema").Stream<Schema.Union<readonly [Schema.Struct<{
@@ -819,7 +1018,7 @@ export declare const QueryRpc: Rpc.Rpc<"FoldkitRemoteQuery", Schema.Struct<{
 }>, typeof RemoteQueryError, never, never>;
 export declare const RemoteRpc: RpcGroup.RpcGroup<Rpc.Rpc<"FoldkitRemoteRead", Schema.Struct<{
   readonly version: Schema.Number;
-  readonly requests: Schema.$Array<Schema.Codec<Requirement$1, Requirement$1, never, never>>;
+  readonly requests: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
 }>, Schema.Struct<{
   readonly entities: Schema.$Array<Schema.Struct<{
     readonly entity: Schema.String;
@@ -857,9 +1056,14 @@ export declare const RemoteRpc: RpcGroup.RpcGroup<Rpc.Rpc<"FoldkitRemoteRead", S
       readonly key: Schema.String;
     }>;
   }>]>>>;
+  /** Entities the mutation deleted; the client knows them absent from then on. */
+  readonly deleted: Schema.optional<Schema.$Array<Schema.Struct<{
+    readonly entity: Schema.String;
+    readonly id: Schema.String;
+  }>>>;
 }>, typeof RemoteMutationError, never, never> | Rpc.Rpc<"FoldkitRemoteLive", Schema.Struct<{
   readonly version: Schema.Number;
-  readonly requirements: Schema.$Array<Schema.Codec<Requirement$1, Requirement$1, never, never>>;
+  readonly requirements: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
   /** Resume cursor; events at or before it are duplicates. */
   readonly after: Schema.Number;
 }>, import("effect/unstable/rpc/RpcSchema").Stream<Schema.Union<readonly [Schema.Struct<{
@@ -930,51 +1134,6 @@ export declare const RemoteRpc: RpcGroup.RpcGroup<Rpc.Rpc<"FoldkitRemoteRead", S
   }>]>;
 }>, typeof RemoteQueryError, never, never>>;
 //#endregion
-//#region src/remoteData.d.ts
-export interface RemoteError {
-  readonly _tag: string;
-  readonly message: string;
-}
-export type RemoteData<A> = {
-  readonly _tag: 'Initial';
-} | {
-  readonly _tag: 'Loading';
-} | {
-  readonly _tag: 'Ready';
-  readonly value: A;
-} | {
-  readonly _tag: 'Refreshing';
-  readonly value: A;
-} | {
-  readonly _tag: 'Failed';
-  readonly error: RemoteError;
-  readonly previous?: A;
-} | {
-  readonly _tag: 'NotFound';
-};
-export declare const remoteErrorSchema: Schema.Struct<{
-  readonly _tag: Schema.String;
-  readonly message: Schema.String;
-}>;
-export declare const remoteDataSchema: <A>(value: Schema.Schema<A>) => Schema.Schema<RemoteData<A>>;
-export declare const RemoteData: {
-  /**
-   * The `RemoteData` schema for a value schema. Exposed so a `RemoteData` can
-   * be embedded in a hand-written Model schema, not only through `Remote.select`.
-   */
-  schema: <A>(value: Schema.Schema<A>) => Schema.Schema<RemoteData<A>>;
-  /** Exhaustive: omitting a state is a compile error. */
-  match: <A, R>(data: RemoteData<A>, cases: {
-    readonly Initial: () => R;
-    readonly Loading: () => R;
-    readonly Ready: (value: A) => R;
-    readonly Refreshing: (value: A) => R;
-    readonly Failed: (error: RemoteError, previous: Option.Option<A>) => R;
-    readonly NotFound: () => R;
-  }) => R;
-  map: <A, B>(data: RemoteData<A>, f: (value: A) => B) => RemoteData<B>;
-};
-//#endregion
 //#region src/model.d.ts
 /**
  * The normalized cache as a Foldkit Submodel. `Remote.define` returns a schema
@@ -1000,29 +1159,40 @@ export interface RemoteModel {
    * fetching this".
    */
   readonly loading: ReadonlySet<string>;
+  /**
+   * `Remote.refresh` generations. The read entries restart when `requested`
+   * moves, so a read sent before a refresh cannot land after it; `started` is
+   * the latest generation a read began under.
+   */
+  readonly refresh: {
+    readonly requested: number;
+    readonly started: number;
+  };
 }
 export declare const initialRemoteModel: RemoteModel;
-export declare const remoteModelSchema: () => Schema.Schema<RemoteModel>;
+export declare const remoteModelSchema: () => Schema.Codec<RemoteModel, unknown>;
 /** The submodel's Messages; each reduces to `RemoteModel` through `updateRemote`. */
 export type RemoteMessage = {
   readonly _tag: 'ReadReceived';
-  readonly requests: readonly Requirement$1[];
+  readonly requests: readonly Requirement[];
   readonly result: Schema.Schema.Type<typeof ReadBatchResult>;
   readonly now: number;
 } | {
   readonly _tag: 'ReadFailed';
-  readonly requests: readonly Requirement$1[];
+  readonly requests: readonly Requirement[];
   readonly error: RemoteError;
 } |
 /** A refetch of present fields began; they read as `Refreshing` until it lands. */
 {
   readonly _tag: 'RefreshStarted';
-  readonly requests: readonly Requirement$1[];
+  readonly requests: readonly Requirement[];
 } |
 /** A read began; the fields it asks for that the store lacks read as `Loading`. */
 {
   readonly _tag: 'ReadStarted';
-  readonly requests: readonly Requirement$1[];
+  readonly requests: readonly Requirement[];
+  /** The refresh generation the read was planned under. */
+  readonly refresh?: number | undefined;
 } |
 /** The active Surfaces' roots changed; everything they do not reach is collected. */
 {
@@ -1046,6 +1216,11 @@ export type RemoteMessage = {
   readonly entities: readonly NormalizedPatch[];
   /** Connection changes the server confirmed; they replace the request's own. */
   readonly connections?: ReadonlyArray<ConnectionChange> | undefined;
+  /** Entities the mutation deleted: tombstoned, which hides them from every connection. */
+  readonly deleted?: ReadonlyArray<{
+    readonly entity: string;
+    readonly id: string;
+  }> | undefined;
 } | {
   readonly _tag: 'MutationFailed';
   readonly requestId: string;
@@ -1079,10 +1254,10 @@ export type RemoteMessage = {
   readonly error: RemoteError;
 };
 export declare const retentionRootsSchema: Schema.Struct<{
-  readonly requirements: Schema.$Array<Schema.Codec<Requirement$1, Requirement$1, never, never>>;
+  readonly requirements: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
   readonly connections: Schema.$Array<Schema.Struct<{
     readonly identity: Schema.String;
-    readonly select: Schema.optional<Schema.Codec<import("foldkit-surface").RelationRequirement, import("foldkit-surface").RelationRequirement, never, never>>;
+    readonly select: Schema.optional<Schema.Codec<RelationRequirement, RelationRequirement, never, never>>;
   }>>;
 }>;
 /**
@@ -1091,7 +1266,7 @@ export declare const retentionRootsSchema: Schema.Struct<{
  */
 export declare const remoteMessageCases: {
   ReadReceived: {
-    requests: Schema.$Array<Schema.Codec<Requirement$1, Requirement$1, never, never>>;
+    requests: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
     result: Schema.Struct<{
       readonly entities: Schema.$Array<Schema.Struct<{
         readonly entity: Schema.String;
@@ -1102,24 +1277,25 @@ export declare const remoteMessageCases: {
     now: Schema.Number;
   };
   ReadFailed: {
-    requests: Schema.$Array<Schema.Codec<Requirement$1, Requirement$1, never, never>>;
+    requests: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
     error: Schema.Struct<{
       readonly _tag: Schema.String;
       readonly message: Schema.String;
     }>;
   };
   RefreshStarted: {
-    requests: Schema.$Array<Schema.Codec<Requirement$1, Requirement$1, never, never>>;
+    requests: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
   };
   ReadStarted: {
-    requests: Schema.$Array<Schema.Codec<Requirement$1, Requirement$1, never, never>>;
+    requests: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
+    refresh: Schema.optional<Schema.Number>;
   };
   RetentionChanged: {
     roots: Schema.Struct<{
-      readonly requirements: Schema.$Array<Schema.Codec<Requirement$1, Requirement$1, never, never>>;
+      readonly requirements: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
       readonly connections: Schema.$Array<Schema.Struct<{
         readonly identity: Schema.String;
-        readonly select: Schema.optional<Schema.Codec<import("foldkit-surface").RelationRequirement, import("foldkit-surface").RelationRequirement, never, never>>;
+        readonly select: Schema.optional<Schema.Codec<RelationRequirement, RelationRequirement, never, never>>;
       }>>;
     }>;
   };
@@ -1139,6 +1315,10 @@ export declare const remoteMessageCases: {
       readonly values: Schema.$Record<Schema.String, Schema.Unknown>;
     }>>;
     connections: Schema.optional<Schema.$Array<Schema.Unknown>>;
+    deleted: Schema.optional<Schema.$Array<Schema.Struct<{
+      readonly entity: Schema.String;
+      readonly id: Schema.String;
+    }>>>;
   };
   MutationFailed: {
     requestId: Schema.String;
@@ -1213,7 +1393,7 @@ export declare const updateRemote: (model: RemoteModel, message: RemoteMessage)
  * accumulates rather than replaces. Every read path should use this rather than
  * reducing `writeEntity` by hand.
  */
-export declare const writeRead: (store: EntityStore, requests: ReadonlyArray<Requirement$1>, result: Schema.Schema.Type<typeof ReadBatchResult>, now?: number) => EntityStore;
+export declare const writeRead: (store: EntityStore, requests: ReadonlyArray<Requirement>, result: Schema.Schema.Type<typeof ReadBatchResult>, now?: number) => EntityStore;
 //#endregion
 //#region src/coalesce.d.ts
 type Batch = Schema.Schema.Type<typeof ReadBatch>;
@@ -1231,7 +1411,7 @@ export interface CoalesceOptions {
   readonly window?: Duration.Input | undefined;
 }
 /** A stable key for a requirement, so an equal requirement in flight is joined. */
-export declare const requirementKey: (requirement: Requirement$1) => string;
+export declare const requirementKey: (requirement: Requirement) => string;
 /**
  * Wraps a raw query so that an identical query in flight (same query, input,
  * and window) is joined rather than run again; distinct queries run
@@ -1251,7 +1431,7 @@ declare const RemoteClient_base: Context.ServiceClass<RemoteClient, "foldkit-rem
   readonly query: (request: Schema.Schema.Type<typeof QueryRequest>) => Effect.Effect<Schema.Schema.Type<typeof QueryResult>, RemoteQueryError>;
   readonly mutate: (request: Schema.Schema.Type<typeof MutationRequest>) => Effect.Effect<Schema.Schema.Type<typeof MutationResult>, RemoteMutationError>;
   readonly live: (request: {
-    readonly requirements: ReadonlyArray<Requirement$1>;
+    readonly requirements: ReadonlyArray<Requirement>;
     readonly after: LiveCursor;
   }) => Stream.Stream<LiveEvent, RemoteLiveError | RemoteProtocolError>;
 }>;
@@ -1295,6 +1475,10 @@ export declare const mutateRemote: <Name extends string, Input, Output>(mutation
     };
   }[];
   connections: ConnectionChange[];
+  deleted: readonly {
+    readonly entity: string;
+    readonly id: string;
+  }[];
 }, RemoteMutationError, RemoteClient>;
 //#endregion
 //#region src/relation.d.ts
@@ -1326,7 +1510,7 @@ export declare const refParts: (encoded: string) => RefParts;
  */
 export declare const refsIn: (value: unknown) => ReadonlyArray<RefParts>;
 /** The refs in a relation value that name the relation's target entity, and no other. */
-export declare const targetsOf: (value: unknown, relation: RelationRequirement$1) => ReadonlyArray<RefParts>;
+export declare const targetsOf: (value: unknown, relation: RelationRequirement) => ReadonlyArray<RefParts>;
 export declare const isRefPage: (value: unknown) => value is RefPageValue;
 /**
  * The relation shape an entity field schema declares: a ref (`one`), a nullable
@@ -1355,7 +1539,7 @@ export interface Selection<Value, Name extends string = string, Shape extends 'e
   /** Pagination windows for nested relation fields, keyed by field name. */
   readonly connections?: Readonly<Record<string, QueryWindow>> | undefined;
   /** The slice required of each nested relation's target, keyed by field name. */
-  readonly relations?: Readonly<Record<string, RelationRequirement$1>> | undefined;
+  readonly relations?: Readonly<Record<string, RelationRequirement>> | undefined;
   /** Present when this selection is itself a paginated relation. */
   readonly window?: QueryWindow | undefined;
   /** Phantom: see `Shape`. */
@@ -1377,8 +1561,13 @@ type NestedValue<Field, Sel> = Sel extends Selection<infer V, string, 'connectio
 export type SelectionValue<F extends Schema.Struct.Fields, Sel> = Simplify<{ readonly [K in keyof Sel & keyof F]: Sel[K] extends true ? Schema.Schema.Type<F[K]> : NestedValue<Schema.Schema.Type<F[K]>, Sel[K]>; }>;
 export declare const pageSchema: (item: AnySchema) => AnySchema;
 /** The requirement a nested selection contributes for its relation's target. */
-export declare const relationOf: (selection: Selection<unknown>) => RelationRequirement$1;
+export declare const relationOf: (selection: Selection<unknown>) => RelationRequirement;
 export declare 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: <Name extends string, S extends Schema.Constraint>(selection: Domain.Selection<Name, unknown, S>) => Selection<S["Type"], Name, "entity">;
   /**
    * 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
@@ -1404,7 +1593,7 @@ interface Assembled {
  * 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.
  */
-export declare const assemble: (store: EntityStore, key: string, requirement: RelationRequirement$1) => Assembled | undefined;
+export declare const assemble: (store: EntityStore, key: string, requirement: RelationRequirement) => Assembled | undefined;
 //#endregion
 //#region src/entity.d.ts
 export type AnySchema = Schema.Schema<unknown>;
@@ -1447,7 +1636,25 @@ export interface RefPage<Name extends string, F extends Schema.Struct.Fields = S
   readonly hasNext: boolean;
   readonly hasPrevious: boolean;
 }
+/** The ref codec a `foldkit-entity` relation becomes: one ref, a nullable ref, or an array of refs. */
+type RelationField<Spec> = Spec extends Domain.RelationSpec<infer Target, infer Cardinality, infer Optional> ? Cardinality extends 'many' ? Schema.$Array<Schema.Codec<EntityRef<Target['name']>, string>> : Optional extends true ? Schema.NullOr<Schema.Codec<EntityRef<Target['name']>, string>> : Schema.Codec<EntityRef<Target['name']>, string> : never;
+/**
+ * The fields Remote stores for a `foldkit-entity` Entity: its own fields, its
+ * derived members (the server supplies them like any field), and each relation
+ * as refs.
+ */
+export type FieldsFrom<E> = E extends Domain.Entity<any, infer Fields, infer Relations, infer Derived> ? Fields & { readonly [K in keyof Derived]: Derived[K]['schema']; } & { readonly [K in keyof Relations]: RelationField<Relations[K]>; } : never;
 declare const Entity$1: {
+  /**
+   * 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: <E extends Domain.AnyEntity>(entity: E & {
+    readonly fields: {
+      readonly id: unknown;
+    };
+  }) => EntityDescriptor<E["name"], FieldsFrom<E>>;
   make: <const Name extends string, const F extends Schema.Struct.Fields & {
     readonly id: Schema.Schema<unknown>;
   }>(name: Name, schema: Schema.Struct<F>) => EntityDescriptor<Name, F>;
@@ -1504,7 +1711,7 @@ export declare const inspectRemote: (model: RemoteModel) => RemoteInspection;
 export declare const inspectEntity: (model: RemoteModel, key: string) => RemoteInspection["entities"][number] | undefined;
 //#endregion
 //#region src/plan.d.ts
-type Window = NonNullable<Requirement$1['windows']>[string];
+type Window = NonNullable<Requirement['windows']>[string];
 /** A stable key for a window, so two equal windows compare equal. */
 export declare const windowKey: (window: Window) => string;
 export interface PlanFreshness {
@@ -1517,7 +1724,7 @@ export interface PlanOptions {
   /** Plan every requested field, present or not, tombstoned or not. */
   readonly force?: boolean | undefined;
 }
-export declare const plan: (store: EntityStore, requirements: readonly Requirement$1[], options?: PlanOptions) => ReadonlyArray<Requirement$1>;
+export declare const plan: (store: EntityStore, requirements: readonly Requirement[], options?: PlanOptions) => ReadonlyArray<Requirement>;
 //#endregion
 //#region src/policy.d.ts
 export type RemotePolicy =
@@ -1561,7 +1768,18 @@ export declare const RemotePolicy: {
 };
 //#endregion
 //#region src/index.d.ts
-type EntityName<D> = D extends EntityDescriptor<infer Name, any> ? Name : never;
+/** What a domain registers: a Remote descriptor, or a `foldkit-entity` Entity (read through `Entity.from`). */
+export type EntityLike = EntityDescriptor<any, any> | Domain.AnyEntity;
+/**
+ * What a read selects: a Remote Selection, or a `foldkit-entity` Selection
+ * (read through `Selection.from`).
+ */
+export type EntitySelection<Value, Name extends string> = Selection<Value, Name, 'entity'> | Domain.Selection<Name, unknown, Schema.Constraint & {
+  readonly Type: Value;
+}>;
+type EntityName<D> = D extends {
+  readonly name: infer Name extends string;
+} ? Name : never;
 type QueryName<D> = D extends QueryDescriptor<infer Name, any, any> ? Name : never;
 type MutationName<D> = D extends MutationDescriptor<infer Name, any, any> ? Name : never;
 /**
@@ -1572,11 +1790,11 @@ type MutationName<D> = D extends MutationDescriptor<infer Name, any, any> ? Name
 export type Registered<Name extends string, Names extends string, Kind extends string> = [Name] extends [Names] ? unknown : Invalid<`${Kind} "${Name}" is not registered with this Remote domain`>;
 /** Nothing when a selection is of the query's entity; otherwise a branded failure naming both. */
 export type SelectsEntity<Entity extends string, Of extends string> = [Entity] extends [Of] ? unknown : Invalid<`the selection is of "${Entity}", but the query lists "${Of}"`>;
-export interface RemoteDescriptor<Entities extends readonly EntityDescriptor<any, any>[] = readonly EntityDescriptor<any, any>[], Queries extends readonly QueryDescriptor<any, any, any>[] = readonly QueryDescriptor<any, any, any>[], Mutations extends readonly MutationDescriptor<any, any, any>[] = readonly MutationDescriptor<any, any, any>[]> {
+export interface RemoteDescriptor<Entities extends readonly EntityLike[] = readonly EntityLike[], Queries extends readonly QueryDescriptor<any, any, any>[] = readonly QueryDescriptor<any, any, any>[], Mutations extends readonly MutationDescriptor<any, any, any>[] = readonly MutationDescriptor<any, any, any>[]> {
   readonly entities: Entities;
   readonly queries: Queries;
   readonly mutations: Mutations;
-  readonly Model: Schema.Schema<RemoteModel>;
+  readonly Model: Schema.Codec<RemoteModel, unknown>;
   readonly initial: RemoteModel;
   readonly Message: Schema.Schema<RemoteMessage>;
   readonly update: (model: RemoteModel, message: RemoteMessage) => RemoteModel;
@@ -1613,7 +1831,17 @@ export interface DomainMutateOptions {
 }
 /** A Foldkit Subscription entry of the Remote domain, emitting its Messages through `RemoteClient`. */
 export type RemoteEntry<AppModel, Dependencies> = EntryWithoutKeepAlive<AppModel, RemoteMessage, Dependencies, RemoteClient>;
+/**
+ * The entries `RemoteDomain.subscriptions` returns for an active record: a read
+ * and a live entry per key (the live one idles when nothing is read live), and
+ * `retain`.
+ */
+export type SubscriptionEntries<AppModel, Active> = { readonly [K in keyof Active & (string | number) as `${K}.read` | `${K}.live`]: RemoteEntry<AppModel, any>; } & {
+  readonly retain: RemoteEntry<AppModel, any>;
+};
 export interface SubscriptionsOptions extends ObserveOptions, LiveOptions, RetainOptions {}
+/** A Remote domain's wiring for an assembly: it routes Remote's Messages into `reduce`, brings its Subscriptions and contract, and requires `RemoteClient` from the runtime's resources Layer. */
+export type RemoteWiring<AppModel> = Wiring<AppModel, RemoteMessage | RemoteMessageInput, RemoteClient>;
 /** What `RemoteDomain.mutate` hands `update`: the Model with the request started, and the Command that settles it. */
 export interface MutationStarted<AppModel> {
   readonly model: AppModel;
@@ -1628,15 +1856,15 @@ export interface MutationStarted<AppModel> {
  * operations over them. Every method compiles to the `Remote.*` function of the
  * same name, which stays exported for tooling, SSR, and tests.
  */
-export interface RemoteDomain<AppModel, Store extends RemoteModel, Entities extends readonly EntityDescriptor<any, any>[], Queries extends readonly QueryDescriptor<any, any, any>[], Mutations extends readonly MutationDescriptor<any, any, any>[]> extends BoundRemote<AppModel, Store, EntityName<Entities[number]>>, RemoteDescriptor<Entities, Queries, Mutations> {
+export interface RemoteDomain<AppModel, Store extends RemoteModel, Entities extends readonly EntityLike[], Queries extends readonly QueryDescriptor<any, any, any>[], Mutations extends readonly MutationDescriptor<any, any, any>[]> extends BoundRemote<AppModel, Store, EntityName<Entities[number]>>, RemoteDescriptor<Entities, Queries, Mutations> {
   /** `Remote.select`: a Projection reading one entity through a selection of a registered entity. */
-  get<Value, Name extends string>(selection: Selection<Value, Name, 'entity'> & Registered<Name, EntityName<Entities[number]>, 'Entity'>, id: string): Projection<AppModel, RemoteData<Value>>;
+  get<Value, Name extends string>(selection: EntitySelection<Value, Name> & Registered<Name, EntityName<Entities[number]>, 'Entity'>, id: string): Projection<AppModel, RemoteData<Value>>;
   /**
    * `get`, and the projection also subscribes to the entity's changes: its
    * requirements are marked `live`, so `subscriptions` derives a live entry for
    * the Surfaces that read it.
    */
-  live<Value, Name extends string>(selection: Selection<Value, Name, 'entity'> & Registered<Name, EntityName<Entities[number]>, 'Entity'>, id: string): Projection<AppModel, RemoteData<Value>>;
+  live<Value, Name extends string>(selection: EntitySelection<Value, Name> & Registered<Name, EntityName<Entities[number]>, 'Entity'>, id: string): Projection<AppModel, RemoteData<Value>>;
   /**
    * A query connection read as a `Page` of items selected of the query's
    * entity: `Initial` until the page and every item's selected fields are
@@ -1651,6 +1879,8 @@ export interface RemoteDomain<AppModel, Store extends RemoteModel, Entities exte
   previous<Name extends string, Input>(model: AppModel, projection: QueryProjection<AppModel, any, Name, Input>): QueryRef<Name, Input> | undefined;
   /** A Command that runs the query and yields the `ConnectionMerged` (or `QueryFailed`) that reduces it: "load more". */
   fetch(ref: QueryRef<string, unknown>): Command<RemoteMessage, never, RemoteClient>;
+  /** `Remote.refresh`: marks what a projection or a Surface requires as due, for its read entry to refetch. */
+  refresh(model: AppModel, target: Projection<AppModel, unknown> | Surface<AppModel, any, any, void>): AppModel;
   /**
    * The Foldkit Subscription entries for the active Surfaces, keyed for
    * `Subscription.make`: a read entry per Surface (`Remote.observe`), a live
@@ -1659,9 +1889,9 @@ export interface RemoteDomain<AppModel, Store extends RemoteModel, Entities exte
    * Surface's params are a function of the Model (`Surface.at`), so what is
    * fetched, subscribed, and retained follows the Model.
    */
-  subscriptions(active: Readonly<Record<string, ActiveSurface<AppModel> | Surface<AppModel, any, any, void>>>, options?: SubscriptionsOptions): Readonly<Record<string, RemoteEntry<AppModel, any>>>;
+  subscriptions<const Active extends Readonly<Record<string, ActiveSurface<AppModel> | Surface<AppModel, any, any, void>>>>(active: Active, options?: SubscriptionsOptions): SubscriptionEntries<AppModel, Active>;
   /** `Remote.plan`: the requirements the store does not satisfy. */
-  plan<Value>(model: AppModel, projection: Projection<AppModel, Value>, options?: PlanOptions): ReadonlyArray<Requirement$1>;
+  plan<Value>(model: AppModel, projection: Projection<AppModel, Value>, options?: PlanOptions): ReadonlyArray<Requirement>;
   /** `Remote.storeOf`: the visible store, base under the pending optimistic layers. */
   storeOf(model: AppModel): EntityStore;
   /**
@@ -1677,8 +1907,21 @@ export interface RemoteDomain<AppModel, Store extends RemoteModel, Entities exte
    * mutation sequence unless `options.requestId` is given.
    */
   mutate<M extends MutationDescriptor<any, any, any>>(model: AppModel, mutation: M & Registered<M['name'], MutationName<Mutations[number]>, 'Mutation'>, input: MutationInput<M>, options?: DomainMutateOptions): MutationStarted<AppModel>;
+  /**
+   * What Remote knows of a mutation `mutate` started, by its request id:
+   * pending, applied, or failed with the error the server or transport gave.
+   */
+  mutation(model: AppModel, requestId: string): MutationStatus;
   /** `updateRemote` on the bound slice: reduces one of Remote's Messages, as `RemoteMessage` or as the application's union constructs it. */
   reduce(model: AppModel, message: RemoteMessage | RemoteMessageInput): AppModel;
+  /**
+   * How this domain joins an assembly: it routes Remote's Messages into
+   * `reduce`, brings its Subscriptions and contract, and requires
+   * `RemoteClient` from the runtime's resources Layer. One assembly holds at
+   * most one Remote wiring: every domain claims the same tags, and routing
+   * takes the first claimant.
+   */
+  wiring: <const Active extends Readonly<Record<string, ActiveSurface<AppModel> | Surface<AppModel, any, any, void>>>>(active: Active, options?: SubscriptionsOptions) => RemoteWiring<AppModel>;
   /** `Remote.inspect` of the bound slice. */
   inspect(model: AppModel): RemoteInspection;
 }
@@ -1700,7 +1943,7 @@ export type QueryWindowOptions = {
 };
 export type QueryOptions<Value, Entity extends string, Of extends string = Entity> = {
   /** What to read of each item: a selection of the query's entity (`Of`). */
-  readonly select: Selection<Value, Entity, 'entity'> & SelectsEntity<Entity, Of>;
+  readonly select: EntitySelection<Value, Entity> & SelectsEntity<Entity, Of>;
 } & QueryWindowOptions;
 /** A query connection read as a `Page` of selected items; `ref` is the connection with its first window. */
 export interface QueryProjection<AppModel, Value, Name extends string, Input> extends Projection<AppModel, RemoteData<Page<Value>>> {
@@ -1744,12 +1987,14 @@ declare const PlannedQuery: Schema.Struct<{
 }>;
 /** The dependencies of the read entry: the entity fields to read and the queries to run. */
 export interface ReadDependencies {
-  readonly requirements: ReadonlyArray<Requirement$1>;
+  readonly requirements: ReadonlyArray<Requirement>;
   readonly queries: ReadonlyArray<Schema.Schema.Type<typeof PlannedQuery>>;
+  /** The Model's requested refresh generation: a refresh restarts the entry. */
+  readonly refresh: number;
 }
 export declare const Remote: {
   /** The submodel's schema, the same for every domain; embed it in the application Model. */
-  Model: Schema.Schema<RemoteModel>;
+  Model: Schema.Codec<RemoteModel, unknown, never, never>;
   /** The submodel's initial value. */
   initial: RemoteModel;
   /**
@@ -1759,7 +2004,7 @@ export declare const Remote: {
    */
   messages: {
     ReadReceived: {
-      requests: Schema.$Array<Schema.Codec<Requirement$1, Requirement$1, never, never>>;
+      requests: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
       result: Schema.Struct<{
         readonly entities: Schema.$Array<Schema.Struct<{
           readonly entity: Schema.String;
@@ -1770,21 +2015,22 @@ export declare const Remote: {
       now: Schema.Number;
     };
     ReadFailed: {
-      requests: Schema.$Array<Schema.Codec<Requirement$1, Requirement$1, never, never>>;
+      requests: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
       error: Schema.Struct<{
         readonly _tag: Schema.String;
         readonly message: Schema.String;
       }>;
     };
     RefreshStarted: {
-      requests: Schema.$Array<Schema.Codec<Requirement$1, Requirement$1, never, never>>;
+      requests: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
     };
     ReadStarted: {
-      requests: Schema.$Array<Schema.Codec<Requirement$1, Requirement$1, never, never>>;
+      requests: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
+      refresh: Schema.optional<Schema.Number>;
     };
     RetentionChanged: {
       roots: Schema.Struct<{
-        readonly requirements: Schema.$Array<Schema.Codec<Requirement$1, Requirement$1, never, never>>;
+        readonly requirements: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
         readonly connections: Schema.$Array<Schema.Struct<{
           readonly identity: Schema.String;
           readonly select: Schema.optional<Schema.Codec<RelationRequirement, RelationRequirement, never, never>>;
@@ -1807,6 +2053,10 @@ export declare const Remote: {
         readonly values: Schema.$Record<Schema.String, Schema.Unknown>;
       }>>;
       connections: Schema.optional<Schema.$Array<Schema.Unknown>>;
+      deleted: Schema.optional<Schema.$Array<Schema.Struct<{
+        readonly entity: Schema.String;
+        readonly id: Schema.String;
+      }>>>;
     };
     MutationFailed: {
       requestId: Schema.String;
@@ -1854,7 +2104,7 @@ export declare const Remote: {
    * in one step; the result carries the application-facing operations. The
    * descriptor alone is `Remote.define`, the binding alone `Remote.at`.
    */
-  make: <AppModel, Store extends RemoteModel, const Entities extends readonly EntityDescriptor<any, any>[], const Queries extends readonly QueryDescriptor<any, any, any>[] = readonly [], const Mutations extends readonly MutationDescriptor<any, any, any>[] = readonly []>(config: {
+  make: <AppModel, Store extends RemoteModel, const Entities extends readonly EntityLike[], const Queries extends readonly QueryDescriptor<any, any, any>[] = readonly [], const Mutations extends readonly MutationDescriptor<any, any, any>[] = readonly []>(config: {
     readonly model: ModelRef<AppModel, Store>;
     readonly entities: Entities;
     readonly queries?: Queries;
@@ -1865,7 +2115,7 @@ export declare const Remote: {
    * mutations, plus the submodel. For a domain reused across applications or
    * bound in a test; `Remote.make` is the one-step form.
    */
-  define: <const Entities extends readonly EntityDescriptor<any, any>[], const Queries extends readonly QueryDescriptor<any, any, any>[] = readonly QueryDescriptor<any, any, any>[], const Mutations extends readonly MutationDescriptor<any, any, any>[] = readonly MutationDescriptor<any, any, any>[]>(config: {
+  define: <const Entities extends readonly EntityLike[], const Queries extends readonly QueryDescriptor<any, any, any>[] = readonly QueryDescriptor<any, any, any>[], const Mutations extends readonly MutationDescriptor<any, any, any>[] = readonly MutationDescriptor<any, any, any>[]>(config: {
     readonly entities: Entities;
     readonly queries?: Queries;
     readonly mutations?: Mutations;
@@ -1875,7 +2125,7 @@ export declare const Remote: {
    * registered entity names are carried on the returned value, so `Remote.select`
    * rejects a selection for an entity this domain never declared.
    */
-  at: <AppModel, Store extends RemoteModel, Entities extends readonly EntityDescriptor<any, any>[], Queries extends readonly QueryDescriptor<any, any, any>[], Mutations extends readonly MutationDescriptor<any, any, any>[]>(definition: RemoteDescriptor<Entities, Queries, Mutations>, store: ModelRef<AppModel, Store>) => BoundRemote<AppModel, Store, EntityName<Entities[number]>>;
+  at: <AppModel, Store extends RemoteModel, Entities extends readonly EntityLike[], Queries extends readonly QueryDescriptor<any, any, any>[], Mutations extends readonly MutationDescriptor<any, any, any>[]>(definition: RemoteDescriptor<Entities, Queries, Mutations>, store: ModelRef<AppModel, Store>) => BoundRemote<AppModel, Store, EntityName<Entities[number]>>;
   /**
    * 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
@@ -1883,13 +2133,13 @@ export declare 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: <AppModel, Store extends RemoteModel, Names extends string, Value, Name extends string>(bound: BoundRemote<AppModel, Store, Names>, selection: Selection<Value, Name, "entity"> & Registered<Name, Names, "Entity">) => (id: string) => Projection<AppModel, RemoteData<Value>>;
+  select: <AppModel, Store extends RemoteModel, Names extends string, Value, Name extends string>(bound: BoundRemote<AppModel, Store, Names>, given: EntitySelection<Value, Name> & Registered<Name, Names, "Entity">) => (id: string) => Projection<AppModel, RemoteData<Value>>;
   /**
    * The pure plan for a projection against a Model: the requirements its
    * remote store does not satisfy, under `options` (freshness, force). A
    * Surface's projection is `surface.projection(params)`.
    */
-  plan: <AppModel, Store extends RemoteModel, Value>(bound: BoundRemote<AppModel, Store>, model: AppModel, projection: Projection<AppModel, Value>, options?: PlanOptions) => ReadonlyArray<Requirement$1>;
+  plan: <AppModel, Store extends RemoteModel, Value>(bound: BoundRemote<AppModel, Store>, model: AppModel, projection: Projection<AppModel, Value>, options?: PlanOptions) => ReadonlyArray<Requirement>;
   /**
    * The queries a projection needs run before its connections read: those the
    * Model does not hold, or holds stale (every one under `force`).
@@ -1908,11 +2158,30 @@ export declare const Remote: {
    * is the clock it reads, so the planner itself stays pure and time-injected.
    */
   prefetch: <AppModel, Store extends RemoteModel, Value>(bound: BoundRemote<AppModel, Store, string>, model: AppModel, projection: Projection<AppModel, Value>, options?: ObserveOptions | undefined) => Effect.Effect<Readonly<Record<string, EntityEntry>>, RemoteReadError | RemoteProtocolError, RemoteClient>;
+  /**
+   * 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: <AppModel, Store extends RemoteModel>(bound: BoundRemote<AppModel, Store>, model: AppModel, target: Projection<AppModel, unknown> | Surface<AppModel, any, any, void>) => AppModel;
   /**
    * Writes a read result into the store, recording each field's applied window.
    * `requests` are the planned requirements the result answers.
    */
-  writeRead: (store: EntityStore, requests: ReadonlyArray<Requirement$1>, result: Schema.Schema.Type<typeof ReadBatchResult>, now?: number) => EntityStore;
+  writeRead: (store: EntityStore, requests: ReadonlyArray<Requirement>, result: Schema.Schema.Type<typeof ReadBatchResult>, now?: number) => EntityStore;
   /**
    * Adapts an Effect RPC client for `RemoteRpc` to `RemoteClient`, so an
    * application provides the transport's RPC layer instead of writing the
@@ -1987,6 +2256,10 @@ export declare const Remote: {
       };
     }[];
     connections: ConnectionChange[];
+    deleted: readonly {
+      readonly entity: string;
+      readonly id: string;
+    }[];
   }, RemoteMutationError, RemoteClient>;
   /**
    * Runs a mutation and reconciles its patches into a `RemoteModel` in one step,
@@ -2015,10 +2288,10 @@ export declare const Remote: {
    * from `RemoteModel.live`, so the application tracks no cursor of its own.
    */
   live: <AppModel, Store extends RemoteModel, Names extends string, Model, SurfaceMessage, Params, Message = RemoteMessage>(bound: BoundRemote<AppModel, Store, Names>, surface: Surface<AppModel, Model, SurfaceMessage, Params>, params: Params, toMessage?: (message: RemoteMessage) => Message, options?: LiveOptions) => EntryWithoutKeepAlive<AppModel, Message, {
-    readonly requirements: ReadonlyArray<Requirement$1>;
+    readonly requirements: ReadonlyArray<Requirement>;
     readonly cursor: LiveCursor;
   }, RemoteClient>;
 };
 //#endregion
-export { Entity$1 as Entity, type RelationRequirement, type Requirement };
+export { Entity$1 as Entity };
 //# sourceMappingURL=index.d.mts.map