@ultimat3/core 29.4.0 → 30.0.0

package/CLAUDE.md

@@ -7,7 +7,7 @@ change to every package.
 | Rule | |
 |---|---|
 | Deps | `@ultimat3/schema` only (`bun-types`: types) |
-| Errors | subclass `UltimateError`; never `throw new Error` |
+| Errors | never `throw new Error`. A FRAMEWORK code: `bun run new-error-code` (a class, `CORE_CODE_TITLES` or the package's `errors.ts`, a `--status`/`--off-socket` decision, a wiki row). An APP code: `defineError()` (`define-error.ts`), which registers title, status and retry in one call and needs no wiki row; its own module, so an `UltimateError`-only chunk never retains it (`define-error-bytes.test.ts`) |
 | Values in a message | `renderCauseValue()` / `renderFixLiteral()`; never raw `JSON.stringify`, `String()` or `${…}` on an `unknown` |
 | A value in a `fix:` a shell READS | `renderFixShellArg(value, placeholder)` — `renderFixLiteral`'s double quotes leave `$(…)`, `` ` `` and `${…}` live. An ordinary path or URL passes through; anything a shell would read becomes the placeholder |
 | Whether that value TRAVELS | `isFixShellSafe(value)`, the predicate `renderFixShellArg` is built on. A placeholder is not a runnable command, so a `fix:` whose value sits mid-command asks this first and emits PROSE when the answer is no (`@ultimat3/auth`'s `jwks.ts`, `@ultimat3/scraping`'s `profileLocked`) |
@@ -19,7 +19,7 @@ change to every package.
 | Time | take a `Clock`; `Date.now()` / `new Date()` only inside `clock.ts` |
 | Context | never thread `ctx` as a parameter — `useContext()` |
 | A value ambient across an `await` | `asyncContext<T>(subject)` from `async-context.ts`, in **every** package — never `new AsyncLocalStorage` |
-| Exports | explicit in `src/index.ts`; no `export *`. ONE subpath, `@ultimat3/core/page` (`src/page.ts`): the page handle, the principal fence and the page's shared names, because any barrel import retains the error registry (~7.6 kB). `page-bundle.test.ts` pins the retained module set and a 1.5 kB ceiling; nothing that constructs an error may join it. `src/exports/` groups three subjects; every name is still written out in `index.ts` |
+| Exports | explicit in `src/index.ts`; no `export *`. FIVE public subpaths (`./page`, `./outbound`, `./redis`, `./render-node`, `./render-nodes`), one INTERNAL (`./internal/error-status`); nothing that constructs an error joins `./page` (`page-bundle.test.ts`, 1.5 kB). Full rule: `docs/history/core.md` |
 | Files | < 200 LOC, 500 hard ceiling, one responsibility, `kebab-case.ts`, test beside source |
 | Type claims | `type-pins.ts`, never a `.test.ts` — `tsconfig.json` excludes tests |
 
@@ -59,23 +59,28 @@ top-level `UltimateError` use in `error-codes.ts`.
 | Concept | Owner | Note |
 |---|---|---|
 | which deploy this is | `environment.ts` (`ULTIMATE_ENV`) | the twin of `ROLE`; never a second env var |
-| one-home helpers | `store-mode` `html-escape` `cookie` `fnv1a` `pg-executor` `deprecation` `aws-sigv4` | never copied (`X_HELPER_COPY`) |
+| one-home helpers | `store-mode` `html-escape` `cookie` `fnv1a` `pg-executor` `deprecation` `aws-sigv4` | never copied (`X_HELPER_COPY`). Full rule: `docs/history/core.md` |
+| the ONE keyed hash | `hmac.ts` (`hmac(alg, key, data, encoding?)`) | `node:crypto`'s `createHmac`: a keyed `Bun.CryptoHasher` throws a stale failed-EC-import error (Bun 1.4.4). `bun run keyed-hasher` (`X_KEYED_HASHER`). Full rule: `docs/history/core.md` |
 | what this process does | `roles.ts` (`ROLE`) | |
 | how a route renders, caches offline and hydrates | `route-vocabulary.ts` (`RENDER_MODES`, `OFFLINE_STRATEGIES`, `HYDRATE_STRATEGIES`) | every union is `(typeof ARRAY)[number]`, pinned in `type-pins.ts`; `scripts/render-modes.test.ts` refuses a second declaration. Re-export it, never restate it |
-| which of two route patterns wins a pathname | `route-rank.ts` (`routeRank`) | the request router's order as one integer: segment by segment, literal 3 > `:param` 2 > `*catch-all` 1, ENDED 4, packed base 5 over 22 segments. Read by `@ultimat3/render`'s `compilePattern` and `@ultimat3/pwa`'s rule order — both tier 4, so the one copy lives here. `@ultimat3/http`'s trie encodes the same order by its walk, not by this number. Never a sum: 100/10/1 ranked `/:a/b/c` above `/a/:x/:y` |
+| which of two route patterns wins a pathname | `route-rank.ts` (`routeRank`) | the request router's order as one integer: segment by segment, literal 3 > `:param` 2 > `*catch-all` 1, ENDED 4, packed base 5 over 22 segments. Full rule: `docs/history/core.md` |
+| an `http.path` template (`/orders/:id`) | `route-path-template.ts` (pure, also on `./page`) + `route-path-merge.ts` (`mergePathParams`, `X_HTTP_PATH_INPUT_CONFLICT`) | `action` and `query` both pin one and share a tier; never a copy in either |
+| `errors:` | `declared-errors.ts`, `-openapi.ts`, `-scan.ts` | ONE copy for `action` and `query`. The HTTP status is passed in (`ErrorStatusOf`): http is above core. The scan is test-time only |
+| a session's loss, an island's poll | `session-lost.ts` (`noteRefusal`, called by `client-dispatch.ts`; a cell on the page handle, cleared by `rescope()`), `visible-interval.ts` (the ONE poll an island takes) | both on `./page`, pinned by `page-bundle.test.ts` |
 | which rungs a cache ladder has | `cache-vocabulary.ts` (`CACHE_TIERS`) | `@ultimat3/cache`'s read order, imported (no `TIER_ORDER` alias). `isr` is a `RenderMode`, never a tier |
 | which build of the APP this is | `app-version.ts` (`APP_VERSION`) | one reader, `dev` by default |
 | the values | `env.ts` | `checkEnv().values` holds REAL secrets — printing goes through `maskedEnvValues()` |
 | `.env.example` | `env-example.ts` | a projection of the schema, never hand-maintained |
 | loading `.env` | **Bun**, not us | `envFileCandidates()` documents the measured order; there is no `.env.staging` |
-| how long to wait, and whether to wait at all | `backoff.ts` + `retry.ts` | one curve, one executor; `jitter` is REQUIRED on a retry policy and defaults to `none` on the arithmetic. `attempt` is 1-based |
-| N callers on one key | `single-flight.ts` | identity-checked eviction, optional injected deadline |
+| how long to wait, and whether to wait at all | `backoff.ts` + `retry-loop.ts` + `retry.ts` | one curve, one loop (no context, for `client-flight.ts`), one executor over it that reads the ambient signal and deadline: the ONE place a loop meets its caller's lifetime, `runToCompletion` the one way out; `jitter` is REQUIRED on a retry policy and defaults to `none` on the arithmetic. `attempt` is 1-based |
+| N callers on one key | `single-flight.ts` | identity-checked eviction, optional injected deadline, optional injected `signal`: a live joiner re-leads after its leader's abort. Reads no context |
 | how many at once | `flight-gate.ts` | hand-over on release, refusal past `maxQueued`, injectable `overflow:` refusal |
 | whether an answer still applies | `generation-fence.ts` | `X_SUPERSEDED` / `isSuperseded` |
 | which HTTP statuses are worth repeating | `retryable-status.ts` | `>= 500` plus 408, 409, 425, 429 |
 | how long this request has left | `request-budget.ts` (`Ctx.deadlineAt`, `REQUEST_TIMEOUT_HEADER`) | `@ultimat3/http`'s `startDeadline` is the one writer of the instant; `traceHeaders()` the one writer of the header. A spent budget sends nothing, never `0` |
 | the above, composed into one typed-client call | `client-flight.ts` + `client-wire.ts` | shared by `@ultimat3/action` and `@ultimat3/query` (both tier 3), re-exported by both. Declares no code of its own. A gate slot per ATTEMPT; the wait holds none, ends on `bump()` or the caller's abort |
-| the browser's one HTTP function, records envelope, per-tab handle and principal fence | `client-transport.ts`, `client-dispatch.ts`, `client-problem.ts`, `client-retry-after.ts`, `client-paths.ts`, `record-envelope.ts`, `record-sink.ts`, `client-scope.ts` | `pageClient()` is the ONE `globalThis` write (`Symbol.for('ultimate.client')`); the scope's listeners live ON the handle. `clientTransport` never value-imports `clientFlight` or `traceHeaders()`: trace/budget headers reach it through the page handle's OUTBOUND SLOT (`outbound-headers.ts`). `isSuperseded` answers both `X_SUPERSEDED` and `X_CLIENT_SCOPE_CHANGED`. The fence never `bump()`s a caller's flight. A write never dedupes; a read dedupes only with a caller's `flight`. `pageClient()` reads `<meta name="ultimate-scope">` (`CLIENT_SCOPE_META`) once: content = principal, empty = anonymous (`null`), absent = UNSCOPED (`undefined`, nothing persisted). `actionPath(name)` with no `style` reads the document's `<meta name="ultimate-path-style">` (`renderedActionPathStyle()`; `CLIENT_PATH_STYLE_META` in `page-meta.ts`) and falls back to `'resource'`. A refusal's `Retry-After` and body `title` are read HERE (`client-retry-after.ts`, `remoteTitleOf`). Bytes: `page-bundle.test.ts`; `rpc`'s and `queryClient`'s in `action`'s and `query`'s CLAUDE.md |
+| a stream-declaring action, read in the browser | `client-stream.ts` | `clientStream`: `POST` with `accept: text/event-stream` through `client-dispatch.ts`'s `dispatchStream` (the ONE browser `fetch`; body handed back unread), never `EventSource` (cannot POST, skips the credentials rule); `clientTransport`'s credentials, headers, caller's signal, session fence and problem decode; a `chunk` frame yields, `done` returns, `error` throws its problem at its own status. A JSON answer is `clientTransport`'s `settleAnswer` (envelope, records, dates), so `stream()` and `call()` agree. Never retried |
+| the browser's one HTTP function, records envelope, per-tab handle and principal fence | `client-transport.ts`, `client-dispatch.ts`, `client-problem.ts`, `client-retry-after.ts`, `client-paths.ts`, `record-envelope.ts`, `record-sink.ts`, `client-scope.ts` | `pageClient()` is the ONE `globalThis` write (`Symbol.for('ultimate.client')`); `clientTransport` never value-imports `clientFlight` or `traceHeaders()` (the OUTBOUND SLOT, `outbound-headers.ts`). A write never dedupes. Full rule: `docs/history/core.md` |
 | a write's public name | `write-digest.ts` (`writeDigest`, `isWriteDigest`, also on `./page`) + `write-origin.ts` (`withWriteOrigin`, `currentWriteOrigin`, `WRITE_ORIGIN_WAL_PREFIX`, server-only) | SHA-256 of an idempotency key, 32 hex; carried action → entity → WAL → realtime `records` frame. A malformed value runs the work unnamed: a label, never a gate |
 | which row survives a conflict | `conflict-policy.ts` (`ConflictPolicy`, `resolveConflict`, `Row`) | read by `action`'s mutator and `realtime`'s rebase |
 | where a visitor's light/dark choice is stored | `theme-storage.ts` (`THEME_STORAGE_KEY`, also on `./page`) | render's boot script reads it, ui's toggle writes it — both tier 4, so the one literal lives here. Persisted in browsers: never respelled |
@@ -85,32 +90,23 @@ top-level `UltimateError` use in `error-codes.ts`.
 | may a caller read this 5xx `cause`? | `public-cause.ts` (`hasPublicCause`) | one table for http, mcp, ai. `registerPublicCause` is `@ultimat3/http`'s `registerProblemMeta` writing it — never an app's door |
 | is this field a credential? | `logger.ts` (`isRedactedKey`) | exact keys + `CREDENTIAL_NAME`; a bare `token` suffix is NOT one (`idempotencyToken`, `maxTokens`). Log line, monitor envelope and `action`'s audit ask it |
 | a value that must not be printed | `secret.ts` | redacted by VALUE; `revealSecret()` is the one, greppable, way out |
-| an `Intl` formatter cache, and the screen in front of it | `intl-cache.ts` (`cachedFormatter`, `canonicalLocale`, `assertLocale`, `MAX_CACHED_FORMATTERS`, `MAX_LOCALE_EXCERPT`) | a locale arrives from a header: refuse a non-tag (`X_LOCALE_INVALID`), key canonically AND bound the cache — never a copy of any of the three. The cause quotes at most `MAX_LOCALE_EXCERPT` (35) code points; the whole tag rides in `meta.locale` |
+| an `Intl` formatter cache, and the screen in front of it | `intl-cache.ts` (`cachedFormatter`, `canonicalLocale`, `assertLocale`, `MAX_CACHED_FORMATTERS`, `MAX_LOCALE_EXCERPT`) | a locale arrives from a header: refuse a non-tag (`X_LOCALE_INVALID`), key canonically AND bound the cache — never a copy of any of the three. |
 | the text direction of a locale | `locale-direction.ts` (`directionOf`, `isRtl`, `Direction`) | import from here, never `@ultimat3/i18n`; here so `@ultimat3/ui` skips the i18n barrel |
 | the committed encrypted values | `secrets.ts` (envelope) + `secrets-store.ts` (files, `installSecrets`) | plaintext is a flat map of ENV NAMES; there is no `secrets.get()` |
 | ONE sealed value | `seal.ts` (`seal`, `open`, `openText`, `sealAll`) + `seal-keys.ts` (the ring) + `seal-errors.ts` | the framework's one AES call above the envelope: `entity`'s sealed column and `scraping`'s stored session call it, never WebCrypto. `purpose` is required and is AAD |
+| one outbound HTTP call | `outbound.ts` + `outbound-attempt.ts` / `-hops.ts` / `-read.ts` / `-dial.ts` / `-errors.ts` / `-types.ts`, entry `outbound-subpath.ts` | never on the barrel (`outbound-subpath.test.ts`). `retry()` owns the clamp to `ctx`, so no second clamp. Its ten codes register their retry class in `outbound-errors.ts`, NOT `error-retry.ts`'s table, which rides every page. `screenDial` holds the framework's one `Bun.dns.lookup` |
+| is a dependency down | `breaker.ts` | the machine only; the trigger is `classify` or a hand-called `failed()`. Every settle takes the `admit()` ticket. `X_BREAKER_OPEN` registers its class here |
+| what an element carries, for a test | `render-nodes.ts` (`renderNodes`, `nodesOf`, selectors) + `render-node.ts` (`JSX_NODE`, `ISLAND_NODE`, `HOLE_NODE`) | the one walker: `ui`, `admin` and apps import the subpath, never a copy. Islands and holes are branded ARRAYS, tested before `Array.isArray`; a hole is walked as `fallback` and `error`, never its deferred `children` |
 
 - **`installSecrets()` is the ONLY path from `secrets.enc.json` to an app value**, landing in
   `process.env` before `defineEnv` reads it. The real environment always wins.
 - **`intl-cache.ts`'s bound and canonical key are two halves of one rule** and live in one file:
   validating and keying are one `getCanonicalLocales` call. Never build an `Intl` formatter on a
   caller string without both.
-- **`secrets-errors.ts`'s command lines are screened**: paths through `renderFixShellArg`; a
-  variable name must match `/^[A-Z_][A-Z0-9_]*$/` or the line degrades to prose;
-  `X_SECRETS_KEY_MISMATCH`'s command carries no key id (it is read from a file). Its seven codes
-  register through `registerErrorCodes()`, so `resetErrorCodes()` drops them — take
-  `errorCodeSnapshot()` first. The envelope's `kid` lets *wrong key* and *edited file* be two codes.
-- **`seal.ts` adds no variable for the CURRENT key** — `findMasterKey()`, the same call
-  `installSecrets()` makes. Retired keys are `ULTIMATE_SECRETS_RETIRED_KEYS`, written into
-  `secrets.enc.json` by `x secrets rotate`; the ring memo is keyed by its source strings, never by
-  time. Constants, `parseMasterKey`, `masterKeyId`, `importKey` and the base64 codec are
-  `secrets.ts`'s — no second set. `seal-errors.ts` runs nothing at import: its titles are in
-  `CORE_CODE_TITLES` and its retry class in `CORE_ERROR_RETRY`, so it is no `sideEffects` anchor.
-  The wire form `x1.<keyId>.<iv>.<ciphertext+tag>` and the AAD string are persisted data: a change
-  is `x2`, never an edit.
+- **`secrets-errors.ts`'s command lines are screened** (`renderFixShellArg`; a bad variable name degrades to prose). Full rule: `docs/history/core.md`.
+- **`seal.ts` adds no variable for the CURRENT key** (`findMasterKey()`). The wire form `x1.<keyId>.<iv>.<ciphertext+tag>` and the AAD string are persisted data: a change is `x2`, never an edit. Full rule: `docs/history/core.md`.
 - **`schema-error-codes.ts` registers `@ultimat3/schema`'s codes** (schema cannot call core), and
   derives their retry classification from the same set. It is a `SIDE_EFFECTS_ANCHORS` entry.
-- `timing-safe-equal.ts` is the one constant-time comparison (`auth`, `storage`).
 - **`canonical-json.ts`: `canonicalJson` is INJECTIVE and `fingerprint` is SHA-256/16 of it** — the
   hash every in-memory sharing key is taken over (`query`'s `queryHash`, `realtime`'s `qid`).
   `NaN`, `±Infinity` and `-0` are bare tokens; `Date`, `Map` and `Set` are TAGGED. Never a
@@ -121,26 +117,14 @@ top-level `UltimateError` use in `error-codes.ts`.
 - **`decimal-order.ts`'s `compareDecimalText` answers `undefined` for a non-decimal**, and only a
   caller that knows the column's kind may ask (`@ultimat3/entity`'s `compareByKind`) — never
   `@ultimat3/query`, whose `OrderKey` has no kind.
