@ultimat3/core 22.15.0 → 24.0.0

package/CLAUDE.md

@@ -48,6 +48,9 @@ top-level `UltimateError` use in `error-codes.ts`.
 - **A string's length is CODE POINTS** — `validators.ts` rejects in that unit and
   `json-schema.ts` publishes `minLength` in it. `parseId`/`uuidTimestamp` describe a rejected id and
   never echo it: a value baked into a message has no log field key to redact.
+- **A test never patches `process.stdout` to read a log line**: `setLogSink(sink)` is the seam, and the
+  test preloads install one that drops every line (`LOG_LEVEL` named = not installed). It decides
+  WHERE a line goes, never whether — the level is untouched.
 - `logger.ts` must not import `context.ts` (`context.ts` injects ids via `setLoggerContextFields()`).
   It imports `secret.ts` one way only: `secret.ts` owns `REDACTED`, `logger.ts` re-exports it.
 - **`ActorFacts` is the app's extension point on `Actor`** (module augmentation). Core never declares
@@ -57,8 +60,10 @@ 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` | never copied (`X_HELPER_COPY`) |
 | 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 rungs a cache ladder has | `cache-vocabulary.ts` (`CACHE_TIERS`) | `@ultimat3/cache`'s `TIER_ORDER` IS this array. `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()` |
@@ -71,15 +76,18 @@ top-level `UltimateError` use in `error-codes.ts`.
 | 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 |
-| the browser's one HTTP function, records envelope, per-tab handle and principal fence | `client-transport.ts`, `client-dispatch.ts`, `client-problem.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 `createClientFlight` 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). Byte figures (`As of 2026-09-23`): `clientTransport` 14,405 B, `pageClient` 8,853 B through the barrel, 332 B from its own module; `rpc`'s live in `packages/action/CLAUDE.md`, `queryClient`'s in `packages/query/CLAUDE.md` |
+| the browser's one HTTP function, records envelope, per-tab handle and principal fence | `client-transport.ts`, `client-dispatch.ts`, `client-problem.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 `createClientFlight` 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'`. Byte figures (`As of 2026-10-01`, `bun build --target=browser --minify`): `clientTransport` 14,251 B and `pageClient` 8,348 B through the barrel, 9,633 B and 1,156 B through `./page`; the whole `./page` entry 15,979 B against `page-bundle.test.ts`'s 16,384; `rpc`'s live in `packages/action/CLAUDE.md`, `queryClient`'s in `packages/query/CLAUDE.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 |
 | the four shapes of an async region | `async-state.ts` (`AsyncState`) | `realtime` returns it, `ui` renders it. `bun run render-modes` refuses a second status union sharing three members |
 | is this `unknown` a keyed record? | `json-object.ts` (`isJsonObject`) | narrows a shape; does not certify provenance |
+| 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` |
 | the text direction of a locale | `locale-direction.ts` (`directionOf`, `isRtl`, `Direction`) | re-exported by `@ultimat3/i18n`; lives here so `@ultimat3/ui` need not reach 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 |
 
 - **`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.
@@ -91,6 +99,14 @@ top-level `UltimateError` use in `error-codes.ts`.
   `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.
 - **`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 (`@ultimat3/auth`, `@ultimat3/storage`).
@@ -134,7 +150,10 @@ top-level `UltimateError` use in `error-codes.ts`.
 `metrics.ts` is to `telemetry.ts` what a counter is to a span: always on, no-op exporter by
 default. `runtime-metrics.ts` is the only place that names a series the chart reads
 (`http_requests_total`, `connections`, `queue_depth`), keyed by `ScalingSignal` in
-`SCALING_METRICS`. One call site per package; a second is the bug:
+`SCALING_METRICS`. `process-metrics.ts` names what the PROCESS costs (`process_*`: resident
+memory, heap, external, CPU seconds, event-loop lag, start time, `process_info{role}`); server-only
+— it reads `process`, so it is never exported from `page.ts`. One call site per package; a second
+is the bug:
 
 | Recorder | The one caller |
 |---|---|
@@ -177,6 +196,8 @@ default. `runtime-metrics.ts` is the only place that names a series the chart re
   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.
+- **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

package/README.md

