foldkit-remote 0.4.0 → 0.5.0

package/README.md

@@ -145,9 +145,9 @@ Start with one server entity and one selection:
 
 ```ts
 import { Schema } from 'effect'
-import { Entity } from 'foldkit-remote'
+import { Entity } from 'foldkit-entity'
 
-const Project = Entity.make(
+const Project = Entity.define(
   'Project',
   Schema.Struct({
     id: Schema.String,
@@ -157,12 +157,20 @@ const Project = Entity.make(
 )
 
 // A Selection is the exact server-owned shape this consumer needs.
-const ProjectSummary = Project.select({
+const ProjectSummary = Entity.select(Project, {
   id: true,
   name: true,
 })
 ```
 
+The entity comes from [`foldkit-entity`](../entity), which declares a domain
+without Remote in it. Remote also has an `Entity.make` of its own, and accepts
+either — but only a `foldkit-entity` entity has addressable `fields`, so only
+that one can be given [relations](#entities-declared-with-foldkit-entity),
+derived members, or a [query body](#queries-and-pagination). Reach for
+`Entity.make` when a domain is small enough that Remote is all it will ever
+need; reach for `Entity.define` otherwise, which is most of the time.
+
 Embed Remote's Submodel in the application and bind the domain to that field:
 
 ```ts
@@ -371,6 +379,46 @@ state that actually means "wait for this request."
 `RemoteData.match` is exhaustive, so adding or omitting a state is visible at
 compile time.
 
+### Drawing one: `RemoteData.render`
+
+Most views draw these six states three ways, under one policy: useful data
+stays on screen. `RemoteData.render` is that fold.
+
+```ts
+RemoteData.render(project, {
+  loading: () => ProjectSkeleton(),
+  notFound: () => NoSuchProject(),
+  failed: error => ErrorView(error),
+  data: (value, freshness) =>
+    ProjectView({ project: value, dimmed: freshness._tag !== 'Fresh' }),
+})
+```
+
+`Initial` and `Loading` reach `loading`; `Ready` and `Refreshing` reach `data`;
+a `Failed` that still carries the value it had reaches `data` too, so a read
+that failed does not throw away what the reader was already looking at. Only a
+`Failed` with nothing to show reaches `failed`.
+
+The `data` branch is told which it got, as a `Freshness` — exported, so a view
+helper that takes one can name it:
+
+| `Freshness` | What it means |
+| --- | --- |
+| `Fresh` | This is the current answer. |
+| `Refreshing` | A newer answer is on its way; this one is still good. |
+| `Stale` | A read failed; this is what was last known good, with its `error`. |
+
+It is one tag rather than a pair of booleans because a value cannot be both
+refreshing and stale, and a type that can say so invites a view to handle a
+state that never arrives.
+
+`notFound` is its own branch and not optional. A row the server answered for
+and does not have is neither loading nor a failure; drawing it as either is a
+spinner that never ends or an error nobody can act on.
+
+Reach for `match` instead when the six states really do draw differently — it
+stays the exhaustive fold, and `render` does not replace it.
+
 ## Normalized entities and selections
 
 Remote stores an entity once by identity, regardless of how many Surfaces read
@@ -444,7 +492,9 @@ const card = Data.get(ProjectCard, 'p1') // Projection<Model, RemoteData<{ name;
 
 - A relation becomes a ref field: `one` a ref, an optional `one` a nullable ref,
   `many` an array of refs. A derived member becomes a field the server supplies.
-- The Entity needs an `id` field; Remote keys the store by it.
+- The Entity needs an `id` field; Remote keys the store by it. When that field
+  is branded, `Data.get` and `Data.live` take that type for an Entity Selection:
+  another Entity's id, or plain text, does not compile.
 - Register the Entities of one `Entity.relate` result and select from that same
   result; `Object.values(Work)` registers them all.
 - `Entity.from(entity)` and `Selection.from(selection)` are the compile steps,
@@ -452,9 +502,14 @@ const card = Data.get(ProjectCard, 'p1') // Projection<Model, RemoteData<{ name;
   handler.
 - `Entity.page(selection, window)` in an Entity Selection is Remote's
   `Selection.connection`: the window travels with the read, and the server
-  answers with a page of refs. One relation of one entity is held whole or as
-  one window at a time, so two views of the same entity should not read the
-  same relation both ways at once.
+  answers with a page of refs. A page of a whole list is read under a name of
+  its own, `comments@first=10`, so one view can show every comment while another
+  shows the first ten of the same post: they are two fields to the store, fetched
+  in one batch, merged and refreshed each on its own. A write to the list (a
+  mutation's patch, a live change) marks its pages stale, so they are read again.
+  A cursor is not part of the name: a page read from a cursor continues its page.
+  The server refuses a request that pages one relation more than four ways, and
+  a field's own name may not contain `@`.
 
 `Entity.make` with `Entity.ref` keeps working, and both kinds can share one
 domain. Both packages export `Entity`; a module that needs `Entity.from` beside
@@ -509,6 +564,24 @@ Projection itself.
 
 ### Refreshing from `update`
 
+### Showing a change nobody has made
+
+A mutation's `optimistic` operations show over the store while it is in flight.
+`Data.overlay` shows operations the same way with no request behind them, until
+`Data.lift`: a preview, in every Selection and view, of something not yet sent.
+
+```ts
+const previewed = Data.overlay(model, 'post-preview', [Project.patch(id, { name: draft })])
+const back = Data.lift(previewed, 'post-preview')
+```
+
+- Both are called from `update`, and neither performs I/O or touches what the
+  server said: the store beneath is as it was.
+- Showing an id again replaces what it showed. Lifting what was never shown
+  returns the same Model.
+- An overlay's id is apart from every request's, so a mutation that settles does
+  not take a preview with it.
+
 To revalidate what a screen already declares — a refresh button, a focus
 regained — hand its Projection (or a Surface without params) to `Data.refresh`:
 
@@ -521,8 +594,9 @@ case 'ClickedRefresh': {
 ```
 
 `Data.refresh` performs no I/O and restates no request. It returns the Model
-with every selected field the store holds reading `Refreshing` and every loaded
-connection invalidated; the `Data.subscriptions` read entries then refetch it,
+with every selected field the store holds reading `Refreshing`, every entity it
+knew to be absent forgotten, so `NotFound` reads `Loading` and is asked for
+again, and every loaded connection invalidated; the `Data.subscriptions` read entries then refetch it,
 since stale data is planned again under every policy, so the page is requested
 once. The Projection must be observed, as it is while it is on screen; for data
 nothing observes, use `Data.prefetch` with `RemotePolicy.networkOnly`.
@@ -555,6 +629,52 @@ const Data = Remote.make({
 })
 ```
 
+`Query.make` names a query and says what it returns. Where it *means*
+something the client should be able to state, declare it with a body instead:
+
+```ts
+import { Entity, Expr, Order, Query } from 'foldkit-entity'
+
+const Task = Entity.define(
+  'Task',
+  Schema.Struct({ id: Schema.String, ownerId: Schema.String, updatedAt: Schema.Number }),
+)
+
+const TasksByOwner = Query.define(
+  'TasksByOwner',
+  { ownerId: Schema.String },
+  ({ input }) =>
+    Query.from(Task).pipe(
+      Query.where(Expr.eq(Task.fields.ownerId, input.ownerId)),
+      Query.orderBy(Order.desc(Task.fields.updatedAt), Order.asc(Task.fields.id)),
+    ),
+)
+```
+
+A body is written over a [`foldkit-entity`](../entity) Entity, because that is
+what has addressable fields: `Task.fields.ownerId` is a reference an `Expr` can
+be built from, where this package's own `Entity.make` describes a field as the
+schema of its value and has nothing to point at. An entity declared either way
+still reads, selects and normalizes the same; only a query body needs the
+richer declaration.
+
+What comes back is an ordinary descriptor — the same name, `Input`, `ref` and
+connection identity — carrying its `body` besides, and the result is a
+connection over the Entity the body reads, so it is not named twice. A server
+can compile that body rather than be told the same thing again in its own
+dialect; one that would rather answer the query its own way still can, and a
+descriptor from `Query.make` has no body at all.
+
+The body is built **once**, when the query is declared. Inside it `input.ownerId`
+is a placeholder for the value the query will be given, not the value — there is
+nothing there yet to branch on. A condition that depends on what was passed is a
+comparison over the placeholder, never a `?:` around it.
+
+`Input` must be fields or a plain `Schema.Struct`, because that is what the
+placeholders are made from. A codec that exposes no keys is refused where the
+query is declared rather than handing the body an empty object, which would
+compare a column to nothing while every type agreed.
+
 Then a query is still just a Projection:
 
 ```ts
@@ -663,6 +783,41 @@ const { model: started, command } = Data.mutate(model, AddComment, input, {
 A successful server result can replace the request's temporary connection
 overlays with confirmed ones in place.
 
+### Reading past what is only pending
+
+Every projection reads the **visible** cache: the server-derived store under
+the layers still pending, which is why an optimistic change shows at once. A
+reader that must not believe a change until the server has agreed to it asks
+for the confirmed read instead:
+
+```ts
+Data.confirmed(Data.get(ProjectSummary, projectId))
+```
+
+It is the same projection — the same requirements, planned the same way, so
+observing it fetches exactly what observing the original fetches — reading the
+server-derived store alone, with the pending layers and connection overlays
+left off. An optimistically inserted edge is not in its page; an
+optimistically patched field reads as the server last said.
+
+A view almost always wants the projection itself. This is for the reader that
+reports on the world rather than drawing it, which in practice is an Agent
+capability that must not claim success before the server reflects it:
+
+```ts
+Agent.when({
+  projection: Data.confirmed(Data.get(ProjectSummary, projectId)),
+  predicate: (project, request) => project.name === request.name,
+})
+```
+
+There is deliberately no `Data.visible`: a projection already is the visible
+read, and a second name for it would be a wrapper that only forwards.
+
+Sync draws the same line over its replica, with the same words and a different
+mechanism: see [what a reader sees while a change is in
+flight](../../docs/state-model.md#what-a-reader-sees-while-a-change-is-in-flight).
+
 ### Remote mutation vs Sync operation
 
 Do not use Remote mutation as a durable offline-write mechanism:
@@ -828,6 +983,15 @@ useful question is: **"Why is this Projection still Initial?"** `Data.plan`
 shows whether Remote believes anything is actually missing; active Surface
 wiring determines whether that plan is being executed.
 
+`Data.inspect(model).loading` answers the other one — **"what is Remote doing
+right now?"** — with the `entity\0id\0field` marks of the reads in flight,
+beside `mutations.pending` for the writes. Both are read from the Model, not
+from the fibers doing the work: a tool that shows them shows something a
+recorded Model can be replayed to, and nothing that needs the runtime to be
+asked. That is deliberate. Runtime activity is not a second source of truth
+here, and a view that rendered from it would stop being reproducible from the
+Model.
+
 ## Advanced: the kernel
 
 Everything above compiles to the lower-level exports below; there is not a

package/dist/index.d.mts

@@ -1,5 +1,6 @@
 import { Context, Duration, Effect, Layer, Option, Schema, Stream } from "effect";
 import * as Domain from "foldkit-entity";
+import { AnyEntity, AnyQuery, InputExpr, Query as Query$1 } from "foldkit-entity";
 import { EntryWithoutKeepAlive } from "foldkit/subscription";
 import { ActiveSurface, Contract, Invalid, Metadata, ModelRef, Projection, Surface, Wiring } from "foldkit-surface";
 import { Rpc, RpcGroup } from "effect/unstable/rpc";
@@ -126,6 +127,21 @@ export type RemoteData<A> = {
 } | {
   readonly _tag: 'NotFound';
 };
+/**
+ * What `RemoteData.render` tells the `data` branch about the value it is
+ * given: whether a newer answer is on its way, and whether this one is what
+ * was last known good before a read failed. It is one tag rather than two
+ * booleans because a value cannot be both at once, and a type that can say so
+ * invites a view to handle a state that never arrives.
+ */
+export type Freshness = {
+  readonly _tag: 'Fresh';
+} | {
+  readonly _tag: 'Refreshing';
+} | {
+  readonly _tag: 'Stale';
+  readonly error: RemoteError;
+};
 export declare const remoteErrorSchema: Schema.Struct<{
   readonly _tag: Schema.String;
   readonly message: Schema.String;
@@ -146,6 +162,36 @@ export declare const RemoteData: {
     readonly Failed: (error: RemoteError, previous: Option.Option<A>) => R;
     readonly NotFound: () => R;
   }) => R;
+  /**
+   * The view-oriented fold: the six states as the three things a view actually
+   * draws, under the policy that useful data stays on screen. A value that is
+   * being refetched, or that a later read failed to replace, still reaches
+   * `data` — with `freshness` saying which — instead of being replaced by a
+   * spinner or an error the reader cannot act on.
+   *
+   * ```ts
+   * RemoteData.render(model.user, {
+   *   loading: () => UserSkeleton(),
+   *   notFound: () => NoSuchUser(),
+   *   failed: error => ErrorView(error),
+   *   data: (user, freshness) => UserView({ user, dimmed: freshness._tag !== 'Fresh' }),
+   * })
+   * ```
+   *
+   * `notFound` is its own branch and not optional: a row the server answered
+   * for and does not have is neither loading nor a failure, and drawing it as
+   * either is a spinner that never ends or an error nobody can fix.
+   *
+   * This does not replace `match`, which is the exhaustive fold over the states
+   * themselves. Reach for `match` when the six states really do draw
+   * differently, and for this when they draw the usual three ways.
+   */
+  render: <A, R>(data: RemoteData<A>, cases: {
+    readonly loading: () => R;
+    readonly notFound: () => R;
+    readonly failed: (error: RemoteError) => R;
+    readonly data: (value: A, freshness: Freshness) => R;
+  }) => R;
   map: <A, B>(data: RemoteData<A>, f: (value: A) => B) => RemoteData<B>;
 };
 //#endregion
@@ -321,7 +367,20 @@ export interface QueryDescriptor<Name extends string, Input, Result> {
   readonly Input: Schema.Codec<Input>;
   readonly Result: Result;
   readonly ref: (input: Input) => QueryRef<Name, Input>;
+  /**
+   * What the query means, when it was declared with `Query.define`: the rows it
+   * is about, as a value an interpreter can compile. A descriptor from
+   * `Query.make` has none — its meaning lives in whatever the server registered
+   * to answer it — and a source is free to answer either.
+   */
+  readonly body?: AnyQuery | undefined;
 }
+/**
+ * The inputs of a definition's body: one placeholder per key of `Input`, typed
+ * as that key's value. A body is built once, so these stand for what the query
+ * will be given rather than being it.
+ */
+export type QueryInputs<Input> = { readonly [K in keyof Input & string]: InputExpr<Input[K]>; };
 /** Stable stringify: object keys sorted, undefined-valued keys dropped, so equal inputs encode equally. */
 export declare const stableStringify: (value: unknown) => string;
 /**
@@ -332,6 +391,8 @@ export declare const stableStringify: (value: unknown) => string;
 export type ResultOf<Result> = Result extends {
   readonly name: infer Entity extends string;
 } ? ConnectionSpec<Entity> : Result;
+/** A relational `Query` over one Entity, as `Query.define`'s body returns. */
+type RelationalQueryOf<E extends AnyEntity> = ReturnType<typeof Query$1.from<E>>;
 export declare const Query: {
   /** Declares the entity and options a query's result is a connection over. */
   connection: <Entity extends string>(entity: {
@@ -349,10 +410,44 @@ export declare const Query: {
     readonly Input: Input;
     readonly Result: Result;
   }) => QueryDescriptor<Name, TypeOf<Input>, ResultOf<Result>>;
+  /**
+   * Declares a query by what it means. The body is built once, here, and the
+   * `input` it is given holds placeholders rather than values — there is
+   * nothing yet to branch on, so a condition that depends on what was passed is
+   * a comparison over the placeholder:
+   *
+   * ```ts
+   * const PostsBySlug = Query.define('PostsBySlug', { slug: Schema.String }, ({ input }) =>
+   *   Query.from(Post).pipe(
+   *     Query.where(Expr.eq(Post.fields.slug, input.slug)),
+   *     Query.orderBy(Order.asc(Post.fields.id)),
+   *   ),
+   * )
+   * ```
+   *
+   * What comes back is an ordinary `QueryDescriptor` — the same name, `Input`,
+   * `ref` and connection identity `Query.make` gives — carrying its `body`
+   * besides. A server can compile that body instead of being told the same
+   * thing again in its own dialect, and one that would rather answer the query
+   * its own way still can.
+   *
+   * The result is a connection over the Entity the body reads, so it is not
+   * named twice.
+   */
+  define: <const Name extends string, Input extends SchemaOrFields, E extends AnyEntity>(name: Name, Input: Input, body: (context: {
+    readonly input: QueryInputs<TypeOf<Input>>;
+  }) => RelationalQueryOf<E>, options?: {
+    readonly edgeKey?: Schema.Schema<unknown>;
+    readonly live?: LivePolicy;
+  }) => QueryDescriptor<Name, TypeOf<Input>, ConnectionSpec<E["name"]>>;
   first: (count: number) => <R extends QueryRef<string, unknown>>(ref: R) => R;
   last: (count: number) => <R extends QueryRef<string, unknown>>(ref: R) => R;
   after: (cursor: Cursor) => <R extends QueryRef<string, unknown>>(ref: R) => R;
   before: (cursor: Cursor) => <R extends QueryRef<string, unknown>>(ref: R) => R;
+  from: <E extends AnyEntity>(entity: E) => Query$1<E>;
+  where: (...predicates: ReadonlyArray<import("foldkit-entity").Predicate>) => <E extends AnyEntity>(self: Query$1<E>) => Query$1<E>;
+  orderBy: (...terms: ReadonlyArray<import("foldkit-entity").OrderTerm>) => <E extends AnyEntity>(self: Query$1<E>) => Query$1<E>;
+  dependencies: (self: AnyQuery) => import("foldkit-entity").Dependencies;
 };
 //#endregion
 //#region src/requirement.d.ts
@@ -1160,15 +1255,25 @@ export interface RemoteModel {
    */
   readonly loading: ReadonlySet<string>;
   /**
-   * `Remote.refresh` generations. The read entries restart when `requested`
-   * moves, so a read sent before a refresh cannot land after it; `started` is
-   * the latest generation a read began under.
+   * `Remote.refresh` generations, held per field rather than for the store as a
+   * whole. A read entry restarts when the generation over the fields it plans
+   * moves, so a read sent before a refresh of its own fields cannot land after
+   * it, and a refresh of one field leaves every other entry's read alone.
    */
-  readonly refresh: {
-    readonly requested: number;
-    readonly started: number;
-  };
+  readonly refresh: RefreshState;
 }
+/**
+ * `Remote.refresh` generations, per field mark. `generation` is the last one
+ * handed out; `requested` is when each field was last refreshed, and `started`
+ * is the generation each field's read last began under. Holding them per field
+ * is what keeps one Projection's refresh from restarting every read entry.
+ */
+export interface RefreshState {
+  readonly generation: number;
+  readonly requested: ReadonlyMap<string, number>;
+  readonly started: ReadonlyMap<string, number>;
+}
+export declare const emptyRefresh: RefreshState;
 export declare const initialRemoteModel: RemoteModel;
 export declare const remoteModelSchema: () => Schema.Codec<RemoteModel, unknown>;
 /** The submodel's Messages; each reduces to `RemoteModel` through `updateRemote`. */
@@ -1225,6 +1330,19 @@ export type RemoteMessage = {
   readonly _tag: 'MutationFailed';
   readonly requestId: string;
   readonly error: RemoteError;
+} |
+/**
+ * Operations shown over the store with no request behind them, until they are
+ * lifted: a preview of a change nobody has made. Showing an id again replaces
+ * what it showed.
+ */
+{
+  readonly _tag: 'OverlayShown';
+  readonly id: string;
+  readonly optimistic: ReadonlyArray<OptimisticOperation>;
+} | {
+  readonly _tag: 'OverlayLifted';
+  readonly id: string;
 } | {
   readonly _tag: 'LiveReceived';
   readonly stream: string;
@@ -1327,6 +1445,13 @@ export declare const remoteMessageCases: {
       readonly message: Schema.String;
     }>;
   };
+  OverlayShown: {
+    id: Schema.String;
+    optimistic: Schema.$Array<Schema.Unknown>;
+  };
+  OverlayLifted: {
+    id: Schema.String;
+  };
   LiveReceived: {
     stream: Schema.String;
     event: Schema.Unknown;
@@ -1374,6 +1499,25 @@ export declare const isRemoteMessage: <M extends {
   readonly _tag: RemoteMessageTag;
 }>;
 export declare const remoteMessageSchema: Schema.Schema<RemoteMessage>;
+/**
+ * The generation a read is planned under: the highest any of the fields it
+ * reads or connections it runs was refreshed at. A read entry carries this as a
+ * dependency, so it restarts when what it observes is refreshed and not when
+ * anything else is.
+ */
+export declare const refreshedAt: (refresh: RefreshState, requests: ReadonlyArray<Requirement>, connections?: ReadonlyArray<string>) => number;
+/**
+ * Marks every field of `requests` and every connection in `connections`
+ * refreshed at the next generation.
+ */
+export declare const withRefreshRequested: (refresh: RefreshState, requests: ReadonlyArray<Requirement>, connections?: ReadonlyArray<string>) => RefreshState;
+/**
+ * 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
+ * refresh, so the refresh takes a new generation to restart it even though the
+ * field is already stale.
+ */
+export declare const refreshIsInFlight: (refresh: RefreshState, request: Requirement, field: string) => boolean;
 /**
  * Whether a read is fetching any of `fields` for this entity. Consulted only
  * when the store lacks the value, which is what separates `Loading` from
@@ -1502,6 +1646,25 @@ export interface RelationShape {
   readonly nullable: boolean;
   readonly entity: string;
 }
+/**
+ * A page of a relation that is a whole list is read under a name of its own, the
+ * field's name and the page's size: `comments@first=10`. It is a field like any
+ * other to the store, the planner, and the wire, so the whole list and a page of
+ * it are held side by side, merged, marked stale, and persisted each on its own.
+ * The server reads the name apart, reads the relation with the window, and
+ * answers under the alias. A cursor is not part of the name: a page read from a
+ * cursor merges onto the page it continues.
+ */
+export declare const RELATION_ALIAS = "@";
+/** The alias a relation field is read under, for a window of this size. */
+export declare const relationAlias: (field: string, window: {
+  readonly first?: number | undefined;
+  readonly last?: number | undefined;
+  readonly after?: string | undefined;
+  readonly before?: string | undefined;
+}) => string;
+/** The field an alias reads; a name that is no alias is its own field. */
+export declare const aliasedField: (name: string) => string;
 /** Splits a ref key (`"Entity:id"`, the store key too) back into its parts. */
 export declare const refParts: (encoded: string) => RefParts;
 /**
@@ -1699,6 +1862,13 @@ export interface RemoteInspection {
   readonly connections: ReadonlyArray<string>;
   readonly live: ReadonlyArray<string>;
   readonly gaps: ReadonlyArray<string>;
+  /**
+   * The `entity\0id\0field` marks of reads in flight. This is what "Remote is
+   * working" means here, and it is read from the Model rather than from the
+   * fibers doing the work: a tool that shows it shows something the Model can
+   * be replayed to, and nothing that needs the runtime to be asked.
+   */
+  readonly loading: ReadonlyArray<string>;
   readonly mutations: {
     readonly pending: ReadonlyArray<string>;
     readonly failed: ReadonlyArray<string>;
@@ -1774,9 +1944,9 @@ export type EntityLike = EntityDescriptor<any, any> | Domain.AnyEntity;
  * What a read selects: a Remote Selection, or a `foldkit-entity` Selection
  * (read through `Selection.from`).
  */
-export type EntitySelection<Value, Name extends string> = Selection<Value, Name, 'entity'> | Domain.Selection<Name, unknown, Schema.Constraint & {
+export type EntitySelection<Value, Name extends string, Id extends string = string> = Selection<Value, Name, 'entity'> | Domain.Selection<Name, unknown, Schema.Constraint & {
   readonly Type: Value;
-}>;
+}, Id>;
 type EntityName<D> = D extends {
   readonly name: infer Name extends string;
 } ? Name : never;
@@ -1858,13 +2028,13 @@ export interface MutationStarted<AppModel> {
  */
 export interface RemoteDomain<AppModel, Store extends RemoteModel, Entities extends readonly EntityLike[], Queries extends readonly QueryDescriptor<any, any, any>[], Mutations extends readonly MutationDescriptor<any, any, any>[]> extends BoundRemote<AppModel, Store, EntityName<Entities[number]>>, RemoteDescriptor<Entities, Queries, Mutations> {
   /** `Remote.select`: a Projection reading one entity through a selection of a registered entity. */
-  get<Value, Name extends string>(selection: EntitySelection<Value, Name> & Registered<Name, EntityName<Entities[number]>, 'Entity'>, id: string): Projection<AppModel, RemoteData<Value>>;
+  get<Value, Name extends string, Id extends string = string>(selection: EntitySelection<Value, Name, Id> & Registered<Name, EntityName<Entities[number]>, 'Entity'>, id: NoInfer<Id>): Projection<AppModel, RemoteData<Value>>;
   /**
    * `get`, and the projection also subscribes to the entity's changes: its
    * requirements are marked `live`, so `subscriptions` derives a live entry for
    * the Surfaces that read it.
    */
-  live<Value, Name extends string>(selection: EntitySelection<Value, Name> & Registered<Name, EntityName<Entities[number]>, 'Entity'>, id: string): Projection<AppModel, RemoteData<Value>>;
+  live<Value, Name extends string, Id extends string = string>(selection: EntitySelection<Value, Name, Id> & Registered<Name, EntityName<Entities[number]>, 'Entity'>, id: NoInfer<Id>): Projection<AppModel, RemoteData<Value>>;
   /**
    * A query connection read as a `Page` of items selected of the query's
    * entity: `Initial` until the page and every item's selected fields are
@@ -1879,6 +2049,15 @@ export interface RemoteDomain<AppModel, Store extends RemoteModel, Entities exte
   previous<Name extends string, Input>(model: AppModel, projection: QueryProjection<AppModel, any, Name, Input>): QueryRef<Name, Input> | undefined;
   /** A Command that runs the query and yields the `ConnectionMerged` (or `QueryFailed`) that reduces it: "load more". */
   fetch(ref: QueryRef<string, unknown>): Command<RemoteMessage, never, RemoteClient>;
+  /**
+   * Shows operations over the store with no request behind them, as a mutation's
+   * `optimistic` ones show while it is in flight: every Selection and view draws
+   * them. For a preview of a change nobody has made. They stay until `lift`;
+   * showing an id again replaces what it showed. Called from `update`.
+   */
+  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;
   /** `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;
   /**
@@ -1894,6 +2073,30 @@ export interface RemoteDomain<AppModel, Store extends RemoteModel, Entities exte
   plan<Value>(model: AppModel, projection: Projection<AppModel, Value>, options?: PlanOptions): ReadonlyArray<Requirement>;
   /** `Remote.storeOf`: the visible store, base under the pending optimistic layers. */
   storeOf(model: AppModel): EntityStore;
+  /**
+   * `Remote.confirmed`: the same projection read against the server-derived
+   * store alone, with every pending optimistic layer and connection overlay
+   * left off. What it plans is unchanged — the requirements are the
+   * projection's own — so observing it reads exactly what observing the
+   * projection reads; only what it *shows* differs.
+   *
+   * A view usually wants the projection itself, which is the visible read:
+   * the optimistic layers are there so a change shows before the server has
+   * agreed to it. This is for the reader that must not believe a change until
+   * the server has confirmed it, which in practice is an Agent capability
+   * reporting that what it was asked to do is done:
+   *
+   * ```ts
+   * Agent.when({
+   *   projection: Data.confirmed(ProjectPage.model.project),
+   *   predicate: (project, request) => project.name === request.name,
+   * })
+   * ```
+   *
+   * There is deliberately no `visible`: a projection is already the visible
+   * read, and a wrapper that only forwards would be a second name for it.
+   */
+  confirmed<P extends Projection<AppModel, any>>(projection: P): P;
   /**
    * The plan run through `RemoteClient` and reduced into the Model: the
    * projection's pending queries first, then the fields it lacks (the pages'
@@ -1989,7 +2192,11 @@ declare const PlannedQuery: Schema.Struct<{
 export interface ReadDependencies {
   readonly requirements: ReadonlyArray<Requirement>;
   readonly queries: ReadonlyArray<Schema.Schema.Type<typeof PlannedQuery>>;
-  /** The Model's requested refresh generation: a refresh restarts the entry. */
+  /**
+   * The highest generation the fields this entry reads were refreshed at: a
+   * refresh of any of them restarts the entry, and a refresh of anything else
+   * leaves it running.
+   */
   readonly refresh: number;
 }
 export declare const Remote: {
@@ -2065,6 +2272,13 @@ export declare const Remote: {
         readonly message: Schema.String;
       }>;
     };
+    OverlayShown: {
+      id: Schema.String;
+      optimistic: Schema.$Array<Schema.Unknown>;
+    };
+    OverlayLifted: {
+      id: Schema.String;
+    };
     LiveReceived: {
       stream: Schema.String;
       event: Schema.Unknown;
@@ -2151,6 +2365,12 @@ export declare const Remote: {
    * has not changed.
    */
   storeOf: <AppModel, Store extends RemoteModel>(bound: BoundRemote<AppModel, Store>, model: AppModel) => EntityStore;
+  /**
+   * The projection read against the server-derived store alone: the same
+   * requirements, planned the same way, with the pending optimistic layers and
+   * connection overlays left off. See the bound `Remote.confirmed`.
+   */
+  confirmed: <AppModel, Store extends RemoteModel, P extends Projection<AppModel, any>>(bound: BoundRemote<AppModel, Store>, projection: P) => P;
   /**
    * Executes the plan against the `RemoteClient` and returns a new store. Used
    * for SSR route prefetch, hover prefetch, and tests. Never called during render.