-- **`format-bytes.ts`: one `formatBytes(bytes)`, 1024-base, `b|kb|mb|gb`** for byte counts in error
-  messages. Not `@ultimat3/ui`'s locale-formatted decimal one. Unmechanised: review catches a third.
-- **The flight layer** (`backoff.ts`, `retry.ts`, `single-flight.ts`, `flight-gate.ts`,
+- **The flight layer** (`backoff.ts`, `retry-loop.ts`, `retry.ts`, `single-flight.ts`, `flight-gate.ts`,
   `generation-fence.ts`, `retryable-status.ts`, `client-flight.ts`, `client-wire.ts`) imports
   nothing but this package, runs nothing at import, and injects every source of non-determinism
   (roll, sleep, clock, timer). `classifyThrown` / `statedDelayMs` live beside `error-retry.ts`'s table.
-- **`backoffDelay` REFUSES a non-finite bound**: `attempt`, `base`, `max` and `factor` go through
-  `finiteOption` before the clamps. The trailing `return 0` is reachable only by `factor` overflow.
-  It clamps to `max` **before** jitter.
 - **`finiteOption` / `finiteCount` (`finite-option.ts`) are the framework's ONE screen for a numeric
   option.** `finiteCount(subject, option, value, min)` takes `min: 0 | 1` because only the caller
   knows what zero means. `bun run finite-bounds` recognises a repair by the call's shape, so a
   package screen carries `Finite` in its name.
-- **`flightGate` HANDS its slot to a waiter** rather than releasing it. `X_FLIGHT_GATE_OVERLOADED`
-  is core's own code (tier 0 cannot borrow http's `X_OVERLOADED`); `overflow:` lets a caller throw its own.
-- **`client-flight.ts` INVERTS `retryDecision`'s unclassified default** through its `transient:`
-  predicate: a bare `TypeError` (dead network) and an `AbortError` (the caller's cancellation) are
-  indistinguishable by class. Never "simplify" it back.
-- **`ClientFlight` stays `import type`-only in `action`'s and `query`'s `client.ts`** — a value import
-  pulls the whole flight layer into every caller's chunk.
 - **`mcp-exposure.ts`'s `isMcpExposed` is the ONE answer to "did this opt into MCP?"**, read by
   `action`, `query`, `mcp`, `ai`, `manifest`. `@ultimat3/cli`'s `mcp-exposure-pin.test.ts` checks
   it; `@ultimat3/admin`'s own catalog is the one opt-OUT exception (`mcp-tools.ts`).
@@ -160,6 +144,7 @@ server-only, never on `page.ts`. One call site per recorder; a second is the bug
 | `recordQueueDepth` | `@ultimat3/jobs` `worker.ts`, throttled inside `tick()` |
 | `recordJob` | `@ultimat3/jobs` `worker.ts`, the outcome branch inside `tick()` (`JOB_OUTCOME_LABELS` drops `suspended`) |
 | `recordLeaseLost` | `@ultimat3/jobs` `heartbeat.ts`, once per lapsed lease |
+| `recordBreakerTransition` | `breaker.ts`, on every state change |
 
 - Tracing is three files: `telemetry.ts` builds spans, `sampler.ts` decides, `otlp*.ts` exports.
   `span.end()` returns early when `traceFlags & 1` is 0. The default sampler reads
@@ -169,45 +154,42 @@ server-only, never on `page.ts`. One call site per recorder; a second is the bug
 - The OTLP exporters are built, not wrapped ([`docs/idea/18-build-vs-wrap.md`](../../docs/idea/18-build-vs-wrap.md)).
   `otlpTraceRequest` / `otlpMetricsRequest` are pure. **gRPC (`:4317`) is out of scope**:
   `X_OTLP_PROTOCOL_UNSUPPORTED` names `:4318`; a boot that must not throw asks `tryOtlpEndpoint(signal)`.
+- **`postOtlp` (`otlp-post.ts`) retries `OTLP_RETRY_STATUSES` and a transport failure only**, never `isRetryableStatus`. Full rule: `docs/history/core.md`.
+- **`errorFingerprint` (`error-fingerprint.ts`) is a function, never an `ErrorReport` field**:
+  `code`, `source`, `scope.operation`, plus the top app frame for `X_INTERNAL` only. Never `cause`,
+  `meta`, ids or `release`. Total over hostile getters; the Sentry envelope's `fingerprint`.
+- **Failure capture is OFF by default** (`config-failure-capture.ts`, `failureCapture.enabled`;
+  `x dev` forces it on): with no `FailureStore` installed nothing allocates. The OUTER
+  `invoke`/`runQuery` opens one buffer (`withFailureCapture`, `failure-capture.ts`); seams record
+  into it (`recordFailureFact`: entity reads, flag answers), masked and path-listed by
+  `captureValue` (`failure-capture-mask.ts`). A 5xx HOLDS the buffer on the thrown value, a 4xx
+  never; `reportError` releases it keyed by `errorFingerprint` over the same report
+  (`failure-capture-flush.ts`). Caps: `perHour` 5 per fingerprint per process, `maxRows` 50,
+  `maxBytes` 64 KiB — past one, stored `truncated`. A refused save is a log line, never awaited.
 - **Three OTLP variables, three codes** — `X_OTLP_ENDPOINT_INVALID`, `X_OTLP_HEADERS_INVALID`,
   `X_OTLP_PROTOCOL_UNSUPPORTED`. A header KEY is in the cause/fix/meta; its VALUE never is.
-- `error-reporter.ts`: `ErrorReporter`, no-op default, memory reporter for tests, Sentry transport
-  (`error-reporter-sentry.ts`, optional export). `reportError` never throws, never awaits. Callers:
-  `@ultimat3/http` `stages.ts` (`status >= 500`), `@ultimat3/jobs` `execute.ts`, `@ultimat3/realtime`
-  `sync-node.ts` and `sync-upgrade.ts`, `@ultimat3/flags` `runtime.ts`. `configureErrorReporting({
-  release })` takes the build id `serve.ts` computed. Trace and span resolve as a PAIR.
+- `error-reporter.ts`: `ErrorReporter`, no-op default, memory reporter for tests, Sentry transport (`error-reporter-sentry.ts`, optional export). Full rule: `docs/history/core.md`. `'browser'`: only cli's `client-errors-routes.ts`, one `X_CLIENT_ERROR` per report.
 - `METRICS_PATH` is served by `@ultimat3/cli`'s `metrics-endpoint.ts` on `METRICS_PORT` (9090), never
   the role's HTTP port; every role opens it.
 
 ## Lifecycle and readiness
 
-- `markReady()` means **bound**; readiness means **usable** — `registerReadinessCheck(name, check)`.
-  `/readyz` is ready when the state is `ready` AND every check passes. `HealthReport.registered` is
-  the count (an empty registry is still `ready`, deliberately). `readinessChecks()` builds through
-  `Object.fromEntries` (a check named `__proto__`). Checks are **synchronous**; liveness ignores
-  them. The registration returns its unregister; `readinessCheckCount()` is the leak probe.
+- `markReady()` means **bound**; readiness means **usable** — `registerReadinessCheck(name, check)`. Full rule: `docs/history/core.md`.
 - **`drain()`'s memo is published BEFORE the first hook runs** — a hook may re-enter `drain()`
   (`@ultimat3/http`'s `handle.stop()`), and `settleWithin` invokes hooks synchronously.
-- **The drain deadline is enforced**: `runPhase` races each hook against the time left before
-  `deadlineAt` (`lifecycle-deadline.ts`'s `settleWithin`) and ABANDONS an overrun, logging it
-  (`X_SHUTDOWN_TIMEOUT`, whose `fix:` names `configureLifecycle({ deadlineMs })`). The budget is the
-  WHOLE drain's; `DEFAULT_DEADLINE_MS` (25 s) always applies; it is real monotonic time
-  (`systemClock`), never the injected `clock`. `drainDeadlineMs()` is the one decision point.
-  `settleWithin` attaches a rejection handler unconditionally.
+- **The drain deadline is enforced** (`lifecycle-deadline.ts`): a hook overrunning the whole drain's budget is abandoned and logged (`X_SHUTDOWN_TIMEOUT`); real monotonic time, never the injected `clock`. Full rule: `docs/history/core.md`.
+- **`close` hooks run last-registered first; the other phases as registered** (`runPhase`). No fourth phase.
 - **Who a health endpoint tells what is ONE rule, here** (`health-disclosure.ts`): `healthBody` +
   `healthPeerListed`, called by http and by realtime's sync listener. Never a second copy.
-- **A readiness grace runs before the `accept` phase** (`lifecycle-grace.ts`): `/readyz` answers 503
-  with the socket still open for `drain.readinessGraceMs`, ADDED to `deadlineMs` (a chart's
-  `terminationGracePeriodSeconds` must exceed the sum — 5 s + 25 s by default). Unset: 0 in
-  development/test, 5000 everywhere else including a process naming no environment (fail closed).
+- **An address answers two questions** (`address-class.ts`): `classifyAddress` is where a DIAL lands
+  and reads through every embedded IPv4; `peerAddressClass` is what a CALLER or a local name may be
+  trusted as, and a transit form (`2002:7f00:1::`, `64:ff9b::7f00:1`) is never loopback there. A
+  check that grants something asks the second. Unmechanised: review catches a new `=== 'loopback'`.
+- **A readiness grace runs before the `accept` phase** (`lifecycle-grace.ts`), ADDED to `deadlineMs`. Full rule: `docs/history/core.md`.
+- **`abandonment()`: a branded abort reason refuses writes** (`@ultimat3/db`); **`runToCompletion(fn)` is the one escape**, built by `derivedContext`. `run-to-completion.test.ts`.
 - `impersonate(actor, reason, fn)` is the ONE door through `withChildContext({ actor })`; it stamps
   `Actor.onBehalfOf` so `actorLabel` renders `service:eng-7→user:cust-99@org-3`. No second path.
-- Every `UltimateError` carries `retry` (`terminal | retryable | retry-after`), **defaulting to
-  `terminal`**. `registerErrorRetry()` is the one registration path and refuses to reclassify a
-  core code. Two readers: `retryFor(code)` (what to do, fails closed) and
-  `declaredErrorRetry(code)` (what was declared, `undefined` otherwise) — a caller deciding whether
-  to STOP work in flight (`@ultimat3/jobs`' executor) reads the second. An instance `retry` on an
-  unregistered code reads as unclassified.
+- Every `UltimateError` carries `retry` (`terminal | retryable | retry-after`), **defaulting to `terminal`**. Full rule: `docs/history/core.md`.
 - `PRIMITIVE_KINDS` is the executable eight-primitive rule; `PrimitiveKind` derives from it and
   `registrar.test.ts` fails on a ninth. `PRIMITIVE_FACTORIES` lists the factories.
 
@@ -219,25 +201,7 @@ bun run typecheck
 The root is load-bearing: Bun reads `bunfig.toml` (its preload installs `@ultimat3/testing`'s
 matchers) from the cwd.
 
-Gotchas:
-- `exactOptionalPropertyTypes` is on — declare optional fields as `x?: T | undefined`.
-- `noPropertyAccessFromIndexSignature` is on — `ctx.services['mail']`, not `.mail`.
-- `Ctx` carries a string index signature so apps can augment `CtxServices`; the cost is that
-  `ctx.anything` type-checks as `unknown`. Deleting it is a breaking change, measured to compile
-  core clean; land it alone, with a full `bun run verify`.
-- **`Ctx extends CtxFacts, CtxServices`, and `ctxOf` holds the framework's ONE irreducible
-  `as Ctx`.** `CtxFacts` is what the framework sets (and what a `ServiceFactory` receives); an
-  augmentation's named members are required of every `Ctx`, and no framework function can obtain
-  them. `@ultimat3/http`'s `requestContext` composes `ctxOf()` and has no assertion.
-  Refused alternatives: the file header. The repair is a major, with the index-signature deletion.
-- Tests that touch the registry, the lifecycle or the listener table call `resetErrorCodes()` /
-  `resetLifecycle()` / `resetListeners()` — and a registry reset takes `errorCodeSnapshot()` first
-  and restores it in `afterAll`, or every earlier package's titles render humanised for the run.
-- `onShutdown`'s return value is the unregister, owned by every caller that can start twice
-  (`@ultimat3/http`'s `server.ts`, `@ultimat3/realtime`'s `listenSyncNode`, `@ultimat3/jobs`' worker,
-  `@ultimat3/cli`'s `hold.ts`). `shutdownHookCount()` is the leak probe.
-- Tests calling `configureCursorSigning()` restore the previous secret or call
-  `resetCursorSigning()`. The secret is read inside `sign()`, never at module scope; new secrets
-  follow the same call-time rule.
+Gotchas (`exactOptionalPropertyTypes`, `Ctx`'s index signature, registry resets, `onShutdown`'s unregister, cursor-secret restore): [`docs/history/core.md`](../../docs/history/core.md#moved-out-2026-11-03-plan-101-wave-3-the-claudemd-ceiling).
 
 Why each rule above is shaped the way it is: [`docs/history/core.md`](../../docs/history/core.md).
+- `drain-deadline.ts` also owns `WORKER_RETIRE_DEFAULT_MS` and `workerRetireIssue`.

package/README.md

@@ -3,12 +3,24 @@
 Tier 0. The foundation every other Ultimate package imports and none of them may bypass.
 Zero dependencies, zero `@ultimat3/*` imports.
 
+`bun add @ultimat3/core` · guide: [Configuration](https://github.com/developerz-ai/ultimate/wiki/Configuration)
+
+```ts
+import { secret } from '@ultimat3/core';
+
+const dsn = secret('postgres://app:hunter2@db/app', 'DATABASE_URL');
+JSON.stringify({ dsn }); // the value never prints: a Secret redacts by value, at any depth
+```
+
 | Owns | Module |
 |---|---|
 | `UltimateError`, the 3-line rendering, `--json` shape | `errors.ts` |
 | rendering an app's value into a `cause` / `fix` without throwing | `error-render.ts` |
 | a thrown value's stack, its `name: message` line restored when Bun dropped it — `failureStack` | `error-stack.ts` |
 | code → `{ title, docs }` registry, `registerErrorCodes()` | `error-codes.ts` |
+| an APP code's one declaration — title, HTTP status, retry and class — `defineError()` | `define-error.ts` |
+| an action's or a query's `errors:` — `checkDeclaredErrors` (the list), `judgeThrown` / `enforceDeclared` / `withDeclaredErrors` (a throw out of a handler; `X_ERROR_UNDECLARED` in test and dev, `undeclared_errors_total` in production), `describeDeclaredErrors` (a tool's description); the OpenAPI half `withDeclaredResponses`; the contract's source scan `scanHandlerSource` + `definedErrorClassCodes` (test-time). The status is passed in: `@ultimat3/http` is above this package | `declared-errors.ts`, `declared-errors-openapi.ts`, `declared-errors-scan.ts` |
+| the app's half of the HTTP status table, written by `defineError` and `@ultimat3/http`'s `registerErrorStatus` — internal, on `@ultimat3/core/internal/error-status` only | `error-status-declared.ts` |
 | the one lazy `AsyncLocalStorage`, every ambient scope in the framework | `async-context.ts` |
 | request context on that seam | `context.ts` |
 | `Actor` (`user \| service \| agent \| anonymous`) | `actor.ts` |
@@ -16,7 +28,8 @@ Zero dependencies, zero `@ultimat3/*` imports.
 | acting as another actor, with an origin and a reason | `impersonate.ts` |
 | is an error worth retrying? one classification per code | `error-retry.ts` |
 | how long to wait before the next attempt — one curve, one jitter table | `backoff.ts` |
-| the retry executor and the pure decision behind it | `retry.ts` |
+| the retry executor, bound to its caller's lifetime | `retry.ts` |
+| the retry loop and the pure decision behind it, no context | `retry-loop.ts` |
 | which HTTP statuses are worth repeating | `retryable-status.ts` |
 | N callers on one key are ONE run | `single-flight.ts` |
 | how many may run at once, and how many may wait | `flight-gate.ts` |
@@ -28,6 +41,8 @@ Zero dependencies, zero `@ultimat3/*` imports.
 | the records envelope an answer carries behind `x-ultimate-records: 1` | `record-envelope.ts` |
 | the per-tab page handle (`globalThis[Symbol.for('ultimate.client')]`) records land in | `record-sink.ts` |
 | which principal the page acts for, and the epoch that moves when it changes | `client-scope.ts` |
+| whether the page's session is lost — the first `X_UNAUTHENTICATED` / `X_SESSION_EXPIRED` on a page rendered for a principal, said once (`onSessionLost`, `sessionIsLost`), cleared by `rescope()`; on `./page` | `session-lost.ts` |
+| a poll a hidden tab and a lost session stop — `visibleInterval(run, ms, { maxMs? })`: no call while hidden, one when shown, a failed run doubling the wait up to `maxMs` (jittered) and a success resetting it, an idempotent disposer; on `./page` (6,045 B alone, `page-bundle.test.ts`) | `visible-interval.ts` |
 | which row survives a conflict — `server-wins`, `last-write-wins`, `custom` | `conflict-policy.ts` |
 | the four shapes an async region can be in | `async-state.ts` |
 | the audit seam `action` and `query` share — `AuditRecord` (`name`, `primitive`, `surface`, `outcome`, the parsed `input`; `action` is a deprecated alias of `name` until 25.0.0), `AuditSink`, the ONE installed sink (`setAuditSink` / `getAuditSink` / `resetAuditSink`, re-exported by `@ultimat3/action`), and `AUDIT_RECORD_FIELDS`, the field list both primitives' tests pin their records to | `audit.ts` |
@@ -49,6 +64,7 @@ Zero dependencies, zero `@ultimat3/*` imports.
 | the shape screens that run before any rule reads a value — section, list, boolean, closed set, path | `config-shape.ts` |
 | the keys a major deleted (`locales`, `defaultLocale`, `defaultTimeZone`, `defaultCurrency`, `theme.tokens` in 25.0.0; `jobs.driver`, deleted in 5.0.0 and refused since 25.0.0) — each REFUSED by name with `X_CONFIG_INVALID` and its replacement, never ignored | `config-removed.ts` |
 | the `pwa` block — what an install needs, and the boot refusal when it is not there | `config-pwa.ts` |
+| the `assets` block — `retain: { disk, builds }`, earlier builds' hashed files kept across a deploy (`AssetsConfig`, `AssetsRetainConfig`, `AssetsSection`, `AssetsSectionInput`) | `config-assets.ts` |
 | `isSameOriginPath(value)` — a path on THIS origin as a browser resolves it: refuses `//host`, `/\host`, a C0 control or DEL (`/\t/evil.example` parses to `//evil.example`) and a dot segment leaving a `//` pathname. The one predicate for every URL precached as an offline answer, `@ultimat3/pwa`'s build included | `config-pwa.ts` |
 | the closed route vocabulary every renderer names | `route-vocabulary.ts` |
 | which of two route patterns wins a pathname (`routeRank`) | `route-rank.ts` |
@@ -60,11 +76,13 @@ Zero dependencies, zero `@ultimat3/*` imports.
 | OTel-shaped spans, always on, no-op by default | `telemetry.ts` |
 | the sampling decision, and `OTEL_TRACES_SAMPLER*` | `sampler.ts` |
 | OTLP/HTTP JSON: endpoint, headers, value encoding | `otlp.ts` |
+| one OTLP POST, retried on the specification's transient answers | `otlp-post.ts` |
 | `SpanExporter` on the wire, batched | `otlp-span-exporter.ts` |
 | `MetricExporter` on the wire | `otlp-metric-exporter.ts` |
 | may a caller read this 5xx code's `cause`? `hasPublicCause(code)` — one predicate for the HTTP problem document, MCP error data and an agent `tool_result` | `public-cause.ts` |
 | `reportError` + the `ErrorReporter` seam, no-op by default | `error-reporter.ts` |
 | that seam on the wire, Sentry's envelope and DSN | `error-reporter-sentry.ts` |
+| which reports are one fault (`errorFingerprint`) | `error-fingerprint.ts` |
 | OTel-shaped counter / gauge / histogram, same seam | `metrics.ts` |
 | the `/metrics` scrape body | `metrics-text.ts` |
 | the series every process emits, incl. what the chart scales on | `runtime-metrics.ts` |
@@ -72,11 +90,11 @@ Zero dependencies, zero `@ultimat3/*` imports.
 | graceful drain, `/healthz`, `/readyz` | `lifecycle.ts` |
 | what a health endpoint tells whom — `healthBody(report, role, detailed)`, `healthPeerListed(peers, address)`, `DEFAULT_HEALTH_DETAIL_PEERS`; the one rule `@ultimat3/http` and the sync node's own listener both call | `health-disclosure.ts` |
 | the readiness grace between `/readyz` → 503 and the listener closing (`drain.readinessGraceMs`) | `lifecycle-grace.ts` |
-| the drain budget's default and domain (`drain.deadlineMs`, 25 s, 1–3600000 ms; the worker's optional `drain.workerDeadlineMs`, 1–86400000 ms) — `DRAIN_DEADLINE_DEFAULT_MS`, `DRAIN_DEADLINE_MAX_MS`, `WORKER_DRAIN_DEADLINE_MAX_MS` | `drain-deadline.ts` |
+| the drain budget's default and domain (`drain.deadlineMs`, 25 s, 1–3600000 ms; the worker's optional `drain.workerDeadlineMs`, 1–86400000 ms; its `drain.workerRetireMs`, an hour, 0–86400000 ms) — `DRAIN_DEADLINE_DEFAULT_MS`, `DRAIN_DEADLINE_MAX_MS`, `WORKER_DRAIN_DEADLINE_MAX_MS`, `WORKER_RETIRE_DEFAULT_MS` | `drain-deadline.ts` |
 | `jobs.concurrency`'s default and domain — one slot count for every queue a worker serves, or a table per queue (`{ banks: 4, 'banks-long': 2 }`; a queue the table does not name runs at the default). `JOBS_CONCURRENCY_DEFAULT` (8), `type JobsConcurrency` | `config-jobs.ts` |
 | SIGTERM/SIGINT → the one drain; on Windows also SIGHUP (console close) and SIGBREAK (Ctrl-Break) — `drainSignals(platform)` | `lifecycle-signals.ts` |
 | is this directory inside a `bun build --compile` binary? `isCompiledBundle(import.meta.dir)` — `/$bunfs/` and Windows' `B:\~BUN\` | `bunfs.ts` |
-| which network an IP literal belongs to — `classifyAddress`, for SSRF screens | `address-class.ts` |
+| which network an IP literal belongs to — `classifyAddress`, for SSRF screens; `peerAddressClass`, for a check that trusts a caller or a local name | `address-class.ts` |
 | the network a caller's address keys a per-caller budget on — `addressNetwork`: IPv4 exact, IPv4-mapped as IPv4, IPv6 as its /64 | `address-class.ts` |
 | the sockets this process opened, so a self-request is not egress | `listeners.ts` |
 | `defineService('orgs', …)` → `ctx.orgs`, rebuilt per actor | `service.ts` |
@@ -86,10 +104,10 @@ Zero dependencies, zero `@ultimat3/*` imports.
 | the one HTML character table — `escapeHtml`, text and attributes alike (`& < > " '`) | `html-escape.ts` |
 | the one `Cookie:` reader — `readCookie(header, name)`, `null` when absent, never a throw | `cookie.ts` |
 | the one `Set-Cookie` writer — `serializeSetCookie(name, value, options?)`; defaults `Path=/; HttpOnly; Secure; SameSite=Lax`, the value percent-encoded so `readCookie` returns it exactly, `X_COOKIE_INVALID` for a non-token name, a pair over 4096 octets, `SameSite=None`/`Partitioned` without `Secure`, a broken `__Secure-`/`__Host-` prefix rule, or an injectable `Path`/`Domain`. `Expires` is an IMF-fixdate in UTC | `cookie.ts` |
-| the one AWS Signature V4 signer — `signAwsRequest({ method, url, headers?, payload?, credentials, region, service, clock? })` → the URL, every header to send (`authorization`, `x-amz-date`, `x-amz-security-token`, `x-amz-content-sha256` by default on `s3`), the canonical request and string-to-sign. `payload`: `{ body }`, a pre-taken `{ sha256Hex }`, or `UNSIGNED_PAYLOAD`. S3 encodes the path once, every other service twice. Web Crypto, no SDK; proven on the aws-c-auth SigV4 suite and S3's worked examples. Shared by `storage`'s s3 disk and `mail`'s SES driver | `aws-sigv4.ts` |
+| the one AWS Signature V4 signer — `signAwsRequest({ method, url, headers?, payload?, credentials, region, service, clock? })` → the URL, every header to send (`authorization`, `x-amz-date`, `x-amz-security-token`, `x-amz-content-sha256` by default on `s3`), the canonical request and string-to-sign. `payload`: `{ body }`, a pre-taken `{ sha256Hex }`, or `UNSIGNED_PAYLOAD`. S3 encodes the path once, every other service twice. Web Crypto, no SDK; proven on the aws-c-auth SigV4 suite and S3's worked examples. Shared by `storage`'s s3 disk and `mail`'s SES driver. `presignAwsUrl({ method, url, expiresInSeconds, headers?, credentials, region, service, clock? })` is the same signature in the query, for a holder with no credentials: `headers` are signed, so a signed `content-length` binds a browser's PUT to that size. Equal to `Bun.S3Client`'s presign byte for byte where Bun can express it | `aws-sigv4.ts` |
 | 32-bit FNV-1a — a BUCKET (rollouts, factory seeds), never a sharing key (`fingerprint` is) | `fnv1a.ts` |
 | `PgExecutor` — the structural `query(text, values)` seam every Postgres store takes | `pg-executor.ts` |
-| a declared retirement as headers — `renderDeprecation` (RFC 9745 `Deprecation`, RFC 8594 `Sunset`, the `successor-version` link) and `recordDeprecatedCall` on the one `deprecated_calls_total`; `action` and `query` both project through it | `deprecation.ts` |
+| a declared retirement as headers — `renderDeprecation` (RFC 9745 `Deprecation`, RFC 8594 `Sunset`, the `successor-version` link, also `successorLink` / `successorPathOf` for a door that re-serves the route) and `recordDeprecatedCall` on the one `deprecated_calls_total`; `action` and `query` both project through it | `deprecation.ts` |
 
 Each of the five, and `fingerprint`, `storeMode` and render's `contentHash`, has ONE implementation:
 `bun run flight-copies` refuses a second by its shape (`X_HELPER_COPY`), whatever it is named.
@@ -147,6 +165,37 @@ Your package declares its own codes in `src/errors.ts` and registers them once:
 `registerErrorCodes({ X_DB_DRIFT: { title: 'schema differs from migrations' } })`.
 Registering a code twice throws `X_ERROR_CODE_DUPLICATE`.
 
+### An app's own codes: `defineError`
+
+A framework package registers codes as above, through `bun run new-error-code`. An APP declares
+each of its codes once, and gets the class back:
+
+```ts
+import { defineError } from '@ultimat3/core';
+
+export const PostNotFound = defineError<{ readonly ref: string }>({
+  code: 'X_POST_NOT_FOUND',
+  title: "no such post in the actor's organisation",
+  status: 404, // or offSocket: true, for a code no response carries — exactly one of the two
+  cause: (p) => `no post ${p.ref} in the actor's organisation`,
+  fix: 'x queries list --json, then pass an id the post read returns',
+});
+
+const error = new PostNotFound({ ref: 'hello' }, { sourceError: undefined });
+PostNotFound.is(error); // the brand plus the code, never `instanceof`
+```
+
+The one call registers the title (`registerErrorCodes`), the status (read by `@ultimat3/http`'s
+`statusFor`, framework table first, so no app declaration moves a framework code) and, when given,
+`retry` (`registerErrorRetry`). The same declaration twice is a no-op — a module re-evaluated
+under `x dev`; a different title or status is `X_ERROR_CODE_DUPLICATE`. A malformed one — both or
+neither of `status`/`offSocket`, a status outside 100-599, a code that is not `X_SCREAMING_SNAKE` —
+is `X_ERROR_DECLARATION_INVALID`. A code some package already registered — a framework code,
+under its own title or not — is `X_ERROR_CODE_DUPLICATE`: its status is not the app's to give. The
+table itself is INTERNAL (`@ultimat3/core/internal/error-status`, read by `@ultimat3/http`): an app
+declares through `defineError`, and a re-raised library code through `registerErrorStatus`. A
+scaffolded app's `guards/error-declared.ts` refuses a handwritten `UltimateError` subclass.
+
 `isUltimateError()` is duck-typed on `Symbol.for('ultimate.error')`, not `instanceof` — that is
 how `@ultimat3/schema` (tier 0, cannot import core) still produces matching errors.
 
@@ -236,6 +285,7 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | `SecretsPlaintextInvalidError` | `X_SECRETS_PLAINTEXT_INVALID` | `src/secrets-errors.ts` |
 | `SecretsTamperedError` | `X_SECRETS_TAMPERED` | `src/secrets-errors.ts` |
 | `UltimateError` | any registered code — every class in the framework extends it | `src/errors.ts` |
+| what `defineError()` returns | the code it declared — `.code`, `.status`, `.is()` | `src/define-error.ts` |
 
 ## Context
 
@@ -263,6 +313,24 @@ because it closes over the ctx (actor, clock, tz) it was built for. `withChildCo
 factory-managed name from what it carries forward on purpose: only an ad hoc service nobody
 registered survives an actor swap unrebuilt.
 
+`As of 2026-11-02`, a scope that was abandoned stops writing. `abandonment()` answers the ambient
+signal's reason when it was aborted with a coded one (the request deadline's `X_TIMEOUT`, a job's
+cancellation), the same object, and `undefined` for a client hang-up, which is uncoded: nobody was
+told anything. `@ultimat3/db` and `@ultimat3/entity` refuse on it. `runToCompletion(fn)` is the one
+escape: same request id and actor, a fresh signal, no deadline, managed services rebuilt over it.
+
+```ts
+import { runToCompletion } from '@ultimat3/core';
+import { withTransaction } from '@ultimat3/db';
+
+declare function recordCharge(): Promise<void>;
+
+await runToCompletion(() => withTransaction(() => recordCharge())); // lands, past the deadline
+```
+
+Nothing in that scope bounds `fn`: the caller owns a ceiling, as `withIdempotency` and `onSettled`
+do. Wrap the whole transaction, as above: a statement wrapped inside one still has its COMMIT refused.
+
 ## Actor facts — the app's own authz vocabulary, on the framework's actor
 
 Roles and an org id answer a columnar question ("same tenant?"). They cannot answer a relational
@@ -479,10 +547,13 @@ match with `sealAll()`; uniqueness cannot be held across keys.
   `tryOtlpEndpoint('traces')` answers `undefined` when nobody configured one, so a boot can skip
   the exporter instead of throwing. **gRPC (`:4317`) is out of scope** and says so with
   `X_OTLP_PROTOCOL_UNSUPPORTED`.
+- **A transient export is sent again** (`postOtlp`, `otlp-post.ts`): 429, 502, 503, 504 or a
+  transport failure, `OTLP_RETRY_STATUSES`, on core's retry loop (3 attempts, full jitter,
+  `Retry-After` honoured) inside `timeoutMs`, which is the whole export. One log line per batch.
 - Metrics are the same shape one signal over: `counter()`, `gauge()`, `histogram()`, aggregated
   in process, free until `configureMetrics({ exporter })`. See below.
 - `onShutdown(name, hook, { phase })` with phases `accept → inflight → close` under one
-  deadline; `readyzPayload()` flips to 503 the moment draining starts, `healthzPayload()` stays
+  deadline, `close` running last-registered first; `readyzPayload()` flips to 503 the moment draining starts, `healthzPayload()` stays
   200 until stopped. It **returns an unregister**, and a caller that starts and stops more than
   once has to keep it: a discarded one is a hook per `start()`, each retaining the resource it
   was going to drain, and the next drain runs every one of them against a torn-down copy.
@@ -547,7 +618,7 @@ process cannot drift apart:
 |---|---|---|
 | `rps` | `http_requests_total` | counter; `rps` is a **rate** the adapter derives (`rate(http_requests_total[1m])`), never a stored number |
 | `ws-connections` | `connections` | gauge, `+1`/`-1` |
-| `queue-depth` | `queue_depth` | gauge, by `queue` label |
+| `queue-demand` | `queue_demand` | gauge, by `queue` label, `@ultimat3/jobs`'s. `queue_depth` stays, for the backlog alert: it reads 0 while a fleet holds every job it has |
 
 `As of 2026-08` all three are emitted and scraped. One call site per package — `recordRequest`
 from `@ultimat3/http`'s pipeline, `recordConnection` from `@ultimat3/realtime`'s socket table,
@@ -591,8 +662,11 @@ reportError(failure, { source: 'http', severity: 'error', scope: { operation: 'P
 | `ErrorReport` | `code` `title` `cause` `fix` `docs` + `meta` `stack` `resource` `environment` `release` `scope`, and the thrown value under `error` |
 | `configureErrorReporting({ reporter, clock, release, environment, enabled })` | the one install point; `resetErrorReporting()` puts the no-op back |
 | Reporters | `noopErrorReporter` (default), `memoryErrorReporter()` (`.events`, `.reset()`), `sentryErrorReporter({ dsn, fetch?, clientName? })` |
+| Several at once | `chainErrorReporters(...reporters)` — one reporter handing each report to every member in order; a member that throws is logged and costs only itself; chains flatten, a member listed twice reports once, none is the no-op. `errorReportersOf(reporter)` reads the members back; `installedErrorReporter()` the one installed now. The container chains its `SENTRY_DSN` transport after what the app installed (`As of 2026-11`) |
 | Wire, testable alone | `parseSentryDsn(dsn)` → `{ publicKey, envelopeUrl, … }`, `sentryEnvelope(report, { dsn, eventId })` → the envelope body. Pure, exactly as `otlpTraceRequest` is |
 | `errorReport(error, options)` | the normalisation on its own, for a transport's test or a surface that enriches before sending |
+| `errorFingerprint(report)` | 16 hex, which reports are one fault: `code`, `source`, `scope.operation`, and for `X_INTERNAL` the top application frame (function and root-relative path, no line). Never `cause`, `meta`, an id or `release`. Total; the Sentry envelope sends it as `fingerprint` |
+| `setFailureStore(store)` / `withFailureCapture(primitive, name, statusOf, run)` / `recordFailureFact(fact)` | the 5xx bundle `x repro` replays (`failureCapture` in `app.config.ts`). No store, no buffer. A 5xx is held on the thrown value and stored at `reportError` under its `errorFingerprint`; masked input listed in `masked` |
 
 `As of 2026-08` four packages call `reportError`, seven call sites in all: `@ultimat3/http`'s
 `stages.ts` (`status >= 500` only), `@ultimat3/jobs`' `executeJob` — the one frame still holding the
@@ -626,7 +700,7 @@ never a silently wrong page.
 | Also keys | `keyedFingerprint(value, purpose)` — `h1:<key id>:<HMAC>` over `canonicalJson`, under a per-purpose key derived from this secret; the fingerprint to PERSIST (`@ultimat3/action`'s idempotency `requestHash`). `compareFingerprint` answers `match` / `mismatch` / `unverifiable` (other key), and still checks a legacy bare `fingerprint()` exactly. Rotating the secret makes in-window stored fingerprints `unverifiable` |
 | Signed, not encrypted | the client already has these rows; what it must not do is *invent* a position |
 | `usesDevCursorSecret({ env? })` | true while the shipped dev key is in use — this process, or the table `env` as signing would read it (empty and the published key count as unset) |
-| `CURSOR_SECRET_KEY` / `CURSOR_SECRET_FIX` | `'ULTIMATE_CURSOR_SECRET'` and the one `fix:` for `X_CURSOR_SECRET_DEV` (`export ULTIMATE_CURSOR_SECRET="$(openssl rand -hex 32)"`) — the boot refusal and `@ultimat3/cli`'s deploy contract (`.env.example`, `x env check`, `x doctor`) read both |
+| `CURSOR_SECRET_KEY` / `CURSOR_SECRET_FIX` | `'ULTIMATE_CURSOR_SECRET'` and the one `fix:` for `X_CURSOR_SECRET_DEV` (`openssl rand -hex 32   # put the output in this deploy's secret store as ULTIMATE_CURSOR_SECRET; …`) — the boot refusal and `@ultimat3/cli`'s deploy contract (`.env.example`, `x env check`, `x doctor`) read both |
 | `devSecretsRefused({ env? })` | THE rule for refusing a shipped dev secret: anything but `development`/`test`, and no named environment counts as production. The boot (`assertNoDevSecretsOutsideLocal`), `@ultimat3/storage`'s disk and the CLI's diagnostics all ask it |
 | `resetCursorSigning()` | test seam: forget `configureCursorSigning` and fall back to the environment |
 
@@ -732,17 +806,18 @@ nothing consulted it before deciding to try again. `As of 2026-08-23`.
 | Export | The one answer | The question it settles |
 |---|---|---|
 | `backoffDelay({ attempt, base, max, factor?, curve?, jitter?, random? })` | one curve — `exponential \| linear \| fixed`, `full \| equal \| none` — 1-based `attempt`, clamped to `max` **before** jitter, rounded, and `0` rather than `NaN` | how long to wait. `random` is injectable, so a schedule is a unit test rather than a range |
-| `singleFlight({ deadlineMs?, schedule? })` → `run(key, work, join?)`, `size`, `keys()`, `evict(key)` | N callers on one key are ONE run | who pays for a miss. Eviction is identity-checked, so a load that settles late never drops the load that replaced it; `deadlineMs` frees the KEY a wedged load would hold forever — it never cancels the work and never rejects a joiner. `evict(key)` does the same on demand, for a caller that learns the load in flight began before a write its result must reflect |
+| `singleFlight({ deadlineMs?, schedule?, signal?, released? })` → `run(key, work, join?)`, `size`, `keys()`, `evict(key)` | N callers on one key are ONE run | who pays for a miss. With `signal`, a live joiner re-leads when its leader was aborted, rather than sharing that rejection. `released(key)` fires each time a key stops being held. Eviction is identity-checked, so a load that settles late never drops the load that replaced it; `deadlineMs` frees the KEY a wedged load would hold forever — it never cancels the work and never rejects a joiner. `evict(key)` does the same on demand, for a caller that learns the load in flight began before a write its result must reflect |
 | `flightGate({ maxConcurrent, maxQueued }, { subject?, overflow? })` | one bound, one queue, one refusal | how many at once. Past the queue the answer is `X_FLIGHT_GATE_OVERLOADED` (503) and never a longer queue; the slot is HANDED to a waiter, never released and re-acquired. Both limits are screened at construction (`finiteCount`, 0 allowed); a width of 0 refuses every caller rather than queueing for a slot that never frees. `run(work, signal?)`: an abort while QUEUED removes the waiter and rejects with the abort's reason |
 | `generationFence(subject)` → `generation()`, `bump()`, `guard(issued)` | whether an answer still applies | `X_SUPERSEDED` (499) and `isSuperseded(error)` — the piece nothing in the tree had. `guard` compares `!==`, never `<` |
 | `isRetryableStatus(status)`, `RETRYABLE_STATUSES` | `>= 500`, plus 408, 409, 425, 429 | which HTTP answers are worth repeating |
 | `jitterStatedDelay(waitMs, capMs, random?)` | the ONE rule for a delay a responder named | the stated wait as a FLOOR plus a spread in `[0, min(wait / 2, cap))`, so a burst told `Retry-After: 1` does not replay in lockstep. `retryDecision`'s `retry-after` path (floor clamped to `max`; `jitter: 'none'` gets the bare floor) and `@ultimat3/jobs`' rate-limit deferral and webhook throttle all take it |
-| `retry(work, policy, { sleep, now?, random? })`, `retryDecision(policy, attempt, error, random?)` | the executor and the pure decision behind the classification | whether to try again at all. `clientFlight` is its one caller in the framework; `jobs`, `ai` and `db` each keep their own loop and delegate only the arithmetic and the classification |
+| `retry(work, policy, { sleep?, now?, random? }?)`, `retryDecision(policy, attempt, error, random?)` | the executor and the pure decision behind the classification | whether to try again at all. `retry` stops on the ambient `ctx.signal` and clamps its budget to `ctx.deadlineAt`, with no opt-out: `runToCompletion(fn)` is the way to outlive a caller. `clientFlight` runs the same loop with no context (`retry-loop.ts`), so a page pays for no ambient request; `jobs`, `ai` and `db` each keep their own loop and delegate only the arithmetic and the classification |
 | `clientFlight({ principal?, retry?, deadlineMs?, limit?, … })` → `run(plan)`, `keyFor(url, opts?)`, `bump()`, `generation()` | the five above composed into one typed-client call | dedup, supersession, retry, one wall-clock deadline and a concurrency ceiling, for a call whose dispatch the caller supplies. `@ultimat3/action` and `@ultimat3/query` import it from here and re-export only its types — one file, because both are tier 3 and neither may import the other |
 | `isTransientFailure(error)` | what a CLIENT may send again | a declared `retryable`/`retry-after`, plus a dispatch that produced no response at all. It **inverts** `retryDecision`'s unclassified default on purpose: a caller's own `AbortError` and a foreign `TypeError` are terminal |
 | `traceHeaders()`, `problemOf(text)`, `retryForStatus(code, status, retryAfterSeconds?)`, `FRAMEWORK_CODE` | what a typed client puts on the wire and reads back off it | the W3C header (nothing at all when the span context is incomplete), a total `problem+json` read, and the classification a STATUS is allowed to give when nobody declared one for the code — `retry-after` for a 429 or 503 that stated a delay, unless the code is declared `terminal` |
 | `retryAfterSecondsOf(header, date)`, `MAX_RETRY_AFTER_SECONDS` | the one `Retry-After` reader | delta-seconds, or an IMF-fixdate measured against the same response's `Date` header (never the client's clock), capped at a day; `0`, a date already past and anything else `undefined` — only a positive delay is a statement (`retryAfterOf`'s outbound rule), so unstated falls back to the jittered curve. `clientTransport` passes it to `problemError` and to a caller's `decodeError(status, text, retryAfterSeconds)`, which carry it as `meta.retryAfterSeconds` for `statedDelayMs` |
 | `withStatedDelay(meta, retryAfterSeconds)` | a remote error's `meta`, for both decoders (`problemError`, `@ultimat3/action`'s `RemoteActionError`) | the copied wire keys minus any `retryAfterSeconds` — the server never writes one in a body, framework meta being operator-only — plus the header's value when there was one. A body can never drive the wait |
+| `withRequestId(meta, requestId)` | a remote error's `meta`, for both decoders | the copied wire keys minus any `requestId`, plus the document's root member when it is a non-empty string under 128 chars. A server's `meta` key cannot pose as the id |
 | `remoteTitleOf(value)`, `MAX_REMOTE_TITLE_LENGTH` | a problem document's `title`, as untrusted display text | a non-blank string cut at 120 characters, or nothing. Handed to `UltimateError` as `remoteTitle`, used only when this realm registered no title for the code |
 
 `retry`'s `policy.jitter` is **required** where `backoffDelay`'s defaults to `none`: a loop retrying
@@ -753,12 +828,42 @@ cause and a runnable `fix:` with the fact that something was retried, which no r
 `classifyThrown` and `statedDelayMs` live in `error-retry.ts`, one import away from the table they
 read; `@ultimat3/jobs` re-exports both rather than keeping a second pair.
 
+## One outbound HTTP call, and the breaker in front of it
+
+Server-only, on its own subpath: `import { outbound, screenDial } from '@ultimat3/core/outbound'`
+(the barrel exports neither, `outbound-subpath.test.ts`). `breaker` is on the barrel. Full page:
+[Outbound HTTP](https://github.com/developerz-ai/ultimate/wiki/Outbound-HTTP).
+
+| Export | The one answer | The question it settles |
+|---|---|---|
+| `outbound({ url, vendor, dial, deadlineMs, method?, headers?, body?, idleMs?, maxBytes?, redirect?, retry?, idempotent?, read?, breaker? }, deps?)` | a vendor call | a whole-call deadline clamped by the ambient request, `ctx.signal` (its reason unchanged), core's `retry()` for safe methods only (`X_OUTBOUND_RETRY_UNSAFE`), `Retry-After`, an idle watchdog and a byte cap on the body, `redirect: 'error'` by default, and ten `X_OUTBOUND_*` codes whose causes carry no query and no header. `deps` injects `fetch`, `resolve`, `sleep`, `now`, `random`, `timer`, `env` |
+| `screenDial(url, { resolve?, allowPrivate? })` → `{ pin } \| { refused } \| { unresolved }` | where a dial may land | every resolved address classified by `classifyAddress`, the connection pinned with `tls.serverName`. The framework's one `Bun.dns.lookup` (`resolveDialHost`); `@ultimat3/jobs`' webhook target and `@ultimat3/scraping` call it and keep their own codes |
+| `deadlineSignal(ms, outer?, timer?)` | one attempt's signal | a deadline plus the caller's signal, undone on dispose (no listener left on `outer`, no timer armed) |
+| `breaker({ name, failures, cooldownMs, classify?, clock? })` → `admit`, `succeeded`, `failed`, `released`, `state`, `failures`, `judge`, `refusal`, `run` | is a dependency down | one state machine, the trigger stays the caller's. One probe in `half-open`, lapsing after `cooldownMs`; `X_BREAKER_OPEN` names `retryAfterSeconds`; `breaker_transitions_total{name,to}`. Per process |
+
+## One Redis client
+
+Server-only, on its own subpath: `import { redisClient } from '@ultimat3/core/redis'` (the barrel
+exports none of it, `redis-subpath.test.ts`). The cache's shared tier and the Redis job driver both
+take it; never `Bun.redis`, whose defaults turned an outage into a hang and a restart into a dead
+client. `As of 2026-11`.
+
+| Export | The one answer | The question it settles |
+|---|---|---|
+| `redisClient(url?)` → `RedisClient` | one client per process per URL | `enableOfflineQueue: false` (a command while down is refused at once, not queued — a stopped server cost 30,916 ms per first read), `maxRetries: 2_147_483_647` (the default gave up after ~31 s and never reconnected), `connectionTimeout: 1_000`. Connects in the background: the caller never waits, and a command before the first connect is refused like any other while down |
+| `redisUrl(env?)` | which server | `REDIS_URL`, then `VALKEY_URL`, then `redis://localhost:6379`; blank is unset |
+| `REDIS_CLIENT_OPTIONS` | the three options above, frozen | each carries its measured `why` in `redis-client.ts` |
+
+A refusal is Bun's `ERR_REDIS_CONNECTION_CLOSED`, untyped here: the job driver types it
+`X_DRIVER_UNAVAILABLE`, the cache tier reads it as a miss. `close()` closes it for every holder in the process.
+
 ## One browser seam — transport, records, page handle, principal fence
 
 | Export | The one answer | The question it settles |
 |---|---|---|
 | `clientTransport({ method, url, body?, rawBody?, headers?, signal?, idempotencyKey?, flight?, fresh?, retry?, responseType?, onResponse?, decodeError?, onEnvelope?, fetchImpl? })` | every browser request | `credentials: 'same-origin'`, JSON in and out, the `idempotency-key` header, a non-2xx `problem+json` back into the server's code (`meta.origin: 'remote'`) unless `decodeError` answers first, a network `TypeError` into `X_CLIENT_TRANSPORT_FAILED`. A GET is abortable on `rescope()` and deduped only when a `flight` is passed (`fresh` refuses to join); any other method is never deduped and never aborted by the fence. `rawBody` goes out verbatim with no default header and resolves `undefined` (the body as a string with `responseType: 'text'`). `responseType: 'text'` resolves a 2xx body as a string (typed `Promise<string>`), sends `accept: */*` unless `headers` names one, and adopts no envelope — for an HTML fragment or a CSV; a non-2xx is still decoded as a refusal. About 10.7 kB minified (4.6 kB gzipped) through `@ultimat3/core/page`, no titles table — pinned in `page-bundle.test.ts`. `onResponse` sees headers before the body is read. `onEnvelope` sees the decoded records envelope after adoption — the one way to learn the order of `records[type]`. `fetchImpl` defaults to `globalThis.fetch`, read at call time |
 | `actionPath(name)`, `actionRoute(name)`, `queryPath(name)`, `QUERY_PATH_PREFIX`, `splitWords`, `pluralize` | the one URL rule | `publishPost` → `/api/posts/publish`, `liveFeed` → `/_x/query/live-feed`. Tier 0 so `action`, `query` and `realtime` derive one URL with no sideways import |
+| `templateParams`, `fillTemplate`, `pathTemplateProblem`, `templateKeyProblem`, `toOpenApiPath` (`route-path-template.ts`; the first two also on `./page`) · `mergePathParams`, `HttpPathInputConflictError` (`route-path-merge.ts`) | the one `http.path` template rule | an action's and a query's pin (`/orders/:id/refund`): lowercase static segments and `:param`s, each a required string input key; filled with each value one encoded segment; `{id}` in OpenAPI; the URL's values merged into the input, a disagreeing key `X_HTTP_PATH_INPUT_CONFLICT` (400). Tier 0 because `action` and `query` share a tier |
 | `actionPath(name)` with no `style`, `renderedActionPathStyle()`, `CLIENT_PATH_STYLE_META` | the style nobody restates | `actionPath(name)` reads the document's `<meta name="ultimate-path-style">` stamp, so a browser caller derives under the style the server serves (`defineApi({ http: { pathStyle } })`). No document, no stamp or an unknown value is `'resource'` — a `'resource'` server writes no stamp. A named `style` is never overridden |
 | `RECORDS_HEADER`, `encodeRecordEnvelope`, `decodeRecordEnvelope`, `RecordRows` | `{ data, records?: { [type]: { [key]: Row } }, removed?: { [type]: key[] } }`, only behind `x-ultimate-records: 1` | how an answer carries entity rows without changing the wire of an answer that has none. A malformed envelope is `X_CLIENT_RECORD_ENVELOPE_INVALID` |
 | `pageClient()` → `{ store, socket, scope }`, `RecordSink` | one handle per TAB, not per module copy | every island bundle carries its own core; the handle lives on `globalThis` under one `Symbol.for` key so all of them resolve the same store. No store installed = records dropped |
@@ -770,6 +875,18 @@ read; `@ultimat3/jobs` re-exports both rather than keeping a second pair.
 are in its file header. A server-side caller that propagates a trace passes `traceHeaders()` in
 `headers` itself.
 
+## A component's node tree, for a test — two subpaths, off the barrel
+
+| Export | Subpath | What |
+|---|---|---|
+| `JSX_NODE`, `ISLAND_NODE`, `HOLE_NODE` | `@ultimat3/core/render-node` | the render node brands, one `Symbol.for` each; a leaf with no import. `@ultimat3/render` imports and re-exports all three |
+| `renderNodes(component, props?, { components? })`, `nodesOf(value, { components? })` | `@ultimat3/core/render-nodes` | every node in the tree, depth first: `'expand'` (default) calls components and keeps host nodes, `'keep'` keeps component nodes beside their output, `'stop'` calls none. Thunks are called; an island's server shell and a hole's `fallback`/`error` are walked, a hole's deferred `children` never called; a value no factory built is nothing |
+| `byTag`, `byComponent`, `withAttr`, `one`, `attachRef`, `fire`, `isRenderNode`, `RenderNode`, `RenderComponent`, `ComponentMode`, `NodesOfOptions` | `@ultimat3/core/render-nodes` | selectors over those nodes. `one()` refuses zero and two, `attachRef`/`fire` a missing prop, all `X_INVARIANT` naming what was sought |
+
+`render-nodes` is imported by tests only, pinned by `render-nodes-subpath.test.ts` with the barrel
+holding none of these names. `renderView` (`@ultimat3/testing`) answers what a reader sees; this
+answers what an element carries.
+
 ## One image pipeline, everywhere
 
 ```ts
@@ -826,3 +943,13 @@ hand-rolled JPEG and PNG codecs is what put it there.
 
 `image/image-fixture.ts` is byte-exact output from Pillow and ffmpeg on purpose: a codec that only round
 trips against itself proves nothing. Never regenerate a fixture with our own encoder.
+
+## Supporting exports
+
+`As of 2026-11-02`.
+
+| Name | What |
+|---|---|
+| `CompletionBound` | what bounds a `runToCompletion` scope, when its caller owns a ceiling |
+| `MAX_TIMER_MS` | the longest delay a timer holds, 2,147,483,647 ms: past it `setTimeout` arms ~1 ms |
+| `jsonbRefusal(text)` | why `jsonb` would refuse this `JSON.stringify` output, or `undefined`. Names the class of thing, never the text |