@ultimat3/query 1.1.0 → 2.0.0

package/CLAUDE.md

@@ -0,0 +1,393 @@
+# @ultimat3/query
+
+Owns the `query` primitive: reads, live reads, cursors, the incremental matcher. Tier 3.
+
+## Boundary
+
+- May import: `core`, `schema` (t0), `cache`, `i18n`, `time` (t1), `entity`, `policy`, `http` (t2).
+- Never import: `action`, `jobs`, `realtime` (sideways), or any tier 4-5 package.
+- Reads only. A query that writes is an `action` in the wrong file.
+
+## Files
+
+| File | Job |
+|---|---|
+| `query.ts` | the primitive: `query()`, `describeQuery`, `queryHash`; the package's front door for the read path |
+| `read.ts` | **the one read path** (`runQuery`, `sourceFor`) + the private declaration store `sql` lives in |
+| `facade.ts` | the fluent surface — binds each projection to the query, re-implements none |
+| `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: no server imports) |
+| `naming.ts` | export name → `/_x/query/<kebab>`. Pure string math. **Paths only** — no tool name |
+| `registry.ts` | export-name registration, `describeQueries()`, and the `registerPrimitiveRegistrar('query', …)` announcement |
+| `live.ts` | `LiveQuery` descriptor + cursor arithmetic |
+| `matcher.ts` | change event → minimal patch, 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 what it becomes again |
+| `input-shape.ts` | what a read's `input:` may be, given that its route is a query STRING |
+| `sql.ts` | `explain()` / `describeSql()` |
+| `cache.ts` | the read path: the request memo, and the fill through `@ultimat3/cache`'s registered tiers |
+| `source.ts` | `SqlSource` contract + `from()` in-memory reference |
+| `shape.ts` | shared read vocabulary (filters, ordering, seek keys) |
+| `policy-gate.ts` | **the only** file that touches `@ultimat3/policy` |
+| `deprecation.ts` | `Deprecation` + the RFC 9745/8594 render + the `deprecated_calls_total` counter — TWINNED with `@ultimat3/action`'s |
+
+## Invariants
+
+- Every surface goes through `sourceFor`: parse input, evaluate policy, build the source.
+  Adding a second read path is the one unforgivable change here.
+- **An explicit `ctx` is INSTALLED, never merely passed** (`As of 2026-08`). `asActor` used to hand
+  `options.ctx` to `run(ctx)` and enter no `runWithContext` unless an `actor` was also given, so
+  `guard()` decided about that actor while everything reading the AMBIENT context — above all
+  `@ultimat3/entity`'s tenant guard, which derives from `tryUseContext()` and not from the ctx it is
+  handed — saw a different identity, or none. A read was authorised as one caller and scoped to
+  nobody. Absent a `ctx` it reinstalls the ambient one, which is a no-op on every path that already
+  worked. The twin fix is `@ultimat3/action`'s `invoke`, and `read-context.test.ts` is written as an
+  equality between the three spellings of one caller — ambient, `options.actor`, `options.ctx` —
+  because three independent expectations are exactly what let this ship.
+- **Skipping a read's policy costs a WRITTEN REASON, never a boolean** (`As of 2026-08`).
+  `SourceOptions.enforce?: boolean` is gone; it is `unenforced?: string`, and a blank one is
+  refused before the source is built. The bar is `@ultimat3/entity`'s `cross-tenant.ts`: a boolean
+  argument "reads exactly like forgetting the tenant", and a forgotten policy reads the same way —
+  so the reason IS the mechanism and every skipped policy is one `grep` away with its justification
+  attached. It is deliberately NOT capability-gated the way `crossTenant` is: `explain` runs from
+  the CLI with no actor to check a scope against, and gating it would close the one surface it
+  exists for. **`ToLiveOptions.enforce` stays a boolean**, because it is that one use with exactly
+  one reason — `toLiveQuery` translates it into the reason string spelled once as
+  `SHARED_WINDOW_REASON`, so a sync node and this file cannot disagree about why the shared window
+  has no subject. Two shipped callers, both reading no rows for a subscriber: `sql.ts` and that
+  window.
+- The declaration never leaves `read.ts`. `defOf`/`stashDef`/`hasDef` are internal and must
+  never be re-exported from `src/index.ts` — that omission is the enforcement.
+- A query has no `.def`. Inside the package read it with `defOf(target)`; outside, read the
+  lifted `.input`/`.policy`/`.cache`/`.mcp`/`.isLive` or `describe()`.
+- App code reaches a projection through the query (`liveFeed.tool()`), never through `.def`
+  and never by importing the projection function. `facade.ts` is where a new method is bound;
+  the projection itself keeps living in its own file.
+- `src/index.ts` re-exports `t` from `@ultimat3/schema` **verbatim**, so a query file imports
+  one package. Never wrap, spread or re-declare it: `t` delegates to `schemaProvider()` on every
+  access, and a copy would freeze the provider at import time. `index.test.ts` asserts identity.
+- **`LiveQuery` describes the read *and* runs it.** `execute()` is the source the shape, the reads
+  and `sqlText` were taken from — one build of one `(query, input)`. A caller that wanted rows and
+  called `sourceFor` itself was a second build: twice the parse, twice the `sql()`, and a matcher
+  describing a source the rows never came from. `@ultimat3/realtime`'s shared window is the one
+  consumer, and it reads through `execute()`. It never memoises — a subscriber joining an existing
+  subscription must see the rows as they are now, not the window someone else opened.
+- `isLive` is the declared boolean, `live()` is the subscription. Never name one after the other.
+  `QueryDescriptor.live` keeps its name — `@ultimat3/manifest` and `@ultimat3/admin` read it.
+- `mcp` is opt-in (`expose: true`), exactly as it is for an action: rows reach an agent only when
+  the author said so. `isExposed` here delegates to `isMcpExposed` in `@ultimat3/core` — the one
+  predicate every reader in the framework asks — rather than spelling `=== true` a second time.
+- **A read has ONE tool name, and it is the export name verbatim** (`As of 2026-08`). `toQueryTool`
+  snake_cased it (`liveFeed` → `live_feed`) while `@ultimat3/mcp` serves the read under
+  `queryName(target)` and answers `tools/call` for nothing else — so anything that read the name off
+  the descriptor rather than off `tools/list` called a tool the server had never heard of, and the
+  scope map in `defineAppMcp` is keyed on the verbatim name too. `toToolName` is **deleted**, not
+  merely unused: an exported derivation is a second way to spell one tool. Two pins, both in this
+  package because this is where the rule can be broken — `mcp-tool.test.ts` asserts
+  `toQueryTool(q).name === queryName(q)` (the presence), and `index.test.ts` asserts the barrel
+  exports no key matching `/tool_?name/i` (the absence, which nothing else catches: the only other
+  guard is `packages/mcp/src/cross-surface.test.ts`, tier 4 and unimportable from here).
+  `naming.ts` derives PATHS only.
+- `client.ts` stays free of server imports — it is bundled into the browser. `@ultimat3/action`
+  is the same tier, so its naming is ported here, never imported.
+- **`queryClient` is the map-wide read client and the mirror of `rpc`; both spellings run
+  `queryClientMethodFor`.** `queryClient<Api['queries']>({ baseUrl })` is how a surface that must
+  not import a feature reaches every registered read — `site/` in an app, whose one edge into
+  `app/` is a boundary violation, so `.client()` (which needs the query object) is unreachable
+  there. The map-wide client re-deriving a path from the property name would be the second URL
+  derivation this package spent a release removing; it proxies to the per-query method instead.
+- **`toQueryRoute` is the other half of `client()`, and the two derive the same URL from the same
+  `naming.ts`.** The client shipped fetching `/_x/query/<kebab>` while nothing built a route for
+  it, so every typed read compiled and 404'd; a projection whose only consumer is a URL string is
+  the failure this pairing exists to prevent. Named for the primitive rather than `toRoute`,
+  because a host mounts it beside `@ultimat3/action`'s — the same reason the tool projection here
+  is `toQueryTool`.
+- **The route coerces, `runQuery` validates, and only the first belongs to the wire.** A search
+  string is characters, so the boundary decodes it with `@ultimat3/schema`'s `coerceQuery` — the
+  one HTTP-boundary decoder, which never invents data and hands on what it cannot convert.
+  Validating there as well (`request.query(schema)`) would be the second parser: the same read
+  would answer `X_BODY_INVALID` where every other surface answers `X_INPUT_INVALID` and prints
+  its schema. For the same reason `meta.input` stays **absent** — the pipeline's body stage
+  validates it against a body, and a GET has none, so declaring it fails every read on nothing.
+- **`rateLimit:` is declarable on a read, and `toQueryRoute` sets the NAME and the NUMBERS.**
+  `QueryDef` had neither until 2026-08, so every `GET /_x/query/*` fell through `bucketFor` to
+  `default` — 120 burst, 2/s per actor — and one authenticated caller could hold 120 cross-tenant
+  aggregates in flight and then 2/s indefinitely, from a single account, with no declaration able
+  to say otherwise. The conversion is `toBucket` from **`@ultimat3/http`**, never a copy here:
+  http owns `Bucket` and the maths, `@ultimat3/action` is the same tier as this package, and a
+  copy in either is a second answer for the other. The field is lifted onto the facade so
+  `toQueryRoute` reads it without `defOf`, exactly as `cache` and `mcp` are.
+- **`deprecated:` is a compat WINDOW; versioning is two deployments behind one ingress.** Headers
+  are rendered ONCE at projection, so an unparseable date is `X_QUERY_DEPRECATION_INVALID` at
+  mount and not on the first read. `deprecation.ts` is a TWIN of `@ultimat3/action`'s — both are
+  tier 3, so neither may import the other, and the shared home is `@ultimat3/http` if it grows
+  one. The same compromise `naming.ts` is ported under; keep the two files identical in behaviour.
+- **The span wraps the whole read, not `source.execute()`.** Parse, policy and `sql()`'s own
+  construction were outside every span, so a read whose cost was in building the source reported
+  milliseconds under a parent that reported seconds — a gap with no name. `readRows` holds the
+  span and `readRowsIn` is the body; attributes are bounded (surface, actor KIND, `live`,
+  `cached`, `fresh`) plus the row count, and never the input or an actor id — a read is keyed per
+  tenant and per cursor, so either would be unbounded. `telemetry.test.ts` asserts the extent
+  structurally through `currentSpan()`, because the test clock is frozen. `sourceFor` still has no
+  span of its own: adding one would double-span every read that goes through `readRows`.
+- **`policyCapability` is a display label and `policyPermissions` is what a report matches on.**
+  A composite renders as `or(feed:read, org:administer)`, which equals no permission string, so
+  `x policy list` matching on `capability` reported every non-trivially-guarded read's permissions
+  as unenforced. `QueryDescriptor.permissions` is the flattened list, published beside
+  `capability` and never instead of it.
+- **`client.ts` injects `traceparent`**, before the caller's own headers so an explicit one wins,
+  and sends nothing when the span context is incomplete — `00-<trace>--01` is a header every
+  collector drops. The twin of `@ultimat3/action`'s, ported for the same tier reason.
+- **A read is `no-store`, and its policy is `enforcedBy: 'handler'`.** The URL names no actor
+  while the answer is scoped to one, so `public` would hand one reader's rows to the next caller
+  of that URL; and `runQuery` is the read's one evaluation, deciding from the parsed input, so an
+  authz stage deciding first would be a second authz system holding raw strings — and would
+  demand an `authorize` hook to decide at all. `http.test.ts` drives both over the real pipeline
+  with no hook wired and counts the evaluations: exactly one.
+- `registry.ts` announces `registerQueries` in core's registrar table at import. That is how
+  `defineApi({ queries })` in `@ultimat3/action` registers a read without importing this package
+  sideways. Never remove the announcement: `defineApi` would then throw `X_REGISTRAR_MISSING`.
+- Policy runs per subscriber for live queries. Never cache a decision across actors.
+- The matcher patches from `QueryShape`, never from SQL text.
+- `paginate` has no `offset` parameter and must never grow one, and it is reachable **only** as
+  `query.page(input, { first, after })` — a page is the read's own answer, not an imported helper.
+  `src/index.ts` exports `Page` and `PaginateArgs` and not the function: re-exporting it would be
+  a second way to ask for the thing `.page()` already does.
+- **A cursor is a position, not a row.** `isAfterKey` in `source.ts` is the one definition of
+  "after this position": `Builder.seek()` compiles it to SQL and `paginate()` applies it when a
+  source cannot push the seek down. The fallback used to find the cursor's row by id and slice
+  after it — which restarts the listing from the top the moment that row is deleted, the exact
+  failure keyset pagination exists to prevent. Never reintroduce a row lookup here.
+- The seek predicate is spelled out per key (`(a < $1) or (a = $2 and id > $3)`), the way
+  `@ultimat3/entity`'s `seekSql` spells it. A row-value comparison cannot express a mixed
+  `createdAt desc, id asc` ordering, and the id-tiebreak-only fallback it replaced returned rows
+  the ordering was already past — with `execute()` disagreeing with the SQL it printed.
+- **NULL has one meaning, and `isNull` is it.** `null` and a column the row omits are the same
+  absence, in the SQL and in memory alike. `=`/`!=`/`in` read NULL as a **value** — `is null`,
+  `is not null`, `is distinct from`, `in (…) or is null`, the pair `@ultimat3/entity`'s
+  `predicateSql` emits; `>`/`>=`/`<`/`<=` read it as **unknown**, matching nothing on either side,
+  which is why they need no special emission; `order by` reads it as the **largest value**, spelled
+  `asc nulls last` / `desc nulls first` rather than inherited from the driver. `= $n` with a NULL
+  argument is never true in Postgres, so `where({ deletedAt: null })` matched every row in memory
+  and none in the database, and `"col" > $n` blanked page two at the first NULL. Never emit a bound
+  parameter where NULL is the value being tested, and never let `compareValues` sort a NULL as the
+  string `"null"` again — `compareRows`, `isAfterKey` and the matcher's insertion position all
+  read it, so one string compare moves rows on three surfaces. `in` takes a list or nothing: an
+  empty one is `1 = 0`, and so is an operand that is not an array at all — `matchesFilter` answers
+  no rows for it, and `"col" in $n` is a syntax error the driver reports instead of that answer.
+- **The id is the tiebreak that makes the order total.** A row without one is
+  `X_QUERY_NOT_PAGEABLE` at `seekKeyOf` **and** at the matcher's `idOf`, never `String(undefined)`:
+  `"undefined"` is a position every row matches, signed and opaque, so page two would be page one
+  forever and one row's patch would land on another's index.
+- **`totalOrder` is the order a read is served in, and all three readers use it.** The declared
+  keys then `id asc`, unless the ordering already names `id` — `Builder.servedOrder()` compiles it,
+  the in-memory sort applies it, and `positionFor` places a row by it. The matcher comparing
+  `shape.orderBy` alone appended a tied row after its whole tie group, which is a position no
+  re-read returns and a cursor that skips every tie it was pushed past. `SeekKey` is the same list
+  decomposed — `key` for the declared part, `id` for the tiebreak — so never add `id` to
+  `QueryShape.orderBy` to get it: `seekKeyOf` would then sign the id twice. An unordered query
+  appends, because SQL promises no position there to get wrong.
+- **A live read asks for that order explicitly, and `sourceFor` is where it asks.** `total()` is
+  the `SqlSource` method for "the same read, served in `totalOrder`" — no cursor, no window — and
+  `buildSource` calls it when `surface === 'live'`, for nothing else, and only when the source
+  implements it. A live window served by the declared keys alone puts a tied row wherever the
+  database returned it, while `positionFor` places the patch by id and the resume re-read seeks by
+  id: the client then renders an order no re-read answers. Never reach for `seek(null, limit)`
+  instead — a live query need not carry a limit, and inventing one is a window nobody asked for.
+- **A sort value carries its own TYPE through the cursor** (`cursor-value.ts`, `As of 2026-08`).
+  The codec is JSON, so `paginate()` putting raw column values in meant a `Date` went out and an
+  ISO STRING came back: `isAfterKey` compared `"1769904000000"` against `"2026-02-01T…"` through
+  `compareValues`' string branch and **page two came back empty** — and a `bigint` sort key was a
+  bare `TypeError` out of `JSON.stringify`, with no code and no fix. `@ultimat3/entity`'s
+  `cursor.ts` solves the same problem by reading the column's declared kind; a `query` has no
+  column kinds — `QueryShape.orderBy` is a name and a direction — so the value is TAGGED instead
+  (`{ $x: 'date' | 'bigint', v }`) and `reviveSortKey` is total without knowing which read minted
+  it. `undefined` encodes as `null`, because SQL has one absence and dropping the key would shift
+  every later one a position left. Anything JSON cannot carry and this cannot tag — an object, an
+  array, `NaN`, `±Infinity` — is `X_CURSOR_VALUE_UNSUPPORTED` where the cursor is MINTED, never
+  `X_CURSOR_INVALID`: the mistake is the read's own `orderBy` and no retry repairs it.
+- **`compareValues` orders numbers and bigints in ONE order, because Postgres does.** The numeric
+  fast path was `typeof === 'number'` on both sides, so an `int8` fell to
+  `String(left) < String(right)`: `compareValues(9n, 10n)` answered `1` and a sort came out
+  `["10", "100", "9"]`. `bigint` is the physical type of every `<p>_minor` column and
+  `@ultimat3/entity`'s `count-by.ts` lists it as groupable, so the in-memory source, the live
+  matcher and the seek fallback ALL disagreed with the database on any bigint-ordered read.
+  `shape-order.test.ts` is the pin: one case per `ColumnKind`, each asserting the order Postgres
+  returns, plus the NULL rule and the cursor round trip. The kind list is spelled out rather than
+  imported — `tsconfig.json` excludes `*.test.ts`, so a `satisfies Record<ColumnKind, …>` written
+  in a test is a type assertion `tsc` never reads; a runtime count is the enforceable half.
+- **A read's `input:` must survive a query STRING, and `query()` refuses one that cannot**
+  (`input-shape.ts`, `X_QUERY_INPUT_UNENCODABLE`, `As of 2026-08`). `client.ts` encoded a nested
+  member as `JSON.stringify(item)` and skipped a `null`, while `coerceQuery` has no inverse for
+  either — `case 'object'` hands the raw value back untouched — so the typed client type-checked
+  calls the server's own route then rejected, which is the exact failure `client.ts`'s header
+  claims to prevent. **The declaration is the fix, not the encoder**: teaching `coerceQuery` to
+  `JSON.parse` a string would make the ONE HTTP-boundary decoder invent structure for every
+  surface that shares it — forms and route params included — against that file's own rule that it
+  never invents data, and a `null` sentinel would be a reserved string colliding with the value
+  `"null"`. Refused: a structural member (`object`, `record`, `money`, or an array/union of one),
+  a REQUIRED nullable member, and a top-level input that is not an object. A schema
+  `tryIntrospect` cannot read is left alone, or `configureSchemaProvider` would be unusable.
+- **A move OUT of a full window is a `refill`, never an `add`** (`matcher.ts`). `insert()` places a
+  moved row among the `limit - 1` rows the client still holds, so its position can never reach
+  `shape.limit` and the `position >= shape.limit` bail is unreachable on that path — the row was
+  re-inserted INSIDE the window. Proven with `limit: 3`, window `[a:1, b:2, c:3]` and a server also
+  holding `d:4, e:5`: moving `a` to `99` rendered `[b, c, a:99]` where the true window is
+  `[b, c, d]`. Only the server can answer the tail, and whether the moved row is still in the
+  window is its answer too.
+- **A page is bounded whether or not the caller bounded it.** `paginate` asserts `first` is a whole
+  number of rows in `1…MAX_PAGE_SIZE` (10,000) before anything else — `args.first + 1` bound
+  whatever an action's input or a route parameter carried, so one request could ask for five
+  million rows. The constant is a TWIN of `@ultimat3/entity`'s, under the same tier compromise
+  `naming.ts` and `deprecation.ts` are ported under.
+- **`tagKeys` is `@ultimat3/cache`'s, not this package's — moved 2026-08.** `src/tags.ts` here and
+  `@ultimat3/action`'s were byte-identical, and both packages are tier 3, so neither can import the
+  other and a copy in either is a second answer for the other — the same move `toBucket` made into
+  `@ultimat3/http`. `tagKey` went with it: `serializeTag` under a second name, zero call sites.
+  `@ultimat3/render` exports a *different* function under the same name (declaration order kept);
+  never import that one here.
+- **A fingerprint is an identity, so two different inputs may not share one** (`stable.ts`).
+  `NaN`, `±Infinity` and JSON `null` all encoded as `'null'`, and `String(-0)` is `"0"` — so four
+  distinct inputs shared one read-cache entry and one cursor scope. They are bare tokens now
+  (`NaN`, `Infinity`, `-Infinity`, `-0`), which the `string` branch cannot spell because it always
+  quotes. Ordinary numbers are byte-identical, so no existing cursor scope moved.
+- The cursor codec is `@ultimat3/core`'s (`encodeCursor` / `decodeCursor` / `configureCursorSigning`).
+  This package supplies only the scope a cursor is bound to — `queryHash(name, input)` — and never
+  signs, encodes or parses one itself. An unverified or foreign cursor is `X_CURSOR_INVALID`, thrown
+  by core's `CursorInvalidError`, which `errors.ts` re-exports so the name stays on this surface.
+- **The request memo holds the read, not the rows.** `readOnce` publishes the in-flight promise
+  before its first await, so two reads of one key in one request are one execution and one tier
+  round trip whether the second follows the first or races it. A value-keyed map could not express
+  that, and could not tell a memoized `undefined` from a miss either. A rejection is evicted — a
+  failed read is not the request's answer, and the next read retries. `requestMemo(ctx)` is
+  therefore `Map<string, Promise<unknown>>`; never put a settled value in it.
+- **Every read is memoized; only a `cache:` read goes through the tier.** `readThrough` is
+  `readOnce` plus the fill through the ladder, and `readRows` picks between them on `def.cache`
+  alone. The memo is not what `cache:` buys — a list that renders one uncached lookup per row pays for
+  every row otherwise, which is the N+1 this collapses. Never gate `readOnce` on `def.cache`
+  again, and never let a second key function grow beside `cacheKeyFor`.
+- **A cache key carries the read's AUTHORITY, and `cache.scope` is what widens it** (`As of
+  2026-08`). `cacheKeyFor` held the name, the input and the tags — nothing about who asked — while
+  `sql(input, ctx)` is handed the context and `@ultimat3/entity` derives every tenant predicate
+  from `ctx.actor.orgId`. The tier is process-wide, so the first actor to ask filled the entry and
+  the next was served it: a query filtering on `ctx.actor.orgId` returned `org-a`'s row to an
+  `org-b` actor. `readAuthority(actor, scope)` is the ONE producer of the component and
+  `cacheKeyFor`'s fourth argument is **required and positional**, because an optional one is one a
+  call site forgets and a forgotten one is that read. `scope` defaults to `'actor'` and the default
+  is the mechanism: declaring nothing gets the narrowest key. `'tenant'` and `'global'` are written
+  statements about the rows — the `unenforced:` shape one field over — and `'tenant'` with no
+  `orgId` narrows to the actor rather than widening to everyone, because nothing here can prove two
+  org-less callers share a tenant. The authority is JSON, never a joined string, for the reason
+  `@ultimat3/entity`'s `scopeKey` gives: an actor id is app data and may carry the separator.
+- **`cache.ttlMs` is judged at `query()`, not on the first read.** Every `CacheTier` refuses a
+  lease that is not positive and finite (`assertTtl`), and the read tier's one catch absorbs
+  `X_CACHE_TOO_LARGE` only — so `ttlMs: Infinity` turned a typo into a permanently failing business
+  read whose cause named a cache key. `X_QUERY_CACHE_TTL_INVALID`, on the line that wrote it. It
+  restates `assertTtl`'s bar as a refusal and never as a second resolution.
+- **`fingerprint` is SHA-256/16, never a 32-bit hash** (`stable.ts`, `As of 2026-08`). It is a
+  SHARING key over client-chosen input — which read-cache entry two callers are served from, which
+  scope a cursor is bound to — so FNV-1a/32's 4×10⁹ values are a collision found offline in
+  seconds. Same primitive and width as `@ultimat3/realtime`'s `stableDigest`. `stableStringify` did
+  not move, so the only cost is one cold cache and every open cursor answering `X_CURSOR_INVALID`
+  with its own "request the first page again" fix.
+- **A fill is FENCED, and the fence is `@ultimat3/cache`'s** (`As of 2026-08`). `run()` answers with
+  rows it read in the past: a mutator committing in between busts a key not yet in the tier, so the
+  drop is a no-op reporting `errors: []`, and the fill then publishes the pre-write rows for the
+  full TTL — invisible to every reader until it expires. The sample happens inside
+  `createCacheStack.read`, immediately before `load()`, and is re-asked per rung before each write.
+  This package no longer samples one of its own — that copy went with the private store. The caller
+  is answered either way: those rows ARE its answer, and only publishing is refused.
+  `cache-fence.test.ts` is the proof the property survived the move.
+- **This package owns NO cache store, and that is the enforcement** (`As of 2026-08`). A `cache:`
+  read fills `createCacheStack(registeredTiers(), { clock })` — the tiers `@ultimat3/cache` has
+  registered — and there is nothing here to install, swap or wire. There used to be: a private
+  `ReadCache` seam (`setReadCache`/`getReadCache`/`MemoryReadCache`) that `invalidateTags` could not
+  reach, because that fan-out walks the registered `CacheTier`s and nothing else. The gap was closed
+  by `packages/cli/src/dev-cache.ts` installing the read cache **over** an object it also
+  registered — a correctness property held by a wiring line in a CLI file, one edit from being
+  wrong, and carrying a second `ReadCache` implementation (`tierReadCache`) that dated entries with
+  `Date.now()`. And `invalidateQueryTags` was a second fan-out path, which
+  `packages/cache/CLAUDE.md` forbids in as many words. One registry, one fan-out, no seam. **Never
+  reintroduce a store here**, and never call `tier.invalidateTags()` from this package.
+- **A tier refusal degrades the cache, never the read** — and so does every other tier concern.
+  `bestEffort`, the fence, the single flight, the promotion and the TTL are all `createCacheStack`'s,
+  which is what "no store here" buys: a refused `get` reads as a miss, a refused `set` as "that tier
+  is unchanged", and the failure lands in `recentTierFailures()` under the name of the tier that
+  actually refused rather than under a `'query-read'` label for a rung in no registry. Never wrap a
+  tier call here in a private try/catch, and never sample a second fence.
+- **The read path reads NO clock, and that is what makes it drivable.** It hands the stack a
+  RELATIVE `ttlMs`; the tier's own clock turns it into an absolute expiry. `fill` used to compute
+  `nowMs(clock) + ttlMs` and `tierReadCache` used to compute `expiresAt - Date.now()`, so the two
+  `ReadCache` implementations disagreed about "now" and no frozen clock could drive the
+  Redis-backed one. `read-tier.test.ts` pins it: a `createLruTier({ clock, jitterFraction: 0 })` and
+  a `ctx.clock` frozen at the same instant produce an expiry a test can assert exactly.
+- **A `cache:` read always expires, and the bound is the tier's.**
+  `def.cache.ttlMs ?? DEFAULT_READ_CACHE_TTL_MS` (60s) is what `readRows` passes — a query keyed on
+  `{ orgId, cursor }` has as many distinct keys as the deployment has tenants, and unbounded that is
+  one permanent entry per page per org. `null` is "the caller named none", never "never": it reaches
+  the stack as an OMITTED `ttlMs`, which is how a tier is asked for its own default. Every tier
+  refuses a non-positive lease outright, so there is no immortal entry to spell.
+- **A process that registered no tier reads uncached.** `createCacheStack([])` loads, answers and
+  writes nowhere — correct, and slower. That is the trade for deleting the module-default store: a
+  script, a worker boot or a test that wants caching calls `registerTier`, the same call every
+  other cached surface in the framework already uses.
+- **The memo holds an execution, never a decision.** `readRows` runs `buildSource` — parse, guard,
+  `sql()` — *before* it reaches the memo, on every call, and `.as()` reads in a child context whose
+  identity is its own memo. So a memoized answer is still one this actor was allowed to ask for,
+  and no impersonated read can join a read made as someone else. Moving the memo above
+  `buildSource` would turn it into an authz bypass.
+- **`fresh: true` skips the memo on the way in and publishes to it on the way out.** A memo is a
+  cache whose lifetime is the request, so `fresh` refuses to *join* an entry — `readFresh` is
+  `readOnce` minus the join, both sharing one `publish` — but it must still *become* one. Returning
+  the rows early instead left the pre-write entry standing, so "the one way to read past a write
+  made earlier in the same request" ended at the single call that asked for it and the next plain
+  read of that key got the stale answer back. Invalidation still drops tier entries only.
+- **A read can declare a `rateLimit:`, and `toQueryRoute` enforces it — added 2026-08.** `QueryDef`
+  had no such field and the route set no bucket, so **every** `GET /_x/query/*` fell through
+  `bucketFor` to `default` — 120 burst, 2/s per actor. One authenticated caller could hold 120
+  cross-tenant aggregates in flight and then 2/s indefinitely, from a single account, and the
+  declaration that would have throttled it did not exist in the type. `meta.rateLimit` (the name)
+  **and** `meta.rateLimitBucket` (the numbers) are both set, because a name nothing registers is
+  the same silent fall-through. The conversion is `toBucket` from **`@ultimat3/http`** — http owns
+  `Bucket` and the maths, and `@ultimat3/action` is this tier, so a copy here would be a second
+  answer for the write half. Never derive a bucket locally.
+- **`deprecated:` is a compat WINDOW; versioning is not here and will not be.** `Deprecation`
+  (RFC 9745, `@<unix seconds>`) and `Sunset` (RFC 8594, IMF-fixdate) on every answer including the
+  failures, a `rel="successor-version"` link built through `derivePath` — the same derivation
+  `client()` uses, never a second one — the dates on the descriptor, and
+  `deprecated_calls_total{primitive,name}`, which is the only way to answer "is anyone still
+  reading it?" before deleting the read. Rendered ONCE at projection, so a date that cannot become
+  a header is `X_QUERY_DEPRECATION_INVALID` at mount rather than on the first read. Running two
+  versions side by side is two deployments behind one ingress (axiom 7). `deprecation.ts` is a
+  twin of `@ultimat3/action`'s: both are tier 3, the shared home is `@ultimat3/http` if it ever
+  grows one, and this is the same compromise `naming.ts` is ported under.
+- **The span wraps the whole read, not `source.execute()`.** Wrapping the execution alone left the
+  input parse, the policy evaluation and `sql()`'s own construction outside every span, so a read
+  whose cost was in building the source reported milliseconds under a parent reporting seconds —
+  a gap with no name, which reads as framework overhead. Attributes are bounded: surface, actor
+  KIND, `live`, `cached`, `fresh`, and the row count. Never the input and never an actor id — a
+  read is keyed per tenant and per cursor, so either would be unbounded. `telemetry.test.ts`
+  asserts the EXTENT structurally, reading `currentSpan()` from inside the policy predicate and
+  `sql:`, because the test clock is frozen and a timing assertion would hang on it.
+- **`policyCapability` is a display label; `policyPermissions` is what a report matches on.** A
+  composite renders as `or(feed:read, org:administer)`, which equals no permission string, so
+  `x policy list` matching on `capability` reported every non-trivially-guarded read's permissions
+  as *unenforced*. `QueryDescriptor.permissions` is the flattened list from `@ultimat3/policy`,
+  published beside `capability` and never instead of it.
+- **`queryClient`/`client()` inject `traceparent`.** Core's `traceparent()` had no caller in the
+  repo, so a service-to-service read began a fresh root trace on the far side. Set BEFORE the
+  caller's own headers so an explicit one wins; an incomplete span context (`spanId: ''`) sends
+  nothing rather than a header every collector drops. In a browser there is no ambient context, so
+  a cross-origin read gains no CORS preflight it did not already have. The helper is twinned in
+  `@ultimat3/action`'s client for the same tier reason `naming.ts` is.
+- Authz goes through `enforce(surface, policy, { input, actor, ctx })` from
+  `@ultimat3/policy`; a live denial keeps its 4403 close code on `QueryDeniedError.denial`.
+  `policy-gate.ts` is the only file that imports the policy package.
+
+## Commands
+
+```
+bun test packages/query
+bun run typecheck
+```

package/README.md

@@ -29,15 +29,51 @@ Every projection is a method on the query itself. A query has no `.def`.
 | `liveFeed.as(actor, { orgId })` | the same read as another actor — the surrounding context is untouched, `null` is signed out |
 | `liveFeed.page({ orgId }, { first: 20, after })` | one bounded page plus the signed cursor that continues it. There is no `offset` |
 | `liveFeed.live({ orgId })` | the `LiveQuery` `@ultimat3/realtime` subscribes to, carrying the same policy object |
-| `liveFeed.tool()` | the MCP read tool. `tool().policy === liveFeed.policy`, and it reads fresh |
+| `liveFeed.tool()` | the MCP read tool, named `liveFeed`. `tool().policy === liveFeed.policy`, and it reads fresh |
 | `liveFeed.client({ baseUrl })` | `GET /_x/query/live-feed?orgId=…`, typed both ways |
 | `liveFeed.describe()` | the manifest row |
 
+The route on the other end of that client is `toQueryRoute(liveFeed)`, and — `As of 2026-08` —
+`x dev` and a container both mount it for every registered read, the framework's job, not the
+app's. The search string is coerced at the wire and validated by the read's own schema, so a bad
+`orgId` is the query's `X_INPUT_INVALID` and a 400; the answer is `no-store`, because the URL
+names no actor while the rows are scoped to one.
+
+`queryClient` is the same method for **every** registered read at once — the read half of
+`@ultimat3/action`'s `rpc`, and the one spelling available to a surface that may not import a
+feature:
+
+```ts
+import { queryClient } from '@ultimat3/query';
+import type { Api } from '../api';                 // a TYPE, so no module-graph edge
+
+export const queries = queryClient<Api['queries']>({ baseUrl });
+const [post] = await queries.publicPost({ slug }); // typed input, typed rows
+```
+
+Both spellings run `queryClientMethodFor`, so a read has one URL however it is addressed.
+
 The declaration is lifted too: `.input`, `.policy`, `.cache`, `.mcp`, `.isLive`. `sql` is not
 among them — it lives in a private store inside `read.ts`, so `sourceFor` is the only thing
 that can build a source and there is nowhere for a second authz path to hide. Something that
 merely looks like a query (`kind: 'query'`, no declaration) is `X_QUERY_FOREIGN`.
 
+### Skipping the policy costs a written reason
+
+Two reads have no subscriber to decide about: developer tooling that returns the statement and no
+rows (`explain`, `describeSql`), and the shared, subject-less window a sync node builds once per
+`(query, input)`. Both say so, in words:
+
+```ts
+const source = await sourceFor(target, input, {
+  unenforced: 'a scaffolded test asserts the SQL text; the policy is asserted separately',
+});
+```
+
+A blank reason is refused before the source is built. It is a string and not a boolean for the
+reason `@ultimat3/entity`'s `crossTenant(reason, fn)` is: `enforce: false` reads exactly like
+forgetting the policy, and the reason is what tells the next reader which of the two it is.
+
 ## What each file owns
 
 | File | Job |
@@ -47,7 +83,8 @@ merely looks like a query (`kind: 'query'`, no declaration) is `X_QUERY_FOREIGN`
 | `facade.ts` | binds each projection to the query; re-implements none of them |
 | `mcp-tool.ts` | the MCP read descriptor |
 | `client.ts` | the typed read client (browser-safe) |
-| `naming.ts` | export name → wire path + tool name |
+| `http.ts` | the route projection — `GET /_x/query/<kebab>`, the URL the client derives |
+| `naming.ts` | export name → wire path. The MCP tool name is the export name verbatim |
 | `live.ts` | the `LiveQuery` descriptor `@ultimat3/realtime` subscribes to |
 | `matcher.ts` | change event → minimal patch (`add` / `update` / `remove` / `refill`) |
 | `pagination.ts` | `paginate()` — keyset pages over core's cursor codec |
@@ -106,6 +143,14 @@ the package, and rotating the secret is what invalidates every open cursor. This
 the only thing that is its business — the scope, `queryHash(name, input)` — and re-exports
 `CursorInvalidError` so the failure keeps its name on this surface.
 
+The scope's hash is **SHA-256, first 16 hex** (`fingerprint` in `stable.ts`), the primitive and
+width `@ultimat3/realtime`'s `stableDigest` and `@ultimat3/entity`'s `planScope` already use. It
+was FNV-1a/32 until 2026-08 — 4×10⁹ values over input a client chooses, brute-forceable offline in
+seconds, and a fingerprint here is a *sharing* key: which read-cache entry two callers are served
+from, and which scope a cursor is bound to. The canonical serialization did not change, only the
+hash, so a cursor issued before it fails its scope check as `X_CURSOR_INVALID` with "request the
+first page again" as its fix, and a warm read cache is cold once.
+
 A cursor names a **position in the ordering**, never a row and never a count. Both seek paths
 answer "is this row after that position?" through the one predicate, `isAfterKey`: `Builder.seek()`
 compiles it to SQL — spelled out per key, so a mixed `createdAt desc, id asc` listing is a real
@@ -116,23 +161,147 @@ gone. A row with no `id` cannot name a position at all: that is `X_QUERY_NOT_PAG
 cursor signed over `"undefined"`.
 
 Because the predicate always carries that id, the ordering carries it too: a paged read is served
-`order by <declared keys>, "id" asc`, and the in-memory path sorts by the same list. Ordering by
-the declared keys alone leaves rows with equal sort values in whatever order the database chose,
-while the cursor reads them as if id had decided — so one of a tied pair comes back on both pages
-and the other on neither.
+`order by <declared keys>, "id" asc` — that list is `totalOrder(orderBy)`, exported for the reason
+`isAfterKey` is — and the in-memory sort and the live matcher's insertion position read the same
+one. Ordering by the declared keys alone leaves rows with equal sort values in whatever order the
+database chose, while the cursor reads them as if id had decided — so one of a tied pair comes back
+on both pages and the other on neither, and a row the matcher appends after a tie group is a
+position no re-read returns.
+
+A **live** read is served that way too, and `SqlSource.total()` is how it says so: the same read
+with no cursor and no window, ordered `<declared keys>, "id" asc`. `sourceFor` calls it for
+`surface: 'live'` and for nothing else, so the initial window, the patch positions the matcher
+computes and the keyset re-read a reconnect resumes with are one ordering. A source that does not
+implement `total()` is left alone — it already serves one order it can be resumed in.
+
+## NULL
+
+One rule, three readers: the SQL a source generates, the in-memory execution behind `from()`, and
+the live matcher. `null` and a column the row omits are the same absence — `isNull` is the one
+definition, exported for the same reason `isAfterKey` is.
+
+| Operator | NULL is | Emitted as |
+|---|---|---|
+| `=` `!=` `in` | a value — it matches itself and nothing else | `is null` · `is not null` · `is distinct from` · `in (…) or is null` |
+| `>` `>=` `<` `<=` | unknown — a NULL on either side matches nothing | `"col" > $n`, which already matches no NULL |
+| `order by`, the cursor | the largest value: last ascending, first descending | `asc nulls last` · `desc nulls first` |
+
+`where({ deletedAt: null })` compiles to `"deletedAt" is null` and binds no parameter: `= $1` with
+a NULL argument is unknown in Postgres and unknown is never true, so that filter used to match
+every row in memory and none in the database. The seek predicate had the same defect one page
+later — `"publishedAt" > $1` is unknown for every draft, so page two stopped at the first NULL and
+the rows after it were unreachable through a cursor. An ascending key now reaches them
+(`("col" > $1 or "col" is null)`); a NULL cursor value drops its own term, nothing sorting after a
+NULL under `nulls last`, and the page continues on the id tiebreak, which is never NULL.
+
+`nulls last` / `nulls first` are Postgres' own defaults, written down rather than inherited: it is
+the rule `compareValues` implements, so the in-memory sort and the seek predicate can only agree
+with it, and a driver whose default differs cannot re-open the divergence.
 
 ## Caching
 
-Request memo (same read twice in one render ⇒ one round trip), then the tier behind
-`ReadCache`. Keys are `query:<name>:<input fingerprint>:<tags>`. An action's
-`cache.invalidates` and a query's `cache.tags` meet in the one graph owned by
-`@ultimat3/cache`.
+Request memo (same read twice in one render ⇒ one round trip), then the tier ladder
+`@ultimat3/cache` has registered — `createCacheStack(registeredTiers())`, read down and promoted
+up. Keys are `query:<name>:<authority>:<input fingerprint>:<tags>`. An action's `cache.invalidates`
+and a query's `cache.tags` meet in the one graph owned by `@ultimat3/cache`, because there is one
+registry and this package holds no store of its own.
+
+**The authority is who the read was answered for, and it is not optional.** `sql(input, ctx)` is
+handed the context and `@ultimat3/entity` derives every tenant predicate from `ctx.actor.orgId`,
+never from the input — so a key made of the name, the input and the tags did not identify a read's
+answer, and the process-wide tier served one org's rows to the next org that asked. `cache.scope`
+declares who may be served one entry:
+
+| `scope` | Key holds | Use it when |
+|---|---|---|
+| `actor` (default) | the actor's kind, id and org | anything. Declaring nothing gets this, and this is always correct |
+| `tenant` | the actor's org — the actor itself when there is none | every member of one org sees the same rows |
+| `global` | nothing | the rows are the same for everyone, signed-in or not |
+
+The default is the mechanism: forgetting to declare a scope gives the narrowest key. Widening it
+is a written statement about the rows, one `grep` away — the same shape `unenforced:` uses for a
+skipped policy. `readAuthority(actor, scope)` is the only producer of the component, and it is a
+required positional argument of `cacheKeyFor`, because an optional one is one a call site forgets.
+
+**The fill is fenced, best-effort and single-flighted, and none of that is written here.**
+`createCacheStack` samples `@ultimat3/cache`'s fence immediately before it runs the source and
+re-asks it per rung before each write, so a bust that lands mid-read cannot be republished for the
+whole TTL — the caller still gets the rows it read, because those are its answer; only publishing is
+refused. Every tier call goes through `bestEffort`, so a Redis refusal is a miss rather than a
+failed business read and shows up in `recentTierFailures()` under the name of the tier that
+refused. Concurrent misses of one key share one `load()`. `@ultimat3/query` used to carry its own
+copy of the first two and none of the third.
+
+`cache.ttlMs` is refused at `query()` unless it is positive and finite
+(`X_QUERY_CACHE_TTL_INVALID`): every tier refuses such a lease, so `ttlMs: Infinity` used to make
+one read fail permanently at run time with a cause about a cache key.
+
+An entry is written with the read's `cache.tags`, so a row bust (`post:1`) drops the lists that
+held the row, exactly as `tagMatches` defines it — and `invalidateTags(tags)`, the call an action's
+`cache.invalidates` makes, is the whole of what drops it. There is nothing to install and nothing
+to wire: a `cache:` read fills the registered tiers, so a process that registered none reads
+uncached rather than filling a store no fan-out can see.
+
+A `cache:` block that omits `ttlMs` gets `DEFAULT_READ_CACHE_TTL_MS` (60s) rather than immortality.
+Tags are the primary eviction; the TTL is the backstop for the read whose tags never fire. The
+lease handed to the ladder is **relative** — the tier's own clock turns it into an expiry, so a
+tier registered with a frozen clock is drivable end to end — and omitting it is how a tier is asked
+for its own default. `@ultimat3/cache`'s tiers refuse a non-positive `ttlMs` and have no immortal
+entry to offer, so there is no "never" to spell.
+
+The memo entry is the read **in flight**, not its value, so "twice" covers reads that race as
+well as reads that follow: five holes rendering concurrently share one execution and one tier
+round trip. A rejection is evicted — a failed read is not the request's answer.
+
+| Layer | Applies to | Lifetime |
+|---|---|---|
+| request memo (`readOnce`) | **every** query, `cache:` or not | the request — a `Ctx`'s identity is the key |
+| tag-keyed tier (`readThrough`) | a query that declares `cache:` | `ttlMs`, or until an `invalidates` fan-out drops the tag |
+
+`cache:` buys the tier, never the memo: an uncached lookup called once per row of a list would
+otherwise cost one round trip per row. Parsing, the policy and `sql()` still run on every call —
+the memo holds the execution, not the decision — and `.as()` reads in a child context, so an
+impersonated read never joins one made as someone else.
+
+`fresh: true` skips both on the way in, and **publishes into the memo on the way out**: it is how
+a caller reads past a write made earlier in the same request, and the read it just made is the
+request's answer from then on, so a later plain read of the same key joins it rather than the entry
+the write moved past. Invalidation drops tier entries, not memo entries.
+
+## `rateLimit:` — the read half, and it is enforced
+
+```ts
+rateLimit: { limit: 3, windowMs: 600_000 },   // 3 held, one back every three and a bit minutes
+```
+
+Symmetric with an action's, and for a reason: without it **every** `GET /_x/query/*` fell to the
+`default` bucket — 120 burst, 2/s per actor — so one authenticated caller could hold 120
+cross-tenant aggregates in flight and then 2/s indefinitely, from a single account, with no
+declaration able to say otherwise. `toQueryRoute` sets the bucket NAME and the NUMBERS, and
+`@ultimat3/http`'s `withRouteBuckets` registers them: a name alone falls through to `default`.
+The conversion is `toBucket` from `@ultimat3/http` — the same one the action route uses, because
+http owns `Bucket` and `action` is the same tier as this package. A pair the limiter cannot run
+on is `X_RATE_LIMIT_INVALID`, at projection.
+
+## `deprecated:` — a compat window, not a version
+
+```ts
+deprecated: { since: '2026-08-01T00:00:00Z', sunset: '2026-12-31T23:59:59Z', replacedBy: 'searchOrders' },
+```
+
+`Deprecation` (RFC 9745) and `Sunset` (RFC 8594) on every answer, a
+`link: </_x/query/search-orders>; rel="successor-version"`, the dates on the descriptor, and a
+`deprecated_calls_total{primitive,name}` counter so "is anyone still reading it?" has an answer
+before the read is deleted. A date that cannot be rendered is `X_QUERY_DEPRECATION_INVALID` at
+projection, not on the first read. Versioning is two deployments behind one ingress, never a
+router feature here.
 
 ## Errors
 
 | Code | When | Fix |
 |---|---|---|
 | `X_QUERY_DUPLICATE` | two queries under one name | rename one export |
+| `X_QUERY_DEPRECATION_INVALID` | `deprecated:` with a `since`/`sunset` that is not a date | use an ISO-8601 instant |
 | `X_QUERY_POLICY_MISSING` | registration without `policy:` | add `policy: can('…')` |
 | `X_MATCHER_UNSUPPORTED` | live query the matcher cannot patch | reshape it, or `live: false` |
 | `X_CURSOR_INVALID` | tampered / foreign / malformed cursor | request the first page again |