@ultimat3/action 11.1.0 → 11.2.0

package/CLAUDE.md

@@ -21,6 +21,8 @@ Owns the `action` + `mutator` primitives and their six projections. Tier 3.
 | `http.ts` | route projection (`enforcedBy: 'handler'`) + OpenAPI operation |
 | `openapi.ts` | deterministic OpenAPI 3.1 document |
 | `client.ts` | typed RPC 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 |
+| `wire-headers.ts` | `BUILD_ID_HEADER` + `IDEMPOTENCY_HEADER`, and nothing else. Their own module so `client.ts` can name them without importing `http.ts` |
 | `mcp-tool.ts` | MCP descriptor, same `invoke` |
 | `job-handle.ts` | the `.job()` projection: an action as a queueable payload. **Not** consumed by `@ultimat3/jobs` — see Invariants |
 | `contract-test.ts` | assertions `x g action` emits |
@@ -35,7 +37,7 @@ Owns the `action` + `mutator` primitives and their six projections. Tier 3.
 | `audit.ts` | the audit seam: `AuditRecord`, `AuditSink`, the memory sink, the installed-sink store |
 | `audit-gate.ts` | **the only** file that calls a sink, and where the two failure policies live |
 | `type-pins.ts` | compile-time assertions `tsc` checks — what the erased view projects, and why `client()` is not part of it |
-| `naming.ts`, `validate.ts`, `json-schema.ts`, `stable.ts` | pure helpers. `stable.ts` is the DOCUMENT serializer only — the hash form is `@ultimat3/core`'s `canonicalJson`/`fingerprint` |
+| `naming.ts`, `validate.ts`, `json-schema.ts`, `stable.ts` | pure helpers. `stable.ts` is the DOCUMENT serializer plus a re-export of core's `isJsonObject` — the hash form is `@ultimat3/core`'s `canonicalJson`/`fingerprint` |
 
 ## Invariants
 
@@ -435,6 +437,62 @@ Owns the `action` + `mutator` primitives and their six projections. Tier 3.
   same-named helpers overwrite each other with no `X_ACTION_DUPLICATE` to raise. The type does the
   same filter, so `rpc<Api['actions']>()` offers only what registered.
 - `rpc` is the only name for the map-wide typed client. There is no `createClient` alias.
+- **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/action` — 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`.
+- **A retried mutation is gated on an `Idempotency-Key`, and the gate is silent narrowing rather
+  than a refusal** (`As of 2026-08-23`). `CallOptions.retry` is honoured only alongside
+  `idempotencyKey`; without one the call is narrowed to a single attempt. A second POST with no key
+  is a second WRITE, and nothing at this seam can tell a lost answer from a lost request. A refusal
+  was the other candidate and was rejected: `retry:` may be set once on the flight for a whole
+  client, and turning every keyless call in an app into a thrown error would make the flight
+  un-installable. `client-flight.test.ts` pins both halves, and the header on every attempt.
+- **A fence never aborts a write, and `client.ts` never calls `flight.keyFor`.** The first because
+  closing a mutation's socket does not un-commit it — it only destroys the one chance the caller had
+  of learning whether it landed, so `abortable: false` is unconditional and the caller still gets
+  `X_SUPERSEDED` for the ANSWER. The second is how "a mutation may never join another mutation" is
+  enforced: there is no dedup path to reach from here, even with a principal installed.
 - **`registerAction` guards the derived PATH as well as the name.** `X_ACTION_DUPLICATE` only ever
   asked about the name, so `archiveOrder` and `archiveOrders` — one route, by `pluralize`'s
   deliberate "a trailing `s` is already plural" rule — both registered and both projected: the

package/README.md

@@ -116,6 +116,38 @@ export const client = rpc<Api['actions']>({ baseUrl: '/' });
 declaration with no codegen step. `Api` is imported as a **type only**, which is what keeps
 a page's module graph free of any edge to a feature's implementation.
 
