@confect/foldkit 10.0.0-next.21 → 10.0.0-next.23

package/src/Command.ts

@@ -6,10 +6,10 @@ import * as FoldkitCommand from "foldkit/command";
 import * as Client from "./Client";
 
 /**
- * Everything a Command against `Ref_` can fail with before it is folded into
- * an `onError` Message: the ref's typed error (if it declares an `error`
- * schema), a transport-level `WebSocketClientError`, or a `SchemaError` from
- * encoding args or decoding returns.
+ * Everything a Command against `Ref_` can fail with before it is folded into an
+ * `onError` Message: the ref's typed error (if it declares an `error` schema),
+ * a transport-level `WebSocketClientError`, or a `SchemaError` from encoding
+ * args or decoding returns.
  */
 export type Error<Ref_ extends Ref.AnyConfect> =
   | Ref.Error<Ref_>
@@ -17,11 +17,11 @@ export type Error<Ref_ extends Ref.AnyConfect> =
   | Schema.SchemaError;
 
 /**
- * Maps a Confect function's outcome into the app's Messages. Every failure —
- * the ref's typed error, a transport error, or a codec error — arrives via
- * `onError`, so the resulting Command's error channel is `never`, as Foldkit
- * requires. Follow Foldkit's naming convention: past-tense facts like
- * `SucceededSaveNote` / `FailedSaveNote`.
+ * Maps a Confect function's outcome into the app's Messages. Every failure—the
+ * ref's typed error, a transport error, or a codec error—arrives via `onError`,
+ * so the resulting Command's error channel is `never`, as Foldkit requires.
+ * Follow Foldkit's naming convention: past-tense facts like
+ * `SucceededSaveNote`/`FailedSaveNote`.
  */
 export interface Handlers<
   Ref_ extends Ref.AnyConfect,
@@ -50,13 +50,13 @@ type SchemaArgs<Ref_ extends Ref.AnyConfect> = Schema.Schema.Type<
 >;
 
 /**
- * A Foldkit Command definition whose args are the ref's args: our
- * ref-derived call signature (args optional when the ref declares none)
- * intersected with Foldkit's own `CommandDefinitionWithArgs`, which supplies
- * the `CommandDefinitionTypeId` brand and makes the definition assignable
- * wherever Foldkit accepts one — including Story/Scene `Command.resolve`
- * and `expectExact` matchers. Call it from `update` to construct a Command
- * instance; nothing runs until the Foldkit runtime executes it.
+ * A Foldkit Command definition whose args are the ref's args: our ref-derived
+ * call signature (args optional when the ref declares none) intersected with
+ * Foldkit's own `CommandDefinitionWithArgs`, which supplies the
+ * `CommandDefinitionTypeId` brand and makes the definition assignable wherever
+ * Foldkit accepts one—including Story/Scene `Command.resolve` and `expectExact`
+ * matchers. Call it from `update` to construct a Command instance; nothing runs
+ * until the Foldkit runtime executes it.
  */
 export type Definition<
   Name extends string,
@@ -70,15 +70,15 @@ export type Definition<
   >;
 
 /**
- * Makes a factory-built Command interruptible — Foldkit's `InterruptOption`
+ * Makes a factory-built Command interruptible—Foldkit's `InterruptOption`
  * applied to the ref's args. `true` keys every invocation by the Command
- * name — right when at most one invocation is meaningfully in flight; a
+ * name—right when at most one invocation is meaningfully in flight; a
  * `KeyedInterrupt` derives the key part from the ref's args, so concurrent
  * invocations can be targeted independently.
  *
  * Interrupting stops the client-side Effect and guarantees the invocation's
- * result Messages never dispatch — it does not cancel the Convex function on
- * the server, which runs to completion once the call is on the wire.
+ * result Messages never dispatch—it does not cancel the Convex function on the
+ * server, which runs to completion once the call is on the wire.
  */
 export type InterruptOption<
   Ref_ extends Ref.AnyConfect,
