foldkit-remote 0.1.0 → 0.3.0

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { Context, Duration, Effect, Layer, Option, Schema, Stream } from "effect";
-import { ActiveSurface, ConnectionRequirement, Contract, Invalid, ModelRef, Projection, RelationRequirement, RelationRequirement as RelationRequirement$1, Requirement, Requirement as Requirement$1, Surface } from "foldkit-surface";
+import { ActiveSurface, Contract, Invalid, Metadata, ModelRef, Projection, Surface } from "foldkit-surface";
 import { Rpc, RpcGroup } from "effect/unstable/rpc";
 import { KeyValueStore } from "effect/unstable/persistence";
 import { Command } from "foldkit/command";
@@ -171,6 +171,130 @@ export declare const Mutation: {
   }) => MutationDescriptor<Name, TypeOf<Input>, TypeOf<Output>>;
 };
 //#endregion
+//#region src/query.d.ts
+export type LiveInsertion = 'visible' | 'boundary' | 'invalidate' | 'ignore';
+export interface LivePolicy {
+  readonly prepend?: LiveInsertion;
+  readonly append?: LiveInsertion;
+}
+export interface ConnectionSpec<Entity extends string = string> {
+  readonly entity: Entity;
+  readonly edgeKey?: Schema.Schema<unknown>;
+  readonly live?: LivePolicy;
+}
+export interface QueryWindow {
+  readonly first?: number | undefined;
+  readonly last?: number | undefined;
+  readonly after?: Cursor | undefined;
+  readonly before?: Cursor | undefined;
+}
+export interface QueryRef<Name extends string, Input> {
+  readonly query: Name;
+  readonly input: Input;
+  /** The input codec, so a `QueryRef` can encode itself without its descriptor. */
+  readonly Input: Schema.Codec<Input>;
+  readonly window: QueryWindow;
+  /** Connection identity: descriptor + canonical input, excluding the window. */
+  readonly identity: string;
+}
+export interface QueryDescriptor<Name extends string, Input, Result> {
+  readonly name: Name;
+  readonly Input: Schema.Codec<Input>;
+  readonly Result: Result;
+  readonly ref: (input: Input) => QueryRef<Name, Input>;
+}
+/** Stable stringify: object keys sorted, undefined-valued keys dropped, so equal inputs encode equally. */
+export declare const stableStringify: (value: unknown) => string;
+/**
+ * `Result: Project` (or anything with the entity's `name`, as `Query.connection`
+ * takes) means a connection over it; a `ConnectionSpec` names its `entity`
+ * instead and is the result as given.
+ */
+export type ResultOf<Result> = Result extends {
+  readonly name: infer Entity extends string;
+} ? ConnectionSpec<Entity> : Result;
+export declare const Query: {
+  /** Declares the entity and options a query's result is a connection over. */
+  connection: <Entity extends string>(entity: {
+    readonly name: Entity;
+  }, options?: {
+    readonly edgeKey?: Schema.Schema<unknown>;
+    readonly live?: LivePolicy;
+  }) => ConnectionSpec<Entity>;
+  /**
+   * Declares a query. `Input` is a codec or the fields of the `Schema.Struct` it
+   * would be; `Result` is a `Query.connection(...)`, or the entity the result is
+   * a connection over.
+   */
+  make: <const Name extends string, Input extends SchemaOrFields, Result>(name: Name, config: {
+    readonly Input: Input;
+    readonly Result: Result;
+  }) => QueryDescriptor<Name, TypeOf<Input>, ResultOf<Result>>;
+  first: (count: number) => <R extends QueryRef<string, unknown>>(ref: R) => R;
+  last: (count: number) => <R extends QueryRef<string, unknown>>(ref: R) => R;
+  after: (cursor: Cursor) => <R extends QueryRef<string, unknown>>(ref: R) => R;
+  before: (cursor: Cursor) => <R extends QueryRef<string, unknown>>(ref: R) => R;
+};
+//#endregion
+//#region src/requirement.d.ts
+/**
+ * The slice required of an entity. `windows` carries a pagination window per
+ * relation field, and `relations` the slice required of each relation's
+ * target, so one requirement describes a whole selection graph.
+ */
+export interface RelationRequirement {
+  readonly entity: string;
+  readonly fields: readonly string[];
+  readonly windows?: Readonly<Record<string, QueryWindow>> | undefined;
+  readonly relations?: Readonly<Record<string, RelationRequirement>> | undefined;
+}
+export interface Requirement extends RelationRequirement {
+  readonly id: string;
+  /** The projection also subscribes to changes of this entity (`Data.live`). */
+  readonly live?: boolean | undefined;
+}
+/**
+ * A query connection a projection reads: the page it first asks for and the
+ * slice it selects of each item. `identity` is the connection's (query plus
+ * canonical input, excluding the window).
+ */
+export interface ConnectionRequirement {
+  readonly identity: string;
+  readonly window: QueryWindow;
+  readonly select: RelationRequirement;
+}
+/**
+ * Merges connection requirements for the same connection and window into one,
+ * unioning what they select of each item; the first keeps its other properties.
+ */
+declare function mergeConnections(connections: readonly ConnectionRequirement[]): readonly ConnectionRequirement[];
+/** Unions two relation slices for the same target: fields, windows, and nested relations. */
+declare function mergeRelation(current: RelationRequirement, next: RelationRequirement): RelationRequirement;
+/** Unions requirements for the same entity + id, dropping duplicate fields. */
+declare function mergeRequirements(requirements: readonly Requirement[]): readonly Requirement[];
+/**
+ * Requirement helpers, for the packages that plan and serve requirements.
+ * `merge` unions same-entity+id requirements; `mergeRelation` unions two
+ * slices of one target (fields, windows, nested relations).
+ */
+export declare const Requirement: {
+  merge: typeof mergeRequirements;
+  mergeRelation: typeof mergeRelation;
+  mergeConnections: typeof mergeConnections;
+};
+/** Remote's entity requirements on a Projection, unioned per entity and id as nodes compose. */
+export declare const RemoteRequirements: import("foldkit-surface").MetadataKey<Requirement>;
+/** Remote's query connections on a Projection, unioned per connection and window. */
+export declare const RemoteConnections: import("foldkit-surface").MetadataKey<ConnectionRequirement>;
+/** The entity requirements a Projection carries. */
+export declare const requirementsOf: (projection: {
+  readonly metadata: Metadata;
+}) => ReadonlyArray<Requirement>;
+/** The query connections a Projection carries. */
+export declare const connectionsOf: (projection: {
+  readonly metadata: Metadata;
+}) => ReadonlyArray<ConnectionRequirement>;
+//#endregion
 //#region src/optimistic.d.ts
 export interface EntityLayer {
   readonly id: string;
@@ -275,71 +399,6 @@ export declare const settleFailure: (optimistic: OptimisticState, requestId: str
  */
 export declare const visibleItems: (connection: Connection, connectionId: string, overlays: ReadonlyArray<ConnectionOverlay>, store?: EntityStore) => ReadonlyArray<Edge>;
 //#endregion
-//#region src/query.d.ts
-export type LiveInsertion = 'visible' | 'boundary' | 'invalidate' | 'ignore';
-export interface LivePolicy {
-  readonly prepend?: LiveInsertion;
-  readonly append?: LiveInsertion;
-}
-export interface ConnectionSpec<Entity extends string = string> {
-  readonly entity: Entity;
-  readonly edgeKey?: Schema.Schema<unknown>;
-  readonly live?: LivePolicy;
-}
-export interface QueryWindow {
-  readonly first?: number | undefined;
-  readonly last?: number | undefined;
-  readonly after?: Cursor | undefined;
-  readonly before?: Cursor | undefined;
-}
-export interface QueryRef<Name extends string, Input> {
-  readonly query: Name;
-  readonly input: Input;
-  /** The input codec, so a `QueryRef` can encode itself without its descriptor. */
-  readonly Input: Schema.Codec<Input>;
-  readonly window: QueryWindow;
-  /** Connection identity: descriptor + canonical input, excluding the window. */
-  readonly identity: string;
-}
-export interface QueryDescriptor<Name extends string, Input, Result> {
-  readonly name: Name;
-  readonly Input: Schema.Codec<Input>;
-  readonly Result: Result;
-  readonly ref: (input: Input) => QueryRef<Name, Input>;
-}
-/** Stable stringify: object keys sorted, undefined-valued keys dropped, so equal inputs encode equally. */
-export declare const stableStringify: (value: unknown) => string;
-/**
- * `Result: Project` (or anything with the entity's `name`, as `Query.connection`
- * takes) means a connection over it; a `ConnectionSpec` names its `entity`
- * instead and is the result as given.
- */
-export type ResultOf<Result> = Result extends {
-  readonly name: infer Entity extends string;
-} ? ConnectionSpec<Entity> : Result;
-export declare const Query: {
-  /** Declares the entity and options a query's result is a connection over. */
-  connection: <Entity extends string>(entity: {
-    readonly name: Entity;
-  }, options?: {
-    readonly edgeKey?: Schema.Schema<unknown>;
-    readonly live?: LivePolicy;
-  }) => ConnectionSpec<Entity>;
-  /**
-   * Declares a query. `Input` is a codec or the fields of the `Schema.Struct` it
-   * would be; `Result` is a `Query.connection(...)`, or the entity the result is
-   * a connection over.
-   */
-  make: <const Name extends string, Input extends SchemaOrFields, Result>(name: Name, config: {
-    readonly Input: Input;
-    readonly Result: Result;
-  }) => QueryDescriptor<Name, TypeOf<Input>, ResultOf<Result>>;
-  first: (count: number) => <R extends QueryRef<string, unknown>>(ref: R) => R;
-  last: (count: number) => <R extends QueryRef<string, unknown>>(ref: R) => R;
-  after: (cursor: Cursor) => <R extends QueryRef<string, unknown>>(ref: R) => R;
-  before: (cursor: Cursor) => <R extends QueryRef<string, unknown>>(ref: R) => R;
-};
-//#endregion
 //#region src/live.d.ts
 export type LiveCursor = number;
 export type LiveEvent = {
@@ -427,10 +486,10 @@ export declare const liveHasNext: (connection: Connection, state: LiveState, con
 /** A connection to keep: its identity, and what a page of it selects of each item, if a projection reads it. */
 export interface ConnectionRoot {
   readonly identity: string;
-  readonly select?: RelationRequirement$1 | undefined;
+  readonly select?: RelationRequirement | undefined;
 }
 export interface RetentionRoots {
-  readonly requirements: ReadonlyArray<Requirement$1>;
+  readonly requirements: ReadonlyArray<Requirement>;
   /** Connections (`QueryRef.identity`) to keep, with their edges' targets and what `select` reaches through them. */
   readonly connections: ReadonlyArray<ConnectionRoot>;
 }
@@ -468,9 +527,17 @@ export interface SnapshotOptions {
 }
 /** How a snapshot meets a store that already has entries. */
 export type MergePolicy = 'replace' | 'preserve-existing';
+/**
+ * The snapshot text, or `undefined` when it would exceed `maxBytes`. Only the
+ * entity store goes in; pass `model.entities`, never the whole `RemoteModel`.
+ */
+declare function dehydrate(store: EntityStore, options?: SnapshotOptions & {
+  readonly maxBytes?: undefined;
+}): string;
+declare function dehydrate(store: EntityStore, options?: SnapshotOptions): string | undefined;
 export declare const RemotePersistence: {
   /** The snapshot text, or `undefined` when it would exceed `maxBytes`. */
-  dehydrate: (store: EntityStore, options?: SnapshotOptions) => string | undefined;
+  dehydrate: typeof dehydrate;
   /** The store a snapshot text holds, or `undefined` when it is refused. */
   hydrate: (raw: string | undefined | null, options?: SnapshotOptions) => EntityStore | undefined;
   /** A snapshot brought into a store by policy. */
@@ -531,11 +598,11 @@ export declare const WindowSchema: Schema.Struct<{
 export declare const MAX_FIELDS_PER_REQUEST = 256;
 /** A selection may not nest relations deeper than this; the wire refuses more. */
 export declare const MAX_RELATION_DEPTH = 8;
-export declare const RelationRequest: Schema.Codec<RelationRequirement$1, RelationRequirement$1, never, never>;
-export declare const ReadRequest: Schema.Codec<Requirement$1, Requirement$1>;
+export declare const RelationRequest: Schema.Codec<RelationRequirement, RelationRequirement, never, never>;
+export declare const ReadRequest: Schema.Codec<Requirement, Requirement>;
 export declare const ReadBatch: Schema.Struct<{
   readonly version: Schema.Number;
-  readonly requests: Schema.$Array<Schema.Codec<Requirement$1, Requirement$1, never, never>>;
+  readonly requests: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
 }>;
 export declare const NormalizedEntity: Schema.Struct<{
   readonly entity: Schema.String;
@@ -608,7 +675,7 @@ export declare const MutationResult: Schema.Struct<{
 }>;
 export declare const LiveRequirement: Schema.Struct<{
   readonly version: Schema.Number;
-  readonly requirements: Schema.$Array<Schema.Codec<Requirement$1, Requirement$1, never, never>>;
+  readonly requirements: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
   /** Resume cursor; events at or before it are duplicates. */
   readonly after: Schema.Number;
 }>;
@@ -654,7 +721,7 @@ export declare const LiveChange: Schema.Union<readonly [Schema.Struct<{
 }>]>;
 export declare const Read: Rpc.Rpc<"FoldkitRemoteRead", Schema.Struct<{
   readonly version: Schema.Number;
-  readonly requests: Schema.$Array<Schema.Codec<Requirement$1, Requirement$1, never, never>>;
+  readonly requests: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
 }>, Schema.Struct<{
   readonly entities: Schema.$Array<Schema.Struct<{
     readonly entity: Schema.String;
@@ -696,7 +763,7 @@ export declare const Mutate: Rpc.Rpc<"FoldkitRemoteMutate", Schema.Struct<{
 }>, typeof RemoteMutationError, never, never>;
 export declare const Live: Rpc.Rpc<"FoldkitRemoteLive", Schema.Struct<{
   readonly version: Schema.Number;
-  readonly requirements: Schema.$Array<Schema.Codec<Requirement$1, Requirement$1, never, never>>;
+  readonly requirements: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
   /** Resume cursor; events at or before it are duplicates. */
   readonly after: Schema.Number;
 }>, import("effect/unstable/rpc/RpcSchema").Stream<Schema.Union<readonly [Schema.Struct<{
@@ -819,7 +886,7 @@ export declare const QueryRpc: Rpc.Rpc<"FoldkitRemoteQuery", Schema.Struct<{
 }>, typeof RemoteQueryError, never, never>;
 export declare const RemoteRpc: RpcGroup.RpcGroup<Rpc.Rpc<"FoldkitRemoteRead", Schema.Struct<{
   readonly version: Schema.Number;
-  readonly requests: Schema.$Array<Schema.Codec<Requirement$1, Requirement$1, never, never>>;
+  readonly requests: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
 }>, Schema.Struct<{
   readonly entities: Schema.$Array<Schema.Struct<{
     readonly entity: Schema.String;
@@ -859,7 +926,7 @@ export declare const RemoteRpc: RpcGroup.RpcGroup<Rpc.Rpc<"FoldkitRemoteRead", S
   }>]>>>;
 }>, typeof RemoteMutationError, never, never> | Rpc.Rpc<"FoldkitRemoteLive", Schema.Struct<{
   readonly version: Schema.Number;
-  readonly requirements: Schema.$Array<Schema.Codec<Requirement$1, Requirement$1, never, never>>;
+  readonly requirements: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
   /** Resume cursor; events at or before it are duplicates. */
   readonly after: Schema.Number;
 }>, import("effect/unstable/rpc/RpcSchema").Stream<Schema.Union<readonly [Schema.Struct<{
@@ -956,7 +1023,7 @@ export declare const remoteErrorSchema: Schema.Struct<{
   readonly _tag: Schema.String;
   readonly message: Schema.String;
 }>;
-export declare const remoteDataSchema: <A>(value: Schema.Schema<A>) => Schema.Schema<RemoteData<A>>;
+export declare const remoteDataSchema: <A>(value: Schema.Schema<A>) => Schema.Codec<RemoteData<A>, unknown>;
 export declare const RemoteData: {
   /**
    * The `RemoteData` schema for a value schema. Exposed so a `RemoteData` can
@@ -977,8 +1044,8 @@ export declare const RemoteData: {
 //#endregion
 //#region src/model.d.ts
 /**
- * The normalized cache as a Foldkit Submodel. `Remote.make` returns a schema and
- * an `update` for this shape; `Remote.update` reconciles every producer.
+ * The normalized cache as a Foldkit Submodel. `Remote.define` returns a schema
+ * and an `update` for this shape; `updateRemote` reconciles every producer.
  */
 export interface RemoteModel {
   /** Entity values, presence, staleness, tombstones, and applied windows. */
@@ -993,24 +1060,47 @@ export interface RemoteModel {
   readonly mutations: MutationState;
   /** Streams whose live cursor fell behind; the caller should resync or refetch. */
   readonly gaps: ReadonlySet<string>;
+  /**
+   * The `entity\0id\0field` marks a read is currently fetching. A field absent
+   * from the store reads as `Loading` while its mark is here and `Initial`
+   * otherwise, which is what separates "being fetched" from "nothing is
+   * fetching this".
+   */
+  readonly loading: ReadonlySet<string>;
+  /**
+   * `Remote.refresh` generations. The read entries restart when `requested`
+   * moves, so a read sent before a refresh cannot land after it; `started` is
+   * the latest generation a read began under.
+   */
+  readonly refresh: {
+    readonly requested: number;
+    readonly started: number;
+  };
 }
 export declare const initialRemoteModel: RemoteModel;
-export declare const remoteModelSchema: () => Schema.Schema<RemoteModel>;
-/** The submodel's Messages; each reduces to `RemoteModel` through `Remote.update`. */
+export declare const remoteModelSchema: () => Schema.Codec<RemoteModel, unknown>;
+/** The submodel's Messages; each reduces to `RemoteModel` through `updateRemote`. */
 export type RemoteMessage = {
   readonly _tag: 'ReadReceived';
-  readonly requests: readonly Requirement$1[];
+  readonly requests: readonly Requirement[];
   readonly result: Schema.Schema.Type<typeof ReadBatchResult>;
   readonly now: number;
 } | {
   readonly _tag: 'ReadFailed';
-  readonly requests: readonly Requirement$1[];
+  readonly requests: readonly Requirement[];
   readonly error: RemoteError;
 } |
 /** A refetch of present fields began; they read as `Refreshing` until it lands. */
 {
   readonly _tag: 'RefreshStarted';
-  readonly requests: readonly Requirement$1[];
+  readonly requests: readonly Requirement[];
+} |
+/** A read began; the fields it asks for that the store lacks read as `Loading`. */
+{
+  readonly _tag: 'ReadStarted';
+  readonly requests: readonly Requirement[];
+  /** The refresh generation the read was planned under. */
+  readonly refresh?: number | undefined;
 } |
 /** The active Surfaces' roots changed; everything they do not reach is collected. */
 {
@@ -1067,10 +1157,10 @@ export type RemoteMessage = {
   readonly error: RemoteError;
 };
 export declare const retentionRootsSchema: Schema.Struct<{
-  readonly requirements: Schema.$Array<Schema.Codec<Requirement$1, Requirement$1, never, never>>;
+  readonly requirements: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
   readonly connections: Schema.$Array<Schema.Struct<{
     readonly identity: Schema.String;
-    readonly select: Schema.optional<Schema.Codec<import("foldkit-surface").RelationRequirement, import("foldkit-surface").RelationRequirement, never, never>>;
+    readonly select: Schema.optional<Schema.Codec<RelationRequirement, RelationRequirement, never, never>>;
   }>>;
 }>;
 /**
@@ -1079,7 +1169,7 @@ export declare const retentionRootsSchema: Schema.Struct<{
  */
 export declare const remoteMessageCases: {
   ReadReceived: {
-    requests: Schema.$Array<Schema.Codec<Requirement$1, Requirement$1, never, never>>;
+    requests: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
     result: Schema.Struct<{
       readonly entities: Schema.$Array<Schema.Struct<{
         readonly entity: Schema.String;
@@ -1090,21 +1180,25 @@ export declare const remoteMessageCases: {
     now: Schema.Number;
   };
   ReadFailed: {
-    requests: Schema.$Array<Schema.Codec<Requirement$1, Requirement$1, never, never>>;
+    requests: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
     error: Schema.Struct<{
       readonly _tag: Schema.String;
       readonly message: Schema.String;
     }>;
   };
   RefreshStarted: {
-    requests: Schema.$Array<Schema.Codec<Requirement$1, Requirement$1, never, never>>;
+    requests: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
+  };
+  ReadStarted: {
+    requests: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
+    refresh: Schema.optional<Schema.Number>;
   };
   RetentionChanged: {
     roots: Schema.Struct<{
-      readonly requirements: Schema.$Array<Schema.Codec<Requirement$1, Requirement$1, never, never>>;
+      readonly requirements: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
       readonly connections: Schema.$Array<Schema.Struct<{
         readonly identity: Schema.String;
-        readonly select: Schema.optional<Schema.Codec<import("foldkit-surface").RelationRequirement, import("foldkit-surface").RelationRequirement, never, never>>;
+        readonly select: Schema.optional<Schema.Codec<RelationRequirement, RelationRequirement, never, never>>;
       }>>;
     }>;
   };
@@ -1179,6 +1273,12 @@ export declare const isRemoteMessage: <M extends {
   readonly _tag: RemoteMessageTag;
 }>;
 export declare const remoteMessageSchema: Schema.Schema<RemoteMessage>;
+/**
+ * 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
+ * `Initial`.
+ */
+export declare const isLoading: (model: RemoteModel, entity: string, id: string, fields: ReadonlyArray<string>) => boolean;
 /**
  * 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
@@ -1192,7 +1292,7 @@ export declare const updateRemote: (model: RemoteModel, message: RemoteMessage)
  * accumulates rather than replaces. Every read path should use this rather than
  * reducing `writeEntity` by hand.
  */
-export declare const writeRead: (store: EntityStore, requests: ReadonlyArray<Requirement$1>, result: Schema.Schema.Type<typeof ReadBatchResult>, now?: number) => EntityStore;
+export declare const writeRead: (store: EntityStore, requests: ReadonlyArray<Requirement>, result: Schema.Schema.Type<typeof ReadBatchResult>, now?: number) => EntityStore;
 //#endregion
 //#region src/coalesce.d.ts
 type Batch = Schema.Schema.Type<typeof ReadBatch>;
@@ -1210,7 +1310,7 @@ export interface CoalesceOptions {
   readonly window?: Duration.Input | undefined;
 }
 /** A stable key for a requirement, so an equal requirement in flight is joined. */
-export declare const requirementKey: (requirement: Requirement$1) => string;
+export declare const requirementKey: (requirement: Requirement) => string;
 /**
  * Wraps a raw query so that an identical query in flight (same query, input,
  * and window) is joined rather than run again; distinct queries run
@@ -1230,7 +1330,7 @@ declare const RemoteClient_base: Context.ServiceClass<RemoteClient, "foldkit-rem
   readonly query: (request: Schema.Schema.Type<typeof QueryRequest>) => Effect.Effect<Schema.Schema.Type<typeof QueryResult>, RemoteQueryError>;
   readonly mutate: (request: Schema.Schema.Type<typeof MutationRequest>) => Effect.Effect<Schema.Schema.Type<typeof MutationResult>, RemoteMutationError>;
   readonly live: (request: {
-    readonly requirements: ReadonlyArray<Requirement$1>;
+    readonly requirements: ReadonlyArray<Requirement>;
     readonly after: LiveCursor;
   }) => Stream.Stream<LiveEvent, RemoteLiveError | RemoteProtocolError>;
 }>;
@@ -1305,7 +1405,7 @@ export declare const refParts: (encoded: string) => RefParts;
  */
 export declare const refsIn: (value: unknown) => ReadonlyArray<RefParts>;
 /** The refs in a relation value that name the relation's target entity, and no other. */
-export declare const targetsOf: (value: unknown, relation: RelationRequirement$1) => ReadonlyArray<RefParts>;
+export declare const targetsOf: (value: unknown, relation: RelationRequirement) => ReadonlyArray<RefParts>;
 export declare const isRefPage: (value: unknown) => value is RefPageValue;
 /**
  * The relation shape an entity field schema declares: a ref (`one`), a nullable
@@ -1334,7 +1434,7 @@ export interface Selection<Value, Name extends string = string, Shape extends 'e
   /** Pagination windows for nested relation fields, keyed by field name. */
   readonly connections?: Readonly<Record<string, QueryWindow>> | undefined;
   /** The slice required of each nested relation's target, keyed by field name. */
-  readonly relations?: Readonly<Record<string, RelationRequirement$1>> | undefined;
+  readonly relations?: Readonly<Record<string, RelationRequirement>> | undefined;
   /** Present when this selection is itself a paginated relation. */
   readonly window?: QueryWindow | undefined;
   /** Phantom: see `Shape`. */
@@ -1356,7 +1456,7 @@ type NestedValue<Field, Sel> = Sel extends Selection<infer V, string, 'connectio
 export type SelectionValue<F extends Schema.Struct.Fields, Sel> = Simplify<{ readonly [K in keyof Sel & keyof F]: Sel[K] extends true ? Schema.Schema.Type<F[K]> : NestedValue<Schema.Schema.Type<F[K]>, Sel[K]>; }>;
 export declare const pageSchema: (item: AnySchema) => AnySchema;
 /** The requirement a nested selection contributes for its relation's target. */
-export declare const relationOf: (selection: Selection<unknown>) => RelationRequirement$1;
+export declare const relationOf: (selection: Selection<unknown>) => RelationRequirement;
 export declare const Selection: {
   /**
    * The fields to read of `entity`. A nested `Selection` on a relation field
@@ -1383,7 +1483,7 @@ interface Assembled {
  * not present yet. A tombstoned target reads as `null` (or is dropped from a
  * list), so the Selection's codec decides whether that is a failure.
  */
-export declare const assemble: (store: EntityStore, key: string, requirement: RelationRequirement$1) => Assembled | undefined;
+export declare const assemble: (store: EntityStore, key: string, requirement: RelationRequirement) => Assembled | undefined;
 //#endregion
 //#region src/entity.d.ts
 export type AnySchema = Schema.Schema<unknown>;
@@ -1483,7 +1583,7 @@ export declare const inspectRemote: (model: RemoteModel) => RemoteInspection;
 export declare const inspectEntity: (model: RemoteModel, key: string) => RemoteInspection["entities"][number] | undefined;
 //#endregion
 //#region src/plan.d.ts
-type Window = NonNullable<Requirement$1['windows']>[string];
+type Window = NonNullable<Requirement['windows']>[string];
 /** A stable key for a window, so two equal windows compare equal. */
 export declare const windowKey: (window: Window) => string;
 export interface PlanFreshness {
@@ -1496,7 +1596,7 @@ export interface PlanOptions {
   /** Plan every requested field, present or not, tombstoned or not. */
   readonly force?: boolean | undefined;
 }
-export declare const plan: (store: EntityStore, requirements: readonly Requirement$1[], options?: PlanOptions) => ReadonlyArray<Requirement$1>;
+export declare const plan: (store: EntityStore, requirements: readonly Requirement[], options?: PlanOptions) => ReadonlyArray<Requirement>;
 //#endregion
 //#region src/policy.d.ts
 export type RemotePolicy =
@@ -1555,7 +1655,7 @@ export interface RemoteDescriptor<Entities extends readonly EntityDescriptor<any
   readonly entities: Entities;
   readonly queries: Queries;
   readonly mutations: Mutations;
-  readonly Model: Schema.Schema<RemoteModel>;
+  readonly Model: Schema.Codec<RemoteModel, unknown>;
   readonly initial: RemoteModel;
   readonly Message: Schema.Schema<RemoteMessage>;
   readonly update: (model: RemoteModel, message: RemoteMessage) => RemoteModel;
@@ -1592,6 +1692,14 @@ export interface DomainMutateOptions {
 }
 /** A Foldkit Subscription entry of the Remote domain, emitting its Messages through `RemoteClient`. */
 export type RemoteEntry<AppModel, Dependencies> = EntryWithoutKeepAlive<AppModel, RemoteMessage, Dependencies, RemoteClient>;
+/**
+ * The entries `RemoteDomain.subscriptions` returns for an active record: a read
+ * and a live entry per key (the live one idles when nothing is read live), and
+ * `retain`.
+ */
+export type SubscriptionEntries<AppModel, Active> = { readonly [K in keyof Active & (string | number) as `${K}.read` | `${K}.live`]: RemoteEntry<AppModel, any>; } & {
+  readonly retain: RemoteEntry<AppModel, any>;
+};
 export interface SubscriptionsOptions extends ObserveOptions, LiveOptions, RetainOptions {}
 /** What `RemoteDomain.mutate` hands `update`: the Model with the request started, and the Command that settles it. */
 export interface MutationStarted<AppModel> {
@@ -1630,6 +1738,8 @@ export interface RemoteDomain<AppModel, Store extends RemoteModel, Entities exte
   previous<Name extends string, Input>(model: AppModel, projection: QueryProjection<AppModel, any, Name, Input>): QueryRef<Name, Input> | undefined;
   /** A Command that runs the query and yields the `ConnectionMerged` (or `QueryFailed`) that reduces it: "load more". */
   fetch(ref: QueryRef<string, unknown>): Command<RemoteMessage, never, RemoteClient>;
+  /** `Remote.refresh`: marks what a projection or a Surface requires as due, for its read entry to refetch. */
+  refresh(model: AppModel, target: Projection<AppModel, unknown> | Surface<AppModel, any, any, void>): AppModel;
   /**
    * The Foldkit Subscription entries for the active Surfaces, keyed for
    * `Subscription.make`: a read entry per Surface (`Remote.observe`), a live
@@ -1638,9 +1748,9 @@ export interface RemoteDomain<AppModel, Store extends RemoteModel, Entities exte
    * Surface's params are a function of the Model (`Surface.at`), so what is
    * fetched, subscribed, and retained follows the Model.
    */
-  subscriptions(active: Readonly<Record<string, ActiveSurface<AppModel> | Surface<AppModel, any, any, void>>>, options?: SubscriptionsOptions): Readonly<Record<string, RemoteEntry<AppModel, any>>>;
+  subscriptions<const Active extends Readonly<Record<string, ActiveSurface<AppModel> | Surface<AppModel, any, any, void>>>>(active: Active, options?: SubscriptionsOptions): SubscriptionEntries<AppModel, Active>;
   /** `Remote.plan`: the requirements the store does not satisfy. */
-  plan<Value>(model: AppModel, projection: Projection<AppModel, Value>, options?: PlanOptions): ReadonlyArray<Requirement$1>;
+  plan<Value>(model: AppModel, projection: Projection<AppModel, Value>, options?: PlanOptions): ReadonlyArray<Requirement>;
   /** `Remote.storeOf`: the visible store, base under the pending optimistic layers. */
   storeOf(model: AppModel): EntityStore;
   /**
@@ -1656,7 +1766,7 @@ export interface RemoteDomain<AppModel, Store extends RemoteModel, Entities exte
    * mutation sequence unless `options.requestId` is given.
    */
   mutate<M extends MutationDescriptor<any, any, any>>(model: AppModel, mutation: M & Registered<M['name'], MutationName<Mutations[number]>, 'Mutation'>, input: MutationInput<M>, options?: DomainMutateOptions): MutationStarted<AppModel>;
-  /** `Remote.update` on the bound slice: reduces one of Remote's Messages, as `RemoteMessage` or as the application's union constructs it. */
+  /** `updateRemote` on the bound slice: reduces one of Remote's Messages, as `RemoteMessage` or as the application's union constructs it. */
   reduce(model: AppModel, message: RemoteMessage | RemoteMessageInput): AppModel;
   /** `Remote.inspect` of the bound slice. */
   inspect(model: AppModel): RemoteInspection;
@@ -1723,12 +1833,14 @@ declare const PlannedQuery: Schema.Struct<{
 }>;
 /** The dependencies of the read entry: the entity fields to read and the queries to run. */
 export interface ReadDependencies {
-  readonly requirements: ReadonlyArray<Requirement$1>;
+  readonly requirements: ReadonlyArray<Requirement>;
   readonly queries: ReadonlyArray<Schema.Schema.Type<typeof PlannedQuery>>;
+  /** The Model's requested refresh generation: a refresh restarts the entry. */
+  readonly refresh: number;
 }
 export declare const Remote: {
   /** The submodel's schema, the same for every domain; embed it in the application Model. */
-  Model: Schema.Schema<RemoteModel>;
+  Model: Schema.Codec<RemoteModel, unknown, never, never>;
   /** The submodel's initial value. */
   initial: RemoteModel;
   /**
@@ -1738,7 +1850,7 @@ export declare const Remote: {
    */
   messages: {
     ReadReceived: {
-      requests: Schema.$Array<Schema.Codec<Requirement$1, Requirement$1, never, never>>;
+      requests: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
       result: Schema.Struct<{
         readonly entities: Schema.$Array<Schema.Struct<{
           readonly entity: Schema.String;
@@ -1749,18 +1861,22 @@ export declare const Remote: {
       now: Schema.Number;
     };
     ReadFailed: {
-      requests: Schema.$Array<Schema.Codec<Requirement$1, Requirement$1, never, never>>;
+      requests: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
       error: Schema.Struct<{
         readonly _tag: Schema.String;
         readonly message: Schema.String;
       }>;
     };
     RefreshStarted: {
-      requests: Schema.$Array<Schema.Codec<Requirement$1, Requirement$1, never, never>>;
+      requests: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
+    };
+    ReadStarted: {
+      requests: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
+      refresh: Schema.optional<Schema.Number>;
     };
     RetentionChanged: {
       roots: Schema.Struct<{
-        readonly requirements: Schema.$Array<Schema.Codec<Requirement$1, Requirement$1, never, never>>;
+        readonly requirements: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
         readonly connections: Schema.$Array<Schema.Struct<{
           readonly identity: Schema.String;
           readonly select: Schema.optional<Schema.Codec<RelationRequirement, RelationRequirement, never, never>>;
@@ -1865,7 +1981,7 @@ export declare const Remote: {
    * remote store does not satisfy, under `options` (freshness, force). A
    * Surface's projection is `surface.projection(params)`.
    */
-  plan: <AppModel, Store extends RemoteModel, Value>(bound: BoundRemote<AppModel, Store>, model: AppModel, projection: Projection<AppModel, Value>, options?: PlanOptions) => ReadonlyArray<Requirement$1>;
+  plan: <AppModel, Store extends RemoteModel, Value>(bound: BoundRemote<AppModel, Store>, model: AppModel, projection: Projection<AppModel, Value>, options?: PlanOptions) => ReadonlyArray<Requirement>;
   /**
    * The queries a projection needs run before its connections read: those the
    * Model does not hold, or holds stale (every one under `force`).
@@ -1884,11 +2000,30 @@ export declare const Remote: {
    * is the clock it reads, so the planner itself stays pure and time-injected.
    */
   prefetch: <AppModel, Store extends RemoteModel, Value>(bound: BoundRemote<AppModel, Store, string>, model: AppModel, projection: Projection<AppModel, Value>, options?: ObserveOptions | undefined) => Effect.Effect<Readonly<Record<string, EntityEntry>>, RemoteReadError | RemoteProtocolError, RemoteClient>;
+  /**
+   * Marks what a projection, or a Surface without params, requires as due again.
+   * Called from `update`: every selected field the store holds reads `Refreshing`,
+   * and every loaded query connection is invalidated. Nothing is fetched here.
+   * The read entries `Data.subscriptions` derives refetch it, because a stale
+   * field or connection is planned again under every policy, so a refresh never
+   * sends a request beside the entry already observing the same data.
+   *
+   * A refreshed connection's page replaces its pages, so items the server removed
+   * or reordered follow it; pages loaded past the first are dropped and paged
+   * again with `next`/`previous`. The read entries restart, so a read or query
+   * sent before the refresh is not applied after it.
+   *
+   * The projection must be observed, which it is while it is on screen. Live
+   * subscriptions are left as they are. For data nothing observes (SSR, tests),
+   * use `Remote.prefetch` with `RemotePolicy.networkOnly`. Refreshing what is
+   * already being refreshed returns the same Model.
+   */
+  refresh: <AppModel, Store extends RemoteModel>(bound: BoundRemote<AppModel, Store>, model: AppModel, target: Projection<AppModel, unknown> | Surface<AppModel, any, any, void>) => AppModel;
   /**
    * Writes a read result into the store, recording each field's applied window.
    * `requests` are the planned requirements the result answers.
    */
-  writeRead: (store: EntityStore, requests: ReadonlyArray<Requirement$1>, result: Schema.Schema.Type<typeof ReadBatchResult>, now?: number) => EntityStore;
+  writeRead: (store: EntityStore, requests: ReadonlyArray<Requirement>, result: Schema.Schema.Type<typeof ReadBatchResult>, now?: number) => EntityStore;
   /**
    * Adapts an Effect RPC client for `RemoteRpc` to `RemoteClient`, so an
    * application provides the transport's RPC layer instead of writing the
@@ -1951,7 +2086,7 @@ export declare const Remote: {
   /**
    * Runs a mutation through `RemoteClient`, decoding its typed Output and
    * returning the result's normalized patches so the caller can reconcile them
-   * through `Remote.update`'s `MutationSucceeded` (or `Remote.mutateInto`).
+   * through `updateRemote`'s `MutationSucceeded` (or `Remote.mutateInto`).
    */
   mutate: <Name extends string, Input, Output>(mutation: MutationDescriptor<Name, Input, Output>, input: Input, requestId: string) => Effect.Effect<{
     output: Output;
@@ -1991,10 +2126,10 @@ export declare const Remote: {
    * from `RemoteModel.live`, so the application tracks no cursor of its own.
    */
   live: <AppModel, Store extends RemoteModel, Names extends string, Model, SurfaceMessage, Params, Message = RemoteMessage>(bound: BoundRemote<AppModel, Store, Names>, surface: Surface<AppModel, Model, SurfaceMessage, Params>, params: Params, toMessage?: (message: RemoteMessage) => Message, options?: LiveOptions) => EntryWithoutKeepAlive<AppModel, Message, {
-    readonly requirements: ReadonlyArray<Requirement$1>;
+    readonly requirements: ReadonlyArray<Requirement>;
     readonly cursor: LiveCursor;
   }, RemoteClient>;
 };
 //#endregion
-export { Entity$1 as Entity, type RelationRequirement, type Requirement };
+export { Entity$1 as Entity };
 //# sourceMappingURL=index.d.mts.map