foldkit-remote 0.4.0 → 0.6.0

package/dist/index.d.mts

@@ -1,5 +1,6 @@
 import { Context, Duration, Effect, Layer, Option, Schema, Stream } from "effect";
 import * as Domain from "foldkit-entity";
+import { AnyEntity, AnyQuery, Dependencies, 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";
@@ -126,6 +127,21 @@ export type RemoteData<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;
@@ -146,6 +162,36 @@ export declare const RemoteData: {
     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
@@ -321,7 +367,30 @@ 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]>; };
+/**
+ * What separates a query's name from its canonical encoded input in a
+ * connection identity.
+ *
+ * NUL, because `JSON.stringify` escapes it inside a string (`\u0000`) and a
+ * query name is a TypeScript identifier — so the first occurrence is always the
+ * boundary, and a name or an input value cannot forge one. Anything recovering
+ * the query from an identity splits here.
+ */
+export declare const IDENTITY_SEPARATOR = "\0";
 /** Stable stringify: object keys sorted, undefined-valued keys dropped, so equal inputs encode equally. */
 export declare const stableStringify: (value: unknown) => string;
 /**
@@ -332,6 +401,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: {
@@ -349,10 +420,46 @@ 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;
+  unsupported: (self: AnyQuery, supported: ReadonlyArray<import("foldkit-entity").Operation>) => ReadonlyArray<import("foldkit-entity").Operation>;
+  show: (self: AnyQuery) => string;
 };
 //#endregion
 //#region src/requirement.d.ts
@@ -556,8 +663,6 @@ export interface BoundaryCounts {
 export interface LiveState {
   /** Last applied cursor for this stream. */
   readonly cursor: LiveCursor;
-  /** Connections marked stale by an invalidating event. */
-  readonly stale: ReadonlySet<string>;
   /** Edges recorded outside the loaded boundary, not visible in `items`. */
   readonly boundary: Readonly<Record<string, BoundaryCounts>>;
 }
@@ -570,7 +675,6 @@ export type LiveOutcome = 'applied' | 'duplicate' | 'gap';
  * spurious gap.
  */
 export declare const classifyLive: (state: LiveState, cursor: LiveCursor) => LiveOutcome;
-export declare const invalidateConnection: (state: LiveState, connection: string) => LiveState;
 /**
  * A subscriber is woken only if the event changed a field it selects. A
  * change to an unselected field is skipped entirely.
@@ -588,17 +692,17 @@ export interface ConnectionApplied {
   readonly state: LiveState;
   readonly optimistic: OptimisticState;
   readonly outcome: LiveOutcome;
+  /**
+   * A connection the event says to refetch. Reported rather than recorded here,
+   * because staleness lives on the connection in the Model — which is what the
+   * planner and every read consult. It used to be written into a set on this
+   * live state that nothing read, so an invalidating event did nothing at all.
+   */
+  readonly invalidated?: string | undefined;
 }
 export declare const applyConnectionEvent: (state: LiveState, optimistic: OptimisticState, event: Extract<LiveEvent, {
   _tag: "ConnectionInsert" | "ConnectionRemove" | "ConnectionInvalidate";
 }>, policy?: LivePolicy) => ConnectionApplied;
-export declare const isStale: (state: LiveState, connection: string) => boolean;
-/**
- * Clears a connection's stale mark once a fresh page has been adopted. An
- * invalidating event only records that a refetch is due; whoever merges the
- * refetched page calls this so `isStale` stops reporting.
- */
-export declare const refreshConnection: (state: LiveState, connection: string) => LiveState;
 /** `hasPrevious` accounting for edges recorded outside the loaded boundary. */
 export declare const liveHasPrevious: (connection: Connection, state: LiveState, connectionId: string) => boolean;
 /** `hasNext` accounting for edges recorded outside the loaded boundary. */