@@ -96,10 +96,10 @@ export type KeyedInterrupt<
 > = Exclude<InterruptOption<Ref_, KeyField>, true>;
 
 /**
- * An interruptible Command definition whose key is the Command name — the
+ * An interruptible Command definition whose key is the Command name—the
  * ref-derived call signature intersected with Foldkit's
- * `Interruptible.DefinitionWithArgsNameKeyed`, which supplies the brand and
- * the `Interrupt` constructor.
+ * `Interruptible.DefinitionWithArgsNameKeyed`, which supplies the brand and the
+ * `Interrupt` constructor.
  */
 export type InterruptibleDefinition<
   Name extends string,
@@ -116,7 +116,7 @@ export type InterruptibleDefinition<
 
 /**
  * An interruptible Command definition whose key is derived from the ref's
- * args — the ref-derived call signature intersected with Foldkit's
+ * args—the ref-derived call signature intersected with Foldkit's
  * `Interruptible.DefinitionWithArgs`, which supplies the brand and the
  * key-args-taking `Interrupt` constructor.
  */
@@ -149,9 +149,9 @@ const run = <Ref_ extends Ref.AnyConfect, SuccessMessage, ErrorMessage>(
   );
 
 /**
- * An execute body for a hand-written `Command.define` — every failure already
- * folded into a Message. Reach for these when the factory below doesn't fit:
- * a custom args schema, `interrupt`, or a Command that makes several calls.
+ * An execute body for a hand-written `Command.define`—every failure already
+ * folded into a Message. Reach for these when the factory below doesn't fit: a
+ * custom args schema, `interrupt`, or a Command that makes several calls.
  */
 export const queryEffect =
   <Query extends Ref.AnyConfectPublicQuery, SuccessMessage, ErrorMessage>(
@@ -164,7 +164,7 @@ export const queryEffect =
     run(handlers, (client) => client.query(ref, ...args));
 
 /**
- * An execute body for a hand-written `Command.define` — every failure already
+ * An execute body for a hand-written `Command.define`—every failure already
  * folded into a Message. See `queryEffect`.
  */
 export const mutationEffect =
@@ -178,7 +178,7 @@ export const mutationEffect =
     run(handlers, (client) => client.mutation(ref, ...args));
 
 /**
- * An execute body for a hand-written `Command.define` — every failure already
+ * An execute body for a hand-written `Command.define`—every failure already
  * folded into a Message. See `queryEffect`.
  */
 export const actionEffect =
@@ -412,22 +412,26 @@ const makeFactory = <BoundRef extends Ref.AnyConfect>(
  *   messages: [SucceededGetNote, FailedGetNote],
  *   onSuccess: (note) => SucceededGetNote({ note }),
  *   onError: (error) => FailedGetNote({ message: String(error) }),
- * })
+ * });
  * // In update:
  * // [model, [FetchNote({ noteId })]]
  * ```
  *
  * Pass `interrupt` to make invocations interruptible via the returned
- * definition's `Interrupt` constructor — `true` keys them by the Command
- * name, `{ keyFields, toKey }` by a part derived from the ref's args:
+ * definition's `Interrupt` constructor—`true` keys them by the Command name, `{
+ * keyFields, toKey }` by a part derived from the ref's args:
  *
  * ```ts
