@ultimat3/query 23.0.0 → 25.0.0

package/src/source.ts

@@ -4,9 +4,13 @@
  * app's `sql:` returns `from()` over an `@ultimat3/entity` repo, and a source only has to
  * answer these four questions.
  */
+
+import { compareByKind } from '@ultimat3/entity';
+import type { KindOf } from './column-kinds';
+import { kindsOf } from './column-kinds';
 import { QueryColumnUnselectedError } from './errors';
 import type { Filter, FilterOp, OrderKey, QueryShape, SeekKey } from './shape';
-import { compareRows, compareValues, isNull, matchesFilters, totalOrder } from './shape';
+import { compareRows, isNull, matchesFilters, totalOrder } from './shape';
 import { columnOf } from './stable';
 
 /** Nothing matches. `in ()` is a syntax error in Postgres, so an empty set needs a constant. */
@@ -48,7 +52,7 @@ export type RowProvider<TRow> =
 
 /**
  * In-memory reference source. `from<Post>('posts', rows).where({ orgId }).orderBy('createdAt')`
- * generates real SQL text for `explain()` while executing against the provided rows.
+ * generates real SQL text for `explainQuery()` while executing against the provided rows.
  */
 export function from<TRow extends object>(entity: string, rows: RowProvider<TRow>): Builder<TRow> {
   return new Builder<TRow>(entity, rows, [], [], null, null, []);
@@ -70,7 +74,7 @@ export class Builder<TRow extends object> implements SqlSource<TRow> {
   /**
    * One equality filter per key, and the clauses come out in **lexical key order** — not the order
    * the object literal was typed in. The generated text is something callers compare across runs:
-   * `explain()` prints it, `LiveQuery.sqlText` caches it, and tests pin it. Reordering two keys in
+   * `explainQuery()` prints it, `LiveQuery.sqlText` caches it, and tests pin it. Reordering two keys in
    * a call site must not rewrite the statement.
    */
   where(equals: Readonly<Record<string, unknown>>): Builder<TRow> {
@@ -97,8 +101,13 @@ export class Builder<TRow extends object> implements SqlSource<TRow> {
     return this.derive({ unsupported: [...this.unsupported, feature] });
   }
 
+  /**
+   * The window is the SMALLER of the two limits. It used to replace a declared `.limit()`, so a
+   * page wider than a "top N" served rows the read itself never would.
+   */
   seek(after: SeekKey | null, limit: number): Builder<TRow> {
-    return this.derive({ after, rowLimit: limit, totalized: true });
+    const rowLimit = this.rowLimit === null ? limit : Math.min(this.rowLimit, limit);
+    return this.derive({ after, rowLimit, totalized: true });
   }
 
   /**
@@ -134,14 +143,15 @@ export class Builder<TRow extends object> implements SqlSource<TRow> {
   async execute(): Promise<readonly TRow[]> {
     const source = typeof this.rows === 'function' ? await this.rows() : this.rows;
     this.assertCarried(source);
-    let result = source.filter((row) => matchesFilters(row, this.filters));
+    const kindOf = kindsOf(this.entity);
+    let result = source.filter((row) => matchesFilters(row, this.filters, kindOf));
     const keys = this.servedOrder();
     if (keys.length > 0) {
-      result = [...result].sort((a, b) => compareRows(a, b, keys));
+      result = [...result].sort((a, b) => compareRows(a, b, keys, kindOf));
     }
     if (this.after !== null) {
       const cut = this.after;
-      result = result.filter((row) => isAfterKey(row, cut, this.order));
+      result = result.filter((row) => isAfterKey(row, cut, this.order, kindOf));
     }
     return this.rowLimit === null ? result : result.slice(0, this.rowLimit);
   }
@@ -264,7 +274,7 @@ function filterClause(filter: Filter, slot: Slot): string {
 
 /**
  * NULL's place in the ordering, written down rather than inherited. Postgres already defaults
- * to `nulls last` under `asc` and `nulls first` under `desc` — that is the rule `compareValues`
+ * to `nulls last` under `asc` and `nulls first` under `desc` — that is the rule `compareRows`
  * implements, so the in-memory sort, the live matcher and `seekClause` below can only agree
  * with it. Saying it out loud is what keeps a driver whose default differs from re-opening the
  * divergence, and it is what an agent reads when a nullable sort key surprises it.
@@ -312,11 +322,16 @@ interface BuilderState {
  * pagination needs the same answer when a source cannot push the seek down — a second definition
  * of "after" is how one path skips a row the other returns.
  */
-export function isAfterKey(row: object, cursor: SeekKey, order: readonly OrderKey[]): boolean {
+export function isAfterKey(
+  row: object,
+  cursor: SeekKey,
+  order: readonly OrderKey[],
+  kindOf: KindOf,
+): boolean {
   for (const [index, key] of order.entries()) {
-    const result = compareValues(columnOf(row, key.column), cursor.key[index]);
+    const result = compareByKind(kindOf(key.column), columnOf(row, key.column), cursor.key[index]);
     const signed = key.direction === 'asc' ? result : -result;
     if (signed !== 0) return signed > 0;
   }
-  return compareValues(columnOf(row, 'id'), cursor.id) > 0;
+  return compareByKind(kindOf('id'), columnOf(row, 'id'), cursor.id) > 0;
 }

package/src/sql.ts

@@ -1,7 +1,7 @@
 /**
  * SQL transparency. An agent that can read the SQL a query generates can fix a
  * slow or wrong read by itself; a query builder that hides its output forces it
- * to guess. `explain` is the read path for `/_x` and for `x db explain`.
+ * to guess. `explainQuery` is the read path for `/_x` and for `x db explain`.
  */
 import type { Ctx } from '@ultimat3/core';
 import type { StandardSchemaV1 } from '@ultimat3/schema';
@@ -18,10 +18,10 @@ export interface ExplainResult extends SqlText {
 }
 
 /**
- * Policy is deliberately NOT enforced here: `explain` never returns rows, and the
+ * Policy is deliberately NOT enforced here: `explainQuery` never returns rows, and the
  * surfaces that expose it (`/_x`, the CLI) are admin-gated in their own right.
  */
-export async function explain<TInput extends StandardSchemaV1, TRow extends object>(
+export async function explainQuery<TInput extends StandardSchemaV1, TRow extends object>(
   target: Query<TInput, TRow, boolean>,
   input: unknown,
   ctx?: Ctx,

package/src/stable.ts

@@ -11,9 +11,6 @@
 
 import { isJsonObject } from '@ultimat3/core';
 
-/** Re-exported, not re-declared: `./stable` stays this package's one import path for it. */
-export { isJsonObject };
-
 /** Column read that works for interfaces without an index signature. */
 export function columnOf(row: object, column: string): unknown {
   const record: unknown = row;

package/src/subscribes.ts

@@ -1,8 +1,8 @@
 /**
  * The relations a live read is patched from: the one thing about a query that cannot be derived,
- * and the two assertions that keep the declaration honest. `x db gen` grants those relations
- * `REPLICA IDENTITY FULL`, so a name that has gone stale is worse than none — it grants it to the
- * wrong table and leaves the right one unable to produce a patch, in silence (#357).
+ * and the two assertions that keep the declaration honest — a stale name is a declaration its
+ * author reads as true. Since #518 `x db gen` grants these relations no `REPLICA IDENTITY FULL`:
+ * every entity is keyed, and a keyed table is correct on DEFAULT (`x db gen` validates the names).
  */
 
 import { QuerySubscribesDriftError, QuerySubscribesInvalidError } from './errors';

package/src/type-pins.ts

@@ -0,0 +1,62 @@
+// Compile-time pins for this package's public surface. Source, not a `.test.ts`, on purpose:
+// `tsconfig.json` excludes `src/**/*.test.ts`, so `tsc -b` never reads a test file and a
+// type-level claim written in one can never fail. This module emits nothing and exports nothing
+// anybody imports — a regression here is a build error, the only enforcement that counts.
+
+import type { McpExposureDeclaration } from '@ultimat3/core';
+import type { StandardSchemaV1 } from '@ultimat3/schema';
+import type { AnyQuery, Query, QueryDef } from './query';
+
+/** Fails to compile when `T` is anything but `true`. The whole mechanism. */
+type Assert<T extends true> = T;
+
+type Equals<A, B> = [A] extends [B] ? ([B] extends [A] ? true : false) : false;
+
+/**
+ * IDENTICAL, not merely mutually assignable: an object type without an optional key is assignable
+ * to one with it and back, so `Equals` cannot see an optional field added on one side only — and
+ * every field of the `mcp` block is optional but `expose`.
+ */
+type Identical<A, B> =
+  (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false;
+
+/**
+ * O-tool, 25.0.0: a query projects no MCP tool of its own — `@ultimat3/mcp`'s `toolFrom` is
+ * the one projection, and a tier-3 `.tool()` could only ever be a second one. A `tool` member
+ * coming back on either view flips these to `false`.
+ */
+export type _AQueryHasNoToolTwin = Assert<Equals<Extract<keyof AnyQuery, 'tool'>, never>>;
+export type _ATypedQueryHasNoToolTwin = Assert<Equals<Extract<keyof Query, 'tool'>, never>>;
+
+/**
+ * 25.0.0 (plan 101, M5): the deprecation TYPES are `@ultimat3/core`'s alone, as the helpers are.
+ * A runtime test cannot see a type re-export, so each is an expected error: a re-export coming
+ * back makes the directive unused, which `tsc` refuses.
+ */
+// @ts-expect-error — `Deprecation` is imported from `@ultimat3/core`, never from this barrel.
+export type _NoDeprecationReexport = import('./index').Deprecation;
+// @ts-expect-error — `DeprecationField` is imported from `@ultimat3/core`.
+export type _NoDeprecationFieldReexport = import('./index').DeprecationField;
+// @ts-expect-error — `DeprecationRender` is imported from `@ultimat3/core`.
+export type _NoDeprecationRenderReexport = import('./index').DeprecationRender;
+
+/**
+ * 25.0.0: a query's `mcp` block is core's ONE `McpExposureDeclaration`, on the declaration and on
+ * both views. `QueryMcp`, `QueryMcpAnnotations` and `QueryListParams` restated it; a twin coming
+ * back on the barrel makes its directive unused, and a field drifting flips the pins to `false`.
+ */
+export type _QueryDeclaresCoresBlock = Assert<
+  Identical<NonNullable<QueryDef<StandardSchemaV1, object>['mcp']>, McpExposureDeclaration>
+>;
+export type _AnyQueryCarriesCoresBlock = Assert<
+  Identical<NonNullable<AnyQuery['mcp']>, McpExposureDeclaration>
+>;
+export type _TypedQueryCarriesCoresBlock = Assert<
+  Identical<NonNullable<Query['mcp']>, McpExposureDeclaration>
+>;
+// @ts-expect-error — `QueryMcp` is gone: the block is `@ultimat3/core`'s `McpExposureDeclaration`.
+export type _NoQueryMcpTwin = import('./index').QueryMcp;
+// @ts-expect-error — `QueryMcpAnnotations` is core's `McpAnnotationHints`.
+export type _NoQueryMcpAnnotationsTwin = import('./index').QueryMcpAnnotations;
+// @ts-expect-error — `QueryListParams` is core's `McpListParams`.
+export type _NoQueryListParamsTwin = import('./index').QueryListParams;

package/src/deprecation.ts

@@ -1,76 +0,0 @@
-/**
- * A declared retirement, rendered as the two headers the standards already define — RFC 9745
- * `Deprecation` and RFC 8594 `Sunset` — plus the successor link. Pure string and date maths, and
- * deliberately throw-free: each package raises its own `X_*` for a date it cannot render.
- *
- * `@ultimat3/action` carries the twin of this file. Both are tier 3, so neither may import the
- * other, and the shared home is `@ultimat3/http` (tier 2) once that package grows one — the same
- * compromise `naming.ts` is ported under.
- */
-import { counter } from '@ultimat3/core';
-
-export interface Deprecation {
-  /** When it was deprecated. ISO-8601, e.g. `'2026-08-01T00:00:00Z'`. */
-  readonly since: string;
-  /** When it stops answering. ISO-8601 — the date `Sunset` publishes and clients plan against. */
-  readonly sunset: string;
-  /** The export name of the replacement, projected to a `rel="successor-version"` link. */
-  readonly replacedBy?: string;
-}
-
-export type DeprecationField = 'since' | 'sunset';
-
-export type DeprecationRender =
-  | {
-      readonly ok: true;
-      readonly headers: Readonly<Record<string, string>>;
-      /** The same facts as data, for the descriptor and the manifest. */
-      readonly meta: Readonly<Record<string, string>>;
-    }
-  | { readonly ok: false; readonly field: DeprecationField; readonly value: string };
-
-/**
- * How many calls a deprecated declaration is still taking — the number "can we remove it yet?"
- * needs. Attributes are the primitive and the declared NAME, both bounded by the size of the
- * codebase; a caller id here would be an unbounded series.
- */
-const deprecatedCalls = counter('deprecated_calls_total', {
-  unit: '{call}',
-  description: 'Calls served by a declaration that has been deprecated, by primitive and name',
-});
-
-export function recordDeprecatedCall(primitive: 'action' | 'query', name: string): void {
-  deprecatedCalls.add(1, { primitive, name });
-}
-
-/**
- * `Deprecation` is a structured-field Date (`@` + unix seconds, RFC 9745); `Sunset` is an
- * HTTP-date (IMF-fixdate, RFC 8594). Two spellings of one instant because two RFCs chose
- * differently — never render one in the other's format, and never emit `Invalid Date`.
- */
-export function renderDeprecation(
-  deprecation: Deprecation,
-  successorPath: string | undefined,
-): DeprecationRender {
-  const since = Date.parse(deprecation.since);
-  if (Number.isNaN(since)) return { ok: false, field: 'since', value: deprecation.since };
-  const sunset = Date.parse(deprecation.sunset);
-  if (Number.isNaN(sunset)) return { ok: false, field: 'sunset', value: deprecation.sunset };
-
-  const headers: Record<string, string> = {
-    deprecation: `@${Math.floor(since / 1000)}`,
-    sunset: new Date(sunset).toUTCString(),
-  };
-  // The successor's URL, derived by the caller from the same `naming.ts` the client uses — a
-  // link this file built from the export name would be the second URL derivation in the package.
-  if (successorPath !== undefined) {
-    headers['link'] = `<${successorPath}>; rel="successor-version"`;
-  }
-
-  const meta: Record<string, string> = {
-    since: new Date(since).toISOString(),
-    sunset: new Date(sunset).toISOString(),
-    ...(deprecation.replacedBy === undefined ? {} : { replacedBy: deprecation.replacedBy }),
-  };
-  return { ok: true, headers, meta };
-}

package/src/mcp-tool.ts

@@ -1,81 +0,0 @@
-/**
- * A query as an MCP read tool. Its `read` goes through `sourceFor` — the same
- * authorized front half the HTTP read and the live subscription use — so the tool
- * cannot drift from the endpoint and cannot acquire a second authz path.
- */
-
-import type { Actor, Ctx } from '@ultimat3/core';
-import { isMcpExposed } from '@ultimat3/core';
-import type { JsonSchema } from '@ultimat3/schema';
-import { toMcpInputSchema } from '@ultimat3/schema';
-import type { QueryPolicy } from './policy-gate';
-import type { AnyQuery } from './query';
-import { queryName, sourceFor } from './read';
-import { listQueries } from './registry';
-
-export interface QueryToolReadOptions {
-  readonly ctx?: Ctx;
-  /** The agent behind the call. `null` is the signed-out caller. */
-  readonly actor?: Actor | null;
-}
-
-export interface QueryToolDescriptor {
-  /**
-   * The export name VERBATIM, and identical to `query` below. `@ultimat3/mcp` serves a read
-   * under `queryName(target)` and answers `tools/call` for nothing else, so a snake_cased
-   * descriptor named a tool the server had never heard of — which it did until 2026-08.
-   */
-  readonly name: string;
-  /** The query's `mcp.description`, or its name when the author gave none. */
-  readonly description: string;
-  readonly query: string;
-  /**
-   * The query's own policy object, not a copy — `tool().policy === query.policy`
-   * is what makes "an MCP call cannot reach a different authz path" checkable.
-   */
-  readonly policy: QueryPolicy;
-  readonly inputSchema: JsonSchema;
-  /** Always false: a query reads. Drives the rate-limit bucket in @ultimat3/mcp. */
-  readonly mutates: false;
-  read(input: unknown, options?: QueryToolReadOptions): Promise<readonly object[]>;
-}
-
-export function toQueryTool(target: AnyQuery): QueryToolDescriptor {
-  const name = queryName(target);
-  return {
-    name,
-    description: target.mcp?.description ?? name,
-    query: name,
-    policy: target.policy,
-    inputSchema: toMcpInputSchema(target.input),
-    mutates: false,
-    read: async (input, options = {}) => {
-      // Executed without the cache tiers on purpose: an agent diffing two tool
-      // calls must be reading the rows, not a TTL.
-      const source = await sourceFor(target, input, {
-        ...(options.ctx === undefined ? {} : { ctx: options.ctx }),
-        ...(options.actor === undefined ? {} : { actor: options.actor }),
-      });
-      return source.execute();
-    },
-  };
-}
-
-/**
- * Opt-in: a read hands rows to an agent, so silence exposes nothing. `mcp: { expose: true }` is
- * the whole opt-in — `isMcpExposed` from `@ultimat3/core` is the framework's one answer, and an
- * action's tool is now decided by the same call rather than by a second, looser rule.
- */
-export function isExposed(target: AnyQuery): boolean {
-  return isMcpExposed(target.mcp);
-}
-
-/** Deterministic order — the tool list is part of the agent-visible contract. */
-export function toQueryTools(
-  queries: readonly AnyQuery[] = listQueries(),
-): readonly QueryToolDescriptor[] {
-  return queries
-    .filter(isExposed)
-    .map(toQueryTool)
-    .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
-}

package/src/naming.ts

@@ -1,22 +0,0 @@
-/**
- * The naming rule for reads, as this package has always exported it: a query's export name
- * derives its HTTP path. The rule itself is `@ultimat3/core`'s `client-paths.ts` — one tier-0 file
- * that `action`, `query` and `realtime` all read, so the path cannot be derived two ways. The MCP
- * tool name is NOT derived — it is the export name verbatim, so there is one name to call.
- */
-
-import { queryPath, splitWords } from '@ultimat3/core/page';
-
-export { splitWords };
-
-/** `liveFeed` -> `live-feed`. */
-export function toKebabCase(name: string): string {
-  return splitWords(name).join('-');
-}
-
-/**
- * `liveFeed` -> `/_x/query/live-feed`, read with `GET …?orgId=…`. A read is a GET under its own
- * prefix so a CDN, a browser cache and a log line can all tell it apart from an action's
- * `POST /api/...` without parsing a body.
- */
-export const derivePath: (name: string) => string = queryPath;