@ultimat3/query 23.0.0 → 25.0.0

package/src/index.ts

@@ -6,8 +6,10 @@
  * authorize or execute on its own. One authz system, structurally.
  */
 
-// Anchored on purpose, and NOT by the `sideEffects` array: Bun reads any array as `false` and drops
-// the module regardless (oven-sh/bun#40650). `registerPrimitiveRegistrar('query', …)` here is read
+// Anchored on purpose, and not by the `sideEffects` array alone: Bun before 1.4.1 read any array as
+// `false` and dropped the module regardless (oven-sh/bun#40650), and a bare import holds on every
+// bundler. The array still lists it, because a bundler that honours the array drops a bare import
+// of a module it does not list. `registerPrimitiveRegistrar('query', …)` here is read
 // by @ultimat3/core's registrar table on behalf of `x` and the manifest, and nothing that registers
 // a query imports this module for a binding. `SIDE_EFFECTS_ANCHORS` carries the argument and
 // `bun run side-effects` enforces it.
@@ -15,33 +17,25 @@ import './registry';
 
 /**
  * Flight control for the typed client, and OPT-IN by construction: `client.ts` names `ClientFlight`
- * as a TYPE only, so a caller that never mentions `createClientFlight` pays nothing for the fence,
+ * as a TYPE only, so a caller that never mentions `clientFlight` pays nothing for the fence,
  * the dedup map or the retry loop. Every mechanism underneath is `@ultimat3/core`'s — one fence,
  * one flight map, one gate, one backoff curve for the whole framework — and so is the pipeline
  * itself: it shipped as a byte-identical copy here and in `@ultimat3/action`, and
  * two tier-3 packages may not import each other, so the one copy lives at tier 0.
  *
- * Re-exported rather than re-declared, so every name is importable from this package exactly as
- * before. `isSuperseded` is core's too: reading a fenced answer is the point of installing a
- * flight, and it should not cost a second import.
+ * `ClientFlight` and `ClientRetry` are re-exported as TYPES because this barrel's options name
+ * them; every value (`clientFlight`, `isSuperseded`, …) is imported from `@ultimat3/core`,
+ * its one home — a re-export is a second import path (`X_HELPER_COPY`, `bun run flight-copies`).
  */
-export type {
-  ClientFlight,
-  ClientFlightOptions,
-  ClientRetry,
-  FlightKeyOptions,
-  FlightPlan,
-  WireAnswer,
-} from '@ultimat3/core';
-export {
-  createClientFlight,
-  DEFAULT_CLIENT_RETRY,
-  isSuperseded,
-  isTransientFailure,
-} from '@ultimat3/core';
+export type { ClientFlight, ClientRetry } from '@ultimat3/core';
 /** Re-exported so a `query` file needs one import, not two. Same object as schema's. */
 export type { Infer } from '@ultimat3/schema';
 export { t } from '@ultimat3/schema';