@@ -32,29 +32,38 @@ Zero dependencies, zero `@ultimat3/*` imports.
 | 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` |
+| which store backs a seam — `storeMode(env)`: `memory` under `test`, `database` everywhere else | `store-mode.ts` |
 | the boot refusal of a shipped dev signing secret outside development/test — `X_CURSOR_SECRET_DEV` | `dev-secrets.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` |
+| one value sealed under the master key — `seal()` / `open()` | `seal.ts` |
+| the key ring those work under: the current key plus retired ones | `seal-keys.ts` |
 | `defineConfig()` for `app.config.ts` | `config.ts` |
 | how overlays layer onto it — per section, key by key | `config-merge.ts` |
+| what each key is when no layer says | `config-defaults.ts` |
+| the shape screens that run before any rule reads a value — section, list, boolean, closed set, path, locale list | `config-shape.ts` |
 | the `pwa` block — what an install needs, and the boot refusal when it is not there | `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` |
 | 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` |
+| structured JSON logging + redaction; `setLogSink(sink)` — the test seam that sends every default-writer line to a sink instead of the process's streams (a test preload drops them; a test asserting on the process logger collects them) | `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` |
+| 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` |
 | 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` |
+| what the process itself costs: `process_resident_memory_bytes`, `process_heap_used_bytes`, `process_heap_total_bytes`, `process_external_memory_bytes`, `process_cpu_seconds_total`, `process_event_loop_lag_seconds`, `process_start_time_seconds`, `process_info{role}` — **server-only**, never on `@ultimat3/core/page` | `process-metrics.ts` (`startProcessMetrics`, `readProcess`) |
 | 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` |
 | SIGTERM/SIGINT → the one drain | `lifecycle-signals.ts` |
 | which network an IP literal belongs to — `classifyAddress`, for SSRF screens | `address-class.ts` |
@@ -63,6 +72,13 @@ Zero dependencies, zero `@ultimat3/*` imports.
 | the registrar table one same-tier package reaches another through | `registrar.ts` |
 | decode → resize → encode, the one image pipeline (over `Bun.Image`) | `image/` |
 | `assertNever`, `invariant` | `assert.ts` |
+| 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` |
+| 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` |
+
+Each of the four, 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.
 
 ## Errors are instructions
 
@@ -193,9 +209,13 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | `OtlpEndpointInvalidError` | `X_OTLP_ENDPOINT_INVALID` | `src/otlp.ts` |
 | `OtlpHeadersInvalidError` | `X_OTLP_HEADERS_INVALID` | `src/otlp.ts` |
 | `OtlpProtocolUnsupportedError` | `X_OTLP_PROTOCOL_UNSUPPORTED` | `src/otlp.ts` |
+| `SealInvalidError` | `X_SEAL_INVALID` | `src/seal-errors.ts` |
+| `SealKeyMissingError` | `X_SEAL_KEY_MISSING` | `src/seal-errors.ts` |
+| `SealKeyUnknownError` | `X_SEAL_KEY_UNKNOWN` | `src/seal-errors.ts` |
 | `SecretsFileInvalidError` | `X_SECRETS_FILE_INVALID` | `src/secrets-errors.ts` |
 | `SecretsFileMissingError` | `X_SECRETS_FILE_MISSING` | `src/secrets-errors.ts` |
 | `SecretsKeyInvalidError` | `X_SECRETS_KEY_INVALID` | `src/secrets-errors.ts` |
+| `SecretsRingKeyInvalidError` | `X_SECRETS_KEY_INVALID` — a malformed entry of `ULTIMATE_SECRETS_RETIRED_KEYS` | `src/secrets-errors.ts` |
 | `SecretsKeyMismatchError` | `X_SECRETS_KEY_MISMATCH` | `src/secrets-errors.ts` |
 | `SecretsKeyMissingError` | `X_SECRETS_KEY_MISSING` | `src/secrets-errors.ts` |
 | `SecretsPlaintextInvalidError` | `X_SECRETS_PLAINTEXT_INVALID` | `src/secrets-errors.ts` |
@@ -305,6 +325,10 @@ fallback of its own; the caller does.
 is not our key. This is the twin of `roles.ts` — `ROLE` says what the process does,
 `ULTIMATE_ENV` says which deploy it belongs to.
 
+`storeMode(Bun.env)` is the one answer to "memory store or database store?" for a seam with both —
+`memory` under `test` (no database client is installed there), `database` everywhere else, `x dev`'s
+embedded PGlite included. Never a `DATABASE_URL` truthiness check: `x dev` sets none.
+
 ## A secret is redacted by value, not by name
 
 ```ts
@@ -313,7 +337,21 @@ logger.info('boot', { dsn });        // {"dsn":"[redacted]"}
 connect(revealSecret(dsn));          // the one greppable way out
 ```
 
-`redactKeys()` catches a secret travelling under a name someone remembered to list. A `Secret`
+`isRedactedKey(key)` is the one answer to "is this field a credential?" — the log line, the error
+monitor's envelope and `@ultimat3/action`'s audit row all ask it. It matches the exact names
+`redactKeys()` holds (`defineEnv` adds every `secret: true` variable) **and** a credential-bearing
+name it was never told about: `password` / `passphrase` anywhere, `secret` as the last word, any
+`…token` that is not a dedupe or paging key (`resetToken`, `githubToken`, `NPM_TOKEN`), key
+material by its qualifier (`signingKey`, `masterKey`, `accessKeyId`), a value that embeds a
+credential (`connectionString`, `dsn`, `databaseUrl`), the one-time codes
+(`totpCode`, `recoveryCode`) and a stored hash of any of them (`passwordHash`, `tokenHash`,
+`keyHash`). It deliberately leaves `idempotencyToken`, a paging token, `maxTokens` and an error
+`code` readable — a redacted field is one an operator cannot correlate on.
+
+`LOG_LEVEL` is refused when it is not one of `LOG_LEVELS` (lowercase), exactly as
+`createLogger({ level })` refuses it; unset or empty is `info`.
+
+A `Secret`
 box catches the other case: `String()`, template literals, `+`, `JSON.stringify`, `console.log`,
 the logger and an error's `meta` all render `[redacted]`, whatever key it sits under. It is
 frozen and everything but `label` is non-enumerable, so `{ ...dsn }` cannot spread the value back
@@ -350,6 +388,56 @@ A missing file is not an error — an app may declare no secrets. A file with **
 is `X_SECRETS_KEY_MISSING` and fatal: a process that booted past its secrets authenticates against
 nothing and still reports healthy.
 
+## Seal one value
+
+One function seals a value under the app's master key. Nothing above tier 0 writes its own AES call.
+
+```ts
+import { openText, seal } from '@ultimat3/core';
+
+export async function roundTrip(password: string): Promise<string> {
+  const purpose = 'scrape-session';
+  // 'x1.4f2a9c0d1e2b3a4f.<iv>.<ciphertext+tag>' — one string, base64url
+  const stored = await seal(password, { purpose });
+  return openText(stored, { purpose });
+}
+```
+
+A column is sealed by declaring it — `text().sealed()` in `@ultimat3/entity`, which derives the
+purpose `entity:<table>.<column>` and calls this. Call `seal()` yourself only for a value that is
+not a column.
+
+| Export | Signature | |
+|---|---|---|
+| `seal` | `(plaintext: string \| Uint8Array, options: SealOptions) => Promise<string>` | always under the CURRENT key |
+| `open` | `(sealed: string, options: SealPurposeOptions) => Promise<Uint8Array>` | picks the key the string names |
+| `openText` | `(sealed: string, options: SealPurposeOptions) => Promise<string>` | the string spelling; no JSON helper |
+| `sealAll` | `(plaintext: string \| Uint8Array, options: SealPurposeOptions) => Promise<readonly string[]>` | the deterministic seal under every declared key, current first |
+| `isSealed` | `(value: unknown) => value is string` | shape only — tells a legacy plaintext row from a sealed one |
+| `sealedKeyId` | `(sealed: string) => string` | what a re-seal `backfill()` compares to the current id |
+| `sealKeyIds` | `(source?: SealKeySource) => Promise<{ current: string; retired: readonly string[] }>` | ids, never keys |
+| `resolveSealKeys` | `(source?: SealKeySource) => Promise<SealKeyRing>` | the ring, resolved once — pass it as `keys` to seal or open MANY values in one operation |
+
+`SealPurposeOptions` is `{ purpose: string; root?: string; env?: Record<string, string | undefined> }`;
+`SealOptions` adds `deterministic?: boolean`. `root` and `env` default to the working directory and
+`process.env`, exactly as `installSecrets()` does. `keys?: SealKeyRing` skips that lookup: a batch
+resolves the ring once and hands it to every call — never kept past the operation, so the next one
+sees a rotation.
+
+| Rule | |
+|---|---|
+| Key | the one `x secrets` manages — `ULTIMATE_SECRETS_KEY` first, `.secrets.key` second. No second variable |
+| `purpose` | REQUIRED, bound as additional authenticated data with the key id: a value sealed for `scrape-session` does not open as `entity:connections.password` |
+| Wire form | `x1.<keyId>.<iv>.<ciphertext+tag>`. `keyId` is `masterKeyId`'s, so a rotated key is a named mismatch, never a garbled read |
+| Key ring | retired keys in `ULTIMATE_SECRETS_RETIRED_KEYS` (comma-separated hex). `x secrets rotate` writes the replaced key there, inside `secrets.enc.json`; `installSecrets()` carries it into the process; `x secrets rotate --drop <keyId>` removes it |
+| Refusals | `X_SEAL_KEY_MISSING`, `X_SEAL_KEY_UNKNOWN`, `X_SEAL_INVALID` — all terminal. Never garbage, never the raw string back, and no reading of an unsealed value |
+
+**`deterministic: true` reveals equality.** The IV is an HMAC of the purpose and the plaintext, so
+equal values seal to equal strings and a column can be matched by `=`. Anyone who can read the
+stored strings sees which rows hold the same value; never use it for a low-entropy value (a
+boolean, a status, a PIN). During a rotation one value has one sealed form per declared key —
+match with `sealAll()`; uniqueness cannot be held across keys.
+
 ## Time, ids, telemetry, drain
 
 - Never call `Date.now()`. Take a `Clock`; tests pass `frozenClock('2026-07-26T10:00:00Z')`.
@@ -497,7 +585,7 @@ never a silently wrong page.
 | | |
 |---|---|
 | Signature | truncated HMAC-SHA256, compared in constant time |
-| 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 |
+| Secret | `configureCursorSigning()` at boot, else `ULTIMATE_CURSOR_SECRET`. An EMPTY value is unset — never an empty HMAC key — so `usesDevCursorSecret()` reports it and the boot refuses it outside a local environment. **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 |
 | 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()` | true while the shipped dev key is in use |
@@ -592,7 +680,7 @@ nothing consulted it before deciding to try again. `As of 2026-08-23`.
 |---|---|---|
 | `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 |
 | `createSingleFlight({ deadlineMs?, schedule? })` → `run(key, work, join?)`, `size` | 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 |
-| `createFlightGate({ 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 |
+| `createFlightGate({ 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 |
 | `createFence(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 |
 | `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. `createClientFlight` is its one caller in the framework; `jobs`, `ai` and `db` each keep their own loop and delegate only the arithmetic and the classification |
@@ -614,6 +702,7 @@ read; `@ultimat3/jobs` re-exports both rather than keeping a second pair.
 |---|---|---|
 | `clientTransport({ method, url, body?, rawBody?, headers?, signal?, idempotencyKey?, flight?, fresh?, retry?, 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`. `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 |
+| `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 |
 | `rescope(principal)`, `onRescope(fn)`, `isSuperseded(error)` | the principal fence | a principal change bumps the epoch and notifies synchronously; reads in flight reject `X_CLIENT_SCOPE_CHANGED`, writes complete but their records are not adopted. `isSuperseded` answers true for it and for `X_SUPERSEDED` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/core",
-  "version": "22.15.0",
+  "version": "24.0.0",
   "description": "Ultimate's foundation: errors, context, env, config, clock, ids, logging, telemetry, lifecycle",
   "license": "MIT",
   "type": "module",
@@ -40,6 +40,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/schema": "22.15.0"
+    "@ultimat3/schema": "24.0.0"
   }
 }

package/src/client-paths.ts

@@ -1,10 +1,13 @@
 /**
  * The ONE URL rule for the two HTTP primitives: an action's export name derives `POST
- * /api/<resource>/<verb>`, a query's derives `GET /_x/query/<kebab>`. Tier 0 and pure string math,
- * so `action`, `query` and `realtime` (all tier 3) derive the same URL with no sideways import and
- * a browser bundle pays a few hundred bytes for it. Moved verbatim from both packages' `naming.ts`.
+ * /api/<resource>/<verb>`, a query's derives `GET /_x/query/<kebab>`. Tier 0 and string math, so
+ * `action`, `query` and `realtime` (all tier 3) derive the same URL with no sideways import and a
+ * browser bundle pays a few hundred bytes for it. The one thing read rather than computed is the
+ * style a caller did not name: `actionPath` takes it from the document the server rendered.
  */
 
