foldkit-remote 0.6.0 → 0.8.0

package/dist/index.d.mts

@@ -1,11 +1,12 @@
-import { Context, Duration, Effect, Layer, Option, Schema, Stream } from "effect";
+import { Context, Duration, Effect, Layer, Option, Result, Schema, Stream } from "effect";
 import * as Domain from "foldkit-entity";
 import { AnyEntity, AnyQuery, Dependencies, InputExpr, Query as Query$1 } from "foldkit-entity";
+import { Command } from "foldkit/command";
 import { EntryWithoutKeepAlive } from "foldkit/subscription";
 import { ActiveSurface, Contract, Invalid, Metadata, ModelRef, Projection, Surface, Wiring } from "foldkit-surface";
 import { Rpc, RpcGroup } from "effect/unstable/rpc";
 import { KeyValueStore } from "effect/unstable/persistence";
-import { Command } from "foldkit/command";
+import * as Update from "foldkit/update";
 //#region ../metadata/dist/index.d.mts
 //#region src/index.d.ts
 /** Marks a `Metadata` value. Its entries are private to this module. */
@@ -202,6 +203,12 @@ export interface EntityEntry {
   readonly present: ReadonlySet<string>;
   /** Present fields whose value may be outdated (revalidation needed). */
   readonly stale: ReadonlySet<string>;
+  /**
+   * Fields the server settled without a value: asked for, and answered without
+   * them, whatever the reason. Not planned again until a refresh asks; a later
+   * write of the field clears it.
+   */
+  readonly unavailable: ReadonlySet<string>;
   /** The entity is known to be absent; a later write clears this. */
   readonly tombstone: boolean;
   /** Injected clock reading of the last write; never read from ambient state. */
@@ -240,6 +247,14 @@ export declare const setStale: (store: EntityStore, marks: ReadonlyArray<readonl
 export declare const markStale: (store: EntityStore, key: EntityKey, fields: Iterable<string>) => EntityStore;
 /** Ends a refresh that did not land: the fields are present again as they were. */
 export declare const clearStale: (store: EntityStore, key: EntityKey, fields: Iterable<string>) => EntityStore;
+/**
+ * Records fields the server settled without a value. A present field is left
+ * as it is: the answer that settled it was not about the value it holds.
+ * `false` forgets the marks, which is how a refresh asks again.
+ */
+export declare const setUnavailable: (store: EntityStore, marks: ReadonlyArray<readonly [key: EntityKey, fields: Iterable<string>]>, unavailable: boolean) => EntityStore;
+/** Whether the server settled this field without a value, and nothing has written it since. */
+export declare const isFieldUnavailable: (store: EntityStore, key: EntityKey, field: string) => boolean;
 /** Records that the entity is known to be absent, so it is not refetched. */
 export declare const tombstone: (store: EntityStore, key: EntityKey) => EntityStore;
 /** Forgets everything known about the entity, including a tombstone. */
@@ -257,7 +272,8 @@ export declare const isFieldStale: (store: EntityStore, key: EntityKey, field: s
 export declare const readField: (store: EntityStore, key: EntityKey, field: string) => Option.Option<unknown>;
 /**
  * The fields the planner must fetch. A tombstone makes every field known
- * (absent), so it returns an empty list and the entity is not refetched. A
+ * (absent), so it returns an empty list and the entity is not refetched, and a
+ * field the server settled without a value is known the same way. A
  * requested window that differs from the one a field was fetched with also
  * marks it missing, but only when the stored window is known (never `""`), so a
  * writer that does not record windows cannot cause a refetch loop.
@@ -740,7 +756,7 @@ 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 = 4;
+export declare const REMOTE_CACHE_VERSION = 5;
 /**
  * What survives a reload: the entity cache, and the connections an application
  * **declared** should come back.
@@ -832,7 +848,7 @@ export declare const RemotePersistence: {
  * server refuses a mismatch with `RemoteProtocolError`, so a shape change never
  * drifts silently: bump it whenever `ReadRequest` or `LiveRequirement` change.
  */
-export declare const REMOTE_PROTOCOL_VERSION = 3;
+export declare const REMOTE_PROTOCOL_VERSION = 4;
 declare const RemoteReadError_base: Schema.Class<RemoteReadError, Schema.TaggedStruct<"RemoteReadError", {
   readonly message: Schema.String;
 }>, import("effect/Cause").YieldableError>;
@@ -875,12 +891,27 @@ export declare const NormalizedEntity: Schema.Struct<{
   readonly id: Schema.String;
   readonly values: Schema.$Record<Schema.String, Schema.Unknown>;
 }>;
+/**
+ * Fields a read asked for that the server answered without, and will not
+ * answer with: the client stops asking. It says nothing about why, so a rule
+ * that withholds a field is not itself on the wire.
+ */
+export declare const SettledFields: Schema.Struct<{
+  readonly entity: Schema.String;
+  readonly id: Schema.String;
+  readonly fields: Schema.$Array<Schema.String>;
+}>;
 export declare const ReadBatchResult: Schema.Struct<{
   readonly entities: Schema.$Array<Schema.Struct<{
     readonly entity: Schema.String;
     readonly id: Schema.String;
     readonly values: Schema.$Record<Schema.String, Schema.Unknown>;
   }>>;
+  readonly settled: Schema.$Array<Schema.Struct<{
+    readonly entity: Schema.String;
+    readonly id: Schema.String;
+    readonly fields: Schema.$Array<Schema.String>;
+  }>>;
 }>;
 export declare const MutationRequest: Schema.Struct<{
   /** Stable across transport retries so a mutation is not applied twice. */
@@ -999,6 +1030,11 @@ export declare const Read: Rpc.Rpc<"FoldkitRemoteRead", Schema.Struct<{
     readonly id: Schema.String;
     readonly values: Schema.$Record<Schema.String, Schema.Unknown>;
   }>>;
+  readonly settled: Schema.$Array<Schema.Struct<{
+    readonly entity: Schema.String;
+    readonly id: Schema.String;
+    readonly fields: Schema.$Array<Schema.String>;
+  }>>;
 }>, Schema.Union<readonly [typeof RemoteReadError, typeof RemoteProtocolError]>, never, never>;
 export declare const Mutate: Rpc.Rpc<"FoldkitRemoteMutate", Schema.Struct<{
   /** Stable across transport retries so a mutation is not applied twice. */
@@ -1169,6 +1205,11 @@ export declare const RemoteRpc: RpcGroup.RpcGroup<Rpc.Rpc<"FoldkitRemoteRead", S
     readonly id: Schema.String;
     readonly values: Schema.$Record<Schema.String, Schema.Unknown>;
   }>>;
+  readonly settled: Schema.$Array<Schema.Struct<{
+    readonly entity: Schema.String;
+    readonly id: Schema.String;
+    readonly fields: Schema.$Array<Schema.String>;
+  }>>;
 }>, Schema.Union<readonly [typeof RemoteReadError, typeof RemoteProtocolError]>, never, never> | Rpc.Rpc<"FoldkitRemoteMutate", Schema.Struct<{
   /** Stable across transport retries so a mutation is not applied twice. */
   readonly requestId: Schema.String;
@@ -1348,8 +1389,22 @@ export interface RefreshState {
   readonly generation: number;
   readonly requested: ReadonlyMap<string, number>;
   readonly started: ReadonlyMap<string, number>;
+  /**
+   * The generation every entry is refreshed at, at least: `forgetRemote` moves
+   * it, so every read and live entry restarts, and a read or stream begun for
+   * the principal before is interrupted rather than landing after.
+   */
+  readonly floor: number;
 }
 export declare const emptyRefresh: RefreshState;
+/**
+ * The Model with everything the server told it forgotten: values, tombstones,
+ * unavailable fields, connections, live cursors, failures, and what is in
+ * flight. For a change of principal, whose facts these were. The mutation
+ * sequence is kept, so request ids stay unique, and a mutation in flight is
+ * treated as applied: its answer, when it comes, writes nothing here.
+ */
+export declare const forgetRemote: (model: RemoteModel) => RemoteModel;
 export declare const initialRemoteModel: RemoteModel;
 export declare const remoteModelSchema: () => Schema.Codec<RemoteModel, unknown>;
 /** The submodel's Messages; each reduces to `RemoteModel` through `updateRemote`. */
@@ -1494,6 +1549,11 @@ export declare const remoteMessageCases: {
         readonly id: Schema.String;
         readonly values: Schema.$Record<Schema.String, Schema.Unknown>;
       }>>;
+      readonly settled: Schema.$Array<Schema.Struct<{
+        readonly entity: Schema.String;
+        readonly id: Schema.String;
+        readonly fields: Schema.$Array<Schema.String>;
+      }>>;
     }>;
     now: Schema.Number;
   };
@@ -1642,6 +1702,12 @@ export declare const isLoading: (model: RemoteModel, entity: string, id: string,
 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;
+/**
+ * Whether a read is fetching any field `relation` reads of an entity, its own
+ * or, through each relation the store holds, its targets'. A value whose owner
+ * is being fetched is loading, not `Initial`: nothing is missing a fetch.
+ */
+export declare const isLoadingThrough: (model: RemoteModel, entity: string, id: string, relation: RelationRequirement) => 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
@@ -1658,6 +1724,23 @@ export declare const failureOf: (model: RemoteModel, entity: string, id: string,
  */
 export declare const writeRead: (store: EntityStore, requests: ReadonlyArray<Requirement>, result: Schema.Schema.Type<typeof ReadBatchResult>, now?: number) => EntityStore;
 //#endregion
+//#region src/resume.d.ts
+/**
+ * A resume part, in the shape `foldkit-ssr`'s `SSR.plan` takes in `parts`.
+ * Declared here structurally, so neither package depends on the other.
+ */
+interface RemoteResumePart<AppModel> {
+  readonly id: string;
+  /** The metadata key names whose reads this part resumes. */
+  readonly covers: ReadonlyArray<string>;
+  readonly capture: (model: AppModel, projections: ReadonlyArray<{
+    readonly metadata: Metadata;
+  }>) => unknown;
+  readonly restore: (model: AppModel, value: unknown) => Result.Result<AppModel, string>;
+  /** Whether a Subscription entry is one of this domain's, which may start late. */
+  readonly deferrable: (key: string, entry: unknown) => boolean;
+}
+//#endregion
 //#region src/coalesce.d.ts
 type Batch = Schema.Schema.Type<typeof ReadBatch>;
 type BatchResult = Schema.Schema.Type<typeof ReadBatchResult>;
@@ -1876,6 +1959,12 @@ interface Assembled {
  * list), so the Selection's codec decides whether that is a failure.
  */
 export declare const assemble: (store: EntityStore, key: string, requirement: RelationRequirement) => Assembled | undefined;
+/**
+ * The first field `requirement` reads, at any depth, that the server settled
+ * without a value, as `Entity:id.field`. A read that consults it says why it
+ * cannot assemble rather than waiting on a field nothing will fetch.
+ */
+export declare const unavailableOf: (store: EntityStore, key: string, requirement: RelationRequirement) => string | undefined;
 //#endregion
 //#region src/entity.d.ts
 export type AnySchema = Schema.Schema<unknown>;
@@ -1899,6 +1988,18 @@ export interface EntityDescriptor<Name extends string, F extends Schema.Struct.F
   /** A patch of this entity's wire-shaped values; `Entity.patch(entity.ref(id), values)`. */
   patch(id: Schema.Schema.Type<F['id']>, values: Partial<Schema.Struct.Encoded<F>>): EntityPatch<Name, F>;
 }
+/**
+ * Relations are **references**, never inline target schemas: a ref cannot
+ * reconstruct a full entity, and dereferencing is a store concern. Because the
+ * target schema is not inlined, recursive relations cannot arise through the
+ * schema graph.
+ */
+/**
+ * A ref as the wire carries it: the target's name, a colon, and its id. Typed
+ * with the name, so a relation to `User` takes `'User:u1'` and not a ref to
+ * some other entity, which would read as a row that does not exist.
+ */
+export type RefKey<Name extends string> = `${Name}:${string}`;
 /**
  * A patch in wire shape: the values the store holds, so a relation is its ref
  * key (`Entity.refKey`), not an `EntityRef`.
@@ -1919,7 +2020,7 @@ export interface RefPage<Name extends string, F extends Schema.Struct.Fields = S
   readonly hasPrevious: boolean;
 }
 /** The ref codec a `foldkit-entity` relation becomes: one ref, a nullable ref, or an array of refs. */
-type RelationField<Spec> = Spec extends Domain.RelationSpec<infer Target, infer Cardinality, infer Optional> ? Cardinality extends 'many' ? Schema.$Array<Schema.Codec<EntityRef<Target['name']>, string>> : Optional extends true ? Schema.NullOr<Schema.Codec<EntityRef<Target['name']>, string>> : Schema.Codec<EntityRef<Target['name']>, string> : never;
+type RelationField<Spec> = Spec extends Domain.RelationSpec<infer Target, infer Cardinality, infer Optional> ? Cardinality extends 'many' ? Schema.$Array<Schema.Codec<EntityRef<Target['name']>, RefKey<Target['name']>>> : Optional extends true ? Schema.NullOr<Schema.Codec<EntityRef<Target['name']>, RefKey<Target['name']>>> : Schema.Codec<EntityRef<Target['name']>, RefKey<Target['name']>> : never;
 /**
  * The fields Remote stores for a `foldkit-entity` Entity: its own fields, its
  * derived members (the server supplies them like any field), and each relation
@@ -1941,9 +2042,9 @@ declare const Entity$1: {
     readonly id: Schema.Schema<unknown>;
   }>(name: Name, schema: Schema.Struct<F>) => EntityDescriptor<Name, F>;
   /** A relation to a known entity, decoded as a reference. */
-  ref: <Name extends string, F extends Schema.Struct.Fields>(entity: EntityDescriptor<Name, F>) => Schema.Codec<EntityRef<Name, F>, string>;
+  ref: <Name extends string, F extends Schema.Struct.Fields>(entity: EntityDescriptor<Name, F>) => Schema.Codec<EntityRef<Name, F>, RefKey<Name>>;
   /** A relation by name, for recursive or forward references. */
-  refTo: <Name extends string>(name: Name) => Schema.Codec<EntityRef<Name>, string>;
+  refTo: <Name extends string>(name: Name) => Schema.Codec<EntityRef<Name>, RefKey<Name>>;
   /**
    * The wire key a relation field carries (`"Entity:id"`). Adapters that read a
    * foreign key emit this so the ref codec can decode it on the client.
@@ -2060,6 +2161,7 @@ export interface RemoteInspection {
     readonly key: string;
     readonly present: ReadonlyArray<string>;
     readonly stale: ReadonlyArray<string>;
+    readonly unavailable: ReadonlyArray<string>;
     readonly tombstone: boolean;
     readonly updatedAt: number;
     readonly windows: Readonly<Record<string, string>>;
@@ -2090,6 +2192,29 @@ 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;
+/**
+ * Why a read shows what it shows, in words, and for `Initial`, which of the
+ * usual mistakes it is.
+ *
+ * `Initial` means nothing is fetching the read, and that is almost always
+ * wiring rather than the network: no active Surface reads it, or one does and
+ * Remote's Subscriptions are not running. The Model can tell those apart when
+ * it is given the active record, so this says which, and what to do.
+ */
+export interface ReadDiagnosis {
+  readonly state: RemoteData<unknown>['_tag'];
+  /**
+   * For `Initial` only. `NotObserved`: no active Surface reads it.
+   * `NotFetching`: one does, and nothing is fetching it, so Remote's
+   * Subscriptions are most likely not installed. `Unknown`: no active record
+   * was given to tell.
+   */
+  readonly reason?: 'NotObserved' | 'NotFetching' | 'Unknown' | undefined;
+  /** One or two sentences a developer can act on. */
+  readonly message: string;
+  /** The active Surfaces reading it, when the active record was given. */
+  readonly surfaces?: ReadonlyArray<string> | undefined;
+}
 /**
  * What one query read is, and what it currently is — data-query-DESIGN §29.1.
  *
@@ -2174,6 +2299,20 @@ export interface PlanOptions {
   /** Plan every requested field, present or not, tombstoned or not. */
   readonly force?: boolean | undefined;
 }
+/** When present values next go stale, and the requirements of the entities that do. */
+export interface Deadline {
+  readonly at: number;
+  readonly due: ReadonlyArray<Requirement>;
+}
+/**
+ * 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.
+ */
+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>;
 //#endregion
 //#region src/policy.d.ts
@@ -2227,6 +2366,10 @@ export type EntityLike = EntityDescriptor<any, any> | Domain.AnyEntity;
 export type EntitySelection<Value, Name extends string, Id extends string = string> = Selection<Value, Name, 'entity'> | Domain.Selection<Name, unknown, Schema.Constraint & {
   readonly Type: Value;
 }, Id>;
+/** The Remote descriptor either kind of entity reads as, at the type level. */
+type DescriptorOf<E extends EntityLike> = E extends EntityDescriptor<any, any> ? E : E extends Domain.AnyEntity ? EntityDescriptor<E['name'], FieldsFrom<E>> : never;
+type NameOf<E extends EntityLike> = DescriptorOf<E> extends EntityDescriptor<infer N, any> ? N : never;
+type FieldsOf<E extends EntityLike> = DescriptorOf<E> extends EntityDescriptor<any, infer F> ? F : never;
 type EntityName<D> = D extends {
   readonly name: infer Name extends string;
 } ? Name : never;
@@ -2345,6 +2488,18 @@ export interface RemoteDomain<AppModel, Store extends RemoteModel, Entities exte
   explain<Name extends string, Input>(model: AppModel, projection: QueryProjection<AppModel, any, Name, Input>, options?: {
     readonly surfaces?: Readonly<Record<string, ActiveSurface<AppModel>>> | undefined;
   }): QueryExplanation;
+  /**
+   * Why a read shows what it shows, in words. Any Remote read: `Data.get`,
+   * `Data.live` or `Data.query`.
+   *
+   * Its point is `Initial`, which means nothing is fetching the read and is
+   * almost always a wiring mistake. Given `surfaces`, the same active record
+   * `subscriptions` takes, it says which: no active Surface reads it, or one
+   * does and Remote's Subscriptions are not running. Pure, like `explain`.
+   */
+  why(model: AppModel, projection: Projection<AppModel, RemoteData<unknown>>, options?: {
+    readonly surfaces?: Readonly<Record<string, ActiveSurface<AppModel>>> | undefined;
+  }): ReadDiagnosis;
   /**
    * The rows of a loaded list that a body matches, decoded as the list decodes
    * them — a filter that asks the server nothing.
@@ -2378,6 +2533,8 @@ export interface RemoteDomain<AppModel, Store extends RemoteModel, Entities exte
   lift(model: AppModel, id: string): AppModel;
   /** `Remote.refresh`: marks what a projection or a Surface requires as due, for its read entry to refetch. */
   refresh(model: AppModel, target: Projection<AppModel, unknown> | Surface<AppModel, any, any, void>): AppModel;
+  /** `Remote.forget`: the Model with every server-derived fact gone, for a change of principal. */
+  forget(model: AppModel): AppModel;
   /**
    * The Foldkit Subscription entries for the active Surfaces, keyed for
    * `Subscription.make`: a read entry per Surface (`Remote.observe`), a live
@@ -2446,6 +2603,30 @@ export interface RemoteDomain<AppModel, Store extends RemoteModel, Entities exte
   /** `Remote.inspect` of the bound slice. */
   inspect(model: AppModel): RemoteInspection;
 }
