@ultimat3/core 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 developerz.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,171 @@
+# 🧱 @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` |
+| code → `{ title, docs }` registry, `registerErrorCodes()` | `error-codes.ts` |
+| `Result<T, E>` for boundaries where throwing is wrong | `result.ts` |
+| request context on `AsyncLocalStorage` | `context.ts` |
+| `Actor` (`user \| service \| agent \| anonymous`) | `actor.ts` |
+| typed env validated at boot | `env.ts` |
+| `defineConfig()` for `app.config.ts` | `config.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 | `logger.ts` |
+| OTel-shaped spans, always on, no-op by default | `telemetry.ts` |
+| graceful drain, `/healthz`, `/readyz` | `lifecycle.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 | `image/` |
+| `assertNever`, `invariant` | `assert.ts` |
+
+## Errors are instructions
+
+```ts
+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"',
+});
+```
+
+```text
+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, meta, stack }`. The title comes from the registry, so
+the terminal, the browser overlay and `--json` cannot drift.
+
+| 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.
+
+## Context
+
+```ts
+const ctx = createContext({ 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. `createContext` 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 `createContext` 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** `createContext` / `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.
+
+## Env fails once, completely
+
+```ts
+export const env = defineEnv({
+  DATABASE_URL: { type: 'url', secret: true },
+  PORT:         { type: 'port', default: 3000 },
+  STAGE:        { type: 'enum', values: ['dev', 'staging', 'prod'] },
+  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.
+
+## Time, ids, telemetry, drain
+
+- Never call `Date.now()`. Take a `Clock`; tests pass `frozenClock('2026-07-26T10:00:00Z')`.
+- `uuid()` 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()` — Sentry, Honeycomb
+  and OTLP all plug in as a `SpanExporter`.
+- `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.
+- 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.
+
+## One cursor, everywhere
+
+```ts
+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 | `ULTIMATE_CURSOR_SECRET`, or `configureCursorSigning()` at boot. Rotating it invalidates every open cursor |
+| Signed, not encrypted | the client already has these rows; what it must not do is *invent* a position |
+| `usesDevCursorSecret()` | true while the shipped dev key is in use |
+
+## One image pipeline, everywhere
+
+```ts
+probeImage(bytes);                                     // { format, width, height, mimeType }
+transformImageBytes(bytes, { width: 640, format: 'jpeg', quality: 80 });
+blurDataUrl(bytes);                                    // 16px 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. Zero dependencies: no `sharp`, no native module.
+
+| | |
+|---|---|
+| Decode / encode | PNG and JPEG. `canDecode()` / `canEncode()` publish the real list |
+| Probe only | WebP, AVIF, GIF, 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), checked from the header **before** a byte is allocated |
+| Determinism | same bytes + same spec → same output bytes. No clock, no randomness |
+
+Adding a format is a decoder plus an entry in `DECODABLE_FORMATS` / `ENCODABLE_FORMATS` — 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.
+
+`image/` is the one place in core allowed past the 200-line target, and only there: a JPEG or PNG
+codec is a single algorithm that does not split into smaller responsibilities without inventing
+seams. Nothing else in it qualifies, which is why the segment headers (`jpeg-headers.ts`), the SVG
+text parse (`probe-svg.ts`) and the colour grammar (`color.ts`) are their own files. The 500-line
+hard ceiling applies to all of them.
+
+`image/fixtures.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.

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@ultimat3/core",
+  "version": "1.0.0",
+  "description": "Ultimate's foundation: errors, context, env, config, clock, ids, logging, telemetry, lifecycle",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/developerz-ai/ultimate.git",
+    "directory": "packages/core"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "bun test"
+  },
+  "dependencies": {}
+}

package/src/actor.ts