+/**
+ * The two refusals `query({ audit: true })` adds. The record and the sink are `@ultimat3/core`'s
+ * (`setAuditSink`) — one sink for every audited primitive, so this package re-exports neither.
+ */
+export { QueryAuditSinkFailedError, QueryAuditSinkMissingError } from './audit-errors';
 export type { QueryCacheScope } from './cache';
 /** `readAuthority` is the ONLY producer of `cacheKeyFor`'s authority — never spell one by hand. */
 export {
@@ -65,11 +59,15 @@ export type {
 } from './client';
 /** `queryClient` is the map-wide read client; `queryClientMethodFor` is what `.client()` binds. */
 export { queryClient, queryClientMethodFor } from './client';
-/** The compat window a retirement gets. Versioning is two deployments, not a router feature. */
-export type { Deprecation, DeprecationField, DeprecationRender } from './deprecation';
-export { recordDeprecatedCall, renderDeprecation } from './deprecation';
+/**
+ * `isNull` is the one definition of SQL NULL a custom `SqlSource` has to agree with, and
+ * `totalOrder` is the one definition of the order it must serve a page in. `compareRows`,
+ * `matchesFilter` and `isAfterKey` take the relation's declared kinds — `kindsOf(shape.entity)` —
+ * because how two values compare is `@ultimat3/entity`'s answer for the column's kind.
+ */
+export type { KindOf } from './column-kinds';
+export { kindsOf } from './column-kinds';
 export {
-  CursorInvalidError,
   CursorValueUnsupportedError,
   MatcherUnsupportedError,
   QueryColumnUnselectedError,
@@ -90,27 +88,19 @@ export {
 /** The HTTP projection: `GET /_x/query/<kebab>`, the URL `client()` derives. */
 export { toQueryRoute } from './http';
 export type { LiveCursor, LiveQuery, ResumeMode, ResumePlan, ToLiveOptions } from './live';
-export { planResume, seekOf, toLiveQuery } from './live';
+export { planResume, seekOf, spendQueryLimit, toLiveQuery } from './live';
 export type { ChangeEvent, ChangeOp, Patch } from './matcher';
 export { assertMatchable, match, positionFor } from './matcher';
-export type { QueryToolDescriptor, QueryToolReadOptions } from './mcp-tool';
-export { isExposed, toQueryTool, toQueryTools } from './mcp-tool';
-/**
- * Path derivation only. There is no `toToolName`: an MCP tool is served under the export name
- * verbatim, and an exported derivation would be a second way to spell one tool.
- */
-export { derivePath } from './naming';
 /**
  * The read half of `openapi.json`. `@ultimat3/cli` merges these paths into `@ultimat3/action`'s
  * `buildOpenApi` document — the two packages are one tier and cannot compose each other.
  */
 export { queryOpenApiPaths, toQueryOpenApiOperation } from './openapi';
 /**
- * The two search-string keys that page `GET /_x/query/<name>` — `_first` and `_after` — and the
- * shape the typed client's `.page()` takes. `MAX_PAGE_SIZE` is the bound both ends check.
+ * The shape the typed client's `.page()` takes. The bound both ends check is `@ultimat3/entity`'s
+ * `MAX_PAGE_SIZE` — imported from there, never re-published here.
  */
 export type { PageControls } from './page-controls';
-export { MAX_PAGE_SIZE } from './page-controls';
 /**
  * The shapes `query.page(input, { first, after })` takes and answers with. `paginate` itself is
  * deliberately unexported: a page is the read's own answer, and a second, importable way to ask
@@ -120,19 +110,12 @@ export { MAX_PAGE_SIZE } from './page-controls';
 export type { Page, PaginateArgs } from './pagination';
 export type { QueryPolicy, QuerySubject, QuerySurface } from './policy-gate';
 /**
- * `policyCapability` is the display label; `policyPermissions` is what a report MATCHES on.
- * `admitsAnonymous` is `@ultimat3/policy`'s, re-exported here beside them: it is what
- * `toQueryRoute` derives `meta.auth` from, so a plain `route` sets that field from the same walk
- * rather than re-reading the root combinator.
+ * The one authz gate for reads, named after what it guards. The display label
+ * (`policyCapability`), what a report MATCHES on (`policyPermissions`) and what `toQueryRoute`
+ * derives `meta.auth` from (`admitsAnonymous`) are `@ultimat3/policy`'s, and the anonymous →
+ * `null` mapping (`actorOf`) is `@ultimat3/core`'s — imported from there, never re-published.
  */
-export {
-  actorOf,
-  admitsAnonymous,
-  guard,
-  guardBeforeInput,
-  policyCapability,
-  policyPermissions,
-} from './policy-gate';
+export { guardQuery, guardQueryBeforeInput } from './policy-gate';
 export type {
   AnyQuery,
   Query,
@@ -140,10 +123,6 @@ export type {
   QueryDef,
   QueryDescriptor,
   QueryFacade,
-  QueryListFilterOp,
-  QueryListParams,
-  QueryMcp,
-  QueryMcpAnnotations,
   QueryOptions,
   QueryRateLimit,
   SourceOptions,
@@ -151,33 +130,30 @@ export type {
 export { describeQuery, isQuery, query, queryHash } from './query';
 /** The one read path. `defOf` stays unexported — that is the enforcement. */
 export { queryName, runQuery, sourceFor } from './read';
-
 export {
   describeQueries,
   getQuery,
   listQueries,
   registerQueries,
   registerQuery,
-  resetRegistry,
+  resetQueries,
 } from './registry';
 /** The query FACTORY over an entity's searchable columns — a `query`, never a ninth primitive. */
 export type { SearchChain, SearchDef, SearchInput, SearchPage } from './search';
 export { search } from './search';
 export type { Filter, FilterOp, OrderKey, QueryShape, SeekKey } from './shape';
-/**
- * `isNull` is the one definition of SQL NULL a custom `SqlSource` has to agree with, and
- * `totalOrder` is the one definition of the order it must serve a page in.
- */
 export {
   compareRows,
-  compareValues,
   isNull,
   matchesFilter,
   seekKeyOf,
   totalOrder,
 } from './shape';
-export type { RowProvider, SqlSource, SqlText } from './source';
+/** What a `single: true` read answers — one rule, also `@ultimat3/mcp`'s served tool's. */
+export { readAnswer } from './single-answer';
+/** `Builder` is a type only: `from()` is the one way to build one, so there is no `new Builder()`. */
+export type { Builder, RowProvider, SqlSource, SqlText } from './source';
 /** `isAfterKey` is the one definition of "after this position" — both seek paths use it. */
-export { Builder, from, isAfterKey } from './source';
+export { from, isAfterKey } from './source';
 export type { ExplainResult, QuerySqlInfo } from './sql';
-export { describeSql, explain } from './sql';
+export { describeSql, explainQuery } from './sql';

package/src/input-shape.ts

@@ -20,7 +20,7 @@ import { QueryInputUnencodableError } from './errors';
 import { PAGE_CONTROL_KEYS } from './page-controls';
 
 /** Node kinds whose value is a structure, not characters. `money` is `{ minor, currency }`. */
-const STRUCTURAL = new Set(['object', 'record', 'money']);
+const STRUCTURAL = new Set(['object', 'record', 'money', 'json']);
 
 /**
  * The first key this input could not put on a wire, or `undefined`. One key, not a list: a fix
@@ -79,3 +79,23 @@ export function assertEncodableInput(input: unknown): void {
   const offender = unencodable(node);
   if (offender !== undefined) throw new QueryInputUnencodableError(offender);
 }
+
+/**
+ * The route's half of an empty array. `searchOf` sends NOTHING for `[]` — a query string has no
+ * spelling for "this key, zero times" — so a REQUIRED array nobody sent can only be the empty one:
+ * left absent it fails validation, on a call the typed client accepted.
+ *
+ * Required only. An optional or defaulted array already has a meaning for absence, and it is the
+ * schema's: `[]` there would overwrite a declared default with a value the caller never wrote.
+ */
+export function absentArraysOf(
+  schema: unknown,
+  input: Readonly<Record<string, unknown>>,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...input };
+  for (const [key, child] of Object.entries(tryIntrospect(schema)?.properties ?? {})) {
+    if (child.kind !== 'array' || child.optional === true || child.hasDefault === true) continue;
+    if (!Object.hasOwn(input, key)) out[key] = [];
+  }
+  return out;
+}

package/src/live.ts

@@ -12,9 +12,11 @@ import type { StandardSchemaV1 } from '@ultimat3/schema';
 import type { Patch } from './matcher';
 import { assertMatchable } from './matcher';
 import type { QueryPolicy, QuerySubject } from './policy-gate';
-import { guard } from './policy-gate';
-import type { Query } from './query';
+import { guardQuery } from './policy-gate';
+import type { AnyQuery, Query } from './query';
 import { queryHash } from './query';
+import type { QueryLimitCaller } from './rate-limit-gate';
+import { spendReadLimit } from './rate-limit-gate';
 import { queryName, sourceFor } from './read';
 import { assertNoSealedKey } from './sealed-shape';
 import type { QueryShape, SeekKey } from './shape';
@@ -103,6 +105,20 @@ export interface ToLiveOptions {
 const SHARED_WINDOW_REASON =
   'the shared subject-less window has no subscriber to decide about; authorize() runs per subscriber';
 
+/**
+ * A live SUBSCRIBE's spend of the read's declared `rateLimit:` — the bucket the HTTP route, a paged
+ * read and the MCP tool spend. Its own export because the subscribe is realtime's: the sync node
+ * builds one shared window per `(query, input)` with no subscriber (`enforce: false`, which spends
+ * nothing) and calls this once per subscriber, beside `authorize`. Never on a re-authorization:
+ * the subscription it already holds was paid for.
+ */
+export function spendQueryLimit(
+  target: AnyQuery,
+  caller: Omit<QueryLimitCaller, 'surface'>,
+): Promise<void> {
+  return spendReadLimit(queryName(target), target.rateLimit, { ...caller, surface: 'live' });
+}
+
 /** Changing the build changes the epoch, which forces reconnects to refetch. */
 export function liveEpoch(): string {
   return Bun.env['X_BUILD_ID'] ?? 'dev';
@@ -148,7 +164,7 @@ export async function toLiveQuery<TInput extends StandardSchemaV1, TRow extends
     limit: shape.limit,
     execute: () => source.execute(),
     authorize: async (subject) => {
-      guard(policy, subject, 'live');
+      guardQuery(policy, subject, 'live');
     },
     initialCursor: (rows) => ({
       epoch,

package/src/matcher.ts

@@ -4,6 +4,8 @@
  * filters + orderBy + limit; anything else throws X_MATCHER_UNSUPPORTED, because
  * an honest refusal beats a silently wrong result set.
  */
+import type { KindOf } from './column-kinds';
+import { kindsOf } from './column-kinds';
 import { MatcherUnsupportedError, QueryNotPageableError } from './errors';
 import type { QueryShape } from './shape';
 import { compareRows, matchesFilters, totalOrder } from './shape';
@@ -58,7 +60,10 @@ export function match<TRow extends object>(
   const id = idOf(event.row, shape.entity);
   const index = rows.findIndex((row) => idOf(row, shape.entity) === id);
   const inSet = index >= 0;
-  const belongs = event.op !== 'delete' && matchesFilters(event.row, shape.filters);
+  // The declared kinds of the relation's columns, resolved once for this event: every comparison
+  // below is `@ultimat3/entity`'s, asked under the kind Postgres would decide by.
+  const kindOf = kindsOf(shape.entity);
+  const belongs = event.op !== 'delete' && matchesFilters(event.row, shape.filters, kindOf);
 
   if (event.op === 'delete' || (inSet && !belongs)) {
     return inSet ? removeAt(shape, index, id, true, rows.length) : [];
@@ -81,14 +86,14 @@ export function match<TRow extends object>(
     return [{ kind: 'refill', from: 0 }];
   }
 
-  if (!inSet) return insert(shape, rows, event.row);
+  if (!inSet) return insert(shape, rows, event.row, kindOf);
 
   // Present and still matching: a change to an ordering column is a move, not an update.
   const current = rows[index];
   const moved =
     shape.orderBy.length > 0 &&
     current !== undefined &&
-    compareRows(event.row, current, shape.orderBy) !== 0;
+    compareRows(event.row, current, shape.orderBy, kindOf) !== 0;
   if (!moved) return [{ kind: 'update', position: index, row: event.row }];
 
   const without = [...rows.slice(0, index), ...rows.slice(index + 1)];
@@ -100,12 +105,12 @@ export function match<TRow extends object>(
   // window is `[b, c, d]`. Whether the moved row is still in the window is the server's answer
   // too, so the refill covers both.
   const wasFull = shape.limit !== null && rows.length >= shape.limit;
-  if (wasFull && positionFor(shape, without, event.row) >= without.length) {
+  if (wasFull && positionFor(shape, without, event.row, kindOf) >= without.length) {
     return removeAt<TRow>(shape, index, id, true, rows.length);
   }
   return [
     ...removeAt<TRow>(shape, index, id, false, rows.length),
-    ...insert(shape, without, event.row),
+    ...insert(shape, without, event.row, kindOf),
   ];
 }
 
@@ -113,8 +118,9 @@ function insert<TRow extends object>(
   shape: QueryShape,
   rows: readonly TRow[],
   row: TRow,
+  kindOf: KindOf,
 ): readonly Patch<TRow>[] {
-  const position = positionFor(shape, rows, row);
+  const position = positionFor(shape, rows, row, kindOf);
   // Sorted past the end of a full window: the row exists but nobody sees it.
   if (shape.limit !== null && position >= shape.limit) return [];
   const patches: Patch<TRow>[] = [{ kind: 'add', position, row }];
@@ -186,10 +192,11 @@ export function positionFor<TRow extends object>(
   shape: QueryShape,
   rows: readonly TRow[],
   row: TRow,
+  kindOf: KindOf = kindsOf(shape.entity),
 ): number {
   if (shape.orderBy.length === 0) return rows.length;
   const order = totalOrder(shape.orderBy);
-  const found = rows.findIndex((current) => compareRows(row, current, order) < 0);
+  const found = rows.findIndex((current) => compareRows(row, current, order, kindOf) < 0);
   return found === -1 ? rows.length : found;
 }
 

package/src/openapi.ts

@@ -16,13 +16,17 @@
  */
 
 import { tagKeys } from '@ultimat3/cache';
-import { RECORDS_OPENAPI_HEADER, recordEnvelopeSchema } from '@ultimat3/core';
+import {
+  isMcpExposed,
+  queryPath,
+  RECORDS_OPENAPI_HEADER,
+  recordEnvelopeSchema,
+} from '@ultimat3/core';
+import { MAX_PAGE_SIZE } from '@ultimat3/entity';
+import { policyCapability } from '@ultimat3/policy';
 import type { SchemaNode } from '@ultimat3/schema';
 import { nodeToJsonSchema, tryIntrospect } from '@ultimat3/schema';
-import { isExposed } from './mcp-tool';
-import { derivePath } from './naming';
-import { MAX_PAGE_SIZE, PAGE_AFTER_KEY, PAGE_FIRST_KEY } from './page-controls';
-import { policyCapability } from './policy-gate';
+import { PAGE_AFTER_KEY, PAGE_FIRST_KEY } from './page-controls';
 import type { AnyQuery } from './query';
 import { queryName } from './read';
 import { answersRecords } from './record-answer';
@@ -48,19 +52,22 @@ const ANSWERS: readonly Record<string, unknown>[] = [
   { type: 'array', items: {} },
   {
     type: 'object',
-    // `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'],
+    // The one page shape: the `endCursor`/`hasNextPage` alias pair left in 25.0.0 (O-12).
+    required: ['rows', 'nextCursor', 'hasMore'],
     properties: {
       rows: { type: 'array', items: {} },
       nextCursor: {
         type: ['string', 'null'],
-        description: `the signed cursor that continues this listing — send it as ${PAGE_AFTER_KEY}; null on an empty page`,
+        description: `the signed cursor for the next page — send it as ${PAGE_AFTER_KEY}; null exactly when hasMore is false`,
       },
       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' },
     },
+    // `@ultimat3/core`'s `Page` is a union, and so is its wire shape: the two facts cannot
+    // disagree in a body this document validates (25.0.0 — the last page used to keep a cursor).
+    oneOf: [
+      { properties: { nextCursor: { type: 'string' }, hasMore: { const: true } } },
+      { properties: { nextCursor: { type: 'null' }, hasMore: { const: false } } },
+    ],
   },
 ];
 
@@ -70,7 +77,7 @@ export function queryOpenApiPaths(
 ): Record<string, OpenApiPathItem> {
   const paths: Record<string, OpenApiPathItem> = {};
   for (const target of [...queries].sort(compareByName)) {
-    paths[derivePath(queryName(target))] = { get: toQueryOpenApiOperation(target) };
+    paths[queryPath(queryName(target))] = { get: toQueryOpenApiOperation(target) };
   }
   return paths;
 }
@@ -117,9 +124,9 @@ export function toQueryOpenApiOperation(target: AnyQuery): Record<string, unknow
       capability: policyCapability(target.policy),
       live: target.isLive,
       cacheTags: tagKeys(target.cache?.tags ?? []),
-      // The same rule `toMcpTool` and the action side apply: a tool is advertised only where the
-      // MCP catalog lists one, under the export name verbatim (`mcp-tool.ts`).
-      tool: isExposed(target) ? name : null,
+      // Core's one predicate, the one `@ultimat3/mcp`'s catalog and the action side ask: a tool is
+      // advertised only where the MCP catalog lists one, under the export name verbatim.
+      tool: isMcpExposed(target.mcp) ? name : null,
     },
   };
 }
@@ -156,7 +163,7 @@ function singleOperation(target: AnyQuery, name: string): Record<string, unknown
       live: target.isLive,
       single: true,
       cacheTags: tagKeys(target.cache?.tags ?? []),
-      tool: isExposed(target) ? name : null,
+      tool: isMcpExposed(target.mcp) ? name : null,
     },
   };
 }
@@ -177,7 +184,7 @@ const PAGE_PARAMETERS: readonly Record<string, unknown>[] = [
     name: PAGE_AFTER_KEY,
     in: 'query',
     required: false,
-    description: `the nextCursor (alias endCursor) a previous page answered; needs ${PAGE_FIRST_KEY}`,
+    description: `the nextCursor a previous page answered; needs ${PAGE_FIRST_KEY}`,
     schema: { type: 'string' },
   },
 ];

package/src/page-controls.ts

@@ -11,21 +11,17 @@
 // the framework's own namespace mark — the route lives under `/_x/` for the same reason — and
 // `input-shape.ts` refuses a declaration that reaches for it, so the two names can never collide.
 
+import { MAX_PAGE_SIZE } from '@ultimat3/entity';
 import { QueryInputInvalidError } from './errors';
 import { PAGE_AFTER_KEY, PAGE_FIRST_KEY } from './page-keys';
 
 export { PAGE_AFTER_KEY, PAGE_FIRST_KEY };
 export const PAGE_CONTROL_KEYS: readonly string[] = [PAGE_FIRST_KEY, PAGE_AFTER_KEY];
 
-/**
- * The largest page a read will serve. A TWIN of `@ultimat3/entity`'s `MAX_PAGE_SIZE` — this
- * package holds no dependency on that one, the same compromise `naming.ts` and `deprecation.ts`
- * are ported under — and it exists for the same reason: `first` reaches `paginate` straight from
- * an action's input or a route parameter, so `args.first + 1` bound whatever a client sent and one
- * request could ask for five million rows. Lives here rather than in `pagination.ts` because the
- * route validates against it BEFORE `paginate` runs — see `pageControlsOf`.
- */
-export const MAX_PAGE_SIZE = 10_000;
+// The largest page a read will serve is `@ultimat3/entity`'s `MAX_PAGE_SIZE`, imported — a batch
+// and a page are one memory bound, and this package already depends on entity. `first` reaches
+// `paginate` straight from a route parameter, so the route judges it against that bound BEFORE
+// `paginate` runs (`pageControlsOf`), and one request can never ask for five million rows.
 
 /** What the route hands `query.page()` — `PaginateArgs` minus the server-side options. */
 export interface PageControls {

package/src/page-keys.ts

@@ -5,5 +5,5 @@
 
 /** `?_first=20` — the page size. Present is what makes the route answer a `Page`. */
 export const PAGE_FIRST_KEY = '_first';
-/** `?_after=<cursor>` — the signed cursor the previous page's `endCursor` carried. */
+/** `?_after=<cursor>` — the signed cursor the previous page's `nextCursor` carried. */
 export const PAGE_AFTER_KEY = '_after';