@abloatai/transaction 0.52.0 → 0.53.0

package/src/schema/openapi.ts

@@ -36,6 +36,7 @@ import {
   commitRecordListSchema,
   commitRecordWhereSchema,
 } from '../wire/commit.js';
+import { CURSOR_PARAM, CURSOR_PARAM_ALIAS } from '../wire/listEnvelope.js';
 import {
   claimRequestSchema,
   claimHeartbeatRequestSchema,
@@ -185,6 +186,43 @@ function fieldSchema(f: FieldMeta): Json {
 
 const pascal = (s: string): string => s.charAt(0).toUpperCase() + s.slice(1);
 const idParam = (): Json => ({ name: 'id', in: 'path', required: true, schema: { type: 'string' } });
+const idempotencyKeyParam = (): Json => ({
+  name: 'Idempotency-Key',
+  in: 'header',
+  schema: { type: 'string', maxLength: 255 },
+  description: 'Replay identity. Reuse the same key only for an identical request.',
+});
+const collectionPageParams = (): Json[] => [
+  {
+    name: 'limit',
+    in: 'query',
+    schema: { type: 'integer', minimum: 1, maximum: 100, default: 20 },
+  },
+  cursorParam(),
+  retiredCursorParam(),
+];
+
+/** The cursor parameter, named from the wire contract that issues its value. */
+const cursorParam = (): Json => ({
+  name: CURSOR_PARAM,
+  in: 'query',
+  schema: { type: 'string' },
+  description: 'The opaque next_cursor returned by the preceding page.',
+});
+
+/**
+ * The retired spelling, documented as deprecated so a caller still sending it
+ * can see it is going. Declared once: `queryParams` reaches for it too, and a
+ * second copy is how the model list came to document the same parameter without
+ * the deprecation the collection routes carried.
+ */
+const retiredCursorParam = (): Json => ({
+  name: CURSOR_PARAM_ALIAS,
+  in: 'query',
+  deprecated: true,
+  schema: { type: 'string' },
+  description: `Deprecated spelling of ${CURSOR_PARAM}, honoured until it is removed. Send ${CURSOR_PARAM}.`,
+});
 const jsonBody = (schema: Json): Json => ({
   required: true,
   content: { 'application/json': { schema } },
@@ -313,16 +351,22 @@ function withGenericRows(derived: Json): Json {
  */
 function queryParams(schema: z.ZodType): Json[] {
   const props = (derive(schema, 'input').properties ?? {}) as Record<string, Json>;
-  return Object.entries(props).map(([name, s]) => ({
-    name,
-    in: 'query',
-    // Query strings arrive at the server as text, but OpenAPI describes the
-    // caller-facing value before serialization. Generated clients should take
-    // an integer here and encode it, not expose a stringly typed page size.
-    schema: name === 'limit'
-      ? { type: 'integer', minimum: 1 }
-      : s,
-  }));
+  return Object.entries(props).map(([name, s]) => {
+    // The retired cursor spelling is documented the same way wherever it
+    // appears. Derived from the schema it still lives in, so the flag cannot be
+    // present on one route's copy of the parameter and absent on another's.
+    if (name === CURSOR_PARAM_ALIAS) return retiredCursorParam();
+    return {
+      name,
+      in: 'query',
+      // Query strings arrive at the server as text, but OpenAPI describes the
+      // caller-facing value before serialization. Generated clients should take
+      // an integer here and encode it, not expose a stringly typed page size.
+      schema: name === 'limit'
+        ? { type: 'integer', minimum: 1 }
+        : s,
+    };
+  });
 }
 
 const commitRecordListQuerySchema = commitRecordWhereSchema.safeExtend({
@@ -492,8 +536,8 @@ export function abloOpenApi(options: SchemaToOpenApiOptions = {}): Json {
         parameters: [modelParam(), ...queryParams(listQuerySchema)],
         responses: {
           '200': namedResp(
-            'A page of rows. `next_cursor` feeds `starting_after` on the next ' +
-              'call; `stamp` is the watermark the page was read at.',
+            'A page of rows. `next_cursor` feeds `cursor` on the next call; ' +
+              '`stamp` is the watermark the page was read at.',
             'ModelPage',
           ),
         },
@@ -599,6 +643,7 @@ export function abloOpenApi(options: SchemaToOpenApiOptions = {}): Json {
       get: {
         tags: ['branches'],
         summary: 'List transaction branches for the credential project',
+        parameters: collectionPageParams(),
         responses: {
           '200': jsonResp(
             'The root and every active child branch.',
@@ -611,6 +656,7 @@ export function abloOpenApi(options: SchemaToOpenApiOptions = {}): Json {
         summary: 'Create an isolated child branch',
         description:
           'The returned id is immutable; retain it for automation. The slug is a project-scoped human handle.',
+        parameters: [idempotencyKeyParam()],
         requestBody: jsonBody(derive(createBranchRequestSchema, 'input')),
         responses: {
           '201': jsonResp('The ready branch.', derive(branchResponseSchema, 'output')),
@@ -866,7 +912,7 @@ export function abloOpenApi(options: SchemaToOpenApiOptions = {}): Json {
       post: {
         tags: ['commits'],
         summary: 'Commit a batch of operations atomically, and/or register durable premises',
-        parameters: [{ name: 'Idempotency-Key', in: 'header', schema: { type: 'string' }, description: 'Replay-safe key; the server returns the cached receipt on retry.' }],
+        parameters: [idempotencyKeyParam()],
         requestBody: commitBody(),
         responses: { '200': commitReceipt() },
       },
@@ -993,7 +1039,7 @@ export function schemaToOpenApi<S extends SchemaRecord>(
     post: {
       tags: ['commits'],
       summary: 'Commit a batch of operations atomically, and/or register durable premises',
-      parameters: [{ name: 'Idempotency-Key', in: 'header', schema: { type: 'string' }, description: 'Replay-safe key; the server returns the cached receipt on retry.' }],
+      parameters: [idempotencyKeyParam()],
       requestBody: commitBody(),
       responses: { '200': commitReceipt() },
     },

package/src/server/adapter.ts

@@ -61,6 +61,8 @@ export type ReadResult =
   | {
       readonly kind: 'query';
       readonly rows: readonly Row[];
+      /** Opaque upstream cursor when a source-backed list has another page. */
+      readonly nextCursor?: string;
     };
 
 // ── sync ─────────────────────────────────────────────────────────────────────

package/src/server/index.ts

@@ -4,7 +4,8 @@
  * vocabulary ({@link Row}, {@link ReadRequest}, {@link ChangeSet}, and the rest),
  * the {@link CommitContext} and {@link CommitExecutionResult} commit types, the
  * {@link StorageMode} enumeration, and the per-model read configuration
- * ({@link BootstrapModel}, {@link ColumnOverride}). These are plain, driver-free
+ * ({@link ReadModelShape} and the {@link BootstrapModel} descriptor built on it,
+ * plus {@link ColumnOverride} and {@link ParentScope}). These are plain, driver-free
  * types; you supply the database code that fulfills them.
  */
 export type {
@@ -27,4 +28,9 @@ export {
   type CommitRecord,
 } from '../wire/commit.js';
 export { storageModeSchema, type StorageMode } from './storageMode.js';
-export type { ColumnOverride, BootstrapModel } from './readConfig.js';
+export type {
+  ColumnOverride,
+  ParentScope,
+  ReadModelShape,
+  BootstrapModel,
+} from './readConfig.js';

package/src/server/readConfig.ts

@@ -1,9 +1,23 @@
 /**
- * Canonical per-model read configuration consumed when a client bootstraps. Each
- * {@link BootstrapModel} maps a model to its physical table, its tenancy column, and
- * any parent scoping — plain data with no database driver. It feeds the read side of
- * the data adapter contract; your query builder reads it to load a model's initial
- * rows.
+ * Canonical per-model read configuration — how one model's rows are located,
+ * scoped to a tenant, and decoded back into the types the schema declared.
+ *
+ * {@link ReadModelShape} is the definition site for those facts. Every read seam
+ * needs the same set, and each one that restated the set drifted from the
+ * others: `json` decoding reached three of them, `number` decoding reached none,
+ * and the where-clause `boolean` list reached exactly one — so a `bigint`-backed
+ * field left one seam as a decimal string and its `int4` neighbour left the next
+ * as a number. Adding a declared type is now one edit here rather than a
+ * remembered sweep.
+ *
+ * The descriptors below carry that shape plus the facts only they need. They
+ * disagree on one thing, deliberately: the model's own name. A bootstrap
+ * descriptor spells it `name`, the server's read-model descriptor spells it
+ * `typename`. `name` is part of the published data-adapter contract, so the two
+ * spellings stay and the shape they share owns everything else.
+ *
+ * Plain data, no database driver — it feeds the read side of the data adapter
+ * contract, and your query builder reads it to load a model's initial rows.
  */
 
 /** A mapping from a declared field to a physical column, with the alias to apply after a `SELECT *`. */
@@ -13,70 +27,110 @@ export interface ColumnOverride {
   readonly alias: string;
 }
 
-/** Read configuration for one model: how to locate its rows and scope them to a tenant. */
-export interface BootstrapModel {
-  name: string;
+/**
+ * Parent-table tenancy scoping for rows that have no `organization_id` column
+ * of their own, mirroring the schema's `scopedVia` option. A read carrying this
+ * adds:
+ *
+ *   WHERE <table>.<localKey> IN
+ *     (SELECT <parentKey> FROM <parentTable> WHERE <parentOrgColumn> = $1)
+ *
+ * It applies on top of whatever `orgScoped` dictates, so a table can carry its
+ * own `organization_id` and still narrow through a parent. The common case is
+ * `orgScoped: false` together with this on a table that lacks the column —
+ * without it, such a table reads every tenant's rows.
+ */
+export interface ParentScope {
+  readonly localKey: string;
+  readonly parentTable: string;
+  readonly parentKey?: string;
+  readonly parentOrgColumn?: string;
+}
+
+/**
+ * Everything a read seam needs to know about one model except what it is called.
+ *
+ * Split from the descriptors that carry it because the two of them name the
+ * model differently and agree on all of this. A seam that only decodes, or only
+ * compiles SQL, projects the members it uses with `Pick` rather than declaring
+ * its own near-copy.
+ */
+export interface ReadModelShape {
   /**
    * Extra names accepted when a request looks up or filters this model. When the
-   * physical table name is canonical, `name` stays that table name and the aliases
-   * cover generated compatibility names such as `WeatherReports` or `weatherReports`.
+   * physical table name is canonical, the descriptor's own name stays that table
+   * name and the aliases cover generated compatibility names such as
+   * `WeatherReports` or `weatherReports`.
    */
-  aliases?: readonly string[];
+  readonly aliases?: readonly string[];
   /**
-   * The schema key used by source endpoints. `name` stays the wire and result model
-   * name (usually the typename), while source handlers are keyed by the developer's
-   * schema key, such as `files` or `blocks`.
+   * The schema key used by source endpoints. The descriptor's own name stays the
+   * wire and result model name (usually the typename), while source handlers are
+   * keyed by the developer's schema key, such as `files` or `blocks`.
    */
-  sourceModel?: string;
-  table: string;
-  syncGroups?: string[];
-  enabled?: boolean;
-  /** Max rows to return. Omit for unlimited. Maps to schema's bootstrapLimit. */
-  limit?: number;
-  /** SQL ORDER BY clause. Default: 'id'. Maps to schema's bootstrapOrderBy. */
-  orderBy?: string;
+  readonly sourceModel?: string;
+  readonly table: string;
   /** Whether the table has organization_id. Default: true. */
-  orgScoped?: boolean;
+  readonly orgScoped?: boolean;
   /**
    * The model derives its tenant from the connected data source (`policy:
-   * { by: 'source' }`) rather than a row column. It carries no tenant predicate on a
-   * log plane, so it is excluded from the bootstrap set entirely until the
-   * write-through connect path can resolve the org from the source registration —
-   * serving it now would return every row to every tenant. Kept on the type as a
-   * defense-in-depth marker so a source-scoped model that reaches `getBootstrapData`
-   * fails closed rather than bootstrapping unscoped.
+   * { by: 'source' }`) rather than a row column — the source registration is the
+   * tenant boundary. Distinct from `orgScoped: false` (a `none`/global model): a
+   * source-scoped model IS tenant-scoped, just not by a column. It carries no
+   * tenant predicate on a log plane, so every read and bootstrap site fails it
+   * closed with `source_tenancy_not_enforced` rather than treating it as global
+   * — serving it now would return every row to every tenant. When the
+   * write-through connect path can resolve the org from the source registration,
+   * this same flag routes to that resolution.
    */
-  sourceScoped?: boolean;
+  readonly sourceScoped?: boolean;
   /** Physical tenancy column (default `organization_id`, configurable per model). */
-  orgColumn?: string;
-  /**
-   * Parent-table scoping for rows that have no `organization_id` column, mirroring
-   * the schema's `scopedVia` option. When set, the bootstrap query adds:
-   *
-   *   WHERE <table>.<localKey> IN
-   *     (SELECT <parentKey> FROM <parentTable> WHERE <parentOrgColumn> = $1)
-   *
-   * This applies on top of whatever `orgScoped` dictates, so a table can carry its
-   * own `organization_id` and still narrow through a parent. The common case,
-   * though, is `orgScoped: false` together with `scopedVia` on a table that lacks the
-   * column.
-   */
-  scopedVia?: {
-    localKey: string;
-    parentTable: string;
-    parentKey?: string;
-    parentOrgColumn?: string;
-  };
+  readonly orgColumn?: string;
+  /** Parent-table scoping for rows with no tenancy column of their own. */
+  readonly scopedVia?: ParentScope;
   /** Client-facing field name → physical DB column for declared fields. */
-  fieldColumns?: Record<string, string>;
+  readonly fieldColumns?: Readonly<Record<string, string>>;
   /** Physical-column aliases needed after SELECT * for `.from(...)` fields. */
-  columnOverrides?: readonly ColumnOverride[];
+  readonly columnOverrides?: readonly ColumnOverride[];
   /**
-   * Physical columns the schema declares as JSON (via `field.json()`). A JSON field
-   * stored in a text column comes back from `row_to_json` as a serialized string, so
-   * the bootstrap reparses these columns to make the wire value the canonical object
-   * regardless of the physical column type. A `jsonb` column already returns an
-   * object, so reparsing it is a no-op.
+   * Physical columns the schema declares as JSON (via `field.json()`). A JSON
+   * field stored in a text column comes back serialized, so a read reparses these
+   * to make the wire value the canonical object regardless of the physical column
+   * type. A `jsonb` column already returns an object, so reparsing it is a no-op.
    */
-  jsonColumns?: readonly string[];
+  readonly jsonColumns?: readonly string[];
+  /**
+   * Physical columns the schema declares as a boolean (via `field.boolean()`).
+   * Two seams need the list. A where-clause parameter is coerced to a real JS
+   * boolean before binding, because the driver's bool encoder is a strict
+   * `=== true` and a string `'t'` would silently bind as `'f'` — an INVERTED
+   * filter, not an error. A row read back from the log is coerced the same way,
+   * because a value echoed from a customer's database arrives as PG's text
+   * literal rather than as `true`.
+   */
+  readonly boolColumns?: readonly string[];
+  /**
+   * Physical columns the schema declares as a number (via `field.number()`).
+   * Postgres has four integer widths where JavaScript has one, so a column too
+   * wide to always fit a JS number comes back as decimal text. A read decodes
+   * these so a `bigint`-backed field and an `int4`-backed one reach the client as
+   * the same JS type.
+   */
+  readonly numberColumns?: readonly string[];
+}
+
+/**
+ * Read configuration for one model at bootstrap: {@link ReadModelShape} plus the
+ * facts only the initial payload needs — which models are in it, how much of
+ * each, and in what order.
+ */
+export interface BootstrapModel extends ReadModelShape {
+  /** The wire and result model name. `ModelMeta.typename` is the same fact. */
+  readonly name: string;
+  readonly syncGroups?: readonly string[];
+  readonly enabled?: boolean;
+  /** Max rows to return. Omit for unlimited. Maps to schema's bootstrapLimit. */
+  readonly limit?: number;
+  /** SQL ORDER BY clause. Default: 'id'. Maps to schema's bootstrapOrderBy. */
+  readonly orderBy?: string;
 }

package/src/transport/httpClient.ts

@@ -32,10 +32,12 @@ import type {
   HttpTransportModel,
   ModelReadOptions,
   ModelMutationOptions,
+  ModelList,
   CreateSessionParams,
   AbloSession,
   SessionResource,
 } from '../resources/httpResources.js';
+import { modelList } from '../resources/httpResources.js';
 import type {
   ModelCreateParams,
   ModelDeleteParams,
@@ -128,7 +130,12 @@ export interface HttpModelClient<T, C = T> {
    * Reads the rows matching a filter. Same resolution as `get`, in bulk,
    * and deduplicated so concurrent identical calls share one request.
    */
-  list(options?: ServerReadOptions<T>): Promise<CapturedRow<T>[]>;
+  /**
+   * The rows are an array as before; `hasMore` and `nextCursor` on the result
+   * say whether the collection continues past this page. Pass `nextCursor`
+   * back as `cursor`, with the same `where` and `orderBy`, to walk it.
+   */
+  list(options?: ServerReadOptions<T>): Promise<ModelList<CapturedRow<T>>>;
   /**
    * Creates a row and returns it, including any framework-applied defaults.
    * Passing an id that already exists is idempotent: the existing row is
@@ -427,10 +434,16 @@ function createHttpModelClient<T, C = T>(
     return read.data as CapturedRow<T> | undefined;
   };
 
-  const list = async (options?: ServerReadOptions<T>): Promise<CapturedRow<T>[]> => {
+  const list = async (
+    options?: ServerReadOptions<T>,
+  ): Promise<ModelList<CapturedRow<T>>> => {
     const snapshot = await protocol.list(options);
+    const page = modelList<CapturedRow<T>>(
+      snapshot.data as readonly CapturedRow<T>[],
+      snapshot,
+    );
     const registry = readSetContext?.getStore();
-    if (!registry) return [...snapshot.data] as CapturedRow<T>[];
+    if (!registry) return page;
     if (!snapshot.evidence) {
       throw new AbloConnectionError(
         `${modelName}.list did not return row evidence. Upgrade the Ablo server or use get({ id }).`,
@@ -451,7 +464,7 @@ function createHttpModelClient<T, C = T>(
       }
       capturePointRead(readSetContext, clientIdentity, modelName, id, row, stamp);
     }
-    return [...snapshot.data] as CapturedRow<T>[];
+    return page;
   };
 
   // Claim acquisition performs its authoritative read only after the grant.

package/src/transport/httpTransport.ts

@@ -84,6 +84,7 @@ import type {
   ModelMutationOptions,
   ModelReadOptions,
   HttpTransportRead,
+  HttpTransportList,
   HttpLogsResource,
   ModelTarget,
   CreateSessionParams,
@@ -151,6 +152,7 @@ import { declaredMeta, wireMeta } from '../coordination/claimMeta.js';
 import type { Claim, ClaimHeartbeat, ClaimHeartbeatOptions, HeldClaim } from '../types/streams.js';
 import type { CoordinationObservability } from '../observability.js';
 import { assertWriteOptions } from '../resources/writeOptionsSchema.js';
+import { normalizeWhere } from '../resources/where.js';
 import {
   createDurableHttpCommitEnvelope,
   canonicalHttpCommitBody,
@@ -1493,9 +1495,12 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
   async function listModel<T>(
     modelName: string,
     options?: ServerReadOptions<T>,
-  ): Promise<{ readonly data: readonly T[]; readonly evidence?: readonly { id: string; stamp: number }[] }> {
+  ): Promise<HttpTransportList<T>> {
     const params = new URLSearchParams();
     if (options?.limit !== undefined) params.set('limit', String(options.limit));
+    if (options?.cursor !== undefined) {
+      params.set('cursor', options.cursor);
+    }
     if (options?.orderBy) {
       const [col, dir] = Object.entries(options.orderBy)[0] ?? [];
       if (col) {
@@ -1503,12 +1508,27 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
         if (dir === 'desc') params.set('order', 'desc');
       }
     }
-    // The collection route turns any non-reserved query param into an equality
-    // filter (`?status=todo`). The wire is AND-only equality — matches what a
-    // stateless reactor needs; richer predicates stay on the stateful path.
-    if (options?.where && typeof options.where === 'object') {
-      for (const [k, v] of Object.entries(options.where as Record<string, unknown>)) {
-        if (v !== undefined && v !== null && typeof v !== 'object') params.set(k, String(v));
+    // The whole filter travels as the canonical clause list, so every operator
+    // the grammar declares survives the trip. The previous encoding walked the
+    // object's own entries and skipped any value that was an object, which
+    // silently discarded `IN` filters and every tuple-form clause: the request
+    // went out unfiltered and the caller read the result as a filtered one.
+    const clauses = normalizeWhere(options?.where);
+    if (clauses.length > 0) {
+      params.set('where', JSON.stringify(clauses));
+      // Plain equality also goes out in the older `?column=value` shorthand.
+      // A server that predates the `where` parameter does not reserve the name
+      // and does not declare it as a column, so it skips it — and a dropped
+      // filter is not an error there, it is a wider answer than the caller
+      // asked for. Sending both means a version skew loses only the operator
+      // filters, which that server could not have honoured anyway. A current
+      // server ignores a shorthand key the clause list already carries.
+      for (const clause of clauses) {
+        const [column] = clause;
+        const value = clause.length === 2 ? clause[1] : clause[2];
+        if (clause.length === 3 && clause[1] !== '=') continue;
+        if (value === null || typeof value === 'object') continue;
+        params.set(column, String(value));
       }
     }
     const qs = params.toString();
@@ -1523,6 +1543,8 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
     // the typed facade above, which holds the model's schema.
     return {
       data: res.data as T[],
+      hasMore: res.has_more,
+      nextCursor: res.next_cursor,
       ...(res.evidence ? { evidence: res.evidence } : {}),
     };
   }

package/src/wire/accountResponses.ts

@@ -14,6 +14,7 @@
  */
 
 import { z } from 'zod';
+import { listEnvelopeSchema } from './listEnvelope.js';
 // Composed, never restated: these are the artifact's own shapes, and a
 // hand-written mirror here would be a second copy of the exact record this
 // response exists to stop withholding.
@@ -45,16 +46,9 @@ export type ProjectResponse = z.infer<typeof projectResponseSchema>;
 /**
  * `GET /v1/projects`.
  *
- * Note what this is NOT: the canonical {@link ListEnvelope}. An org's projects
- * are returned whole, so the route emits `data` with no `has_more`/`next_cursor`
- * beside it. That divergence is real and this schema states it rather than
- * describing a pagination the endpoint does not implement — adding the two
- * fields is an API change, not a documentation fix.
+ * Uses the canonical paginated list envelope shared by every collection.
  */
-export const projectListResponseSchema = z.object({
-  object: z.literal('list'),
-  data: z.array(projectResponseSchema).readonly(),
-});
+export const projectListResponseSchema = listEnvelopeSchema(projectResponseSchema);
 export type ProjectListResponse = z.infer<typeof projectListResponseSchema>;
 
 /** One minted key, returned exactly once — the plaintext is never readable again. */

package/src/wire/claims.ts

@@ -121,7 +121,13 @@ export const listQuerySchema = z.object({
   limit: z.string().optional(),
   order_by: z.string().optional(),
   order: z.enum(['asc', 'desc']).optional(),
-  /** Keyset cursor: the id of the last row from the previous page. */
+  /**
+   * Keyset cursor: the opaque `next_cursor` the previous page returned. It
+   * encodes the sort position it was issued for, so it is not a row id and is
+   * refused against a different `order_by`/`order`.
+   */
+  cursor: z.string().optional(),
+  /** @deprecated The pre-0.53.0 spelling of `cursor`. Send `cursor`. */
   starting_after: z.string().optional(),
 });
 export type ListQuery = z.infer<typeof listQuerySchema>;

package/src/wire/index.ts

@@ -22,7 +22,13 @@ export {
   INTERNAL_ERROR_PUBLIC_MESSAGE,
 } from './errorEnvelope.js';
 export type { ErrorEnvelope } from './errorEnvelope.js';
-export { listEnvelopeSchema, listEnvelope } from './listEnvelope.js';
+export {
+  listEnvelopeSchema,
+  listEnvelope,
+  CURSOR_PARAM,
+  CURSOR_PARAM_ALIAS,
+  CURSOR_PARAM_NAMES,
+} from './listEnvelope.js';
 export type { ListEnvelope } from './listEnvelope.js';
 
 // The `GET /v1/logs` feed — the two arms, their envelope, and the cursor that

package/src/wire/listEnvelope.ts

@@ -10,6 +10,29 @@
  */
 import { z } from 'zod';
 
+/**
+ * The query parameter a caller resumes a collection with, and the single alias
+ * retained for it.
+ *
+ * Declared beside the envelope that issues `next_cursor`, because the parameter
+ * and the field it consumes are one contract and both planes read them: the
+ * server to know which names are taken, the spec generator to document them,
+ * the client to send one. When the name lived in each of those separately, this
+ * spec described `starting_after` for a model list and `cursor` for a commit
+ * record list — the same concept under two names, in one document.
+ *
+ * `starting_after` is the spelling used through 0.52.0. It borrowed a name whose
+ * established meaning elsewhere is a row id, while this value has always been an
+ * opaque token bound to the sort it was issued for.
+ */
+export const CURSOR_PARAM = 'cursor';
+
+/** @deprecated The pre-0.53.0 spelling of {@link CURSOR_PARAM}. */
+export const CURSOR_PARAM_ALIAS = 'starting_after';
+
+/** Both names a cursor may arrive under, for reserving them in a query string. */
+export const CURSOR_PARAM_NAMES: readonly string[] = [CURSOR_PARAM, CURSOR_PARAM_ALIAS];
+
 /**
  * Builds the authoritative list-envelope schema for a row schema. Keeping the
  * item validator generic lets every endpoint share the same envelope contract