@ultimat3/query 22.14.0 → 23.0.0

package/CLAUDE.md

@@ -18,12 +18,14 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
 | `http.ts` | route projection (`GET /_x/query/<kebab>`, `enforcedBy: 'handler'`) |
 | `mcp-tool.ts` | MCP read descriptor, same `sourceFor` |
 | `client.ts` | typed read client (browser-safe); dispatches through `@ultimat3/core`'s `clientTransport`, never `fetch` |
+| `client-scale-pins.ts` | compile-time pin: `queryClient<Api['queries']>` over 100 reads in 50 modules — list, `.page` and `single: true` |
 | `record-answer.ts` | a read's HTTP answer: bare rows, or the record envelope when `rows:` is an entity's branded row schema |
 | — | flight control is **`@ultimat3/core`**'s `client-flight.ts` + `client-wire.ts`, re-exported. No local copy |
 | `naming.ts` | export name → `/_x/query/<kebab>` — `derivePath` IS core's `queryPath`. **Paths only** |
 | `registry.ts` | export-name registration, `describeQueries()`, the `registerPrimitiveRegistrar('query', …)` announcement |
 | `live.ts` | `LiveQuery` descriptor + cursor arithmetic |
 | `subscribes.ts` | the relations a live read declares, and the two assertions that keep them true |
+| `sealed-shape.ts` | a live read keyed on a `.sealed()` column is refused at subscribe (`X_MATCHER_UNSUPPORTED`) |
 | `matcher.ts` | change event → minimal patch, `refill` when the window cannot place the row, or `X_MATCHER_UNSUPPORTED` |
 | `pagination.ts` | `paginate()` over core's cursor codec — no offset, ever |
 | `cursor-value.ts` | what a sort value becomes inside a cursor, and back |
@@ -61,6 +63,9 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
   barrel exports nothing matching `/tool_?name/i`.
 - **`queryClient` is the map-wide read client (mirror of `rpc`)**; both spellings run
   `queryClientMethodFor`. **`toQueryRoute` and `client()` derive the same URL from `naming.ts`.**
+- **`QueryClient` typechecks at any app size, and a `.test.ts` cannot say so** (`tsconfig.json`
+  excludes them): `client-scale-pins.ts` is source, so a regression is a `typecheck` error. The map
+  it pins is the intersection `@ultimat3/action`'s `Merge` hands over; that package pins `Merge`.
 - **The route coerces (`coerceQuery`), `runQuery` validates.** No `request.query(schema)` and no
   `meta.input` on the route.
 - **`rateLimit:` is declarable; `toQueryRoute` sets both `meta.rateLimit` and
@@ -84,6 +89,15 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
 - Authz goes through `enforce(surface, policy, { input, actor, ctx })`; a live denial keeps its 4403
   close code on `QueryDeniedError.denial`. Policy runs per subscriber for live queries — never cache a
   decision across actors.
+- **This package strips NO column, and must not start.** A query has no output parse; a
+  `.sealed()` column is absent from every projection because `@ultimat3/entity`'s repository row
+  does not ENUMERATE it (`serverOnly`, `packages/entity/src/sealed.ts`). So nothing on the read
+  path may rebuild a row property by property from a column list or `Object.getOwnPropertyNames`
+  — `JSON.stringify`, a spread and `Object.keys` are the only walks. `sealed-egress.test.ts` pins
+  HTTP (list, `Page`, single, envelope), MCP, live, the cache tier and a derived row.
+- **A live read keyed on a sealed column is refused at subscribe** (`assertNoSealedKey`, called by
+  `toLiveQuery`): a change row carries none, so the window would be read once and never patched.
+  The refusal names the column, never the filter's value.
 
 ## Invariants — the client
 
@@ -102,7 +116,7 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
   import core from `@ultimat3/core/page`, the page keys live in the leaf `page-keys.ts`, and
   `client.ts` never imports `page-controls.ts` or `stable.ts`. `client-bundle.test.ts` fails on any
   titles table in the graph or past 11 kB; `client-subpath.test.ts` pins the specifier. Byte figures
-  (`As of 2026-09-22`, browser, minified): barrel `queryClient` 24,114 B; `./client` 10,210 B.
+  (`As of 2026-10-01`, browser, minified): barrel `queryClient` 23,997 B; `./client` 10,899 B.
 - **The record envelope is derived from `rows:`** — `answersRecords(rows)` (`hasEntityRows`,
   `@ultimat3/entity`), decided once at projection for `http.ts` and `openapi.ts`, sent on every
   answer. No `rows:` is byte-identical on the wire.

package/README.md

@@ -53,6 +53,9 @@ const [post] = await queries.publicPost({ slug }); // typed input, typed rows
 
 Both spellings run `queryClientMethodFor`, so a read has one URL however it is addressed.
 
