@ultimat3/core 22.15.0 → 23.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
@@ -71,7 +74,7 @@ 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 |
@@ -80,6 +83,7 @@ top-level `UltimateError` use in `error-codes.ts`.
 | 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 +95,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 +146,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 |
 |---|---|

package/README.md

@@ -36,6 +36,8 @@ Zero dependencies, zero `@ultimat3/*` imports.
 | 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` |
 | the `pwa` block — what an install needs, and the boot refusal when it is not there | `config-pwa.ts` |
@@ -43,7 +45,7 @@ Zero dependencies, zero `@ultimat3/*` imports.
 | 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` |
@@ -54,6 +56,7 @@ Zero dependencies, zero `@ultimat3/*` imports.
 | 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` |
 | the readiness grace between `/readyz` → 503 and the listener closing (`drain.readinessGraceMs`) | `lifecycle-grace.ts` |
 | SIGTERM/SIGINT → the one drain | `lifecycle-signals.ts` |
@@ -193,9 +196,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` |
@@ -350,6 +357,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')`.
@@ -614,6 +671,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": "23.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": "23.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/core-error-codes.ts

@@ -54,6 +54,11 @@ const CORE_CODE_TITLES = {
   X_REGISTRAR_CONFLICT: 'two different registrars are loaded for one primitive kind',
   X_REGISTRAR_MISSING: 'no registrar is loaded for a primitive kind',
   X_ROLE_INVALID: 'ROLE is not a known runtime role',
+  // `seal.ts`'s three. Titled here, not registered beside their classes the way the X_SECRETS_*
+  // set is, so `seal-errors.ts` runs nothing at import and is no `sideEffects` anchor.
+  X_SEAL_INVALID: 'a sealed value did not authenticate, or is not a sealed value',
+  X_SEAL_KEY_MISSING: 'no master key to seal or open a value with',
+  X_SEAL_KEY_UNKNOWN: 'a sealed value names a master key this process does not declare',
   X_SERVICE_DUPLICATE: 'a service name is registered twice',
   X_SERVICE_MISSING: 'service is not registered on the request context',
   X_SHUTDOWN_TIMEOUT: 'graceful shutdown exceeded its deadline',

package/src/error-render.ts

@@ -188,9 +188,11 @@ export function renderFixLiteral(value: unknown, placeholder: string): string {
  * denylist has to be right about every character every shell will ever read, and this only has to
  * be right about the ones a fix line needs. No space, so a value is always one word; no leading
  * `-` or `~`, because an argument starting with either is an OPTION or a home directory rather
- * than the value it reads as.
+ * than the value it reads as. A leading `@` IS carried: a scoped package name starts with one, and
+ * `@` opens nothing in a POSIX shell — `$@` needs the `$`, an extglob `@(…)` the parenthesis, and
+ * neither is in the set.
  */
