foldkit-remote 0.12.0 → 0.14.0

package/dist/{index-njA5CxbS.d.mts → index-CXAGo7Dz.d.mts}

@@ -1,11 +1,11 @@
-import { Context, Duration, Effect, Layer, Option, Result, Schema, Stream } from "effect";
+import { Context, Data, Duration, Effect, Layer, Option, Result, Schema, Stream } from "effect";
+import { KeyValueStore } from "effect/persistence";
 import * as Domain from "foldkit-entity";
-import { AnyEntity, AnyQuery, Dependencies, InputExpr, Query } from "foldkit-entity";
+import { AnyEntity, AnyQuery, AnyWrite, BoundWrite, Dependencies, InputExpr, Query, Write } 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 { ActiveSurface, Contract, Invalid, Metadata, ModelRef, Projection, Surface, SurfaceSource, Wiring } from "foldkit-surface";
 import { Rpc, RpcClientError, RpcGroup } from "effect/rpc";
-import { KeyValueStore } from "effect/persistence";
 import * as Update from "foldkit/update";
 //#region ../metadata/src/index.d.ts
 /** Marks a `Metadata` value. Its entries are private to this module. */
@@ -108,6 +108,13 @@ declare const isGapped: (connection: Connection) => boolean;
 interface RemoteError {
   readonly _tag: string;
   readonly message: string;
+  /**
+   * A refused mutation's refusal, encoded as the server sent it. Read it
+   * decoded, by its mutation, with `Data.refusal`.
+   */
+  readonly refusal?: unknown;
+  /** Why the server refused who is asking (`_tag: 'Forbidden'`), when it said. */
+  readonly reason?: string;
 }
 type RemoteData<A> = {
   readonly _tag: 'Initial';
@@ -144,6 +151,8 @@ type Freshness = {
 declare const remoteErrorSchema: Schema.Struct<{
   readonly _tag: Schema.String;
   readonly message: Schema.String;
+  readonly refusal: Schema.optional<Schema.Unknown>;
+  readonly reason: Schema.optional<Schema.String>;
 }>;
 declare const remoteDataSchema: <A>(value: Schema.Schema<A>) => Schema.Codec<RemoteData<A>, unknown>;
 declare const RemoteData: {
@@ -152,6 +161,11 @@ declare const RemoteData: {
    * be embedded in a hand-written Model schema, not only through `Remote.select`.
    */
   schema: <A>(value: Schema.Schema<A>) => Schema.Schema<RemoteData<A>>;
+  /**
+   * Whether the read has an answer: `Ready`, `Refreshing`, `Failed` or
+   * `NotFound`. `Initial` and `Loading` are still waiting for one.
+   */
+  answered: <A>(data: RemoteData<A>) => boolean;
   /** Exhaustive: omitting a state is a compile error. */
   match: <A, R>(data: RemoteData<A>, cases: {
     readonly Initial: () => R;
@@ -338,26 +352,81 @@ interface MutationAnswer {
  */
 declare const reconcileMutation: (store: EntityStore, state: MutationState, requestId: string, answer: MutationAnswer) => Reconciled;
 /** A mutation an application declares: its name and input/output codecs. */
-interface MutationDescriptor<Name extends string, Input, Output> {
+interface MutationDescriptor<Name extends string, Input, Output, Refused = unknown> {
   readonly name: Name;
   readonly Input: Schema.Codec<Input>;
   readonly Output: Schema.Codec<Output>;
+  /**
+   * What the server may refuse the mutation with, as a value a client can
+   * match on rather than a message to parse: `Schema.Never` when it declares
+   * none.
+   */
+  readonly Refusal: Schema.Codec<Refused, unknown>;
+  /**
+   * What the mutation writes, when it was declared as a `Write`: the optimistic
+   * patch a client shows, and what a server can run without a handler.
+   */
+  readonly write?: AnyWrite | undefined;
 }
+/** Refusals a form or an editor knows how to show. */
+declare const Refusal: {
+  /** One input key was refused, for `reason`, which a form shows beside that key. */
+  field: <const Key extends string, Reason extends Schema.Top>(key: Key, reason: Reason) => Schema.TaggedStruct<"Field", {
+    readonly key: Schema.Literal<Key>;
+    readonly reason: Reason;
+  }>;
+  /** The row moved on since the client read it; the author decides what wins. */
+  conflict: Schema.TaggedStruct<"Conflict", {}>;
+  /** Whether a refusal, of whatever mutation, is a `Refusal.field`. */
+  isField: <I>(input: I) => input is I & {
+    readonly _tag: "Field";
+    readonly key: string;
+    readonly reason: unknown;
+  };
+  /** Whether a refusal, of whatever mutation, is `Refusal.conflict`. */
+  isConflict: <I>(input: I) => input is I & {
+    readonly _tag: "Conflict";
+  };
+};
 /** A codec, or the fields of a `Schema.Struct` where one is expected. */
 type SchemaOrFields = Schema.Codec<any, any, any, any> | Schema.Struct.Fields;
 /** The decoded type of a codec, or of the Struct the fields describe. */
 type TypeOf<S extends SchemaOrFields> = S extends Schema.Codec<infer T, any, any, any> ? T : S extends Schema.Struct.Fields ? Schema.Struct.Type<S> : never;
 /** The codec itself, or a `Schema.Struct` over the fields. */
 declare const schemaOf: <S extends SchemaOrFields>(shape: S) => Schema.Codec<TypeOf<S>>;
+/**
+ * A bound write as the store patches it: its fields as they are, and each
+ * relation it points as the ref key the store holds (`'User:u1'`), or null.
+ */
+declare const patchOfWrite: (bound: BoundWrite) => NormalizedPatch;
+/**
+ * What a declared write shows before the server answers: an update's or an
+ * insert's row as a patch (an update's only for the keys named, when some
+ * are). A delete shows nothing, since no operation removes a row from every
+ * list it is in; its answer does.
+ */
+declare const optimisticOfWrite: (write: AnyWrite, input: unknown, keys: ReadonlyArray<string> | undefined) => ReadonlyArray<NormalizedPatch>;
 declare const Mutation: {
   /**
    * Declares a mutation. `Input` and `Output` are codecs, or the fields of the
    * `Schema.Struct` they would be (`{ id: ProjectId, name: Schema.String }`).
+   * `Refusal`, when given, is what the server may refuse with: a codec, usually
+   * a union of `Refusal.field(...)` and `Refusal.conflict`.
+   */
+  /**
+   * A mutation that is a declared `Write` (`update`, `insert` or `delete`): its
+   * input is the write's, and it answers nothing but the row it changed, as a
+   * patch, or its deletion. It may be refused as a conflict, for a write that
+   * `expect`s a revision the row has moved past.
    */
-  make: <const Name extends string, Input extends SchemaOrFields, Output extends SchemaOrFields>(name: Name, config: {
+  write: <const Name extends string, Fields extends Schema.Struct.Fields>(name: Name, write: Write<any, Fields>) => MutationDescriptor<Name, Schema.Struct.Type<Fields>, {}, typeof Refusal.conflict.Type> & {
+    readonly write: Write<any, Fields>;
+  };
+  make: <const Name extends string, Input extends SchemaOrFields, Output extends SchemaOrFields, Refused = never>(name: Name, config: {
     readonly Input: Input;
     readonly Output: Output;
-  }) => MutationDescriptor<Name, TypeOf<Input>, TypeOf<Output>>;
+    readonly Refusal?: Schema.Codec<Refused, any>;
+  }) => MutationDescriptor<Name, TypeOf<Input>, TypeOf<Output>, Refused>;
 };
 //#endregion
 //#region src/query.d.ts
@@ -480,8 +549,10 @@ declare const Query$1: {
   before: (cursor: Cursor) => <R extends QueryRef<string, unknown>>(ref: R) => R;
   from: <E extends AnyEntity>(entity: E) => Query<E>;
   where: (...predicates: ReadonlyArray<import("foldkit-entity").Predicate>) => <E extends AnyEntity>(self: Query<E>) => Query<E>;
-  orderBy: (...terms: ReadonlyArray<import("foldkit-entity").OrderTerm>) => <E extends AnyEntity>(self: Query<E>) => Query<E>;
-  dependencies: (self: AnyQuery) => import("foldkit-entity").Dependencies;
+  orderBy: (...terms: ReadonlyArray<import("foldkit-entity").Ordering>) => <E extends AnyEntity>(self: Query<E>) => Query<E>;
+  orderFor: (self: AnyQuery, input: Readonly<Record<string, unknown>>) => ReadonlyArray<import("foldkit-entity").OrderTerm>;
+  placement: (self: AnyQuery, input: Readonly<Record<string, unknown>>) => import("foldkit-entity").Placement;
+  dependencies: (self: AnyQuery) => import("foldkit-entity").QueryDependencies;
   unsupported: (self: AnyQuery, supported: ReadonlyArray<import("foldkit-entity").Operation>) => ReadonlyArray<import("foldkit-entity").Operation>;
   show: (self: AnyQuery) => string;
 };
@@ -863,8 +934,20 @@ declare const RemoteReadError_base: Schema.Class<RemoteReadError, Schema.TaggedS
 declare class RemoteReadError extends RemoteReadError_base {}
 declare const RemoteMutationError_base: Schema.Class<RemoteMutationError, Schema.TaggedStruct<"RemoteMutationError", {
   readonly message: Schema.String;
+  /** The mutation's own `Refusal`, encoded, when the server refused it as one. */
+  readonly refusal: Schema.optional<Schema.Unknown>;
 }>, import("effect/Cause").YieldableError>;
 declare class RemoteMutationError extends RemoteMutationError_base {}
+declare const RemoteForbidden_base: Schema.Class<RemoteForbidden, Schema.TaggedStruct<"Forbidden", {
+  readonly message: Schema.String;
+  readonly reason: Schema.optional<Schema.String>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * The server refused who is asking: they may not do this, and asking again
+ * as the same principal is refused again. `reason` is the application's own
+ * words for the person who asked; without it the refusal says nothing of why.
+ */
+declare class RemoteForbidden extends RemoteForbidden_base {}
 declare const RemoteLiveError_base: Schema.Class<RemoteLiveError, Schema.TaggedStruct<"RemoteLiveError", {
   readonly message: Schema.String;
 }>, import("effect/Cause").YieldableError>;
@@ -926,6 +1009,8 @@ declare const MutationRequest: Schema.Struct<{
   readonly requestId: Schema.String;
   readonly mutation: Schema.String;
   readonly input: Schema.Unknown;
+  /** For a mutation that is a `Write`: the input keys to write, when not all of them. */
+  readonly keys: Schema.optional<Schema.$Array<Schema.String>>;
 }>;
 declare const LiveEdge: Schema.Struct<{
   readonly entity: Schema.String;
@@ -1049,6 +1134,8 @@ declare const Mutate: Rpc.Rpc<"FoldkitRemoteMutate", Schema.Struct<{
   readonly requestId: Schema.String;
   readonly mutation: Schema.String;
   readonly input: Schema.Unknown;
+  /** For a mutation that is a `Write`: the input keys to write, when not all of them. */
+  readonly keys: Schema.optional<Schema.$Array<Schema.String>>;
 }>, Schema.Struct<{
   readonly output: Schema.Unknown;
   readonly entities: Schema.$Array<Schema.Struct<{
@@ -1080,7 +1167,7 @@ declare const Mutate: Rpc.Rpc<"FoldkitRemoteMutate", Schema.Struct<{
     readonly entity: Schema.String;
     readonly id: Schema.String;
   }>>>;
-}>, typeof RemoteMutationError, never, never>;
+}>, Schema.Union<readonly [typeof RemoteMutationError, typeof RemoteForbidden]>, never, never>;
 declare const Live: Rpc.Rpc<"FoldkitRemoteLive", Schema.Struct<{
   readonly version: Schema.Number;
   readonly requirements: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
@@ -1265,6 +1352,8 @@ declare const RemoteRpc: RpcGroup.RpcGroup<Rpc.Rpc<"FoldkitRemoteRead", Schema.S
   readonly requestId: Schema.String;
   readonly mutation: Schema.String;
   readonly input: Schema.Unknown;
+  /** For a mutation that is a `Write`: the input keys to write, when not all of them. */
+  readonly keys: Schema.optional<Schema.$Array<Schema.String>>;
 }>, Schema.Struct<{
   readonly output: Schema.Unknown;
   readonly entities: Schema.$Array<Schema.Struct<{
@@ -1296,7 +1385,7 @@ declare const RemoteRpc: RpcGroup.RpcGroup<Rpc.Rpc<"FoldkitRemoteRead", Schema.S
     readonly entity: Schema.String;
     readonly id: Schema.String;
   }>>>;
-}>, typeof RemoteMutationError, never, never> | Rpc.Rpc<"FoldkitRemoteLive", Schema.Struct<{
+}>, Schema.Union<readonly [typeof RemoteMutationError, typeof RemoteForbidden]>, never, never> | Rpc.Rpc<"FoldkitRemoteLive", Schema.Struct<{
   readonly version: Schema.Number;
   readonly requirements: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
   /** Resume cursor; events at or before it are duplicates. */
@@ -1412,8 +1501,14 @@ interface RemoteModel {
   readonly live: Readonly<Record<string, LiveState>>;
   /** Mutation pending/applied/failed ledger. */
   readonly mutations: MutationState;
-  /** Streams whose live cursor fell behind; the caller should resync or refetch. */
+  /**
+   * Streams that broke, by an error or by an event ahead of their cursor, and
+   * have not resubscribed since: changes after the break are missed until the
+   * live entry restarts them and refetches what they cover.
+   */
   readonly gaps: ReadonlySet<string>;
+  /** Each live stream that has ever broken, by stream key. One that never broke is absent. */
+  readonly streams: Readonly<Record<string, StreamHealth>>;
   /**
    * 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`
@@ -1440,6 +1535,42 @@ interface RemoteModel {
    * is how a view retries.
    */
   readonly failures: Failures;
+  /**
+   * The storage key the cache was last restored from, through `Hydrated`'s
+   * `from`. `Data.persistence` saves under a key only once its own snapshot is
+   * in, so a save at startup cannot write the empty store over it.
+   */
+  readonly restoredFrom: Option.Option<string>;
+  /**
+   * Under `verifyPlacement`, the order each list was placed in, by edge key,
+   * and the rows placing took out of its first page, until the server's page
+   * for it arrives to be compared with them.
+   */
+  readonly placed: Readonly<Record<string, PlacedOrder>>;
+  /** Under `verifyPlacement`, each placement the server's page disagreed with. */
+  readonly placementMismatches: ReadonlyArray<PlacementMismatch>;
+}
+/** A list's first page as the client placed it: its keys in order, and those it took out. */
+interface PlacedOrder {
+  readonly order: ReadonlyArray<string>;
+  readonly dropped: ReadonlyArray<string>;
+}
+/** A list the client placed rows in one order and the server then listed in another. */
+interface PlacementMismatch {
+  readonly connection: string;
+  /** The keys as placed, as far as the server's page reached. */
+  readonly placed: ReadonlyArray<string>;
+  /** The keys of the server's first page. */
+  readonly served: ReadonlyArray<string>;
+}
+/** How a live stream has fared, as its live entry restarts it. */
+interface StreamHealth {
+  /** How many times it broke. The live entry restarts on each, so it only grows. */
+  readonly restarts: number;
+  /** Breaks since its last applied event: what the restart's backoff grows with. */
+  readonly failures: number;
+  /** Why it last broke; none for a gap, which is not an error. */
+  readonly error: Option.Option<RemoteError>;
 }
 /**
  * Failed reads, as the errors they failed with.
@@ -1497,8 +1628,8 @@ type RemoteMessage = {
   /**
    * The live stream whose subscription broke, when this is that rather
    * than a read. Nothing was being read, so no field failed: the stream is
-   * recorded as a gap, since changes after it are missed until the host
-   * resubscribes.
+   * recorded as a gap, since changes after it are missed until the live
+   * entry restarts it.
    */
   readonly stream?: string | undefined;
 } |
@@ -1540,6 +1671,8 @@ type RemoteMessage = {
    */
   readonly connections?: Readonly<Record<string, ReadonlyArray<ReadonlyArray<Edge>>>> | undefined;
   readonly merge: MergePolicy;
+  /** The storage key the snapshot was read from, when it was: `restoredFrom`. */
+  readonly from?: string | undefined;
 } |
 /** A mutation began; its optimistic operations show until it settles. */
 {
@@ -1667,6 +1800,8 @@ declare const remoteMessageCases: {
     error: Schema.Struct<{
       readonly _tag: Schema.String;
       readonly message: Schema.String;
+      readonly refusal: Schema.optional<Schema.Unknown>;
+      readonly reason: Schema.optional<Schema.String>;
     }>;
     stream: Schema.optional<Schema.String>;
   };
@@ -1691,6 +1826,7 @@ declare const remoteMessageCases: {
   };
   Hydrated: {
     connections: Schema.optional<Schema.Unknown>;
+    from: Schema.optional<Schema.String>;
     entities: Schema.Unknown;
     merge: Schema.Union<readonly [Schema.Literal<"replace">, Schema.Literal<"preserve-existing">]>;
   };
@@ -1717,6 +1853,8 @@ declare const remoteMessageCases: {
     error: Schema.Struct<{
       readonly _tag: Schema.String;
       readonly message: Schema.String;
+      readonly refusal: Schema.optional<Schema.Unknown>;
+      readonly reason: Schema.optional<Schema.String>;
     }>;
   };
   OverlayShown: {
@@ -1767,6 +1905,8 @@ declare const remoteMessageCases: {
     error: Schema.Struct<{
       readonly _tag: Schema.String;
       readonly message: Schema.String;
+      readonly refusal: Schema.optional<Schema.Unknown>;
+      readonly reason: Schema.optional<Schema.String>;
     }>;
   };
 };
@@ -1789,6 +1929,8 @@ declare const isRemoteMessage: <M extends {
   readonly _tag: RemoteMessageTag;
 }>;
 declare const remoteMessageSchema: Schema.Schema<RemoteMessage>;
+/** The ids `OverlayShown` shows now, each once, in the order they are drawn. */
+declare const overlaysOf: (model: RemoteModel) => ReadonlyArray<string>;
 /** The key a grown window is kept under: its connection and the window first asked for. */
 declare const windowGrowthKey: (identity: string, window: string) => string;
 /**
@@ -1811,6 +1953,12 @@ declare const refreshedAt: (refresh: RefreshState, requests: ReadonlyArray<Requi
  * refreshed at the next generation.
  */
 declare const withRefreshRequested: (refresh: RefreshState, requests: ReadonlyArray<Requirement>, connections?: ReadonlyArray<string>) => RefreshState;
+/**
+ * Marks connections as needing to be asked again, and restarts a read of them
+ * already in flight: a page requested before what invalidated it could land
+ * after it, saying what is no longer true. `Remote.refresh` marks the same way.
+ */
+declare const invalidateConnections: (model: RemoteModel, connections: ReadonlyArray<string>) => RemoteModel;
 /**
  * Whether one field's read already began under the generation that field was
  * last refreshed at. Such a read is in flight and would otherwise outlive the
@@ -1826,8 +1974,8 @@ declare const refreshIsInFlight: (refresh: RefreshState, request: Requirement, f
 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
- * can resubscribe rather than silently miss facts. When every field a Message
+ * its cursor is a gap: it is not applied, and the stream is recorded so its
+ * live entry restarts it rather than silently missing 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
@@ -1910,7 +2058,7 @@ declare const coalesceReads: (read: BatchRead, options?: CoalesceOptions) => Eff
 declare const RemoteClient_base: Context.ServiceClass<RemoteClient, "foldkit-remote/RemoteClient", {
   readonly read: (batch: Schema.Schema.Type<typeof ReadBatch>) => Effect.Effect<Schema.Schema.Type<typeof ReadBatchResult>, RemoteReadError | RemoteProtocolError>;
   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 mutate: (request: Schema.Schema.Type<typeof MutationRequest>) => Effect.Effect<Schema.Schema.Type<typeof MutationResult>, RemoteMutationError | RemoteForbidden>;
   readonly live: (request: {
     readonly requirements: ReadonlyArray<Requirement>;
     readonly after: LiveCursor;
@@ -1934,7 +2082,7 @@ declare class RemoteClient extends RemoteClient_base {}
 interface RemoteRpcClient<R = never, TransportError = never> {
   readonly FoldkitRemoteRead: (payload: Schema.Schema.Type<typeof ReadBatch>) => Effect.Effect<Schema.Schema.Type<typeof ReadBatchResult>, RemoteReadError | RemoteProtocolError | TransportError, R>;
   readonly FoldkitRemoteQuery: (payload: Schema.Schema.Type<typeof QueryRequest>) => Effect.Effect<Schema.Schema.Type<typeof QueryResult>, RemoteQueryError | TransportError, R>;
-  readonly FoldkitRemoteMutate: (payload: Schema.Schema.Type<typeof MutationRequest>) => Effect.Effect<Schema.Schema.Type<typeof MutationResult>, RemoteMutationError | TransportError, R>;
+  readonly FoldkitRemoteMutate: (payload: Schema.Schema.Type<typeof MutationRequest>) => Effect.Effect<Schema.Schema.Type<typeof MutationResult>, RemoteMutationError | RemoteForbidden | TransportError, R>;
   readonly FoldkitRemoteLive: (payload: Schema.Schema.Type<typeof LiveRequirement>) => Stream.Stream<Schema.Schema.Type<typeof LiveChange>, RemoteLiveError | RemoteProtocolError | TransportError, R>;
 }
 /** Reconstructs the client's `ConnectionChange` from the wire's flattened edge. */
@@ -1944,13 +2092,15 @@ declare const liveEventOf: (change: Schema.Schema.Type<typeof LiveChange>) => Li
 declare const remoteError: (error: {
   readonly _tag: string;
   readonly message: string;
+  readonly refusal?: unknown;
+  readonly reason?: string | undefined;
 }) => RemoteError;
 declare const coalescedLayer: <E, R>(layer: Layer.Layer<RemoteClient, E, R>, options?: CoalesceOptions) => Layer.Layer<RemoteClient, E, R>;
 /**
  * `Remote.mutate` as a standalone effect, so `Remote.mutateInto` can reuse it
  * without the object literal referencing itself.
  */
-declare const mutateRemote: <Name extends string, Input, Output>(mutation: MutationDescriptor<Name, Input, Output>, input: Input, requestId: string) => Effect.Effect<{
+declare const mutateRemote: <Name extends string, Input, Output>(mutation: MutationDescriptor<Name, Input, Output, unknown>, input: Input, requestId: string, keys?: readonly string[] | undefined) => Effect.Effect<{
   output: Output;
   entities: readonly {
     readonly entity: string;
@@ -1964,7 +2114,7 @@ declare const mutateRemote: <Name extends string, Input, Output>(mutation: Mutat
     readonly entity: string;
     readonly id: string;
   }[];
-}, RemoteMutationError, RemoteClient>;
+}, RemoteMutationError | RemoteForbidden, RemoteClient>;
 //#endregion
 //#region src/json.d.ts
 /** A request: which of Remote's calls, and its payload as the RPC protocol encodes it. */
@@ -1978,6 +2128,11 @@ declare const RemoteJsonAnswer: Schema.Union<readonly [Schema.Struct<{
   readonly result: Schema.Unknown;
 }>, Schema.Struct<{
   readonly error: Schema.String;
+  readonly refusal: Schema.optional<Schema.Unknown>;
+  /** Who is asking was refused, with the application's reason when it gave one. */
+  readonly forbidden: Schema.optional<Schema.Struct<{
+    readonly reason: Schema.optional<Schema.String>;
+  }>>;
 }>]>;
 type RemoteJsonAnswer = typeof RemoteJsonAnswer.Type;
 /**
@@ -1986,6 +2141,22 @@ type RemoteJsonAnswer = typeof RemoteJsonAnswer.Type;
  */
 type RemoteJsonSend = (request: string) => Promise<unknown>;
 //#endregion
+//#region src/sse.d.ts
+/** What `httpWithLive` needs besides the URL. Mirrors `http`, plus the fetch itself. */
+interface LiveFetchOptions {
+  /** Read per request, so a token that changes reaches the next call. */
+  readonly headers?: (() => Readonly<Record<string, string>>) | undefined;
+  /** Defaults to the global one; pass it to route calls elsewhere in tests. */
+  readonly fetch?: typeof fetch | undefined;
+}
+/** Remote's live stream over fetch: `serveFetch`'s live open as a `Stream`. */
+declare const liveFetch: (url: string, options?: LiveFetchOptions) => RemoteRpcClient["FoldkitRemoteLive"];
+/**
+ * Remote's client over HTTP with live: reads, queries, and mutations as
+ * `http` sends them, live as `liveFetch` streams it, for `clientLayer`.
+ */
+declare const httpWithLive: (url: string, options?: LiveFetchOptions) => RemoteRpcClient;
+//#endregion
 //#region src/relation.d.ts
 interface RefParts {
   readonly entity: string;
@@ -2337,6 +2508,8 @@ interface RemoteInspection {
   readonly connections: ReadonlyArray<string>;
   readonly live: ReadonlyArray<string>;
   readonly gaps: ReadonlyArray<string>;
+  /** Under `verifyPlacement`, each placement the server's page disagreed with. */
+  readonly placementMismatches: ReadonlyArray<PlacementMismatch>;
   /**
    * The `entity\0id\0field` marks of reads in flight, and a
    * `\0connection\0identity` mark for each query in flight. This is what "Remote is
@@ -2531,6 +2704,134 @@ declare const RemotePolicy: {
   refreshes: (policy: RemotePolicy) => boolean;
 };
 //#endregion
+//#region src/placement.d.ts
+/** Where a row falls in a loaded list. */
+type RowPlace = Data.TaggedEnum<{
+  /** Just before this edge, in this segment. */
+  Before: {
+    readonly segment: number;
+    readonly edge: string;
+  };
+  /** After every edge of this segment, which ends the list. */
+  End: {
+    readonly segment: number;
+  };
+  /** In rows the list has not loaded: past a `Cursor` boundary, or in a gap. */
+  Outside: {};
+  /** Not judged exactly, and why. */
+  Unknown: {
+    readonly reason: string;
+  };
+}>;
+declare const RowPlace: {
+  readonly Unknown: Data.TaggedEnum.ConstructorFrom<{
+    readonly _tag: "Unknown";
+    readonly reason: string;
+  }, "_tag">;
+  readonly Before: Data.TaggedEnum.ConstructorFrom<{
+    readonly _tag: "Before";
+    readonly segment: number;
+    readonly edge: string;
+  }, "_tag">;
+  readonly End: Data.TaggedEnum.ConstructorFrom<{
+    readonly _tag: "End";
+    readonly segment: number;
+  }, "_tag">;
+  readonly Outside: Data.TaggedEnum.ConstructorFrom<{
+    readonly _tag: "Outside";
+  }, "_tag">;
+  readonly $is: <Tag extends "Unknown" | "Before" | "End" | "Outside">(tag: Tag) => (u: unknown) => u is Extract<{
+    readonly _tag: "Unknown";
+    readonly reason: string;
+  }, {
+    readonly _tag: Tag;
+  }> | Extract<{
+    readonly _tag: "Before";
+    readonly segment: number;
+    readonly edge: string;
+  }, {
+    readonly _tag: Tag;
+  }> | Extract<{
+    readonly _tag: "End";
+    readonly segment: number;
+  }, {
+    readonly _tag: Tag;
+  }> | Extract<{
+    readonly _tag: "Outside";
+  }, {
+    readonly _tag: Tag;
+  }>;
+  readonly $match: {
+    <Cases extends {
+      readonly Unknown: (args: {
+        readonly _tag: "Unknown";
+        readonly reason: string;
+      }) => any;
+      readonly Before: (args: {
+        readonly _tag: "Before";
+        readonly segment: number;
+        readonly edge: string;
+      }) => any;
+      readonly End: (args: {
+        readonly _tag: "End";
+        readonly segment: number;
+      }) => any;
+      readonly Outside: (args: {
+        readonly _tag: "Outside";
+      }) => any;
+    }>(cases: Cases): (value: {
+      readonly _tag: "Unknown";
+      readonly reason: string;
+    } | {
+      readonly _tag: "Before";
+      readonly segment: number;
+      readonly edge: string;
+    } | {
+      readonly _tag: "End";
+      readonly segment: number;
+    } | {
+      readonly _tag: "Outside";
+    }) => import("effect/Unify").Unify<ReturnType<Cases["Unknown" | "Before" | "End" | "Outside"]>>;
+    <Cases extends {
+      readonly Unknown: (args: {
+        readonly _tag: "Unknown";
+        readonly reason: string;
+      }) => any;
+      readonly Before: (args: {
+        readonly _tag: "Before";
+        readonly segment: number;
+        readonly edge: string;
+      }) => any;
+      readonly End: (args: {
+        readonly _tag: "End";
+        readonly segment: number;
+      }) => any;
+      readonly Outside: (args: {
+        readonly _tag: "Outside";
+      }) => any;
+    }>(value: {
+      readonly _tag: "Unknown";
+      readonly reason: string;
+    } | {
+      readonly _tag: "Before";
+      readonly segment: number;
+      readonly edge: string;
+    } | {
+      readonly _tag: "End";
+      readonly segment: number;
+    } | {
+      readonly _tag: "Outside";
+    }, cases: Cases): import("effect/Unify").Unify<ReturnType<Cases["Unknown" | "Before" | "End" | "Outside"]>>;
+  };
+};
+/**
+ * Where the row stored under `key` falls in `connection`, by `body`'s order
+ * for `input` (encoded, as a connection's identity carries it). The row's own
+ * edge, if the list holds it, is left out: placing a row that moved asks
+ * where it goes now.
+ */
+declare const placeIn: (store: EntityStore, connection: Connection, body: AnyQuery, input: Readonly<Record<string, unknown>>, key: string) => RowPlace;
+//#endregion
 //#region src/index.d.ts
 /** What a domain registers: a Remote descriptor, or a `foldkit-entity` Entity (read through `Entity.from`). */
 type EntityLike = EntityDescriptor<any, any> | Domain.AnyEntity;
@@ -2572,6 +2873,12 @@ interface RemoteDescriptor<Entities extends readonly EntityLike[] = readonly Ent
     readonly entities: ReadonlyMap<string, EntityDescriptor<any, any>>;
     readonly queries: ReadonlyMap<string, QueryDescriptor<any, any, any>>;
     readonly mutations: ReadonlyMap<string, MutationDescriptor<any, any, any>>;
+    /**
+     * Per entity name, the members its server filters rows by under a rule
+     * the client does not run (`ReadFilter`), so a change to one is fetched,
+     * not placed.
+     */
+    readonly filtered: ReadonlyMap<string, ReadonlyArray<string>>;
   };
 }
 declare const boundRemoteNames: unique symbol;
@@ -2584,6 +2891,24 @@ interface BoundRemote<AppModel, Store extends RemoteModel, Names extends string
   readonly [boundRemoteNames]?: Names;
 }
 type MutationInput<M> = M extends MutationDescriptor<any, infer Input, any> ? Input : never;
+/** How `Data.persistence` keeps the cache across a reload. */
+interface PersistenceOptions<AppModel> {
+  /**
+   * Where the snapshot is stored, from the Model: one key per principal, so a
+   * change of principal reads and writes another snapshot.
+   */
+  readonly key: (model: AppModel) => string;
+  /** Who the snapshot is for; one taken under another scope is discarded. */
+  readonly scope: (model: AppModel) => string;
+  /** The query connections whose rows survive a reload; none by default. */
+  readonly connections?: ReadonlyArray<ConnectionIdentity> | undefined;
+  /** What to keep, when it is not `snapshotOf` the `connections`. */
+  readonly snapshot?: ((remote: RemoteModel) => Snapshot) | undefined;
+  /** A snapshot larger than this is neither written nor read. */
+  readonly maxBytes?: number | undefined;
+  /** How long the cache must be unchanged before it is written; default 250 milliseconds. */
+  readonly debounce?: Duration.Input | undefined;
+}
 interface DomainMutateOptions {
   /** Overrides the generated id, for a retry, a durable bridge, or a test. */
   readonly requestId?: string | undefined;
@@ -2598,7 +2923,21 @@ interface DomainMutateOptions {
   }) => ReadonlyArray<OptimisticOperation>) | undefined;
   /** The clock `MutationSucceeded` stamps the answer with; default `Date.now`, read at each use. */
   readonly now?: (() => number) | undefined;
+  /**
+   * For a mutation that is a `Write`: the input keys to write, when only some
+   * changed (what an author edited). The rest of the input is still sent, whole.
+   */
+  readonly keys?: ReadonlyArray<string> | undefined;
 }
+/**
+ * One entry of the active record `subscriptions`, `wiring` and `satisfy`
+ * take: a Surface as the Model activates it (`Surface.at`/`Surface.when`),
+ * a source of keyed instances (`Surface.each`, or any `SurfaceSource`), or a
+ * Surface without params read whole. A family joins its parent's
+ * requirements with its instances', so passing the family alone fetches both
+ * the page and what the page reveals.
+ */
+type ActiveEntry<AppModel> = ActiveSurface<AppModel> | Surface<AppModel, any, any, void> | SurfaceSource<AppModel>;
 /** A Foldkit Subscription entry of the Remote domain, emitting its Messages through `RemoteClient`. */
 type RemoteEntry<AppModel, Dependencies> = EntryWithoutKeepAlive<AppModel, RemoteMessage, Dependencies, RemoteClient>;
 /**
@@ -2614,7 +2953,31 @@ interface LiveDependencies {
   readonly requirements: ReadonlyArray<Requirement>;
   readonly cursor: LiveCursor;
   readonly floor: number;
+  /** How many times the stream broke; each break restarts it. */
+  readonly restarts: number;
+  /** Breaks since its last applied event, which the restart's backoff grows with. */
+  readonly failures: number;
 }
+/**
+ * Whether what an active entry reads live is arriving. `Reconnecting` is a
+ * stream that broke and waits to resubscribe; until it has, changes are
+ * missed, and its rows may be out of date.
+ */
+type LiveStatus =
+/** It reads nothing live. */
+{
+  readonly _tag: 'Idle';
+} |
+/** Subscribed, and not broken since. */
+{
+  readonly _tag: 'Live';
+} | {
+  readonly _tag: 'Reconnecting';
+  /** Breaks in a row, the first being 1. */
+  readonly attempt: number;
+  /** Why it broke; none for a gap in its events. */
+  readonly error: Option.Option<RemoteError>;
+};
 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. */
 type RemoteWiring<AppModel> = Wiring<AppModel, RemoteMessage | RemoteMessageInput, RemoteClient>;
@@ -2672,7 +3035,7 @@ interface RemoteDomain<AppModel, Store extends RemoteModel, Entities extends rea
    * read one connection, so it is not a property of the read.
    */
   explain<Name extends string, Input>(model: AppModel, projection: QueryProjection<AppModel, any, Name, Input>, options?: {
-    readonly surfaces?: Readonly<Record<string, ActiveSurface<AppModel>>> | undefined;
+    readonly surfaces?: Readonly<Record<string, ActiveSurface<AppModel> | SurfaceSource<AppModel>>> | undefined;
   }): QueryExplanation;
   /**
    * Why a read shows what it shows, in words. Any Remote read: `Data.get`,
@@ -2684,7 +3047,7 @@ interface RemoteDomain<AppModel, Store extends RemoteModel, Entities extends rea
    * 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;
+    readonly surfaces?: Readonly<Record<string, ActiveSurface<AppModel> | SurfaceSource<AppModel>>> | undefined;
   }): ReadDiagnosis;
   /**
    * The rows of a loaded list that a body matches, decoded as the list decodes
@@ -2717,6 +3080,20 @@ interface RemoteDomain<AppModel, Store extends RemoteModel, Entities extends rea
   overlay(model: AppModel, id: string, optimistic: ReadonlyArray<OptimisticOperation>): AppModel;
   /** Lifts what `overlay` showed under this id. Lifting nothing returns the same Model. */
   lift(model: AppModel, id: string): AppModel;
+  /**
+   * The ids `overlay` shows now, in the order they are drawn, a later one over
+   * an earlier: what a caller that overlays from its own state reconciles
+   * against.
+   */
+  overlays(model: AppModel): ReadonlyArray<string>;
+  /**
+   * The edges a connection shows, as its reads draw them: the server's pages
+   * with pending edits placed, each inserted row where the body's order puts
+   * it (or at the end its overlay names, when it cannot be placed), minus
+   * removed edges and tombstones. Takes the `RemoteModel`, so a persistence
+   * `snapshot` can store a list as it is shown.
+   */
+  visibleItems(remote: RemoteModel, connection: ConnectionIdentity): ReadonlyArray<Edge>;
   /** `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. */
@@ -2730,16 +3107,18 @@ interface RemoteDomain<AppModel, Store extends RemoteModel, Entities extends rea
    */
   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 (`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>;
+   * The Foldkit Subscription entries for the active record, keyed for
+   * `Subscription.make`: a read entry per record entry (`Remote.observe`), a
+   * live entry per record entry that reads through `live` (`Remote.live`), and
+   * one retain entry (`Remote.retain`). A `Surface.each` family is one record
+   * entry whose read unions its parent's requirements with its instances'.
+   * 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, ActiveEntry<AppModel>>>>(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. */
@@ -2786,7 +3165,7 @@ interface RemoteDomain<AppModel, Store extends RemoteModel, Entities extends rea
    * `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>;
+  satisfy(model: AppModel, active: Readonly<Record<string, ActiveEntry<AppModel>>>, 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
@@ -2799,6 +3178,18 @@ interface RemoteDomain<AppModel, Store extends RemoteModel, Entities extends rea
    * pending, applied, or failed with the error the server or transport gave.
    */
   mutation(model: AppModel, requestId: string): MutationStatus;
+  /**
+   * Why the server refused a mutation, as the value its `Refusal` declares:
+   * none while it is pending or applied, when it failed for another reason,
+   * or when the refusal does not decode as `mutation`'s.
+   */
+  refusal<Refused>(model: AppModel, requestId: string, mutation: MutationDescriptor<string, any, any, Refused>): Option.Option<Refused>;
+  /**
+   * Whether what `active` reads live is arriving: `Reconnecting` from the
+   * moment its stream breaks until it resubscribes, which its live entry does
+   * on its own, with backoff.
+   */
+  liveStatus(model: AppModel, active: ActiveEntry<AppModel>): LiveStatus;
   /** `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;
   /**
@@ -2808,7 +3199,17 @@ interface RemoteDomain<AppModel, Store extends RemoteModel, Entities extends rea
    * most one Remote wiring: every domain claims the same tags, and routing
    * takes the first claimant.
    */
-  wiring: <const Active extends Readonly<Record<string, ActiveSurface<AppModel> | Surface<AppModel, any, any, void>>>>(active: Active, options?: SubscriptionsOptions) => RemoteWiring<AppModel>;
+  wiring: <const Active extends Readonly<Record<string, ActiveEntry<AppModel>>>>(active: Active, options?: SubscriptionsOptions) => RemoteWiring<AppModel>;
+  /**
+   * Keeps the cache across a reload, as a wiring beside `wiring`: at start and
+   * whenever `key` changes, the stored snapshot is restored (`Hydrated`, with
+   * what the store already holds kept over it, so a page resumed from the
+   * server wins); and the cache is written back when it changes, once its own
+   * snapshot is in. Overlays, optimistic layers, the mutation ledger, live
+   * cursors and gaps are never stored. A change of principal should `forget`
+   * in `update`, and name another `key`.
+   */
+  persistence(options: PersistenceOptions<AppModel>): Wiring<AppModel, RemoteMessage, KeyValueStore.KeyValueStore>;
   /** `Remote.inspect` of the bound slice. */
   inspect(model: AppModel): RemoteInspection;
 }
@@ -2830,7 +3231,7 @@ interface RemoteFold<AppModel, ParentMessage, Domain extends RemoteDomain<AppMod
   /** `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) => SubscriptionEntries<AppModel, Active, ParentMessage>;
+  readonly subscriptions: <const Active extends Readonly<Record<string, ActiveEntry<AppModel>>>>(active: Active, options?: SubscriptionsOptions) => SubscriptionEntries<AppModel, Active, ParentMessage>;
 }
 /** The application Model a bound domain is over. */
 type ModelOfDomain<Domain> = Domain extends RemoteDomain<infer AppModel, any, any, any, any> ? AppModel : never;
@@ -2916,6 +3317,13 @@ declare class RemoteUnsatisfied extends RemoteUnsatisfied_base {}
 interface LiveOptions {
   /** The clock `LiveReceived` stamps events with; default `Date.now`, read at each use. */
   readonly now?: (() => number) | undefined;
+  /**
+   * The first restart's delay after a stream breaks, doubled for each break in
+   * a row, with ±20% jitter: Sync's transport policy. Default `50 millis`.
+   */
+  readonly retryBase?: Duration.Input | undefined;
+  /** The longest a restart waits. Default `5 seconds`. */
+  readonly maxRetryDelay?: Duration.Input | undefined;
 }
 /** A query the read entry runs, as its dependencies carry it: plain data Foldkit compares. */
 declare const PlannedQuery: Schema.Struct<{
@@ -2979,6 +3387,8 @@ declare const Remote: {
       error: Schema.Struct<{
         readonly _tag: Schema.String;
         readonly message: Schema.String;
+        readonly refusal: Schema.optional<Schema.Unknown>;
+        readonly reason: Schema.optional<Schema.String>;
       }>;
       stream: Schema.optional<Schema.String>;
     };
@@ -3003,6 +3413,7 @@ declare const Remote: {
     };
     Hydrated: {
       connections: Schema.optional<Schema.Unknown>;
+      from: Schema.optional<Schema.String>;
       entities: Schema.Unknown;
       merge: Schema.Union<readonly [Schema.Literal<"replace">, Schema.Literal<"preserve-existing">]>;
     };
@@ -3029,6 +3440,8 @@ declare const Remote: {
       error: Schema.Struct<{
         readonly _tag: Schema.String;
         readonly message: Schema.String;
+        readonly refusal: Schema.optional<Schema.Unknown>;
+        readonly reason: Schema.optional<Schema.String>;
       }>;
     };
     OverlayShown: {
@@ -3079,6 +3492,8 @@ declare const Remote: {
       error: Schema.Struct<{
         readonly _tag: Schema.String;
         readonly message: Schema.String;
+        readonly refusal: Schema.optional<Schema.Unknown>;
+        readonly reason: Schema.optional<Schema.String>;
       }>;
     };
   };
@@ -3116,6 +3531,8 @@ declare const Remote: {
       error: Schema.Struct<{
         readonly _tag: Schema.String;
         readonly message: Schema.String;
+        readonly refusal: Schema.optional<Schema.Unknown>;
+        readonly reason: Schema.optional<Schema.String>;
       }>;
       stream: Schema.optional<Schema.String>;
     };
@@ -3140,6 +3557,7 @@ declare const Remote: {
     };
     Hydrated: {
       connections: Schema.optional<Schema.Unknown>;
+      from: Schema.optional<Schema.String>;
       entities: Schema.Unknown;
       merge: Schema.Union<readonly [Schema.Literal<"replace">, Schema.Literal<"preserve-existing">]>;
     };
@@ -3166,6 +3584,8 @@ declare const Remote: {
       error: Schema.Struct<{
         readonly _tag: Schema.String;
         readonly message: Schema.String;
+        readonly refusal: Schema.optional<Schema.Unknown>;
+        readonly reason: Schema.optional<Schema.String>;
       }>;
     };
     OverlayShown: {
@@ -3216,6 +3636,8 @@ declare const Remote: {
       error: Schema.Struct<{
         readonly _tag: Schema.String;
         readonly message: Schema.String;
+        readonly refusal: Schema.optional<Schema.Unknown>;
+        readonly reason: Schema.optional<Schema.String>;
       }>;
     };
   }>;
@@ -3267,13 +3689,22 @@ declare const Remote: {
     readonly entities: Entities;
     readonly queries?: Queries;
     readonly mutations?: Mutations;
+    /**
+     * Places what the server said (a mutation's answer, a read, a live
+     * patch) as usual, and also fetches each list it placed in, comparing the
+     * server's first page with the order it placed: a disagreement is kept in
+     * `placementMismatches` (`Data.inspect`). A pending edit is not checked,
+     * since the server does not have it yet. For development and tests, where
+     * a collation that drifts should be found.
+     */
+    readonly verifyPlacement?: boolean | undefined;
   }) => RemoteDomain<AppModel, Store, Entities, Queries, Mutations>;
   /**
    * Declares a Remote domain without binding it: its entities, queries, and
    * mutations, plus the submodel. For a domain reused across applications or
    * bound in a test; `Remote.make` is the one-step form.
    */
-  define: <const Entities extends readonly EntityLike[], const Queries extends readonly QueryDescriptor<any, any, any>[] = readonly QueryDescriptor<any, any, any>[], const Mutations extends readonly MutationDescriptor<any, any, any>[] = readonly MutationDescriptor<any, any, any>[]>(config: {
+  define: <const Entities extends readonly EntityLike[], const Queries extends readonly QueryDescriptor<any, any, any>[] = readonly QueryDescriptor<any, any, any>[], const Mutations extends readonly MutationDescriptor<any, any, any>[] = readonly MutationDescriptor<any, any, any, unknown>[]>(config: {
     readonly entities: Entities;
     readonly queries?: Queries;
     readonly mutations?: Mutations;
@@ -3401,8 +3832,16 @@ declare const Remote: {
    * request to `url`. `headers` is read per request (a session token, say).
    */
   http: (url: string, options?: {
-    readonly headers?: () => Readonly<Record<string, string>>;
+    readonly headers?: (() => Readonly<Record<string, string>>) | undefined;
+    readonly fetch?: typeof fetch | undefined;
   }) => RemoteRpcClient;
+  /**
+   * Remote's client over HTTP with live, for `clientLayer`: reads, queries,
+   * and mutations as `http` sends them, live requirements as one `POST`
+   * answered with a `text/event-stream` of changes.
+   * `foldkit-remote-server/fetch` is the other end.
+   */
+  httpWithLive: (url: string, options?: LiveFetchOptions) => RemoteRpcClient;
   clientLayer: <R = never>(client: RemoteRpcClient<R, RpcClientError.RpcClientError>, options?: CoalesceOptions) => Layer.Layer<RemoteClient, never, R>;
   /**
    * Wraps a `RemoteClient` layer so its reads coalesce: requirements issued
@@ -3461,12 +3900,6 @@ declare const Remote: {
   }, 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>, 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
-   * target is a tombstone.
-   */
-  visibleItems: (model: RemoteModel, connection: ConnectionIdentity) => ReadonlyArray<Edge>;
   /** A pure, serializable view of the whole cache. */
   inspect: (model: RemoteModel) => RemoteInspection;
   /** A pure, serializable view of one entity, or `undefined` if unknown. */
@@ -3476,7 +3909,7 @@ declare const Remote: {
    * returning the result's normalized patches so the caller can reconcile them
    * through `updateRemote`'s `MutationSucceeded` (or `Remote.mutateInto`).
    */
-  mutate: <Name extends string, Input, Output>(mutation: MutationDescriptor<Name, Input, Output>, input: Input, requestId: string) => Effect.Effect<{
+  mutate: <Name extends string, Input, Output>(mutation: MutationDescriptor<Name, Input, Output, unknown>, input: Input, requestId: string, keys?: readonly string[] | undefined) => Effect.Effect<{
     output: Output;
     entities: readonly {
       readonly entity: string;
@@ -3490,7 +3923,7 @@ declare const Remote: {
       readonly entity: string;
       readonly id: string;
     }[];
-  }, RemoteMutationError, RemoteClient>;
+  }, RemoteMutationError | RemoteForbidden, RemoteClient>;
   /**
    * Runs a mutation and reconciles its patches into a `RemoteModel` in one step,
    * returning the new model alongside the typed Output. The model-level form of
@@ -3498,10 +3931,10 @@ declare const Remote: {
    * application the three are `update` (with `optimistic`), a Command, and the
    * Message the Command returns, so the optimistic operations show meanwhile.
    */
-  mutateInto: <Name extends string, Input, Output, AppModel, Store extends RemoteModel>(bound: BoundRemote<AppModel, Store, string>, model: AppModel, mutation: MutationDescriptor<Name, Input, Output>, input: Input, requestId: string, options?: MutateOptions | undefined) => Effect.Effect<{
+  mutateInto: <Name extends string, Input, Output, AppModel, Store extends RemoteModel>(bound: BoundRemote<AppModel, Store, string>, model: AppModel, mutation: MutationDescriptor<Name, Input, Output, unknown>, input: Input, requestId: string, options?: MutateOptions | undefined) => Effect.Effect<{
     output: Output;
     model: AppModel;
-  }, RemoteMutationError, RemoteClient>;
+  }, RemoteMutationError | RemoteForbidden, RemoteClient>;
   /**
    * A Foldkit Subscription entry that plans a Surface's missing fields from the
    * Model and fetches them through `RemoteClient`, emitting a `RemoteMessage`
@@ -3516,11 +3949,12 @@ declare const Remote: {
    * requirements, emitting a `LiveReceived` per event and a `ReadFailed`
    * carrying its `stream` when the stream breaks (including
    * `ResumeUnavailable`). That records a gap on the stream rather than a failed
-   * read, since nothing was being read. The resume cursor is read
+   * read, since nothing was being read, and restarts the entry after a
+   * backoff; the restart refetches what it covers. 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, LiveDependencies, RemoteClient>;
 };
 //#endregion
-export { Entity$2 as $, isGapped as $i, Snapshot as $n, ResultOf as $r, failureOf as $t, SelectsEntity as A, readField as Ai, PageSize as An, pruneOverlays as Ar, RemoteJsonRequest as At, ExplainedDependencies as B, remoteDataSchema as Bi, RelationRequest as Bn, RemoteRequirements as Br, CoalesceOptions as Bt, RemoteDomain as C, entry as Ci, LiveRequirement as Cn, OptimisticOperation as Cr, isRefPage as Ct, RemoteWiring as D, isTombstone as Di, MutationRequest as Dn, beginOptimistic as Dr, relationShape as Dt, RemoteUnsatisfied as E, isFieldUnavailable as Ei, Mutate as En, addOverlay as Er, relationAlias as Et, PlanFreshness as F, writeEntities as Fi, REMOTE_PROTOCOL_VERSION as Fn, visibleItems as Fr, connectionChangeOf as Ft, inspectRemote as G, Edge as Gi, RemoteReadError as Gn, IDENTITY_SEPARATOR as Gr, RemoteResumePart as Gt, ReadDiagnosis as H, Boundary as Hi, RemoteMutationError as Hn, connectionsOf as Hr, coalesceQueries as Ht, PlanOptions as I, writeEntity as Ii, Read as In, visibleStore as Ir, liveEventOf as It, Matched as J, cursor as Ji, WindowSchema as Jn, Query$1 as Jr, RemoteMessage as Jt, Belongs as K, EdgeRef as Ki, RemoteRpc as Kn, LiveInsertion as Kr, Failures as Kt, deadlineOf as L, Freshness as Li, ReadBatch as Ln, ConnectionRequirement as Lr, mutateRemote as Lt, SubscriptionsOptions as M, setStale as Mi, QueryRequest as Mn, removeOverlay as Mr, RemoteClient as Mt, RemotePolicy as N, setUnavailable as Ni, QueryResult as Nn, settleFailure as Nr, RemoteRpcClient as Nt, RetainOptions as O, markStale as Oi, MutationResult as On, connectionIdentity as Or, targetsOf as Ot, Deadline as P, tombstone as Pi, QueryRpc as Pn, settleSuccess as Pr, coalescedLayer as Pt, AnySchema as Q, hasPrevious as Qi, RemotePersistence as Qn, QueryWindow as Qr, emptyRefresh as Qt, plan as R, RemoteData as Ri, ReadBatchResult as Rn, RelationRequirement as Rr, remoteError as Rt, RemoteDescriptor as S, entityKey as Si, LiveEdge as Sn, EntityLayer as Sr, aliasedField as St, RemoteFold as T, isFieldStale as Ti, MAX_RELATION_DEPTH as Tn, addLayer as Tr, refsIn as Tt, RemoteInspection as U, Connection as Ui, RemoteProtocolError as Un, requirementsOf as Ur, coalesceReads as Ut, QueryExplanation as V, remoteErrorSchema as Vi, RemoteLiveError as Vn, Requirement as Vr, QueryRun as Vt, inspectEntity as W, Cursor as Wi, RemoteQueryError as Wn, ConnectionSpec as Wr, requirementKey as Wt, belongsEncoded as X, emptyConnection as Xi, MergePolicy as Xn, QueryInputs as Xr, RemoteMessageTag as Xt, MatchingOptions as Y, edge as Yi, WireBoundary as Yn, QueryDescriptor as Yr, RemoteMessageInput as Yt, matching as Z, hasNext as Zi, REMOTE_CACHE_VERSION as Zn, QueryRef as Zr, RemoteModel as Zt, QueryWindowOptions as _, EntityKey as _i, withRefreshRequested as _n, liveHasNext as _r, RefParts as _t, FoldedMutationStarted as a, MutationStatus as ai, isQueryLoading as an, reachable as ar, RefPage as at, Registered as b, clearStale as bi, Live as bn, ConnectionIdentity as br, RelationKind as bt, ModelOfDomain as c, SchemaOrFields as ci, onlyOverlaid as cn, EntityApplied as cr, SelectionOf as ct, ObserveOptions as d, emptyMutationState as di, remoteMessageCases as dn, LiveOutcome as dr, assemble as dt, items as ea, stableStringify as ei, forgetRemote as en, SnapshotOptions as er, EntityDescriptor as et, QueryEntity as f, failMutation as fi, remoteMessageSchema as fn, LiveState as fr, pageSchema as ft, QueryRequirement as g, EntityEntry as gi, windowGrowthKey as gn, emptyLiveState as gr, RefPageValue as gt, QueryProjection as h, schemaOf as hi, updateRemote as hn, classifyLive as hr, RELATION_ALIAS as ht, EntitySelection as i, unknown as ia, MutationState as ii, isLoadingThrough as in, gc as ir, RefKey as it, SubscriptionEntries as j, remove as ji, QueryEdge as jn, removeLayer as jr, RemoteJsonSend as jt, SatisfyOptions as k, missingFields as ki, NormalizedEntity as kn, emptyOptimistic as kr, RemoteJsonAnswer as kt, MutateOptions as l, TypeOf as li, refreshIsInFlight as ln, LiveCursor as lr, SelectionValue as lt, QueryOptions as m, reconcileMutation as mi, retentionRootsSchema as mn, applyEntityEvent as mr, unavailableOf as mt, DomainMutateOptions as n, segment as na, MutationAnswer as ni, isFieldFailed as nn, Retained as nr, EntityRef as nt, LiveDependencies as o, NormalizedPatch as oi, isRemoteMessage as on, BoundaryCounts as or, Page as ot, QueryInput as p, mutationStatus as pi, remoteModelSchema as pn, applyConnectionEvent as pr, relationOf as pt, Judged as q, Segment as qi, SettledFields as qn, LivePolicy as qr, RefreshState as qt, EntityLike as r, terminal as ra, MutationDescriptor as ri, isLoading as rn, RetentionRoots as rr, FieldsFrom as rt, LiveOptions as s, Reconciled as si, noFailures as sn, ConnectionApplied as sr, Selection as st, BoundRemote as t, merge as ta, Mutation as ti, initialRemoteModel as tn, ConnectionRoot as tr, EntityPatch as tt, MutationStarted as u, beginMutation as ui, refreshedAt as un, LiveEvent as ur, SelectionValueOf as ut, ReadDependencies as v, EntityStore as vi, writeRead as vn, liveHasPrevious as vr, RelationAnnotation as vt, RemoteEntry as w, hasField as wi, MAX_FIELDS_PER_REQUEST as wn, OptimisticState as wr, refParts as wt, Remote as x, emptyStore as xi, LiveChange as xn, ConnectionOverlay as xr, RelationShape as xt, ReadMeta as y, EntityWrite as yi, ConnectionChangeSchema as yn, ConnectionChange as yr, RelationEntityAnnotation as yt, windowKey as z, RemoteError as zi, ReadRequest as zn, RemoteConnections as zr, BatchRead as zt };
-//# sourceMappingURL=index-njA5CxbS.d.mts.map
+export { Matched as $, writeEntity as $i, RelationRequest as $n, RemoteConnections as $r, RemoteResumePart as $t, RemoteWiring as A, patchOfWrite as Ai, withRefreshRequested as An, emptyLiveState as Ar, refsIn as At, PlanFreshness as B, entry as Bi, MutationRequest as Bn, addOverlay as Br, RemoteClient as Bt, Registered as C, SchemaOrFields as Ci, refreshedAt as Cn, LiveCursor as Cr, RelationAnnotation as Ct, RemoteEntry as D, failMutation as Di, retentionRootsSchema as Dn, applyConnectionEvent as Dr, aliasedField as Dt, RemoteDomain as E, emptyMutationState as Ei, remoteModelSchema as En, LiveState as Er, RelationShape as Et, SubscriptionsOptions as F, EntityStore as Fi, LiveEdge as Fn, ConnectionOverlay as Fr, httpWithLive as Ft, ExplainedDependencies as G, markStale as Gi, QueryRequest as Gn, removeLayer as Gr, mutateRemote as Gt, deadlineOf as H, isFieldStale as Hi, NormalizedEntity as Hn, connectionIdentity as Hr, coalescedLayer as Ht, RowPlace as I, EntityWrite as Ii, LiveRequirement as In, EntityLayer as Ir, liveFetch as It, RemoteInspection as J, remove as Ji, REMOTE_PROTOCOL_VERSION as Jn, settleSuccess as Jr, CoalesceOptions as Jt, QueryExplanation as K, missingFields as Ki, QueryResult as Kn, removeOverlay as Kr, remoteError as Kt, placeIn as L, clearStale as Li, MAX_FIELDS_PER_REQUEST as Ln, OptimisticOperation as Lr, RemoteJsonAnswer as Lt, SatisfyOptions as M, schemaOf as Mi, ConnectionChangeSchema as Mn, liveHasPrevious as Mr, relationShape as Mt, SelectsEntity as N, EntityEntry as Ni, Live as Nn, ConnectionChange as Nr, targetsOf as Nt, RemoteFold as O, mutationStatus as Oi, updateRemote as On, applyEntityEvent as Or, isRefPage as Ot, SubscriptionEntries as P, EntityKey as Pi, LiveChange as Pn, ConnectionIdentity as Pr, LiveFetchOptions as Pt, Judged as Q, writeEntities as Qi, ReadRequest as Qn, RelationRequirement as Qr, requirementKey as Qt, RemotePolicy as R, emptyStore as Ri, MAX_RELATION_DEPTH as Rn, OptimisticState as Rr, RemoteJsonRequest as Rt, ReadMeta as S, Refusal as Si, refreshIsInFlight as Sn, EntityApplied as Sr, RefParts as St, RemoteDescriptor as T, beginMutation as Ti, remoteMessageSchema as Tn, LiveOutcome as Tr, RelationKind as Tt, plan as U, isFieldUnavailable as Ui, PageSize as Un, emptyOptimistic as Ur, connectionChangeOf as Ut, PlanOptions as V, hasField as Vi, MutationResult as Vn, beginOptimistic as Vr, RemoteRpcClient as Vt, windowKey as W, isTombstone as Wi, QueryEdge as Wn, pruneOverlays as Wr, liveEventOf as Wt, inspectRemote as X, setUnavailable as Xi, ReadBatch as Xn, visibleStore as Xr, coalesceQueries as Xt, inspectEntity as Y, setStale as Yi, Read as Yn, visibleItems as Yr, QueryRun as Yt, Belongs as Z, tombstone as Zi, ReadBatchResult as Zn, ConnectionRequirement as Zr, coalesceReads as Zt, QueryOptions as _, items as _a, MutationDescriptor as _i, isQueryLoading as _n, RetentionRoots as _r, pageSchema as _t, EntitySelection as a, Boundary as aa, IDENTITY_SEPARATOR as ai, RemoteMessageInput as an, RemoteReadError as ar, EntityDescriptor as at, QueryWindowOptions as b, terminal as ba, NormalizedPatch as bi, onlyOverlaid as bn, BoundaryCounts as br, RELATION_ALIAS as bt, LiveOptions as c, Edge as ca, Query$1 as ci, StreamHealth as cn, WindowSchema as cr, FieldsFrom as ct, MutateOptions as d, cursor as da, QueryRef as di, forgetRemote as dn, REMOTE_CACHE_VERSION as dr, Page as dt, Freshness as ea, RemoteRequirements as ei, Failures as en, RemoteForbidden as er, MatchingOptions as et, MutationStarted as f, edge as fa, QueryWindow as fi, initialRemoteModel as fn, RemotePersistence as fr, Selection as ft, QueryInput as g, isGapped as ga, MutationAnswer as gi, isLoadingThrough as gn, Retained as gr, assemble as gt, QueryEntity as h, hasPrevious as ha, Mutation as hi, isLoading as hn, ConnectionRoot as hr, SelectionValueOf as ht, EntityLike as i, remoteErrorSchema as ia, ConnectionSpec as ii, RemoteMessage as in, RemoteQueryError as ir, Entity$2 as it, RetainOptions as j, reconcileMutation as ji, writeRead as jn, liveHasNext as jr, relationAlias as jt, RemoteUnsatisfied as k, optimisticOfWrite as ki, windowGrowthKey as kn, classifyLive as kr, refParts as kt, LiveStatus as l, EdgeRef as la, QueryDescriptor as li, emptyRefresh as ln, WireBoundary as lr, RefKey as lt, PersistenceOptions as m, hasNext as ma, stableStringify as mi, isFieldFailed as mn, SnapshotOptions as mr, SelectionValue as mt, BoundRemote as n, RemoteError as na, connectionsOf as ni, PlacementMismatch as nn, RemoteMutationError as nr, matching as nt, FoldedMutationStarted as o, Connection as oa, LiveInsertion as oi, RemoteMessageTag as on, RemoteRpc as or, EntityPatch as ot, ObserveOptions as p, emptyConnection as pa, ResultOf as pi, invalidateConnections as pn, Snapshot as pr, SelectionOf as pt, ReadDiagnosis as q, readField as qi, QueryRpc as qn, settleFailure as qr, BatchRead as qt, DomainMutateOptions as r, remoteDataSchema as ra, requirementsOf as ri, RefreshState as rn, RemoteProtocolError as rr, AnySchema as rt, LiveDependencies as s, Cursor as sa, LivePolicy as si, RemoteModel as sn, SettledFields as sr, EntityRef as st, ActiveEntry as t, RemoteData as ta, Requirement as ti, PlacedOrder as tn, RemoteLiveError as tr, belongsEncoded as tt, ModelOfDomain as u, Segment as ua, QueryInputs as ui, failureOf as un, MergePolicy as ur, RefPage as ut, QueryProjection as v, merge as va, MutationState as vi, isRemoteMessage as vn, gc as vr, relationOf as vt, Remote as w, TypeOf as wi, remoteMessageCases as wn, LiveEvent as wr, RelationEntityAnnotation as wt, ReadDependencies as x, unknown as xa, Reconciled as xi, overlaysOf as xn, ConnectionApplied as xr, RefPageValue as xt, QueryRequirement as y, segment as ya, MutationStatus as yi, noFailures as yn, reachable as yr, unavailableOf as yt, Deadline as z, entityKey as zi, Mutate as zn, addLayer as zr, RemoteJsonSend as zt };
+//# sourceMappingURL=index-CXAGo7Dz.d.mts.map