@ultimat3/core 23.0.0 → 25.0.0

package/CLAUDE.md

@@ -40,11 +40,10 @@ top-level `UltimateError` use in `error-codes.ts`.
 - **`singleLine` keeps the 3-line contract to three lines, applied in the CONSTRUCTOR** so every
   door (`format()`, `.message`, `.cause`, `toJSON()`) is covered once. It touches only C0 controls
   and DEL — a cause keeps its quotes and backslashes. `@ultimat3/schema` carries a deliberate
-  duplicate, pinned by `single-line-pin.test.ts` HERE, with `ERROR_DOCS_URL` and the brand key.
-- **`core → schema` is declared, and the five former copies are gone** (`describeValue`,
-  `charCount`, `CURRENCY_CODE_PATTERN`, `SCHEMA_ERROR_CODES`, `isIanaZoneName`). Its bundle cost is
-  measured in `docs/architecture/01-package-map.md`; it depends on `@ultimat3/schema` keeping
-  `sideEffects: false`.
+  duplicate, pinned by `single-line-pin.test.ts` HERE, with `ERROR_DOCS_URL`. The brand symbol is
+  NOT a copy: `ULTIMATE_ERROR_BRAND` is schema's one declaration, imported by `errors.ts`.
+- **`core → schema` is declared: import a schema value, never copy it.** Bundle cost:
+  `docs/architecture/01-package-map.md`; it depends on `@ultimat3/schema` keeping `sideEffects: false`.
 - **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.
@@ -60,9 +59,11 @@ 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`) |
 | 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 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 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 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 |
@@ -73,15 +74,19 @@ top-level `UltimateError` use in `error-codes.ts`.
 | 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 |
-| 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` |
+| 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 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 |
 | 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 |
+| the audit record + one sink | `audit.ts` | `action` + `query`; `AUDIT_RECORD_FIELDS` pins both |
 | 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 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 |
 
@@ -105,7 +110,7 @@ top-level `UltimateError` use in `error-codes.ts`.
   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`).
+- `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
@@ -117,8 +122,7 @@ top-level `UltimateError` use in `error-codes.ts`.
   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. Not mechanised — review catches a
-  third copy.
+  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`,
   `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
@@ -130,7 +134,7 @@ top-level `UltimateError` use in `error-codes.ts`.
   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.
-- **`createFlightGate` HANDS its slot to a waiter** rather than releasing it. `X_FLIGHT_GATE_OVERLOADED`
+- **`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
@@ -143,13 +147,11 @@ top-level `UltimateError` use in `error-codes.ts`.
 
 ## Metrics, tracing, reporting
 
-`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`. `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:
+`metrics.ts`: counters (spans are `telemetry.ts`), always on, no-op exporter by default.
+`runtime-metrics.ts` alone names a series the chart reads (`http_requests_total`, `connections`,
+`queue_depth`), keyed by `ScalingSignal` in `SCALING_METRICS`. `process-metrics.ts`: `process_*`
+(resident memory, heap, external, CPU seconds, event-loop lag, start time, `process_info{role}`);
+server-only, never on `page.ts`. One call site per recorder; a second is the bug:
 
 | Recorder | The one caller |
 |---|---|
@@ -192,6 +194,8 @@ is the bug:
   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
@@ -212,8 +216,8 @@ bun test packages/core/src    # from the REPO ROOT, never from packages/core
 bun run typecheck
 ```
 
-The root is not a preference: `bunfig.toml`'s preload installs `@ultimat3/testing`'s matchers, and
-Bun reads `bunfig.toml` from the cwd (`scripts/coverage-gate.ts` runs from the root for the same reason).
+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`.
@@ -221,12 +225,11 @@ Gotchas:
 - `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 `createContext` holds the framework's ONE irreducible
+- **`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 `createRequestContext` composes `createContext()` and has no assertion.
-  Four alternatives were measured and refused (listed in the file header); the structural repair is
-  a major, alongside the index-signature deletion.
+  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.

package/README.md

@@ -28,20 +28,28 @@ Zero dependencies, zero `@ultimat3/*` imports.
 | which principal the page acts for, and the epoch that moves when it changes | `client-scope.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` |
 | is this `unknown` a keyed record? | `json-object.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` |
