foldkit-remote 0.5.0 → 0.6.0

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import { Context, Duration, Effect, Layer, Option, Schema, Stream } from "effect";
 import * as Domain from "foldkit-entity";
-import { AnyEntity, AnyQuery, InputExpr, Query as Query$1 } 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";
@@ -381,6 +381,16 @@ export interface QueryDescriptor<Name extends string, Input, Result> {
  * 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;
 /**
@@ -448,6 +458,8 @@ export declare const Query: {
   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
@@ -651,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>>;
 }
@@ -665,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.
@@ -683,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. */
@@ -731,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
@@ -745,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
@@ -1261,7 +1310,34 @@ export interface RemoteModel {
    * it, and a refresh of one field leaves every other entry's read alone.
    */
   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`
@@ -1286,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. */
 {
@@ -1299,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';
@@ -1308,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. */
@@ -1365,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;
@@ -1400,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>>;
@@ -1408,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>>;
@@ -1418,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">]>;
   };
@@ -1499,6 +1607,8 @@ 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
@@ -1530,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
@@ -1848,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 {
@@ -1863,12 +2068,18 @@ export interface RemoteInspection {
   readonly live: ReadonlyArray<string>;
   readonly gaps: ReadonlyArray<string>;
   /**
-   * The `entity\0id\0field` marks of reads in flight. This is what "Remote is
+   * 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>;
@@ -1879,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];
@@ -2047,6 +2327,44 @@ 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>;
   /**
@@ -2151,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;
@@ -2227,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>>;
@@ -2235,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>>;
@@ -2245,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">]>;
     };
@@ -2391,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
@@ -2503,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, {