@ultimat3/core 1.2.0 → 3.0.0

package/src/secrets.ts

@@ -0,0 +1,292 @@
+// Single responsibility: the encrypted-secrets envelope. Seal a flat map of env values under a
+// 32-byte master key and open one back, AES-256-GCM through WebCrypto only — a fresh 12-byte IV per
+// seal, the 128-bit tag verified on open, and the envelope's own header bound in as additional
+// authenticated data so a downgraded `alg` or a swapped key id fails the tag instead of decrypting.
+
+import {
+  SecretsFileInvalidError,
+  SecretsKeyInvalidError,
+  SecretsKeyMismatchError,
+  SecretsPlaintextInvalidError,
+  SecretsTamperedError,
+} from './secrets-errors';
+
+export const SECRETS_VERSION = 1;
+export const SECRETS_ALG = 'AES-256-GCM';
+export const SECRETS_KEY_BYTES = 32;
+export const SECRETS_KEY_HEX_LENGTH = SECRETS_KEY_BYTES * 2;
+/** GCM's standard nonce. 96 bits is the size the construction is defined for; never reused. */
+export const SECRETS_IV_BYTES = 12;
+export const SECRETS_TAG_BYTES = 16;
+/** Truncated to 64 bits: enough to name a key, far too little to attack the 256-bit key behind it. */
+export const SECRETS_KEY_ID_LENGTH = 16;
+
+/** A secret's name is the env var it becomes — there is no second namespace. */
+export const SECRET_NAME = /^[A-Z][A-Z0-9_]*$/;
+
+const HEX_KEY = /^[0-9a-f]+$/;
+const KEY_ID = /^[0-9a-f]{16}$/;
+const BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+
+/** Decrypted values: env var name to value. Flat on purpose — see `installSecrets`. */
+export type SecretValues = Readonly<Record<string, string>>;
+
+/** The committed file, header first so `git diff` shows a rotation as a one-line `kid` change. */
+export interface SecretsEnvelope {
+  readonly v: number;
+  readonly alg: string;
+  /** Non-secret fingerprint of the master key this was sealed with. */
+  readonly kid: string;
+  readonly iv: string;
+  readonly ct: string;
+}
+
+/** Where each half came from, so an error names the file the reader has to act on. */
+export interface SecretsLocation {
+  /** The envelope's path, or the name of whatever produced it. */
+  readonly file: string;
+  /** The master key's origin — an env var name, or the key file's path. */
+  readonly key: string;
+}
+
+const encoder = new TextEncoder();
+
+function encodeHex(bytes: Uint8Array<ArrayBuffer>): string {
+  let out = '';
+  for (const byte of bytes) out += byte.toString(16).padStart(2, '0');
+  return out;
+}
+
+function decodeHex(hex: string): Uint8Array<ArrayBuffer> {
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < bytes.length; i += 1)
+    bytes[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  return bytes;
+}
+
+// `btoa`/`atob` rather than node:buffer — both are standard globals, and a chunk loop avoids the
+// stack blow-up `String.fromCharCode(...bytes)` hits on a spread of any size.
+function encodeBase64(bytes: Uint8Array<ArrayBuffer>): string {
+  let binary = '';
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+
+function decodeBase64(text: string): Uint8Array<ArrayBuffer> {
+  const binary = atob(text);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+
+/** A fresh master key: 32 CSPRNG bytes, hex. The only thing that must never reach the repo. */
+export function generateMasterKey(): string {
+  return encodeHex(crypto.getRandomValues(new Uint8Array(SECRETS_KEY_BYTES)));
+}
+
+/** 64 lowercase hex characters, or `X_SECRETS_KEY_INVALID`. Whitespace is trimmed, never repaired. */
+export function parseMasterKey(raw: string, at: string): Uint8Array<ArrayBuffer> {
+  const hex = raw.trim();
+  if (hex.length !== SECRETS_KEY_HEX_LENGTH || !HEX_KEY.test(hex)) {
+    throw new SecretsKeyInvalidError({
+      at,
+      found: hex.length,
+      expected: SECRETS_KEY_HEX_LENGTH,
+    });
+  }
+  return decodeHex(hex);
+}
+
+/**
+ * The key's public name. Domain-separated so this digest can never be replayed as a digest of the
+ * key computed for any other purpose, and truncated to 16 hex characters because its only job is
+ * telling two keys apart in a committed file and in an error message.
+ */
+export async function masterKeyId(key: Uint8Array<ArrayBuffer>): Promise<string> {
+  const domain = encoder.encode('ultimate.secrets.kid.v1');
+  const material = new Uint8Array(domain.length + key.length);
+  material.set(domain, 0);
+  material.set(key, domain.length);
+  const digest = await crypto.subtle.digest('SHA-256', material);
+  return encodeHex(new Uint8Array(digest)).slice(0, SECRETS_KEY_ID_LENGTH);
+}
+
+/**
+ * The bytes the tag covers besides the ciphertext. Binding the header means an attacker who can
+ * write the file cannot downgrade `alg`, renumber `v` or claim a different `kid` without the tag
+ * catching it — the fields that decide how the body is read are authenticated with the body.
+ */
+const additionalData = (header: Omit<SecretsEnvelope, 'iv' | 'ct'>): Uint8Array<ArrayBuffer> =>
+  encoder.encode(`ultimate.secrets|v=${header.v}|alg=${header.alg}|kid=${header.kid}`);
+
+const importKey = (key: Uint8Array<ArrayBuffer>): Promise<CryptoKey> =>
+  crypto.subtle.importKey('raw', key, { name: 'AES-GCM' }, false, ['encrypt', 'decrypt']);
+
+/**
+ * The plaintext form: one flat JSON object, keys sorted, two-space indent. Deterministic so
+ * `x secrets edit` can compare the buffer it handed the editor against the one it got back and
+ * skip the write when nothing changed — the ciphertext differs on every seal (the IV is fresh), so
+ * without this every edit session would produce a diff whether or not a value moved.
+ */
+export function serializeSecretValues(values: SecretValues): string {
+  const sorted = Object.fromEntries(Object.entries(values).sort(([a], [b]) => a.localeCompare(b)));
+  return `${JSON.stringify(sorted, null, 2)}\n`;
+}
+
+/** Flat, env-shaped and non-empty, or `X_SECRETS_PLAINTEXT_INVALID`. Runs before every seal. */
+export function assertSecretValues(value: unknown, at: string): SecretValues {
+  const refuse = (reason: string): never => {
+    throw new SecretsPlaintextInvalidError({ at, reason });
+  };
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    return refuse('are not a JSON object');
+  }
+  for (const [key, entry] of Object.entries(value)) {
+    if (!SECRET_NAME.test(key)) {
+      return refuse(`name "${key}", which is not an environment variable name (A-Z, 0-9, _)`);
+    }
+    if (typeof entry !== 'string') return refuse(`give "${key}" a value that is not a string`);
+    if (entry.length === 0) return refuse(`give "${key}" an empty value`);
+  }
+  return Object.freeze({ ...(value as Record<string, string>) });
+}
+
+/** The masked projection — names and lengths only. What `x secrets show` and any log may print. */
+export interface SecretSummary {
+  readonly name: string;
+  readonly length: number;
+}
+
+export function describeSecrets(values: SecretValues): readonly SecretSummary[] {
+  return Object.entries(values)
+    .map(([name, value]) => ({ name, length: value.length }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/** Encrypt `values` under `keyHex` and return the exact bytes the committed file holds. */
+export async function sealSecrets(
+  values: SecretValues,
+  keyHex: string,
+  at: SecretsLocation,
+): Promise<string> {
+  const checked = assertSecretValues(values, at.file);
+  const key = parseMasterKey(keyHex, at.key);
+  const header = { v: SECRETS_VERSION, alg: SECRETS_ALG, kid: await masterKeyId(key) };
+  const iv = crypto.getRandomValues(new Uint8Array(SECRETS_IV_BYTES));
+  const sealed = await crypto.subtle.encrypt(
+    { name: 'AES-GCM', iv, additionalData: additionalData(header), tagLength: 128 },
+    await importKey(key),
+    encoder.encode(serializeSecretValues(checked)),
+  );
+  const envelope: SecretsEnvelope = {
+    ...header,
+    iv: encodeBase64(iv),
+    ct: encodeBase64(new Uint8Array(sealed)),
+  };
+  return `${JSON.stringify(envelope, null, 2)}\n`;
+}
+
+function field(record: Record<string, unknown>, name: string, at: string, bytes?: number): string {
+  const value = record[name];
+  if (typeof value !== 'string' || !BASE64.test(value) || value.length === 0) {
+    throw new SecretsFileInvalidError({ at, reason: `has no base64 "${name}" field` });
+  }
+  const decoded = decodeBase64(value);
+  if (bytes !== undefined && decoded.length !== bytes) {
+    throw new SecretsFileInvalidError({
+      at,
+      reason: `has a ${decoded.length}-byte "${name}"; AES-256-GCM uses ${bytes}`,
+    });
+  }
+  return value;
+}
+
+/**
+ * Read the envelope without needing a key. Every rejection here is `X_SECRETS_FILE_INVALID`: none
+ * of it has reached authentication yet, so calling it tampering would send the reader hunting an
+ * attacker for what is a truncated write or a merge conflict marker.
+ */
+export function parseSecretsEnvelope(text: string, at: string): SecretsEnvelope {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new SecretsFileInvalidError({ at, reason: 'is not JSON' });
+  }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    throw new SecretsFileInvalidError({ at, reason: 'is not a JSON object' });
+  }
+  const record = parsed as Record<string, unknown>;
+  if (record['v'] !== SECRETS_VERSION) {
+    throw new SecretsFileInvalidError({
+      at,
+      reason: `declares envelope version ${JSON.stringify(record['v'])}; this build seals version ${SECRETS_VERSION}`,
+    });
+  }
+  if (record['alg'] !== SECRETS_ALG) {
+    throw new SecretsFileInvalidError({
+      at,
+      reason: `declares algorithm ${JSON.stringify(record['alg'])}; this build seals ${SECRETS_ALG}`,
+    });
+  }
+  const kid = record['kid'];
+  if (typeof kid !== 'string' || !KEY_ID.test(kid)) {
+    throw new SecretsFileInvalidError({ at, reason: 'has no 16-character hex "kid" field' });
+  }
+  const iv = field(record, 'iv', at, SECRETS_IV_BYTES);
+  const ct = field(record, 'ct', at);
+  if (decodeBase64(ct).length <= SECRETS_TAG_BYTES) {
+    throw new SecretsFileInvalidError({
+      at,
+      reason: `has a "ct" too short to hold a ${SECRETS_TAG_BYTES}-byte authentication tag and any content`,
+    });
+  }
+  return { v: SECRETS_VERSION, alg: SECRETS_ALG, kid, iv, ct };
+}
+
+/**
+ * Open a committed envelope. Four distinct refusals, in the order the facts become knowable: the
+ * file is unreadable, the key is malformed, the key is the wrong one (the `kid` says so before any
+ * decryption is attempted), or the tag rejected the body.
+ */
+export async function openSecrets(
+  text: string,
+  keyHex: string,
+  at: SecretsLocation,
+): Promise<SecretValues> {
+  const envelope = parseSecretsEnvelope(text, at.file);
+  const key = parseMasterKey(keyHex, at.key);
+  const kid = await masterKeyId(key);
+  if (kid !== envelope.kid) {
+    throw new SecretsKeyMismatchError({
+      at: at.file,
+      keyAt: at.key,
+      sealedWith: envelope.kid,
+      found: kid,
+    });
+  }
+  let plaintext: ArrayBuffer;
+  try {
+    plaintext = await crypto.subtle.decrypt(
+      {
+        name: 'AES-GCM',
+        iv: decodeBase64(envelope.iv),
+        additionalData: additionalData(envelope),
+        tagLength: 128,
+      },
+      await importKey(key),
+      decodeBase64(envelope.ct),
+    );
+  } catch {
+    // Deliberately no `sourceError`: WebCrypto's OperationError says nothing this code does not,
+    // and an error that wraps a crypto exception is one more object a log could try to serialize.
+    throw new SecretsTamperedError({ at: at.file });
+  }
+  let decoded: unknown;
+  try {
+    decoded = JSON.parse(new TextDecoder().decode(plaintext));
+  } catch {
+    throw new SecretsPlaintextInvalidError({ at: at.file, reason: 'are not JSON' });
+  }
+  return assertSecretValues(decoded, at.file);
+}

package/src/telemetry.ts

@@ -5,8 +5,10 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { type Clock, systemClock } from './clock';
 import { tryUseContext } from './context';
+import { renderThrowable } from './error-render';
 import { isUltimateError } from './errors';
-import { spanId as newSpanId, traceId as newTraceId } from './ids';
+import { isSpanId, isTraceId, spanId as newSpanId, traceId as newTraceId } from './ids';
+import { defaultSampler, resetDefaultSampler, type Sampler } from './sampler';
 
 export type SpanKind = 'internal' | 'server' | 'client' | 'producer' | 'consumer';
 
@@ -87,6 +89,8 @@ export interface TelemetryOptions {
   readonly serviceName?: string | undefined;
   readonly serviceVersion?: string | undefined;
   readonly enabled?: boolean | undefined;
+  /** Defaults to `defaultSampler()`: honour the parent, else the ratio the env asks for. */
+  readonly sampler?: Sampler | undefined;
 }
 
 export const noopExporter: SpanExporter = Object.freeze({
@@ -100,7 +104,7 @@ export interface MemoryExporter extends SpanExporter {
   reset(): void;
 }
 
-/** For tests and for `x trace --json`. */
+/** For tests, and for reading back what a run traced with no collector on the box. */
 export function memoryExporter(): MemoryExporter {
   const spans: ReadableSpan[] = [];
   return {
@@ -119,12 +123,14 @@ const activeSpan = new AsyncLocalStorage<Span>();
 let exporter: SpanExporter = noopExporter;
 let clock: Clock = systemClock;
 let enabled = true;
+let sampler: Sampler | undefined;
 let resource: SpanResource = Object.freeze({ serviceName: 'ultimate', serviceVersion: '0.0.1' });
 
 export function configureTelemetry(options: TelemetryOptions): void {
   if (options.exporter !== undefined) exporter = options.exporter;
   if (options.clock !== undefined) clock = options.clock;
   if (options.enabled !== undefined) enabled = options.enabled;
+  if (options.sampler !== undefined) sampler = options.sampler;
   if (options.serviceName !== undefined || options.serviceVersion !== undefined) {
     resource = Object.freeze({
       serviceName: options.serviceName ?? resource.serviceName,
@@ -137,6 +143,13 @@ export function resetTelemetry(): void {
   exporter = noopExporter;
   clock = systemClock;
   enabled = true;
+  sampler = undefined;
+  resetDefaultSampler();
+}
+
+/** The sampler in force: whatever `configureTelemetry` was given, else the env's. */
+export function currentSampler(): Sampler {
+  return sampler ?? defaultSampler();
 }
 
 /**
@@ -162,12 +175,16 @@ export function currentSpanContext(): SpanContext | undefined {
 
 export function startSpan(name: string, options?: StartSpanOptions): Span {
   const parent = options?.parent ?? currentSpanContext();
+  const attributes: Record<string, AttributeValue> = { ...(options?.attributes ?? {}) };
+  // The bit is decided ONCE, here, and every child of this span inherits it through `parent` —
+  // so one trace is sampled or not sampled as a whole. Before this, `traceFlags` was hardcoded to
+  // 1 for a root and `end()` exported regardless, which made the bit a value the framework
+  // forwarded and nobody obeyed.
   const context: SpanContext = {
     traceId: parent?.traceId ?? newTraceId(),
     spanId: newSpanId(),
-    traceFlags: parent?.traceFlags ?? 1,
+    traceFlags: currentSampler().shouldSample(name, parent, attributes) ? 1 : 0,
   };
-  const attributes: Record<string, AttributeValue> = { ...(options?.attributes ?? {}) };
   const events: SpanEvent[] = [];
   const startedAt = clock.now().getTime();
   const startedMono = clock.monotonic();
@@ -198,7 +215,12 @@ export function startSpan(name: string, options?: StartSpanOptions): Span {
     },
     recordError(error) {
       const code = isUltimateError(error) ? error.code : 'X_INTERNAL';
-      const message = error instanceof Error ? error.message : String(error);
+      // `renderThrowable`, never `error instanceof Error ? error.message : String(error)`: both
+      // halves are property reads on a value the framework did not build, and this runs inside
+      // `withSpan`'s catch — around `cache.invalidate`, `db.<verb>` and every HTTP and job span.
+      // A throw here substitutes the tracer's own TypeError for the caller's real failure and
+      // leaves the span it was annotating unended.
+      const message = renderThrowable(error);
       events.push({
         name: 'exception',
         at: clock.now().getTime(),
@@ -215,6 +237,10 @@ export function startSpan(name: string, options?: StartSpanOptions): Span {
       if (ended) return;
       ended = true;
       if (!enabled) return;
+      // The whole point of propagating a sampling bit is that somebody obeys it. A span still
+      // exists, still parents its children and still carries the decision onward in
+      // `traceparent`; it is simply not exported.
+      if ((context.traceFlags & 1) === 0) return;
       const endedAt = clock.now().getTime();
       const parentSpanId = parent === undefined || parent.spanId === '' ? undefined : parent.spanId;
       exporter.export({
@@ -272,8 +298,13 @@ export function withSpanContext<T>(context: SpanContext, name: string, fn: (span
 
 const TRACEPARENT_RE = /^00-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
 
+/**
+ * Round-trips with `traceId()` / `spanId()` from `ids.ts` and with nothing else. A context whose
+ * `traceId` came from `uuid()` renders a 36-character dashed header here that `parseTraceparent`
+ * — and every OTLP collector — rejects, so mint the pair with those two generators.
+ */
 export function traceparent(context: SpanContext): string {
-  const flags = context.traceFlags.toString(16).padStart(2, '0');
+  const flags = (context.traceFlags & 0xff).toString(16).padStart(2, '0');
   return `00-${context.traceId}-${context.spanId}-${flags}`;
 }
 
@@ -281,11 +312,12 @@ export function parseTraceparent(header: string | null | undefined): SpanContext
   if (header === null || header === undefined) return undefined;
   const match = TRACEPARENT_RE.exec(header.trim());
   if (match === null) return undefined;
-  return {
-    traceId: match[1] as string,
-    spanId: match[2] as string,
-    traceFlags: Number.parseInt(match[3] as string, 16),
-  };
+  const traceId = match[1] as string;
+  const spanId = match[2] as string;
+  // `ids.ts` owns what a valid id is, so the all-zero rejection the spec requires lives in one
+  // place instead of being a second regex here that drifts from the generator's.
+  if (!isTraceId(traceId) || !isSpanId(spanId)) return undefined;
+  return { traceId, spanId, traceFlags: Number.parseInt(match[3] as string, 16) };
 }
 
 function isPromiseLike(value: unknown): value is PromiseLike<unknown> {

package/src/timing-safe-equal.ts

@@ -0,0 +1,18 @@
+// Single responsibility: a string comparison whose duration does not depend on where two secrets
+// first differ. `@ultimat3/auth` and `@ultimat3/storage` both compared a signature or a hashed
+// token this way and, being tier 1+ packages that both sit below `@ultimat3/core`, neither is the
+// other's dependency — so the one copy lives here, at the tier both can reach.
+
+/**
+ * Length is compared first and non-constant-time on purpose: every secret this compares is a
+ * fixed-width hash, token or signature, so the length carries no information, and the XOR
+ * accumulator below is what has to be branch-free.
+ */
+export function timingSafeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let index = 0; index < a.length; index += 1) {
+    diff |= a.charCodeAt(index) ^ b.charCodeAt(index);
+  }
+  return diff === 0;
+}

package/src/type-pins.ts

@@ -0,0 +1,93 @@
+// Compile-time pins for the actor-facts seam and the config surface. Source, not a `.test.ts`,
+// on purpose:
+// `tsconfig.json` excludes `src/**/*.test.ts`, so `tsc -b` never reads a test file and a
+// type-level assertion written there can never fail. This module emits nothing and exports
+// nothing anybody imports — a regression is a build error, the only enforcement that counts.
+
+import type { Actor, ActorFactMap, FactKeysOf, FactMapOf } from './actor';
+import type { AppConfigInput, DatabaseConfig } from './config';
+
+/** Fails to compile when `T` is anything but `true`. The whole mechanism. */
+type Assert<T extends true> = T;
+
+interface Viewer {
+  readonly friendIds: ReadonlySet<string>;
+}
+
+/**
+ * A stand-in for what an app augments `ActorFacts` with. Declared locally rather than by
+ * augmenting the real interface: augmenting it HERE would declare `viewer` for every app that
+ * imports the framework, and a pin that changes the product it pins is not a pin.
+ */
+interface SampleFacts {
+  readonly viewer: Viewer;
+}
+
+type SampleMap = FactMapOf<SampleFacts>;
+
+/** A declared fact reads back as its own type — never `unknown`, never a bag. */
+type _FactIsTyped = Assert<[NonNullable<SampleMap['viewer']>] extends [Viewer] ? true : false>;
+
+type _FactIsNotUnknown = Assert<[unknown] extends [SampleMap['viewer']] ? false : true>;
+
+/**
+ * The denial rule, as a type. Every fact is independently absent because nothing can prove one
+ * was resolved — a job runner, a test and an MCP token exchange all mint actors too. A predicate
+ * therefore has to branch on `undefined`, so an absent fact cannot silently read as a satisfied
+ * one.
+ */
+type _AbsentFactIsRepresentable = Assert<undefined extends SampleMap['viewer'] ? true : false>;
+
+/** A typo is a build error rather than a fact that is forever absent. */
+type _UnknownFactIsNotAKey = Assert<'viewr' extends keyof SampleMap ? false : true>;
+
+/** The phantom that keeps the empty interface from being `{}` is never itself a fact. */
+type _PhantomIsNotAFactKey = Assert<'__ultimate' extends FactKeysOf<SampleFacts> ? false : true>;
+
+/** An actor that resolved nothing is still an actor: every key is optional, always. */
+type _NoFactsIsALegalFactMap = Assert<Record<string, never> extends SampleMap ? true : false>;
+
+type _ActorFactMapAcceptsNothing = Assert<
+  Record<string, never> extends ActorFactMap ? true : false
+>;
+
+/**
+ * The seam is additive: an actor literal written before it existed still is one. `facts` is
+ * optional for that reason and not only for the denial rule — a required member would have been
+ * a breaking change to a tier-0 type every package depends on.
+ */
+type _ActorWithoutFactsIsStillAnActor = Assert<
+  [
+    {
+      readonly kind: 'user';
+      readonly id: string;
+      readonly roles: readonly string[];
+      readonly scopes: readonly string[];
+    },
+  ] extends [Actor]
+    ? true
+    : false
+>;
+
+/**
+ * The three `config.database` fields deleted 2026-08 must stay deleted. Each produced neither a
+ * build error nor a runtime effect, which is the worst state a config field can be in: an SRE set
+ * `poolSize: 3`, redeployed, and nothing changed. Re-adding one silently restores that, so the
+ * pin is here rather than in a `.test.ts` — a `@ts-expect-error` in an excluded file asserts
+ * nothing.
+ *
+ * `DATABASE_POOL_MAX` is the pool knob that works, `DATABASE_URL` is read as a literal by
+ * `@ultimat3/db`'s `client.ts`, and nothing emits `SET search_path`.
+ */
+type DeadDatabaseField = 'urlEnv' | 'poolSize' | 'schema';
+
+type _DatabaseConfigCarriesNoDeadField = Assert<
+  Extract<keyof DatabaseConfig, DeadDatabaseField> extends never ? true : false
+>;
+
+/** And the input side with it — `Input<DatabaseConfig>` is what an `app.config.ts` writes. */
+type _DatabaseInputCarriesNoDeadField = Assert<
+  Extract<keyof NonNullable<AppConfigInput['database']>, DeadDatabaseField> extends never
+    ? true
+    : false
+>;

package/src/version.ts

@@ -3,11 +3,12 @@
 // manifest is `private` and carries no `version`, and after `npm install` a walk above the package
 // lands in `node_modules/` where there is no manifest at all. Both mistakes fail silently.
 
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 // Bun has no path-join primitive; `import.meta.dir` is the module's own directory in both the
 // checked-out `src/` layout and the published `dist/` one, each exactly one level below the
 // package root.
 import { resolve } from 'node:path';
+import { renderCauseValue } from './error-render';
 import { UltimateError } from './errors';
 
 const SEMVER = /^\d+\.\d+\.\d+(?:[-+][\w.-]+)*$/;
@@ -15,10 +16,22 @@ const SEMVER = /^\d+\.\d+\.\d+(?:[-+][\w.-]+)*$/;
 /** `@ultimat3/core`'s own manifest — the only file that can answer what version shipped. */
 export const VERSION_MANIFEST = resolve(import.meta.dir, '..', 'package.json');
 
+/**
+ * The bundler define that carries the version into a build with no manifest to read.
+ * `x build --target binary` passes it (`binaryArgs` in `@ultimat3/cli`); the name is declared here
+ * so the flag that writes it and the read below cannot drift.
+ */
+export const VERSION_DEFINE = 'ULTIMATE_FRAMEWORK_VERSION';
+
+// Replaced with a string literal by `bun build --define ULTIMATE_FRAMEWORK_VERSION='"1.2.3"'`, and
+// declared by nothing at runtime — which is why the read is `typeof`-guarded. An unbundled process
+// must see `undefined` here, not a `ReferenceError`.
+declare const ULTIMATE_FRAMEWORK_VERSION: string | undefined;
+
 /**
  * A package with no readable version is a broken publish, not a runtime condition to degrade
  * through: an `undefined` version poisons the MCP handshake and every dependency a scaffold pins,
- * and does it quietly. Fail at import, where the fix is a release-script change.
+ * and does it quietly. Fail where the fix is a release-script change.
  */
 export function readPackageVersion(manifestPath: string): string {
   const raw: unknown = JSON.parse(readFileSync(manifestPath, 'utf-8'));
@@ -27,11 +40,47 @@ export function readPackageVersion(manifestPath: string): string {
   if (typeof version !== 'string' || !SEMVER.test(version)) {
     throw new UltimateError({
       code: 'X_INVARIANT',
-      cause: `${manifestPath} has no valid semver "version" field (found ${JSON.stringify(version)})`,
+      cause: `${manifestPath} has no valid semver "version" field (found ${renderCauseValue(version)})`,
       fix: `set a semver "version" in ${manifestPath}, then re-run: bun run verify`,
     });
   }
   return version;
 }
 
-export const FRAMEWORK_VERSION: string = readPackageVersion(VERSION_MANIFEST);
+/**
+ * Manifest first, build define second, throw last.
+ *
+ * A single-file executable carries no `package.json`, so a *missing* manifest is the one absence
+ * that is not a broken publish — it falls through to the define. A manifest that exists and
+ * declares no semver still throws, because that is the broken publish `readPackageVersion` was
+ * written for, and a define must not paper over it. Pure and exported so the compiled-binary case
+ * is a unit test rather than a `bun build --compile` nobody runs.
+ */
+export function resolveVersion(manifestPath: string, defined: string | undefined): string {
+  if (existsSync(manifestPath)) return readPackageVersion(manifestPath);
+  if (defined !== undefined && SEMVER.test(defined)) return defined;
+  throw new UltimateError({
+    code: 'X_INVARIANT',
+    cause: `no manifest at ${manifestPath} and no valid ${VERSION_DEFINE} define (found ${JSON.stringify(defined)}) — only the builder that passes the define produces a bootable binary`,
+    fix: `x build --target binary`,
+  });
+}
+
+let resolved: string | undefined;
+
+/**
+ * The framework's version, resolved on first call and cached for every call after.
+ *
+ * Lazy is the whole point. As a module-scope constant the read ran before `main` in every process
+ * that imported core, so `x build --target binary` produced an artifact that threw at import
+ * before any role started — the artifact compiled and could never boot.
+ */
+export function frameworkVersion(): string {
+  if (resolved === undefined) {
+    resolved = resolveVersion(
+      VERSION_MANIFEST,
+      typeof ULTIMATE_FRAMEWORK_VERSION === 'string' ? ULTIMATE_FRAMEWORK_VERSION : undefined,
+    );
+  }
+  return resolved;
+}