@@ -636,7 +740,33 @@ export declare const gc: (state: Retained & {
 //#endregion
 //#region src/persistence.d.ts
 /** Bump when the serialized shape changes; a mismatch discards the cache. */
-export declare const REMOTE_CACHE_VERSION = 3;
+export declare const REMOTE_CACHE_VERSION = 4;
+/**
+ * What survives a reload: the entity cache, and the connections an application
+ * **declared** should come back.
+ *
+ * Connections are session state by default and stay that way — `snapshotOf`
+ * takes none unless asked. What a declared one keeps is its **edges and
+ * nothing else**, which is not a simplification but the rule: a connection's
+ * boundaries are cursors the server minted, and a cursor may name server state
+ * that no longer exists. Restoring one would be claiming to know where the
+ * page ends. The shape has nowhere to put a cursor, so that cannot be got
+ * wrong later.
+ */
+export interface Snapshot {
+  readonly entities: EntityStore;
+  /**
+   * By connection identity: its **segments**, each a run of edges. No
+   * boundaries.
+   *
+   * Segments rather than one flat list, because the gaps between them are
+   * knowledge too. A connection paged from both ends holds a head and a tail
+   * with an unfetched middle; flattening those into one run would claim the
+   * tail's first row follows the head's last, which is a thing the client was
+   * never told.
+   */
+  readonly connections: Readonly<Record<string, ReadonlyArray<ReadonlyArray<Edge>>>>;
+}
 export interface SnapshotOptions {
   /**
    * Who or what the snapshot is for (a user id, a tenant, a build). A snapshot
@@ -650,36 +780,50 @@ 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`.
+ * The snapshot text, or `undefined` when it would exceed `maxBytes`. Build the
+ * snapshot with `snapshotOf`, which is where the connections that survive are
+ * named; runtime state — optimistic layers, live cursors, gaps, the mutation
+ * ledger — is never in one.
  */
-declare function dehydrate(store: EntityStore, options?: SnapshotOptions & {
+declare function dehydrate(snapshot: Snapshot, options?: SnapshotOptions & {
   readonly maxBytes?: undefined;
 }): string;
-declare function dehydrate(store: EntityStore, options?: SnapshotOptions): string | undefined;
+declare function dehydrate(snapshot: Snapshot, options?: SnapshotOptions): string | undefined;
 export declare const RemotePersistence: {
   /** The snapshot text, or `undefined` when it would exceed `maxBytes`. */
   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. */
+  /** What a snapshot text holds, or `undefined` when it is refused. */
+  hydrate: (raw: string | undefined | null, options?: SnapshotOptions) => Snapshot | undefined;
+  /**
+   * What to keep of a Model, naming the connections that should survive a
+   * reload. Naming none is the default and is what Remote always did.
+   */
+  snapshotOf: (model: {
+    readonly entities: EntityStore;
+    readonly connections: Readonly<Record<string, Connection>>;
+  }, options?: {
+    readonly connections?: ReadonlyArray<ConnectionIdentity> | undefined;
+  }) => Snapshot;
+  /** A snapshot's entities brought into a store by policy. */
   mergeStores: (current: EntityStore, snapshot: EntityStore, policy: MergePolicy) => EntityStore;
+  /** The cache as a fresh session has it; what a refused `restore` yields. */
+  emptySnapshot: Snapshot;
   /**
    * Writes the snapshot under `key`, or removes the key when the store would
    * exceed `maxBytes`, so a stale smaller snapshot cannot outlive a larger
    * store it no longer describes.
    */
-  save: (store: EntityStore, options: {
+  save: (snapshot: Snapshot, options: {
     readonly key: string;
   } & SnapshotOptions) => Effect.Effect<void, KeyValueStore.KeyValueStoreError, KeyValueStore.KeyValueStore>;
   /**
-   * Reads the cache. A missing key yields `emptyStore`; anything `hydrate`
-   * refuses yields `emptyStore` and removes the key, so the next `restore` is
-   * clean and the planner refetches.
+   * Reads the cache. A missing key yields `emptySnapshot`; anything `hydrate`
+   * refuses yields `emptySnapshot` and removes the key, so the next `restore`
+   * is clean and the planner refetches.
    */
   restore: (options: {
     readonly key: string;
-  } & SnapshotOptions) => Effect.Effect<Readonly<Record<string, EntityEntry>>, KeyValueStore.KeyValueStoreError, KeyValueStore.KeyValueStore>;
+  } & SnapshotOptions) => Effect.Effect<Snapshot, KeyValueStore.KeyValueStoreError, KeyValueStore.KeyValueStore>;
 };
 //#endregion
 //#region src/wire.d.ts
@@ -1160,15 +1304,52 @@ 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;
+  /**
+   * The reads that failed and have not been settled since, so a read can say
+   * `Failed` rather than `Initial`.
+   *
+   * Without them a read that failed before anything loaded read exactly like
+   * one nobody had asked for, and nothing asked again: a read entry restarts
+   * only when what it plans changes, and a failure changed nothing. What failed
+   * is not planned again on its own either, so a persistent error is not
+   * retried every time an unrelated read restarts the entry. `Remote.refresh`
+   * is how a view retries.
+   */
+  readonly failures: Failures;
+}
+/**
+ * Failed reads, as the errors they failed with.
+ *
+ * `connections` is by connection identity, and is settled by a page arriving,
+ * an invalidation, or retention dropping the connection. `fields` is by field
+ * mark (`entity\0id\0field`, the marks `loading` uses), and is settled by the
+ * field being written again, a refresh asking for it, or retention dropping the
+ * entity. A read of it in flight reads `Loading` over the failure without
+ * settling it: if that read fails too, the failure is simply recorded again.
+ */
+export interface Failures {
+  readonly connections: Readonly<Record<string, RemoteError>>;
+  readonly fields: Readonly<Record<string, RemoteError>>;
 }
+export declare const noFailures: Failures;
+/**
+ * `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`. */
@@ -1181,6 +1362,13 @@ export type RemoteMessage = {
   readonly _tag: 'ReadFailed';
   readonly requests: readonly Requirement[];
   readonly error: RemoteError;
+  /**
+   * The live stream whose subscription broke, when this is that rather
+   * than a read. Nothing was being read, so no field failed: the stream is
+   * recorded as a gap, since changes after it are missed until the host
+   * resubscribes.
+   */
+  readonly stream?: string | undefined;
 } |
 /** A refetch of present fields began; they read as `Refreshing` until it lands. */
 {
@@ -1194,6 +1382,15 @@ export type RemoteMessage = {
   /** The refresh generation the read was planned under. */
   readonly refresh?: number | undefined;
 } |
+/**
+ * Queries for these connections were sent. One with nothing to show reads
+ * `Loading` until its page or its failure arrives, which is what separates
+ * "being fetched" from `Initial`, "nothing is fetching this".
+ */
+{
+  readonly _tag: 'QueryStarted';
+  readonly connections: readonly string[];
+} |
 /** The active Surfaces' roots changed; everything they do not reach is collected. */
 {
   readonly _tag: 'RetentionChanged';
@@ -1203,6 +1400,13 @@ export type RemoteMessage = {
 {
   readonly _tag: 'Hydrated';
   readonly entities: EntityStore;
+  /**
+   * The connections a snapshot declared should survive, as their edges.
+   * Restored with **unknown** boundaries and marked stale: the rows show
+   * at once and the connection is refetched, because a persisted cursor
+   * may name server state that is gone.
+   */
+  readonly connections?: Readonly<Record<string, ReadonlyArray<ReadonlyArray<Edge>>>> | undefined;
   readonly merge: MergePolicy;
 } |
 /** A mutation began; its optimistic operations show until it settles. */
@@ -1225,6 +1429,19 @@ export type RemoteMessage = {
   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;
@@ -1247,7 +1464,11 @@ export type RemoteMessage = {
   readonly _tag: 'ConnectionRefreshed';
   readonly connection: string;
 } |
-/** A query for the connection failed; it reads as it did before the request. */
+/**
+ * A query for the connection failed. Its pages stay as they were, and it
+ * reads `Failed` — with them as `previous`, when it has any — until a page
+ * arrives, it is invalidated, or retention drops it.
+ */
 {
   readonly _tag: 'QueryFailed';
   readonly connection: string;
@@ -1282,6 +1503,7 @@ export declare const remoteMessageCases: {
       readonly _tag: Schema.String;
       readonly message: Schema.String;
     }>;
+    stream: Schema.optional<Schema.String>;
   };
   RefreshStarted: {
     requests: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
@@ -1290,6 +1512,9 @@ export declare const remoteMessageCases: {
     requests: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
     refresh: Schema.optional<Schema.Number>;
   };
+  QueryStarted: {
+    connections: Schema.$Array<Schema.String>;
+  };
   RetentionChanged: {
     roots: Schema.Struct<{
       readonly requirements: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
@@ -1300,6 +1525,7 @@ export declare const remoteMessageCases: {
     }>;
   };
   Hydrated: {
+    connections: Schema.optional<Schema.Unknown>;
     entities: Schema.Unknown;
     merge: Schema.Union<readonly [Schema.Literal<"replace">, Schema.Literal<"preserve-existing">]>;
   };
@@ -1327,6 +1553,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;
@@ -1374,6 +1607,27 @@ export declare const isRemoteMessage: <M extends {
   readonly _tag: RemoteMessageTag;
 }>;
 export declare const remoteMessageSchema: Schema.Schema<RemoteMessage>;
+/** Whether a query for this connection is in flight. */
+export declare const isQueryLoading: (model: RemoteModel, identity: string) => boolean;
+/**
+ * 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
@@ -1386,6 +1640,15 @@ export declare const isLoading: (model: RemoteModel, entity: string, id: string,
  * can resubscribe rather than silently miss facts.
  */
 export declare const updateRemote: (model: RemoteModel, message: RemoteMessage) => RemoteModel;
+/** Whether this field's last read failed and nothing has settled it since. */
+export declare const isFieldFailed: (model: RemoteModel, entity: string, id: string, field: string) => boolean;
+/**
+ * The first failure among the fields `relation` reads of an entity, following
+ * each relation the store holds into its targets, as `assemble` does. A read
+ * that consults it shows `Failed` for a related entity's failure too, rather
+ * than waiting on a field nothing will fetch.
+ */
+export declare const failureOf: (model: RemoteModel, entity: string, id: string, relation: RelationRequirement) => RemoteError | undefined;
 /**
  * Writes a read result into the store, recording each field's applied window so
  * a later request with a different window refetches. A relation page requested
@@ -1502,6 +1765,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;
 /**
@@ -1685,6 +1967,92 @@ declare const Entity$1: {
   patch: <Name extends string, F extends Schema.Struct.Fields>(ref: EntityRef<Name, F>, patch: Partial<Schema.Struct.Encoded<F>>) => EntityPatch<Name, F>;
 };
 //#endregion
+//#region src/matching.d.ts
+/**
+ * An answer over the rows the client holds — never over the rows that exist.
+ *
+ * `complete` is the whole reason this is its own type rather than a `Page`. A
+ * `Page` carries `hasNext`/`hasPrevious`, which are facts the *server* stated
+ * about rows beyond the ones it delivered; a local answer has no such facts and
+ * cannot invent them. What it can say is whether the population it judged was
+ * all of it, which is decidable: a connection terminal at both ends is wholly
+ * held, and nothing was skipped for a missing field.
+ *
+ * An incomplete answer is not wrong — it is an answer about less than the
+ * caller may have meant, and the flag is what lets a view say "3 so far" rather
+ * than "3", or a caller decide to ask the server.
+ */
+export interface Matched<A> {
+  readonly items: ReadonlyArray<A>;
+  /** Whether every row the answer is about was judged. */
+  readonly complete: boolean;
+}
+/**
+ * What the rows the client holds had to say about a body.
+ *
+ * `skipped` is the honest half. A row missing a field the body reads cannot be
+ * judged — it is neither a match nor a non-match — and dropping it silently
+ * would turn "I could not tell" into "no". Naming it lets a caller decide:
+ * fetch the field, ask the server, or say the answer is partial.
+ */
+export interface Judged {
+  /** Keys of the rows that satisfy the body, in the order the body asks for. */
+  readonly matched: ReadonlyArray<EntityKey>;
+  /** Keys of rows held but missing a field the body reads, so not judged either way. */
+  readonly skipped: ReadonlyArray<EntityKey>;
+}
+export interface MatchingOptions {
+  /**
+   * Judge only these keys. Without it every row of the body's Entity in the
+   * store is a candidate, which is what a filter over a loaded list wants; with
+   * it, a caller narrows to a connection's own edges.
+   */
+  readonly among?: ReadonlyArray<EntityKey> | undefined;
+}
+/**
+ * The rows of `descriptor`'s Entity that the store holds and the body matches.
+ *
+ * The input is given **decoded**, as an application writes it, and encoded here
+ * through the descriptor's own `Input` codec. That is deliberate and is the
+ * whole reason this takes a descriptor rather than a bare body: a store holds
+ * wire values, so an input has to be in that space to be compared against them,
+ * and handing an interpreter a decoded value is a mistake **no runtime error
+ * catches** — the reference interpreter answers "no rows", which reads exactly
+ * like a correct answer. Doing it here means a caller cannot get it wrong.
+ *
+ * Literals in the body are deliberately *not* encoded. A literal written in
+ * domain terms is already broken against the server, which binds it to a column
+ * the same way; accepting it here would make the client quietly more permissive
+ * than the thing it has to agree with.
+ */
+export declare const matching: <Name extends string, Input>(store: EntityStore, descriptor: QueryDescriptor<Name, Input, unknown>, input: Input, options?: MatchingOptions) => Judged;
+/**
+ * Whether one row belongs to a query, as far as the client can tell.
+ *
+ * Three answers, and the third is the one that makes this usable. `'unknown'`
+ * is a row the store never fetched, or holds without a field the body reads —
+ * a caller that collapses it into `'no'` has turned "I could not tell" into an
+ * answer, which is the mistake this whole module is shaped against.
+ *
+ * **Membership is decidable where position is not.** Whether a row satisfies
+ * `eq`, `isNull` or `contains` needs no collation: equality on text is exact
+ * and `contains` folds ASCII, both stated in §6.0.1. *Where* a row sorts needs
+ * text collation, which is the backend's and deliberately outside the
+ * conformant subset — so this answers the half that is always answerable, and
+ * ordering stays the server's until a query can declare its collation.
+ */
+export type Belongs = 'yes' | 'no' | 'unknown';
+/**
+ * Takes the input **encoded**, because its one caller holds it that way: a
+ * connection identity carries the canonical encoded input, and making it decode
+ * only for this to encode again would be a round trip that can fail.
+ *
+ * A decoded-input sibling was written first and deleted: nothing called it. The
+ * asymmetry with `matching`, which takes a decoded input, is the shape of the
+ * two real callers rather than an oversight.
+ */
+export declare const belongsEncoded: <Name extends string, Input>(store: EntityStore, descriptor: QueryDescriptor<Name, Input, unknown>, encoded: Readonly<Record<string, unknown>>, key: EntityKey) => Belongs;
+//#endregion
 //#region src/inspect.d.ts
 /** A serializable summary of a RemoteModel for DevTools and diagnostics. */
 export interface RemoteInspection {
@@ -1699,6 +2067,19 @@ export interface RemoteInspection {
   readonly connections: ReadonlyArray<string>;
   readonly live: ReadonlyArray<string>;
   readonly gaps: ReadonlyArray<string>;
+  /**
+   * The `entity\0id\0field` marks of reads in flight, and a
+   * `\0connection\0identity` mark for each query 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>;
+  /**
+   * The reads that failed and are not yet settled: queries by connection
+   * identity, entity fields by `entity\0id\0field` mark, each with its error.
+   */
+  readonly failures: Failures;
   readonly mutations: {
     readonly pending: ReadonlyArray<string>;
     readonly failed: ReadonlyArray<string>;
@@ -1709,6 +2090,75 @@ export interface RemoteInspection {
 export declare const inspectRemote: (model: RemoteModel) => RemoteInspection;
 /** A pure, serializable view of one entity, or `undefined` if unknown. */
 export declare const inspectEntity: (model: RemoteModel, key: string) => RemoteInspection["entities"][number] | undefined;
+/**
+ * What one query read is, and what it currently is — data-query-DESIGN §29.1.
+ *
+ * Every member is gathered from something that already existed: the read was
+ * always this many pieces, and nothing had ever been asked to put them in one
+ * place. It is plain serializable data, so a DevTools panel, a log line and a
+ * test assert on the same value.
+ *
+ * Two members of §29.1's sketch are **not** here, and their absence is the
+ * finding rather than an omission:
+ *
+ * - **Surface.** A Projection does not know which Surface reads it, and often
+ *   several do — so it is not a property of the read, and `explain` cannot
+ *   recover it alone. Given the active Surfaces (the same record
+ *   `subscriptions` takes), it reports **every** Surface reading the connection
+ *   rather than guessing one, and omits the member entirely when it was not
+ *   given them.
+ * - **Executor.** The thing that answers a query is a `RemoteClient` Layer in
+ *   the runtime, not a value in the Model, and a pure read of the Model cannot
+ *   see it. That is the same boundary that makes this function pure and
+ *   replayable, so it is worth more than the line of text.
+ *
+ * And one that the design proposed and this does not want: *expectation*
+ * (required versus optional). §11 left it unbuilt for want of a consumer, and
+ * the explanation was the likeliest consumer. It turns out not to need it — a
+ * query's result is a connection, so the shape is a `Page`, decided by the
+ * definition rather than by the read. Nothing here has an opinion about whether
+ * an empty one is an error, because nothing here has to have one.
+ */
+export interface QueryExplanation {
+  /** The bound Remote domain that answers it. */
+  readonly domain: string;
+  /** The definition's name. */
+  readonly query: string;
+  /** The input as encoded, which is what the identity is built from. */
+  readonly input: unknown;
+  /** The connection identity: definition plus canonical input, excluding the window. */
+  readonly identity: string;
+  /** How much of the connection this read asks for. */
+  readonly window: QueryWindow;
+  /** What it reads of each item, as the slice asked of the server. */
+  readonly select: RelationRequirement;
+  /**
+   * What the query means, as readable text — `Query.show`, and so neither SQL
+   * nor whatever the backend compiled. Absent for a definition made with
+   * `Query.make`, whose meaning lives on the server that answers it.
+   */
+  readonly body?: string | undefined;
+  /** The fields, inputs and operations the body reads; absent with the body. */
+  readonly dependencies?: Dependencies | undefined;
+  /** What the read answers from this Model right now. */
+  readonly state: RemoteData<unknown>['_tag'];
+  /**
+   * The active Surfaces reading this connection at this Model, if the active
+   * record was supplied. Plural because several may, which is why a Projection
+   * cannot carry the answer itself.
+   */
+  readonly surfaces?: ReadonlyArray<string> | undefined;
+  /**
+   * Why each of those Surfaces is active, where it was placed with
+   * `Surface.when` — the Model path and the tag, without running anything. A
+   * Surface placed with `Surface.at` has no entry: a callback cannot be read.
+   */
+  readonly activation?: ReadonlyArray<{
+    readonly surface: string;
+    readonly path: readonly string[];
+    readonly tag: string;
+  }> | undefined;
+}
 //#endregion
 //#region src/plan.d.ts
 type Window = NonNullable<Requirement['windows']>[string];
@@ -1774,9 +2224,9 @@ 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 & {
+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;
@@ -1858,13 +2308,13 @@ export interface MutationStarted<AppModel> {
  */
 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: EntitySelection<Value, Name> & 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: EntitySelection<Value, Name> & 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
@@ -1877,8 +2327,55 @@ export interface RemoteDomain<AppModel, Store extends RemoteModel, Entities exte
   next<Name extends string, Input>(model: AppModel, projection: QueryProjection<AppModel, any, Name, Input>): QueryRef<Name, Input> | undefined;
   /** The `QueryRef` for the page before the loaded start, or `undefined`. */
   previous<Name extends string, Input>(model: AppModel, projection: QueryProjection<AppModel, any, Name, Input>): QueryRef<Name, Input> | undefined;
+  /**
+   * What a query read is and what it currently is, as one serializable value —
+   * data-query-DESIGN §29.1: the domain, the definition and its input, the
+   * connection identity, the window, the Selection, the body as readable text
+   * with what it depends on, and what the read answers from this Model.
+   *
+   * Pure, so a DevTools panel showing it shows something the Model can be
+   * replayed to.
+   *
+   * Given `surfaces` — the same active record `subscriptions` takes — it also
+   * reports which of them read this connection, and why each is active where
+   * that is a readable fact (`Surface.when`) rather than a callback
+   * (`Surface.at`). A Projection cannot carry this itself: several Surfaces may
+   * read one connection, so it is not a property of the read.
+   */
+  explain<Name extends string, Input>(model: AppModel, projection: QueryProjection<AppModel, any, Name, Input>, options?: {
+    readonly surfaces?: Readonly<Record<string, ActiveSurface<AppModel>>> | undefined;
+  }): QueryExplanation;
+  /**
+   * The rows of a loaded list that a body matches, decoded as the list decodes
+   * them — a filter that asks the server nothing.
+   *
+   * **It filters a list; it does not run a query.** That distinction is what
+   * keeps it honest. "Which rows match" would need to know that the list holds
+   * every row the body could match, which is predicate containment and is
+   * deliberately not built. "Which rows *of this list* match" is decidable from
+   * what is already here, and is what a search box over a loaded page actually
+   * wants.
+   *
+   * `complete` says whether the answer is about the whole list: every edge
+   * judged, and the connection terminal at both ends. An incomplete answer is
+   * not wrong — it is about less than the caller may have meant, which is why
+   * it is said rather than left for a view to assume.
+   *
+   * Creates no connection, so there is nothing new to retain and nothing new to
+   * fetch. The server stays authoritative for which rows exist.
+   */
+  filtered<Value, Name extends string, Input, Q extends QueryDescriptor<any, any, any>>(model: AppModel, over: QueryProjection<AppModel, Value, Name, Input>, by: Q & Registered<Q['name'], QueryName<Queries[number]>, 'Query'>, input: QueryInput<Q>): Matched<Value>;
   /** 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;
   /**
@@ -1894,6 +2391,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'
@@ -1948,6 +2469,8 @@ export type QueryOptions<Value, Entity extends string, Of extends string = Entit
 /** 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>>> {
   readonly ref: QueryRef<Name, Input>;
+  /** What it reads of each item, so a filter over the same list decodes identically. */
+  readonly selection: Selection<Value, string>;
 }
 /** The input of a query descriptor. */
 export type QueryInput<Q> = Q extends QueryDescriptor<any, infer Input, any> ? Input : never;
@@ -1989,7 +2512,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: {
@@ -2020,6 +2547,7 @@ export declare const Remote: {
         readonly _tag: Schema.String;
         readonly message: Schema.String;
       }>;
+      stream: Schema.optional<Schema.String>;
     };
     RefreshStarted: {
       requests: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
@@ -2028,6 +2556,9 @@ export declare const Remote: {
       requests: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
       refresh: Schema.optional<Schema.Number>;
     };
+    QueryStarted: {
+      connections: Schema.$Array<Schema.String>;
+    };
     RetentionChanged: {
       roots: Schema.Struct<{
         readonly requirements: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
@@ -2038,6 +2569,7 @@ export declare const Remote: {
       }>;
     };
     Hydrated: {
+      connections: Schema.optional<Schema.Unknown>;
       entities: Schema.Unknown;
       merge: Schema.Union<readonly [Schema.Literal<"replace">, Schema.Literal<"preserve-existing">]>;
     };
@@ -2065,6 +2597,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;
@@ -2151,6 +2690,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.
@@ -2171,6 +2716,9 @@ export declare const Remote: {
    * again with `next`/`previous`. The read entries restart, so a read or query
    * sent before the refresh is not applied after it.
    *
+   * It is also how a failed query is retried: a connection whose query failed
+   * is not run again on its own, so its read stays `Failed` until this asks.
+   *
    * 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
@@ -2283,8 +2831,10 @@ export declare const Remote: {
   observe: <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?: ObserveOptions) => EntryWithoutKeepAlive<AppModel, Message, ReadDependencies, RemoteClient>;
   /**
    * A Foldkit Subscription entry that consumes the live stream for a Surface's
-   * requirements, emitting a `LiveReceived` per event and a `ReadFailed` when
-   * the stream breaks (including `ResumeUnavailable`). The resume cursor is read
+   * requirements, emitting a `LiveReceived` per event and a `ReadFailed`
+   * carrying its `stream` when the stream breaks (including
+   * `ResumeUnavailable`). That records a gap on the stream rather than a failed
+   * read, since nothing was being read. The resume cursor is read
    * 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, {