+/** What `Remote.fold(Data, …).mutate` starts: `Data.mutate`'s result with its Command lifted. */
+export type FoldedMutationStarted<AppModel, ParentMessage> = Omit<MutationStarted<AppModel>, 'command'> & {
+  readonly command: Command<ParentMessage, never, RemoteClient>;
+};
+/**
+ * A bound domain folded under one of the application's own Message variants,
+ * from `Remote.fold`. Calling it reduces a Remote Message into the Model; the
+ * members that produce Messages, `fetch`, `mutate`, and `subscriptions`,
+ * yield the wrapper Message instead of `RemoteMessage`, with the lift recorded
+ * so Story and Scene can resolve a fetch or a mutation by Remote's own answer.
+ * Members that only read or write the Model (`get`, `refresh`, `next`,
+ * `overlay`, and the rest) stay on the domain itself.
+ */
+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>; };
+}
+/** The application Model a bound domain is over. */
+export type ModelOfDomain<Domain> = Domain extends RemoteDomain<infer AppModel, any, any, any, any> ? AppModel : never;
 /** A projection's connection requirement with the `QueryRef` that runs it. */
 export interface QueryRequirement extends ConnectionRequirement {
   readonly ref: QueryRef<string, unknown>;
@@ -2518,6 +2699,14 @@ export interface ReadDependencies {
    * leaves it running.
    */
   readonly refresh: number;
+  /**
+   * Under a refreshing policy, when a value the entry holds next ages out and
+   * what is due then. Time reaches Remote only as a Message: the entry sleeps
+   * until then and emits `RefreshStarted`, which marks the fields stale, and
+   * the plan that follows fetches them. A Model that does not change past its
+   * `maxAge` is otherwise never looked at again.
+   */
+  readonly expires: Deadline | null;
 }
 export declare const Remote: {
   /** The submodel's schema, the same for every domain; embed it in the application Model. */
@@ -2538,6 +2727,11 @@ export declare const Remote: {
           readonly id: Schema.String;
           readonly values: Schema.$Record<Schema.String, Schema.Unknown>;
         }>>;
+        readonly settled: Schema.$Array<Schema.Struct<{
+          readonly entity: Schema.String;
+          readonly id: Schema.String;
+          readonly fields: Schema.$Array<Schema.String>;
+        }>>;
       }>;
       now: Schema.Number;
     };
