@ultimat3/query 11.1.0 → 11.3.0

package/CLAUDE.md

@@ -18,6 +18,7 @@ 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: no server imports) |
+| — | opt-in flight control is **`@ultimat3/core`**'s `client-flight.ts` + `client-wire.ts`, re-exported from `src/index.ts`. There is no local copy and must not be one |
 | `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 |
@@ -162,6 +163,50 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
 - `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`.
+- **Flight control is `@ultimat3/core`'s, and this package RE-EXPORTS it.** `client-flight.ts` and
+  `client-wire.ts` shipped here and in the other tier-3 client package as byte-identical copies —
+  288 and 85 lines — kept in step by a `client-twin.test.ts` in each. A test that makes drift LOUD
+  is not the same as a file that cannot drift, and this package's own thesis is that duplication is
+  the defect. Both files import nothing but tier 0, which was always the argument for where they
+  belong; the one blocker was `isJsonObject`, now `@ultimat3/core`'s `json-object.ts`, re-exported
+  from `./stable` here. `createClientFlight`, `DEFAULT_CLIENT_RETRY`, `isTransientFailure`,
+  `isSuperseded`, `ClientFlight`, `ClientFlightOptions`, `ClientRetry`, `FlightKeyOptions`,
+  `FlightPlan` and `WireAnswer` are all still importable from `@ultimat3/query` — the same names,
+  and now literally the same objects the other package exports. Never re-declare one here; the
+  fix for anything wrong with the pipeline is an edit in `packages/core/src/client-flight.ts`.
+- **Every mechanism underneath the flight is `@ultimat3/core`'s, the pipeline included.**
+  `createSingleFlight` for dedup, `createFence`/`isSuperseded` for supersession, `createFlightGate`
+  for the ceiling, `retry` + `backoffDelay` for the schedule, `isRetryableStatus` for the status
+  table, `X_TIMEOUT` for the deadline — and `createClientFlight`, which composes them. This package
+  declares NO new error code for any of it; never add a second curve, a second fence or a private
+  retry loop here, and `bun run flight-copies` is what says so.
+- **`isTransientFailure` INVERTS `retryDecision`'s unclassified default, and the inversion must
+  survive** (`As of 2026-08-23`). `retryDecision` sends a throw nobody classified again until the
+  attempts run out; `@ultimat3/ai` and `@ultimat3/db` each refused the executor outright over it.
+  The client keeps the executor and supplies a predicate instead: a declared
+  `retryable`/`retry-after`, plus a dispatch that produced no response at all (`fetch` rejecting
+  with a plain `TypeError`), and nothing else — a caller's own `AbortError` and a foreign value are
+  terminal. The loop is stopped by RESOLVING to a private sentinel rather than by throwing, so the
+  original value still reaches the caller unwrapped, which is the property `retry`'s own header
+  promises. It lives in `packages/core/src/client-flight.ts` now; the tests that pin it from this
+  side still drive it through this package's own client.
+- **`ClientFlight` is a TYPE inside `client.ts` and never a value.** That erasure is the entire
+  tree-shaking story: `rpc` alone is 14,759 B minified for the browser and `queryClient` alone is
+  12,755 B, against 20,292 B / 17,912 B with `createClientFlight` imported beside them — ±376 B run
+  to run, which is `Bun.build` 1.4.0 dropping core's `schema-error-codes.ts` (issue #273). A caller
+  who wants a plain typed fetch must not pay for the fence, the dedup map or the retry loop —
+  `packages/cli/src/templates/resource-form-island.ts` and `examples/dummy`'s contact-sales island
+  both write a bare `fetch` today because that bill used to be unavoidable. Never import
+  `createClientFlight` for a VALUE from `client.ts` — `ClientFlight` and `ClientRetry` are
+  `import type` from `@ultimat3/core` and must stay that way.
+- **The `sideEffects` array is what makes the barrel shakable, and it is load-bearing** (`As of
+  2026-08-23`). Declaring nothing meant a bundler had to assume every module ran at import, so
+  `import { rpc } from '@ultimat3/action'` was 43,104 B and `import { queryClient } from
+  '@ultimat3/query'` was 40,859 B — three times the deep-import cost, through the ONLY specifier
+  the `exports` map offers. The arrays are the ones `bun run scripts/side-effects.ts --explain
+  --json` measures, and they must stay that: `errors.ts` runs `registerErrorCodes` at import in both
+  packages, and query's `registry.ts` runs `registerPrimitiveRegistrar('query', …)` — drop either
+  and a bundled app loses its error titles or throws `X_REGISTRAR_MISSING`. Never `false`.
 - 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
@@ -304,7 +349,8 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
   date window shared one live query id. The hash form tags a `Date`, a `Map` and a `Set`
   (`Date(<epoch>)`, `Map(…)`, `Set(…)`) beside the bare `NaN` / `±Infinity` / `-0` tokens it
   already emitted, all for the reason a bare token exists: `'null'` collided with JSON `null` and
-  `String(-0)` is `"0"`. `stable.ts` keeps `isJsonObject`/`columnOf` and nothing else. Ordinary
+  `String(-0)` is `"0"`. `stable.ts` keeps `columnOf` and a re-export of core's `isJsonObject` —
+  that predicate went down to tier 0 the same way, when `client-wire.ts` did. Ordinary
   inputs are byte-identical, so the durable-key cost is confined to reads whose input carries a
   `Date`, a `Map` or a `Set`: those cursors answer `X_CURSOR_INVALID` once, and their cache entries
   are cold once. `query-hash.test.ts` is the pin, at `queryHash` and at `cacheKeyFor`.

package/README.md

@@ -53,6 +53,54 @@ const [post] = await queries.publicPost({ slug }); // typed input, typed rows
 
 Both spellings run `queryClientMethodFor`, so a read has one URL however it is addressed.
 
+### Flight control — `createClientFlight`, opt-in
+
+A typed read is one `fetch` and nothing else until a `flight` is installed. With one, N concurrent
+identical reads become ONE dispatch, a fence can retire everything issued before now, and a failure
+worth sending again is sent again on `@ultimat3/core`'s one backoff curve.
+
+```ts
+import { createClientFlight, isSuperseded, queryClient } from '@ultimat3/query';
+
+declare const session: () => { userId: string };
+declare const baseUrl: string;
+type Api = { queries: Record<string, never> };
+
+const flight = createClientFlight({
+  principal: () => session().userId,   // dedup is OFF without this — see below
+  retry: { attempts: 3 },              // default is `attempts: 1`, i.e. no retry
+  deadlineMs: 10_000,
+  limit: { maxConcurrent: 6, maxQueued: 12 },
+});
+
+export const queries = queryClient<Api['queries']>({ baseUrl, flight });
+
+// A route change, a sign-out, a tenant switch: everything already issued stops being addressed
+// to anybody, and every read still open is aborted.
+flight.bump();
+```
+
+| Rule | Why it is that way |
+|---|---|
+| the dedup key is `[principal, url]`, and **no principal means no dedup** | a key that is only the URL lets one caller join another's still-open read across a sign-in or a tenant switch |
+| a caller-supplied `signal` is **never** shared | the leader owns the request, so one caller's abort would cancel every other caller's read; refcounting joiners is the "correct" fix and this is the one that cannot be wrong |
+| `{ fresh: true }` opts one read out | the case it exists for is "this read exists BECAUSE something just changed", which must not join a dispatch that left before the change did |
+| every joiner parses its own rows | what is shared is the immutable body TEXT; handing two callers one array hands each of them the other's edits |
+| a fenced answer is `X_SUPERSEDED`, never a failure | `isSuperseded(error)` is the read; a caller that cannot tell it from a refusal retries a request its own context has already replaced |
+| an **unclassified** throw is not retried | core's `retryDecision` retries anything nobody classified — a caller's own `AbortError` included. A client retries a declared `retryable`/`retry-after`, plus a dispatch that produced no response at all |
+| a deadline is `X_TIMEOUT` | core's code, already classified `retryable`, so a caller's own loop needs no table |
+
+`createClientFlight` is **`@ultimat3/core`'s**, re-exported here: it is the same object
+`@ultimat3/action` re-exports, because both packages are tier 3 and neither may import the other.
+It shipped as a byte-identical copy in each; the copies are gone and every name is importable from
+this package exactly as before.
+
+Bundle cost is why `ClientFlight` is a TYPE inside `client.ts` and never a value: importing
+`queryClient` alone from this package is **12,755 B** minified for the browser, and adding
+`createClientFlight` is **17,912 B**. A caller who wants a plain typed fetch pays for none of it.
+Expect ±376 B run to run — `Bun.build` 1.4.0 drops `@ultimat3/core`'s `schema-error-codes.ts` from
+some builds even though `sideEffects` names it (issue #273).
+
 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

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@ultimat3/query",
-  "version": "11.1.0",
+  "version": "11.3.0",
   "description": "The query primitive: a policy-checked read, optionally live, with cursor pagination and an incremental matcher",
   "license": "MIT",
   "type": "module",
+  "sideEffects": [
+    "./src/errors.ts",
+    "./src/registry.ts"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/developerz-ai/ultimate.git",
@@ -31,10 +35,10 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "11.1.0",
-    "@ultimat3/core": "11.1.0",
-    "@ultimat3/http": "11.1.0",
-    "@ultimat3/policy": "11.1.0",
-    "@ultimat3/schema": "11.1.0"
+    "@ultimat3/cache": "11.3.0",
+    "@ultimat3/core": "11.3.0",
+    "@ultimat3/http": "11.3.0",
+    "@ultimat3/policy": "11.3.0",
+    "@ultimat3/schema": "11.3.0"
   }
 }

package/src/client.ts

@@ -8,9 +8,16 @@
  * output schema — row types come from the `SqlSource` its `sql:` returns — so there is nothing
  * here to rehydrate a `Date` with, and an instant reaches a caller as the ISO string
  * `JSON.stringify` wrote. A surface that formats one converts at its own edge.
+ *
+ * `ClientFlight` is a TYPE here and never a value: dedup, retry, the deadline and the fence are
+ * `@ultimat3/core`'s `client-flight.ts`, and a caller that never calls `createClientFlight` does
+ * not pay a byte for any of them — an `import type` is erased and the value import would not be.
+ * That erasure is the whole reason two islands in this repo write a bare `fetch` instead of
+ * importing a typed client.
  */
 
-import { currentSpanContext, traceparent } from '@ultimat3/core';
+import type { ClientFlight, ClientRetry, WireAnswer } from '@ultimat3/core';
+import { problemOf, traceHeaders } from '@ultimat3/core';
 import type { InferInput, StandardSchemaV1 } from '@ultimat3/schema';
 import { QueryRequestFailedError } from './errors';
 import { derivePath } from './naming';
@@ -23,10 +30,24 @@ export interface QueryClientOptions {
   readonly baseUrl: string;
   readonly fetch?: FetchLike;
   readonly headers?: Readonly<Record<string, string>>;
+  /**
+   * Opt-in flight control for every read this client makes — `createClientFlight({ principal })`.
+   * Absent, a read is one `fetch` and nothing else, which is what every caller written before this
+   * option existed already gets.
+   */
+  readonly flight?: ClientFlight;
 }
 
 export interface QueryCallOptions {
   readonly signal?: AbortSignal;
+  /**
+   * Refuse to join an identical read already in flight. The case it exists for: this read exists
+   * BECAUSE something just changed, so an answer dispatched before the change is the wrong one.
+   * Named for `read.ts`'s `fresh`, which means the same thing one layer down — do not join.
+   */
+  readonly fresh?: boolean;
+  /** Overrides the flight's retry policy for this one read. Ignored with no `flight` installed. */
+  readonly retry?: ClientRetry;
 }
 
 /** `feed({ orgId })` with the input schema and the row type both inferred. */
@@ -107,41 +128,50 @@ async function read(
 ): Promise<unknown> {
   const search = searchOf(input);
   const url = `${base}${derivePath(name)}${search === '' ? '' : `?${search}`}`;
+  const dispatch = (signal: AbortSignal | undefined): Promise<WireAnswer> =>
+    fetchOnce(doFetch, url, options, name, signal ?? callOptions.signal);
+
+  const flight = options.flight;
+  const answer =
+    flight === undefined
+      ? await dispatch(undefined)
+      : await flight.run({
+          key: flight.keyFor(url, callOptions),
+          // A caller holding its own signal owns this read's lifecycle: it is neither shared nor
+          // aborted by a fence bump, and its signal is the only one that reaches the wire.
+          abortable: callOptions.signal === undefined,
+          ...(callOptions.retry === undefined ? {} : { retry: callOptions.retry }),
+          run: dispatch,
+        });
+  // Parsed per CALLER, never once per dispatch: N joiners of one deduped read may not be handed
+  // one mutable array between them, and the shared value is the immutable body TEXT for that
+  // reason alone.
+  return JSON.parse(answer.text) as unknown;
+}
+
+/** One dispatch. Everything above it decides how many times this happens; it decides none. */
+async function fetchOnce(
+  doFetch: FetchLike,
+  url: string,
+  options: QueryClientOptions,
+  name: string,
+  signal: AbortSignal | undefined,
+): Promise<WireAnswer> {
   const init: RequestInit = {
-    method: 'GET',
     // `traceHeaders()` before the caller's, so an explicit `traceparent` still wins. Without it a
     // service-to-service read started a fresh root trace on the other side, and "which of my
     // downstreams is slow" was unanswerable across every Ultimate-to-Ultimate hop.
     headers: { accept: 'application/json', ...traceHeaders(), ...options.headers },
-    ...(callOptions.signal === undefined ? {} : { signal: callOptions.signal }),
+    method: 'GET',
+    ...(signal === undefined ? {} : { signal }),
   };
 
   const response = await doFetch(url, init);
-  if (!response.ok)
-    throw new QueryRequestFailedError(name, response.status, await problemOf(response));
-  const body: unknown = await response.json();
-  return body;
-}
-
-/** A `traceparent` is `00-<32 hex>-<16 hex>-<2 hex>`, and nothing else may be sent as one. */
-const TRACE_ID = /^[0-9a-f]{32}$/;
-const SPAN_ID = /^[0-9a-f]{16}$/;
-
-/**
- * The current trace, as the W3C header — or nothing at all. `currentSpanContext()` answers with
- * an empty `spanId` when a request context exists but no span is active, and `00-<trace>--01` is
- * a header every collector drops, so an incomplete context sends none. In a browser there is no
- * ambient context and this is always empty, which is also what keeps a cross-origin read from
- * acquiring a CORS preflight it did not have.
- *
- * `@ultimat3/action`'s client carries the twin of this function: both are tier 3, so neither may
- * import the other — the same reason `naming.ts` is ported rather than shared.
- */
-function traceHeaders(): Record<string, string> {
-  const context = currentSpanContext();
-  if (context === undefined) return {};
-  if (!TRACE_ID.test(context.traceId) || !SPAN_ID.test(context.spanId)) return {};
-  return { traceparent: traceparent(context) };
+  // Read as TEXT once: a `Response` body is a single-use stream, so the failure path and the row
+  // path cannot both have it, and a shared answer has to be something a joiner can re-read.
+  const text = await response.text();
+  if (!response.ok) throw new QueryRequestFailedError(name, response.status, problemOf(text));
+  return { status: response.status, text };
 }
 
 /**
@@ -160,9 +190,3 @@ function searchOf(input: unknown): string {
   }
   return params.toString();
 }
-
-/** `application/problem+json`, or nothing when a proxy answered instead of the app. */
-async function problemOf(response: Response): Promise<Record<string, unknown>> {
-  const body: unknown = await response.json().catch(() => null);
-  return isJsonObject(body) ? body : {};
-}

package/src/errors.ts

@@ -1,5 +1,5 @@
 /** Every failure @ultimat3/query can produce, one subclass per stable code. */
-import { assertNever, registerErrorCodes, UltimateError } from '@ultimat3/core';
+import { assertNever, registerErrorCodes, retryForStatus, UltimateError } from '@ultimat3/core';
 import type { SurfaceDenial } from '@ultimat3/policy';
 
 // No `docs:` on the classes below, with one exception noted at `QueryRequestFailedError`.
@@ -279,6 +279,11 @@ export class QueryRequestFailedError extends UltimateError {
     const served = text(problem.docs);
     super({
       code,
+      // The status is what says "send it again", and only where nobody has classified the code:
+      // `UltimateError` otherwise fills `retry` from `retryFor(code)`, which fails closed, so a
+      // 502 out of a typed read announced itself as `terminal` on the one field the framework
+      // promises a client never has to infer.
+      retry: retryForStatus(code, status),
       cause: text(problem.cause) ?? text(problem.detail) ?? `${name} returned HTTP ${status}`,
       fix:
         text(problem.fix) ??

package/src/index.ts

@@ -6,6 +6,32 @@
  * authorize or execute on its own. One authz system, structurally.
  */
 
+/**
+ * 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,
+ * 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.
+ */
+export type {
+  ClientFlight,
+  ClientFlightOptions,
+  ClientRetry,
+  FlightKeyOptions,
+  FlightPlan,
+  WireAnswer,
+} from '@ultimat3/core';
+export {
+  createClientFlight,
+  DEFAULT_CLIENT_RETRY,
+  isSuperseded,
+  isTransientFailure,
+} 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';

package/src/stable.ts

@@ -1,16 +1,18 @@
 /**
- * What a JSON object IS to this package, and how a column is read off a row that declares no index
- * signature. Two small predicates the read path needs everywhere.
+ * How a column is read off a row that declares no index signature — one predicate the read path
+ * needs everywhere, and one re-export beside it.
  *
- * The deterministic-JSON half used to live here and no longer does: `canonicalJson` and
- * `fingerprint` are `@ultimat3/core`'s, because `@ultimat3/action` and `@ultimat3/realtime` need
- * the identical function and all three are tier 3 — so a copy in any of them was a second answer
- * for the other two, and the copies had already diverged. This one rendered every `Date` as `{}`.
+ * Both halves used to be declared here and no longer are. `canonicalJson` and `fingerprint` are
+ * `@ultimat3/core`'s, because `@ultimat3/action` and `@ultimat3/realtime` need the identical
+ * function and all three are tier 3 — so a copy in any of them was a second answer for the other
+ * two, and the copies had already diverged. This one rendered every `Date` as `{}`. `isJsonObject`
+ * went the same way for the same reason, when `client-wire.ts` moved to tier 0.
  */
 
-export function isJsonObject(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
+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 {