+| 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` |
+| a key file only its owner can read — 0600, and an `icacls` ACL on Windows — written via temp + rename, the rename retried on EPERM/EBUSY (`writeMasterKeyFile`, `stageMasterKeyFile`, `promoteStagedMasterKey`) | `secrets-key-file.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 | `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` |
+| `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` |
 | runtime roles + `ROLE` resolution | `roles.ts` |
 | `Clock` — the only source of "now" | `clock.ts` |
 | UUIDv7, nanoid, branded ids | `ids.ts` |
@@ -51,6 +59,7 @@ Zero dependencies, zero `@ultimat3/*` imports.
 | 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` |
@@ -58,14 +67,29 @@ Zero dependencies, zero `@ultimat3/*` imports.
 | 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` |
+| the drain budget's default and domain (`drain.deadlineMs`, 25 s, 1–3600000 ms) — `DRAIN_DEADLINE_DEFAULT_MS`, `DRAIN_DEADLINE_MAX_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` |
+| 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` |
 | 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` |
+| `assertNever`, `assertCoded`, `assert` | `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` |
+| 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` |
+| 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` |
+
+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.
 
 ## Errors are instructions
 
@@ -179,9 +203,9 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | Class | Code | Declared in |
 |---|---|---|
 | `ConfigInvalidError` | `X_CONFIG_INVALID` | `src/errors.ts` |
+| `CookieInvalidError` | `X_COOKIE_INVALID` | `src/cookie.ts` |
 | `CursorInvalidError` | `X_CURSOR_INVALID` | `src/cursor.ts` |
 | `CursorSecretDevError` | `X_CURSOR_SECRET_DEV` | `src/dev-secrets.ts` |
-| `EnvExampleDriftError` | `X_ENV_EXAMPLE_DRIFT` | `src/env-example.ts` |
 | `EnvironmentInvalidError` | `X_ENVIRONMENT_INVALID` | `src/environment.ts` |
 | `EnvMissingError` | `X_ENV_MISSING` | `src/errors.ts` |
 | `ErrorReporterDsnInvalidError` | `X_ERROR_REPORTER_DSN_INVALID` | `src/error-reporter-sentry.ts` |
@@ -201,6 +225,7 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | `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` |
+| `SecretsKeyAclError` | `X_SECRETS_KEY_ACL_FAILED` — Windows only: `icacls` could not restrict a new key file, so none was written | `src/secrets-key-file.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` |
@@ -212,7 +237,7 @@ a job boundary the class is gone and the `code` is what survives — match on th
 ## Context
 
 ```ts
-const ctx = createContext({ actor: agentActor({ id: 'mcp-1', scopes: ['post:publish'] }) });
+const ctx = ctxOf({ actor: agentActor({ id: 'mcp-1', scopes: ['post:publish'] }) });
 await runWithContext(ctx, async () => {
   const { actor, locale, tz, logger } = useContext();   // throws X_NO_CONTEXT outside
   await withChildContext({ locale: 'es' }, () => render());
@@ -224,13 +249,13 @@ automatically; so does the root `logger` while a context is active. Add typed se
 augmenting `CtxServices`; reach late-bound ones with `useService<T>('mail')`.
 
 A service that reads the actor (`ctx.posts`, scoped to `ctx.actor.orgId`) registers once with
-`defineService('posts', (ctx) => ({ ... }))`, at import time. `createContext` and
+`defineService('posts', (ctx) => ({ ... }))`, at import time. `ctxOf` and
 `withChildContext` then build it fresh, bound to whichever actor they are constructing a ctx
 for — importing the module that calls `defineService` is the registration, the same convention
-`registerActions` uses. Passing `services: { posts: ... }` to `createContext` still works and
+`registerActions` uses. Passing `services: { posts: ... }` to `ctxOf` still works and
 wins over a registered factory of the same name, for a test that wants to hand in a mock.
 
-A factory runs again on **every** `createContext` / `withChildContext` call and is never cached,
+A factory runs again on **every** `ctxOf` / `withChildContext` call and is never cached,
 because it closes over the ctx (actor, clock, tz) it was built for. `withChildContext` drops a
 factory-managed name from what it carries forward on purpose: only an ad hoc service nobody
 registered survives an actor swap unrebuilt.
@@ -283,9 +308,11 @@ safe for `x.manifest.json`. Omit `required` for required — `required: false` i
 loosening. Never declare an env var for *which deploy this is* — that is `ULTIMATE_ENV`, below.
 
 `.env.example` is a **projection** of that schema, never a second list:
-`renderEnvExample(schema)` writes it, `assertEnvExample(schema, text)` fails with
-`X_ENV_EXAMPLE_DRIFT` when a declared key has no line — the failure that otherwise arrives as
-somebody else's `X_ENV_MISSING` on a variable nobody documented.
+`renderEnvExample(schema)` writes it and `checkEnvExample(schema, text)` reports `missing` /
+`extra` as data. The gate is `x verify`'s `manifest` step (`X_ENV_EXAMPLE_DRIFT`, fixed by
+`x env example`) — the failure that otherwise arrives as somebody else's `X_ENV_MISSING` on a
+variable nobody documented. `assertEnvExample` (key presence only, called by nothing) was deleted
+in 25.0.0.
 
 Loading `.env` is **Bun's**, not ours. `envFileCandidates()` states what it does, measured:
 `.env` → `.env.<mode>` → `.env.local`, with `.env.local` skipped under test, and the mode being
@@ -312,6 +339,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
@@ -320,7 +351,24 @@ 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`), session and bearer material (`credentials`, `jwt`, `bearer`,
+`cookie`, `sessionId`, `sessionKey`, `privateKeyPem`), card data (`cvv`, `cvc`, a whole-word `pin`
+such as `cardPin` or `pinCode`) and a stored hash of any of them (`passwordHash`, `tokenHash`,
+`keyHash`). `@ultimat3/action` also asks it before storing an idempotent answer. It deliberately
+leaves `idempotencyToken`, a paging token, `maxTokens`, an error `code`, `spinner`, `isPinned`,
+`sessionStart` and `cookieName` 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
+`structuredLogger({ 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
@@ -410,11 +458,11 @@ 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')`.
-- `uuid()` is UUIDv7: time-prefixed, monotonic within a millisecond, never backwards on clock
+- `uuidV7()` 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()`, whose ids come from
-  `traceId()` / `spanId()` — **never `uuid()`**, whose dashed 36 characters every collector
+  `traceId()` / `spanId()` — **never `uuidV7()`**, 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
@@ -554,12 +602,28 @@ 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 |
+| `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 |
+| `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 |
 
+### One page shape
+
+`Page<Row>` (`src/cursor-page.ts`) is what every cursor page answers — an entity `findMany`, a
+`query`'s `.page()`, the `?_first=` HTTP envelope and the typed client: `{ rows, nextCursor,
+hasMore }`, with ONE meaning. `nextCursor` is the cursor for the next page and `null` exactly when
+`hasMore` is false, so `while (page.hasMore)` and `while (page.nextCursor !== null)` are the same
+loop and both stop on the last page without fetching an empty one.
+
+| | |
+|---|---|
+| The type | a union of `{ nextCursor: string; hasMore: true }` and `{ nextCursor: null; hasMore: false }` — a literal that disagrees is a build error (`type-pins.ts`), and `if (page.hasMore)` narrows `nextCursor` to `string` |
+| `pageOf(rows, nextCursor)` | the only constructor: `hasMore` is derived from the cursor, never passed beside it. `null` (or `''`) is the last page |
+| Re-exported | by `@ultimat3/query` as its `Page`; `@ultimat3/entity` exports none — import it from here |
+
 ## One bounded cache for every `Intl` formatter
 
 ```ts
@@ -607,16 +671,16 @@ prose has none.
 ```ts
 import {
   backoffDelay,
-  createFence,
-  createFlightGate,
-  createSingleFlight,
+  generationFence,
+  flightGate,
+  singleFlight,
   isRetryableStatus,
 } from '@ultimat3/core';
 
 // One ceiling on work whose cost is memory, one run per key, one fence over the answer.
-const gate = createFlightGate({ maxConcurrent: 8, maxQueued: 64 }, { subject: 'jwks fetches' });
-const flights = createSingleFlight({ deadlineMs: 30_000 });
-const fence = createFence('the jwks cache');
+const gate = flightGate({ maxConcurrent: 8, maxQueued: 64 }, { subject: 'jwks fetches' });
+const flights = singleFlight({ deadlineMs: 30_000 });
+const fence = generationFence('the jwks cache');
 
 export async function jwks(url: string): Promise<Response> {
   const issued = fence.generation();
@@ -648,14 +712,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 |
-| `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 |
-| `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 `<` |
+| `singleFlight({ 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 |
+| `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 |
-| `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 |
-| `createClientFlight({ 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` re-export it verbatim — it is one file because both are tier 3 and neither may import the other |
+| `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 |
+| `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)`, `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 |
+| `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 |
+| `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
 without jitter IS the thundering herd, so the mode is a decision each caller makes rather than one
@@ -678,7 +746,7 @@ read; `@ultimat3/jobs` re-exports both rather than keeping a second pair.
 | `resolveConflict(policy, local, server, { clockField? })`, `ConflictPolicy`, `Row` | one conflict vocabulary, over ROWS | `last-write-wins` keeps the local row only when its numeric clock field (default `updatedAt`) is newer; no provable clock = the server's row |
 | `AsyncState<T>` | `pending \| refreshing \| ready \| failed` | the type `realtime` produces and `ui` renders; tier 0 because neither may import the other |
 
-`clientTransport` does not value-import `createClientFlight` or `traceHeaders()` — measured sizes
+`clientTransport` does not value-import `clientFlight` or `traceHeaders()` — measured sizes
 are in its file header. A server-side caller that propagates a trace passes `traceHeaders()` in
 `headers` itself.
 
@@ -732,9 +800,9 @@ is read, mapping it onto `X_IMAGE_UNSUPPORTED` / `X_IMAGE_TOO_LARGE` / `X_IMAGE_
 caller branches on a Bun code.
 
 Two files in `image/` are past the 200-line target and neither splits without inventing a seam:
-`probe.ts` is one algorithm per format over header bytes, and `fixtures.ts` is data. The 500-line
+`probe.ts` is one algorithm per format over header bytes, and `image-fixture.ts` is data. The 500-line
 hard ceiling applies to both. Everything else in `image/` is under the target — deleting the
 hand-rolled JPEG and PNG codecs is what put it there.
 
-`image/fixtures.ts` is byte-exact output from Pillow and ffmpeg on purpose: a codec that only round
+`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.

package/package.json

@@ -1,15 +1,12 @@
 {
   "name": "@ultimat3/core",
-  "version": "23.0.0",
+  "version": "25.0.0",
   "description": "Ultimate's foundation: errors, context, env, config, clock, ids, logging, telemetry, lifecycle",
   "license": "MIT",
   "type": "module",
   "sideEffects": [
-    "./src/context.ts",
     "./src/core-error-codes.ts",
-    "./src/lifecycle-errors.ts",
-    "./src/schema-error-codes.ts",
-    "./src/secrets-errors.ts"
+    "./src/schema-error-codes.ts"
   ],
   "repository": {
     "type": "git",
@@ -33,13 +30,13 @@
     "LICENSE"
   ],
   "engines": {
-    "bun": ">=1.4.0"
+    "bun": ">=1.4.2"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/schema": "23.0.0"
+    "@ultimat3/schema": "25.0.0"
   }
 }

package/src/actor.ts

@@ -185,6 +185,15 @@ export function isAnonymous(actor: Actor): boolean {
   return actor.kind === 'anonymous';
 }
 
+/**
+ * The context's actor as a policy reads it: core models "nobody" as the anonymous actor, policy as
+ * `null` — the value that turns a missing session into `X_UNAUTHENTICATED` instead of a bare
+ * denial. Declared here, once, so action, query, MCP and a page all map it the same way.
+ */
+export function actorOf(ctx: { readonly actor: Actor }): Actor | null {
+  return isAnonymous(ctx.actor) ? null : ctx.actor;
+}
+
 export function hasRole(actor: Actor, role: string): boolean {
   return actor.roles.includes(role);
 }