- * const SaveDraft = Command.mutation("SaveDraft", refs.public.notes.insert, {
- *   messages: [SucceededSaveDraft, FailedSaveDraft],
- *   onSuccess: (noteId) => SucceededSaveDraft({ noteId }),
- *   onError: (error) => FailedSaveDraft({ message: String(error) }),
- *   interrupt: true,
- * })
+ * const SaveDraft = Command.mutation(
+ *   "SaveDraft",
+ *   refs.public.notes.insert,
+ *   {
+ *     messages: [SucceededSaveDraft, FailedSaveDraft],
+ *     onSuccess: (noteId) => SucceededSaveDraft({ noteId }),
+ *     onError: (error) => FailedSaveDraft({ message: String(error) }),
+ *     interrupt: true,
+ *   },
+ * );
  * // In update:
  * // [model, [SaveDraft.Interrupt((outcome) => CompletedCancelSaveDraft({ outcome }))]]
  * ```
@@ -444,8 +448,8 @@ export const mutation: ReturnType<
 > = makeFactory(mutationEffect);
 
 /**
- * A Foldkit Command definition for a Confect action whose Command args are
- * the ref's args. See `query`.
+ * A Foldkit Command definition for a Confect action whose Command args are the
+ * ref's args. See `query`.
  */
 export const action: ReturnType<
   typeof makeFactory<Ref.AnyConfectPublicAction>

package/src/PaginatedQuery.ts

@@ -11,7 +11,9 @@ import * as SchemaGetter from "effect/SchemaGetter";
 import * as SchemaIssue from "effect/SchemaIssue";
 import * as Client from "./Client";
 
-/** Identifies the cursor range fetched for one page. */
+/**
+ * Identifies the cursor range fetched for one page.
+ */
 export interface PageDescriptor {
   readonly cursor: string | null;
   readonly endCursor: Option.Option<string>;
@@ -22,7 +24,9 @@ export const PageDescriptor = Schema.Struct({
   endCursor: Schema.Option(Schema.String),
 });
 
-/** Options that remain fixed for one pagination session. */
+/**
+ * Options that remain fixed for one pagination session.
+ */
 export interface Options {
   readonly initialNumItems: number;
   readonly maximumRowsRead?: number;
@@ -38,7 +42,9 @@ export const Options = Schema.Struct({
   maximumBytesRead: Schema.optionalKey(PositiveInt),
 });
 
-/** Why the machine is fetching its current target. */
+/**
+ * Why the machine is fetching its current target.
+ */
 export type Direction =
   | "Initial"
   | "Next"
@@ -47,7 +53,9 @@ export type Direction =
   | "Split"
   | "Reset";
 
-/** A complete page that can remain on screen while another page is fetched. */
+/**
+ * A complete page that can remain on screen while another page is fetched.
+ */
 export interface Page<Item_> {
   readonly descriptor: PageDescriptor;
   readonly number: number;
@@ -89,12 +97,16 @@ interface PhaseDefinition extends Data.TaggedEnum.WithGenerics<2> {
 
 const Phase = Data.taggedEnum<PhaseDefinition>();
 
-/** A closed machine that retains its generation for stale-result rejection. */
+/**
+ * A closed machine that retains its generation for stale-result rejection.
+ */
 export type Idle = Data.TaggedEnum<{
   Idle: { readonly generation: number };
 }>;
 
-/** A live cursor-pagination session. */
+/**
+ * A live cursor-pagination session.
+ */
 export type Active<Item_, UserArgs_, Error_> = Data.TaggedEnum<{
   Active: {
     readonly generation: number;
@@ -108,7 +120,9 @@ export type Active<Item_, UserArgs_, Error_> = Data.TaggedEnum<{
   };
 }>;
 
-/** A schema-backed cursor-pagination machine. */
+/**
+ * A schema-backed cursor-pagination machine.
+ */
 export type State<Item_, UserArgs_, Error_> =
   | Idle
   | Active<Item_, UserArgs_, Error_>;
@@ -119,7 +133,9 @@ interface StateDefinition extends Data.TaggedEnum.WithGenerics<3> {
 
 const State = Data.taggedEnum<StateDefinition>();
 
-/** The logical request from which a subscription allocates a session id. */
+/**
+ * The logical request from which a subscription allocates a session id.
+ */
 export interface SubscriptionRequest<UserArgs_> {
   readonly generation: number;
   readonly args: UserArgs_;
@@ -129,7 +145,9 @@ export interface SubscriptionRequest<UserArgs_> {
   readonly descriptor: PageDescriptor;
 }
 
-/** The complete identity and arguments of a subscribed page request. */
+/**
+ * The complete identity and arguments of a subscribed page request.
+ */
 export interface Request<UserArgs_> {
   readonly generation: number;
   readonly args: UserArgs_;
@@ -139,7 +157,9 @@ export interface Request<UserArgs_> {
   readonly descriptor: PageDescriptor;
 }
 
-/** The successful payload returned by a Convex paginated query. */
+/**
+ * The successful payload returned by a Convex paginated query.
+ */
 export interface PageResult<Item_> {
   readonly page: ReadonlyArray<Item_>;
   readonly isDone: boolean;
@@ -149,8 +169,8 @@ export interface PageResult<Item_> {
 }
 
 /**
- * One correlated subscription outcome. Both success and failure travel
- * through this value so `settle` can mirror `AsyncData.settle`.
+ * One correlated subscription outcome. Both success and failure travel through
+ * this value so `settle` can mirror `AsyncData.settle`.
  */
 export interface Settlement<Item_, UserArgs_, Error_> {
   readonly request: Request<UserArgs_>;
@@ -173,18 +193,24 @@ interface FunctionErrorDefinition extends Data.TaggedEnum.WithGenerics<1> {
   readonly taggedEnum: TaggedFunctionError<this["A"]>;
 }
 
-/** Constructs a declared function or middleware failure envelope. */
+/**
+ * Constructs a declared function or middleware failure envelope.
+ */
 export const FunctionError =
   Data.taggedEnum<FunctionErrorDefinition>().FunctionError;
 
-/** A declared function or middleware failure, kept distinct from client errors. */
+/**
+ * A declared function or middleware failure, kept distinct from client errors.
+ */
 export type FunctionError<Query extends Ref.AnyConfectPublicPaginatedQuery> = [
   Ref.Error<Query>,
 ] extends [never]
   ? never
   : TaggedFunctionError<Ref.Error<Query>>;
 
-/** Every failure a paginated query subscription can settle with. */
+/**
+ * Every failure a paginated query subscription can settle with.
+ */
 export type Error<Query extends Ref.AnyConfectPublicPaginatedQuery> =
   | FunctionError<Query>
   | PaginationError.InvalidCursor
@@ -205,7 +231,9 @@ type MachineActive<Query extends Ref.AnyConfectPublicPaginatedQuery> = Active<
   Error<Query>
 >;
 
-/** The schema-and-constructor bundle returned by `make`. */
+/**
+ * The schema-and-constructor bundle returned by `make`.
+ */
 export interface PaginatedQuery<
   Query extends Ref.AnyConfectPublicPaginatedQuery,
 > {
@@ -295,7 +323,9 @@ const SerializableSchemaError = Schema.instanceOf(Schema.SchemaError, {
     }),
 });
 
-/** Builds a page machine from a paginated ref. */
+/**
+ * Builds a page machine from a paginated ref.
+ */
 export const make = <Query extends Ref.AnyConfectPublicPaginatedQuery>(
   ref: Query,
 ): PaginatedQuery<Query> => {
@@ -483,7 +513,9 @@ const descriptorEquals = (a: PageDescriptor, b: PageDescriptor): boolean =>
       }),
   });
 
-/** Returns the logical request currently driving the subscription. */
+/**
+ * Returns the logical request currently driving the subscription.
+ */
 export const getSubscriptionRequest = <Item_, UserArgs_, Error_>(
   state: Active<Item_, UserArgs_, Error_>,
 ): SubscriptionRequest<UserArgs_> => ({
@@ -495,7 +527,9 @@ export const getSubscriptionRequest = <Item_, UserArgs_, Error_>(
   descriptor: state.current,
 });
 
-/** Attaches the client-allocated pagination id to a logical request. */
+/**
+ * Attaches the client-allocated pagination id to a logical request.
+ */
 export const allocateRequest = <UserArgs_>(
   request: SubscriptionRequest<UserArgs_>,
   paginationId: number,
@@ -525,12 +559,16 @@ const pendingPhase = <Item_>(
     onSome: (page) => Phase.Refreshing<Item_, never>({ data: page, direction }),
   });
 
-/** Close the subscription while retaining its generation tombstone. */
+/**
+ * Close the subscription while retaining its generation tombstone.
+ */
 export const close = <Item_, UserArgs_, Error_>(
   state: Active<Item_, UserArgs_, Error_>,
 ): Idle => State.Idle({ generation: state.generation });
 
-/** Start a fresh pagination session at page one while retaining visible data. */
+/**
+ * Start a fresh pagination session at page one while retaining visible data.
+ */
 export const reset = <Item_, UserArgs_, Error_>(
   state: Active<Item_, UserArgs_, Error_>,
 ): Active<Item_, UserArgs_, Error_> => ({
@@ -543,7 +581,17 @@ export const reset = <Item_, UserArgs_, Error_>(
   phase: pendingPhase(phaseData(state.phase), "Reset"),
 });
 
-/** Navigate to the next page, retaining the current page while it loads. */
+/**
+ * Navigate to the next page, retaining the current page while it loads.
+ *
+ * The page being left is pushed onto the stack _pinned_ to the range it
+ * displayed—its cursor to its continuation cursor—so `prev` reloads exactly
+ * that range rather than the first `initialNumItems` documents after its
+ * cursor, however the data has moved meanwhile. Convex's own pagination keeps
+ * that range in its query journal; stream-paginated queries have no journal, so
+ * the pin is what keeps consecutive pages gap-free and duplicate-free for
+ * them.
+ */
 export const next = <Item_, UserArgs_, Error_>(
   state: Active<Item_, UserArgs_, Error_>,
 ): Option.Option<Active<Item_, UserArgs_, Error_>> =>
@@ -553,24 +601,25 @@ export const next = <Item_, UserArgs_, Error_>(
       Match.value(data.isDone).pipe(
         Match.withReturnType<Option.Option<Active<Item_, UserArgs_, Error_>>>(),
         Match.when(true, () => Option.none()),
-        Match.when(false, () =>
-          Option.some({
+        Match.when(false, () => {
+          const end = Option.getOrElse(
+            data.descriptor.endCursor,
+            () => data.continueCursor,
+          );
+          return Option.some({
             ...state,
             requestId: state.requestId + 1,
-            current: {
-              cursor: Option.getOrElse(
-                data.descriptor.endCursor,
-                () => data.continueCursor,
-              ),
-              endCursor: Option.none(),
-            },
-            prevStack: [...state.prevStack, data.descriptor],
+            current: { cursor: end, endCursor: Option.none() },
+            prevStack: [
+              ...state.prevStack,
+              { cursor: data.descriptor.cursor, endCursor: Option.some(end) },
+            ],
             phase: Phase.Refreshing<Item_, Error_>({
               data,
               direction: "Next",
             }),
-          }),
-        ),
+          });
+        }),
         Match.exhaustive,
       ),
     ),
@@ -578,7 +627,9 @@ export const next = <Item_, UserArgs_, Error_>(
     Match.exhaustive,
   );
 
-/** Navigate to the previous page, retaining the current page while it loads. */
+/**
+ * Navigate to the previous page, retaining the current page while it loads.
+ */
 export const prev = <Item_, UserArgs_, Error_>(
   state: Active<Item_, UserArgs_, Error_>,
 ): Option.Option<Active<Item_, UserArgs_, Error_>> =>
@@ -608,7 +659,9 @@ export const prev = <Item_, UserArgs_, Error_>(
     Match.exhaustive,
   );
 
-/** Navigate to page one without invalidating the current pagination session. */
+/**
+ * Navigate to page one without invalidating the current pagination session.
+ */
 export const first = <Item_, UserArgs_, Error_>(
   state: Active<Item_, UserArgs_, Error_>,
 ): Option.Option<Active<Item_, UserArgs_, Error_>> =>
@@ -630,7 +683,9 @@ export const first = <Item_, UserArgs_, Error_>(
     Match.exhaustive,
   );
 
-/** Whether a request still names the machine's live pagination session/page. */
+/**
+ * Whether a request still names the machine's live pagination session/page.
+ */
 export const isCurrentRequest = <Item_, UserArgs_, Error_>(
   state: State<Item_, UserArgs_, Error_>,
   candidate: Request<UserArgs_>,
@@ -799,7 +854,9 @@ export const settle: {
     ),
 );
 
-/** The complete page currently available to render. */
+/**
+ * The complete page currently available to render.
+ */
 export const getPage = <Item_, UserArgs_, Error_>(
   state: State<Item_, UserArgs_, Error_>,
 ): Option.Option<Page<Item_>> =>
@@ -809,13 +866,17 @@ export const getPage = <Item_, UserArgs_, Error_>(
     Match.exhaustive,
   );
 
-/** The items currently available to render. */
+/**
+ * The items currently available to render.
+ */
 export const getItems = <Item_, UserArgs_, Error_>(
   state: State<Item_, UserArgs_, Error_>,
 ): Option.Option<ReadonlyArray<Item_>> =>
   Option.map(getPage(state), (page) => page.items);
 
-/** The error from the most recent failed request, if any. */
+/**
+ * The error from the most recent failed request, if any.
+ */
 export const getError = <Item_, UserArgs_, Error_>(
   state: State<Item_, UserArgs_, Error_>,
 ): Option.Option<Error_> =>
@@ -833,7 +894,9 @@ export const getError = <Item_, UserArgs_, Error_>(
     Match.exhaustive,
   );
 
-/** The 1-indexed page number currently targeted by the subscription. */
+/**
+ * The 1-indexed page number currently targeted by the subscription.
+ */
 export const targetPageNumber = <Item_, UserArgs_, Error_>(
   state: Active<Item_, UserArgs_, Error_>,
 ): number => state.prevStack.length + 1;
@@ -948,7 +1011,9 @@ export const canPrev = <Item_, UserArgs_, Error_>(
     Match.exhaustive,
   );
 
-/** Pattern-match exhaustively on the machine's AsyncData-style state. */
+/**
+ * Pattern-match exhaustively on the machine's AsyncData-style state.
+ */
 export const match: {
   <Item_, Error_, A, B, C, D, E, F>(handlers: {
     readonly onIdle: (idle: Idle) => A;

package/src/Subscription.ts

@@ -44,18 +44,17 @@ const paginatedError = <Query extends Ref.AnyConfectPublicPaginatedQuery>(
 
 /**
  * The dependency record of a `reactiveQuery` entry. `None` means the
- * subscription is closed; a change from one `Some` to another tears the
- * server subscription down and reopens it with the new args.
+ * subscription is closed; a change from one `Some` to another tears the server
+ * subscription down and reopens it with the new args.
  */
 export interface Dependencies<Query extends Ref.AnyConfectPublicQuery> {
   readonly args: Option.Option<Ref.Args<Query>>;
 }
 
 /**
- * Maps a reactive query's emissions into the app's Messages. Every failure —
- * the ref's typed error, a transport error, or a codec error — arrives via
- * `onError`, so the resulting stream's error channel is `never`, as Foldkit
- * requires.
+ * Maps a reactive query's emissions into the app's Messages. Every failure—the
+ * ref's typed error, a transport error, or a codec error—arrives via `onError`,
+ * so the resulting stream's error channel is `never`, as Foldkit requires.
  */
 export interface Handlers<
   Query extends Ref.AnyConfectPublicQuery,
@@ -79,13 +78,13 @@ type ArgsConfig<Query extends Ref.AnyConfectPublicQuery, Model> = {
     });
 
 /**
- * A `dependenciesToStream` body for a hand-written subscription entry: runs
- * the ref as a reactive query against the `Client` resource and maps
- * every emission and every failure into a Message. Query failures are values,
- * so the subscription remains live and can later emit a successful result.
+ * A `dependenciesToStream` body for a hand-written subscription entry: runs the
+ * ref as a reactive query against the `Client` resource and maps every emission
+ * and every failure into a Message. Query failures are values, so the
+ * subscription remains live and can later emit a successful result.
  *
- * Prefer `reactiveQuery`, which builds the whole entry; reach for this when
- * you need control over the entry's dependencies (custom gating, extra
+ * Prefer `reactiveQuery`, which builds the whole entry; reach for this when you
+ * need control over the entry's dependencies (custom gating, extra
  * dependencies).
  */
 export const reactiveQueryStream =
@@ -109,30 +108,34 @@ export const reactiveQueryStream =
 
 /**
  * A complete Foldkit subscription entry for a Confect reactive query. The
- * leading thunk fixes the `Model` type (TypeScript cannot partially infer
- * type arguments), so the `args` extractor's parameter is already typed.
- * Pass the result as an entry value to `Subscription.make`:
+ * leading thunk fixes the `Model` type (TypeScript cannot partially infer type
+ * arguments), so the `args` extractor's parameter is already typed. Pass the
+ * result as an entry value to `Subscription.make`:
  *
  * ```ts