+### Flight control — `createClientFlight`, opt-in
+
+Same object as `@ultimat3/query`'s, installed the same way (`rpc({ baseUrl, flight })`), and the
+write half is the half made of refusals:
+
+| Rule | Why |
+|---|---|
+| a mutation **never** joins another mutation | `client.ts` never calls `flight.keyFor`, so there is no dedup path to reach; two writes are two writes |
+| a fence bump **never** aborts a write | closing the socket does not un-commit it, it only destroys the one chance this caller had of learning whether it landed. The caller still gets `X_SUPERSEDED` — the answer is retired, the request is not |
+| `retry` is honoured only alongside an `idempotencyKey` | a retried POST without one is a second write. Without a key the call is narrowed to a single attempt, silently and by construction |
+| the same `Idempotency-Key` rides every attempt | that is what makes the retry a retry rather than a duplicate |
+
+```ts
+declare const api: { charge: (input: { orderId: string }, options?: {
+  idempotencyKey?: string; retry?: { attempts: number };
+}) => Promise<unknown> };
+declare const orderId: string;
+
+await api.charge({ orderId }, { idempotencyKey: `charge:${orderId}`, retry: { attempts: 3 } });
+```
+
+`createClientFlight` is **`@ultimat3/core`'s**, re-exported here: it is the same object
+`@ultimat3/query` 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.
+
+Importing `rpc` alone from this package is **14,759 B** minified for the browser; adding
+`createClientFlight` is **20,292 B**. `ClientFlight` is a TYPE inside `client.ts` and never a
+value, which is what keeps the second number off the first caller's bill. 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), which is the size of the schema error titles.
+
 ## Path derivation
 
 First camelCase word is the verb; the rest is the resource, last word pluralized,

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@ultimat3/action",
-  "version": "11.1.0",
+  "version": "11.2.0",
   "description": "The action primitive: one declaration projected to route, OpenAPI, client, MCP tool, job handle, tests",
   "license": "MIT",
   "type": "module",
+  "sideEffects": [
+    "./src/errors.ts"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/developerz-ai/ultimate.git",
@@ -31,10 +34,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.2.0",
+    "@ultimat3/core": "11.2.0",
+    "@ultimat3/http": "11.2.0",
+    "@ultimat3/policy": "11.2.0",
+    "@ultimat3/schema": "11.2.0"
   }
 }

package/src/client.ts

@@ -2,15 +2,20 @@
  * Projection 3: the typed RPC client. Types come from the action map, paths from
  * the same pure derivation the server uses, so a renamed or mistyped action is a
  * compile error in a Solid component — not a 404 at runtime.
+ *
+ * `ClientFlight` is a TYPE here and never a value: the fence, the retry loop and the deadline are
+ * `@ultimat3/core`'s `client-flight.ts`, so 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.
+ * Dedup is deliberately unreachable from this file — a mutation may never join another mutation,
+ * and the way that is guaranteed is that `keyFor` is never called here.
  */
-import type { UltimateError } from '@ultimat3/core';
-import { currentSpanContext, traceparent } from '@ultimat3/core';
+import type { ClientFlight, ClientRetry, UltimateError, WireAnswer } from '@ultimat3/core';
+import { FRAMEWORK_CODE, problemOf, traceHeaders } from '@ultimat3/core';
 import type { InferInput, InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
 import type { Action } from './action';
 import { ContractDriftError, RemoteActionError, RpcFailedError } from './errors';
-import { BUILD_ID_HEADER, IDEMPOTENCY_HEADER } from './http';
 import { derivePath } from './naming';
-import { isJsonObject } from './stable';
+import { BUILD_ID_HEADER, IDEMPOTENCY_HEADER } from './wire-headers';
 
 /**
  * Loose constraint on purpose: a map of concrete `Action<In, Out>` values must be
@@ -26,6 +31,12 @@ export type ActionMap = Record<string, ActionLike>;
 export interface CallOptions {
   readonly idempotencyKey?: string;
   readonly signal?: AbortSignal;
+  /**
+   * Retry THIS call. Honoured only alongside an `idempotencyKey`, and silently narrowed to one
+   * attempt without one — a retried mutation with no key is a second write, not a second attempt,
+   * and the framework has no way to tell a lost answer from a lost request.
+   */
+  readonly retry?: ClientRetry;
 }
 
 /** `api.publishPost({ postId })` with both sides of the schema inferred. */