package/src/address-class.ts

@@ -119,16 +119,22 @@ function classifyV6(g: readonly number[]): AddressClass {
   return 'public';
 }
 
+/** The literal itself: trimmed, unbracketed, its IPv6 zone id dropped. */
+function literalOf(address: string): string {
+  let text = address.trim();
+  if (text.startsWith('[') && text.endsWith(']')) text = text.slice(1, -1);
+  const zone = text.indexOf('%');
+  if (zone !== -1 && text.includes(':')) text = text.slice(0, zone);
+  return text;
+}
+
 /**
  * The class of an IP address LITERAL — IPv4, IPv6, bracketed `[::1]`, a zone id `fe80::1%eth0`,
  * and every IPv6 form carrying an IPv4 address. `undefined` means "not an address literal": a
  * hostname must be resolved first and each resolved address classified, never this string.
  */
 export function classifyAddress(address: string): AddressClass | undefined {
-  let text = address.trim();
-  if (text.startsWith('[') && text.endsWith(']')) text = text.slice(1, -1);
-  const zone = text.indexOf('%');
-  if (zone !== -1 && text.includes(':')) text = text.slice(0, zone);
+  const text = literalOf(address);
   if (text.includes(':')) {
     const groups = parseV6(text);
     return groups === undefined ? undefined : classifyV6(groups);
@@ -141,3 +147,33 @@ export function classifyAddress(address: string): AddressClass | undefined {
 export function isPublicAddress(address: string): boolean {
   return classifyAddress(address) === 'public';
 }
+
+/**
+ * The NETWORK a caller's address names, for keying a per-caller budget: IPv4 as itself, an
+ * IPv4-mapped IPv6 (`::ffff:a.b.c.d`) as the IPv4 it carries, any other IPv6 as its /64 in RFC 5952
+ * form (`2001:db8:1:2::/64`). A /64 is the smallest block one subscriber is handed, so keying on
+ * the full IPv6 string gave one host ~2^64 budgets. Anything that is not an address literal is
+ * returned unchanged — the caller's key stays whatever it was, never a guessed network.
+ */
+export function addressNetwork(address: string): string {
+  const text = literalOf(address);
+  if (!text.includes(':')) {
+    const v4 = parseV4(text);
+    return v4 === undefined ? address : text;
+  }
+  const g = parseV6(text);
+  if (g === undefined) return address;
+  if (g.slice(0, 5).every((group) => group === 0) && g[5] === 0xffff) {
+    const v4 = embeddedV4(g);
+    return [24, 16, 8, 0].map((shift) => String(Math.floor(v4 / 2 ** shift) % 256)).join('.');
+  }
+  const prefix = g.slice(0, 4);
+  // RFC 5952: the zero run reaching into the (zero) interface half is always the longest, so
+  // compression starts at the first zero group from which the prefix stays zero.
+  let cut = 4;
+  while (cut > 0 && prefix[cut - 1] === 0) cut -= 1;
+  return `${prefix
+    .slice(0, cut)
+    .map((group) => group.toString(16))
+    .join(':')}::/64`;
+}

package/src/assert.ts

@@ -4,7 +4,7 @@
 import { renderCauseValue } from './error-render';
 import { UltimateError } from './errors';
 
-export interface InvariantOptions {
+export interface AssertCodedOptions {
   readonly docs?: string | undefined;
   readonly meta?: Readonly<Record<string, unknown>> | undefined;
 }
@@ -25,12 +25,16 @@ export function assertNever(value: never, fix?: string): never {
   });
 }
 
-export function invariant(
+/**
+ * Throw `code` with `cause` and `fix` unless `condition` holds — `assert` with a dedicated code.
+ * Not `invariant`: that name is `@ultimat3/entity`'s, the declaration of an entity invariant.
+ */
+export function assertCoded(
   condition: unknown,
   code: string,
   cause: string,
   fix: string,
-  options?: InvariantOptions,
+  options?: AssertCodedOptions,
 ): asserts condition {
   if (condition) return;
   throw new UltimateError({
@@ -42,7 +46,7 @@ export function invariant(
   });
 }
 
-/** `invariant` with the generic code, for checks that have no dedicated code yet. */
+/** `assertCoded` with the generic code, for checks that have no dedicated code yet. */
 export function assert(condition: unknown, cause: string, fix: string): asserts condition {
-  invariant(condition, 'X_INVARIANT', cause, fix);
+  assertCoded(condition, 'X_INVARIANT', cause, fix);
 }