@ultimat3/query 22.10.0 → 22.12.0

package/CLAUDE.md

@@ -38,7 +38,8 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
 
 ## Invariants — the read path
 
-- Every surface goes through `sourceFor`: parse input, evaluate policy, build the source. A second
+- Every surface goes through `sourceFor`: the policy's actor half (`guardBeforeInput`), parse input,
+  evaluate policy, build the source. A second
   read path is the one unforgivable change here.
 - **An explicit `ctx` is INSTALLED, never merely passed** — the ambient context (which
   `@ultimat3/entity`'s tenant guard reads) must be the identity `guard()` decided about.

package/README.md

@@ -336,16 +336,19 @@ not exported, because a page is the read's own answer rather than an imported he
 ### The same page over HTTP — `?_first=` and `?_after=`
 
 The route reads two controls off the search string BEFORE the schema sees it, and with either
-present answers the `Page` envelope `.page()` answers a server caller with — `{ rows, endCursor,
-hasNextPage }`, the same names, so a cursor read off the wire and one read off a direct call are
-one string in one field. Without a control the answer is the bare array it has always been, so a
+present answers the `Page` envelope `.page()` answers a server caller with — `{ rows, nextCursor,
+hasMore, endCursor, hasNextPage }`, the same names, so a cursor read off the wire and one read off a
+direct call are one string in one field. **`nextCursor` and `hasMore` are the preferred names**
+(`As of 22.12`); `endCursor` and `hasNextPage` carry the same two values, always, as aliases — not
+deprecated, so a client reading them keeps working. `openapi.json` lists all five as required, the
+aliases described as such. Without a control the answer is the bare array it has always been, so a
 client written before the controls existed keeps reading rows. `As of 2026-09`; until then the
 route had no envelope, and a query over a paged external source carried its page marker on a row
 (an `olderCursor` column on the oldest message), which is a cursor on the wrong side of the shape.
 
 ```
-GET /_x/query/live-feed?orgId=…&_first=20             → { rows, endCursor, hasNextPage }
-GET /_x/query/live-feed?orgId=…&_first=20&_after=<c>  → the next page
+GET /_x/query/live-feed?orgId=…&_first=20             → { rows, nextCursor, hasMore, endCursor, hasNextPage }
+GET /_x/query/live-feed?orgId=…&_first=20&_after=<c>  → the next page (<c> = nextCursor)
 GET /_x/query/live-feed?orgId=…                       → [ …rows ]   (unchanged)
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/query",
-  "version": "22.10.0",
+  "version": "22.12.0",
   "description": "The query primitive: a policy-checked read, optionally live, with cursor pagination and an incremental matcher",
   "license": "MIT",
   "type": "module",
@@ -36,11 +36,11 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "22.10.0",
-    "@ultimat3/core": "22.10.0",
-    "@ultimat3/entity": "22.10.0",
-    "@ultimat3/http": "22.10.0",
-    "@ultimat3/policy": "22.10.0",
-    "@ultimat3/schema": "22.10.0"
+    "@ultimat3/cache": "22.12.0",
+    "@ultimat3/core": "22.12.0",
+    "@ultimat3/entity": "22.12.0",
+    "@ultimat3/http": "22.12.0",
+    "@ultimat3/policy": "22.12.0",
+    "@ultimat3/schema": "22.12.0"
   }
 }

package/src/http.ts

@@ -80,7 +80,8 @@ export function toQueryRoute(target: AnyQuery): Route {
       return answerRow(row);
     }
     // With a page control the answer is the `Page` envelope `query.page()` answers a server
-    // caller with — `{ rows, endCursor, hasNextPage }`, the same names, so a cursor read off the
+    // caller with — `{ rows, nextCursor, hasMore, endCursor, hasNextPage }`, the same names (the
+    // last two aliases of the first two), so a cursor read off the
     // wire and one read off a direct call are the same string in the same field. Without one the
     // answer is the bare array it has always been: every client written before the controls
     // existed keeps reading rows, and `hasNextPage` never rides on a row where a page marker

package/src/index.ts

@@ -129,6 +129,7 @@ export {
   actorOf,
   admitsAnonymous,
   guard,
+  guardBeforeInput,
   policyCapability,
   policyPermissions,
 } from './policy-gate';

package/src/openapi.ts

@@ -48,11 +48,18 @@ const ANSWERS: readonly Record<string, unknown>[] = [
   { type: 'array', items: {} },
   {
     type: 'object',
-    required: ['rows', 'endCursor', 'hasNextPage'],
+    // `nextCursor`/`hasMore` are the preferred names; the other two are the same values, kept as
+    // aliases — documented as such, not deprecated — so every client written against them reads on.
+    required: ['rows', 'nextCursor', 'hasMore', 'endCursor', 'hasNextPage'],
     properties: {
       rows: { type: 'array', items: {} },
-      endCursor: { type: ['string', 'null'] },
-      hasNextPage: { type: 'boolean' },
+      nextCursor: {
+        type: ['string', 'null'],
+        description: `the signed cursor that continues this listing — send it as ${PAGE_AFTER_KEY}; null on an empty page`,
+      },
+      hasMore: { type: 'boolean', description: 'whether another page follows' },
+      endCursor: { type: ['string', 'null'], description: 'alias of nextCursor — the same value' },
+      hasNextPage: { type: 'boolean', description: 'alias of hasMore — the same value' },
     },
   },
 ];
@@ -170,7 +177,7 @@ const PAGE_PARAMETERS: readonly Record<string, unknown>[] = [
     name: PAGE_AFTER_KEY,
     in: 'query',
     required: false,
-    description: `the endCursor a previous page answered; needs ${PAGE_FIRST_KEY}`,
+    description: `the nextCursor (alias endCursor) a previous page answered; needs ${PAGE_FIRST_KEY}`,
     schema: { type: 'string' },
   },
 ];

package/src/page-controls.ts

@@ -90,7 +90,7 @@ export function pageControlsOf(name: string, values: SearchValues): SplitSearch
   if (cursor.length === 0) {
     throw new QueryInputInvalidError(
       name,
-      `${PAGE_AFTER_KEY} is empty — omit it for the first page, or send the endCursor the previous page answered`,
+      `${PAGE_AFTER_KEY} is empty — omit it for the first page, or send the nextCursor the previous page answered`,
     );
   }
   return { input, page: { first: Number(size), after: cursor } };

package/src/pagination.ts

@@ -20,12 +20,32 @@ import { compareRows, seekKeyOf, totalOrder } from './shape';
 import type { SqlSource } from './source';
 import { isAfterKey } from './source';
 
+/**
+ * One page. `nextCursor` / `hasMore` are the preferred names; `endCursor` / `hasNextPage` are the
+ * same two values under the names every client before 22.12 reads — aliases, both always present,
+ * never able to disagree because `pageOf` is the one place that writes them.
+ */
 export interface Page<TRow> {
   readonly rows: readonly TRow[];
+  /** The signed cursor that continues this listing; `null` on an empty page. */
+  readonly nextCursor: string | null;
+  /** Whether another page follows. */
+  readonly hasMore: boolean;
+  /** Alias of `nextCursor`. */
   readonly endCursor: string | null;
+  /** Alias of `hasMore`. */
   readonly hasNextPage: boolean;
 }
 
+/** Builds a `Page` from its two facts — the only constructor, so the aliases cannot drift. */
+export function pageOf<TRow>(
+  rows: readonly TRow[],
+  nextCursor: string | null,
+  hasMore: boolean,
+): Page<TRow> {
+  return { rows, nextCursor, hasMore, endCursor: nextCursor, hasNextPage: hasMore };
+}
+
 export interface PaginateArgs extends SourceOptions {
   readonly first: number;
   readonly after?: string;
@@ -70,20 +90,17 @@ export async function paginate<TInput extends StandardSchemaV1, TRow extends obj
   const last = rows[rows.length - 1];
   const seek = last === undefined ? null : seekKeyOf(last, shape);
 
-  return {
-    rows,
-    endCursor:
-      seek === null
-        ? null
-        : encodeCursor({
-            scope: hash,
-            // The id rides TYPED at the tail of the key — core's `id` slot is a string — so a
-            // numeric or bigint tiebreak compares as a number on the next page, not lexically.
-            key: [...seek.key, seek.id].map(serializeSortValue),
-            id: String(seek.id),
-          }),
-    hasNextPage: scoped.length > args.first,
-  };
+  const nextCursor =
+    seek === null
+      ? null
+      : encodeCursor({
+          scope: hash,
+          // The id rides TYPED at the tail of the key — core's `id` slot is a string — so a
+          // numeric or bigint tiebreak compares as a number on the next page, not lexically.
+          key: [...seek.key, seek.id].map(serializeSortValue),
+          id: String(seek.id),
+        });
+  return pageOf(rows, nextCursor, scoped.length > args.first);
 }
 
 /**

package/src/policy-gate.ts

@@ -9,6 +9,7 @@ import { assertNever, isAnonymous } from '@ultimat3/core';
 import type { Policy, Surface as PolicySurface } from '@ultimat3/policy';
 import {
   enforce,
+  enforceBeforeInput,
   policyPermissions as flattenedPermissions,
   admitsAnonymous as policyAdmitsAnonymous,
 } from '@ultimat3/policy';
@@ -42,6 +43,23 @@ export function guard(policy: QueryPolicy, subject: QuerySubject, surface: Query
   if (denial !== undefined) throw new QueryDeniedError(subject.query, denial);
 }
 
+/**
+ * The actor-only half of `guard`, run BEFORE the input is parsed — the twin of
+ * `@ultimat3/action`'s. A reader the policy refuses whatever they send is answered 403 (or 401),
+ * never `X_INPUT_INVALID` with the read's input schema in it. Undecided passes to `guard`.
+ */
+export function guardBeforeInput(
+  policy: QueryPolicy,
+  subject: Omit<QuerySubject, 'input' | 'row'>,
+  surface: QuerySurface,
+): void {
+  const denial = enforceBeforeInput(policySurface(surface), policy, {
+    actor: subject.actor,
+    ctx: subject.ctx,
+  });
+  if (denial !== undefined) throw new QueryDeniedError(subject.query, denial);
+}
+
 /** A direct server read is the job surface: no request, no socket to close. */
 function policySurface(surface: QuerySurface): PolicySurface {
   switch (surface) {

package/src/read.ts

@@ -29,7 +29,7 @@ import {
   readThrough,
 } from './cache';
 import { QueryForeignError, QueryInputInvalidError, QueryUnregisteredError } from './errors';
-import { actorOf, guard } from './policy-gate';
+import { actorOf, guard, guardBeforeInput } from './policy-gate';
 import type { AnyQuery, AnyQueryDef, Query, QueryOptions, SourceOptions } from './query';
 import type { SqlSource } from './source';
 
@@ -204,8 +204,17 @@ async function buildSource(
 ): Promise<SqlSource<object>> {
   const def = defOf(target);
   const name = queryName(target);
-  const input = await validate(def.input, raw, name);
   const unenforced = options.unenforced;
+  // The actor half of the policy first, exactly as `invoke` does it: a reader refused whatever
+  // they send learns nothing about this read's input schema from an `X_INPUT_INVALID`.
+  if (unenforced === undefined) {
+    guardBeforeInput(
+      def.policy,
+      { actor: actorOf(ctx), ctx, query: name },
+      options.surface ?? 'server',
+    );
+  }
+  const input = await validate(def.input, raw, name);
   if (unenforced === undefined) {
     guard(
       def.policy,