- * import * as Confect from "@confect/foldkit"
- * import * as Subscription from "foldkit/subscription"
+ * import * as Confect from "@confect/foldkit";
+ * import * as Subscription from "foldkit/subscription";
  *
  * const subscriptions = Subscription.make<
  *   Model,
  *   Message,
  *   Confect.Client.Client
  * >()(() => ({
- *   note: Confect.Subscription.reactiveQuery<Model>()(refs.public.notes.get, {
- *     args: (model) => Option.map(model.noteId, (noteId) => ({ noteId })),
- *     onSuccess: (note) => SucceededGetNote({ note }),
- *     onError: (error) => FailedGetNote({ message: String(error) }),
- *   }),
- * }))
+ *   note: Confect.Subscription.reactiveQuery<Model>()(
+ *     refs.public.notes.get,
+ *     {
+ *       args: (model) =>
+ *         Option.map(model.noteId, (noteId) => ({ noteId })),
+ *       onSuccess: (note) => SucceededGetNote({ note }),
+ *       onError: (error) => FailedGetNote({ message: String(error) }),
+ *     },
+ *   ),
+ * }));
  * ```
  *
  * The entry's dependencies are the query args wrapped in `Option`: `None`
- * closes the subscription, a change from one `Some` to another unsubscribes
- * and resubscribes with the new args, and structurally equal args leave the
+ * closes the subscription, a change from one `Some` to another unsubscribes and
+ * resubscribes with the new args, and structurally equal args leave the
  * subscription running (equivalence is derived from the ref's args schema).
  * Queries without args may omit `args`, leaving the subscription always open.
  */
@@ -170,18 +173,17 @@ export const reactiveQuery =
 
 /**
  * A complete Foldkit subscription entry that keeps exactly one live reactive
- * page subscription in sync with a `PaginatedQuery` machine in the Model.
- * The machine state is the single source of truth: navigation and
- * split-pinning change the derived args, while `Idle` closes the subscription.
- * Pagination ids are allocated here and installed by the first settlement.
+ * page subscription in sync with a `PaginatedQuery` machine in the Model. The
+ * machine state is the single source of truth: navigation and split-pinning
+ * change the derived args, while `Idle` closes the subscription. Pagination ids
+ * are allocated here and installed by the first settlement.
  *
- * The leading thunk fixes the `Model` type (TypeScript cannot partially
- * infer type arguments), so the `state` extractor's parameter is already
- * typed:
+ * The leading thunk fixes the `Model` type (TypeScript cannot partially infer
+ * type arguments), so the `state` extractor's parameter is already typed:
  *
  * ```ts
- * import * as Confect from "@confect/foldkit"
- * import * as Subscription from "foldkit/subscription"
+ * import * as Confect from "@confect/foldkit";
+ * import * as Subscription from "foldkit/subscription";
  *
  * const subscriptions = Subscription.make<
  *   Model,
@@ -192,13 +194,13 @@ export const reactiveQuery =
  *     state: (model) => model.notes,
  *     onSettled: (settlement) => SettledGetNotesPage({ settlement }),
  *   }),
- * }))
+ * }));
  * ```
  *
  * Pass the settlement to `PaginatedQuery.settle` in `update`. The request
  * identity is included in both success and failure Messages, so superseded
- * outcomes cannot settle a newer page or pagination session. Query failures
- * do not close the Convex subscription; a later result can recover naturally.
+ * outcomes cannot settle a newer page or pagination session. Query failures do
+ * not close the Convex subscription; a later result can recover naturally.
  */
 type DependenciesSchema<Dependencies_> = Schema.Schema<Dependencies_> & {
   readonly fields: Schema.Struct.Fields;