@ultimat3/core 23.0.0 → 25.0.0

package/src/otlp.ts

@@ -96,7 +96,10 @@ function parseEndpoint(signal: OtlpSignal, raw: string, perSignal: boolean, env:
   // The spec's own asymmetry, not ours: a per-signal endpoint is the full URL an operator chose,
   // while the generic one is a base the signal path is appended to.
   if (perSignal) return url.toString();
-  return `${url.toString().replace(/\/+$/, '')}/v1/${signal}`;
+  // On the PATH, never on the string: `http://collector:4318?tenant=a` concatenated to
+  // `…/?tenant=a/v1/traces`, a request to `/` whose query merely ends in the receiver's path.
+  url.pathname = `${url.pathname.replace(/\/+$/, '')}/v1/${signal}`;
+  return url.toString();
 }
 
 /** The endpoint an operator configured, or `undefined` when they configured none. */
@@ -157,32 +160,43 @@ export function otlpEndpoint(
  * and no fix. Refused instead, naming the variable and the header KEY: the value is the
  * collector's credential and a `cause:` is folded into a log line.
  */
-function decodeHeaderValue(key: string, raw: string): string {
+function decodeHeaderValue(variable: string, key: string, raw: string): string {
   try {
     return decodeURIComponent(raw);
   } catch {
     throw new OtlpHeadersInvalidError({
-      cause: `${OTLP_HEADERS_KEY} carries a malformed percent-escape in the "${key}" value, so the header cannot be decoded`,
-      fix: `set ${OTLP_HEADERS_KEY}=${key}=<encoded>, where <encoded> is what bun -e 'console.log(encodeURIComponent(process.argv[1]))' <value> prints — or drop the stray % from the "${key}" value if it was meant literally`,
+      cause: `${variable} carries a malformed percent-escape in the "${key}" value, so the header cannot be decoded`,
+      fix: `set ${variable}=${key}=<encoded>, where <encoded> is what bun -e 'console.log(encodeURIComponent(process.argv[1]))' <value> prints — or drop the stray % from the "${key}" value if it was meant literally`,
       meta: { header: key },
     });
   }
 }
 
-/** `key=value,key2=value2`, percent-decoded — the spec's format for collector auth headers. */
+/**
+ * `key=value,key2=value2`, percent-decoded — the spec's format for collector auth headers.
+ *
+ * With a `signal`, `OTEL_EXPORTER_OTLP_<SIGNAL>_HEADERS` REPLACES the generic variable for that
+ * signal, which is the spec's rule and the one `ENDPOINT` and `PROTOCOL` already followed here:
+ * only the generic one was read, so a collector that authenticates traces and metrics with
+ * different keys got the same key on both and rejected one of them.
+ */
 export function otlpHeaders(
   explicit?: Readonly<Record<string, string>> | undefined,
   env: OtlpEnv = process.env,
+  signal?: OtlpSignal | undefined,
 ): Record<string, string> {
   const headers: Record<string, string> = { 'content-type': 'application/json' };
-  const raw = env[OTLP_HEADERS_KEY];
+  const specific = signal === undefined ? undefined : signalKey(signal, 'HEADERS');
+  const variable =
+    specific !== undefined && (env[specific] ?? '').trim() !== '' ? specific : OTLP_HEADERS_KEY;
+  const raw = env[variable];
   if (raw !== undefined) {
     for (const pair of raw.split(',')) {
       const index = pair.indexOf('=');
       if (index <= 0) continue;
       const key = pair.slice(0, index).trim().toLowerCase();
       if (key === '') continue;
-      headers[key] = decodeHeaderValue(key, pair.slice(index + 1).trim());
+      headers[key] = decodeHeaderValue(variable, key, pair.slice(index + 1).trim());
     }
   }
   for (const [key, value] of Object.entries(explicit ?? {})) headers[key.toLowerCase()] = value;
@@ -202,22 +216,39 @@ export interface OtlpKeyValue {
   readonly value: OtlpAnyValue;
 }
 
-function anyValue(value: AttributeValue): OtlpAnyValue {
+/**
+ * `undefined` for a number the wire cannot spell. `NaN` and `±Infinity` serialise as
+ * `{"doubleValue":null}`, and a validating collector rejects the WHOLE batch for it — `postOtlp`
+ * only warns, so one bad gauge silently cost every span beside it. Dropped, as a missing
+ * attribute is the honest reading of "not a number".
+ */
+function anyValue(value: AttributeValue): OtlpAnyValue | undefined {
   if (typeof value === 'string') return { stringValue: value };
   if (typeof value === 'boolean') return { boolValue: value };
   if (typeof value === 'number') {
+    if (!Number.isFinite(value)) return undefined;
     // `intValue` is a 64-bit field, so the JSON encoding spells it as a string. A float that
-    // happens to be integral is still a double to whoever queries it; `Number.isInteger` is the
-    // only signal available and matches what every other OTLP/JSON encoder does.
-    return Number.isInteger(value) ? { intValue: String(value) } : { doubleValue: value };
+    // happens to be integral is still a double to whoever queries it; SAFE-integer is the signal,
+    // because past 2^53 `String(value)` is `"1e+21"` — exponent notation is not an int64.
+    return Number.isSafeInteger(value) ? { intValue: String(value) } : { doubleValue: value };
+  }
+  const values: OtlpAnyValue[] = [];
+  for (const item of value) {
+    const encoded = anyValue(item);
+    if (encoded !== undefined) values.push(encoded);
   }
-  return { arrayValue: { values: value.map((item) => anyValue(item)) } };
+  return { arrayValue: { values } };
 }
 
 export function otlpAttributes(
   attributes: Readonly<Record<string, AttributeValue>>,
 ): readonly OtlpKeyValue[] {
-  return Object.entries(attributes).map(([key, value]) => ({ key, value: anyValue(value) }));
+  const out: OtlpKeyValue[] = [];
+  for (const [key, raw] of Object.entries(attributes)) {
+    const value = anyValue(raw);
+    if (value !== undefined) out.push({ key, value });
+  }
+  return out;
 }
 
 /** Epoch ms -> the string of nanoseconds OTLP/JSON wants, without losing precision to a float. */

package/src/page.ts

@@ -10,7 +10,7 @@
 // The client seam's own functions, for the hooks a browser island calls: the one transport, the
 // URL rule, the principal-supersession reader, and the small helpers realtime's browser half uses.
 // Each reaches no titles table — `page-bundle.test.ts` builds all of them together to prove it.
-export { invariant } from './assert';
+export { assertCoded } from './assert';
 export type { AsyncState } from './async-state';
 export type { JitterMode, Random } from './backoff';
 export { backoffDelay } from './backoff';
@@ -32,7 +32,7 @@ export type { UltimateErrorInit } from './errors';
 export { isUltimateError, UltimateError } from './errors';
 export { finiteCount, finiteOption } from './finite-option';
 export { isSuperseded } from './generation-fence';
-export { uuid } from './ids';
+export { uuidV7 } from './ids';
 export { isJsonObject } from './json-object';
 export type { OutboxDrainMessage } from './outbox-drain';
 export { OUTBOX_DRAIN_MESSAGE } from './outbox-drain';
@@ -54,5 +54,7 @@ export type { RecordEnvelope, RecordRows } from './record-envelope';
 export { decodeRecordEnvelope, RECORDS_HEADER } from './record-envelope';
 export type { PageClient, RecordSink } from './record-sink';
 export { pageClient } from './record-sink';
+// The key the theme boot script reads and the toggle island writes.
+export { THEME_STORAGE_KEY } from './theme-storage';
 // A write's public name, so the page's store can recognise the `records` frame its own write made.
 export { isWriteDigest, WRITE_DIGEST_LENGTH, writeDigest } from './write-digest';

package/src/pg-executor.ts

@@ -0,0 +1,15 @@
+// The one structural Postgres seam: `query(text, values)` answering rows. Declared at tier 0 so
+// `@ultimat3/http`, `auth`, `action` and `jobs` share it while staying free of `@ultimat3/db` —
+// four packages each declared it, and a copy is a fifth place for the contract to drift.
+
+/**
+ * One method, positional parameters. **`Bun.sql` does not satisfy it** — `Bun.sql.query` is
+ * `undefined`; it is a tagged template whose positional form is `unsafe`, so `{ executor: Bun.sql }`
+ * would `TypeError` on the first statement. What satisfies it is a client that already speaks
+ * `(text, values)`, wrapped in one line — `@ultimat3/cli`'s `pgExecutorFor(client)` over
+ * `@ultimat3/db`'s `DbClient.query({ text, values })` is the framework's own — or a transaction
+ * handle, which is a client on its own connection. It answers rows, never a command tag.
+ */
+export interface PgExecutor {
+  query<R>(sql: string, params: readonly unknown[]): Promise<readonly R[]>;
+}

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;
@@ -67,6 +84,7 @@ export const PRIMITIVE_FACTORIES = Object.freeze<readonly PrimitiveFactory[]>(
       { factory: 'exportRows', pkg: '@ultimat3/jobs', kind: 'job' },
       { factory: 'purge', pkg: '@ultimat3/jobs', kind: 'job' },
       { factory: 'webhook', pkg: '@ultimat3/jobs', kind: 'job' },
+      { factory: 'mcpConfirmations', pkg: '@ultimat3/mcp', kind: 'action' },
       { factory: 'notifier', pkg: '@ultimat3/notify', kind: 'job' },
       { factory: 'scrape', pkg: '@ultimat3/scraping', kind: 'job' },
     ] satisfies readonly PrimitiveFactory[]
@@ -103,9 +121,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 +145,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

@@ -3,16 +3,27 @@
 // nothing in the tree consulted it before deciding to try again, so four packages each shipped
 // their own loop and only `@ultimat3/jobs`' asked the classification at all.
 
-import { type BackoffCurve, backoffDelay, type JitterMode, type Random } from './backoff';
+import {
+  type BackoffCurve,
+  backoffDelay,
+  type JitterMode,
+  jitterStatedDelay,
+  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. */
   readonly attempts: number;
   /** The first delay, in ms. */
   readonly base: number;
-  /** Ceiling for any single delay, in ms — a `retry-after` the responder named included. */
+  /**
+   * Ceiling for any single delay, in ms. A `retry-after` the responder named is clamped to it
+   * too, and then gets its spread on top — at most half again, so a burst told one delay does
+   * not wake together (`jitterStatedDelay`).
+   */
   readonly max: number;
   /**
    * Required, unlike `backoffDelay`'s, and that is the point: a retry loop with no jitter is the
@@ -63,6 +74,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 +88,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,
@@ -88,9 +102,19 @@ export function retryDecision(
   const stated = classification === 'retry-after' ? statedDelayMs(error) : undefined;
   return {
     retry: true,
-    // Clamped by the policy's own ceiling, which is what `max` is for: a responder naming a day is
-    // still a responder this deployment has not agreed to wait a day for.
-    delayMs: stated === undefined ? computed : Math.min(stated, policy.max),
+    // The stated delay is a FLOOR plus a spread (`jitterStatedDelay`), never the bare number: a
+    // shedding server tells a whole burst `Retry-After: 1`, and waiting exactly that replays the
+    // burst in lockstep every second. The floor is clamped by the policy's own ceiling, which is
+    // what `max` is for — a responder naming a day is still a responder this deployment has not
+    // agreed to wait a day for — and the spread on top is at most half of it.
+    // `jitter: 'none'` is honoured here too — the caller's one decision, for a test or a printable
+    // schedule — and only that mode gets the bare floor.
+    delayMs:
+      stated === undefined
+        ? computed
+        : policy.jitter === 'none'
+          ? Math.min(stated, policy.max)
+          : jitterStatedDelay(Math.min(stated, policy.max), policy.max, random),
     attempt,
     nextAttempt: attempt + 1,
     classification,
@@ -111,6 +135,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 +156,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/secrets-errors.ts

@@ -77,8 +77,19 @@ export class SecretsKeyInvalidError extends UltimateError {
   constructor(input: { at: string; found: number; expected: number }) {
     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: `export ULTIMATE_SECRETS_KEY="$(cat .secrets.key)"   # the key file holds the ${input.expected} characters verbatim, no newline of its own`,
+      // The lost-key sentence is CAUSE, not fix: a `fix:` is one command, and no command restores
+      // a key file — so the file branch says what cannot be done here and the fix measures it.
+      cause:
+        input.at === 'ULTIMATE_SECRETS_KEY'
+          ? `the master key in ${input.at} is ${input.found} character(s); an AES-256 key is ${input.expected} lowercase hex characters`
+          : `the master key in ${input.at} is ${input.found} character(s); an AES-256 key is ${input.expected} lowercase hex characters — the key FILE is what is wrong, so re-exporting it changes nothing: restore it from wherever the team keeps the key, because a lost key cannot be recovered or regenerated`,
+      // Branches on WHERE the bad key was read. From the variable, re-reading the file repairs
+      // it. From the FILE, that same line reads the truncated file into the variable and is
+      // refused again, so the command is the measurement that says when the restore worked.
+      fix:
+        input.at === 'ULTIMATE_SECRETS_KEY'
+          ? `export ULTIMATE_SECRETS_KEY="$(cat .secrets.key)"   # the key file holds the ${input.expected} characters on one line`
+          : `wc -c ${renderFixShellArg(input.at, '<the key file the cause names>')}   # ${input.expected + 1} is a whole key and its newline; any other count is the truncated or padded file to restore`,
       meta: { at: input.at },
     });
   }
@@ -99,7 +110,7 @@ export class SecretsRingKeyInvalidError extends UltimateError {
     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`,
+      fix: `x secrets edit   # ${variable} holds ${input.expected}-character lowercase hex keys separated by commas: correct or remove the entry the cause names — the variable is a line of secrets.enc.json, and a platform that ALSO sets it wins, so correct it there too`,
       meta: { at: input.at },
     });
   }

package/src/secrets-key-file.ts

@@ -0,0 +1,139 @@
+// Single responsibility: writing a master-key file that only its owner can read, on every platform,
+// and renaming one over another without losing to a reader that holds it open. POSIX gets the first
+// from the create mode. Windows ignores the mode — the file inherits the profile directory's ACL —
+// so there the temp file's ACL is cut to the current account BEFORE the rename makes it live.
+
+// why: `node:fs` sync — Bun.write takes no mode and has no atomic rename; both run once, at a CLI
+// command or at boot, before anything is served, so there is nothing for an async call to overlap.
+import { renameSync, rmSync, writeFileSync } from 'node:fs';
+import { backoffDelay } from './backoff';
+import { renderCauseValue, stringField } from './error-render';
+import { UltimateError } from './errors';
+
+/** How long `icacls` or `whoami` may take before the write is refused as a failed ACL. */
+const ACL_TIMEOUT_MS = 10_000;
+
+/** Owner read/write — the mode every key file is CREATED with. */
+export const OWNER_ONLY_MODE = 0o600;
+
+/**
+ * Tries for a rename over a file another process holds open. Windows refuses that rename with
+ * EPERM or EBUSY rather than replacing the name the way POSIX does — an editor, an indexer or an
+ * antivirus scan holding `.secrets.key` for a moment — so a short, bounded retry outlasts the
+ * holder; a holder that never lets go is still an error, after ~150 ms rather than never.
+ */
+export const RENAME_ATTEMPTS = 5;
+const isHeldOpen = (code: string | undefined): boolean => code === 'EPERM' || code === 'EBUSY';
+
+/** Every effect, injectable: the Windows branch is proven on Linux with a fake. */
+export interface KeyFileIo {
+  readonly platform: string;
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly writeExclusive: (path: string, text: string, mode: number) => void;
+  readonly rename: (from: string, to: string) => void;
+  readonly remove: (path: string) => void;
+  readonly runAcl: (argv: readonly string[]) => { exitCode: number; output: string };
+  readonly username: () => string;
+  readonly sleep: (ms: number) => void;
+}
+
+/** Built per call, never at import: the barrel reaches this module from browser bundles too. */
+const systemIo = (): KeyFileIo => ({
+  platform: process.platform,
+  env: process.env,
+  // `wx`: the mode applies only when a write CREATES the file, so never write into a leftover.
+  writeExclusive: (path, text, mode) =>
+    writeFileSync(path, text, { encoding: 'utf-8', mode, flag: 'wx' }),
+  rename: renameSync,
+  remove: (path) => rmSync(path, { force: true }),
+  runAcl: (argv) => {
+    // Bounded: icacls on one local file answers in milliseconds; a hang must not hold the boot.
+    const ran = Bun.spawnSync([...argv], {
+      stdout: 'pipe',
+      stderr: 'pipe',
+      timeout: ACL_TIMEOUT_MS,
+    });
+    return {
+      exitCode: ran.exitCode,
+      output: `${ran.stdout.toString()}${ran.stderr.toString()}`.trim(),
+    };
+  },
+  // `whoami` prints `DOMAIN\user`, the form icacls resolves. Never `node:os`'s `userInfo`: the
+  // browser polyfill lacks it, and the barrel reaches this module from every island's bundle.
+  username: () =>
+    Bun.spawnSync(['whoami'], { stdout: 'pipe', timeout: ACL_TIMEOUT_MS }).stdout.toString().trim(),
+  sleep: (ms) => Bun.sleepSync(ms),
+});
+
+/** The account the key is granted to: `DOMAIN\user` where Windows names both. */
+export function aclPrincipal(
+  env: Readonly<Record<string, string | undefined>>,
+  username: () => string,
+): string {
+  const user = env['USERNAME'];
+  const domain = env['USERDOMAIN'];
+  if (user !== undefined && user !== '') {
+    return domain !== undefined && domain !== '' ? `${domain}\\${user}` : user;
+  }
+  return username();
+}
+
+/**
+ * `/inheritance:r` drops every ACE the directory handed down; `/grant:r` REPLACES any explicit one
+ * for the principal with full control. What is left is one entry: the account that wrote the key.
+ */
+export function ownerOnlyAclArgv(path: string, principal: string): readonly string[] {
+  return ['icacls', path, '/inheritance:r', '/grant:r', `${principal}:F`];
+}
+
+/** icacls refused, so the key was never written: no file is better than a readable one. */
+export class SecretsKeyAclError extends UltimateError {
+  constructor(input: { path: string; principal: string; exitCode: number; output: string }) {
+    super({
+      code: 'X_SECRETS_KEY_ACL_FAILED',
+      cause: `icacls could not restrict ${renderCauseValue(input.path)} to ${renderCauseValue(input.principal)} (exit ${input.exitCode}: ${renderCauseValue(input.output)}), so the key was not written — on Windows a file's mode does not keep other accounts out, its ACL does`,
+      fix: 'x doctor --json   # on Windows: where.exe icacls must resolve (C:\\Windows\\System32) and whoami names the account the key is granted to — or keep no key file and set ULTIMATE_SECRETS_KEY instead',
+      meta: { path: input.path, exitCode: input.exitCode },
+    });
+  }
+}
+
+/** On win32, cut `path`'s ACL to the current account. A no-op elsewhere: the mode did it. */
+export function restrictToOwner(path: string, io: KeyFileIo = systemIo()): void {
+  if (io.platform !== 'win32') return;
+  const principal = aclPrincipal(io.env, io.username);
+  const ran = io.runAcl(ownerOnlyAclArgv(path, principal));
+  if (ran.exitCode !== 0) {
+    throw new SecretsKeyAclError({ path, principal, exitCode: ran.exitCode, output: ran.output });
+  }
+}
+
+/** `rename(from, to)`, retried on EPERM/EBUSY only, `RENAME_ATTEMPTS` tries in all. */
+export function renameOver(from: string, to: string, io: KeyFileIo = systemIo()): void {
+  for (let attempt = 1; ; attempt++) {
+    try {
+      io.rename(from, to);
+      return;
+    } catch (error) {
+      if (attempt >= RENAME_ATTEMPTS || !isHeldOpen(stringField(error, 'code'))) throw error;
+      io.sleep(backoffDelay({ attempt, base: 10, max: 160 }));
+    }
+  }
+}
+
+/**
+ * Write `text` to `path`, readable by its owner alone, atomically: a fresh temp file created at
+ * 0600 (and ACL-restricted on Windows) is renamed over the target, so a reader sees the old file or
+ * the new one, and rotating over a key that was world-readable never leaves the new key so.
+ */
+export function writeOwnerOnlyFile(path: string, text: string, io: KeyFileIo = systemIo()): void {
+  const temp = `${path}.${crypto.randomUUID()}.tmp`;
+  try {
+    io.writeExclusive(temp, text, OWNER_ONLY_MODE);
+    restrictToOwner(temp, io);
+    renameOver(temp, path, io);
+  } catch (error) {
+    io.remove(temp);
+    throw error;
+  }
+}