@@ -2638,6 +2832,158 @@ export declare const Remote: {
   }>(message: M) => message is Extract<M, {
     readonly _tag: RemoteMessageTag;
   }>;
+  /**
+   * Remote's Messages as one Schema, for a wrapper variant in the
+   * application's union: `GotRemoteMessage: { message: Remote.Message }`. With
+   * a wrapper, `update` matches the application's union exhaustively and
+   * `Remote.fold` reduces what arrives inside it.
+   */
+  Message: import("foldkit/message").MessageUnion<{
+    ReadReceived: {
+      requests: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
+      result: Schema.Struct<{
+        readonly entities: Schema.$Array<Schema.Struct<{
+          readonly entity: Schema.String;
+          readonly id: Schema.String;
+          readonly values: Schema.$Record<Schema.String, Schema.Unknown>;
+        }>>;
+        readonly settled: Schema.$Array<Schema.Struct<{
+          readonly entity: Schema.String;
+          readonly id: Schema.String;
+          readonly fields: Schema.$Array<Schema.String>;
+        }>>;
+      }>;
+      now: Schema.Number;
+    };
+    ReadFailed: {
+      requests: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
+      error: Schema.Struct<{
+        readonly _tag: Schema.String;
+        readonly message: Schema.String;
+      }>;
+      stream: Schema.optional<Schema.String>;
+    };
+    RefreshStarted: {
+      requests: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
+    };
+    ReadStarted: {
+      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>>;
+        readonly connections: Schema.$Array<Schema.Struct<{
+          readonly identity: Schema.String;
+          readonly select: Schema.optional<Schema.Codec<RelationRequirement, RelationRequirement, never, never>>;
+        }>>;
+      }>;
+    };
+    Hydrated: {
+      connections: Schema.optional<Schema.Unknown>;
+      entities: Schema.Unknown;
+      merge: Schema.Union<readonly [Schema.Literal<"replace">, Schema.Literal<"preserve-existing">]>;
+    };
+    MutationStarted: {
+      requestId: Schema.String;
+      optimistic: Schema.optional<Schema.$Array<Schema.Unknown>>;
+    };
+    MutationSucceeded: {
+      requestId: Schema.String;
+      entities: Schema.$Array<Schema.Struct<{
+        readonly entity: Schema.String;
+        readonly id: Schema.String;
+        readonly values: Schema.$Record<Schema.String, Schema.Unknown>;
+      }>>;
+      connections: Schema.optional<Schema.$Array<Schema.Unknown>>;
+      deleted: Schema.optional<Schema.$Array<Schema.Struct<{
+        readonly entity: Schema.String;
+        readonly id: Schema.String;
+      }>>>;
+    };
+    MutationFailed: {
+      requestId: Schema.String;
+      error: Schema.Struct<{
+        readonly _tag: Schema.String;
+        readonly message: Schema.String;
+      }>;
+    };
+    OverlayShown: {
+      id: Schema.String;
+      optimistic: Schema.$Array<Schema.Unknown>;
+    };
+    OverlayLifted: {
+      id: Schema.String;
+    };
+    LiveReceived: {
+      stream: Schema.String;
+      event: Schema.Unknown;
+      policy: Schema.optional<Schema.Unknown>;
+      now: Schema.Number;
+    };
+    GapCleared: {
+      stream: Schema.String;
+    };
+    ConnectionMerged: {
+      connection: Schema.String;
+      page: Schema.Unknown;
+      refreshes: Schema.optional<Schema.Boolean>;
+    };
+    ConnectionInvalidated: {
+      connection: Schema.String;
+    };
+    ConnectionRefreshed: {
+      connection: Schema.String;
+    };
+    QueryFailed: {
+      connection: Schema.String;
+      error: Schema.Struct<{
+        readonly _tag: Schema.String;
+        readonly message: Schema.String;
+      }>;
+    };
+  }>;
+  /**
+   * A bound domain under one wrapper variant of the application's union, the
+   * same shape Foldkit gives a Submodel: `toParentMessage` wraps Remote's
+   * Messages, the fold reduces them, and its `fetch`, `mutate`, and
+   * `subscriptions` yield the wrapper. Spreading `Remote.messages` and
+   * narrowing with `Remote.reduces` remains the shorter path for an
+   * application whose `update` only reduces.
+   *
+   * @example
+   * ```ts
+   * const Message = defineMessageUnion({ GotRemoteMessage: { message: Remote.Message } })
+   * const foldData = Remote.fold(Data, message => Message.GotRemoteMessage({ message }))
+   *
+   * const update = (model: Model, message: Message): Return =>
+   *   Message.match(message, {
+   *     GotRemoteMessage: ({ message }) => foldData(model, message),
+   *   })
+   * const subscriptions = Subscription.make<Model, Message, RemoteClient>()(() =>
+   *   foldData.subscriptions({ page: Surface.at(ProjectPage, …) }),
+   * )
+   * ```
+   */
+  fold: <Domain extends RemoteDomain<any, any, any, any, any>, ParentMessage>(domain: Domain, toParentMessage: (message: RemoteMessage) => ParentMessage) => RemoteFold<ModelOfDomain<Domain>, ParentMessage, Domain>;
+  /**
+   * A patch of one entity's values, for a mutation's `optimistic` list or an
+   * overlay. Takes a `foldkit-entity` Entity or a Remote descriptor alike, so
+   * the domain you declared once is the one you patch:
+   * `Remote.patch(Project, 'p1', { name: 'Apollo II' })`. Values are the
+   * fields' wire shape, as the server writes them; a relation is its ref key
+   * (`'User:u1'`).
+   */
+  patch: <E extends EntityLike>(entity: E, id: string, values: Partial<Schema.Struct.Encoded<FieldsOf<E>>>) => EntityPatch<NameOf<E>, FieldsOf<E>>;
+  /**
+   * A reference to one entity, for `ConnectionChange` and anything else that
+   * names a row: `Remote.ref(Project, 'p3')`. Either kind of entity, as with
+   * `Remote.patch`.
+   */
+  ref: <E extends EntityLike>(entity: E, id: string) => EntityRef<NameOf<E>, FieldsOf<E>>;
   /**
    * Declares a Remote domain and binds it to its place in the application Model
    * in one step; the result carries the application-facing operations. The
@@ -2665,6 +3011,17 @@ export declare const Remote: {
    * rejects a selection for an entity this domain never declared.
    */
   at: <AppModel, Store extends RemoteModel, Entities extends readonly EntityLike[], Queries extends readonly QueryDescriptor<any, any, any>[], Mutations extends readonly MutationDescriptor<any, any, any>[]>(definition: RemoteDescriptor<Entities, Queries, Mutations>, store: ModelRef<AppModel, Store>) => BoundRemote<AppModel, Store, EntityName<Entities[number]>>;
