foldkit-remote 0.18.1 → 0.20.0

package/dist/{index-86gaaCWm.d.mts → index-BEvVAL76.d.mts}

@@ -1,13 +1,12 @@
 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, AnyWrite, BoundWrite, Dependencies, InputExpr, Query, Write } from "foldkit-entity";
+import { AnyEntity, AnyQuery, AnyWrite, BoundWrite, ConditionedWrite, Dependencies, InputExpr, Invariant, MemoryOperators, Query, Write } from "foldkit-entity";
 import { Command } from "foldkit/command";
 import { EntryWithoutKeepAlive } from "foldkit/subscription";
 import { ActiveSurface, Contract, Invalid, Metadata, ModelRef, Projection, Surface, SurfaceSource, Wiring } from "foldkit-surface";
 import { Rpc, RpcClientError, RpcGroup } from "effect/rpc";
 import * as Update from "foldkit/update";
-//#region src/store.d.ts
 type EntityKey = string;
 interface EntityEntry {
   readonly values: Readonly<Record<string, unknown>>;
@@ -92,8 +91,6 @@ declare const readField: (store: EntityStore, key: EntityKey, field: string) =>
  * writer that does not record windows cannot cause a refetch loop.
  */
 declare const missingFields: (store: EntityStore, key: EntityKey, fields: Iterable<string>, windows?: Readonly<Record<string, string>>) => ReadonlyArray<string>;
-//#endregion
-//#region src/connection.d.ts
 interface EdgeRef {
   readonly entity: string;
   readonly id: string;
@@ -137,8 +134,6 @@ declare const hasPrevious: (connection: Connection) => boolean;
 declare const hasNext: (connection: Connection) => boolean;
 /** A connection with more than one segment has an explicit unknown gap. */
 declare const isGapped: (connection: Connection) => boolean;
-//#endregion
-//#region src/remoteData.d.ts
 interface RemoteError {
   readonly _tag: string;
   readonly message: string;
@@ -272,19 +267,30 @@ declare const RemoteData: {
   denied: (error: RemoteError) => Option.Option<Denied>;
   map: <A, B>(data: RemoteData<A>, f: (value: A) => B) => RemoteData<B>;
 };
-//#endregion
-//#region src/mutation.d.ts
 interface NormalizedPatch {
   readonly entity: string;
   readonly id: string;
   readonly values: Readonly<Record<string, unknown>>;
 }
+/**
+ * A patch a pending request shows, and the amounts it moves fields by: each
+ * added, whenever the store is read, to the value under it, so a change that
+ * reaches the store meanwhile is added to, not hidden.
+ */
+interface PendingPatch extends NormalizedPatch {
+  readonly adds?: Readonly<Record<string, number>>;
+}
 interface MutationState {
   readonly pending: ReadonlySet<string>;
   readonly applied: ReadonlySet<string>;
   readonly failed: ReadonlySet<string>;
   /** Why each request in `failed` failed, kept exactly as long as `failed` keeps its id. */
   readonly errors: ReadonlyMap<string, RemoteError>;
+  /**
+   * The operation id each request in `failed` was sent with, kept as `errors`
+   * is: a retry of that request id sends it again, so a server recognises it.
+   */
+  readonly operations: ReadonlyMap<string, string>;
   /**
    * How many mutations this model has started. A bound domain takes its next
    * request id from here, so `update` stays pure and the id exists before the
@@ -294,7 +300,7 @@ interface MutationState {
 }
 declare const emptyMutationState: MutationState;
 declare const beginMutation: (state: MutationState, requestId: string) => MutationState;
-declare const failMutation: (state: MutationState, requestId: string, error: RemoteError) => MutationState;
+declare const failMutation: (state: MutationState, requestId: string, error: RemoteError, operation: string) => MutationState;
 /** What Remote knows of one mutation request, by the id `mutate` returned. */
 type MutationStatus =
 /** Never started here, or settled so long ago its id has left the window. */
@@ -347,6 +353,18 @@ interface MutationDescriptor<Name extends string, Input, Output, Refused = unkno
    */
   readonly write?: AnyWrite | undefined;
 }
+declare const conflict: Schema.TaggedStruct<"Conflict", {}>;
+declare const unmet: Schema.TaggedStruct<"Unmet", {}>;
+/**
+ * The row the write would leave breaks one of its Entity's invariants: which
+ * one, what to tell the author, and the fields to show it beside. None and
+ * empty when the invariant reads a member hidden from whoever asked.
+ */
+declare const invalid: Schema.TaggedStruct<"Invalid", {
+  readonly rule: Schema.OptionFromNullOr<Schema.String>;
+  readonly message: Schema.String;
+  readonly path: Schema.$Array<Schema.String>;
+}>;
 /** 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. */
@@ -356,6 +374,14 @@ declare const Refusal: {
   }>;
   /** The row moved on since the client read it; the author decides what wins. */
   conflict: Schema.TaggedStruct<"Conflict", {}>;
+  /** The row does not hold what the write's `when` asks of it, where it would commit. */
+  unmet: Schema.TaggedStruct<"Unmet", {}>;
+  /** The row the write would leave breaks an invariant of its Entity. */
+  invalid: Schema.TaggedStruct<"Invalid", {
+    readonly rule: Schema.OptionFromNullOr<Schema.String>;
+    readonly message: Schema.String;
+    readonly path: Schema.$Array<Schema.String>;
+  }>;
   /** Whether a refusal, of whatever mutation, is a `Refusal.field`. */
   isField: <I>(input: I) => input is I & {
     readonly _tag: "Field";
@@ -366,7 +392,30 @@ declare const Refusal: {
   isConflict: <I>(input: I) => input is I & {
     readonly _tag: "Conflict";
   };
+  /** Whether a refusal, of whatever mutation, is `Refusal.unmet`. */
+  isUnmet: <I>(input: I) => input is I & {
+    readonly _tag: "Unmet";
+  };
+  /** Whether a refusal, of whatever mutation, is `Refusal.invalid`. */
+  isInvalid: <I>(input: I) => input is I & {
+    readonly _tag: "Invalid";
+    readonly rule: Option.Option<string>;
+    readonly message: string;
+    readonly path: readonly string[];
+  };
+  /**
+   * Whether a refusal is `Refusal.invalid` naming this invariant: the one
+   * `Entity.invariant` returned, or one `Entity.invariants` reads. An invariant
+   * over a member hidden from the asker names none, so it matches nothing.
+   */
+  isInvalidBy: (refusal: unknown, invariant: Pick<Invariant, 'id'>) => boolean;
 };
+/**
+ * What a declared write may be refused with: unmet too, when it has a `when`,
+ * and invalid always, since the server's Entity may hold invariants the
+ * client's does not show.
+ */
+type RefusalOfWrite<W> = (W extends ConditionedWrite<any, any> ? typeof conflict.Type | typeof unmet.Type : typeof conflict.Type) | typeof invalid.Type;
 /** 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. */
@@ -381,10 +430,10 @@ 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
+ * are), and an update's increments as amounts over the value the store holds. 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 optimisticOfWrite: (write: AnyWrite, input: unknown, keys: ReadonlyArray<string> | undefined) => ReadonlyArray<PendingPatch>;
 declare const Mutation: {
   /**
    * Declares a mutation. `Input` and `Output` are codecs, or the fields of the
@@ -396,10 +445,11 @@ declare const Mutation: {
    * 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.
+   * `expect`s a revision the row has moved past, for a write with a `when` as
+   * unmet, and as invalid when the row it would leave breaks an invariant.
    */
-  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>;
+  write: <const Name extends string, Fields extends Schema.Struct.Fields, W extends Write<any, Fields> = Write<any, Fields>>(name: Name, write: W & Write<any, Fields>) => MutationDescriptor<Name, Schema.Struct.Type<Fields>, {}, RefusalOfWrite<W>> & {
+    readonly write: W;
   };
   make: <const Name extends string, Input extends SchemaOrFields, Output extends SchemaOrFields, Refused = never>(name: Name, config: {
     readonly Input: Input;
@@ -407,11 +457,9 @@ declare const Mutation: {
     readonly Refusal?: Schema.Codec<Refused, any>;
   }) => MutationDescriptor<Name, TypeOf<Input>, TypeOf<Output>, Refused>;
 };
-//#endregion
-//#region src/optimistic.d.ts
 interface EntityLayer {
   readonly id: string;
-  readonly patches: ReadonlyArray<NormalizedPatch>;
+  readonly patches: ReadonlyArray<PendingPatch>;
 }
 /**
  * Edges placed outside a connection's server-known region (`prepend`,
@@ -436,7 +484,7 @@ type ConnectionChange = {
   readonly edge: Edge;
 };
 /** What a request changes before the server answers: entity patches and connection changes. */
-type OptimisticOperation = NormalizedPatch | ConnectionChange;
+type OptimisticOperation = PendingPatch | ConnectionChange;
 /** A connection, by identity string or by anything that carries one (a `QueryRef`). */
 type ConnectionIdentity = string | {
   readonly identity: string;
@@ -487,6 +535,13 @@ declare const removeOverlay: (optimistic: OptimisticState, id: string) => Optimi
  * is dated `Infinity`, so freshness never plans or times it.
  */
 declare const visibleStore: (base: EntityStore, optimistic: OptimisticState) => EntityStore;
+/**
+ * Every pending patch in order, each amount added to the value under it: the
+ * store's, or an earlier layer's. A prediction, so only over a number the
+ * client holds: a field it has not read, or holds as anything else, keeps
+ * what it shows until the server answers with the sum.
+ */
+declare const resolvedPatches: (base: EntityStore, optimistic: OptimisticState) => ReadonlyArray<NormalizedPatch>;
 /**
  * A fresh page is newer than any settled overlay it covers: an edge the page
  * carries no longer needs an insert overlay, and a `remove` overlay hiding it
@@ -519,8 +574,6 @@ declare const settleFailure: (optimistic: OptimisticState, requestId: string) =>
  * Boundaries still come from the connection's segments.
  */
 declare const visibleItems: (connection: Connection, connectionId: string, overlays: ReadonlyArray<ConnectionOverlay>, store?: EntityStore) => ReadonlyArray<Edge>;
-//#endregion
-//#region src/query.d.ts
 type LiveInsertion = 'visible' | 'boundary' | 'invalidate' | 'ignore';
 interface LivePolicy {
   readonly prepend?: LiveInsertion;
@@ -592,9 +645,11 @@ declare const Query$1: {
   where: <const P extends ReadonlyArray<import("foldkit-entity").Predicate>>(...predicates: P) => <E extends AnyEntity>(self: Query<E> & (string extends import("foldkit-entity").ReadsOf<P[number]> ? unknown : [import("foldkit-entity").ReadsOf<P[number]>] extends [E["name"]] ? unknown : import("foldkit-entity").Invalid<`foldkit-entity: a predicate reads ${Exclude<import("foldkit-entity").ReadsOf<P[number]>, E["name"]>}, but the query is from ${E["name"]}`>)) => Query<E>;
   orderBy: <const T extends ReadonlyArray<import("foldkit-entity").Ordering>>(...terms: T) => <E extends AnyEntity>(self: Query<E> & (string extends import("foldkit-entity").ReadsOf<T[number]> ? unknown : [import("foldkit-entity").ReadsOf<T[number]>] extends [E["name"]] ? unknown : import("foldkit-entity").Invalid<`foldkit-entity: an ordering term reads ${Exclude<import("foldkit-entity").ReadsOf<T[number]>, E["name"]>}, but the query is from ${E["name"]}`>)) => 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;
+  placement: (self: AnyQuery, input: Readonly<Record<string, unknown>>, options?: {
+    readonly operators?: import("foldkit-entity").OperatorTable | undefined;
+  }) => 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>;
+  unsupported: (self: AnyQuery, supported: ReadonlyArray<import("foldkit-entity").Operation>, operators?: import("foldkit-entity").OperatorTable) => ReadonlyArray<string>;
   show: (self: AnyQuery) => string;
   /** Declares the entity and options a query's result is a connection over. */
   connection: <Entity extends string>(entity: {
@@ -647,8 +702,6 @@ declare const Query$1: {
   after: (cursor: Cursor) => <R extends QueryRef<string, unknown>>(ref: R) => R;
   before: (cursor: Cursor) => <R extends QueryRef<string, unknown>>(ref: R) => R;
 };
-//#endregion
-//#region src/requirement.d.ts
 /**
  * The slice required of an entity. `windows` carries a pagination window per
  * relation field, and `relations` the slice required of each relation's
@@ -706,8 +759,6 @@ declare const requirementsOf: (projection: {
 declare const connectionsOf: (projection: {
   readonly metadata: Metadata;
 }) => ReadonlyArray<ConnectionRequirement>;
-//#endregion
-//#region src/wire.d.ts
 /**
  * The read/live protocol version. A batch names the version it speaks and the
  * server refuses a mismatch with `RemoteProtocolError`, so a shape change never
@@ -801,9 +852,21 @@ declare const ReadBatchResult: Schema.Struct<{
     readonly fields: Schema.$Array<Schema.String>;
   }>>;
 }>;
+/**
+ * One operation's identity across every client: minted where it is first sent
+ * and sent again with each retry of it. Bounded, since a server keys a record
+ * of the write by it.
+ */
+declare const OperationId: Schema.String;
 declare const MutationRequest: Schema.Struct<{
-  /** Stable across transport retries so a mutation is not applied twice. */
+  /**
+   * This client's id for the request, the same on each retry of it. It is
+   * unique within one client's Model only (a counter there), so it names a
+   * request to that client; `operation` names it to a server.
+   */
   readonly requestId: Schema.String;
+  /** The operation's identity across clients: what a server keys a record of the write by. */
+  readonly operation: Schema.optional<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. */
@@ -927,8 +990,14 @@ declare const Read: Rpc.Rpc<"FoldkitRemoteRead", Schema.Struct<{
   }>>;
 }>, Schema.Union<readonly [typeof RemoteReadError, typeof RemoteProtocolError, typeof RemoteUnauthenticated]>, never, never>;
 declare const Mutate: Rpc.Rpc<"FoldkitRemoteMutate", Schema.Struct<{
-  /** Stable across transport retries so a mutation is not applied twice. */
+  /**
+   * This client's id for the request, the same on each retry of it. It is
+   * unique within one client's Model only (a counter there), so it names a
+   * request to that client; `operation` names it to a server.
+   */
   readonly requestId: Schema.String;
+  /** The operation's identity across clients: what a server keys a record of the write by. */
+  readonly operation: Schema.optional<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. */
@@ -1171,8 +1240,14 @@ declare const RemoteRpc: RpcGroup.RpcGroup<Rpc.Rpc<"FoldkitRemoteLive", Schema.S
   readonly cursor: Schema.Number;
   readonly connection: Schema.String;
 }>]>, Schema.Union<readonly [typeof RemoteLiveError, typeof RemoteProtocolError, typeof RemoteUnauthenticated]>>, Schema.Never, never, never> | Rpc.Rpc<"FoldkitRemoteMutate", Schema.Struct<{
-  /** Stable across transport retries so a mutation is not applied twice. */
+  /**
+   * This client's id for the request, the same on each retry of it. It is
+   * unique within one client's Model only (a counter there), so it names a
+   * request to that client; `operation` names it to a server.
+   */
   readonly requestId: Schema.String;
+  /** The operation's identity across clients: what a server keys a record of the write by. */
+  readonly operation: Schema.optional<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. */
@@ -1275,8 +1350,6 @@ declare const RemoteRpc: RpcGroup.RpcGroup<Rpc.Rpc<"FoldkitRemoteLive", Schema.S
     readonly fields: Schema.$Array<Schema.String>;
   }>>;
 }>, Schema.Union<readonly [typeof RemoteReadError, typeof RemoteProtocolError, typeof RemoteUnauthenticated]>, never, never>>;
-//#endregion
-//#region src/coalesce.d.ts
 type Batch = Schema.Schema.Type<typeof ReadBatch>;
 type BatchResult = Schema.Schema.Type<typeof ReadBatchResult>;
 type ReadError = RemoteReadError | RemoteProtocolError | RemoteUnauthenticated;
@@ -1306,8 +1379,6 @@ declare const coalesceQueries: (query: QueryRun, options?: CoalesceOptions) => E
  * idempotent, so writing it more than once is harmless.
  */
 declare const coalesceReads: (read: BatchRead, options?: CoalesceOptions) => Effect.Effect<BatchRead>;
-//#endregion
-//#region src/live.d.ts
 type LiveCursor = number;
 type LiveEvent = {
   readonly _tag: 'EntityPatched';
@@ -1381,8 +1452,6 @@ declare const applyConnectionEvent: (state: LiveState, optimistic: OptimisticSta
 declare const liveHasPrevious: (connection: Connection, state: LiveState, connectionId: string) => boolean;
 /** `hasNext` accounting for edges recorded outside the loaded boundary. */
 declare const liveHasNext: (connection: Connection, state: LiveState, connectionId: string) => boolean;
-//#endregion
-//#region src/client.d.ts
 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 | RemoteUnauthenticated>;
   readonly query: (request: Schema.Schema.Type<typeof QueryRequest>) => Effect.Effect<Schema.Schema.Type<typeof QueryResult>, RemoteQueryError | RemoteUnauthenticated>;
@@ -1424,11 +1493,24 @@ declare const remoteError: (error: {
   readonly reason?: string | undefined;
 }) => RemoteError;
 declare const coalescedLayer: <E, R>(layer: Layer.Layer<RemoteClient, E, R>, options?: CoalesceOptions) => Layer.Layer<RemoteClient, E, R>;
+/**
+ * A new operation's identity: random, so unique across clients and reloads.
+ * `randomUUID` exists only in a secure context, so a page served over plain
+ * HTTP draws 128 random bits from `getRandomValues`, which exists in all.
+ */
+declare const mintOperation: () => string;
 /**
  * `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, unknown>, input: Input, requestId: string, keys?: readonly string[] | undefined) => Effect.Effect<{
+declare const mutateRemote: <Name extends string, Input, Output>(mutation: MutationDescriptor<Name, Input, Output, unknown>, input: Input, requestId: string, options?: {
+  readonly keys?: ReadonlyArray<string> | undefined;
+  /**
+   * The operation's identity across clients, the same on each retry of it:
+   * minted here when not given, so a retry must pass the one first sent.
+   */
+  readonly operation?: string | undefined;
+} | undefined) => Effect.Effect<{
   output: Output;
   entities: readonly {
     readonly entity: string;
@@ -1443,8 +1525,6 @@ declare const mutateRemote: <Name extends string, Input, Output>(mutation: Mutat
     readonly id: string;
   }[];
 }, RemoteForbidden | RemoteMutationError | RemoteUnauthenticated, RemoteClient>;
-//#endregion
-//#region src/relation.d.ts
 interface RefParts {
   readonly entity: string;
   readonly id: string;
@@ -1500,8 +1580,6 @@ declare const isRefPage: (value: unknown) => value is RefPageValue;
  * scalar field, which cannot take a nested selection.
  */
 declare const relationShape: (schema: Schema.Top) => RelationShape | undefined;
-//#endregion
-//#region src/selection.d.ts
 /** One page of a paginated relation with each target assembled through a nested selection. */
 interface Page<Item> {
   readonly items: ReadonlyArray<Item>;
@@ -1582,8 +1660,6 @@ declare const assemble: (store: EntityStore, key: string, requirement: RelationR
  * cannot assemble rather than waiting on a field nothing will fetch.
  */
 declare const unavailableOf: (store: EntityStore, key: string, requirement: RelationRequirement) => string | undefined;
-//#endregion
-//#region src/entity.d.ts
 type AnySchema = Schema.Schema<unknown>;
 declare const entityRefFields: unique symbol;
 /**
@@ -1684,8 +1760,6 @@ declare const Entity$2: {
    */
   patch: <Name extends string, F extends Schema.Struct.Fields>(ref: EntityRef<Name, F>, patch: Partial<Schema.Struct.Encoded<F>>) => EntityPatch<Name, F>;
 };
-//#endregion
-//#region src/matching.d.ts
 /**
  * An answer over the rows the client holds — never over the rows that exist.
  *
@@ -1726,6 +1800,8 @@ interface MatchingOptions {
    * it, a caller narrows to a connection's own edges.
    */
   readonly among?: ReadonlyArray<EntityKey> | undefined;
+  /** How the body's primitive operators are run: `Remote.make`'s `operators`. */
+  readonly operators?: MemoryOperators | undefined;
 }
 /**
  * The rows of `descriptor`'s Entity that the store holds and the body matches.
@@ -1769,9 +1845,7 @@ type Belongs = 'yes' | 'no' | 'unknown';
  * asymmetry with `matching`, which takes a decoded input, is the shape of the
  * two real callers rather than an oversight.
  */
-declare const belongsEncoded: <Name extends string, Input>(store: EntityStore, descriptor: QueryDescriptor<Name, Input, unknown>, encoded: Readonly<Record<string, unknown>>, key: EntityKey) => Belongs;
-//#endregion
-//#region src/retain.d.ts
+declare const belongsEncoded: <Name extends string, Input>(store: EntityStore, descriptor: QueryDescriptor<Name, Input, unknown>, encoded: Readonly<Record<string, unknown>>, key: EntityKey, operators?: MemoryOperators | undefined) => Belongs;
 /** A connection to keep: its identity, and what a page of it selects of each item, if a projection reads it. */
 interface ConnectionRoot {
   readonly identity: string;
@@ -1800,8 +1874,6 @@ declare const reachable: (store: EntityStore, roots: RetentionRoots, connections
 declare const gc: (state: Retained & {
   readonly mutations: MutationState;
 }, roots: RetentionRoots) => Retained;
-//#endregion
-//#region src/persistence.d.ts
 /** Bump when the serialized shape changes; a mismatch discards the cache. */
 declare const REMOTE_CACHE_VERSION = 5;
 /**
@@ -1909,8 +1981,6 @@ declare const RemotePersistence: {
     readonly key: string;
   } & SnapshotOptions) => Effect.Effect<Snapshot, KeyValueStore.KeyValueStoreError, KeyValueStore.KeyValueStore>;
 };
-//#endregion
-//#region src/model.d.ts
 /**
  * The normalized cache as a Foldkit Submodel. `Remote.define` returns a schema
  * and an `update` for this shape; `updateRemote` reconciles every producer.
@@ -2127,6 +2197,8 @@ type RemoteMessage = {
   readonly _tag: 'MutationFailed';
   readonly requestId: string;
   readonly error: RemoteError;
+  /** The operation id it was sent with, for a retry to send again. */
+  readonly operation: string;
 } |
 /**
  * Operations shown over the store with no request behind them, until they are
@@ -2296,6 +2368,7 @@ declare const remoteMessageCases: {
       readonly refusal: Schema.optional<Schema.Unknown>;
       readonly reason: Schema.optional<Schema.String>;
     }>;
+    operation: Schema.String;
   };
   OverlayShown: {
     id: Schema.String;
@@ -2449,8 +2522,6 @@ declare const failureOf: (model: RemoteModel, entity: string, id: string, relati
  * reducing `writeEntity` by hand.
  */
 declare const writeRead: (store: EntityStore, requests: ReadonlyArray<Requirement>, result: Schema.Schema.Type<typeof ReadBatchResult>, now?: number) => EntityStore;
-//#endregion
-//#region src/inspect.d.ts
 /** A query body's `Dependencies` as plain data: each field by its Entity's name and key. */
 interface ExplainedDependencies {
   readonly fields: ReadonlyArray<{
@@ -2459,6 +2530,11 @@ interface ExplainedDependencies {
   }>;
   readonly inputs: Dependencies['inputs'];
   readonly operations: Dependencies['operations'];
+  /** Each operator it calls, by its id and version. */
+  readonly operators: ReadonlyArray<{
+    readonly id: string;
+    readonly version: number;
+  }>;
 }
 /** A serializable summary of a RemoteModel for DevTools and diagnostics. */
 interface RemoteInspection {
@@ -2595,8 +2671,6 @@ interface QueryExplanation {
     readonly tag: string;
   }> | undefined;
 }
-//#endregion
-//#region src/plan.d.ts
 type Window = NonNullable<Requirement['windows']>[string];
 /** A stable key for a window, so two equal windows compare equal. */
 declare const windowKey: (window: Window) => string;
@@ -2628,8 +2702,6 @@ interface Deadline {
  */
 declare const deadlineOf: (store: EntityStore, requirements: readonly Requirement[], freshness: PlanFreshness) => Deadline | undefined;
 declare const plan: (store: EntityStore, requirements: readonly Requirement[], options?: PlanOptions) => ReadonlyArray<Requirement>;
-//#endregion
-//#region src/policy.d.ts
 type RemotePolicy =
 /** Fetch only fields the store lacks (missing, stale, or re-windowed). */
 {
@@ -2669,8 +2741,6 @@ declare const RemotePolicy: {
    */
   refreshes: (policy: RemotePolicy) => boolean;
 };
-//#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.
@@ -2696,8 +2766,6 @@ declare const resumePart: <AppModel, Store extends RemoteModel>(domain: {
 }, options?: {
   readonly id?: string | undefined;
 }) => RemoteResumePart<AppModel>;
-//#endregion
-//#region src/json.d.ts
 /** A request: which of Remote's calls, and its payload as the RPC protocol encodes it. */
 declare const RemoteJsonRequest: Schema.Struct<{
   readonly operation: Schema.Literals<readonly ["read", "query", "mutate"]>;
@@ -2741,8 +2809,6 @@ declare const http: (url: string, options?: {
   readonly headers?: (() => Readonly<Record<string, string>>) | undefined;
   readonly fetch?: typeof fetch | undefined;
 }) => RemoteRpcClient;
-//#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. */
@@ -2757,8 +2823,6 @@ declare const liveFetch: (url: string, options?: LiveFetchOptions) => RemoteRpcC
  * `http` sends them, live as `liveFetch` streams it, for `clientLayer`.
  */
 declare const httpWithLive: (url: string, options?: LiveFetchOptions) => RemoteRpcClient;
-//#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. */
@@ -2874,13 +2938,11 @@ declare const RowPlace: {
 };
 /**
  * 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.
+ * for `input` (encoded, as a connection's identity carries it), a call in it
+ * run by `operators`. 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
+declare const placeIn: (store: EntityStore, connection: Connection, body: AnyQuery, input: Readonly<Record<string, unknown>>, key: string, operators: MemoryOperators) => RowPlace;
 /** What a domain registers: a Remote descriptor, or a `foldkit-entity` Entity (read through `Entity.from`). */
 type EntityLike = EntityDescriptor<any, any> | Domain.AnyEntity;
 /**
@@ -3516,6 +3578,7 @@ declare const Remote: {
         readonly refusal: Schema.optional<Schema.Unknown>;
         readonly reason: Schema.optional<Schema.String>;
       }>;
+      operation: Schema.String;
     };
     OverlayShown: {
       id: Schema.String;
@@ -3659,6 +3722,7 @@ declare const Remote: {
         readonly refusal: Schema.optional<Schema.Unknown>;
         readonly reason: Schema.optional<Schema.String>;
       }>;
+      operation: Schema.String;
     };
     OverlayShown: {
       id: Schema.String;
@@ -3773,6 +3837,13 @@ declare const Remote: {
      * a collation that drifts should be found.
      */
     readonly verifyPlacement?: boolean | undefined;
+    /**
+     * How the client runs a body's primitive operators when it judges rows it
+     * holds (`Operators`): the kernel's when not given. A body calling one this
+     * table lacks is judged by the server instead, as any row the client cannot
+     * judge is.
+     */
+    readonly operators?: MemoryOperators | undefined;
   }) => RemoteDomain<AppModel, Store, Entities, Queries, Mutations>;
   /**
    * Declares a Remote domain without binding it: its entities, queries, and
@@ -3973,7 +4044,10 @@ 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, unknown>, input: Input, requestId: string, keys?: readonly string[] | undefined) => Effect.Effect<{
+  mutate: <Name extends string, Input, Output>(mutation: MutationDescriptor<Name, Input, Output, unknown>, input: Input, requestId: string, options?: {
+    readonly keys?: ReadonlyArray<string> | undefined;
+    readonly operation?: string | undefined;
+  } | undefined) => Effect.Effect<{
     output: Output;
     entities: readonly {
       readonly entity: string;
@@ -4019,6 +4093,5 @@ 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, LiveDependencies, RemoteClient>;
 };
-//#endregion
-export { QueryExplanation as $, merge as $i, coalesceReads as $n, ConnectionIdentity as $r, Entity$2 as $t, RemoteWiring as A, optimisticOfWrite as Ai, RemoteRpcClient as An, RemoteUnauthenticated as Ar, remoteModelSchema as At, liveFetch as B, Boundary as Bi, LiveEvent as Bn, requirementsOf as Br, SnapshotOptions as Bt, Registered as C, writeEntity as Ca, Refusal as Ci, isRefPage as Cn, RemoteForbidden as Cr, noFailures as Ct, RemoteEntry as D, emptyMutationState as Di, relationShape as Dn, RemoteQueryError as Dr, refreshedAt as Dt, RemoteDomain as E, beginMutation as Ei, relationAlias as En, RemoteProtocolError as Er, refreshIsInFlight as Et, SubscriptionsOptions as F, Freshness as Fi, remoteError as Fn, RelationRequirement as Fr, writeRead as Ft, RemotePolicy as G, Segment as Gi, classifyLive as Gn, Query$1 as Gr, reachable as Gt, RemoteJsonRequest as H, Cursor as Hi, LiveState as Hn, IDENTITY_SEPARATOR as Hr, Retained as Ht, RowPlace as I, RemoteData as Ii, BoundaryCounts as In, RemoteConnections as Ir, MergePolicy as It, PlanOptions as J, emptyConnection as Ji, liveHasPrevious as Jn, QueryRef as Jr, Matched as Jt, Deadline as K, cursor as Ki, emptyLiveState as Kn, QueryDescriptor as Kr, Belongs as Kt, placeIn as L, RemoteError as Li, ConnectionApplied as Ln, RemoteRequirements as Lr, REMOTE_CACHE_VERSION as Lt, SatisfyOptions as M, reconcileMutation as Mi, connectionChangeOf as Mn, WindowSchema as Mr, updateRemote as Mt, SelectsEntity as N, schemaOf as Ni, liveEventOf as Nn, WireBoundary as Nr, windowGrowthKey as Nt, RemoteFold as O, failMutation as Oi, targetsOf as On, RemoteReadError as Or, remoteMessageCases as Ot, SubscriptionEntries as P, Denied as Pi, mutateRemote as Pn, ConnectionRequirement as Pr, withRefreshRequested as Pt, ExplainedDependencies as Q, items as Qi, coalesceQueries as Qn, ConnectionChange as Qr, AnySchema as Qt, LiveFetchOptions as R, remoteDataSchema as Ri, EntityApplied as Rn, Requirement as Rr, RemotePersistence as Rt, ReadMeta as S, writeEntities as Sa, Reconciled as Si, aliasedField as Sn, RelationRequest as Sr, isRemoteMessage as St, RemoteDescriptor as T, TypeOf as Ti, refsIn as Tn, RemoteMutationError as Tr, overlaysOf as Tt, RemoteJsonSend as U, Edge as Ui, applyConnectionEvent as Un, LiveInsertion as Ur, RetentionRoots as Ut, RemoteJsonAnswer as V, Connection as Vi, LiveOutcome as Vn, ConnectionSpec as Vr, ConnectionRoot as Vt, RemoteResumePart as W, EdgeRef as Wi, applyEntityEvent as Wn, LivePolicy as Wr, gc as Wt, plan as X, hasPrevious as Xi, CoalesceOptions as Xn, ResultOf as Xr, belongsEncoded as Xt, deadlineOf as Y, hasNext as Yi, BatchRead as Yn, QueryWindow as Yr, MatchingOptions as Yt, windowKey as Z, isGapped as Zi, QueryRun as Zn, stableStringify as Zr, matching as Zt, QueryOptions as _, readField as _a, MutationAnswer as _i, RefParts as _n, REMOTE_PROTOCOL_VERSION as _r, invalidateConnections as _t, EntitySelection as a, EntityStore as aa, addOverlay as ai, RefPage as an, LiveRequirement as ar, PlacedOrder as at, QueryWindowOptions as b, setUnavailable as ba, MutationStatus as bi, RelationKind as bn, ReadBatchResult as br, isLoadingThrough as bt, LiveOptions as c, emptyStore as ca, emptyOptimistic as ci, SelectionOf as cn, Mutate as cr, RemoteMessage as ct, MutateOptions as d, hasField as da, removeOverlay as di, assemble as dn, NormalizedEntity as dr, RemoteModel as dt, segment as ea, ConnectionOverlay as ei, EntityDescriptor as en, requirementKey as er, ReadDiagnosis as et, MutationStarted as f, isFieldStale as fa, settleFailure as fi, pageSchema as fn, PageSize as fr, StreamHealth as ft, QueryInput as g, missingFields as ga, Mutation as gi, RefPageValue as gn, QueryRpc as gr, initialRemoteModel as gt, QueryEntity as h, markStale as ha, visibleStore as hi, RELATION_ALIAS as hn, QueryResult as hr, forgetRemote as ht, EntityLike as i, EntityKey as ia, addLayer as ii, RefKey as in, LiveEdge as ir, Failures as it, RetainOptions as j, patchOfWrite as ji, coalescedLayer as jn, SettledFields as jr, retentionRootsSchema as jt, RemoteUnsatisfied as k, mutationStatus as ki, RemoteClient as kn, RemoteRpc as kr, remoteMessageSchema as kt, LiveStatus as l, entityKey as la, pruneOverlays as li, SelectionValue as ln, MutationRequest as lr, RemoteMessageInput as lt, PersistenceOptions as m, isTombstone as ma, visibleItems as mi, unavailableOf as mn, QueryRequest as mr, failureOf as mt, BoundRemote as n, unknown as na, OptimisticOperation as ni, EntityRef as nn, Live as nr, inspectEntity as nt, FoldedMutationStarted as o, EntityWrite as oa, beginOptimistic as oi, Page as on, MAX_FIELDS_PER_REQUEST as or, PlacementMismatch as ot, ObserveOptions as p, isFieldUnavailable as pa, settleSuccess as pi, relationOf as pn, QueryEdge as pr, emptyRefresh as pt, PlanFreshness as q, edge as qi, liveHasNext as qn, QueryInputs as qr, Judged as qt, DomainMutateOptions as r, EntityEntry as ra, OptimisticState as ri, FieldsFrom as rn, LiveChange as rr, inspectRemote as rt, LiveDependencies as s, clearStale as sa, connectionIdentity as si, Selection as sn, MAX_RELATION_DEPTH as sr, RefreshState as st, ActiveEntry as t, terminal as ta, EntityLayer as ti, EntityPatch as tn, ConnectionChangeSchema as tr, RemoteInspection as tt, ModelOfDomain as u, entry as ua, removeLayer as ui, SelectionValueOf as un, MutationResult as ur, RemoteMessageTag as ut, QueryProjection as v, remove as va, MutationDescriptor as vi, RelationAnnotation as vn, Read as vr, isFieldFailed as vt, Remote as w, SchemaOrFields as wi, refParts as wn, RemoteLiveError as wr, onlyOverlaid as wt, ReadDependencies as x, tombstone as xa, NormalizedPatch as xi, RelationShape as xn, ReadRequest as xr, isQueryLoading as xt, QueryRequirement as y, setStale as ya, MutationState as yi, RelationEntityAnnotation as yn, ReadBatch as yr, isLoading as yt, httpWithLive as z, remoteErrorSchema as zi, LiveCursor as zn, connectionsOf as zr, Snapshot as zt };
-//# sourceMappingURL=index-86gaaCWm.d.mts.map
+export { QueryExplanation as $, emptyConnection as $i, coalesceQueries as $n, stableStringify as $r, Entity$2 as $t, RemoteWiring as A, TypeOf as Ai, RemoteRpcClient as An, RemoteReadError as Ar, remoteModelSchema as At, liveFetch as B, Freshness as Bi, LiveCursor as Bn, Requirement as Br, SnapshotOptions as Bt, Registered as C, remove as Ca, MutationStatus as Ci, isRefPage as Cn, ReadRequest as Cr, noFailures as Ct, RemoteEntry as D, writeEntities as Da, Refusal as Di, relationShape as Dn, RemoteMutationError as Dr, refreshedAt as Dt, RemoteDomain as E, tombstone as Ea, Reconciled as Ei, relationAlias as En, RemoteLiveError as Er, refreshIsInFlight as Et, SubscriptionsOptions as F, optimisticOfWrite as Fi, mutateRemote as Fn, WireBoundary as Fr, writeRead as Ft, RemotePolicy as G, Boundary as Gi, applyEntityEvent as Gn, LiveInsertion as Gr, reachable as Gt, RemoteJsonRequest as H, RemoteError as Hi, LiveOutcome as Hn, requirementsOf as Hr, Retained as Ht, RowPlace as I, patchOfWrite as Ii, remoteError as In, ConnectionRequirement as Ir, MergePolicy as It, PlanOptions as J, Edge as Ji, liveHasNext as Jn, QueryDescriptor as Jr, Matched as Jt, Deadline as K, Connection as Ki, classifyLive as Kn, LivePolicy as Kr, Belongs as Kt, placeIn as L, reconcileMutation as Li, BoundaryCounts as Ln, RelationRequirement as Lr, REMOTE_CACHE_VERSION as Lt, SatisfyOptions as M, emptyMutationState as Mi, connectionChangeOf as Mn, RemoteUnauthenticated as Mr, updateRemote as Mt, SelectsEntity as N, failMutation as Ni, liveEventOf as Nn, SettledFields as Nr, windowGrowthKey as Nt, RemoteFold as O, writeEntity as Oa, RefusalOfWrite as Oi, targetsOf as On, RemoteProtocolError as Or, remoteMessageCases as Ot, SubscriptionEntries as P, mutationStatus as Pi, mintOperation as Pn, WindowSchema as Pr, withRefreshRequested as Pt, ExplainedDependencies as Q, edge as Qi, QueryRun as Qn, ResultOf as Qr, AnySchema as Qt, LiveFetchOptions as R, schemaOf as Ri, ConnectionApplied as Rn, RemoteConnections as Rr, RemotePersistence as Rt, ReadMeta as S, readField as Sa, MutationState as Si, aliasedField as Sn, ReadBatchResult as Sr, isRemoteMessage as St, RemoteDescriptor as T, setUnavailable as Ta, PendingPatch as Ti, refsIn as Tn, RemoteForbidden as Tr, overlaysOf as Tt, RemoteJsonSend as U, remoteDataSchema as Ui, LiveState as Un, ConnectionSpec as Ur, RetentionRoots as Ut, RemoteJsonAnswer as V, RemoteData as Vi, LiveEvent as Vn, connectionsOf as Vr, ConnectionRoot as Vt, RemoteResumePart as W, remoteErrorSchema as Wi, applyConnectionEvent as Wn, IDENTITY_SEPARATOR as Wr, gc as Wt, plan as X, Segment as Xi, BatchRead as Xn, QueryRef as Xr, belongsEncoded as Xt, deadlineOf as Y, EdgeRef as Yi, liveHasPrevious as Yn, QueryInputs as Yr, MatchingOptions as Yt, windowKey as Z, cursor as Zi, CoalesceOptions as Zn, QueryWindow as Zr, matching as Zt, QueryOptions as _, isFieldStale as _a, visibleItems as _i, RefParts as _n, QueryResult as _r, invalidateConnections as _t, EntitySelection as a, segment as aa, OptimisticState as ai, RefPage as an, LiveEdge as ar, PlacedOrder as at, QueryWindowOptions as b, markStale as ba, MutationAnswer as bi, RelationKind as bn, Read as br, isLoadingThrough as bt, LiveOptions as c, EntityEntry as ca, beginOptimistic as ci, SelectionOf as cn, MAX_RELATION_DEPTH as cr, RemoteMessage as ct, MutateOptions as d, EntityWrite as da, pruneOverlays as di, assemble as dn, MutationResult as dr, RemoteModel as dt, hasNext as ea, ConnectionChange as ei, EntityDescriptor as en, coalesceReads as er, ReadDiagnosis as et, MutationStarted as f, clearStale as fa, removeLayer as fi, pageSchema as fn, NormalizedEntity as fr, StreamHealth as ft, QueryInput as g, hasField as ga, settleSuccess as gi, RefPageValue as gn, QueryRequest as gr, initialRemoteModel as gt, QueryEntity as h, entry as ha, settleFailure as hi, RELATION_ALIAS as hn, QueryEdge as hr, forgetRemote as ht, EntityLike as i, merge as ia, OptimisticOperation as ii, RefKey as in, LiveChange as ir, Failures as it, RetainOptions as j, beginMutation as ji, coalescedLayer as jn, RemoteRpc as jr, retentionRootsSchema as jt, RemoteUnsatisfied as k, SchemaOrFields as ki, RemoteClient as kn, RemoteQueryError as kr, remoteMessageSchema as kt, LiveStatus as l, EntityKey as la, connectionIdentity as li, SelectionValue as ln, Mutate as lr, RemoteMessageInput as lt, PersistenceOptions as m, entityKey as ma, resolvedPatches as mi, unavailableOf as mn, PageSize as mr, failureOf as mt, BoundRemote as n, isGapped as na, ConnectionOverlay as ni, EntityRef as nn, ConnectionChangeSchema as nr, inspectEntity as nt, FoldedMutationStarted as o, terminal as oa, addLayer as oi, Page as on, LiveRequirement as or, PlacementMismatch as ot, ObserveOptions as p, emptyStore as pa, removeOverlay as pi, relationOf as pn, OperationId as pr, emptyRefresh as pt, PlanFreshness as q, Cursor as qi, emptyLiveState as qn, Query$1 as qr, Judged as qt, DomainMutateOptions as r, items as ra, EntityLayer as ri, FieldsFrom as rn, Live as rr, inspectRemote as rt, LiveDependencies as s, unknown as sa, addOverlay as si, Selection as sn, MAX_FIELDS_PER_REQUEST as sr, RefreshState as st, ActiveEntry as t, hasPrevious as ta, ConnectionIdentity as ti, EntityPatch as tn, requirementKey as tr, RemoteInspection as tt, ModelOfDomain as u, EntityStore as ua, emptyOptimistic as ui, SelectionValueOf as un, MutationRequest as ur, RemoteMessageTag as ut, QueryProjection as v, isFieldUnavailable as va, visibleStore as vi, RelationAnnotation as vn, QueryRpc as vr, isFieldFailed as vt, Remote as w, setStale as wa, NormalizedPatch as wi, refParts as wn, RelationRequest as wr, onlyOverlaid as wt, ReadDependencies as x, missingFields as xa, MutationDescriptor as xi, RelationShape as xn, ReadBatch as xr, isQueryLoading as xt, QueryRequirement as y, isTombstone as ya, Mutation as yi, RelationEntityAnnotation as yn, REMOTE_PROTOCOL_VERSION as yr, isLoading as yt, httpWithLive as z, Denied as zi, EntityApplied as zn, RemoteRequirements as zr, Snapshot as zt };
+//# sourceMappingURL=index-BEvVAL76.d.mts.map