foldkit-remote 0.8.0 → 0.9.0

package/dist/index.d.mts

@@ -7,8 +7,7 @@ import { ActiveSurface, Contract, Invalid, Metadata, ModelRef, Projection, Surfa
 import { Rpc, RpcGroup } from "effect/unstable/rpc";
 import { KeyValueStore } from "effect/unstable/persistence";
 import * as Update from "foldkit/update";
-//#region ../metadata/dist/index.d.mts
-//#region src/index.d.ts
+//#region ../metadata/src/index.d.ts
 /** Marks a `Metadata` value. Its entries are private to this module. */
 declare const MetadataTypeId: unique symbol;
 type MetadataTypeId = typeof MetadataTypeId;
@@ -60,7 +59,6 @@ declare const Metadata$1: {
   summarize: (metadata: Metadata$1) => readonly MetadataSummary[];
 };
 //#endregion
-//#endregion
 //#region src/connection.d.ts
 export interface EdgeRef {
   readonly entity: string;
@@ -228,6 +226,8 @@ export interface EntityWrite {
   readonly values: Readonly<Record<string, unknown>>;
   /** The canonical window each written relation field was fetched with. */
   readonly windows?: Readonly<Record<string, string>> | undefined;
+  /** When this write dates the entity, instead of the batch's `now`. */
+  readonly updatedAt?: number | undefined;
 }
 /**
  * Merges known values into many entities, copying the store once. Every
@@ -320,15 +320,23 @@ export interface Reconciled {
   readonly store: EntityStore;
   readonly state: MutationState;
 }
+/** What a settled mutation wrote, as `MutationSucceeded` carries it. */
+export interface MutationAnswer {
+  readonly entities: ReadonlyArray<NormalizedPatch>;
+  /** Entities the mutation deleted; each is tombstoned. */
+  readonly deleted?: ReadonlyArray<{
+    readonly entity: string;
+    readonly id: string;
+  }> | undefined;
+  /** Injected clock reading of the answer, which dates what it writes. */
+  readonly now: number;
+}
 /**
  * Applies a mutation result once and marks the request settled. A second call
  * 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>, deleted?: ReadonlyArray<{
-  readonly entity: string;
-  readonly id: string;
-}>) => Reconciled;
+export declare const reconcileMutation: (store: EntityStore, state: MutationState, requestId: string, answer: MutationAnswer) => Reconciled;
 /** A mutation an application declares: its name and input/output codecs. */
 export interface MutationDescriptor<Name extends string, Input, Output> {
   readonly name: Name;
@@ -609,7 +617,12 @@ export declare const addLayer: (optimistic: OptimisticState, layer: EntityLayer)
 export declare const removeLayer: (optimistic: OptimisticState, id: string) => OptimisticState;
 export declare const addOverlay: (optimistic: OptimisticState, overlay: ConnectionOverlay) => OptimisticState;
 export declare const removeOverlay: (optimistic: OptimisticState, id: string) => OptimisticState;
-/** Base store with every layer applied in order. Later layers win. */
+/**
+ * Base store with every layer applied in order. Later layers win. A patch is
+ * not news from the server, so it keeps the date of the value under it; an
+ * entity only a request holds (a temporary id) is not the server's to age, and
+ * is dated `Infinity`, so freshness never plans or times it.
+ */
 export declare const visibleStore: (base: EntityStore, optimistic: OptimisticState) => EntityStore;
 /**
  * A fresh page is newer than any settled overlay it covers: an edge the page
@@ -623,10 +636,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>, deleted?: ReadonlyArray<{
-  readonly entity: string;
-  readonly id: string;
-}>) => {
+export declare const settleSuccess: (base: EntityStore, optimistic: OptimisticState, state: MutationState, requestId: string, answer: MutationAnswer & {
+  /** Connection changes the server confirmed; they replace the request's own. */
+  readonly connections?: ReadonlyArray<ConnectionChange> | undefined;
+}) => {
   readonly store: EntityStore;
   readonly state: MutationState;
   readonly optimistic: OptimisticState;
@@ -691,11 +704,6 @@ export type LiveOutcome = 'applied' | 'duplicate' | 'gap';
  * spurious gap.
  */
 export declare const classifyLive: (state: LiveState, cursor: LiveCursor) => LiveOutcome;
-/**
- * A subscriber is woken only if the event changed a field it selects. A
- * change to an unselected field is skipped entirely.
- */
-export declare const shouldWake: (changed: ReadonlyArray<string>, selected: ReadonlyArray<string>) => boolean;
 export interface EntityApplied {
   readonly state: LiveState;
   readonly store: EntityStore;
@@ -1135,6 +1143,12 @@ export declare const QueryRequest: Schema.Struct<{
     readonly after: Schema.optional<Schema.String>;
     readonly before: Schema.optional<Schema.String>;
   }>;
+  /**
+   * What to read of each item, as the relation slice a read asks the server
+   * for. Absent for a query run without one: the response carries only edges,
+   * and the client's read entry fetches fields in a second round trip.
+   */
+  readonly select: Schema.optional<Schema.Codec<RelationRequirement, RelationRequirement, never, never>>;
 }>;
 export declare const QueryEdge: Schema.Struct<{
   readonly entity: Schema.String;
@@ -1163,6 +1177,21 @@ export declare const QueryResult: Schema.Struct<{
   }>, Schema.Struct<{
     readonly _tag: Schema.Literal<"Unknown">;
   }>]>;
+  /**
+   * The selected fields of the page's items, in the same shape a read batch
+   * returns. Absent from a server that predates payload planning: the client
+   * reads it as empty and fetches fields as before.
+   */
+  readonly entities: Schema.optional<Schema.$Array<Schema.Struct<{
+    readonly entity: Schema.String;
+    readonly id: Schema.String;
+    readonly values: Schema.$Record<Schema.String, Schema.Unknown>;
+  }>>>;
+  readonly settled: Schema.optional<Schema.$Array<Schema.Struct<{
+    readonly entity: Schema.String;
+    readonly id: Schema.String;
+    readonly fields: Schema.$Array<Schema.String>;
+  }>>>;
 }>;
 export declare const QueryRpc: Rpc.Rpc<"FoldkitRemoteQuery", Schema.Struct<{
   readonly query: Schema.String;
@@ -1173,6 +1202,12 @@ export declare const QueryRpc: Rpc.Rpc<"FoldkitRemoteQuery", Schema.Struct<{
     readonly after: Schema.optional<Schema.String>;
     readonly before: Schema.optional<Schema.String>;
   }>;
+  /**
+   * What to read of each item, as the relation slice a read asks the server
+   * for. Absent for a query run without one: the response carries only edges,
+   * and the client's read entry fetches fields in a second round trip.
+   */
+  readonly select: Schema.optional<Schema.Codec<RelationRequirement, RelationRequirement, never, never>>;
 }>, Schema.Struct<{
   readonly edges: Schema.$Array<Schema.Struct<{
     readonly entity: Schema.String;
@@ -1195,6 +1230,21 @@ export declare const QueryRpc: Rpc.Rpc<"FoldkitRemoteQuery", Schema.Struct<{
   }>, Schema.Struct<{
     readonly _tag: Schema.Literal<"Unknown">;
   }>]>;
+  /**
+   * The selected fields of the page's items, in the same shape a read batch
+   * returns. Absent from a server that predates payload planning: the client
+   * reads it as empty and fetches fields as before.
+   */
+  readonly entities: Schema.optional<Schema.$Array<Schema.Struct<{
+    readonly entity: Schema.String;
+    readonly id: Schema.String;
+    readonly values: Schema.$Record<Schema.String, Schema.Unknown>;
+  }>>>;
+  readonly settled: Schema.optional<Schema.$Array<Schema.Struct<{
+    readonly entity: Schema.String;
+    readonly id: Schema.String;
+    readonly fields: Schema.$Array<Schema.String>;
+  }>>>;
 }>, typeof RemoteQueryError, never, never>;
 export declare const RemoteRpc: RpcGroup.RpcGroup<Rpc.Rpc<"FoldkitRemoteRead", Schema.Struct<{
   readonly version: Schema.Number;
@@ -1295,6 +1345,12 @@ export declare const RemoteRpc: RpcGroup.RpcGroup<Rpc.Rpc<"FoldkitRemoteRead", S
     readonly after: Schema.optional<Schema.String>;
     readonly before: Schema.optional<Schema.String>;
   }>;
+  /**
+   * What to read of each item, as the relation slice a read asks the server
+   * for. Absent for a query run without one: the response carries only edges,
+   * and the client's read entry fetches fields in a second round trip.
+   */
+  readonly select: Schema.optional<Schema.Codec<RelationRequirement, RelationRequirement, never, never>>;
 }>, Schema.Struct<{
   readonly edges: Schema.$Array<Schema.Struct<{
     readonly entity: Schema.String;
@@ -1317,6 +1373,21 @@ export declare const RemoteRpc: RpcGroup.RpcGroup<Rpc.Rpc<"FoldkitRemoteRead", S
   }>, Schema.Struct<{
     readonly _tag: Schema.Literal<"Unknown">;
   }>]>;