+  /**
+   * The resume part for this domain, for `foldkit-ssr`'s `SSR.plan({ parts })`:
+   * a server render sends what the plan's active Surfaces read from the store,
+   * each connection with its boundaries and each live cursor with it, and
+   * nothing else. `id` tells two domains in one application apart.
+   */
+  resume: <AppModel, Store extends RemoteModel>(domain: {
+    readonly store: ModelRef<AppModel, Store>;
+  }, options?: {
+    readonly id?: string | undefined;
+  }) => RemoteResumePart<AppModel>;
   /**
    * A Projection node that reads a `RemoteData` value out of the store. The id
    * is supplied by the caller, usually from a Surface's params. The assembled
@@ -2725,6 +3082,17 @@ export declare const Remote: {
    * 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;
+  /**
+   * Forgets everything the server told this Model: values, tombstones,
+   * unavailable fields, connections, live cursors, failures. What is known is
+   * known for a principal, and this is the one boundary for a login, a logout
+   * or a switch of organization: called from `update`, it performs no I/O, and
+   * every active Surface's read and live entries restart, so the screen asks
+   * again as whoever the client now is. A read or stream begun before is
+   * interrupted rather than landing after. A mutation in flight is treated as
+   * applied: its answer writes nothing here.
+   */
+  forget: <AppModel, Store extends RemoteModel>(bound: BoundRemote<AppModel, Store>, model: AppModel) => AppModel;
   /**
    * Writes a read result into the store, recording each field's applied window.
    * `requests` are the planned requirements the result answers.
@@ -2840,8 +3208,9 @@ export declare const Remote: {
   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>;
 };
 //#endregion
-export { Entity$1 as Entity };
+export { Entity$1 as Entity, type RemoteResumePart };
 //# sourceMappingURL=index.d.mts.map