+`queryClient<Api['queries']>` typechecks at any app size: `client-scale-pins.ts` compiles it over
+100 reads in 50 modules — a list read, its `.page` and a `single: true` read — on every `typecheck`.
+
 Every read goes through `@ultimat3/core`'s **`clientTransport`** — the one browser HTTP function,
 `As of 2026-09-22` (21.0.0). There is no `fetch` call in this package: the `fetch` option is handed
 on as the transport's `fetchImpl`. The transport owns `Accept`, the trace/budget headers, the
@@ -205,6 +208,7 @@ forgetting the policy, and the reason is what tells the next reader which of the
 | `sql.ts` | `explain()` — the generated SQL, verbatim |
 | `cache.ts` | request memo + tag-keyed tier, one invalidation graph |
 | `source.ts` | the `SqlSource` contract + `from()`, the in-memory reference |
+| `sealed-shape.ts` | a live read may not filter or order on a `.sealed()` column — refused at subscribe |
 
 ## Live queries
 
@@ -262,6 +266,22 @@ cursor cannot prove that rows sorting *before* it are unchanged, so any epoch ch
 new build, new policy, new schema — forces a full refetch instead of a resume. Bounded
 server memory bought with an occasional extra page fetch.
 
+## A sealed column never rides on a row
+
+A query has no output schema; nothing here strips a column. A `.sealed()` column is absent from
+every projection because `@ultimat3/entity` answers it as a server-only (non-enumerable) property —
+`row.password` on the server, nothing in `JSON.stringify(row)`.
+
+| Projection | Sealed column |
+|---|---|
+| HTTP — list, `Page`, `single: true`, the record envelope | absent |
+| MCP read, a `cache:` entry, a live snapshot | absent |
+| a derived row `({ ...row, extra })` | absent |
+| a derived row naming it `({ token: row.token })` | sent — the name is the statement |
+| `query(input)` on the server | `row.password` reads the plaintext |
+
+`sealed-egress.test.ts` holds one assertion per projection.
+
 ## Matcher support
 
 | Shape | Result |
@@ -270,6 +290,7 @@ server memory bought with an occasional extra page fetch.
 | `orderBy` (any number of keys) | insert position computed, moves become remove + add |
 | `limit` | tail eviction on insert, `refill` patch on removal |
 | joins, aggregates, `group by`, subqueries | `X_MATCHER_UNSUPPORTED` with a fix line |
+| a `.sealed()` column in a filter or an order | `X_MATCHER_UNSUPPORTED` — a change row carries no sealed column |
 
 An honest refusal beats a silently wrong result set, so unsupported shapes fail at
 **subscribe** time, not on the first change event.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/query",
-  "version": "22.14.0",
+  "version": "23.0.0",
   "description": "The query primitive: a policy-checked read, optionally live, with cursor pagination and an incremental matcher",
   "license": "MIT",
   "type": "module",
@@ -24,6 +24,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "!src/**/*-fixture.ts",
     "CLAUDE.md",
     "README.md",
     "LICENSE"
@@ -36,11 +37,11 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "22.14.0",
-    "@ultimat3/core": "22.14.0",
-    "@ultimat3/entity": "22.14.0",
-    "@ultimat3/http": "22.14.0",
-    "@ultimat3/policy": "22.14.0",
-    "@ultimat3/schema": "22.14.0"
+    "@ultimat3/cache": "23.0.0",
+    "@ultimat3/core": "23.0.0",
+    "@ultimat3/entity": "23.0.0",
+    "@ultimat3/http": "23.0.0",
+    "@ultimat3/policy": "23.0.0",
+    "@ultimat3/schema": "23.0.0"
   }
 }

package/src/client-scale-pins.ts

