@ultimat3/core 22.15.0 → 24.0.0

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/public-cause.ts

@@ -0,0 +1,37 @@
+// Single responsibility: the ONE answer to "may a caller read this 5xx code's `cause`?". Moved down
+// from `@ultimat3/http`'s `problem-meta.ts` because three renderers send an error off the box — the
+// HTTP problem document, the MCP error data and the agent `tool_result` — and only the first asked.
+// Tier 0, so `@ultimat3/mcp` and `@ultimat3/ai` (tier 4) can ask it without importing each other.
+
+/**
+ * The 5xx codes whose `cause` a caller may read. Every other 5xx document carries the code and the
+ * request id and a fixed sentence: `X_DB_STATEMENT_FAILED` has a status row, so the old "blank only
+ * what nobody classified" rule served the Postgres message and the SQL statement in a production
+ * 500. The framework's four are refusals whose cause IS the instruction — back off, retry.
+ */
+const FRAMEWORK_PUBLIC_CAUSE: ReadonlySet<string> = new Set([
+  'X_DRAINING',
+  'X_OVERLOADED',
+  'X_FLIGHT_GATE_OVERLOADED',
+  'X_TIMEOUT',
+]);
+const APP_PUBLIC_CAUSE = new Set<string>();
+
+/** Whether a 5xx document for `code` may carry its authored `cause`. */
+export const hasPublicCause = (code: string): boolean =>
+  FRAMEWORK_PUBLIC_CAUSE.has(code) || APP_PUBLIC_CAUSE.has(code);
+
+/**
+ * The WRITE half, and not an app's door: an app declares a public cause through
+ * `registerProblemMeta({ CODE: { publicCause: true } })` in `@ultimat3/http`, which refuses a
+ * framework-owned code first and then calls this. The set lives here only so the predicate above
+ * has one table to read whichever renderer asks.
+ */
+export const registerPublicCause = (code: string): void => {
+  APP_PUBLIC_CAUSE.add(code);
+};
+
+/** Test seam. Production registers once at boot and never unregisters. */
+export const resetPublicCauses = (): void => {
+  APP_PUBLIC_CAUSE.clear();
+};

package/src/registrar.ts

@@ -27,6 +27,23 @@ export const PRIMITIVE_KINDS = [
 
 export type PrimitiveKind = (typeof PRIMITIVE_KINDS)[number];
 
+/**
+ * The package that ANNOUNCES each kind's registrar — a kind is not a package name. Both `fix:`
+ * lines below spliced `@ultimat3/${kind}`, so a missing `task` registrar told its reader to
+ * `bun add @ultimat3/task`, a package the registry has never had. A `Record` over the union, so a
+ * ninth kind fails to compile here before it can ship a fix that 404s.
+ */
+export const PRIMITIVE_PACKAGES = Object.freeze<Record<PrimitiveKind, string>>({
+  action: '@ultimat3/action',
+  entity: '@ultimat3/entity',
+  job: '@ultimat3/jobs',
+  mutator: '@ultimat3/action',
+  policy: '@ultimat3/policy',
+  query: '@ultimat3/query',
+  route: '@ultimat3/render',
+  task: '@ultimat3/jobs',
+});
+
 /** One factory over one primitive: the export's name, the package that ships it, what it returns. */
 export interface PrimitiveFactory {
   readonly factory: string;
@@ -103,9 +120,9 @@ export function registerPrimitiveRegistrar(kind: PrimitiveKind, registrar: Modul
       code: 'X_REGISTRAR_CONFLICT',
       cause: `two different ${kind} registrars are loaded, so ${kind} primitives would split across two registries`,
       // One command, because a `fix:` is pasted verbatim: collapsing every range on the package
-      // to one resolved version is the repair. `bun pm why @ultimat3/<kind>` names the dependents
-      // when a range genuinely disagrees and the update cannot converge on its own.
-      fix: `bun update @ultimat3/${kind}`,
+      // to one resolved version is the repair. `bun pm why <package>` names the dependents when
+      // a range genuinely disagrees and the update cannot converge on its own.
+      fix: `bun update ${PRIMITIVE_PACKAGES[kind]}`,
       meta: { kind },
     });
   }
@@ -127,7 +144,7 @@ export function primitiveRegistrar(kind: PrimitiveKind): ModuleRegistrar {
     throw new UltimateError({
       code: 'X_REGISTRAR_MISSING',
       cause: `no ${kind} registrar is loaded, so ${kind} primitives cannot be registered`,
-      fix: `bun add @ultimat3/${kind}`,
+      fix: `bun add ${PRIMITIVE_PACKAGES[kind]}`,
       meta: { kind },
     });
   }

package/src/retry.ts

@@ -6,6 +6,7 @@
 import { type BackoffCurve, backoffDelay, type JitterMode, type Random } from './backoff';
 import { systemClock } from './clock';
 import { classifyThrown, type ErrorRetry, statedDelayMs } from './error-retry';