@@ -0,0 +1,81 @@
+// Single responsibility: who is making the request. `agent` is a first-class kind because
+// every action is also an MCP tool, and MCP callers go through the same authz as humans.
+
+/** `agent` = an MCP/LLM caller acting on behalf of a user or a service. */
+export type ActorKind = 'user' | 'service' | 'agent' | 'anonymous';
+
+export const ACTOR_KINDS = ['user', 'service', 'agent', 'anonymous'] as const;
+
+export interface Actor {
+  readonly kind: ActorKind;
+  readonly id: string;
+  readonly orgId?: string | undefined;
+  /** Application roles (`admin`, `editor`). Unrelated to the runtime `Role`. */
+  readonly roles: readonly string[];
+  /** Capability strings a policy can require (`post:publish`). */
+  readonly scopes: readonly string[];
+}
+
+export interface ActorInit {
+  readonly id: string;
+  readonly orgId?: string | undefined;
+  readonly roles?: readonly string[] | undefined;
+  readonly scopes?: readonly string[] | undefined;
+}
+
+const ANONYMOUS: Actor = Object.freeze({
+  kind: 'anonymous',
+  id: 'anonymous',
+  roles: Object.freeze([]),
+  scopes: Object.freeze([]),
+});
+
+function build(kind: ActorKind, init: ActorInit): Actor {
+  return Object.freeze({
+    kind,
+    id: init.id,
+    orgId: init.orgId,
+    roles: Object.freeze([...(init.roles ?? [])]),
+    scopes: Object.freeze([...(init.scopes ?? [])]),
+  });
+}
+
+export function userActor(init: ActorInit): Actor {
+  return build('user', init);
+}
+
+export function serviceActor(init: ActorInit): Actor {
+  return build('service', init);
+}
+
+/** An MCP or LLM caller. `orgId` and `scopes` are mandatory in practice — authz is identical. */
+export function agentActor(init: ActorInit): Actor {
+  return build('agent', init);
+}
+
+export function anonymousActor(): Actor {
+  return ANONYMOUS;
+}
+
+export function isActorKind(value: unknown): value is ActorKind {
+  return typeof value === 'string' && (ACTOR_KINDS as readonly string[]).includes(value);
+}
+
+export function isAnonymous(actor: Actor): boolean {
+  return actor.kind === 'anonymous';
+}
+
+export function hasRole(actor: Actor, role: string): boolean {
+  return actor.roles.includes(role);
+}
+
+export function hasScope(actor: Actor, scope: string): boolean {
+  return actor.scopes.includes(scope);
+}
+
+/** Log/trace-safe identity — no email, no token, stable across surfaces. */
+export function actorLabel(actor: Actor): string {
+  return actor.orgId === undefined
+    ? `${actor.kind}:${actor.id}`
+    : `${actor.kind}:${actor.id}@${actor.orgId}`;
+}

package/src/assert.ts

@@ -0,0 +1,44 @@
+// Single responsibility: compile-time-backed runtime assertions. Exhaustive switches and
+// invariants both fail with a real error code, never a bare Error.
+
+import { UltimateError } from './errors';
+
+export interface InvariantOptions {
+  readonly docs?: string | undefined;
+  readonly meta?: Readonly<Record<string, unknown>> | undefined;
+}
+
+/**
+ * Put in the `default` branch of a switch over a union. Adding a union member becomes a
+ * type error at the call site instead of a silent fallthrough at runtime.
+ */
+export function assertNever(value: never, fix?: string): never {
+  throw new UltimateError({
+    code: 'X_UNREACHABLE',
+    cause: `unhandled variant: ${JSON.stringify(value) ?? String(value)}`,
+    fix: fix ?? 'add a case for the variant named in cause',
+    meta: { value },
+  });
+}
+
+export function invariant(
+  condition: unknown,
+  code: string,
+  cause: string,
+  fix: string,
+  options?: InvariantOptions,
+): asserts condition {
+  if (condition) return;
+  throw new UltimateError({
+    code,
+    cause,
+    fix,
+    docs: options?.docs,
+    meta: options?.meta,
+  });
+}
+
+/** `invariant` with the generic code, for checks that have no dedicated code yet. */
+export function assert(condition: unknown, cause: string, fix: string): asserts condition {
+  invariant(condition, 'X_INVARIANT', cause, fix);
+}

package/src/clock.ts