@@ -0,0 +1,78 @@
+// Compile-time pin: `queryClient<Api['queries']>` at 100 reads in 50 modules. Source, not a
+// `.test.ts` — `tsconfig.json` excludes those, so `tsc -b` would never read the claim. Types only:
+// nothing here is emitted, and a regression is a build error in the `typecheck` step.
+//
+// `QueryClient` is its own mapped type and regresses on its own. `defineApi` is `@ultimat3/action`'s
+// (sideways), so the map is spelled the way its `Merge` hands it over: one intersection of every
+// module's registered reads. `@ultimat3/action`'s `client-scale-pins.ts` holds the `Merge` half.
+
+import type { NumberSchema, ObjectSchema, StringSchema } from '@ultimat3/schema';
+import type { queryClient } from './client';
+import type { Page } from './pagination';
+import type { Query } from './query';
+
+type Assert<T extends true> = T;
+
+type Equals<A, B> = [A] extends [B] ? ([B] extends [A] ? true : false) : false;
+
+/** Distinct per module, so no two modules collapse into one instantiation. */
+type ScaleInput<N extends number> = ObjectSchema<
+  { readonly orgId: StringSchema; readonly limit: NumberSchema } & {
+    readonly [K in `q${N}`]: StringSchema;
+  }
+>;
+
+type ScaleRow<N extends number> = { readonly id: string } & { readonly [K in `col${N}`]: number };
+
+/** One feature's reads: a list and a `single: true`, the two methods `QueryClient` projects. */
+type QueryModule<N extends number> = {
+  readonly [K in `listRows${N}`]: Query<ScaleInput<N>, ScaleRow<N>>;
+} & { readonly [K in `oneRow${N}`]: Query<ScaleInput<N>, ScaleRow<N>, true> };
+
+/** `Module<0> & … & Module<TCount - 1>`. A tail call, so the count costs no depth here. */
+type MergedQueries<
+  TCount extends number,
+  TSeen extends readonly unknown[] = [],
+  TMap = unknown,
+> = TSeen['length'] extends TCount
+  ? TMap
+  : MergedQueries<TCount, [...TSeen, unknown], TMap & QueryModule<TSeen['length']>>;
+
+type ScaleQueries = MergedQueries<50>;
+
+/** The idiom itself, through `queryClient`'s own `QueryMap` constraint. */
+type ScaleClient = ReturnType<typeof queryClient<ScaleQueries>>;
+
+export type _EveryModuleReachesTheClient = Assert<
+  'listRows0' | 'oneRow24' | 'listRows49' extends keyof ScaleClient ? true : false
+>;
+
+export type _TheClientHasExactlyTheMergedReads = Assert<
+  Equals<keyof ScaleClient, keyof ScaleQueries>
+>;
+
+type LastInput = { readonly orgId: string; readonly limit: number; readonly q49: string };
+
+/** One call of each shape, read off the LAST module's own declaration. */
+export type _AListReadAnswersRows = Assert<
+  Equals<
+    [Parameters<ScaleClient['listRows49']>[0], Awaited<ReturnType<ScaleClient['listRows49']>>],
+    [LastInput, readonly ScaleRow<49>[]]
+  >
+>;
+
+export type _AListReadPages = Assert<
+  Equals<Awaited<ReturnType<ScaleClient['listRows49']['page']>>, Page<ScaleRow<49>>>
+>;
+
+export type _ASingleReadAnswersTheRow = Assert<
+  Equals<
+    [Parameters<ScaleClient['oneRow49']>[0], Awaited<ReturnType<ScaleClient['oneRow49']>>],
+    [LastInput, ScaleRow<49>]
+  >
+>;
+
+/** A single read has no `page` — the route refuses the controls, so the method would be a 400. */
+export type _ASingleReadHasNoPage = Assert<
+  'page' extends keyof ScaleClient['oneRow49'] ? false : true
+>;

package/src/live.ts

@@ -16,6 +16,7 @@ import { guard } from './policy-gate';
 import type { Query } from './query';
 import { queryHash } from './query';
 import { queryName, sourceFor } from './read';
+import { assertNoSealedKey } from './sealed-shape';
 import type { QueryShape, SeekKey } from './shape';
 import { seekKeyOf } from './shape';
 import { assertSubscribed } from './subscribes';
@@ -128,6 +129,8 @@ export async function toLiveQuery<TInput extends StandardSchemaV1, TRow extends
   // outgrown means `x db gen` granted REPLICA IDENTITY FULL somewhere else, so every UPDATE on this
   // relation arrives without its old row and no patch is computable from it.
   assertSubscribed(name, target.subscribes, shape.entity);
+  // And once more for the same moment: a window keyed on a sealed column is read and never patched.
+  assertNoSealedKey(name, shape);
 
   const epoch = options.epoch ?? liveEpoch();
   const hash = queryHash(name, input);

package/src/sealed-shape.ts

@@ -0,0 +1,27 @@
+/**
+ * A live read may not FILTER or ORDER on a sealed column, refused at subscribe. The matcher places
+ * a change from the row the change feed carries, and that row names no sealed column — the log
+ * holds the stored string, which `@ultimat3/realtime` drops rather than forwards. So a window keyed
+ * on one could be read once and never patched: every later change would miss the filter or land
+ * at no position, silently.
+ */
+
+import { entityForTable, sealedFields } from '@ultimat3/entity';
+import { MatcherUnsupportedError } from './errors';
+import type { QueryShape } from './shape';
+
+export function assertNoSealedKey(name: string, shape: QueryShape): void {
+  // A relation no entity declares has no sealed column to name: `from('report', rows)` over a
+  // projection is common, and it is not this rule's to refuse.
+  const entity = entityForTable(shape.entity);
+  if (entity === undefined) return;
+  const sealed = new Set(sealedFields(entity).map((field) => field.property));
+  if (sealed.size === 0) return;
+  const keyed = [...shape.filters, ...shape.orderBy].find((key) => sealed.has(key.column));
+  if (keyed === undefined) return;
+  // The column's NAME, never the filter's value: that value is the secret being matched on.
+  throw new MatcherUnsupportedError(
+    name,
+    `the sealed column "${keyed.column}" in a filter or an order — a change row carries no sealed column`,
+  );
+}