+import { finiteCount, finiteOption } from './finite-option';
 
 export interface RetryPolicy {
   /** Total attempts INCLUDING the first. `attempts: 1` means no retry. */
@@ -63,6 +64,9 @@ export function retryDecision(
   error: unknown,
   random?: Random,
 ): RetryDecision {
+  // Screened HERE and not only in `retry()`: this function is exported so a caller can write its
+  // own loop, and `attempt >= NaN` is false for every attempt — the loop that asks it never ends.
+  const attempts = finiteCount('a retry policy', 'attempts', policy.attempts);
   const classification = classifyThrown(error);
   const stop = (stoppedBy: RetryStopReason): RetryDecision => ({
     retry: false,
@@ -74,7 +78,7 @@ export function retryDecision(
   });
 
   if (classification === 'terminal') return stop('terminal');
-  if (attempt >= policy.attempts) return stop('attempts-exhausted');
+  if (attempt >= attempts) return stop('attempts-exhausted');
 
   const computed = backoffDelay({
     attempt,
@@ -111,6 +115,16 @@ export async function retry<T>(
   policy: RetryPolicy,
   deps: RetryDeps,
 ): Promise<T> {
+  // Both bounds are refused BEFORE the first try: a policy that cannot stop the loop is a defect in
+  // the call, and running the work once first would report it as the work's own failure.
+  // `finiteOption` for the budget, not `finiteCount`: it is a duration a caller computes from a
+  // monotonic clock, so a fraction is real and a spent (negative) one means "do not wait at all".
+  // Zero stays legal and means what it always did — one try, no retry (`retry.test.ts` pins it).
+  finiteCount('a retry policy', 'attempts', policy.attempts);
+  const budget =
+    policy.timeBudgetMs === undefined
+      ? undefined
+      : finiteOption('a retry policy', 'timeBudgetMs', policy.timeBudgetMs);
   const now = deps.now ?? ((): number => systemClock.monotonic());
   // Read once even when no budget is set: a clock call per attempt would be a cost the common case
   // does not owe. `startedAt` is only compared against when `timeBudgetMs` is present.
@@ -122,7 +136,6 @@ export async function retry<T>(
     } catch (error) {
       const decision = retryDecision(policy, attempt, error, deps.random);
       if (!decision.retry) throw error;
-      const budget = policy.timeBudgetMs;
       // Decided BEFORE the wait, never after: a loop that sleeps and then discovers it is out of
       // budget has already spent the caller's deadline on a wait nobody could use.
       if (budget !== undefined && now() - startedAt + decision.delayMs > budget) throw error;

package/src/route-rank.ts

@@ -0,0 +1,36 @@
+// Single responsibility: the ONE precedence between route patterns, as an integer. Tier 0 because
+// three tier-4 readers need it and may not import each other — `@ultimat3/render`'s
+// `compilePattern` (ISR, sitemap extras, the admin), and `@ultimat3/pwa`'s worker rule order.
+
+/**
+ * Per segment, how strongly it claims a pathname: a literal 3, a `:param` 2, a `*catch-all` 1, and
+ * 4 where the pattern has already ENDED — `/` outranks `/*rest` and `/docs` outranks `/docs/*path`
+ * at the bare prefix, as the request router's own terminal outranks its catch-all.
+ */
+const SEGMENT_WEIGHT = { literal: 3, param: 2, catchAll: 1, ended: 4 } as const;
+const WEIGHT_BASE = 5;
+/** 5^22 < 2^53: every rank is an exact integer. A deeper pattern ties past its 22nd segment. */
+export const ROUTE_RANK_SEGMENTS = 22;
+
+/**
+ * The request router's precedence (`@ultimat3/http`'s trie) as ONE number, higher wins: segment by
+ * segment, the first segment where two patterns differ decides — literal over `:param` over
+ * `*catch-all`. Positional, never a sum: the 100/10/1 sum this replaced ranked `/:a/b/c` above
+ * `/a/:x/:y` for `/a/b/c`, where the trie takes the literal first segment. Compare two ranks only
+ * with each other; the value itself means nothing.
+ */
+export function routeRank(pattern: string): number {
+  const weights = pattern
+    .split('/')
+    .filter((segment) => segment.length > 0)
+    .map((segment) => {
+      if (segment.startsWith('*')) return SEGMENT_WEIGHT.catchAll;
+      if (segment.startsWith(':')) return SEGMENT_WEIGHT.param;
+      return SEGMENT_WEIGHT.literal;
+    });
+  let rank = 0;
+  for (let i = 0; i < ROUTE_RANK_SEGMENTS; i += 1) {
+    rank = rank * WEIGHT_BASE + (weights[i] ?? SEGMENT_WEIGHT.ended);
+  }
+  return rank;
+}

package/src/same-origin.ts

@@ -13,7 +13,7 @@ export interface OriginEvidence {
   readonly secFetchSite: string | null;
   /** An EXACT allowance for a sibling origin — never a wildcard, never a suffix match. */
   readonly listed: (origin: string) => boolean;
-  /** Where the operator adds an origin, named in the refusal: `http.cors.origins`, `SYNC_ORIGINS`. */
+  /** Where the operator adds an origin, named in the refusal: `http.cors.origins`, `APP_URL`. */
   readonly listName: string;
 }
 

package/src/sampler.ts

@@ -136,9 +136,13 @@ export function samplerFromEnv(
       return ratioSampler(ratio);
     case 'parentbased_always_off':
       return parentBasedRatioSampler(0);
+    case 'parentbased_always_on':
+      // Its own case because it takes NO arg: sharing the ratio branch let a leftover
+      // `OTEL_TRACES_SAMPLER_ARG=0.1` thin the roots of a sampler whose name says always.
+      return parentBasedRatioSampler(1);
     default:
-      // `parentbased_always_on`, `parentbased_traceidratio` and the unset case are one sampler:
-      // honour the parent, else the ratio — which is 1 when nothing set an arg.
+      // `parentbased_traceidratio` and the unset case are one sampler: honour the parent, else
+      // the ratio — which is 1 when nothing set an arg.
       return parentBasedRatioSampler(ratio);
   }
 }

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) };
+}