@@ -0,0 +1,51 @@
+// Single responsibility: the only source of "now" in the framework. Everything time-related
+// takes a `Clock` so tests freeze time instead of sleeping. Nothing else may call `Date.now()`.
+
+export interface Clock {
+  /** Wall-clock instant. Always UTC-backed; format at the edge with an explicit IANA tz. */
+  now(): Date;
+  /** Monotonic milliseconds — safe for durations, unaffected by wall-clock jumps. */
+  monotonic(): number;
+}
+
+export interface FrozenClock extends Clock {
+  /** Move wall-clock and monotonic time forward by `ms`. */
+  advance(ms: number): void;
+  set(at: Date | number | string): void;
+}
+
+export const systemClock: Clock = Object.freeze({
+  now(): Date {
+    return new Date();
+  },
+  monotonic(): number {
+    return performance.now();
+  },
+});
+
+function toEpochMs(at: Date | number | string): number {
+  if (at instanceof Date) return at.getTime();
+  if (typeof at === 'number') return at;
+  return new Date(at).getTime();
+}
+
+/** A clock stuck at `at` until `advance()` is called. Monotonic starts at 0. */
+export function frozenClock(at: Date | number | string = 0): FrozenClock {
+  let epochMs = toEpochMs(at);
+  let mono = 0;
+  return {
+    now(): Date {
+      return new Date(epochMs);
+    },
+    monotonic(): number {
+      return mono;
+    },
+    advance(ms: number): void {
+      epochMs += ms;
+      mono += ms;
+    },
+    set(next: Date | number | string): void {
+      epochMs = toEpochMs(next);
+    },
+  };
+}

package/src/config.ts

