@ultimat3/core 1.2.0 → 2.0.0

package/CLAUDE.md

@@ -0,0 +1,252 @@
+# @ultimat3/core — agent notes
+
+Tier 0. **Imports no `@ultimat3/*` package.** Everything else depends on this, so a change here
+is a change to every package.
+
+| Rule | |
+|---|---|
+| Deps | none (`bun-types` only) |
+| Errors | subclass `UltimateError`; never `throw new Error` |
+| Values in a message | `renderCauseValue()` / `renderFixLiteral()`; never raw `JSON.stringify`, `String()` or `${…}` on an `unknown` |
+| A value a CALLER supplied | `describeValue()` — shape, never content. `renderCauseValue` is safe against throwing, not against leaking |
+| Reading a caught value | `renderThrowable()` / `isThrownError()` / `stringField()`; never `error.message`, `error instanceof Error` or `typeof error.code === 'string'` directly — the probe throws before the renderer runs |
+| New code | add to `CORE_CODE_TITLES` in `error-codes.ts`, else the title is auto-humanised |
+| Time | take a `Clock`; `Date.now()` / `new Date()` only inside `clock.ts` |
+| Context | never thread `ctx` as a parameter — `useContext()` |
+| Exports | add to `src/index.ts` explicitly; no `export *`. Three subjects that each span a dozen modules arrive through `src/exports/` — every name is still written out in `index.ts`, so the public surface is one file to read |
+| 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, so `tsc` never reads one |
+
+Deliberate cycles (safe — nothing is referenced at module-evaluation time):
+`errors.ts ⇄ error-codes.ts`. Keep it that way: no top-level `UltimateError` use in
+`error-codes.ts`.
+
+`error-render.ts` imports nothing, including from this package — an error factory that dies
+formatting its own message is the failure it exists to prevent, so it cannot depend on anything
+that could itself throw. The same defect shipped three times (`entity`, `flags`, `cli`) before
+this file existed; `renderCauseValue` is `@ultimat3/entity`'s `renderValue` moved down a tier
+VERBATIM, `a object` included, so a package adopting it changes no message. `toUltimateError`,
+`parseId` and `readPackageVersion` are its first callers. The mechanical half is
+`scripts/error-render.ts` on `x verify`'s `errors` step (`X_ERROR_RENDER_UNSAFE`) — it reads
+parameters typed `unknown` that reach a `cause:` / `fix:`, and it cannot see a value laundered
+through a local helper first (`packages/ui/src/components/ErrorState.tsx` builds a `message`
+const, then assigns it).
+
+`describeValue` in `error-render.ts` is a character-for-character duplicate of `describeValue` in
+`packages/schema/src/describe-value.ts`, for the same tier-0 reason `SCHEMA_ERROR_CODE_TITLES` is
+one: schema and core are both tier 0 and `core → schema` is **not** a declared edge in
+`scripts/lib/tiers.ts`, so neither may import the other. Keep the two identical; a pin test in
+`@ultimat3/cli` (which may legally import both) is the mechanical half, the same shape as
+`schema-error-codes-pin.test.ts`. The rule it enforces: a `cause` reaches the log index AND the
+HTTP problem document, redaction is by log FIELD key, and a value baked into a message string has
+no key left to redact — so `parseId`/`uuidTimestamp` describe a rejected id and never echo it.
+
+`logger.ts` must not import `context.ts`. `context.ts` injects the ids via
+`setLoggerContextFields()`. It **does** import `secret.ts`, one way only: `secret.ts` owns
+`REDACTED` so a `Secret` can render it without importing the logger, and `logger.ts` re-exports
+the constant so there is still one definition and one public path.
+
+`ActorFacts` is the app's extension point on `Actor` — module augmentation, the same trick as
+`CtxServices` and `PermissionRegistry`. Core declares the seam and **never a fact**: augmenting
+`ActorFacts` inside the framework would declare that fact for every app. Every fact reads as
+`T | undefined` through `actorFact()` on purpose — an unresolved fact must deny, and a job, a
+test and an MCP token exchange all mint actors that resolved nothing. `type-pins.ts` pins that
+shape against a locally declared sample interface for exactly that reason.
+
+| Concept | Owner | Note |
+|---|---|---|
+| which deploy this is | `environment.ts` (`ULTIMATE_ENV`) | the twin of `ROLE`; never declare a second env var for it |
+| what this process does | `roles.ts` (`ROLE`) | |
+| which build of the APP this is | `app-version.ts` (`APP_VERSION`) | one reader, `dev` by default: `db` writes it into `x_migrations` and `jobs` into `x_backfills`, and `jobs` cannot reach `db` for the answer |
+| the values | `env.ts` | `checkEnv().values` holds REAL secrets — anything that prints 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` |
+| a value that must not be printed | `secret.ts` | redacted by VALUE; `revealSecret()` is the one way out, on purpose greppable |
+| 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()` |
+
+`installSecrets()` is the ONLY path from `secrets.enc.json` to an app value, and it lands in
+`process.env` before `defineEnv` reads it — so a secret has one declaration (`envSchema`), one
+`.env.example` row, one mask and one reader. A second accessor would be five second
+implementations. The real environment always wins, which is what lets one image run in Compose and
+on K8s off one committed file.
+
+`secrets-errors.ts` registers its seven codes through `registerErrorCodes()` rather than joining
+`CORE_CODE_TITLES` — the codes and the module that throws them ship together, and `registerErrorCodes`
+is the one mechanism that raises `X_ERROR_CODE_DUPLICATE` if anything else claims one. Consequence
+to know: a test that calls `resetErrorCodes()` drops these titles like any other package's, so take
+`errorCodeSnapshot()` first. The envelope carries a `kid` (a domain-separated, truncated SHA-256 of
+the master key) purely so *wrong key* and *edited file* are two codes and not one shrug — GCM alone
+cannot tell them apart.
+
+`schema-error-codes.ts` is the same shape a second time, for codes this package does not even own.
+`@ultimat3/schema` is tier 0 like `core` and so can neither call `registerErrorCodes()` itself nor
+import core to reach it — the four codes' titles are a deliberate, tested duplicate of
+`SCHEMA_ERROR_CODES` in `packages/schema/src/errors.ts`, registered unconditionally at import time
+so any process that imports core (not just `@ultimat3/cli`, which used to be the only registrant)
+renders schema's real titles. Neither tier-0 package can check the duplicate against its source, so
+the pin (`schema-error-codes-pin.test.ts`) lives in `@ultimat3/cli`, which may legally import both.
+
+`timing-safe-equal.ts` holds the one constant-time string comparison `@ultimat3/auth` and
+`@ultimat3/storage` both need — core is the lowest tier both can reach, so the shared code lives
+here rather than in either package copying the other's file.
+
+`mcp-exposure.ts` is the same shape for a declaration rather than an algorithm: `isMcpExposed` is
+the ONE answer to "did this primitive opt into being an MCP tool?", asked by `action`, `query`
+(t3), `mcp`, `ai`, `manifest` (t4) — five packages that cannot import each other, so core is the
+only tier all of them reach. Three spellings of the same question shipped before it (`=== true`,
+`!== false`, `?? true`), which published tools in `openapi.json` and `x.manifest.json` that no
+surface would serve. Never add a second reader: `@ultimat3/cli`'s `mcp-exposure-pin.test.ts` is
+what makes "one predicate" checkable, since no single package below tier 5 can. The one deliberate
+exception is `@ultimat3/admin`'s own catalog, which is opt-OUT and says why in `mcp-tools.ts`.
+
+Metrics mirror tracing exactly — `metrics.ts` is to `telemetry.ts` what a counter is to a span:
+always on, no-op exporter by default, driver on the wire. `runtime-metrics.ts` is the only place
+that names a series the deploy chart reads (`http_requests_total`, `connections`, `queue_depth`);
+`SCALING_METRICS` keys them by `ScalingSignal` so `roles.ts` and `docker/helm` cannot drift.
+Core declares the instruments and never calls them for another package's events. `As of 2026-08`
+the recorders are wired, and there is exactly one call site per package — a second one anywhere is
+the bug:
+
+| Recorder | The one caller | Why that seam |
+|---|---|---|
+| `recordRequest` | `@ultimat3/http` `pipeline.ts`, the `finally` around `execute` | every request passes it once, error paths included |
+| `recordConnection` | `@ultimat3/realtime` `socket.ts`, `SocketRegistry.add`/`remove` | the only definition of a live connection; close, idle sweep and drain all pass through it, so the gauge cannot leak |
+| `recordQueueDepth` | `@ultimat3/jobs` `worker.ts`, throttled inside `tick()` | the worker is the only process that reads its own queue |
+| `recordJob` | `@ultimat3/jobs` `worker.ts`, the outcome branch inside `tick()` | the loop is where the queue name is in scope; `JOB_OUTCOME_LABELS` maps the four outcomes onto three labels and drops `suspended`, because parking a run is control flow |
+| `recordLeaseLost` | `@ultimat3/jobs` `heartbeat.ts`, once per lease that lapsed | the lease heartbeat is the only thing that knows a renewal stopped landing; deliberately not an `outcome` on `jobs_total`, because nothing failed and nothing finished — the queue simply re-delivered a job this process was still running |
+
+Tracing has three parts and they are three files on purpose: `telemetry.ts` builds spans,
+`sampler.ts` decides whether a trace is worth exporting, and `otlp*.ts` puts it on the wire.
+`span.end()` returns early when `traceFlags & 1` is 0 — the bit is obeyed, not merely forwarded,
+which is what stops an exporter from turning 40k rps into 40k rps of spans. `configureTelemetry`
+takes a `Sampler`; the default reads `OTEL_TRACES_SAMPLER*` **at the first span, never at module
+scope** (same call-time rule as `cursor.ts`'s secret). `resetTelemetry()` drops both.
+
+The OTLP exporters are built, not wrapped, and the case is in
+[`docs/idea/18-build-vs-wrap.md`](../../docs/idea/18-build-vs-wrap.md): OTLP/HTTP JSON is `fetch`
+plus `JSON.stringify`, while `@opentelemetry/api` would put a SECOND `Span` type in the framework
+(axiom 1) and `sdk-node` would fight `context.ts` for the AsyncLocalStorage. `otlpTraceRequest` /
+`otlpMetricsRequest` are pure so the wire format is a unit test, exactly as `sentryEnvelope` is.
+**gRPC (`:4317`) is out of scope** — it needs HTTP/2 and protobuf, and both the `:4317` port and a
+non-`http/json` `OTEL_EXPORTER_OTLP_PROTOCOL` throw `X_OTLP_PROTOCOL_UNSUPPORTED` naming `:4318`.
+A boot that must not throw asks `tryOtlpEndpoint(signal)` first.
+
+`error-reporter.ts` is the same shape a third time: `ErrorReporter`, a no-op default, a memory
+reporter for tests, and a transport on the wire (`error-reporter-sentry.ts`, an optional separate
+export — the DSN is the app's typed env, never a constant here). `reportError` never throws and
+never awaits. **Four packages call it, seven call sites, `As of 2026-08`** — and unlike the
+recorders it is not one per package, because `realtime` has two files that can see a throw:
+
+| Package | Call site |
+|---|---|
+| `@ultimat3/http` | `stages.ts` — `status >= 500` only |
+| `@ultimat3/jobs` | `execute.ts`, inside `executeJob`: the one frame still holding the thrown value, where the loop above it sees a message string |
+| `@ultimat3/realtime` | `sync-node.ts` (three) and `sync-upgrade.ts` (one) |
+| `@ultimat3/flags` | `runtime.ts` — `source: 'process'`, severity `warning` |
+
+`configureErrorReporting({ release })` is fed the build id `serve.ts` already computed — never a
+second deploy identity. Trace and span resolve as a **pair**, from one source and never field by
+field: a caller-supplied `traceId` picking up the ambient `spanId` produced reports naming a span
+in a different trace, which is worse than no span because it looks authoritative.
+
+`METRICS_PATH` is served by `@ultimat3/cli`'s `metrics-endpoint.ts`, on `METRICS_PORT` (9090) and
+**not** on the role's HTTP port: the chart's ingress routes `/` to `web`, so `/metrics` beside
+`/healthz` would be the app's route patterns and error rates on the internet. Every role opens it,
+including the three that open no other socket — `queue_depth` belongs to one of them.
+
+```bash
+bun test                      # from packages/core
+bun run typecheck
+```
+
+`markReady()` means **bound**, and readiness means **usable** — two different facts since
+`registerReadinessCheck(name, check)`. `/readyz` is ready only when the state is `ready` AND every
+named check passes, and `HealthReport.checks` carries them by name because "alert on check
+failures by check name" is not writable against a boolean. Checks are **synchronous** on purpose:
+a probe that awaits a network call turns a slow dependency into a wedged endpoint and a restart
+loop, so the owner of the dependency keeps a boolean fresh and this reads it. Liveness ignores
+them — a database outage that failed `/healthz` would restart the whole fleet into the same
+outage. The registration returns its unregister, same shape and same ownership rule as
+`onShutdown`; `readinessCheckCount()` is the leak probe.
+
+**The drain deadline is enforced, not merely computed, and there is no unbounded state.**
+`ShutdownReason.deadlineAt` was always handed to every hook and **no hook has ever read it** —
+`jobs`' worker awaits every in-flight job and `driver.close()`, `jobs`' scheduler awaits its round,
+`realtime`'s `listenSyncNode` awaits `node.drain()`'s own grace, `http`'s `server.ts` awaits
+`server.stop()` — so before 2026-08 `configureLifecycle({ deadlineMs: 100 })` bounded nothing:
+measured, one 5-second `accept` hook drained in **5053ms**, state pinned at `draining`. `runPhase`
+now races each hook against the time left before `deadlineAt` (`lifecycle-deadline.ts`'s
+`settleWithin`, split out so the race cannot reach this file's state) and an overrun is
+**ABANDONED** — the drain resolves, the later phases still run, and `installSignalHandlers` reaches
+`process.exit(0)`. Merely logging would leave the kubelet to SIGKILL at the grace period, which is
+the every-deploy job duplicate draining exists to prevent; the abandoned hook keeps running with
+nobody reading it, and that cost is named in the log line rather than hidden. `settleWithin`
+attaches a rejection handler unconditionally: an abandoned hook that rejects later has nobody left
+awaiting it, and the unhandled rejection would kill the process the drain is ending cleanly.
+
+Three rules follow and none is optional. **The budget is the WHOLE drain's**, read per hook off
+`deadlineAt`, so a hook that spends it leaves none for the ones behind — the sum of the phases is
+bounded, not each phase separately, which is what `terminationGracePeriodSeconds` means. A budget
+already spent still lets a *synchronous* hook finish (a resolved promise settles on a microtask,
+the 0ms timer on a macrotask), so closing a pool costs nothing it does not already have.
+**`DEFAULT_DEADLINE_MS` (25s) applies whether or not an app sets one** — an opt-in deadline would
+have left `worker`, `scheduler` and `sync` unbounded, i.e. a mechanism claiming more than it
+enforces; abandoned at 25s a worker exits clean, its row's visibility lease lapses and another
+worker re-claims it, which is what at-least-once already promises, and the alternative is the same
+duplicate delivered by SIGKILL with no line naming what overran. The lever is a **larger** value —
+`configureLifecycle({ deadlineMs: 600_000 })` for a 10-minute job — and the `X_SHUTDOWN_TIMEOUT`
+`fix:` says so, because whoever reads it at 3am learns the knob from the line. **The budget is real
+monotonic time (`systemClock`), never the injected `clock`**: `waitForIdle` sleeps on a real
+`setTimeout`, so a frozen clock advanced an hour handed the drain a 16-minute grace period the
+kubelet would never honour. `clock` still owns `uptimeMs`. `drainDeadlineMs()` is the one place the
+budget is decided and the only thing a test can pin — 25s is above any drain a test can wait out.
+
+`impersonate(actor, reason, fn)` is the ONE door through `withChildContext({ actor })`. It stamps
+the caller onto the child as `Actor.onBehalfOf`, so `actorLabel` renders
+`service:eng-7→user:cust-99@org-3` and a refund issued during a support session can never read as
+the customer's. The non-blank-reason assert is `@ultimat3/entity`'s `crossTenant()` template
+verbatim — two escapes from the framework's default posture should not look like two things. Do
+not add a second impersonation path.
+
+Every `UltimateError` carries `retry` (`terminal | retryable | retry-after`), **defaulting to
+`terminal`** — fail closed, because a client retrying on `status >= 500` hammers `X_DB_DRIFT` and
+`X_TENANCY_UNSCOPED`, which are permanent config faults. `registerErrorRetry()` is the one
+registration path and it refuses to reclassify a core code, the same way `registerErrorStatus`
+refuses to remap one. A new code in any package should be classified beside its declaration.
+
+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` for `ctx.posts`. The
+  cost is a real axiom-3 hole: `ctx.anything` type-checks as `unknown`, so a service nobody
+  declared and nobody installed reads as a value rather than a build error (`examples/dummy`
+  shipped `ctx.storage.ensureBucket()` against a method no package has). Deleting the signature
+  is the fix and a breaking change; until then `ctx.services['mail']` is the honest late-bound
+  path and a declared augmentation is the only typed one. **Measured 2026-08:** deleting the
+  signature compiles core clean on its own, and the augmentation seam survives untouched — an
+  augmentation adds NAMED members and `Ctx extends CtxServices` picks them up with no index
+  signature at all. What is unmeasured is the rest of the tree: the change is only a build error
+  where an app reads an undeclared service, which is the point, but `examples/dummy` ships one
+  such read and it would land on the app gate's ratchet. Land it as its own change, alone, with a
+  full `bun run verify` — never folded into another branch.
+- Tests that touch the registry, the lifecycle or the listener table must call
+  `resetErrorCodes()` / `resetLifecycle()` / `resetListeners()`.
+- `onShutdown`'s return value is the unregister, and every caller that can be started twice owns
+  it — `@ultimat3/http`'s `server.ts`, `@ultimat3/realtime`'s `listenSyncNode`, `@ultimat3/jobs`'
+  worker, `@ultimat3/cli`'s `hold.ts`. `shutdownHookCount()` is the test-only probe, the same
+  shape as `idleWaiterCount()`: a count that climbs across a start/stop cycle is a leak.
+- The error-code registry is process-global and every package fills it once, at import time. A
+  test that resets it must take `errorCodeSnapshot()` first and call the returned undo in
+  `afterAll` — a reset that is not handed back strips the titles of every package imported before
+  that file, and their errors render the humanised fallback (`X_DB_DRIFT: db drift`) for the rest
+  of the run. That is a load-order flake: green locally, red on whichever CI ordering hits it.
+- Tests that call `configureCursorSigning()` must restore the previous secret, or call
+  `resetCursorSigning()` — the only way back to "unconfigured", which restoring a literal cannot
+  express. The secret itself is read inside `sign()`, never at module scope: `openSecrets()` runs
+  during boot, so a module-scope read signed a whole process's cursors with the dev key while
+  `ULTIMATE_CURSOR_SECRET` was set and `x doctor` merely warned. Same call-time rule as
+  `@ultimat3/auth`'s `oauth-cookie.ts` / `oauth-exchange.ts`; new secrets follow it.
+- `PRIMITIVE_KINDS` is the executable copy of the eight-primitive rule — `PrimitiveKind` derives
+  from it, so the list and the type cannot drift. A ninth entry fails `registrar.test.ts`, which
+  is the point: a new capability arrives as a factory over an existing primitive (`llm()` returns
+  an `action`), never as a new kind.

package/README.md

@@ -6,20 +6,31 @@ Zero dependencies, zero `@ultimat3/*` imports.
 | 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` |
 | code → `{ title, docs }` registry, `registerErrorCodes()` | `error-codes.ts` |
 | `Result<T, E>` for boundaries where throwing is wrong | `result.ts` |
 | request context on `AsyncLocalStorage` | `context.ts` |
 | `Actor` (`user \| service \| agent \| anonymous`) | `actor.ts` |
+| acting as another actor, with an origin and a reason | `impersonate.ts` |
+| is an error worth retrying? one classification per code | `error-retry.ts` |
 | typed env validated at boot | `env.ts` |
 | `.env.example` rendered from that schema, and its drift check | `env-example.ts` |
 | named environments + `ULTIMATE_ENV` resolution | `environment.ts` |
 | a value that cannot be printed by accident | `secret.ts` |
+| the committed encrypted secrets envelope, AES-256-GCM | `secrets.ts` |
+| the two secrets files, and decrypted values → `defineEnv` | `secrets-store.ts` |
 | `defineConfig()` for `app.config.ts` | `config.ts` |
 | runtime roles + `ROLE` resolution | `roles.ts` |
 | `Clock` — the only source of "now" | `clock.ts` |
 | UUIDv7, nanoid, branded ids | `ids.ts` |
 | structured JSON logging + redaction | `logger.ts` |
 | 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` |
+| `SpanExporter` on the wire, batched | `otlp-span-exporter.ts` |
+| `MetricExporter` on the wire | `otlp-metric-exporter.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` |
 | 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` |
@@ -47,9 +58,21 @@ X_DB_DRIFT: schema differs from migrations
 ```
 
 `format()` is always 3 lines (`format({ docs: true })` adds a 4th). `toJSON()` is the `--json`
-form: `{ code, title, cause, fix, docs, meta, stack }`. The title comes from the registry, so
+form: `{ code, title, cause, fix, docs, retry, meta, stack }`. The title comes from the registry, so
 the terminal, the browser overlay and `--json` cannot drift.
 
+`retry` is `terminal | retryable | retry-after`, and it **defaults to `terminal`** — a client that
+retried on `status >= 500` hammered `X_DB_DRIFT` and `X_TENANCY_UNSCOPED`, which are permanent
+config faults, during the incident they were already causing. Classify the codes your package or
+app throws once, beside the module that declares them:
+
+```ts
+registerErrorRetry({ X_OAUTH_EXCHANGE_FAILED: 'retryable', X_RATE_LIMITED: 'retry-after' });
+```
+
+Core's own classifications are closed, exactly as `registerErrorStatus`'s framework table is: a
+second, different registration for one code throws `X_ERROR_RETRY_INVALID`.
+
 | Code | Subclass |
 |---|---|
 | `X_CONFIG_INVALID` | `ConfigInvalidError` |
@@ -64,6 +87,54 @@ Registering a code twice throws `X_ERROR_CODE_DUPLICATE`.
 `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.
 
+### A value you did not produce goes through the renderer
+
+An error factory may never throw while formatting its own message: the caller then catches a
+`TypeError` instead of the refusal, `error.code === 'X_…'` matches nothing, and an HTTP surface
+answers 500 where the mapped status belonged. `JSON.stringify` throws on a bigint and on a cycle
+and RUNS any `toJSON` the value carries; `` `${value}` `` throws on a symbol and on a hostile
+`toString`. Both are reachable from app data.
+
+```ts
+import { renderCauseValue, renderFixLiteral, UltimateError } from '@ultimat3/core';
+
+declare const kind: unknown;
+declare const value: unknown;
+
+throw new UltimateError({
+  code: 'X_ID_INVALID',
+  cause: `expected a ${renderCauseValue(kind)} UUIDv7, received ${renderCauseValue(value)}`,
+  fix: `pass an id produced by typedId<${renderFixLiteral(kind, '<kind>')}>()`,
+});
+```
+
+| Helper | For | Degrades to |
+|---|---|---|
+| `renderCauseValue(value)` | a `cause`, which only has to describe | `a object that cannot be rendered` |
+| `renderFixLiteral(value, placeholder)` | a `fix`, which has to parse and run | the placeholder you name |
+| `renderThrowable(value)` | a caught value: an `Error`'s own words, anything else rendered | `renderCauseValue(value)` |
+| `isThrownError(value)` | `value instanceof Error` where the test itself may throw | `false` |
+| `stringField(value, key)` | one string field off a caught value | `undefined` |
+
+The last two are the READ side, and the reason they exist is that the renderers above them were
+being reached past an unguarded probe. `catch (error)` hands you a value the framework did not
+build: `error instanceof Error` runs a `Proxy`'s `getPrototypeOf` trap, and
+`typeof error.code === 'string'` — the structural check every surface uses to recognise an
+`UltimateError` that crossed a worker, a subprocess or a socket — is a getter call. Either one
+throws one line *before* the total renderer that was meant to make the path safe.
+
+```ts
+const code = stringField(error, 'code') ?? 'X_TRANSPORT_UNAVAILABLE';
+const cause = stringField(error, 'cause') ?? renderThrowable(error);
+```
+
+`stringField` answers `undefined` for absent, wrong type and threw, because all three mean the
+same thing to the caller: this value did not supply the field, so use the default.
+
+Enforced, not documented: `x verify`'s `errors` step fails with `X_ERROR_RENDER_UNSAFE` when a
+parameter typed `unknown` reaches a `cause:` or `fix:` through `JSON.stringify`, `String()` or a
+bare interpolation (`scripts/error-render.ts`).
+
 ## Context
 
 ```ts
@@ -90,6 +161,36 @@ 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.
 
+## 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
+one ("a friend of the author?"), and a policy predicate is synchronous, so it may not go and
+fetch one. Resolve the graph ONCE per request and hand it to the actor every surface already
+carries:
+
+```ts
+declare module '@ultimat3/core' {
+  interface ActorFacts { readonly viewer: Viewer }   // declared once, app-wide
+}
+
+// at the request boundary, where the await already happens
+const actor = withFacts(userActor({ id: user.id, roles: [user.role] }), { viewer });
+
+// in a predicate, on any surface — HTTP, MCP, admin, a job
+can('post:read', ({ row, actor }) => row !== null && canSee(actorFact(actor, 'viewer'), row));
+```
+
+| Rule | Why |
+|---|---|
+| `actorFact(actor, key)` takes `Actor \| null` | that is exactly what a predicate is handed |
+| every fact is `T \| undefined` | nothing can prove one was resolved — a job, a test and a token exchange mint actors too, so an absent fact is a **denial** the compiler makes you write |
+| `facts` is optional on `Actor` | additive: an actor literal written before the seam is still an `Actor` |
+| the framework declares no fact | `ActorFacts` is the app's; core only owns the seam. `type-pins.ts` pins the machinery against a local sample rather than augmenting the real interface |
+
+Not a second authz path: the facts ride the actor the policy layer already reads, so no surface
+package learns the app's vocabulary and one `Policy` object still answers everywhere. Facts are
+request-scoped and never logged — `actorLabel()` stays id-only.
+
 ## Env fails once, completely
 
 ```ts
@@ -120,11 +221,17 @@ Loading `.env` is **Bun's**, not ours. `envFileCandidates()` states what it does
 ## One environment, one key
 
 ```ts
-resolveEnvironment();   // 'development' | 'test' | 'staging' | 'production'
-isProduction();         // exact; nothing else counts
-isLocal();              // development or test — never staging
+resolveEnvironment();      // 'development' | 'test' | 'staging' | 'production'
+tryResolveEnvironment();   // the same, `undefined` instead of a throw for an unrecognised value
+isProduction();            // exact; nothing else counts
+isLocal();                 // development or test — never staging
 ```
 
+`tryResolveEnvironment` is for a caller that must *answer* rather than fail — a `robots.txt` render
+is the case: `ULTIMATE_ENV` is not in the env schema, so nothing validates it at boot, and a typo
+would otherwise 500 the one response whose body was already going to be `Disallow: /`. It names no
+fallback of its own; the caller does.
+
 `ULTIMATE_ENV` is the key, `NODE_ENV` the fallback (platforms already set it). Values are
 `NODE_ENV`'s spellings plus `staging` — `prod` and `dev` are typos, not aliases, and
 `ULTIMATE_ENV=prod` is `X_ENVIRONMENT_INVALID`. An unrecognised `NODE_ENV` is *not* an error: it
@@ -146,19 +253,63 @@ frozen and everything but `label` is non-enumerable, so `{ ...dsn }` cannot spre
 out. There is no vault integration and there will not be one — that is a platform primitive
 (axiom 7); a `Secret` plus the platform's own secret store is the whole design.
 
+## Encrypted secrets are env values that arrive early
+
+```ts
+// app.config.ts
+await installSecrets();                       // secrets.enc.json → process.env, real env wins
+export const envSchema = {
+  SESSION_SECRET: { type: 'string', secret: true },
+} satisfies EnvSchema;
+export const env = defineEnv(envSchema);
+```
+
+`secrets.enc.json` is committed; `.secrets.key` is not, and `ULTIMATE_SECRETS_KEY` is read before
+it so a container is handed its key by the platform. The plaintext is a flat map of environment
+variable names to values, so a secret keeps **one** declaration (`envSchema`), one `.env.example`
+row, one mask (`maskedEnvValues`), one redaction entry and one reader (`env.SESSION_SECRET`).
+There is deliberately no `secrets.get()`: a second accessor would mint values with no declaration,
+no type and no mask, and each of those five would need a second implementation. `x secrets` is the
+only writer.
+
+| Envelope | |
+|---|---|
+| Cipher | AES-256-GCM through WebCrypto, 128-bit tag, a fresh 12-byte IV per seal |
+| Key | 32 CSPRNG bytes, hex. No KDF — the key is the key |
+| AAD | `v`, `alg` and `kid`, so a downgraded header fails the tag rather than changing how the body is read |
+| `kid` | a domain-separated, truncated SHA-256 of the master key. Safe to commit, and what makes *wrong key* (`X_SECRETS_KEY_MISMATCH`) a different code from *edited file* (`X_SECRETS_TAMPERED`) |
+
+A missing file is not an error — an app may declare no secrets. A file with **no key to open it**
+is `X_SECRETS_KEY_MISSING` and fatal: a process that booted past its secrets authenticates against
+nothing and still reports healthy.
+
 ## Time, ids, telemetry, drain
 
 - Never call `Date.now()`. Take a `Clock`; tests pass `frozenClock('2026-07-26T10:00:00Z')`.
 - `uuid()` is UUIDv7: time-prefixed, monotonic within a millisecond, never backwards on clock
   skew. `typedId<'post'>()` brands it so a post id cannot be passed where a user id is wanted.
 - `withSpan('action.publishPost', fn)` is free until `configureTelemetry({ exporter })`.
-  Traces cross process boundaries via `traceparent()` / `parseTraceparent()` — Sentry, Honeycomb
-  and OTLP all plug in as a `SpanExporter`.
+  Traces cross process boundaries via `traceparent()` / `parseTraceparent()`, whose ids come from
+  `traceId()` / `spanId()` — **never `uuid()`**, whose dashed 36 characters every collector
+  rejects. `isTraceId()` / `isSpanId()` are the one definition of the valid shape.
+- **Sampling is honoured, not just propagated.** `startSpan` takes the parent's bit when there is
+  one, else asks the `Sampler`; `span.end()` exports nothing when the bit is 0. The default reads
+  `OTEL_TRACES_SAMPLER` / `OTEL_TRACES_SAMPLER_ARG` at the first span, and
+  `configureTelemetry({ sampler })` replaces it.
+- **The OTLP exporters ship**, speaking OTLP/HTTP JSON, no dependency:
+  `otlpSpanExporter({ endpoint })` (batched, with `flush()` / `shutdown()`) and
+  `otlpMetricExporter({ endpoint })`. Both default to `OTEL_EXPORTER_OTLP_ENDPOINT`;
+  `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`.
 - 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
-  200 until stopped.
+  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.
+  `shutdownHookCount()` is the test-only probe that makes the leak assertable.
 - Anything that opens a socket calls `markListening(server.url.origin)` and releases it on close.
   That is what tells the sealed test network a loopback request is this process, not egress.
 
@@ -181,8 +332,8 @@ collectMetrics();       // the same numbers as data, for a MetricExporter
 | Temporality | cumulative, as OTel defines it — a read never resets a counter, so two scrapers cannot steal each other's samples |
 | Names | lowercase `snake_case`, the intersection every exposition format accepts. Dotted OTel names survive OTLP and die at a Prometheus scrape |
 | Attributes | `string \| number \| boolean` only — each distinct set is a stored series, so a user id here is an outage |
-| Driver seam | `MetricExporter`, defaulting to a no-op. `memoryMetricExporter()` for tests, `startMetricExport(ms)` for a periodic push |
-| Not shipped | an OTLP client. It is bytes on a wire and a dependency; the seam is here, the driver is yours — or scrape `/metrics` with an agent that already speaks it |
+| Cardinality | enforced, not advised: `maxSeries` per instrument (default `DEFAULT_MAX_SERIES`), and past it every new label set folds into one `otel_metric_overflow="true"` series with `X_METRIC_CARDINALITY` logged once, naming the instrument |
+| Driver seam | `MetricExporter`, defaulting to a no-op. `memoryMetricExporter()` for tests, `startMetricExport(ms)` for a periodic push, `otlpMetricExporter()` for a collector |
 
 `runtime-metrics.ts` holds the series every process emits, and `SCALING_METRICS` maps each
 `ScalingSignal` from `roles.ts` to the one that carries it — so the role table, the chart and the
@@ -201,6 +352,54 @@ at `METRICS_PATH` on `METRICS_PORT` (9090), for every role rather than only the
 HTTP socket. Labels are route **patterns**, status **classes** and queue names: nothing
 per-user, per-id or attacker-chosen ever becomes a series.
 
+## Error reporting: the third seam, same shape as the other two
+
+A no-op by default, one transport on the wire, one memory double for tests — `telemetry.ts` and
+`metrics.ts`' shape a third time. What a monitor receives is the framework's error contract
+verbatim, so it groups on `code` and shows `fix` to whoever is paged.
+
+**An Ultimate app installs nothing.** `@ultimat3/cli`'s `serve.ts` calls
+`configureErrorReporting` at boot from one env var — `SENTRY_DSN`, unset meaning the no-op stays
+and nobody is paged — and passes the build id it already computed as `release`. The call below is
+for a host that boots something other than `runRole`.
+
+```ts
+import { configureErrorReporting, reportError, sentryErrorReporter } from '@ultimat3/core';
+
+declare const sentryDsn: string;
+declare const buildId: string;
+declare const failure: unknown;
+
+configureErrorReporting({
+  reporter: sentryErrorReporter({ dsn: sentryDsn }),   // config, never a constant in this package
+  release: buildId,                                    // the id `x-ultimate-build` carries
+});
+
+reportError(failure, { source: 'http', severity: 'error', scope: { operation: 'POST /api/posts' } });
+```
+
+| | |
+|---|---|
+| `reportError(error, { source, severity?, scope? })` | never throws, never awaits. A monitor that is down must not turn one failure into two |
+| `ERROR_SOURCES` | `http` `job` `realtime` `cli` `process` — closed. A new surface adds a member, never a string of its own |
+| `ErrorSeverity` | `warning` `error` `fatal`. `warning` is a failure the framework already recovered from — a retry, not a dead letter |
+| `ErrorScope` | `requestId` `traceId` `spanId` `role` `operation` `actorId` `extra`. `operation` is a route **pattern** or a job name, never a concrete path or a row id |
+| `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? })` |
+| 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 |
+
+`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
+thrown value — `@ultimat3/realtime`'s `sync-node.ts` and `sync-upgrade.ts`, and `@ultimat3/flags`'
+`runtime.ts` (`source: 'process'`, severity `warning`). Trace and span resolve as a **pair** from
+one source: a caller-supplied `traceId` never picks up the ambient `spanId`, because a report
+claiming a span from a different trace sends whoever is paged somewhere authoritative and wrong.
+
+`ErrorReporterDsnInvalidError` (`X_ERROR_REPORTER_DSN_INVALID`) is the only code this seam owns —
+raised at `parseSentryDsn`, at configuration, never at a report.
+
 ## One cursor, everywhere
 
 ```ts
@@ -219,9 +418,10 @@ never a silently wrong page.
 | | |
 |---|---|
 | Signature | truncated HMAC-SHA256, compared in constant time |
-| Secret | `ULTIMATE_CURSOR_SECRET`, or `configureCursorSigning()` at boot. Rotating it invalidates every open cursor |
+| Secret | `configureCursorSigning()` at boot, else `ULTIMATE_CURSOR_SECRET`. **Read when a cursor is signed, never at import** — an app whose `openSecrets()` sets the variable during boot would otherwise sign every cursor with the dev key. Rotating it invalidates every open cursor |
 | Signed, not encrypted | the client already has these rows; what it must not do is *invent* a position |
 | `usesDevCursorSecret()` | true while the shipped dev key is in use |
+| `resetCursorSigning()` | test seam: forget `configureCursorSigning` and fall back to the environment |
 
 ## One image pipeline, everywhere
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/core",
-  "version": "1.2.0",
+  "version": "2.0.0",
   "description": "Ultimate's foundation: errors, context, env, config, clock, ids, logging, telemetry, lifecycle",
   "license": "MIT",
   "type": "module",
@@ -19,6 +19,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "CLAUDE.md",
     "README.md",
     "LICENSE"
   ],