foldkit-remote 0.3.0 → 0.5.0

package/dist/index.d.mts

@@ -1,9 +1,65 @@
 import { Context, Duration, Effect, Layer, Option, Schema, Stream } from "effect";
-import { ActiveSurface, Contract, Invalid, Metadata, ModelRef, Projection, Surface } from "foldkit-surface";
+import * as Domain from "foldkit-entity";
+import { AnyEntity, AnyQuery, InputExpr, Query as Query$1 } 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 +105,96 @@ 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';
+};
+/**
+ * What `RemoteData.render` tells the `data` branch about the value it is
+ * given: whether a newer answer is on its way, and whether this one is what
+ * was last known good before a read failed. It is one tag rather than two
+ * booleans because a value cannot be both at once, and a type that can say so
+ * invites a view to handle a state that never arrives.
+ */
+export type Freshness = {
+  readonly _tag: 'Fresh';
+} | {
+  readonly _tag: 'Refreshing';
+} | {
+  readonly _tag: 'Stale';
+  readonly error: RemoteError;
+};
+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;
+  /**
+   * The view-oriented fold: the six states as the three things a view actually
+   * draws, under the policy that useful data stays on screen. A value that is
+   * being refetched, or that a later read failed to replace, still reaches
+   * `data` — with `freshness` saying which — instead of being replaced by a
+   * spinner or an error the reader cannot act on.
+   *
+   * ```ts
+   * RemoteData.render(model.user, {
+   *   loading: () => UserSkeleton(),
+   *   notFound: () => NoSuchUser(),
+   *   failed: error => ErrorView(error),
+   *   data: (user, freshness) => UserView({ user, dimmed: freshness._tag !== 'Fresh' }),
+   * })
+   * ```
+   *
+   * `notFound` is its own branch and not optional: a row the server answered
+   * for and does not have is neither loading nor a failure, and drawing it as
+   * either is a spinner that never ends or an error nobody can fix.
+   *
+   * This does not replace `match`, which is the exhaustive fold over the states
+   * themselves. Reach for `match` when the six states really do draw
+   * differently, and for this when they draw the usual three ways.
+   */
+  render: <A, R>(data: RemoteData<A>, cases: {
+    readonly loading: () => R;
+    readonly notFound: () => R;
+    readonly failed: (error: RemoteError) => R;
+    readonly data: (value: A, freshness: Freshness) => 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 +274,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 +285,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 +309,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;
@@ -202,7 +367,20 @@ export interface QueryDescriptor<Name extends string, Input, Result> {
   readonly Input: Schema.Codec<Input>;
   readonly Result: Result;
   readonly ref: (input: Input) => QueryRef<Name, Input>;
+  /**
+   * What the query means, when it was declared with `Query.define`: the rows it
+   * is about, as a value an interpreter can compile. A descriptor from
+   * `Query.make` has none — its meaning lives in whatever the server registered
+   * to answer it — and a source is free to answer either.
+   */
+  readonly body?: AnyQuery | undefined;
 }
+/**
+ * The inputs of a definition's body: one placeholder per key of `Input`, typed
+ * as that key's value. A body is built once, so these stand for what the query
+ * will be given rather than being it.
+ */
+export type QueryInputs<Input> = { readonly [K in keyof Input & string]: InputExpr<Input[K]>; };
 /** Stable stringify: object keys sorted, undefined-valued keys dropped, so equal inputs encode equally. */
 export declare const stableStringify: (value: unknown) => string;
 /**
@@ -213,6 +391,8 @@ export declare const stableStringify: (value: unknown) => string;
 export type ResultOf<Result> = Result extends {
   readonly name: infer Entity extends string;
 } ? ConnectionSpec<Entity> : Result;
+/** A relational `Query` over one Entity, as `Query.define`'s body returns. */
+type RelationalQueryOf<E extends AnyEntity> = ReturnType<typeof Query$1.from<E>>;
 export declare const Query: {
   /** Declares the entity and options a query's result is a connection over. */
   connection: <Entity extends string>(entity: {
@@ -230,10 +410,44 @@ export declare const Query: {
     readonly Input: Input;
     readonly Result: Result;
   }) => QueryDescriptor<Name, TypeOf<Input>, ResultOf<Result>>;
+  /**
+   * Declares a query by what it means. The body is built once, here, and the
+   * `input` it is given holds placeholders rather than values — there is
+   * nothing yet to branch on, so a condition that depends on what was passed is
+   * a comparison over the placeholder:
+   *
+   * ```ts
+   * const PostsBySlug = Query.define('PostsBySlug', { slug: Schema.String }, ({ input }) =>
+   *   Query.from(Post).pipe(
+   *     Query.where(Expr.eq(Post.fields.slug, input.slug)),
+   *     Query.orderBy(Order.asc(Post.fields.id)),
+   *   ),
+   * )
+   * ```
+   *
+   * What comes back is an ordinary `QueryDescriptor` — the same name, `Input`,
+   * `ref` and connection identity `Query.make` gives — carrying its `body`
+   * besides. A server can compile that body instead of being told the same
+   * thing again in its own dialect, and one that would rather answer the query
+   * its own way still can.
+   *
+   * The result is a connection over the Entity the body reads, so it is not
+   * named twice.
+   */
+  define: <const Name extends string, Input extends SchemaOrFields, E extends AnyEntity>(name: Name, Input: Input, body: (context: {
+    readonly input: QueryInputs<TypeOf<Input>>;
+  }) => RelationalQueryOf<E>, options?: {
+    readonly edgeKey?: Schema.Schema<unknown>;
+    readonly live?: LivePolicy;
+  }) => QueryDescriptor<Name, TypeOf<Input>, ConnectionSpec<E["name"]>>;
   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;
+  from: <E extends AnyEntity>(entity: E) => Query$1<E>;
+  where: (...predicates: ReadonlyArray<import("foldkit-entity").Predicate>) => <E extends AnyEntity>(self: Query$1<E>) => Query$1<E>;
+  orderBy: (...terms: ReadonlyArray<import("foldkit-entity").OrderTerm>) => <E extends AnyEntity>(self: Query$1<E>) => Query$1<E>;
+  dependencies: (self: AnyQuery) => import("foldkit-entity").Dependencies;
 };
 //#endregion
 //#region src/requirement.d.ts
@@ -283,9 +497,9 @@ export declare const Requirement: {
   mergeConnections: typeof mergeConnections;
 };
 /** Remote's entity requirements on a Projection, unioned per entity and id as nodes compose. */
-export declare const RemoteRequirements: import("foldkit-surface").MetadataKey<Requirement>;
+export declare const RemoteRequirements: MetadataKey<Requirement>;
 /** Remote's query connections on a Projection, unioned per connection and window. */
-export declare const RemoteConnections: import("foldkit-surface").MetadataKey<ConnectionRequirement>;
+export declare const RemoteConnections: MetadataKey<ConnectionRequirement>;
 /** The entity requirements a Projection carries. */
 export declare const requirementsOf: (projection: {
   readonly metadata: Metadata;
@@ -381,7 +595,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;
@@ -672,6 +889,11 @@ 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;
@@ -760,6 +982,11 @@ 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;
@@ -924,6 +1151,11 @@ 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, Requirement, never, never>>;
@@ -997,51 +1229,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.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/model.d.ts
 /**
  * The normalized cache as a Foldkit Submodel. `Remote.define` returns a schema
@@ -1068,15 +1255,25 @@ export interface RemoteModel {
    */
   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.
+   * `Remote.refresh` generations, held per field rather than for the store as a
+   * whole. A read entry restarts when the generation over the fields it plans
+   * moves, so a read sent before a refresh of its own fields cannot land after
+   * it, and a refresh of one field leaves every other entry's read alone.
    */
-  readonly refresh: {
-    readonly requested: number;
-    readonly started: number;
-  };
+  readonly refresh: RefreshState;
 }
+/**
+ * `Remote.refresh` generations, per field mark. `generation` is the last one
+ * handed out; `requested` is when each field was last refreshed, and `started`
+ * is the generation each field's read last began under. Holding them per field
+ * is what keeps one Projection's refresh from restarting every read entry.
+ */
+export interface RefreshState {
+  readonly generation: number;
+  readonly requested: ReadonlyMap<string, number>;
+  readonly started: ReadonlyMap<string, number>;
+}
+export declare const emptyRefresh: RefreshState;
 export declare const initialRemoteModel: RemoteModel;
 export declare const remoteModelSchema: () => Schema.Codec<RemoteModel, unknown>;
 /** The submodel's Messages; each reduces to `RemoteModel` through `updateRemote`. */
@@ -1124,10 +1321,28 @@ 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;
   readonly error: RemoteError;
+} |
+/**
+ * Operations shown over the store with no request behind them, until they are
+ * lifted: a preview of a change nobody has made. Showing an id again replaces
+ * what it showed.
+ */
+{
+  readonly _tag: 'OverlayShown';
+  readonly id: string;
+  readonly optimistic: ReadonlyArray<OptimisticOperation>;
+} | {
+  readonly _tag: 'OverlayLifted';
+  readonly id: string;
 } | {
   readonly _tag: 'LiveReceived';
   readonly stream: string;
@@ -1218,6 +1433,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;
@@ -1226,6 +1445,13 @@ export declare const remoteMessageCases: {
       readonly message: Schema.String;
     }>;
   };
+  OverlayShown: {
+    id: Schema.String;
+    optimistic: Schema.$Array<Schema.Unknown>;
+  };
+  OverlayLifted: {
+    id: Schema.String;
+  };
   LiveReceived: {
     stream: Schema.String;
     event: Schema.Unknown;
@@ -1273,6 +1499,25 @@ export declare const isRemoteMessage: <M extends {
   readonly _tag: RemoteMessageTag;
 }>;
 export declare const remoteMessageSchema: Schema.Schema<RemoteMessage>;
+/**
+ * The generation a read is planned under: the highest any of the fields it
+ * reads or connections it runs was refreshed at. A read entry carries this as a
+ * dependency, so it restarts when what it observes is refreshed and not when
+ * anything else is.
+ */
+export declare const refreshedAt: (refresh: RefreshState, requests: ReadonlyArray<Requirement>, connections?: ReadonlyArray<string>) => number;
+/**
+ * Marks every field of `requests` and every connection in `connections`
+ * refreshed at the next generation.
+ */
+export declare const withRefreshRequested: (refresh: RefreshState, requests: ReadonlyArray<Requirement>, connections?: ReadonlyArray<string>) => RefreshState;
+/**
+ * Whether one field's read already began under the generation that field was
+ * last refreshed at. Such a read is in flight and would otherwise outlive the
+ * refresh, so the refresh takes a new generation to restart it even though the
+ * field is already stale.
+ */
+export declare const refreshIsInFlight: (refresh: RefreshState, request: Requirement, field: string) => boolean;
 /**
  * Whether a read is fetching any of `fields` for this entity. Consulted only
  * when the store lacks the value, which is what separates `Loading` from
@@ -1374,6 +1619,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
@@ -1397,6 +1646,25 @@ export interface RelationShape {
   readonly nullable: boolean;
   readonly entity: string;
 }
+/**
+ * A page of a relation that is a whole list is read under a name of its own, the
+ * field's name and the page's size: `comments@first=10`. It is a field like any
+ * other to the store, the planner, and the wire, so the whole list and a page of
+ * it are held side by side, merged, marked stale, and persisted each on its own.
+ * The server reads the name apart, reads the relation with the window, and
+ * answers under the alias. A cursor is not part of the name: a page read from a
+ * cursor merges onto the page it continues.
+ */
+export declare const RELATION_ALIAS = "@";
+/** The alias a relation field is read under, for a window of this size. */
+export declare const relationAlias: (field: string, window: {
+  readonly first?: number | undefined;
+  readonly last?: number | undefined;
+  readonly after?: string | undefined;
+  readonly before?: string | undefined;
+}) => string;
+/** The field an alias reads; a name that is no alias is its own field. */
+export declare const aliasedField: (name: string) => string;
 /** Splits a ref key (`"Entity:id"`, the store key too) back into its parts. */
 export declare const refParts: (encoded: string) => RefParts;
 /**
@@ -1458,6 +1726,11 @@ 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;
 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
@@ -1526,7 +1799,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>;
@@ -1571,6 +1862,13 @@ export interface RemoteInspection {
   readonly connections: ReadonlyArray<string>;
   readonly live: ReadonlyArray<string>;
   readonly gaps: ReadonlyArray<string>;
+  /**
+   * The `entity\0id\0field` marks of reads in flight. This is what "Remote is
+   * working" means here, and it is read from the Model rather than from the
+   * fibers doing the work: a tool that shows it shows something the Model can
+   * be replayed to, and nothing that needs the runtime to be asked.
+   */
+  readonly loading: ReadonlyArray<string>;
   readonly mutations: {
     readonly pending: ReadonlyArray<string>;
     readonly failed: ReadonlyArray<string>;
@@ -1640,7 +1938,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, Id extends string = string> = Selection<Value, Name, 'entity'> | Domain.Selection<Name, unknown, Schema.Constraint & {
+  readonly Type: Value;
+}, Id>;
+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;
 /**
@@ -1651,7 +1960,7 @@ 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;
@@ -1701,6 +2010,8 @@ export type SubscriptionEntries<AppModel, Active> = { readonly [K in keyof Activ
   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;
@@ -1715,15 +2026,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, Id extends string = string>(selection: EntitySelection<Value, Name, Id> & Registered<Name, EntityName<Entities[number]>, 'Entity'>, id: NoInfer<Id>): 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, Id extends string = string>(selection: EntitySelection<Value, Name, Id> & Registered<Name, EntityName<Entities[number]>, 'Entity'>, id: NoInfer<Id>): 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
@@ -1738,6 +2049,15 @@ 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>;
+  /**
+   * Shows operations over the store with no request behind them, as a mutation's
+   * `optimistic` ones show while it is in flight: every Selection and view draws
+   * them. For a preview of a change nobody has made. They stay until `lift`;
+   * showing an id again replaces what it showed. Called from `update`.
+   */
+  overlay(model: AppModel, id: string, optimistic: ReadonlyArray<OptimisticOperation>): AppModel;
+  /** Lifts what `overlay` showed under this id. Lifting nothing returns the same Model. */
+  lift(model: AppModel, id: string): AppModel;
   /** `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;
   /**
@@ -1753,6 +2073,30 @@ export interface RemoteDomain<AppModel, Store extends RemoteModel, Entities exte
   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;
+  /**
+   * `Remote.confirmed`: the same projection read against the server-derived
+   * store alone, with every pending optimistic layer and connection overlay
+   * left off. What it plans is unchanged — the requirements are the
+   * projection's own — so observing it reads exactly what observing the
+   * projection reads; only what it *shows* differs.
+   *
+   * A view usually wants the projection itself, which is the visible read:
+   * the optimistic layers are there so a change shows before the server has
+   * agreed to it. This is for the reader that must not believe a change until
+   * the server has confirmed it, which in practice is an Agent capability
+   * reporting that what it was asked to do is done:
+   *
+   * ```ts
+   * Agent.when({
+   *   projection: Data.confirmed(ProjectPage.model.project),
+   *   predicate: (project, request) => project.name === request.name,
+   * })
+   * ```
+   *
+   * There is deliberately no `visible`: a projection is already the visible
+   * read, and a wrapper that only forwards would be a second name for it.
+   */
+  confirmed<P extends Projection<AppModel, any>>(projection: P): P;
   /**
    * The plan run through `RemoteClient` and reduced into the Model: the
    * projection's pending queries first, then the fields it lacks (the pages'
@@ -1766,8 +2110,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;
 }
@@ -1789,7 +2146,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>>> {
@@ -1835,7 +2192,11 @@ declare const PlannedQuery: Schema.Struct<{
 export interface ReadDependencies {
   readonly requirements: ReadonlyArray<Requirement>;
   readonly queries: ReadonlyArray<Schema.Schema.Type<typeof PlannedQuery>>;
-  /** The Model's requested refresh generation: a refresh restarts the entry. */
+  /**
+   * The highest generation the fields this entry reads were refreshed at: a
+   * refresh of any of them restarts the entry, and a refresh of anything else
+   * leaves it running.
+   */
   readonly refresh: number;
 }
 export declare const Remote: {
@@ -1899,6 +2260,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;
@@ -1907,6 +2272,13 @@ export declare const Remote: {
         readonly message: Schema.String;
       }>;
     };
+    OverlayShown: {
+      id: Schema.String;
+      optimistic: Schema.$Array<Schema.Unknown>;
+    };
+    OverlayLifted: {
+      id: Schema.String;
+    };
     LiveReceived: {
       stream: Schema.String;
       event: Schema.Unknown;
@@ -1946,7 +2318,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;
@@ -1957,7 +2329,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;
@@ -1967,7 +2339,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
@@ -1975,7 +2347,7 @@ 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
@@ -1993,6 +2365,12 @@ export declare const Remote: {
    * has not changed.
    */
   storeOf: <AppModel, Store extends RemoteModel>(bound: BoundRemote<AppModel, Store>, model: AppModel) => EntityStore;
+  /**
+   * The projection read against the server-derived store alone: the same
+   * requirements, planned the same way, with the pending optimistic layers and
+   * connection overlays left off. See the bound `Remote.confirmed`.
+   */
+  confirmed: <AppModel, Store extends RemoteModel, P extends Projection<AppModel, any>>(bound: BoundRemote<AppModel, Store>, projection: P) => P;
   /**
    * Executes the plan against the `RemoteClient` and returns a new store. Used
    * for SSR route prefetch, hover prefetch, and tests. Never called during render.
@@ -2098,6 +2476,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,