-const SHELL_ARG_SAFE = /^[A-Za-z0-9/][A-Za-z0-9._:/@=+,%~-]*$/;
+const SHELL_ARG_SAFE = /^[A-Za-z0-9/@][A-Za-z0-9._:/@=+,%~-]*$/;
 
 /**
  * The same value where the text is read by a SHELL. A `fix:` is a command meant to be pasted, so a

package/src/error-retry.ts

@@ -61,6 +61,14 @@ const CORE_ERROR_RETRY: ReadonlyMap<string, ErrorRetry> = new Map(
     // The principal fence's twin of `X_SUPERSEDED`, listed for the same reason: re-sending a read
     // from the previous principal's scope is refused identically every time.
     X_CLIENT_SCOPE_CHANGED: 'terminal',
+    // `seal.ts`'s three, listed for `X_NOT_IMPLEMENTED`'s reason: a missing key, an undeclared
+    // key and a value that failed its tag are each the same answer on attempt five, and left
+    // unclassified a job opening a sealed column would spend its whole retry policy re-proving it.
+    // Here rather than through `registerErrorRetry` because they are core's own codes, which that
+    // function refuses, and a module-scope call would make `seal-errors.ts` a side-effect anchor.
+    X_SEAL_INVALID: 'terminal',
+    X_SEAL_KEY_MISSING: 'terminal',
+    X_SEAL_KEY_UNKNOWN: 'terminal',
   } as const),
 );
 

package/src/index.ts

@@ -585,6 +585,9 @@ export type { Direction } from './locale-direction';
 export { directionOf, isRtl } from './locale-direction';
 export type { LocalePathSplit } from './locale-path';
 export { localeSegment, localizePath, splitLocalePath } from './locale-path';
+// The process logger's test seam, beside nothing it groups with: where a default-writer line goes.
+export type { LogSink } from './logger';
+export { setLogSink } from './logger';
 export { isMcpExposed, type McpExposureDeclaration } from './mcp-exposure';
 export type { MeasurementActorFactory } from './measurement-actor';
 export {
@@ -604,12 +607,15 @@ export {
   CLIENT_NAVIGATION_LOCATION_HEADER,
   CLIENT_NAVIGATION_SCOPE_HEADER,
   CLIENT_NAVIGATION_SURFACE_HEADER,
+  CLIENT_PATH_STYLE_META,
   CLIENT_PERSIST_META,
   CLIENT_SCOPE_HEADER,
   CLIENT_SCOPE_META,
   CLIENT_SYNC_META,
   CLIENT_SYNC_WORKER_META,
 } from './page-meta';
+export type { ProcessMetricsOptions, ProcessReading } from './process-metrics';
+export { readProcess, resetProcessMetrics, startProcessMetrics } from './process-metrics';
 export { type CappedBody, readWithinLimit } from './read-capped';
 export type { RecordEnvelope, RecordRows } from './record-envelope';
 export { decodeRecordEnvelope, encodeRecordEnvelope, RECORDS_HEADER } from './record-envelope';
@@ -648,6 +654,20 @@ export {
   type OriginVerdict,
   proveSameOrigin,
 } from './same-origin';
+export type { SealOptions, SealPurposeOptions } from './seal';
+export { isSealed, open, openText, SEAL_VERSION, seal, sealAll, sealedKeyId } from './seal';
+export type { SealInvalidReason } from './seal-errors';
+export { SealInvalidError, SealKeyMissingError, SealKeyUnknownError } from './seal-errors';
+export type { SealKeyRing, SealKeySource } from './seal-keys';
+export {
+  resolveSealKeys,
+  SECRETS_RETIRED_KEYS_ENV,
+  sealKeyIds,
+  splitRetiredKeys,
+} from './seal-keys';
+// Beside the ring it is raised for, not in the `exports/secrets` group: same code as
+// `SecretsKeyInvalidError`, a different variable to repair.
+export { SecretsRingKeyInvalidError } from './secrets-errors';
 export {
   defineService,
   installedServices,

package/src/logger.ts

@@ -121,6 +121,28 @@ export function setLogStream(stream: 'stdout' | 'stderr'): void {
   logStream = stream;
 }
 
+/** What `setLogSink` installs: one complete JSON line, and the level it was written at. */
+export type LogSink = (line: string, level: LogLevel) => void;
+
+let logSink: LogSink | undefined;
+
+/**
+ * TEST SEAM. Every line with no explicit `writer` goes to `sink` INSTEAD of the process's streams,
+ * until it is cleared with `undefined`. Returns the sink that was installed, so a caller restores
+ * rather than clears — the shape `setRowObserver` has, for the same shared-process reason.
+ *
+ * It exists for two callers. A test preload installs a sink that drops every line, so a green run
+ * prints its reporter and nothing else; and a test that asserts on what the PROCESS logger wrote
+ * installs one that collects, instead of patching `process.stdout`. A logger given its own
+ * `writer` never reaches it, and the level is untouched: this decides where a line goes, never
+ * whether it is written.
+ */
+export function setLogSink(sink: LogSink | undefined): LogSink | undefined {
+  const previous = logSink;
+  logSink = sink;
+  return previous;
+}
+
 /**
  * The second half of the same defect, one call deeper than `envLevel`. A module init made safe
  * that still reached `process.stdout` here would only move the `ReferenceError` from load to the
@@ -135,6 +157,10 @@ export function setLogStream(stream: 'stdout' | 'stderr'): void {
  * its log stream, and where there is a `process` this writes to the fd as it always did.
  */
 function defaultWriter(line: string, level: LogLevel): void {
+  if (logSink !== undefined) {
+    logSink(line, level);
+    return;
+  }
   const toStderr = logStream === 'stderr' || LEVEL_WEIGHT[level] >= LEVEL_WEIGHT.error;
   if (typeof process === 'undefined') {
     if (toStderr) console.error(line);

package/src/page-meta.ts

@@ -27,6 +27,13 @@ export const CLIENT_BUILD_META = 'x-ultimate-build';
  */
 export const APP_UPDATE_MESSAGE = 'AppUpdateAvailable';
 
+/**
+ * How this server turns an action's name into its URL (`defineApi({ http: { pathStyle } })`), for
+ * the browser's `actionPath`. Written only for a style other than the default: absent IS
+ * `'resource'`, so an app that declares nothing renders the bytes it always did.
+ */
+export const CLIENT_PATH_STYLE_META = 'ultimate-path-style';
+
 /** Where the page's one socket dials: `/_x/sync`, or the deployment's absolute `SYNC_URL`. */
 export const CLIENT_SYNC_META = 'ultimate-sync';
 

package/src/page.ts

@@ -43,6 +43,7 @@ export {
   CLIENT_NAVIGATION_LOCATION_HEADER,
   CLIENT_NAVIGATION_SCOPE_HEADER,
   CLIENT_NAVIGATION_SURFACE_HEADER,
+  CLIENT_PATH_STYLE_META,
   CLIENT_PERSIST_META,
   CLIENT_SCOPE_HEADER,
   CLIENT_SCOPE_META,

package/src/process-metrics.ts

@@ -0,0 +1,206 @@
+// Single responsibility: the series every Ultimate PROCESS emits about itself — memory, CPU,
+// event-loop lag, start time and which role it is. `runtime-metrics.ts` names what a role does;
+// this names what the process costs, so "what is growing?" is a query and not a guess. Runs
+// nothing at import: the first `startProcessMetrics()` declares the instruments.
+
+import { type Clock, systemClock } from './clock';
+import { finiteCount } from './finite-option';
+import type { Counter, Gauge, Histogram } from './metrics';
+import { counter, gauge, histogram } from './metrics';
+
+/**
+ * One reading of the process, in bytes and seconds — everything `process` answers in microseconds.
+ * No object count and no collection count: `bun:jsc`'s `heapStats()` runs a full collection to
+ * answer (9 ms on an empty framework process, measured 2026-10-01), which a scrape must not cause.
+ */
+export interface ProcessReading {
+  /** Resident set size: what the kernel charges the container for. */
+  readonly rss: number;
+  /** Bytes of JavaScript heap in use, garbage not yet collected included. */
+  readonly heapUsed: number;
+  /** Bytes the engine has reserved for the heap, used or not. */
+  readonly heapTotal: number;
+  /** Bytes held outside the heap on behalf of heap objects: buffers, strings, compiled code. */
+  readonly external: number;
+  /** User plus system CPU seconds consumed since the process started. */
+  readonly cpuSeconds: number;
+  /** Seconds since the process started — what places `process_start_time_seconds`. */
+  readonly uptimeSeconds: number;
+}
+
+/**
+ * How often the event loop is asked how late it is, and the only work this module does unasked.
+ * One timer wake a second: measured at 0.12 millicore on top of the 1.8 an idle Bun process
+ * already spends (20 s of `process.cpuUsage()`, sampler on against off, 2026-10-01).
+ */
+export const EVENT_LOOP_SAMPLE_MS = 1000;
+
+/** A stalled loop is the signal, so the buckets run from a millisecond to a frozen process. */
+export const EVENT_LOOP_LAG_BOUNDS: readonly number[] = Object.freeze([
+  0.001, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 10,
+]);
+
+/** The default reading: `process.memoryUsage()` and `process.cpuUsage()`, ~12 µs together. */
+export function readProcess(): ProcessReading {
+  const memory = process.memoryUsage();
+  const cpu = process.cpuUsage();
+  return {
+    rss: memory.rss,
+    heapUsed: memory.heapUsed,
+    heapTotal: memory.heapTotal,
+    external: memory.external,
+    cpuSeconds: (cpu.user + cpu.system) / 1_000_000,
+    uptimeSeconds: process.uptime(),
+  };
+}
+
+export interface ProcessMetricsOptions {
+  /** What this process is: a `ROLE`, or `x dev`'s several joined. The `process_info` label. */
+  readonly role: string;
+  /** Defaults to `readProcess`. Injected by a test. */
+  readonly read?: (() => ProcessReading) | undefined;
+  readonly clock?: Clock | undefined;
+  /** The sampler's timer. Injected by a test; the default is an unref'd `setInterval`. */
+  readonly every?: ((tick: () => void, intervalMs: number) => () => void) | undefined;
+  readonly sampleMs?: number | undefined;
+}
+
+interface Instruments {
+  readonly cpu: Counter;
+  readonly lag: Histogram;
+  readonly info: Gauge;
+}
+
+// The live source. The observers below are declared ONCE and read through it, because a gauge
+// redeclared with a different `observe` is refused (`X_METRIC_NAME_INVALID`) and a process may
+// start, stop and start this again — every `x dev` reload does.
+let source: (() => ProcessReading) | undefined;
+let startedAtSeconds = 0;
+let instruments: Instruments | undefined;
+// What the counter already holds, kept across a stop and a start so neither loses the CPU spent
+// before the first sample — a boot is where most of it goes — nor counts it twice.
+let cpuCounted = 0;
+// The start that owns `source` and the sampler, compared by identity: two starts may share a
+// reader (the default one), so the reader cannot say which start a stop belongs to.
+let active: { readonly stopTimer: () => void } | undefined;
+// The role `process_info` last said 1 for, so a start under another role sets it back to 0 —
+// one process, one role, even across a stop and a start.
+let infoRole: string | undefined;
+
+/** 0 while stopped: a scrape between a stop and a start reads a flat line, never a throw. */
+const observed = (pick: (reading: ProcessReading) => number) => (): number =>
+  source === undefined ? 0 : pick(source());
+
+function declare(): Instruments {
+  if (instruments !== undefined) return instruments;
+  gauge('process_resident_memory_bytes', {
+    unit: 'By',
+    description: 'Resident set size of this process',
+    observe: observed((reading) => reading.rss),
+  });
+  gauge('process_heap_used_bytes', {
+    unit: 'By',
+    description: 'JavaScript heap in use, garbage not yet collected included',
+    observe: observed((reading) => reading.heapUsed),
+  });
+  gauge('process_heap_total_bytes', {
+    unit: 'By',
+    description: 'JavaScript heap reserved by the engine',
+    observe: observed((reading) => reading.heapTotal),
+  });
+  gauge('process_external_memory_bytes', {
+    unit: 'By',
+    description: 'Memory held outside the heap for heap objects: buffers, strings, compiled code',
+    observe: observed((reading) => reading.external),
+  });
+  gauge('process_start_time_seconds', {
+    unit: 's',
+    description: 'When this process started, in seconds since the Unix epoch',
+    observe: () => startedAtSeconds,
+  });
+  instruments = {
+    cpu: counter('process_cpu_seconds_total', {
+      unit: 's',
+      description: 'User and system CPU time consumed by this process',
+    }),
+    lag: histogram('process_event_loop_lag_seconds', {
+      unit: 's',
+      description: `How late the event loop ran a ${String(EVENT_LOOP_SAMPLE_MS)}ms timer, sampled once per interval`,
+      bounds: EVENT_LOOP_LAG_BOUNDS,
+    }),
+    info: gauge('process_info', {
+      unit: '1',
+      description: 'Always 1; the labels say which role this process runs',
+    }),
+  };
+  return instruments;
+}
+
+const unrefInterval = (tick: () => void, intervalMs: number): (() => void) => {
+  const timer = setInterval(tick, intervalMs);
+  timer.unref();
+  return () => clearInterval(timer);
+};
+
+/** Test-only: forget the CPU already counted, beside `resetMetrics()` dropping the counter. */
+export function resetProcessMetrics(): void {
+  active?.stopTimer();
+  active = undefined;
+  source = undefined;
+  cpuCounted = 0;
+  infoRole = undefined;
+}
+
+/**
+ * Starts the process series and the one sampler behind two of them, and answers the stop. Called
+ * by whatever opens the scrape listener, so every role that can be scraped reports itself.
+ *
+ * CPU is a COUNTER fed by the sampler rather than a gauge read at scrape time: `rate()` over a
+ * counter survives a restart, and an observed gauge named `_total` would lie about its type.
+ */
+export function startProcessMetrics(options: ProcessMetricsOptions): () => void {
+  const clock = options.clock ?? systemClock;
+  const read = options.read ?? readProcess;
+  const sampleMs = finiteCount(
+    'startProcessMetrics',
+    'sampleMs',
+    options.sampleMs ?? EVENT_LOOP_SAMPLE_MS,
+    1,
+  );
+  const declared = declare();
+  // A start that replaces a live one ends its sampler: two timers would sample twice.
+  active?.stopTimer();
+  source = read;
+  // Uptime subtracted from now: the process started before this module was asked.
+  startedAtSeconds = Math.floor(clock.now().getTime() / 1000 - read().uptimeSeconds);
+  if (infoRole !== undefined && infoRole !== options.role) {
+    declared.info.record(0, { role: infoRole });
+  }
+  infoRole = options.role;
+  declared.info.record(1, { role: options.role });
+
+  const countCpu = (): void => {
+    const cpu = read().cpuSeconds;
+    // Monotonic by construction, and guarded anyway: a counter refuses a negative delta.
+    if (cpu > cpuCounted) declared.cpu.add(cpu - cpuCounted);
+    cpuCounted = Math.max(cpu, cpuCounted);
+  };
+  countCpu();
+  let due = clock.monotonic() + sampleMs;
+  const stopTimer = (options.every ?? unrefInterval)(() => {
+    const now = clock.monotonic();
+    // Late by this much; a timer that fires early reports no lag rather than a negative one.
+    declared.lag.record(Math.max(0, now - due) / 1000);
+    due = now + sampleMs;
+    countCpu();
+  }, sampleMs);
+
+  const owner = { stopTimer };
+  active = owner;
+  return () => {
+    stopTimer();
+    if (active !== owner) return;
+    active = undefined;
+    source = undefined;
+  };
+}

package/src/seal-errors.ts

@@ -0,0 +1,76 @@
+// Single responsibility: the three X_SEAL_* refusals and the errors that carry them. Three codes
+// rather than one "it will not open" because each names a different fact — no key at all, a key
+// this process was not given, a value that did not authenticate — and a different thing to do
+// next. No error here carries a key, a plaintext or the sealed string itself. Titles live in
+// `core-error-codes.ts` and the retry class in `error-retry.ts`, so this module runs nothing at
+// import and stays out of every bundle that does not seal.
+
+import { renderCauseValue } from './error-render';
+import { UltimateError } from './errors';
+
+/**
+ * No key in the environment and none on disk. Never a pass-through: storing the plaintext because
+ * the key was missing is the failure a sealed column exists to prevent, and it would look healthy.
+ */
+export class SealKeyMissingError extends UltimateError {
+  constructor(input: { envVar: string; keyPath: string }) {
+    super({
+      code: 'X_SEAL_KEY_MISSING',
+      cause: `${input.envVar} is unset and ${input.keyPath} does not exist, so there is no master key to seal or open a value with`,
+      fix: 'x secrets init   # or, where the key already exists: export ULTIMATE_SECRETS_KEY="$(cat .secrets.key)"',
+      meta: { keyPath: input.keyPath },
+    });
+  }
+}
+
+/**
+ * The value names a key id the ring does not hold — a rotation whose retired key was dropped
+ * before the re-seal finished, or a value copied from another environment. `keyId` is matched
+ * against 16 hex characters before it gets here, so it is safe to print; `declared` is computed.
+ */
+export class SealKeyUnknownError extends UltimateError {
+  constructor(input: { keyId: string; declared: readonly string[] }) {
+    super({
+      code: 'X_SEAL_KEY_UNKNOWN',
+      cause: `the sealed value names master key ${input.keyId}, which is not among the declared keys: ${input.declared.join(', ')} (current first)`,
+      // The variable is written out, not interpolated: `x errors explain` prints this line with no
+      // instance behind it. `seal.test.ts` holds it equal to `SECRETS_RETIRED_KEYS_ENV`.
+      fix: `x secrets edit   # put the retired key back in ULTIMATE_SECRETS_RETIRED_KEYS (64 hex characters, comma-separated) and keep it there until the re-seal backfill() has finished`,
+      meta: { keyId: input.keyId, declared: [...input.declared] },
+    });
+  }
+}
+
+export type SealInvalidReason = 'malformed' | 'unauthenticated';
+
+/**
+ * Either the string is not a sealed value at all, or the tag rejected it. AEAD cannot tell a wrong
+ * purpose from changed bytes — both are "the tag did not verify" — so the cause names both rather
+ * than guessing one and sending the reader after the wrong thing.
+ */
+export class SealInvalidError extends UltimateError {
+  constructor(
+    input:
+      | { reason: 'malformed'; purpose?: string | undefined; length: number }
+      | { reason: 'unauthenticated'; purpose: string; keyId: string },
+  ) {
+    const purpose =
+      input.purpose === undefined ? '' : ` for purpose ${renderCauseValue(input.purpose)}`;
+    super({
+      code: 'X_SEAL_INVALID',
+      cause:
+        input.reason === 'malformed'
+          ? `a ${input.length}-character string read${purpose} is not a sealed value (x1.<keyId>.<iv>.<ciphertext>) — it was never sealed, or it was truncated`
+          : `the value did not authenticate under master key ${input.keyId}${purpose}: it was sealed for a different purpose, or its bytes changed after it was sealed — AES-GCM cannot tell the two apart`,
+      // ONE literal covering both conditions, so `x errors explain` prints it without an instance.
+      // A string that was never sealed is almost always a column sealed AFTER rows were written,
+      // and no key fixes that: there is no reading of an unsealed value, so the rows are migrated.
+      fix: 'x secrets show --json   # a value that failed its tag: confirms the key id in force, and the value must be re-entered. A value that was never sealed — a column sealed after rows were written — is migrated: add a NEW .sealed() column, copy into it with a backfill(), drop the old one',
+      meta: {
+        reason: input.reason,
+        ...(input.purpose === undefined ? {} : { purpose: input.purpose }),
+        ...(input.reason === 'unauthenticated' ? { keyId: input.keyId } : {}),
+      },
+    });
+  }
+}

package/src/seal-keys.ts

@@ -0,0 +1,121 @@
+// Single responsibility: the key ring `seal()` and `open()` work under. The CURRENT key is the one
+// `x secrets` already manages — `ULTIMATE_SECRETS_KEY` first, `.secrets.key` second, through
+// `findMasterKey`, no second variable. RETIRED keys are one more env var, which `x secrets rotate`
+// writes into the committed file and `installSecrets()` carries into the process like any secret.
+
+import { SealKeyMissingError } from './seal-errors';
+import { importKey, masterKeyId, parseMasterKey } from './secrets';
+import { findMasterKey, masterKeyPath, SECRETS_KEY_ENV } from './secrets-store';
+
+/**
+ * Master keys that no longer seal but still open: 64 hex characters each, separated by commas or
+ * whitespace. A secret like any other — it lives in `secrets.enc.json` under this name, sealed by
+ * the current key, so a deploy is handed ONE key and the ring travels in the repository.
+ */
+export const SECRETS_RETIRED_KEYS_ENV = 'ULTIMATE_SECRETS_RETIRED_KEYS';
+
+type EnvRecord = Record<string, string | undefined>;
+
+/** Where the keys are read from. The same two fields, with the same defaults, as `installSecrets`. */
+export interface SealKeySource {
+  /** The app root holding `.secrets.key`. Defaults to the process's working directory. */
+  readonly root?: string | undefined;
+  /** Read for the current key and the retired ring. Defaults to `process.env`. */
+  readonly env?: EnvRecord | undefined;
+}
+
+export interface SealKey {
+  /** `masterKeyId`'s — the id a sealed string carries. */
+  readonly id: string;
+  readonly aes: CryptoKey;
+  /** HMAC key the deterministic IV is derived under; never the AES key itself. */
+  readonly mac: CryptoKey;
+}
+
+export interface SealKeyRing {
+  readonly current: SealKey;
+  /** Current first, then retired in declaration order. */
+  readonly keys: readonly SealKey[];
+  /** The same keys by the id a sealed string names — built once, read on every `open()`. */
+  readonly byId: ReadonlyMap<string, SealKey>;
+}
+
+const encoder = new TextEncoder();
+const MAC_DOMAIN = encoder.encode('ultimate.seal.iv.v1');
+
+/**
+ * The MAC key is DERIVED from the master key under a fixed label rather than being the master key:
+ * one key used for both AES-GCM and HMAC has no known break, and no proof either.
+ */
+async function sealKey(hex: string, at: string, variable?: string): Promise<SealKey> {
+  const raw = parseMasterKey(hex, at, variable);
+  const hmac = { name: 'HMAC', hash: 'SHA-256' } as const;
+  const master = await crypto.subtle.importKey('raw', raw, hmac, false, ['sign']);
+  const derived = await crypto.subtle.sign('HMAC', master, MAC_DOMAIN);
+  return {
+    id: await masterKeyId(raw),
+    aes: await importKey(raw),
+    mac: await crypto.subtle.importKey('raw', derived, hmac, false, ['sign']),
+  };
+}
+
+/** The retired ring as written: hex entries, in order, blanks dropped. Nothing is validated here. */
+export function splitRetiredKeys(raw: string | undefined): readonly string[] {
+  return (raw ?? '').split(/[\s,]+/).filter((entry) => entry.length > 0);
+}
+
+async function buildRing(
+  current: string,
+  currentAt: string,
+  retired: string,
+): Promise<SealKeyRing> {
+  const first = await sealKey(current, currentAt);
+  const keys = [first];
+  for (const [index, hex] of splitRetiredKeys(retired).entries()) {
+    // A malformed entry is refused by position, never skipped: a ring that silently lost a key
+    // surfaces later as X_SEAL_KEY_UNKNOWN on a row, far from the edit that caused it.
+    const next = await sealKey(
+      hex,
+      `${SECRETS_RETIRED_KEYS_ENV} (entry ${index + 1})`,
+      SECRETS_RETIRED_KEYS_ENV,
+    );
+    if (!keys.some((key) => key.id === next.id)) keys.push(next);
+  }
+  return { current: first, keys, byId: new Map(keys.map((key) => [key.id, key])) };
+}
+
+// The last ring, kept by the exact strings it was built from. Importing a key is three WebCrypto
+// calls and a list read opens hundreds of values, so the ring is built once — but it is keyed by
+// its SOURCE, never by time or by process, so a rotated key file or a changed variable is a new
+// ring on the very next call. Only a resolved ring is kept; a refusal is recomputed.
+let memo: { readonly source: string; readonly ring: Promise<SealKeyRing> } | undefined;
+
+/** The ring in force now, or `X_SEAL_KEY_MISSING`. A malformed key is `X_SECRETS_KEY_INVALID`. */
+export function resolveSealKeys(source: SealKeySource = {}): Promise<SealKeyRing> {
+  const root = source.root ?? process.cwd();
+  const env = source.env ?? (process.env as EnvRecord);
+  const found = findMasterKey(root, env);
+  if (found === undefined) {
+    return Promise.reject(
+      new SealKeyMissingError({ envVar: SECRETS_KEY_ENV, keyPath: masterKeyPath(root) }),
+    );
+  }
+  const retired = env[SECRETS_RETIRED_KEYS_ENV] ?? '';
+  const key = `${found.hex}\n${retired}`;
+  if (memo?.source === key) return memo.ring;
+  const ring = buildRing(found.hex, found.at, retired);
+  const entry = { source: key, ring };
+  memo = entry;
+  ring.catch(() => {
+    if (memo === entry) memo = undefined;
+  });
+  return ring;
+}
+
+/** The ids a sealed value may name right now. Safe to print: an id is not a key. */
+export async function sealKeyIds(
+  source: SealKeySource = {},
+): Promise<{ readonly current: string; readonly retired: readonly string[] }> {
+  const ring = await resolveSealKeys(source);
+  return { current: ring.current.id, retired: ring.keys.slice(1).map((key) => key.id) };
+}

package/src/seal.ts

@@ -0,0 +1,259 @@
+// Single responsibility: seal ONE value under the app's master key and open it back. The wire form
+// is one string, `x1.<keyId>.<iv>.<ciphertext+tag>`, AES-256-GCM through WebCrypto with a REQUIRED
+// purpose bound in as additional authenticated data. `secrets.ts` is the env envelope — a file of
+// many values; this is the per-value form a column or a stored session holds.
+
+import { assert } from './assert';
+import { UltimateError } from './errors';
+import { SealInvalidError, SealKeyUnknownError } from './seal-errors';
+import type { SealKey, SealKeyRing, SealKeySource } from './seal-keys';
+import { resolveSealKeys } from './seal-keys';
+import {
+  decodeBase64,
+  encodeBase64,
+  SECRETS_ALG,
+  SECRETS_IV_BYTES,
+  SECRETS_TAG_BYTES,
+} from './secrets';
+
+/** The format tag. A string without it was never sealed by this function. */
+export const SEAL_VERSION = 'x1';
+
+/** What a value was sealed FOR — `entity:connections.password`, `scrape-session`. Never optional. */
+export interface SealPurposeOptions extends SealKeySource {
+  /** Bound into the tag: a value sealed for one purpose does not open as another. */
+  readonly purpose: string;
+  /**
+   * A ring already resolved — `await resolveSealKeys()` — for a caller sealing or opening MANY
+   * values in one operation. Without it every call finds the master key again (an environment
+   * read, or a file read in a checkout); with it a 500-row page asks once. Never held past the
+   * operation: a ring kept across requests would outlive a rotation.
+   */
+  readonly keys?: SealKeyRing | undefined;
+}
+
+const ringFor = (options: SealPurposeOptions): Promise<SealKeyRing> | SealKeyRing =>
+  options.keys ?? resolveSealKeys(options);
+
+export interface SealOptions extends SealPurposeOptions {
+  /**
+   * Derive the IV from the purpose and the plaintext instead of drawing it, so equal values seal
+   * to equal strings and a column can be looked up by equality. It REVEALS EQUALITY to anyone who
+   * can read the stored strings: two rows holding the same value are visibly the same. Never use
+   * it for a low-entropy value (a boolean, a status, a PIN, a date of birth) — the handful of
+   * possible ciphertexts is a lookup table. Under a rotation the same value seals differently per
+   * key; `sealAll` returns every candidate.
+   */
+  readonly deterministic?: boolean | undefined;
+}
+
+// 12 bytes are exactly 16 unpadded base64url characters; a 16-byte tag alone is 22.
+const SEALED = /^x1\.([0-9a-f]{16})\.([A-Za-z0-9_-]{16})\.([A-Za-z0-9_-]{22,})$/;
+
+const encoder = new TextEncoder();
+
+const toUrl = (bytes: Uint8Array<ArrayBuffer>): string =>
+  encodeBase64(bytes).replaceAll('+', '-').replaceAll('/', '_').replaceAll('=', '');
+
+function fromUrl(text: string): Uint8Array<ArrayBuffer> {
+  const standard = text.replaceAll('-', '+').replaceAll('_', '/');
+  return decodeBase64(standard.padEnd(standard.length + ((4 - (standard.length % 4)) % 4), '='));
+}
+
+/** A fresh copy either way, so a caller's buffer is never the one WebCrypto is handed. */
+const bytesOf = (plaintext: string | Uint8Array): Uint8Array<ArrayBuffer> =>
+  typeof plaintext === 'string' ? encoder.encode(plaintext) : new Uint8Array(plaintext);
+
+/**
+ * The bytes the tag covers besides the ciphertext: the format, the algorithm, the key id and the
+ * purpose. A string moved to another column, or relabelled with another key id, fails the tag.
+ */
+const additionalData = (keyId: string, purpose: string): Uint8Array<ArrayBuffer> =>
+  encoder.encode(
+    `ultimate.seal|${SEAL_VERSION}|alg=${SECRETS_ALG}|kid=${keyId}|purpose=${purpose}`,
+  );
+
+function requirePurpose(purpose: unknown): asserts purpose is string {
+  assert(
+    typeof purpose === 'string' && purpose.length > 0,
+    'seal() and open() were called without a purpose, and the purpose is what stops a value sealed for one column opening as another',
+    "pass purpose: '<what the value is for>' — seal(value, { purpose: 'entity:<table>.<column>' })",
+  );
+}
+
+/**
+ * The deterministic IV: HMAC-SHA-256 over the length-prefixed purpose and the plaintext, cut to
+ * GCM's 96 bits. Length-prefixed so (`a`, `bc`) and (`ab`, `c`) are different inputs. A repeated
+ * (key, IV) pair then means a repeated (purpose, plaintext) — the same ciphertext, which is the
+ * mode's stated leak and not a nonce reuse across two messages.
+ */
+async function derivedIv(
+  key: SealKey,
+  purpose: string,
+  plaintext: Uint8Array<ArrayBuffer>,
+): Promise<Uint8Array<ArrayBuffer>> {
+  const label = encoder.encode(purpose);
+  const material = new Uint8Array(4 + label.length + plaintext.length);
+  new DataView(material.buffer).setUint32(0, label.length);
+  material.set(label, 4);
+  material.set(plaintext, 4 + label.length);
+  const mac = await crypto.subtle.sign('HMAC', key.mac, material);
+  return new Uint8Array(mac).slice(0, SECRETS_IV_BYTES);
+}
+
+async function sealUnder(
+  key: SealKey,
+  plaintext: Uint8Array<ArrayBuffer>,
+  purpose: string,
+  deterministic: boolean,
+): Promise<string> {
+  const iv = deterministic
+    ? await derivedIv(key, purpose, plaintext)
+    : crypto.getRandomValues(new Uint8Array(SECRETS_IV_BYTES));
+  const sealed = await crypto.subtle.encrypt(
+    {
+      name: 'AES-GCM',
+      iv,
+      additionalData: additionalData(key.id, purpose),
+      tagLength: SECRETS_TAG_BYTES * 8,
+    },
+    key.aes,
+    plaintext,
+  );
+  return `${SEAL_VERSION}.${key.id}.${toUrl(iv)}.${toUrl(new Uint8Array(sealed))}`;
+}
+
+/**
+ * Seal one value under the CURRENT master key — the one `x secrets` manages, found where
+ * `installSecrets()` finds it.
+ *
+ * ```ts
+ * const stored = await seal(password, { purpose: 'entity:connections.password' });
+ * const password = await openText(stored, { purpose: 'entity:connections.password' });
+ * ```
+ *
+ * `X_SEAL_KEY_MISSING` when there is no key: the plaintext is never returned in its place.
+ */
+export async function seal(plaintext: string | Uint8Array, options: SealOptions): Promise<string> {
+  requirePurpose(options.purpose);
+  const ring = await ringFor(options);
+  return sealUnder(
+    ring.current,
+    bytesOf(plaintext),
+    options.purpose,
+    options.deterministic === true,
+  );
+}
+
+/**
+ * The DETERMINISTIC seal of one value under every declared key, current first. During a rotation
+ * a row written before it holds the old key's string and a row written after holds the new one's,
+ * so an equality lookup has to match either: `where column in (…sealAll(value))`. Outside a
+ * rotation this is one string. Uniqueness cannot be held across keys — one value has two forms.
+ */
+export async function sealAll(
+  plaintext: string | Uint8Array,
+  options: SealPurposeOptions,
+): Promise<readonly string[]> {
+  requirePurpose(options.purpose);
+  const ring = await ringFor(options);
+  const bytes = bytesOf(plaintext);
+  return Promise.all(ring.keys.map((key) => sealUnder(key, bytes, options.purpose, true)));
+}
+
+interface SealedParts {
+  readonly keyId: string;
+  readonly iv: string;
+  readonly body: string;
+}
+
+function partsOf(value: unknown): SealedParts | undefined {
+  const match = typeof value === 'string' ? SEALED.exec(value) : null;
+  const [keyId, iv, body] = [match?.[1], match?.[2], match?.[3]];
+  if (keyId === undefined || iv === undefined || body === undefined) return undefined;
+  // No whole number of bytes encodes to 4n+1 base64 characters: a truncated write, not a value.
+  return body.length % 4 === 1 ? undefined : { keyId, iv, body };
+}
+
+const malformed = (sealed: unknown, purpose?: string): SealInvalidError =>
+  new SealInvalidError({
+    reason: 'malformed',
+    purpose,
+    length: typeof sealed === 'string' ? sealed.length : 0,
+  });
+
+/**
+ * Whether a value has the SHAPE of a sealed string. Not a claim that it opens: it exists so a
+ * caller migrating a plaintext column can tell an unsealed legacy row from a sealed one without
+ * attempting a decryption — `open()` itself never falls back to the raw string.
+ */
+export function isSealed(value: unknown): value is string {
+  return partsOf(value) !== undefined;
+}
+
+/** The id of the key a sealed string names — what a re-seal `backfill()` compares to the current. */
+export function sealedKeyId(sealed: string): string {
+  const parts = partsOf(sealed);
+  if (parts === undefined) throw malformed(sealed);
+  return parts.keyId;
+}
+
+/**
+ * Open a sealed string to its bytes. Three refusals, in the order the facts become knowable: the
+ * string is not a sealed value (`X_SEAL_INVALID`), it names a key this process does not declare
+ * (`X_SEAL_KEY_UNKNOWN` — read off the string before any decryption is attempted, so a rotation
+ * is never reported as tampering), or the tag rejected it under the purpose given
+ * (`X_SEAL_INVALID`).
+ */
+export async function open(
+  sealed: string,
+  options: SealPurposeOptions,
+): Promise<Uint8Array<ArrayBuffer>> {
+  requirePurpose(options.purpose);
+  const parts = partsOf(sealed);
+  if (parts === undefined) throw malformed(sealed, options.purpose);
+  const { keyId, iv, body } = parts;
+  const ring = await ringFor(options);
+  // A lookup by the id the string names. An id is public — it is in every sealed value — and a
+  // `Map` says so: nothing here is compared byte by byte against a secret.
+  const key = ring.byId.get(keyId);
+  if (key === undefined) {
+    throw new SealKeyUnknownError({
+      keyId,
+      declared: ring.keys.map((one) => one.id),
+    });
+  }
+  try {
+    const plaintext = await crypto.subtle.decrypt(
+      {
+        name: 'AES-GCM',
+        iv: fromUrl(iv),
+        additionalData: additionalData(keyId, options.purpose),
+        tagLength: SECRETS_TAG_BYTES * 8,
+      },
+      key.aes,
+      fromUrl(body),
+    );
+    return new Uint8Array(plaintext);
+  } catch {
+    // No `sourceError`, for `openSecrets`' reason: WebCrypto's OperationError says nothing more.
+    throw new SealInvalidError({ reason: 'unauthenticated', purpose: options.purpose, keyId });
+  }
+}
+
+/**
+ * `open()` for a value that was sealed from a string. Bytes that are not UTF-8 are refused rather
+ * than decoded with replacement characters: a caller would store the repaired text back.
+ */
+export async function openText(sealed: string, options: SealPurposeOptions): Promise<string> {
+  const bytes = await open(sealed, options);
+  try {
+    return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+  } catch {
+    throw new UltimateError({
+      code: 'X_INVARIANT',
+      cause: `the value opened to ${bytes.length} byte(s) that are not UTF-8 text, so it was sealed from bytes and openText() cannot return it`,
+      fix: 'call open() instead of openText() for a value sealed from a Uint8Array',
+    });
+  }
+}

package/src/secrets-errors.ts

@@ -84,6 +84,27 @@ export class SecretsKeyInvalidError extends UltimateError {
   }
 }
 
+/**
+ * The same condition under the same code, for a key that is NOT the current one: a malformed entry
+ * of a ring variable (`ULTIMATE_SECRETS_RETIRED_KEYS`). Its own class because its repair is an
+ * edit of that variable — the current key is fine, and re-exporting it changes nothing — and
+ * because a class has one literal `fix:`, which is what `x errors explain` prints without an
+ * instance. A variable name that is not one never reaches the line.
+ */
+export class SecretsRingKeyInvalidError extends UltimateError {
+  constructor(input: { at: string; found: number; expected: number; variable: string }) {
+    const variable = ENV_VAR_NAME.test(input.variable)
+      ? input.variable
+      : 'the variable the cause names';
+    super({
+      code: 'X_SECRETS_KEY_INVALID',
+      cause: `the master key in ${input.at} is ${input.found} character(s); an AES-256 key is ${input.expected} lowercase hex characters`,
+      fix: `x secrets edit   # ${variable} holds ${input.expected}-character lowercase hex keys separated by commas: correct or remove the entry the cause names`,
+      meta: { at: input.at },
+    });
+  }
+}
+
 /**
  * A well-formed key that is not the one this file was sealed with. Distinguishable from tampering
  * only because the envelope carries a key id — a domain-separated SHA-256 of the key, which is

package/src/secrets.ts

@@ -8,6 +8,7 @@ import {
   SecretsKeyInvalidError,
   SecretsKeyMismatchError,
   SecretsPlaintextInvalidError,
+  SecretsRingKeyInvalidError,
   SecretsTamperedError,
 } from './secrets-errors';
 
@@ -65,14 +66,15 @@ function decodeHex(hex: string): Uint8Array<ArrayBuffer> {
 }
 
 // `btoa`/`atob` rather than node:buffer — both are standard globals, and a chunk loop avoids the
-// stack blow-up `String.fromCharCode(...bytes)` hits on a spread of any size.
-function encodeBase64(bytes: Uint8Array<ArrayBuffer>): string {
+// stack blow-up `String.fromCharCode(...bytes)` hits on a spread of any size. Exported for
+// `seal.ts`, which writes the same bytes in the URL-safe alphabet — one codec, never a second.
+export function encodeBase64(bytes: Uint8Array<ArrayBuffer>): string {
   let binary = '';
   for (const byte of bytes) binary += String.fromCharCode(byte);
   return btoa(binary);
 }
 
-function decodeBase64(text: string): Uint8Array<ArrayBuffer> {
+export function decodeBase64(text: string): Uint8Array<ArrayBuffer> {
   const binary = atob(text);
   const bytes = new Uint8Array(binary.length);
   for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
@@ -84,15 +86,22 @@ export function generateMasterKey(): string {
   return encodeHex(crypto.getRandomValues(new Uint8Array(SECRETS_KEY_BYTES)));
 }
 
-/** 64 lowercase hex characters, or `X_SECRETS_KEY_INVALID`. Whitespace is trimmed, never repaired. */
-export function parseMasterKey(raw: string, at: string): Uint8Array<ArrayBuffer> {
+/**
+ * 64 lowercase hex characters, or `X_SECRETS_KEY_INVALID`. Whitespace is trimmed, never repaired.
+ * `variable` names the variable a key OTHER than the current one was read from, so the refusal's
+ * fix edits that variable instead of re-exporting a current key that is fine.
+ */
+export function parseMasterKey(
+  raw: string,
+  at: string,
+  variable?: string,
+): Uint8Array<ArrayBuffer> {
   const hex = raw.trim();
   if (hex.length !== SECRETS_KEY_HEX_LENGTH || !HEX_KEY.test(hex)) {
-    throw new SecretsKeyInvalidError({
-      at,
-      found: hex.length,
-      expected: SECRETS_KEY_HEX_LENGTH,
-    });
+    const shape = { at, found: hex.length, expected: SECRETS_KEY_HEX_LENGTH };
+    throw variable === undefined
+      ? new SecretsKeyInvalidError(shape)
+      : new SecretsRingKeyInvalidError({ ...shape, variable });
   }
   return decodeHex(hex);
 }
@@ -119,7 +128,8 @@ export async function masterKeyId(key: Uint8Array<ArrayBuffer>): Promise<string>
 const additionalData = (header: Omit<SecretsEnvelope, 'iv' | 'ct'>): Uint8Array<ArrayBuffer> =>
   encoder.encode(`ultimate.secrets|v=${header.v}|alg=${header.alg}|kid=${header.kid}`);
 
-const importKey = (key: Uint8Array<ArrayBuffer>): Promise<CryptoKey> =>
+/** The AES-256-GCM key object, non-extractable. Shared with `seal-keys.ts`: one import, one usage set. */
+export const importKey = (key: Uint8Array<ArrayBuffer>): Promise<CryptoKey> =>
   crypto.subtle.importKey('raw', key, { name: 'AES-GCM' }, false, ['encrypt', 'decrypt']);
 
 /**