+  /**
+   * The selected fields of the page's items, in the same shape a read batch
+   * returns. Absent from a server that predates payload planning: the client
+   * reads it as empty and fetches fields as before.
+   */
+  readonly entities: Schema.optional<Schema.$Array<Schema.Struct<{
+    readonly entity: Schema.String;
+    readonly id: Schema.String;
+    readonly values: Schema.$Record<Schema.String, Schema.Unknown>;
+  }>>>;
+  readonly settled: Schema.optional<Schema.$Array<Schema.Struct<{
+    readonly entity: Schema.String;
+    readonly id: Schema.String;
+    readonly fields: Schema.$Array<Schema.String>;
+  }>>>;
 }>, typeof RemoteQueryError, never, never>>;
 //#endregion
 //#region src/model.d.ts
@@ -1329,6 +1400,12 @@ export interface RemoteModel {
   readonly entities: EntityStore;
   /** Normalized ordered connections, keyed by connection identity. */
   readonly connections: Readonly<Record<string, Connection>>;
+  /**
+   * How many rows `Data.more` has grown a read's window to, by
+   * `windowGrowthKey`. A read shows at most its window, so this is what "load
+   * more" changes; it lives here because a list holds no state of its own.
+   */
+  readonly grown: Readonly<Record<string, number>>;
   /** Optimistic entity layers and connection overlays over the base store. */
   readonly optimistic: OptimisticState;
   /** Live cursor and boundary state, keyed by the subscription's stream key. */
@@ -1480,6 +1557,8 @@ export type RemoteMessage = {
     readonly entity: string;
     readonly id: string;
   }> | undefined;
+  /** Injected clock reading of the answer: how fresh the written entities are. */
+  readonly now: number;
 } | {
   readonly _tag: 'MutationFailed';
   readonly requestId: string;
@@ -1497,6 +1576,12 @@ export type RemoteMessage = {
 } | {
   readonly _tag: 'OverlayLifted';
   readonly id: string;
+} |
+/** `Data.more`: a read's window, by `windowGrowthKey`, now shows `size` rows. */
+{
+  readonly _tag: 'WindowGrown';
+  readonly window: string;
+  readonly size: number;
 } | {
   readonly _tag: 'LiveReceived';
   readonly stream: string;
@@ -1512,6 +1597,26 @@ export type RemoteMessage = {
   readonly page: Segment;
   /** The page answers the connection's refresh, so the merge also clears `stale`. */
   readonly refreshes?: boolean | undefined;
+  /**
+   * The slice the query asked for, so the payload's entities write like a
+   * read: one request per matching edge. Absent for a page from a server
+   * that predates payload planning, which carries edges only.
+   */
+  readonly select?: RelationRequirement | undefined;
+  /** The selected fields of the page's items, as a read batch returns them. */
+  readonly entities?: ReadonlyArray<{
+    readonly entity: string;
+    readonly id: string;
+    readonly values: Record<string, unknown>;
+  }> | undefined;
+  /** Fields asked for that the server settled without a value. */
+  readonly settled?: ReadonlyArray<{
+    readonly entity: string;
+    readonly id: string;
+    readonly fields: ReadonlyArray<string>;
+  }> | undefined;
+  /** Injected clock reading of the answer, dating what the payload writes. */
+  readonly now?: number | undefined;
 } | {
   readonly _tag: 'ConnectionInvalidated';
   readonly connection: string;
@@ -1605,6 +1710,7 @@ export declare const remoteMessageCases: {
       readonly entity: Schema.String;
       readonly id: Schema.String;
     }>>>;
+    now: Schema.Number;
   };
   MutationFailed: {
     requestId: Schema.String;
@@ -1620,6 +1726,10 @@ export declare const remoteMessageCases: {
   OverlayLifted: {
     id: Schema.String;
   };
+  WindowGrown: {
+    window: Schema.String;
+    size: Schema.Number;
+  };
   LiveReceived: {
     stream: Schema.String;
     event: Schema.Unknown;
@@ -1633,6 +1743,18 @@ export declare const remoteMessageCases: {
     connection: Schema.String;
     page: Schema.Unknown;
     refreshes: Schema.optional<Schema.Boolean>;
+    select: Schema.optional<Schema.Codec<RelationRequirement, RelationRequirement, never, never>>;
+    entities: Schema.optional<Schema.$Array<Schema.Struct<{
+      readonly entity: Schema.String;
+      readonly id: Schema.String;
+      readonly values: Schema.$Record<Schema.String, Schema.Unknown>;
+    }>>>;
+    settled: Schema.optional<Schema.$Array<Schema.Struct<{
+      readonly entity: Schema.String;
+      readonly id: Schema.String;
+      readonly fields: Schema.$Array<Schema.String>;
+    }>>>;
+    now: Schema.optional<Schema.Number>;
   };
   ConnectionInvalidated: {
     connection: Schema.String;
@@ -1667,6 +1789,14 @@ export declare const isRemoteMessage: <M extends {
   readonly _tag: RemoteMessageTag;
 }>;
 export declare const remoteMessageSchema: Schema.Schema<RemoteMessage>;
+/** The key a grown window is kept under: its connection and the window first asked for. */
+export declare const windowGrowthKey: (identity: string, window: string) => string;
+/**
+ * Whether only overlays show this entity: the server has told the store
+ * nothing of it and no request's layer writes it, so nothing will fetch what an
+ * overlay leaves out.
+ */
+export declare const onlyOverlaid: (model: RemoteModel, entity: string, id: string) => boolean;
 /** Whether a query for this connection is in flight. */
 export declare const isQueryLoading: (model: RemoteModel, identity: string) => boolean;
 /**
@@ -1697,7 +1827,12 @@ export declare const isLoading: (model: RemoteModel, entity: string, id: string,
 /**
  * The pure reducer all four producers share. A live event that arrives ahead of
  * its cursor is a gap: it is not applied, and the stream is recorded so the host
- * can resubscribe rather than silently miss facts.
+ * can resubscribe rather than silently miss facts. When every field a Message
+ * touches keeps its identity, `model` itself is returned, so the application's
+ * root keeps its identity and Foldkit does not render. The common no-ops do (a
+ * duplicate live event, a repeated `ReadStarted`); a repeated failure, or a
+ * `preserve-existing` restore of entities already held, still makes an equal
+ * copy.
  */
 export declare const updateRemote: (model: RemoteModel, message: RemoteMessage) => RemoteModel;
 /** Whether this field's last read failed and nothing has settled it since. */
@@ -2307,10 +2442,13 @@ export interface Deadline {
 /**
  * The earliest moment a value `requirements` read, following the relations the
  * store holds as `plan` does, goes stale under `freshness`, with the
- * requirements of the entities that go stale then. Nothing when no value is
- * both present and still fresh: what is already expired or stale is planned,
- * not awaited, which is what keeps a timer from firing on what it already
- * fired on.
+ * requirements of the entities that go stale then. A field the server settled
+ * without a value ages with its entity too, since `plan` asks for it again once
+ * the entity expires. Nothing when no such field is still fresh: what is
+ * already expired or stale is planned, not awaited, which is what keeps a
+ * timer from firing on what it already fired on. It is the next moment the
+ * plan can change with the clock alone, which the read entry relies on to
+ * reuse its plan until then.
  */
 export declare const deadlineOf: (store: EntityStore, requirements: readonly Requirement[], freshness: PlanFreshness) => Deadline | undefined;
 export declare const plan: (store: EntityStore, requirements: readonly Requirement[], options?: PlanOptions) => ReadonlyArray<Requirement>;
@@ -2421,6 +2559,8 @@ export interface DomainMutateOptions {
     readonly requestId: string;
     readonly tempId: string;
   }) => ReadonlyArray<OptimisticOperation>) | undefined;
+  /** The clock `MutationSucceeded` stamps the answer with; default `Date.now`, read at each use. */
+  readonly now?: (() => number) | undefined;
 }
 /** A Foldkit Subscription entry of the Remote domain, emitting its Messages through `RemoteClient`. */
 export type RemoteEntry<AppModel, Dependencies> = EntryWithoutKeepAlive<AppModel, RemoteMessage, Dependencies, RemoteClient>;
@@ -2429,9 +2569,15 @@ export type RemoteEntry<AppModel, Dependencies> = EntryWithoutKeepAlive<AppModel
  * and a live entry per key (the live one idles when nothing is read live), and
  * `retain`.
  */
-export type SubscriptionEntries<AppModel, Active> = { readonly [K in keyof Active & (string | number) as `${K}.read` | `${K}.live`]: RemoteEntry<AppModel, any>; } & {
-  readonly retain: RemoteEntry<AppModel, any>;
+export type SubscriptionEntries<AppModel, Active, Message = RemoteMessage> = { readonly [K in keyof Active & (string | number) as `${K}.read`]: EntryWithoutKeepAlive<AppModel, Message, ReadDependencies, RemoteClient>; } & { readonly [K in keyof Active & (string | number) as `${K}.live`]: EntryWithoutKeepAlive<AppModel, Message, LiveDependencies, RemoteClient>; } & {
+  readonly retain: EntryWithoutKeepAlive<AppModel, Message, RetentionRoots, never>;
 };
+/** The dependencies of a live entry: what it subscribes to, and where a restart resumes. */
+export interface LiveDependencies {
+  readonly requirements: ReadonlyArray<Requirement>;
+  readonly cursor: LiveCursor;
+  readonly floor: number;
+}
 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>;
@@ -2466,10 +2612,13 @@ export interface RemoteDomain<AppModel, Store extends RemoteModel, Entities exte
    * onto the connection read through the same projection.
    */
   query<Q extends QueryDescriptor<any, any, any>, Value, Entity extends string>(query: Q & Registered<Q['name'], QueryName<Queries[number]>, 'Query'>, input: QueryInput<Q>, options: QueryOptions<Value, Entity, QueryEntity<Q>>): QueryProjection<AppModel, Value, Q['name'], QueryInput<Q>>;
-  /** The `QueryRef` for the page after the loaded end (same page size), or `undefined` when there is none or its cursor is unknown. */
-  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;
+  /**
+   * "Load more": the Model with the read's window grown by one page, so it
+   * shows that many more rows; the read entry fetches what the connection
+   * lacks. None when the read shows everything there is (or is not a sized
+   * window). Called from `update`.
+   */
+  more<Name extends string, Input>(model: AppModel, projection: QueryProjection<AppModel, any, Name, Input>): Option.Option<AppModel>;
   /**
    * 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
@@ -2520,13 +2669,13 @@ export interface RemoteDomain<AppModel, Store extends RemoteModel, Entities exte
    * 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`.
+   * showing an id again replaces what it showed. Called from `update`. A read
+   * of an entity only overlays show, lacking a field it selects, is `Failed`
+   * (`Overlaid`): nothing will fetch that field.
    */
   overlay(model: AppModel, id: string, optimistic: ReadonlyArray<OptimisticOperation>): AppModel;
   /** Lifts what `overlay` showed under this id. Lifting nothing returns the same Model. */
@@ -2535,17 +2684,29 @@ export interface RemoteDomain<AppModel, Store extends RemoteModel, Entities exte
   refresh(model: AppModel, target: Projection<AppModel, unknown> | Surface<AppModel, any, any, void>): AppModel;
   /** `Remote.forget`: the Model with every server-derived fact gone, for a change of principal. */
   forget(model: AppModel): AppModel;
+  /**
+   * A read of this domain as an active Surface, for `subscriptions` and
+   * `wiring`: `projectionOf` is what it reads for a Model, none while it
+   * reads nothing. It belongs to the domain's application, and lists no
+   * Messages: it is a requirement, not a sender. A domain made from a raw
+   * optic names no application, so this throws for one.
+   */
+  active<Value>(name: string, projectionOf: (model: AppModel) => Option.Option<Projection<AppModel, Value>>): ActiveSurface<AppModel>;
   /**
    * The Foldkit Subscription entries for the active Surfaces, keyed for
    * `Subscription.make`: a read entry per Surface (`Remote.observe`), a live
    * entry per Surface that reads through `live` (`Remote.live`), and one
-   * retain entry with every active Surface as a root (`Remote.retain`). A
+   * retain entry (`Remote.retain`). Retention is the domain's: the retain
+   * entry of every call roots the active Surfaces of every call, so reads
+   * split over calls (one per policy) do not collect each other's data. A
    * Surface's params are a function of the Model (`Surface.at`), so what is
    * fetched, subscribed, and retained follows the Model.
    */
   subscriptions<const Active extends Readonly<Record<string, ActiveSurface<AppModel> | Surface<AppModel, any, any, void>>>>(active: Active, options?: SubscriptionsOptions): SubscriptionEntries<AppModel, Active>;
   /** `Remote.plan`: the requirements the store does not satisfy. */
   plan<Value>(model: AppModel, projection: Projection<AppModel, Value>, options?: PlanOptions): ReadonlyArray<Requirement>;
+  /** `Remote.meta`: when what a projection shows was last received, and whether it is stale or loading. */
+  meta<Value>(model: AppModel, projection: Projection<AppModel, Value>): ReadMeta;
   /** `Remote.storeOf`: the visible store, base under the pending optimistic layers. */
   storeOf(model: AppModel): EntityStore;
   /**
@@ -2578,6 +2739,17 @@ export interface RemoteDomain<AppModel, Store extends RemoteModel, Entities exte
    * items included). For SSR, route or hover prefetch, and tests.
    */
   prefetch<Value>(model: AppModel, projection: Projection<AppModel, Value>, options?: ObserveOptions): Effect.Effect<AppModel, RemoteReadError | RemoteProtocolError | RemoteQueryError, RemoteClient>;
+  /**
+   * The Model with everything the active Surfaces read, for a render that
+   * fetches nothing (SSR, a prerender). Each pass prefetches every Surface
+   * that plans a read, over the Model the one before it left, so a Surface
+   * active only once another's read has arrived is read in the next pass (or
+   * the same one, when it comes later in `active`). It stops at the first
+   * pass that plans nothing, and fails with `RemoteUnsatisfied` when
+   * `options.passes` run out first. Reads are cache-first: a field already
+   * held is not asked again.
+   */
+  satisfy(model: AppModel, active: Readonly<Record<string, ActiveSurface<AppModel> | Surface<AppModel, any, any, void>>>, options?: SatisfyOptions): Effect.Effect<AppModel, RemoteReadError | RemoteProtocolError | RemoteQueryError | RemoteUnsatisfied, RemoteClient>;
   /**
    * Starts a registered mutation from `update`: applies `MutationStarted` (with
    * the optimistic operations) to the Model and returns the Command that runs
@@ -2618,12 +2790,10 @@ export type FoldedMutationStarted<AppModel, ParentMessage> = Omit<MutationStarte
  */
 export interface RemoteFold<AppModel, ParentMessage, Domain extends RemoteDomain<AppModel, any, any, any, any>> {
   (model: AppModel, message: RemoteMessage | RemoteMessageInput): Update.Return<AppModel, ParentMessage>;
-  /** `Data.fetch`, lifted. */
-  readonly fetch: (ref: QueryRef<string, unknown>) => Command<ParentMessage, never, RemoteClient>;
   /** `Data.mutate`, its Command lifted. */
   readonly mutate: (...args: Parameters<Domain['mutate']>) => FoldedMutationStarted<AppModel, ParentMessage>;
   /** `Data.subscriptions`, every entry lifted to the wrapper Message. */
-  readonly subscriptions: <const Active extends Readonly<Record<string, ActiveSurface<AppModel> | Surface<AppModel, any, any, void>>>>(active: Active, options?: SubscriptionsOptions) => { readonly [K in keyof SubscriptionEntries<AppModel, Active>]: EntryWithoutKeepAlive<AppModel, ParentMessage, any, RemoteClient>; };
+  readonly subscriptions: <const Active extends Readonly<Record<string, ActiveSurface<AppModel> | Surface<AppModel, any, any, void>>>>(active: Active, options?: SubscriptionsOptions) => SubscriptionEntries<AppModel, Active, ParentMessage>;
 }
 /** The application Model a bound domain is over. */
 export type ModelOfDomain<Domain> = Domain extends RemoteDomain<infer AppModel, any, any, any, any> ? AppModel : never;
@@ -2657,9 +2827,23 @@ export interface QueryProjection<AppModel, Value, Name extends string, Input> ex
 export type QueryInput<Q> = Q extends QueryDescriptor<any, infer Input, any> ? Input : never;
 /** The entity a query's connection is over. */
 export type QueryEntity<Q> = Q extends QueryDescriptor<any, any, ConnectionSpec<infer Entity>> ? Entity : string;
+/**
+ * When what a projection shows was last received, and whether it is stale
+ * or loading. See `Remote.meta`.
+ */
+export interface ReadMeta {
+  /** The newest server write among what is shown; none received reads `undefined`. */
+  readonly updatedAt: number | undefined;
+  /** Any shown field or connection is marked stale. */
+  readonly stale: boolean;
+  /** Any shown field or connection is in flight. */
+  readonly loading: boolean;
+}
 export interface MutateOptions {
   /** What the request changes before the server answers; released when it settles. */
   readonly optimistic?: ReadonlyArray<OptimisticOperation> | undefined;
+  /** The clock `MutationSucceeded` stamps the answer with; default `Date.now`, read at each use. */
+  readonly now?: (() => number) | undefined;
 }
 export interface RetainOptions {
   /** The query connections the application shows, by `QueryRef` or identity. */
@@ -2671,11 +2855,29 @@ export interface RetainOptions {
 export interface ObserveOptions {
   /** Default `RemotePolicy.cacheFirst`. */
   readonly policy?: RemotePolicy | undefined;
-  /** The clock a refreshing policy reads; default `Date.now`. */
+  /** The clock a refreshing policy reads; default `Date.now`, read at each use. */
   readonly now?: (() => number) | undefined;
 }
+/** How `Data.satisfy` reads: how many passes it may take, and the clock. */
+export interface SatisfyOptions {
+  /** At most this many passes over the Surfaces; default 8. */
+  readonly passes?: number | undefined;
+  /** The clock the reads are stamped with; default `Date.now`, read at each use. */
+  readonly now?: (() => number) | undefined;
+}
+declare const RemoteUnsatisfied_base: Schema.Class<RemoteUnsatisfied, Schema.TaggedStruct<"RemoteUnsatisfied", {
+  readonly surfaces: Schema.$Array<Schema.String>;
+  readonly passes: Schema.Number;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * `Data.satisfy` reached its bound with Surfaces still reading, such as a
+ * chain whose every read reveals one more. It names them, so a page that
+ * would have rendered them loading fails instead. (A read the server leaves
+ * unanswered settles as missing and ends the loop.)
+ */
+export declare class RemoteUnsatisfied extends RemoteUnsatisfied_base {}
 export interface LiveOptions {
-  /** The clock `LiveReceived` stamps events with; default `Date.now`. */
+  /** The clock `LiveReceived` stamps events with; default `Date.now`, read at each use. */
   readonly now?: (() => number) | undefined;
 }
 /** A query the read entry runs, as its dependencies carry it: plain data Foldkit compares. */
@@ -2783,6 +2985,7 @@ export declare const Remote: {
         readonly entity: Schema.String;
         readonly id: Schema.String;
       }>>>;
+      now: Schema.Number;
     };
     MutationFailed: {
       requestId: Schema.String;
@@ -2798,6 +3001,10 @@ export declare const Remote: {
     OverlayLifted: {
       id: Schema.String;
     };
+    WindowGrown: {
+      window: Schema.String;
+      size: Schema.Number;
+    };
     LiveReceived: {
       stream: Schema.String;
       event: Schema.Unknown;
@@ -2811,6 +3018,18 @@ export declare const Remote: {
       connection: Schema.String;
       page: Schema.Unknown;
       refreshes: Schema.optional<Schema.Boolean>;
+      select: Schema.optional<Schema.Codec<RelationRequirement, RelationRequirement, never, never>>;
+      entities: Schema.optional<Schema.$Array<Schema.Struct<{
+        readonly entity: Schema.String;
+        readonly id: Schema.String;
+        readonly values: Schema.$Record<Schema.String, Schema.Unknown>;
+      }>>>;
+      settled: Schema.optional<Schema.$Array<Schema.Struct<{
+        readonly entity: Schema.String;
+        readonly id: Schema.String;
+        readonly fields: Schema.$Array<Schema.String>;
+      }>>>;
+      now: Schema.optional<Schema.Number>;
     };
     ConnectionInvalidated: {
       connection: Schema.String;
@@ -2903,6 +3122,7 @@ export declare const Remote: {
         readonly entity: Schema.String;
         readonly id: Schema.String;
       }>>>;
+      now: Schema.Number;
     };
     MutationFailed: {
       requestId: Schema.String;
@@ -2918,6 +3138,10 @@ export declare const Remote: {
     OverlayLifted: {
       id: Schema.String;
     };
+    WindowGrown: {
+      window: Schema.String;
+      size: Schema.Number;
+    };
     LiveReceived: {
       stream: Schema.String;
       event: Schema.Unknown;
@@ -2931,6 +3155,18 @@ export declare const Remote: {
       connection: Schema.String;
       page: Schema.Unknown;
       refreshes: Schema.optional<Schema.Boolean>;
+      select: Schema.optional<Schema.Codec<RelationRequirement, RelationRequirement, never, never>>;
+      entities: Schema.optional<Schema.$Array<Schema.Struct<{
+        readonly entity: Schema.String;
+        readonly id: Schema.String;
+        readonly values: Schema.$Record<Schema.String, Schema.Unknown>;
+      }>>>;
+      settled: Schema.optional<Schema.$Array<Schema.Struct<{
+        readonly entity: Schema.String;
+        readonly id: Schema.String;
+        readonly fields: Schema.$Array<Schema.String>;
+      }>>>;
+      now: Schema.optional<Schema.Number>;
     };
     ConnectionInvalidated: {
       connection: Schema.String;
@@ -3030,6 +3266,17 @@ export declare const Remote: {
    * 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>, given: EntitySelection<Value, Name> & Registered<Name, Names, "Entity">) => (id: string) => Projection<AppModel, RemoteData<Value>>;
+  /**
+   * When what a projection shows was last received, and whether it is stale
+   * or loading. Pure, so a view can show "updated 5s ago" without I/O.
+   *
+   * `updatedAt` is the newest server write among what is shown, as the
+   * store dates it; `undefined` when nothing shown was received (nothing
+   * loaded, or only an optimistic preview). `stale` is any shown field or
+   * connection marked stale; `loading` is any of them in flight. Optimistic
+   * previews do not date: showing only one reads `updatedAt: undefined`.
+   */
+  meta: <AppModel, Store extends RemoteModel, Value>(bound: BoundRemote<AppModel, Store>, model: AppModel, projection: Projection<AppModel, Value>) => ReadMeta;
   /**
    * The pure plan for a projection against a Model: the requirements its
    * remote store does not satisfy, under `options` (freshness, force). A
@@ -3121,8 +3368,10 @@ export declare const Remote: {
   /**
    * Runs a `Query` through `RemoteClient`, encoding its input from the ref.
    * Pair the result with `Remote.queryMessage` to merge the page into the Model.
+   * With `select`, the server also returns the selected fields of the page's
+   * items, so one response populates both the connection and the store.
    */
-  query: <Name extends string, Input>(ref: QueryRef<Name, Input>) => Effect.Effect<{
+  query: <Name extends string, Input>(ref: QueryRef<Name, Input>, select?: RelationRequirement | undefined) => Effect.Effect<{
     readonly edges: readonly {
       readonly entity: string;
       readonly id: string;
@@ -3144,9 +3393,21 @@ export declare const Remote: {
     } | {
       readonly _tag: "Unknown";
     };
+    readonly entities?: readonly {
+      readonly entity: string;
+      readonly id: string;
+      readonly values: {
+        readonly [x: string]: unknown;
+      };
+    }[] | undefined;
+    readonly settled?: readonly {
+      readonly entity: string;
+      readonly id: string;
+      readonly fields: readonly string[];
+    }[] | undefined;
   }, RemoteQueryError, RemoteClient>;
   /** The `RemoteMessage` that merges a query page into its connection. */
-  queryMessage: <Name extends string, Input>(ref: QueryRef<Name, Input>, result: Schema.Schema.Type<typeof QueryResult>) => RemoteMessage;
+  queryMessage: <Name extends string, Input>(ref: QueryRef<Name, Input>, result: Schema.Schema.Type<typeof QueryResult>, select?: RelationRequirement | undefined, now?: number | undefined) => RemoteMessage;
   /**
    * The edges a connection shows: its server-known region with pending and
    * confirmed overlays placed around it, minus removed edges and edges whose
@@ -3205,11 +3466,7 @@ export declare const Remote: {
    * 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, {
-    readonly requirements: ReadonlyArray<Requirement>;
-    readonly cursor: LiveCursor;
-    readonly floor: number;
-  }, RemoteClient>;
+  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, LiveDependencies, RemoteClient>;
 };
 //#endregion
 export { Entity$1 as Entity, type RemoteResumePart };