+import { CLIENT_PATH_STYLE_META } from './page-meta';
+
 /** Irregular plurals we actually hit in domain models. A `Map`: the key is a caller's word. */
 const IRREGULAR: ReadonlyMap<string, string> = new Map([
   ['person', 'people'],
@@ -98,9 +101,26 @@ export function actionRoute(name: string, style: ActionPathStyle = 'resource'):
   return { verb: head, resource, path: `/api/${resource}/${head}` };
 }
 
-/** The path an action is POSTed to — `actionRoute(name, style).path`. */
-export function actionPath(name: string, style: ActionPathStyle = 'resource'): string {
-  return actionRoute(name, style).path;
+/**
+ * The style the SERVER stamped into this document (`<meta name="ultimate-path-style">`), or
+ * `undefined`: no document (a server, a worker, a script), no stamp (a `'resource'` server writes
+ * none), or a value this build does not know. A style is a runtime value and a type is erased, so
+ * this is the only way a browser learns it without the app restating it.
+ */
+export function renderedActionPathStyle(): ActionPathStyle | undefined {
+  const doc: { querySelector?: (selector: string) => { content?: unknown } | null } | undefined =
+    Reflect.get(globalThis, 'document');
+  const stamped = doc?.querySelector?.(`meta[name="${CLIENT_PATH_STYLE_META}"]`)?.content;
+  return ACTION_PATH_STYLES.find((known) => known === stamped);
+}
+
+/**
+ * The path an action is POSTed to. A caller that names no `style` gets the document's — every
+ * browser caller (`rpc`, `useMutation`, the outbox replay) derives under the one the server serves
+ * — and `'resource'` where there is no document to ask. A named style is never overridden.
+ */
+export function actionPath(name: string, style?: ActionPathStyle): string {
+  return actionRoute(name, style ?? renderedActionPathStyle() ?? 'resource').path;
 }
 
 /** `liveFeed` -> `/_x/query/live-feed`, read with `GET …?orgId=…`. */

package/src/config-defaults.ts

@@ -0,0 +1,46 @@
+// Single responsibility: the value every `app.config.ts` key has when no layer says otherwise.
+// Split from `config.ts`, which sits at its 500-line ceiling; literals only, so it reads no key.
+
+import type { AppConfig } from './config';
+import { defaultReadinessGraceMs } from './lifecycle-grace';
+import { ROLES } from './roles';
+
+/** The keys `config-site.ts`, `config-navigation.ts` and `config-islands.ts` default themselves. */
+type Sectioned = 'name' | 'site' | 'seo' | 'navigation' | 'islands';
+
+export function configDefaults(name: string): Omit<AppConfig, Sectioned> {
+  return {
+    locales: ['en'],
+    defaultLocale: 'en',
+    defaultTimeZone: 'UTC',
+    defaultCurrency: 'USD',
+    theme: { defaultMode: 'system', tokens: {} },
+    auth: { signInPath: null },
+    pwa: {
+      enabled: false,
+      offline: { fallback: null, image: null, font: null, neverCache: [], personalPages: 'never' },
+      backgroundSync: false,
+      push: false,
+      name: '',
+      colors: undefined,
+    },
+    roles: [...ROLES],
+    database: { driver: 'postgres', ssl: false },
+    cache: { defaultTtlMs: 60_000, tiers: ['request-memo', 'lru'] },
+    jobs: {
+      queues: [`${name}-default`],
+      concurrency: 8,
+      maxAttempts: 5,
+      backoff: 'exponential',
+      visibilityTimeoutMs: 30_000,
+    },
+    // ON by default since 22.0.0, when the boot began obeying the key: an app with no section
+    // keeps the `sync` node it always got, and `enabled: false` is the explicit opt-out.
+    realtime: { enabled: true, transport: 'memory', urlEnv: undefined },
+    notify: { inboxReadRetentionMs: undefined, inboxUnreadRetentionMs: undefined },
+    ai: { mcp: { expose: true, path: '/mcp' } },
+    // Read from the process env when the config is DEFINED — the same env the drain will run in.
+    drain: { readinessGraceMs: defaultReadinessGraceMs() },
+    health: { readiness: 'dependencies' },
+  };
+}

package/src/config-merge.ts

@@ -2,6 +2,8 @@
 // per section and key by key. Carries no config KEY on purpose: `config-readers` counts a property
 // access outside `config.ts` as a reader, so this file only ever sees sections as opaque records.
 
+import { isJsonObject } from './json-object';
+
 /** A section's patch: every key optional, and an explicit `undefined` meaning "not said". */
 export type Input<T> = { readonly [K in keyof T]?: T[K] | undefined };
 
@@ -11,6 +13,12 @@ export type Input<T> = { readonly [K in keyof T]?: T[K] | undefined };
  */
 export function section<T extends object>(base: T, patch: Input<T> | undefined): T {
   if (patch === undefined) return base;
+  // A layer that wrote something other than an object (`null`, a string, a list) has no key to
+  // merge, and `Object.entries(null)` below was a native `TypeError` out of the validator's own
+  // caller. It is carried through AS WRITTEN — and stays, whatever later layers say — so the shape
+  // screen refuses it by name; dropped here, the app would run on defaults it believed it replaced.
+  if (!isJsonObject(base)) return base;
+  if (!isJsonObject(patch)) return patch as T;
   const out: Record<string, unknown> = { ...(base as Record<string, unknown>) };
   for (const [key, value] of Object.entries(patch)) {
     if (value !== undefined) out[key] = value;

package/src/config-shape.ts

@@ -0,0 +1,112 @@
+// Single responsibility: the SHAPE half of `app.config.ts` validation — is this a section, a list,
+// a boolean, one of a closed set — asked before any rule reads the value. Takes every key as a
+// string and every value as `unknown`, and names no config key of its own: `config-readers` counts
+// a property access outside the declaring files as a reader, so this file must not make one.
+
+import { describeValue } from './error-render';
+import { isJsonObject } from './json-object';
+
+/** A string is worth echoing — it is the typo; anything else is described by shape. */
+const said = (value: unknown): string =>
+  typeof value === 'string' ? `"${value}"` : describeValue(value);
+
+/**
+ * Every section and list one LAYER wrote, compared with the same position in `reference` — the
+ * defaults merged with no layer, so the screen is derived and never a hand list of key names.
+ * Structure only: where the reference holds a section the layer may hold a section, where it holds
+ * a list, a list. `undefined` is a layer not saying; scalars are the per-key rules' business; and
+ * a position the reference leaves `null` or `undefined` (an optional block) is not judged here.
+ *
+ * It runs BEFORE the merge and its issues end the validation, because the merge and every rule
+ * after it read through the structure: `Object.entries(null)` and `null.length` are the native
+ * `TypeError`s the validator exists to replace with an instruction.
+ */
+export function shapeIssues(reference: unknown, layer: unknown, issues: string[], path = ''): void {
+  if (!isJsonObject(reference) || !isJsonObject(layer)) return;
+  for (const [key, expected] of Object.entries(reference)) {
+    const at = path === '' ? key : `${path}.${key}`;
+    const value: unknown = layer[key];
+    if (value === undefined) continue;
+    if (Array.isArray(expected)) {
+      if (!Array.isArray(value)) issues.push(`${at} must be a list, not ${describeValue(value)}`);
+    } else if (isJsonObject(expected)) {
+      if (isJsonObject(value)) shapeIssues(expected, value, issues, at);
+      else issues.push(`${at} must be an object, not ${describeValue(value)}`);
+    }
+  }
+}
+
+/** Why `value` is not one of `allowed`, or `undefined` when it is. */
+export function oneOfIssue(
+  key: string,
+  value: unknown,
+  allowed: readonly string[],
+): string | undefined {
+  if (allowed.some((known) => known === value)) return undefined;
+  return `${key} ${said(value)} is not one of ${allowed.join(', ')}`;
+}
+
+/**
+ * `typeof`, never truthiness: an untyped config writing `'false'` — a string out of an environment
+ * variable — is truthy, so the switch it meant to turn off stayed on and nothing said so.
+ */
+export function booleanIssue(key: string, value: unknown): string | undefined {
+  return typeof value === 'boolean'
+    ? undefined
+    : `${key} must be true or false, not ${said(value)}`;
+}
+
+/** A route path the framework mounts or redirects to: absolute, or the browser resolves it. */
+export function routePathIssue(key: string, value: unknown): string | undefined {
+  return typeof value === 'string' && value.startsWith('/')
+    ? undefined
+    : `${key} must be a path starting with /, not ${said(value)}`;
+}
+
+/** A list that names things: at least one entry, each a non-empty string, `what` each. */
+export function nameListIssues(
+  key: string,
+  list: readonly unknown[],
+  what: string,
+  issues: string[],
+): void {
+  if (list.length === 0) issues.push(`${key} must list at least one ${what}`);
+  for (const entry of list) {
+    if (typeof entry !== 'string' || entry.trim() === '') {
+      issues.push(`${key} contains ${said(entry)}, not a ${what} name`);
+    }
+  }
+}
+
+function canonicalTag(tag: unknown): string | undefined {
+  if (typeof tag !== 'string') return undefined;
+  try {
+    const canonical = Intl.getCanonicalLocales(tag);
+    return canonical.length === 1 ? canonical[0] : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The locale list and the tag that must be in it. Two spellings of ONE locale are refused: the
+ * list keys a catalog, a route prefix and an `hreflang` each, and `['EN', 'en']` is two of every
+ * one of them for a single language.
+ */
+export function localeIssues(tags: readonly unknown[], fallback: unknown, issues: string[]): void {
+  if (tags.length === 0) issues.push('locales must list at least one locale');
+  const seen = new Map<string, unknown>();
+  for (const tag of tags) {
+    const canonical = canonicalTag(tag);
+    if (canonical === undefined) {
+      issues.push(`locales contains ${said(tag)}, not a BCP-47 tag`);
+    } else if (seen.has(canonical)) {
+      issues.push(
+        `locales lists ${canonical} twice, as ${said(seen.get(canonical))} and ${said(tag)}`,
+      );
+    } else {
+      seen.set(canonical, tag);
+    }
+  }
+  if (!tags.includes(fallback)) issues.push(`defaultLocale ${said(fallback)} is not in locales`);
+}

package/src/config-site.ts

@@ -3,6 +3,7 @@
 // Split from `config.ts` for `config-pwa.ts`' reason: that file sits at its 500-line ceiling.
 
 import { type Input, layered } from './config-merge';
+import { describeValue } from './error-render';
 
 export interface SiteConfig {
   /**
@@ -108,10 +109,20 @@ export function siteIssues(config: SiteSections, issues: string[]): void {
     const issue = originIssue(origin);
     if (issue !== undefined) issues.push(issue);
   }
-  for (const path of config.seo.robots.disallow) {
-    if (!path.startsWith('/')) issues.push(`seo.robots.disallow entry "${path}" must start with /`);
+  // `unknown` entries: an untyped config reaches here with whatever it listed, and `5.startsWith`
+  // was a native `TypeError` thrown by the validator itself.
+  for (const path of config.seo.robots.disallow as readonly unknown[]) {
+    if (typeof path !== 'string') {
+      issues.push(`seo.robots.disallow entry must be a path string, not ${describeValue(path)}`);
+    } else if (!path.startsWith('/')) {
+      issues.push(`seo.robots.disallow entry "${path}" must start with /`);
+    }
   }
-  for (const path of config.seo.sitemap.extra) {
+  for (const path of config.seo.sitemap.extra as readonly unknown[]) {
+    if (typeof path !== 'string') {
+      issues.push(`seo.sitemap.extra entry must be a path string, not ${describeValue(path)}`);
+      continue;
+    }
     // A PATH, never a URL: every `<loc>` is built against the one declared origin, and a query or
     // a fragment names a variant of a page, which a sitemap lists by its canonical URL alone.
     if (!path.startsWith('/') || path.startsWith('//') || /[?#]/.test(path)) {