@@ -48,6 +59,11 @@ export interface ClientOptions {
   /** Sent on every call; a differing server build id raises X_CONTRACT_DRIFT. */
   readonly buildId?: string;
   readonly headers?: Readonly<Record<string, string>>;
+  /**
+   * Opt-in flight control — `createClientFlight({ … })`. Absent, a call is one `fetch` and nothing
+   * else, which is what every caller written before this option existed already gets.
+   */
+  readonly flight?: ClientFlight;
 }
 
 /**
@@ -87,6 +103,9 @@ export function clientMethodFor<TInput extends StandardSchemaV1, TOutput extends
     call(doFetch, base, options, name, input, callOptions) as Promise<InferOutput<TOutput>>;
 }
 
+/** One attempt, and no retry at all. What a mutation carrying no idempotency key is allowed. */
+const ONCE: ClientRetry = { attempts: 1 };
+
 async function call(
   doFetch: FetchLike,
   base: string,
@@ -95,6 +114,40 @@ async function call(
   input: unknown,
   callOptions: CallOptions,
 ): Promise<unknown> {
+  const url = `${base}${derivePath(name).path}`;
+  const body = JSON.stringify(input ?? {});
+  const dispatch = (signal: AbortSignal | undefined): Promise<WireAnswer> =>
+    postOnce(doFetch, url, body, options, name, callOptions, signal ?? callOptions.signal);
+
+  const flight = options.flight;
+  const answer =
+    flight === undefined
+      ? await dispatch(undefined)
+      : await flight.run({
+          // `undefined`, unconditionally: a mutation may never join another mutation, and the
+          // enforcement is that this file never calls `flight.keyFor`.
+          key: undefined,
+          // NEVER aborted. A fence bump and a deadline both mean "this answer no longer matters";
+          // closing the socket does not un-commit the write, it only destroys the one chance this
+          // caller had of learning whether it landed.
+          abortable: false,
+          retry: callOptions.idempotencyKey === undefined ? ONCE : (callOptions.retry ?? ONCE),
+          run: dispatch,
+        });
+  if (answer.status === 204) return undefined;
+  return JSON.parse(answer.text) as unknown;
+}
+
+/** One dispatch. Everything above it decides how many times this happens; it decides none. */
+async function postOnce(
+  doFetch: FetchLike,
+  url: string,
+  body: string,
+  options: ClientOptions,
+  name: string,
+  callOptions: CallOptions,
+  signal: AbortSignal | undefined,
+): Promise<WireAnswer> {
   const headers: Record<string, string> = {
     'content-type': 'application/json',
     // Before the caller's headers, so an explicit `traceparent` still wins. Without this a
@@ -111,36 +164,16 @@ async function call(
   const init: RequestInit = {
     method: 'POST',
     headers,
-    body: JSON.stringify(input ?? {}),
-    ...(callOptions.signal === undefined ? {} : { signal: callOptions.signal }),
+    body,
+    ...(signal === undefined ? {} : { signal }),
   };
-  const response = await doFetch(`${base}${derivePath(name).path}`, init);
+  const response = await doFetch(url, init);
   assertSameBuild(options.buildId, response.headers.get(BUILD_ID_HEADER), name);
-  if (!response.ok) throw await toUltimateError(response, name);
-  if (response.status === 204) return undefined;
-  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 GET from
- * acquiring a CORS preflight it did not have.
- *
- * `@ultimat3/query`'s client carries the twin of this function: both are tier 3, so neither may
- * import the other.
- */
-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
+  // answer path cannot both have it.
+  const text = response.status === 204 ? '' : await response.text();
+  if (!response.ok) throw toUltimateError(text, response.status, name);
+  return { status: response.status, text };
 }
 
 /**
@@ -160,13 +193,6 @@ function assertSameBuild(
   );
 }
 
-/**
- * A framework code, spelled the one way codes are spelled. `typeof code === 'string'` alone
- * accepted `""` and `"error"` — a gateway's JSON body became an `UltimateError` whose code
- * nothing in the framework or the app declares, rendering `: ` under a humanised title.
- */
-const FRAMEWORK_CODE = /^X_[A-Z0-9]+(?:_[A-Z0-9]+)*$/;
-
 /**
  * `application/problem+json` back into the error the server threw. The code rides along
  * verbatim — carrying one is the point of the document — but it is a code this bundle may never
@@ -174,18 +200,19 @@ const FRAMEWORK_CODE = /^X_[A-Z0-9]+(?:_[A-Z0-9]+)*$/;
  * to a page that exists. A body naming no framework code is a proxy answering rather than the
  * app, which is what `RpcFailedError` already says.
  */
-async function toUltimateError(response: Response, name: string): Promise<UltimateError> {
-  const body: unknown = await response.json().catch(() => null);
-  if (!isJsonObject(body)) return new RpcFailedError(name, response.status);
+function toUltimateError(text: string, status: number, name: string): UltimateError {
+  // `problemOf` is total — a gateway's HTML, an empty body and a truncated stream all answer `{}`,
+  // which carries no `code` and therefore lands on `RpcFailedError` exactly as before.
+  const body = problemOf(text);
   const code = body['code'];
   if (typeof code !== 'string' || !FRAMEWORK_CODE.test(code)) {
-    return new RpcFailedError(name, response.status);
+    return new RpcFailedError(name, status);
   }
   return new RemoteActionError({
     action: name,
-    status: response.status,
+    status,
     code,
-    cause: stringOr(body['cause'] ?? body['detail'], `${name} failed with ${response.status}`),
+    cause: stringOr(body['cause'] ?? body['detail'], `${name} failed with ${status}`),
     fix: stringOr(body['fix'], `x actions describe ${name} --json`),
     // RFC-9457's `type` IS a documentation URI, so a server that sends no `docs` extension has
     // still offered one. Both travel, in preference order: `??` picked `docs` on presence alone,

package/src/errors.ts

@@ -9,6 +9,7 @@ import {
   ERROR_DOCS_URL,
   hasErrorCode,
   registerErrorCodes,
+  retryForStatus,
   UltimateError,
 } from '@ultimat3/core';
 import type { SurfaceDenial } from '@ultimat3/policy';
@@ -280,6 +281,11 @@ export class RemoteActionError extends UltimateError {
       cause: failure.cause,
       fix: failure.fix,
       docs: remoteDocs(failure.code, failure.docs),
+      // The status is what says "send it again", and only where nobody has classified the code
+      // this build may never have heard of. `UltimateError` otherwise fills `retry` from
+      // `retryFor(code)`, which fails closed — so a 503 out of a typed call announced itself as
+      // `terminal` on the one field the framework promises a client never has to infer.
+      retry: retryForStatus(failure.code, failure.status),
       meta: { origin: 'remote', action: failure.action, status: failure.status },
     });
     this.status = failure.status;
@@ -293,6 +299,7 @@ export class RpcFailedError extends UltimateError {
       code: 'X_RPC_FAILED',
       cause: `${name} returned HTTP ${status} without a problem+json body`,
       fix: `check the gateway in front of the app, then: x actions describe ${name} --json`,
+      retry: retryForStatus('X_RPC_FAILED', status),
     });
   }
 }

package/src/http.ts

@@ -26,11 +26,15 @@ import {
   toOperationId,
 } from './naming';
 import { admitsAnonymous, policyCapability } from './policy-gate';
+import { IDEMPOTENCY_HEADER } from './wire-headers';
+
+/**
+ * Re-exported, never re-declared. The two strings moved to `wire-headers.ts` so `client.ts` can
+ * name them without pulling this file's server graph into a browser bundle; every importer of
+ * `./http` still reads them from here, which is what kept the move from touching a call site.
+ */
+export { BUILD_ID_HEADER, IDEMPOTENCY_HEADER } from './wire-headers';
 
-/** Matches `HttpConfig.buildIdHeader`; the pipeline reads it into `ctx.clientBuildId` — the
- * CLIENT's claim, never `ctx.buildId`, which is the build this process serves. */
-export const BUILD_ID_HEADER = 'x-ultimate-build';
-export const IDEMPOTENCY_HEADER = 'idempotency-key';
 export const REPLAYED_HEADER = 'x-ultimate-replayed';
 
 /**

package/src/index.ts

@@ -7,6 +7,32 @@
  * framework died; there is exactly one here, 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/query`, 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';
 /**
  * `toBucket` is `@ultimat3/http`'s — http owns `Bucket` and the limiter maths, and `action` and
  * `query` are the same tier, so a copy in either is a second answer for the other. Re-exported

package/src/stable.ts

@@ -9,11 +9,14 @@
  * published. Ordinary payloads are byte-identical between the two; `stable.test.ts` pins that.
  */
 
-export type JsonObject = Record<string, unknown>;
+/**
+ * `@ultimat3/core`'s, re-exported so `./stable` stays this package's one import path for the JSON
+ * helpers. It was declared here AND identically in `@ultimat3/query`'s own `stable.ts`, which is
+ * the duplication `client-wire.ts` moving to tier 0 made unnecessary.
+ */
+export { isJsonObject } from '@ultimat3/core';
 
-export function isJsonObject(value: unknown): value is JsonObject {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
+export type JsonObject = Record<string, unknown>;
 
 /** JSON with object keys sorted at every depth. No timestamps, no insertion-order leaks. */
 export function stableStringify(value: unknown, indent = 0): string {

package/src/wire-headers.ts

@@ -0,0 +1,17 @@
+/**
+ * The two request headers the typed client and the HTTP projection both name. Their own module and
+ * not `http.ts`'s, because `client.ts` needs exactly these two strings: importing them from there
+ * dragged `@ultimat3/http`, `@ultimat3/cache`, `@ultimat3/policy` and the whole `invoke` runtime
+ * into every browser bundle that called `rpc()` — 42,204 B against the read client's 11,977 B,
+ * measured, which is why two islands in this repo write a bare `fetch` instead of importing one.
+ */
+
+/**
+ * Matches `HttpConfig.buildIdHeader`; the pipeline reads it into `ctx.clientBuildId` — the
+ * CLIENT's claim, never `ctx.buildId`, which is the build this process serves. A mismatch the
+ * client sees on the way back is `X_CONTRACT_DRIFT`.
+ */
+export const BUILD_ID_HEADER = 'x-ultimate-build';
+
+/** RFC 9110's spelling, lower-cased, as `Headers` normalises it. */
+export const IDEMPOTENCY_HEADER = 'idempotency-key';