@ultimat3/core

🧱 @ultimat3/core

Tier 0. The foundation every other Ultimate package imports and none of them may bypass. Zero dependencies, zero @ultimat3/* imports.

Owns	Module
UltimateError, the 3-line rendering, --json shape	errors.ts
rendering an app's value into a cause / fix without throwing	error-render.ts
code → { title, docs } registry, registerErrorCodes()	error-codes.ts
the one lazy AsyncLocalStorage, every ambient scope in the framework	async-context.ts
request context on that seam	context.ts
Actor (user | service | agent | anonymous)	actor.ts
whether a permission grant reaches a name — grantCovers, * and <prefix>:*	actor.ts
acting as another actor, with an origin and a reason	impersonate.ts
is an error worth retrying? one classification per code	error-retry.ts
how long to wait before the next attempt — one curve, one jitter table	backoff.ts
the retry executor and the pure decision behind it	retry.ts
which HTTP statuses are worth repeating	retryable-status.ts
N callers on one key are ONE run	single-flight.ts
how many may run at once, and how many may wait	flight-gate.ts
whether an answer still applies — X_SUPERSEDED	generation-fence.ts
the five composed into one typed-client call — dedup, fence, retry, deadline, ceiling	client-flight.ts
what a typed client puts on the wire and reads back off it	client-wire.ts
the ONE browser HTTP function — credentials, JSON, the error decode, records, the fence	client-transport.ts + client-dispatch.ts + client-problem.ts
the ONE URL rule for actions and queries	client-paths.ts
the records envelope an answer carries behind x-ultimate-records: 1	record-envelope.ts
the per-tab page handle (globalThis[Symbol.for('ultimate.client')]) records land in	record-sink.ts
which principal the page acts for, and the epoch that moves when it changes	client-scope.ts
which row survives a conflict — server-wins, last-write-wins, custom	conflict-policy.ts
the four shapes an async region can be in	async-state.ts
the audit seam action and query share — AuditRecord (name, primitive, surface, outcome, the parsed input; action is a deprecated alias of name until 25.0.0), AuditSink, the ONE installed sink (setAuditSink / getAuditSink / resetAuditSink, re-exported by @ultimat3/action), and AUDIT_RECORD_FIELDS, the field list both primitives' tests pin their records to	audit.ts
is this unknown a keyed record?	json-object.ts
typed env validated at boot	env.ts
.env.example rendered from that schema, and its drift check	env-example.ts
named environments + ULTIMATE_ENV resolution	environment.ts
which store backs a seam — storeMode(env): memory under test, database everywhere else	store-mode.ts
the boot refusal of a shipped dev signing secret outside development/test — X_CURSOR_SECRET_DEV	dev-secrets.ts
a value that cannot be printed by accident	secret.ts
the committed encrypted secrets envelope, AES-256-GCM	secrets.ts
the two secrets files, and decrypted values → defineEnv	secrets-store.ts
a key file only its owner can read — 0600, and an icacls ACL on Windows — written via temp + rename, the rename retried on EPERM/EBUSY (writeMasterKeyFile, stageMasterKeyFile, promoteStagedMasterKey)	secrets-key-file.ts
one value sealed under the master key — seal() / open()	seal.ts
the key ring those work under: the current key plus retired ones	seal-keys.ts
defineConfig() for app.config.ts	config.ts
how overlays layer onto it — per section, key by key	config-merge.ts
what each key is when no layer says	config-defaults.ts
the shape screens that run before any rule reads a value — section, list, boolean, closed set, path	config-shape.ts
the keys a major deleted (locales, defaultLocale, defaultTimeZone, defaultCurrency, theme.tokens in 25.0.0; jobs.driver, deleted in 5.0.0 and refused since 25.0.0) — each REFUSED by name with X_CONFIG_INVALID and its replacement, never ignored	config-removed.ts
the pwa block — what an install needs, and the boot refusal when it is not there	config-pwa.ts
isSameOriginPath(value) — a path on THIS origin as a browser resolves it: refuses //host, /\host, a C0 control or DEL (/\t/evil.example parses to //evil.example) and a dot segment leaving a // pathname. The one predicate for every URL precached as an offline answer, @ultimat3/pwa's build included	config-pwa.ts
the closed route vocabulary every renderer names	route-vocabulary.ts
which of two route patterns wins a pathname (routeRank)	route-rank.ts
runtime roles + ROLE resolution	roles.ts
Clock — the only source of "now"	clock.ts
UUIDv7, nanoid, branded ids	ids.ts
structured JSON logging + redaction; setLogSink(sink) — the test seam that sends every default-writer line to a sink instead of the process's streams (a test preload drops them; a test asserting on the process logger collects them)	logger.ts
OTel-shaped spans, always on, no-op by default	telemetry.ts
the sampling decision, and OTEL_TRACES_SAMPLER*	sampler.ts
OTLP/HTTP JSON: endpoint, headers, value encoding	otlp.ts
SpanExporter on the wire, batched	otlp-span-exporter.ts
MetricExporter on the wire	otlp-metric-exporter.ts
may a caller read this 5xx code's cause? hasPublicCause(code) — one predicate for the HTTP problem document, MCP error data and an agent tool_result	public-cause.ts
reportError + the ErrorReporter seam, no-op by default	error-reporter.ts
that seam on the wire, Sentry's envelope and DSN	error-reporter-sentry.ts
OTel-shaped counter / gauge / histogram, same seam	metrics.ts
the /metrics scrape body	metrics-text.ts
the series every process emits, incl. what the chart scales on	runtime-metrics.ts
what the process itself costs: process_resident_memory_bytes, process_heap_used_bytes, process_heap_total_bytes, process_external_memory_bytes, process_cpu_seconds_total, process_event_loop_lag_seconds, process_start_time_seconds, process_info{role} — server-only, never on @ultimat3/core/page	process-metrics.ts (startProcessMetrics, readProcess)
graceful drain, /healthz, /readyz	lifecycle.ts
what a health endpoint tells whom — healthBody(report, role, detailed), healthPeerListed(peers, address), DEFAULT_HEALTH_DETAIL_PEERS; the one rule @ultimat3/http and the sync node's own listener both call	health-disclosure.ts
the readiness grace between /readyz → 503 and the listener closing (drain.readinessGraceMs)	lifecycle-grace.ts
the drain budget's default and domain (drain.deadlineMs, 25 s, 1–3600000 ms) — DRAIN_DEADLINE_DEFAULT_MS, DRAIN_DEADLINE_MAX_MS	drain-deadline.ts
jobs.concurrency's default and domain — one slot count for every queue a worker serves, or a table per queue ({ banks: 4, 'banks-long': 2 }; a queue the table does not name runs at the default). JOBS_CONCURRENCY_DEFAULT (8), type JobsConcurrency	config-jobs.ts
SIGTERM/SIGINT → the one drain; on Windows also SIGHUP (console close) and SIGBREAK (Ctrl-Break) — drainSignals(platform)	lifecycle-signals.ts
is this directory inside a bun build --compile binary? isCompiledBundle(import.meta.dir) — /$bunfs/ and Windows' B:\~BUN\	bunfs.ts
which network an IP literal belongs to — classifyAddress, for SSRF screens	address-class.ts
the network a caller's address keys a per-caller budget on — addressNetwork: IPv4 exact, IPv4-mapped as IPv4, IPv6 as its /64	address-class.ts
the sockets this process opened, so a self-request is not egress	listeners.ts
defineService('orgs', …) → ctx.orgs, rebuilt per actor	service.ts
the registrar table one same-tier package reaches another through	registrar.ts
decode → resize → encode, the one image pipeline (over Bun.Image)	image/
assertNever, assertCoded, assert	assert.ts
the one HTML character table — escapeHtml, text and attributes alike (& < > " ')	html-escape.ts
the one Cookie: reader — readCookie(header, name), null when absent, never a throw	cookie.ts
the one Set-Cookie writer — serializeSetCookie(name, value, options?); defaults Path=/; HttpOnly; Secure; SameSite=Lax, the value percent-encoded so readCookie returns it exactly, X_COOKIE_INVALID for a non-token name, a pair over 4096 octets, SameSite=None/Partitioned without Secure, a broken __Secure-/__Host- prefix rule, or an injectable Path/Domain. Expires is an IMF-fixdate in UTC	cookie.ts
the one AWS Signature V4 signer — signAwsRequest({ method, url, headers?, payload?, credentials, region, service, clock? }) → the URL, every header to send (authorization, x-amz-date, x-amz-security-token, x-amz-content-sha256 by default on s3), the canonical request and string-to-sign. payload: { body }, a pre-taken { sha256Hex }, or UNSIGNED_PAYLOAD. S3 encodes the path once, every other service twice. Web Crypto, no SDK; proven on the aws-c-auth SigV4 suite and S3's worked examples. Shared by storage's s3 disk and mail's SES driver	aws-sigv4.ts
32-bit FNV-1a — a BUCKET (rollouts, factory seeds), never a sharing key (fingerprint is)	fnv1a.ts
PgExecutor — the structural query(text, values) seam every Postgres store takes	pg-executor.ts
a declared retirement as headers — renderDeprecation (RFC 9745 Deprecation, RFC 8594 Sunset, the successor-version link) and recordDeprecatedCall on the one deprecated_calls_total; action and query both project through it	deprecation.ts

Each of the five, and fingerprint, storeMode and render's contentHash, has ONE implementation: bun run flight-copies refuses a second by its shape (X_HELPER_COPY), whatever it is named.

Errors are instructions

throw new UltimateError({
  code: 'X_DB_DRIFT',
  cause: 'table "posts" has column "publish_at" not present in any migration',
  fix: 'x db gen "add publish_at"',
});

X_DB_DRIFT: schema differs from migrations
  cause: table "posts" has column "publish_at" not present in any migration
  fix:   x db gen "add publish_at"

format() is always 3 lines (format({ docs: true }) adds a 4th). toJSON() is the --json form: { code, title, cause, fix, docs, retry, meta, stack }. The title comes from the registry, so the terminal, the browser overlay and --json cannot drift.

retry is terminal | retryable | retry-after, and it defaults to terminal — a client that retried on status >= 500 hammered X_DB_DRIFT and X_TENANCY_UNSCOPED, which are permanent config faults, during the incident they were already causing. Classify the codes your package or app throws once, beside the module that declares them:

registerErrorRetry({ X_OAUTH_EXCHANGE_FAILED: 'retryable', X_RATE_LIMITED: 'retry-after' });

Core's own classifications are closed, exactly as registerErrorStatus's framework table is: a second, different registration for one code throws X_ERROR_RETRY_INVALID.

Two readers, and the difference is load-bearing. retryFor(code) answers what to do and fails closed — terminal for a code nobody classified. declaredErrorRetry(code) answers what somebody actually declared, and is undefined when nobody did. UltimateError.retry is init.retry ?? retryFor(code), so every unclassified error already carries terminal: a caller deciding whether to stop work already in flight reads declaredErrorRetry, and the job executor that read retryFor instead would dead-letter attempt 1 of every job in every app whose codes nobody has classified. An instance-level retry: 'terminal' on an unregistered code is indistinguishable from that default and is read as unclassified — register the code (registerErrorRetry({ X_YOUR_CODE: 'terminal' })), which is the one way.

Code	Subclass
X_CONFIG_INVALID	ConfigInvalidError
X_ENV_MISSING	EnvMissingError
X_NOT_IMPLEMENTED	NotImplementedError
X_INTERNAL	InternalError

Your package declares its own codes in src/errors.ts and registers them once: registerErrorCodes({ X_DB_DRIFT: { title: 'schema differs from migrations' } }). Registering a code twice throws X_ERROR_CODE_DUPLICATE.

isUltimateError() is duck-typed on Symbol.for('ultimate.error'), not instanceof — that is how @ultimat3/schema (tier 0, cannot import core) still produces matching errors.

A value you did not produce goes through the renderer

An error factory may never throw while formatting its own message: the caller then catches a TypeError instead of the refusal, error.code === 'X_…' matches nothing, and an HTTP surface answers 500 where the mapped status belonged. JSON.stringify throws on a bigint and on a cycle and RUNS any toJSON the value carries; `${value}` throws on a symbol and on a hostile toString. Both are reachable from app data.

import { renderCauseValue, renderFixLiteral, UltimateError } from '@ultimat3/core';

declare const kind: unknown;
declare const value: unknown;

throw new UltimateError({
  code: 'X_ID_INVALID',
  cause: `expected a ${renderCauseValue(kind)} UUIDv7, received ${renderCauseValue(value)}`,
  fix: `pass an id produced by typedId<${renderFixLiteral(kind, '<kind>')}>()`,
});

Helper	For	Degrades to
renderCauseValue(value)	a cause, which only has to describe	a object that cannot be rendered
renderFixLiteral(value, placeholder)	a fix, which has to parse and run	the placeholder you name
renderThrowable(value)	a caught value: an Error's own words, anything else rendered	renderCauseValue(value)
isThrownError(value)	value instanceof Error where the test itself may throw	false
stringField(value, key)	one string field off a caught value	undefined

The last two are the READ side, and the reason they exist is that the renderers above them were being reached past an unguarded probe. catch (error) hands you a value the framework did not build: error instanceof Error runs a Proxy's getPrototypeOf trap, and typeof error.code === 'string' — the structural check every surface uses to recognise an UltimateError that crossed a worker, a subprocess or a socket — is a getter call. Either one throws one line before the total renderer that was meant to make the path safe.

const code = stringField(error, 'code') ?? 'X_TRANSPORT_UNAVAILABLE';
const cause = stringField(error, 'cause') ?? renderThrowable(error);

stringField answers undefined for absent, wrong type and threw, because all three mean the same thing to the caller: this value did not supply the field, so use the default.

Enforced, not documented: x verify's errors step fails with X_ERROR_RENDER_UNSAFE when a parameter typed unknown reaches a cause: or fix: through JSON.stringify, String() or a bare interpolation (scripts/error-render.ts).

Error classes

Every error class src/index.ts exports, for instanceof inside one process. Across a wire or a job boundary the class is gone and the code is what survives — match on that.

Class	Code	Declared in
ConfigInvalidError	X_CONFIG_INVALID	src/errors.ts
CookieInvalidError	X_COOKIE_INVALID	src/cookie.ts
CursorInvalidError	X_CURSOR_INVALID	src/cursor.ts
CursorSecretDevError	X_CURSOR_SECRET_DEV	src/dev-secrets.ts
EnvironmentInvalidError	X_ENVIRONMENT_INVALID	src/environment.ts
EnvMissingError	X_ENV_MISSING	src/errors.ts
ErrorReporterDsnInvalidError	X_ERROR_REPORTER_DSN_INVALID	src/error-reporter-sentry.ts
ImageDecodeFailedError	X_IMAGE_DECODE_FAILED	src/image/errors.ts
ImageTooLargeError	X_IMAGE_TOO_LARGE	src/image/errors.ts
ImageUnsupportedError	X_IMAGE_UNSUPPORTED	src/image/errors.ts
InternalError	X_INTERNAL	src/errors.ts
MetricCardinalityError	X_METRIC_CARDINALITY	src/metrics.ts
MetricNameInvalidError	X_METRIC_NAME_INVALID	src/metric-names.ts
MetricValueInvalidError	X_METRIC_VALUE_INVALID	src/metrics.ts
NotImplementedError	X_NOT_IMPLEMENTED	src/errors.ts
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
SecretsKeyAclError	X_SECRETS_KEY_ACL_FAILED — Windows only: icacls could not restrict a new key file, so none was written	src/secrets-key-file.ts
SecretsKeyInvalidError	X_SECRETS_KEY_INVALID	src/secrets-errors.ts
SecretsRingKeyInvalidError	X_SECRETS_KEY_INVALID — a malformed entry of ULTIMATE_SECRETS_RETIRED_KEYS	src/secrets-errors.ts
SecretsKeyMismatchError	X_SECRETS_KEY_MISMATCH	src/secrets-errors.ts
SecretsKeyMissingError	X_SECRETS_KEY_MISSING	src/secrets-errors.ts
SecretsPlaintextInvalidError	X_SECRETS_PLAINTEXT_INVALID	src/secrets-errors.ts
SecretsTamperedError	X_SECRETS_TAMPERED	src/secrets-errors.ts
UltimateError	any registered code — every class in the framework extends it	src/errors.ts

Context

const ctx = ctxOf({ actor: agentActor({ id: 'mcp-1', scopes: ['post:publish'] }) });
await runWithContext(ctx, async () => {
  const { actor, locale, tz, logger } = useContext();   // throws X_NO_CONTEXT outside
  await withChildContext({ locale: 'es' }, () => render());
});

Concurrent requests never leak into each other. ctx.logger carries requestId + traceId automatically; so does the root logger while a context is active. Add typed services by augmenting CtxServices; reach late-bound ones with useService<T>('mail').

A service that reads the actor (ctx.posts, scoped to ctx.actor.orgId) registers once with defineService('posts', (ctx) => ({ ... })), at import time. ctxOf and withChildContext then build it fresh, bound to whichever actor they are constructing a ctx for — importing the module that calls defineService is the registration, the same convention registerActions uses. Passing services: { posts: ... } to ctxOf still works and wins over a registered factory of the same name, for a test that wants to hand in a mock.

A factory runs again on every ctxOf / withChildContext call and is never cached, because it closes over the ctx (actor, clock, tz) it was built for. withChildContext drops a factory-managed name from what it carries forward on purpose: only an ad hoc service nobody registered survives an actor swap unrebuilt.

Actor facts — the app's own authz vocabulary, on the framework's actor

Roles and an org id answer a columnar question ("same tenant?"). They cannot answer a relational one ("a friend of the author?"), and a policy predicate is synchronous, so it may not go and fetch one. Resolve the graph ONCE per request and hand it to the actor every surface already carries:

declare module '@ultimat3/core' {
  interface ActorFacts { readonly viewer: Viewer }   // declared once, app-wide
}

// at the request boundary, where the await already happens
const actor = withFacts(userActor({ id: user.id, roles: [user.role] }), { viewer });

// in a predicate, on any surface — HTTP, MCP, admin, a job
can('post:read', ({ row, actor }) => row !== null && canSee(actorFact(actor, 'viewer'), row));

Rule	Why
actorFact(actor, key) takes Actor | null	that is exactly what a predicate is handed
every fact is T | undefined	nothing can prove one was resolved — a job, a test and a token exchange mint actors too, so an absent fact is a denial the compiler makes you write
facts is optional on Actor	additive: an actor literal written before the seam is still an Actor
the framework declares no fact	ActorFacts is the app's; core only owns the seam. type-pins.ts pins the machinery against a local sample rather than augmenting the real interface

Not a second authz path: the facts ride the actor the policy layer already reads, so no surface package learns the app's vocabulary and one Policy object still answers everywhere. Facts are request-scoped and never logged — actorLabel() stays id-only.

Env fails once, completely

export const env = defineEnv({
  DATABASE_URL: { type: 'url', secret: true },
  PORT:         { type: 'port', default: 3000 },
  REGION:       { type: 'enum', values: ['us', 'eu'] },
  SENTRY_DSN:   { type: 'url', required: false },
  NATS_URL:     { type: 'url', role: 'sync' },   // only required for ROLE=sync
});

Every missing or malformed key is listed in one X_ENV_MISSING. secret: true keys are redacted in logs and masked in checkEnv() output; describeEnv() emits declarations only, safe for x.manifest.json. Omit required for required — required: false is the only loosening. Never declare an env var for which deploy this is — that is ULTIMATE_ENV, below.

.env.example is a projection of that schema, never a second list: renderEnvExample(schema) writes it and checkEnvExample(schema, text) reports missing / extra as data. The gate is x verify's manifest step (X_ENV_EXAMPLE_DRIFT, fixed by x env example) — the failure that otherwise arrives as somebody else's X_ENV_MISSING on a variable nobody documented. assertEnvExample (key presence only, called by nothing) was deleted in 25.0.0.

Loading .env is Bun's, not ours. envFileCandidates() states what it does, measured: .env → .env.<mode> → .env.local, with .env.local skipped under test, and the mode being production, test or development for everything else — staging included. There is no .env.staging; a staging deploy carries real environment variables.

One environment, one key

resolveEnvironment();      // 'development' | 'test' | 'staging' | 'production'
tryResolveEnvironment();   // the same, `undefined` instead of a throw for an unrecognised value
isProduction();            // exact; nothing else counts
isLocal();                 // development or test — never staging

tryResolveEnvironment is for a caller that must answer rather than fail — a robots.txt render is the case: ULTIMATE_ENV is not in the env schema, so nothing validates it at boot, and a typo would otherwise 500 the one response whose body was already going to be Disallow: /. It names no fallback of its own; the caller does.

ULTIMATE_ENV is the key, NODE_ENV the fallback (platforms already set it). Values are NODE_ENV's spellings plus staging — prod and dev are typos, not aliases, and ULTIMATE_ENV=prod is X_ENVIRONMENT_INVALID. An unrecognised NODE_ENV is not an error: it is not our key. This is the twin of roles.ts — ROLE says what the process does, ULTIMATE_ENV says which deploy it belongs to.

storeMode(Bun.env) is the one answer to "memory store or database store?" for a seam with both — memory under test (no database client is installed there), database everywhere else, x dev's embedded PGlite included. Never a DATABASE_URL truthiness check: x dev sets none.

A secret is redacted by value, not by name

const dsn = secret(process.env.DATABASE_URL ?? '', 'DATABASE_URL');
logger.info('boot', { dsn });        // {"dsn":"[redacted]"}
connect(revealSecret(dsn));          // the one greppable way out

isRedactedKey(key) is the one answer to "is this field a credential?" — the log line, the error monitor's envelope and @ultimat3/action's audit row all ask it. It matches the exact names redactKeys() holds (defineEnv adds every secret: true variable) and a credential-bearing name it was never told about: password / passphrase anywhere, secret as the last word, any …token that is not a dedupe or paging key (resetToken, githubToken, NPM_TOKEN), key material by its qualifier (signingKey, masterKey, accessKeyId), a value that embeds a credential (connectionString, dsn, databaseUrl), the one-time codes (totpCode, recoveryCode), session and bearer material (credentials, jwt, bearer, cookie, sessionId, sessionKey, privateKeyPem), card data (cvv, cvc, a whole-word pin such as cardPin or pinCode) and a stored hash of any of them (passwordHash, tokenHash, keyHash). @ultimat3/action also asks it before storing an idempotent answer. It deliberately leaves idempotencyToken, a paging token, maxTokens, an error code, spinner, isPinned, sessionStart and cookieName readable — a redacted field is one an operator cannot correlate on.

LOG_LEVEL is refused when it is not one of LOG_LEVELS (lowercase), exactly as structuredLogger({ level }) refuses it; unset or empty is info.

A Secret box catches the other case: String(), template literals, +, JSON.stringify, console.log, the logger and an error's meta all render [redacted], whatever key it sits under. It is frozen and everything but label is non-enumerable, so { ...dsn } cannot spread the value back out. There is no vault integration and there will not be one — that is a platform primitive (axiom 7); a Secret plus the platform's own secret store is the whole design.

Encrypted secrets are env values that arrive early

// app.config.ts
await installSecrets();                       // secrets.enc.json → process.env, real env wins
export const envSchema = {
  SESSION_SECRET: { type: 'string', secret: true },
} satisfies EnvSchema;
export const env = defineEnv(envSchema);

secrets.enc.json is committed; .secrets.key is not, and ULTIMATE_SECRETS_KEY is read before it so a container is handed its key by the platform. The plaintext is a flat map of environment variable names to values, so a secret keeps one declaration (envSchema), one .env.example row, one mask (maskedEnvValues), one redaction entry and one reader (env.SESSION_SECRET). There is deliberately no secrets.get(): a second accessor would mint values with no declaration, no type and no mask, and each of those five would need a second implementation. x secrets is the only writer.

Envelope
Cipher	AES-256-GCM through WebCrypto, 128-bit tag, a fresh 12-byte IV per seal
Key	32 CSPRNG bytes, hex. No KDF — the key is the key
AAD	v, alg and kid, so a downgraded header fails the tag rather than changing how the body is read
kid	a domain-separated, truncated SHA-256 of the master key. Safe to commit, and what makes wrong key (X_SECRETS_KEY_MISMATCH) a different code from edited file (X_SECRETS_TAMPERED)

A missing file is not an error — an app may declare no secrets. A file with no key to open it 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.

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').
• uuidV7() is UUIDv7: time-prefixed, monotonic within a millisecond, never backwards on clock skew. typedId<'post'>() brands it so a post id cannot be passed where a user id is wanted.
• withSpan('action.publishPost', fn) is free until configureTelemetry({ exporter }). Traces cross process boundaries via traceparent() / parseTraceparent(), whose ids come from traceId() / spanId() — never uuidV7(), whose dashed 36 characters every collector rejects. isTraceId() / isSpanId() are the one definition of the valid shape.
• Sampling is honoured, not just propagated. startSpan takes the parent's bit when there is one, else asks the Sampler; span.end() exports nothing when the bit is 0. The default reads OTEL_TRACES_SAMPLER / OTEL_TRACES_SAMPLER_ARG at the first span, and configureTelemetry({ sampler }) replaces it. shouldSample is handed the TRACE ID of the span being created, so traceidratio decides once per trace by hashing it — a roll per span left one trace half exported, which is orphan children under a root the collector never saw.
• The OTLP exporters ship, speaking OTLP/HTTP JSON, no dependency: otlpSpanExporter({ endpoint }) (batched, with flush() / shutdown()) and otlpMetricExporter({ endpoint }). Both default to OTEL_EXPORTER_OTLP_ENDPOINT; tryOtlpEndpoint('traces') answers undefined when nobody configured one, so a boot can skip the exporter instead of throwing. gRPC (:4317) is out of scope and says so with X_OTLP_PROTOCOL_UNSUPPORTED.
• Metrics are the same shape one signal over: counter(), gauge(), histogram(), aggregated in process, free until configureMetrics({ exporter }). See below.
• onShutdown(name, hook, { phase }) with phases accept → inflight → close under one deadline; readyzPayload() flips to 503 the moment draining starts, healthzPayload() stays 200 until stopped. It returns an unregister, and a caller that starts and stops more than once has to keep it: a discarded one is a hook per start(), each retaining the resource it was going to drain, and the next drain runs every one of them against a torn-down copy. shutdownHookCount() is the test-only probe that makes the leak assertable.
• registerReadinessCheck(name, check) is what makes /readyz mean usable rather than bound. ReadinessCheck is () => boolean and must stay synchronous — a probe that awaits its dependency turns a slow dependency into a wedged endpoint and then a restart loop; keep a boolean fresh and let the check read it. It returns an unregister. HealthReport.checks is a map of name → 'ok' | 'failing', so "alert on check failures by check name" is writable.
• HealthReport.registered is the third state. checks: {} reads identically for "every check passed" and "nobody registered one", and an empty registry is still ready — reported, never enforced, so a role with no dependency does not have to invent a check to boot. Read registered before trusting an empty checks.
• Anything that opens a socket calls markListening(server.url.origin) and releases it on close. That is what tells the sealed test network a loopback request is this process, not egress.

Metrics: same seam as tracing, one signal over

const published = counter('posts_published_total', { description: 'posts published' });
published.add(1, { plan: 'pro' });

gauge('queue_depth', { observe: () => pending() });   // read at scrape time, never stale
histogram('render_duration_seconds').record(ms / 1000);

metricsText();          // the /metrics body, at METRICS_PATH, METRICS_CONTENT_TYPE
collectMetrics();       // the same numbers as data, for a MetricExporter

Kinds	counter (monotonic sum), gauge (record / add, or an async observe), histogram (explicit bounds, OTel's default latency set)
Temporality	cumulative, as OTel defines it — a read never resets a counter, so two scrapers cannot steal each other's samples
Names	lowercase snake_case, the intersection every exposition format accepts. Dotted OTel names survive OTLP and die at a Prometheus scrape
Attributes	string | number | boolean only — each distinct set is a stored series, so a user id here is an outage
Cardinality	enforced, not advised: maxSeries per instrument (default DEFAULT_MAX_SERIES), and past it every new label set folds into one otel_metric_overflow="true" series with X_METRIC_CARDINALITY logged once, naming the instrument
Async gauges	an observe() that throws, or answers a non-finite number, costs that instrument its point and nothing beside it — X_METRIC_VALUE_INVALID logged once, naming the instrument. Unguarded it took the whole /metrics body down with it, and startMetricExport's timer callback raised where nothing can catch it
Driver seam	MetricExporter, defaulting to a no-op. memoryMetricExporter() for tests, startMetricExport(ms) for a periodic push, otlpMetricExporter() for a collector

runtime-metrics.ts holds the series every process emits, and SCALING_METRICS maps each ScalingSignal from roles.ts to the one that carries it — so the role table, the chart and the process cannot drift apart:

Role scales on	Series	Instrument
rps	http_requests_total	counter; rps is a rate the adapter derives (rate(http_requests_total[1m])), never a stored number
ws-connections	connections	gauge, +1/-1
queue-depth	queue_depth	gauge, by queue label

As of 2026-08 all three are emitted and scraped. One call site per package — recordRequest from @ultimat3/http's pipeline, recordConnection from @ultimat3/realtime's socket table, recordQueueDepth from @ultimat3/jobs' worker loop — and @ultimat3/cli serves metricsText() at METRICS_PATH on METRICS_PORT (9090), for every role rather than only the ones that open an HTTP socket. Labels are route patterns, status classes and queue names: nothing per-user, per-id or attacker-chosen ever becomes a series.

Error reporting: the third seam, same shape as the other two

A no-op by default, one transport on the wire, one memory double for tests — telemetry.ts and metrics.ts' shape a third time. What a monitor receives is the framework's error contract verbatim, so it groups on code and shows fix to whoever is paged.

An Ultimate app installs nothing. @ultimat3/cli's serve.ts calls configureErrorReporting at boot from one env var — SENTRY_DSN, unset meaning the no-op stays and nobody is paged — and passes the build id it already computed as release. The call below is for a host that boots something other than runRole.

import { configureErrorReporting, reportError, sentryErrorReporter } from '@ultimat3/core';

declare const sentryDsn: string;
declare const buildId: string;
declare const failure: unknown;

configureErrorReporting({
  reporter: sentryErrorReporter({ dsn: sentryDsn }),   // config, never a constant in this package
  release: buildId,                                    // the id `x-ultimate-build` carries
});

reportError(failure, { source: 'http', severity: 'error', scope: { operation: 'POST /api/posts' } });

reportError(error, { source, severity?, scope? })	never throws, never awaits. A monitor that is down must not turn one failure into two
ERROR_SOURCES	http job realtime cli process — closed. A new surface adds a member, never a string of its own
ErrorSeverity	warning error fatal. warning is a failure the framework already recovered from — a retry, not a dead letter
ErrorScope	requestId traceId spanId role operation actorId extra. operation is a route pattern or a job name, never a concrete path or a row id
ErrorReport	code title cause fix docs + meta stack resource environment release scope, and the thrown value under error
configureErrorReporting({ reporter, clock, release, environment, enabled })	the one install point; resetErrorReporting() puts the no-op back
Reporters	noopErrorReporter (default), memoryErrorReporter() (.events, .reset()), sentryErrorReporter({ dsn, fetch?, clientName? })
Wire, testable alone	parseSentryDsn(dsn) → { publicKey, envelopeUrl, … }, sentryEnvelope(report, { dsn, eventId }) → the envelope body. Pure, exactly as otlpTraceRequest is
errorReport(error, options)	the normalisation on its own, for a transport's test or a surface that enriches before sending

As of 2026-08 four packages call reportError, seven call sites in all: @ultimat3/http's stages.ts (status >= 500 only), @ultimat3/jobs' executeJob — the one frame still holding the thrown value — @ultimat3/realtime's sync-node.ts and sync-upgrade.ts, and @ultimat3/flags' runtime.ts (source: 'process', severity warning). Trace and span resolve as a pair from one source: a caller-supplied traceId never picks up the ambient spanId, because a report claiming a span from a different trace sends whoever is paged somewhere authoritative and wrong.

ErrorReporterDsnInvalidError (X_ERROR_REPORTER_DSN_INVALID) is the only code this seam owns — raised at parseSentryDsn, at configuration, never at a report.

One cursor, everywhere

encodeCursor({ scope, key: ['2026-01-01T00:00:00.000Z'], id: 'p_9' }); // base64url(body).hmac
decodeCursor(cursor, scope);                                          // or X_CURSOR_INVALID

Keyset pagination is the repo's, the read primitive's and the admin's — so the codec is here, signed once and verified once, and a second one anywhere is the regression cursor.ts exists to prevent. scope binds a cursor to one read: the entity plus its filters and sort order for a repo page, queryHash(name, input) for a query, the resource for the admin. It is a required argument to decodeCursor on purpose — an optional check is one a call site can forget, and a forgotten one pages a listing with another read's cursor. Replaying one is X_CURSOR_INVALID, never a silently wrong page.

Signature	truncated HMAC-SHA256, compared in constant time
Secret	configureCursorSigning() at boot, else ULTIMATE_CURSOR_SECRET. An EMPTY value is unset — never an empty HMAC key — so usesDevCursorSecret() reports it and the boot refuses it outside a local environment. Read when a cursor is signed, never at import — an app whose openSecrets() sets the variable during boot would otherwise sign every cursor with the dev key. Rotating it invalidates every open cursor
Also keys	keyedFingerprint(value, purpose) — h1:<key id>:<HMAC> over canonicalJson, under a per-purpose key derived from this secret; the fingerprint to PERSIST (@ultimat3/action's idempotency requestHash). compareFingerprint answers match / mismatch / unverifiable (other key), and still checks a legacy bare fingerprint() exactly. Rotating the secret makes in-window stored fingerprints unverifiable
Signed, not encrypted	the client already has these rows; what it must not do is invent a position
usesDevCursorSecret({ env? })	true while the shipped dev key is in use — this process, or the table env as signing would read it (empty and the published key count as unset)
CURSOR_SECRET_KEY / CURSOR_SECRET_FIX	'ULTIMATE_CURSOR_SECRET' and the one fix: for X_CURSOR_SECRET_DEV (export ULTIMATE_CURSOR_SECRET="$(openssl rand -hex 32)") — the boot refusal and @ultimat3/cli's deploy contract (.env.example, x env check, x doctor) read both
devSecretsRefused({ env? })	THE rule for refusing a shipped dev secret: anything but development/test, and no named environment counts as production. The boot (assertNoDevSecretsOutsideLocal), @ultimat3/storage's disk and the CLI's diagnostics all ask it
resetCursorSigning()	test seam: forget configureCursorSigning and fall back to the environment

One page shape

Page<Row> (src/cursor-page.ts) is what every cursor page answers — an entity findMany, a query's .page(), the ?_first= HTTP envelope and the typed client: { rows, nextCursor, hasMore }, with ONE meaning. nextCursor is the cursor for the next page and null exactly when hasMore is false, so while (page.hasMore) and while (page.nextCursor !== null) are the same loop and both stop on the last page without fetching an empty one.

The type	a union of { nextCursor: string; hasMore: true } and { nextCursor: null; hasMore: false } — a literal that disagrees is a build error (type-pins.ts), and if (page.hasMore) narrows nextCursor to string
pageOf(rows, nextCursor)	the only constructor: hasMore is derived from the cursor, never passed beside it. null (or '') is the last page
Re-exported	by @ultimat3/query as its Page; @ultimat3/entity exports none — import it from here

One bounded cache for every Intl formatter

import { assertLocale, cachedFormatter } from '@ultimat3/core';

const cache = new Map<string, Intl.NumberFormat>();

export function euroFormatter(locale: string): Intl.NumberFormat {
  // Validates AND canonicalizes: `EN-us` and `en-latn-us` collapse to one key, and a tag `Intl`
  // cannot parse is `X_LOCALE_INVALID` here rather than a bare `RangeError` out of the constructor
  // below. `canonicalLocale(locale) ?? locale` is the same call with the refusal deleted — it is
  // what `@ultimat3/money` did, and an `Accept-Language` value of `en_US` took the request down.
  const tag = assertLocale(locale);
  return cachedFormatter(
    cache,
    `${tag}|EUR`,
    () => new Intl.NumberFormat(tag, { style: 'currency', currency: 'EUR' }),
  );
}

A locale arrives from Accept-Language and a zone from x-timezone, so an unbounded Map keyed on that string is memory the client chooses. Measured As of 2026-08: 4,096 casings of one zone name retained 31 MB, and 20,000 valid en-US-x-* tags through formatMoney retained 55.1 MB. The bound (MAX_CACHED_FORMATTERS, 512, FIFO) and the canonical key are two halves of one rule and neither is sufficient alone — an unknown -u- extension value survives canonicalization as a distinct string, and the cap alone lets one locale evict itself under three spellings. A miss costs one Intl construction, never a wrong answer, which is what makes the bound safe. It lives here rather than in @ultimat3/time because @ultimat3/money needs it too and tier 1 may not import sideways.

The refusal is bounded for the same reason the cache is. X_LOCALE_INVALID answers 400 and @ultimat3/http's toProblem copies a cause into the response detail and into the log line, so a tag echoed verbatim is a stranger-chosen string of unbounded length in a shared log index. localeInvalid quotes back the first MAX_LOCALE_EXCERPT (35) code points — RFC 5646 §4.4.1's own figure for the longest tag the registry can form — and appends (truncated at 35 characters) when there were more, so a cut value is never read as a whole one. describeValue is deliberately not used here: "a 5-character string" deletes the only actionable content in a sentence whose job is to name the tag. The whole tag rides in meta.locale, which is the half that gives a redactor a key to address; a value spliced into prose has none.

One flight layer — wait, classify, share, bound, fence

import {
  backoffDelay,
  generationFence,
  flightGate,
  singleFlight,
  isRetryableStatus,
} from '@ultimat3/core';

// One ceiling on work whose cost is memory, one run per key, one fence over the answer.
const gate = flightGate({ maxConcurrent: 8, maxQueued: 64 }, { subject: 'jwks fetches' });
const flights = singleFlight({ deadlineMs: 30_000 });
const fence = generationFence('the jwks cache');

export async function jwks(url: string): Promise<Response> {
  const issued = fence.generation();
  const answer = await gate.run(
    async () =>
      await flights.run(url, async () => {
        const first = await fetch(url);
        if (!isRetryableStatus(first.status)) return first;
        const waitMs = backoffDelay({ attempt: 1, base: 500, max: 8_000, jitter: 'full' });
        await new Promise<void>((wake) => {
          setTimeout(wake, waitMs);
        });
        return await fetch(url);
      }),
  );
  // X_SUPERSEDED if anything called bump() while the fetch was in flight.
  fence.guard(issued);
  return answer;
}

Eight modules, one tier-0 home — because the framework had N copies of each and no owner: four backoff curves (@ultimat3/jobs, @ultimat3/ai, @ultimat3/realtime, and @ultimat3/db with none at all), five retryability tables — two of them byte-identical in packages that cannot import each other — and three separate concurrency bounds, only one of which refused past its queue. error-retry.ts declared the vocabulary (terminal | retryable | retry-after) and nothing consulted it before deciding to try again. As of 2026-08-23.

Export	The one answer	The question it settles
backoffDelay({ attempt, base, max, factor?, curve?, jitter?, random? })	one curve — exponential | linear | fixed, full | equal | none — 1-based attempt, clamped to max before jitter, rounded, and 0 rather than NaN	how long to wait. random is injectable, so a schedule is a unit test rather than a range
singleFlight({ deadlineMs?, schedule? }) → run(key, work, join?), size	N callers on one key are ONE run	who pays for a miss. Eviction is identity-checked, so a load that settles late never drops the load that replaced it; deadlineMs frees the KEY a wedged load would hold forever — it never cancels the work and never rejects a joiner
flightGate({ maxConcurrent, maxQueued }, { subject?, overflow? })	one bound, one queue, one refusal	how many at once. Past the queue the answer is X_FLIGHT_GATE_OVERLOADED (503) and never a longer queue; the slot is HANDED to a waiter, never released and re-acquired. Both limits are screened at construction (finiteCount, 0 allowed); a width of 0 refuses every caller rather than queueing for a slot that never frees. run(work, signal?): an abort while QUEUED removes the waiter and rejects with the abort's reason
generationFence(subject) → generation(), bump(), guard(issued)	whether an answer still applies	X_SUPERSEDED (499) and isSuperseded(error) — the piece nothing in the tree had. guard compares !==, never <
isRetryableStatus(status), RETRYABLE_STATUSES	>= 500, plus 408, 409, 425, 429	which HTTP answers are worth repeating
jitterStatedDelay(waitMs, capMs, random?)	the ONE rule for a delay a responder named	the stated wait as a FLOOR plus a spread in [0, min(wait / 2, cap)), so a burst told Retry-After: 1 does not replay in lockstep. retryDecision's retry-after path (floor clamped to max; jitter: 'none' gets the bare floor) and @ultimat3/jobs' rate-limit deferral and webhook throttle all take it
retry(work, policy, { sleep, now?, random? }), retryDecision(policy, attempt, error, random?)	the executor and the pure decision behind the classification	whether to try again at all. clientFlight is its one caller in the framework; jobs, ai and db each keep their own loop and delegate only the arithmetic and the classification
clientFlight({ principal?, retry?, deadlineMs?, limit?, … }) → run(plan), keyFor(url, opts?), bump(), generation()	the five above composed into one typed-client call	dedup, supersession, retry, one wall-clock deadline and a concurrency ceiling, for a call whose dispatch the caller supplies. @ultimat3/action and @ultimat3/query import it from here and re-export only its types — one file, because both are tier 3 and neither may import the other
isTransientFailure(error)	what a CLIENT may send again	a declared retryable/retry-after, plus a dispatch that produced no response at all. It inverts retryDecision's unclassified default on purpose: a caller's own AbortError and a foreign TypeError are terminal
traceHeaders(), problemOf(text), retryForStatus(code, status, retryAfterSeconds?), FRAMEWORK_CODE	what a typed client puts on the wire and reads back off it	the W3C header (nothing at all when the span context is incomplete), a total problem+json read, and the classification a STATUS is allowed to give when nobody declared one for the code — retry-after for a 429 or 503 that stated a delay, unless the code is declared terminal
retryAfterSecondsOf(header, date), MAX_RETRY_AFTER_SECONDS	the one Retry-After reader	delta-seconds, or an IMF-fixdate measured against the same response's Date header (never the client's clock), capped at a day; 0, a date already past and anything else undefined — only a positive delay is a statement (retryAfterOf's outbound rule), so unstated falls back to the jittered curve. clientTransport passes it to problemError and to a caller's decodeError(status, text, retryAfterSeconds), which carry it as meta.retryAfterSeconds for statedDelayMs
withStatedDelay(meta, retryAfterSeconds)	a remote error's meta, for both decoders (problemError, @ultimat3/action's RemoteActionError)	the copied wire keys minus any retryAfterSeconds — the server never writes one in a body, framework meta being operator-only — plus the header's value when there was one. A body can never drive the wait
remoteTitleOf(value), MAX_REMOTE_TITLE_LENGTH	a problem document's title, as untrusted display text	a non-blank string cut at 120 characters, or nothing. Handed to UltimateError as remoteTitle, used only when this realm registered no title for the code

retry's policy.jitter is required where backoffDelay's defaults to none: a loop retrying without jitter IS the thundering herd, so the mode is a decision each caller makes rather than one it inherits without noticing. retry never wraps the last error — a wrapper would replace a code, a cause and a runnable fix: with the fact that something was retried, which no reader can act on.

classifyThrown and statedDelayMs live in error-retry.ts, one import away from the table they read; @ultimat3/jobs re-exports both rather than keeping a second pair.

One browser seam — transport, records, page handle, principal fence

Export	The one answer	The question it settles
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
resolveConflict(policy, local, server, { clockField? }), ConflictPolicy, Row	one conflict vocabulary, over ROWS	last-write-wins keeps the local row only when its numeric clock field (default updatedAt) is newer; no provable clock = the server's row
AsyncState<T>	pending | refreshing | ready | failed	the type realtime produces and ui renders; tier 0 because neither may import the other

clientTransport does not value-import clientFlight or traceHeaders() — measured sizes are in its file header. A server-side caller that propagates a trace passes traceHeaders() in headers itself.

One image pipeline, everywhere

probeImage(bytes);                                     // { format, width, height, mimeType }
await transformImageBytes(bytes, { width: 640, format: 'webp', quality: 80 });
await blurDataUrl(bytes);                              // ThumbHash PNG data: URI, the LQIP

storage variants, seo <picture> sources and pwa icons are the same three steps — decode, resize, encode — with different numbers, so there is one implementation and no second scaler for an icon to grow a halo in. The codecs are Bun.Image — statically-linked libjpeg-turbo / libspng / libwebp with SIMD resize kernels, in the runtime. Still zero dependencies: no sharp, no native module.

Every terminal is async, because the pipeline runs on a worker thread. probeImage stays synchronous: it reads a header and never decodes, which is also why it measures SVG and AVIF that no codec here reads.

Decode	PNG, JPEG, WebP, GIF. canDecode() publishes the real list
Encode	PNG, JPEG, WebP. canEncode() publishes the real list
Probe only	AVIF and SVG — measured from the header so width/height still inline and CLS stays 0
Anything else	X_IMAGE_UNSUPPORTED, naming the format and pointing at an ImageTransformDriver
Ceiling	MAX_IMAGE_PIXELS (64MP), passed to the decoder as maxPixels and refused from the header before a byte is allocated
Determinism	same bytes + same spec → same output bytes, on every platform

AVIF and HEIC are refused everywhere, deliberately. Bun.Image can reach them through an OS codec (ImageIO on macOS, WIC on Windows), and this pipeline sets Bun.Image.backend = 'bun' on every call to forbid exactly that: the static codecs and the Highway geometry kernels are what make a laptop and a Linux node produce the same bytes, and variantKey is content-addressed. A variant that re-encoded differently per platform is a cache that never hits. Producing AVIF means a CDN or a custom ImageTransformDriver.

transformImageBytes has two paths and picks by geometry. When the resampled artwork IS the output box it is one Bun.Image call, source bytes to encoded bytes. When it is not — a letterbox, a padding, a cover crop — the artwork comes back as PNG and canvas.ts composites it, because Bun.Image resamples but has no compositor and the PWA maskable safe zone is a composite. png-pixels.ts is the raw-pixel seam that hop needs, 8-bit RGBA only; anything else is X_IMAGE_UNSUPPORTED naming transformImageBytes.

Adding a format is an entry in DECODABLE_FORMATS / ENCODABLE_FORMATS and a branch in withFormat — never a second dispatch. An unencodable format is refused from the spec alone, before the source is decoded, so a request nothing can write never expands 64 megapixels first.

Bun.Image rejects with ERR_IMAGE_* on error.code. imageFromBunError is the ONE place that is read, mapping it onto X_IMAGE_UNSUPPORTED / X_IMAGE_TOO_LARGE / X_IMAGE_DECODE_FAILED; no caller branches on a Bun code.

Two files in image/ are past the 200-line target and neither splits without inventing a seam: probe.ts is one algorithm per format over header bytes, and image-fixture.ts is data. The 500-line hard ceiling applies to both. Everything else in image/ is under the target — deleting the hand-rolled JPEG and PNG codecs is what put it there.

image/image-fixture.ts is byte-exact output from Pillow and ffmpeg on purpose: a codec that only round trips against itself proves nothing. Never regenerate a fixture with our own encoder.