@@ -0,0 +1,265 @@
+// Single responsibility: `app.config.ts` — the one config file. Deeply optional with real
+// defaults, validated eagerly, and composable so a big app can split it across `config/*.ts`
+// without inventing a second config mechanism.
+
+import { ConfigInvalidError } from './errors';
+import { ROLES, type Role } from './roles';
+
+export type ThemeMode = 'light' | 'dark' | 'system';
+export type OfflineStrategy = 'precache' | 'runtime' | 'network-only';
+export type CacheTier = 'memo' | 'lru' | 'shared' | 'isr' | 'cdn';
+export type JobsDriver = 'postgres' | 'redis' | 'nats';
+export type RealtimeTier = 'channels' | 'live-queries' | 'local-first';
+export type RealtimeTransport = 'memory' | 'nats' | 'redis';
+
+export interface ThemeConfig {
+  readonly defaultMode: ThemeMode;
+  /** Semantic design tokens. Raw hex is a lint error in components, never here. */
+  readonly tokens: Readonly<Record<string, string>>;
+}
+
+export interface PwaConfig {
+  readonly enabled: boolean;
+  readonly offline: OfflineStrategy;
+  readonly installPrompt: boolean;
+  readonly backgroundSync: boolean;
+  readonly push: boolean;
+}
+
+export interface DatabaseConfig {
+  readonly driver: 'postgres';
+  /** Env key holding the connection string — never the string itself. */
+  readonly urlEnv: string;
+  readonly poolSize: number;
+  readonly ssl: boolean;
+  readonly schema: string;
+}
+
+export interface CacheConfig {
+  readonly driver: 'memory' | 'redis';
+  readonly urlEnv: string | undefined;
+  readonly defaultTtlMs: number;
+  readonly tiers: readonly CacheTier[];
+}
+
+export interface JobsConfig {
+  readonly driver: JobsDriver;
+  readonly queues: readonly string[];
+  readonly concurrency: number;
+  readonly maxAttempts: number;
+  readonly backoff: 'exponential' | 'fixed';
+  readonly visibilityTimeoutMs: number;
+}
+
+export interface RealtimeConfig {
+  readonly enabled: boolean;
+  readonly tier: RealtimeTier;
+  readonly transport: RealtimeTransport;
+  readonly urlEnv: string | undefined;
+  readonly heartbeatMs: number;
+}
+
+export interface McpConfig {
+  readonly expose: boolean;
+  readonly path: string;
+}
+
+export interface AiConfig {
+  readonly mcp: McpConfig;
+  /** Env key for the model id, so no model string is baked into the image. */
+  readonly modelEnv: string | undefined;
+}
+
+export interface AppConfig {
+  readonly name: string;
+  readonly locales: readonly string[];
+  readonly defaultLocale: string;
+  readonly defaultTimeZone: string;
+  readonly defaultCurrency: string;
+  readonly theme: ThemeConfig;
+  readonly pwa: PwaConfig;
+  readonly roles: readonly Role[];
+  readonly database: DatabaseConfig;
+  readonly cache: CacheConfig;
+  readonly jobs: JobsConfig;
+  readonly realtime: RealtimeConfig;
+  readonly ai: AiConfig;
+}
+
+type Input<T> = { readonly [K in keyof T]?: T[K] | undefined };
+
+export interface AiConfigInput extends Input<Omit<AiConfig, 'mcp'>> {
+  readonly mcp?: Input<McpConfig> | undefined;
+}
+
+export interface AppConfigInput {
+  readonly name: string;
+  readonly locales?: readonly string[] | undefined;
+  readonly defaultLocale?: string | undefined;
+  readonly defaultTimeZone?: string | undefined;
+  readonly defaultCurrency?: string | undefined;
+  readonly theme?: Input<ThemeConfig> | undefined;
+  readonly pwa?: Input<PwaConfig> | undefined;
+  readonly roles?: readonly Role[] | undefined;
+  readonly database?: Input<DatabaseConfig> | undefined;
+  readonly cache?: Input<CacheConfig> | undefined;
+  readonly jobs?: Input<JobsConfig> | undefined;
+  readonly realtime?: Input<RealtimeConfig> | undefined;
+  readonly ai?: AiConfigInput | undefined;
+}
+
+/** An overlay from `config/<concern>.ts`. No `name` — the base owns it. */
+export type AppConfigOverlay = Omit<AppConfigInput, 'name'> & { readonly name?: string };
+
+/**
+ * Apply a partial section over its defaults. Explicit `undefined` never wins — that is what
+ * makes every config field deeply optional without `exactOptionalPropertyTypes` fighting back.
+ */
+function section<T extends object>(base: T, patch: Input<T> | undefined): T {
+  if (patch === undefined) return base;
+  const out: Record<string, unknown> = { ...(base as Record<string, unknown>) };
+  for (const [key, value] of Object.entries(patch)) {
+    if (value !== undefined) out[key] = value;
+  }
+  return out as T;
+}
+
+const NAME_RE = /^[a-z][a-z0-9-]{1,63}$/;
+const CURRENCY_RE = /^[A-Z]{3}$/;
+
+function isTimeZone(value: string): boolean {
+  try {
+    new Intl.DateTimeFormat('en', { timeZone: value });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isLocale(value: string): boolean {
+  try {
+    return Intl.getCanonicalLocales(value).length === 1;
+  } catch {
+    return false;
+  }
+}
+
+function defaults(name: string): Omit<AppConfig, 'name'> {
+  return {
+    locales: ['en'],
+    defaultLocale: 'en',
+    defaultTimeZone: 'UTC',
+    defaultCurrency: 'USD',
+    theme: { defaultMode: 'system', tokens: {} },
+    pwa: {
+      enabled: false,
+      offline: 'network-only',
+      installPrompt: false,
+      backgroundSync: false,
+      push: false,
+    },
+    roles: [...ROLES],
+    database: {
+      driver: 'postgres',
+      urlEnv: 'DATABASE_URL',
+      poolSize: 10,
+      ssl: false,
+      schema: 'public',
+    },
+    cache: { driver: 'memory', urlEnv: undefined, defaultTtlMs: 60_000, tiers: ['memo', 'lru'] },
+    jobs: {
+      driver: 'postgres',
+      queues: [`${name}-default`],
+      concurrency: 8,
+      maxAttempts: 5,
+      backoff: 'exponential',
+      visibilityTimeoutMs: 30_000,
+    },
+    realtime: {
+      enabled: false,
+      tier: 'channels',
+      transport: 'memory',
+      urlEnv: undefined,
+      heartbeatMs: 15_000,
+    },
+    ai: { mcp: { expose: true, path: '/mcp' }, modelEnv: undefined },
+  };
+}
+
+function validate(config: AppConfig): void {
+  const issues: string[] = [];
+
+  if (!NAME_RE.test(config.name)) {
+    issues.push(`name "${config.name}" must match ${String(NAME_RE)}`);
+  }
+  if (config.locales.length === 0) issues.push('locales must list at least one locale');
+  for (const locale of config.locales) {
+    if (!isLocale(locale)) issues.push(`locales contains "${locale}", not a BCP-47 tag`);
+  }
+  if (!config.locales.includes(config.defaultLocale)) {
+    issues.push(`defaultLocale "${config.defaultLocale}" is not in locales`);
+  }
+  if (!isTimeZone(config.defaultTimeZone)) {
+    issues.push(`defaultTimeZone "${config.defaultTimeZone}" is not an IANA time zone`);
+  }
+  if (!CURRENCY_RE.test(config.defaultCurrency)) {
+    issues.push(`defaultCurrency "${config.defaultCurrency}" is not a 3-letter ISO 4217 code`);
+  }
+  if (config.roles.length === 0) issues.push('roles must list at least one runtime role');
+  if (config.database.poolSize < 1) issues.push('database.poolSize must be >= 1');
+  if (config.jobs.concurrency < 1) issues.push('jobs.concurrency must be >= 1');
+  if (config.jobs.queues.length === 0) issues.push('jobs.queues must list at least one queue');
+  if (config.realtime.transport !== 'memory' && config.realtime.urlEnv === undefined) {
+    issues.push(`realtime.transport "${config.realtime.transport}" requires realtime.urlEnv`);
+  }
+  if (config.cache.driver === 'redis' && config.cache.urlEnv === undefined) {
+    issues.push('cache.driver "redis" requires cache.urlEnv');
+  }
+
+  if (issues.length > 0) {
+    throw new ConfigInvalidError({
+      cause: issues.join('; '),
+      fix: 'edit app.config.ts to fix the fields named in cause, then run: x verify',
+      meta: { issues },
+    });
+  }
+}
+
+/**
+ * The single config entry point. Later overlays win, so `config/jobs.ts` can own jobs without
+ * touching `app.config.ts`.
+ */
+export function defineConfig(
+  input: AppConfigInput,
+  ...overlays: readonly AppConfigOverlay[]
+): AppConfig {
+  const base = defaults(input.name);
+  // One `Object.assign` over all overlays rather than a spread per overlay: `reduce` with a
+  // spread copies every key again on each step, and config is merged at boot on every start.
+  // `name` is applied last because it identifies the app — an overlay may not rename it.
+  const merged: AppConfigInput = Object.assign({}, input, ...overlays, {
+    name: input.name,
+  }) as AppConfigInput;
+
+  const config: AppConfig = {
+    name: merged.name,
+    locales: merged.locales ?? base.locales,
+    defaultLocale: merged.defaultLocale ?? base.defaultLocale,
+    defaultTimeZone: merged.defaultTimeZone ?? base.defaultTimeZone,
+    defaultCurrency: merged.defaultCurrency ?? base.defaultCurrency,
+    theme: section(base.theme, merged.theme),
+    pwa: section(base.pwa, merged.pwa),
+    roles: merged.roles ?? base.roles,
+    database: section(base.database, merged.database),
+    cache: section(base.cache, merged.cache),
+    jobs: section(base.jobs, merged.jobs),
+    realtime: section(base.realtime, merged.realtime),
+    ai: {
+      mcp: section(base.ai.mcp, merged.ai?.mcp),
+      modelEnv: merged.ai?.modelEnv ?? base.ai.modelEnv,
+    },
+  };
+
+  validate(config);
+  return Object.freeze(config);
+}