@ultimat3/cli 23.0.0 → 24.0.0

package/CLAUDE.md

@@ -44,8 +44,8 @@ Commands: `bun test packages/cli` (from the repo root — the test preload lives
 |---|---|
 | `verify-checks.ts` / `verify-step.ts` / `verify-run.ts` | the step list, the outcome shape, the run order (`BESIDE_SERIAL_SUITES`) |
 | `verify-floor.ts` | `x.verify.json`: a floor step that ran zero tests is `X_VERIFY_SUITE_VANISHED` |
-| `coverage-floor.ts` / `coverage-lcov.ts` / `coverage-source.ts` / `verify-coverage-run.ts` | an APP's `unit` step holds `coverage` in `x.verify.json` over its whole source tree. The suite runs as fixed slices, one plain `bun test` each — never `--parallel --coverage`, whose merge moves with the core count. `coverage-lcov.ts` is the ONE lcov reader; `scripts/coverage-gate.ts` reads through it. A shard defers to `verify-merge.ts` (`coverageRiders`); `doctor-coverage.ts` lists the excludes |
-| `verify-deadline.ts` / `verify-progress.ts` | a step past its deadline is `X_VERIFY_STEP_TIMEOUT`: its children carry `ULTIMATE_VERIFY_STEP` and are killed by that tag; `--json` streams a line per finished step to stderr. A `fix:` names `ctx.command` — `bun run verify` at the framework root |
+| `coverage-floor.ts` / `coverage-lcov.ts` / `coverage-source.ts` / `verify-coverage-run.ts` | an APP's `unit` step holds `coverage` in `x.verify.json` over its whole source tree. The suite runs as fixed slices, one plain `bun test` each — never `--parallel --coverage`, whose merge moves with the core count. `coverage-lcov.ts` is the ONE lcov reader; `scripts/coverage-gate.ts` reads through it. A shard defers to `verify-merge.ts` (`coverageRiders`), which also holds the shards' `files` to a partition of the corpus they hashed and reads each part step through `verify-part-step.ts`; `doctor-coverage.ts` lists the excludes |
+| `verify-deadline.ts` / `verify-stalled.ts` / `verify-progress.ts` | a step past its deadline is `X_VERIFY_STEP_TIMEOUT`: its children carry `ULTIMATE_VERIFY_STEP` and are killed by that tag; the finding names the test file `bun test` had not finished (`at`, `meta.inFlight`) and its `fix:` runs that file; `--json` streams a line per finished step to stderr. A `fix:` names `ctx.command` — `bun run verify` at the framework root |
 | `load-findings.ts` | module-load failures are reported once, by `manifest`; other steps point there |
 | `boundary-findings.ts` / `app-boundaries.ts` / `boundary-cuts.ts` | surface + layer rules; a finding's `fix:` is the concrete cut |
 | `app-transport.ts` / `browser-transport.ts` / `transport-calls.ts` / `import-closure.ts` / `server-barrels.ts` | `boundaries`, built in: one browser transport. `app-transport.ts` reuses the files `readAppSources` read (no second walk), resolves through the app's tsconfig `paths` and workspace manifests, reads the app's own `packages/*` lazily, and STOPS at `node_modules`. `browser-transport.ts` is the pure rule — `scripts/browser-transport.ts` calls the same function with this repo's seam FILES. Never a `guards/` file: an app must not be able to delete it |
@@ -53,16 +53,16 @@ Commands: `bun test packages/cli` (from the repo root — the test preload lives
 | `templates/scaffold-guards.ts` | `SHIPPED` — the one list of shipped guards: `x new` writes all, `x g guard <name>` writes one, `doctor-guards.ts` lists the ones an app lacks (a listing, never a finding). A new one is a `templates/guard-<name>.ts` + a row + `guard-<name>.test.ts`; `scaffold-guards-style.test.ts` holds embedded scales to `@ultimat3/ui`, the framework's own sheets to the rules, and both tracked apps byte-equal to the templates |
 | `error-contract.ts` / `ts-scan.ts` / `fix-scan.ts` / `fix-imports.ts` / `fix-command.ts` / `fix-path.ts` | the `errors` step: every `fix:` names a runnable command, call or existing file |
 | `workspace-checks.ts` / `workspace-graph.ts` / `tsconfig-references.ts` / `publish-closure.ts` | `package-shape`, `filesize`. A published package's `files` negates `*.test.ts` and `*-fixture.ts`, and no entry point (`exports`, `bin`) may reach a `-fixture.ts` — `X_PACKAGE_SHAPE` names the file to rename |
-| `app-permissions.ts` / `permission-grants.ts` | `policy`: every permission granted or required is declared, and every one required is granted by some role (`X_PERMISSION_UNGRANTED`) |
+| `app-permissions.ts` / `permission-grants.ts` / `app-permissions-borrowed.ts` / `app-permissions-site.ts` | `policy`: every permission granted or required is declared, every one required is granted by some role (`X_PERMISSION_UNGRANTED`), and every one an app rule requires is declared by an app module, not only by a package (`X_PERMISSION_BORROWED`, read off `permissionDeclarationSites()`) |
 | `job-registration.ts` | `manifest`: no job or task under a positional `anonymous-*` name (`X_JOB_UNREGISTERED`) |
 | `unscanned-admin.ts` | `manifest`: a `defineAdmin()` outside the app scan (`apps/*/src/`) is `X_ADMIN_UNSCANNED`, with the `git mv` that mounts it |
 | `verify-role-load.ts` / `verify-role-load-probe.ts` | `manifest`: a child imports the app as a worker does, then the rest module by module; a registration only a document-reaching module makes is `X_ROLE_LOAD_INCOMPLETE` with the module and the import the API index lacks |
 | `async-pages.ts` / `live-routes.ts` / `budgets.ts` | `budgets` riders: an async `Page` with no `load`, a live read no island imports, bytes per route |
 | `app-agents-md.ts` / `app-env.ts` / `app-openapi.ts` / `app-manifest.ts` | `manifest` and `contract-diff` |
-| `schema-drift.ts` / `drift.ts` / `db-destructive.ts` / `db-ungeneratable.ts` | `drift`: snapshot vs declarations, the source hash (core's `canonicalJson`), the header markers |
+| `schema-drift.ts` / `drift.ts` / `drift-replica-identity.ts` / `db-destructive.ts` / `db-ungeneratable.ts` | `drift`: snapshot vs declarations (`REPLICA IDENTITY FULL` a params channel or `subscribes:` needs included), the source hash (core's `canonicalJson`), the header markers |
 | `schema-dump-drift.ts` | `drift`'s fourth rail, the only one that boots a database: committed `packages/db/schema/` vs a scratch replay, and that dump loaded back (`X_SCHEMA_DUMP_DRIFT`) |
 | `i18n-registration.ts` / `i18n-audit.ts` / `admin-catalog-keys.ts` | `i18n`; a mounted admin's keys are `AdminApp.catalogKeys()`, asked of every app catalog — never re-derived here (`X_CATALOG_MISSING_KEYS`) |
-| `error-unthrown.ts` | host check: a registered code nothing throws must say so |
+| `error-unthrown.ts` / `unthrown-codes.ts` | host check: a registered code nothing throws is listed in `UNTHROWN_CODES` (a row's wording waives nothing); a listed code thrown again is `X_ERROR_CODE_UNTHROWN_STALE` |
 
 ### Generators (`x g`, `x new`)
 
@@ -70,6 +70,7 @@ Commands: `bun test packages/cli` (from the repo root — the test preload lives
 |---|---|
 | `cmd-generate.ts` / `generate-files.ts` / `generate-kinds.ts` / `generate-write.ts` | argv → pure file list → writes (conflict-checked, `merge: 'json'` / `'if-absent'`) |
 | `generate-feature.ts` | a `--feature` naming no slice is `X_FEATURE_UNKNOWN`; nothing invents an entity |
+| `generate-shadow.ts` | a name whose type spelling a planned file also uses as a global or local type (`promise`, `row`) is `X_CLI_BAD_FLAG`, decided on the planned files |
 | `generate-grants.ts` | a written `policy.ts` grants `:read` to `member`, `:write` to `admin` in `apps/web/shared/roles.ts`; a written `entity.ts` declares its table's `<table>:read\|write\|delete` there and grants all three to `admin` — what the admin asks for the screen that entity just became |
 | `api-registration.ts` | a written job or task is listed in `apps/web/api/index.ts` |
 | `handle-registration.ts` / `workspace-dep-edit.ts` / `templates/scaffold-db-client.ts` | a written entity joins `const entities = { … }` in `packages/db/src/client.ts` (the typed handle every generated `repo.ts` reads), with the two manifest lines the new imports need; no anchor is `X_DB_HANDLE_UNREGISTERED` carrying the lines. `cmd-generate.ts`'s `nextSteps` prints what the new table owes |
@@ -88,11 +89,16 @@ Commands: `bun test packages/cli` (from the repo root — the test preload lives
 | `cmd-dev.ts` / `dev-route-table.ts` | `x dev`: every role in one process, `/_x`, the watcher |
 | `runtime-bindings.ts` | which service each binding points at (embedded or external); events follow `realtime.transport` / `urlEnv` |
 | `runtime-queue.ts` / `runtime-services.ts` | the db + queue pair; everything else and every ambient accessor |
-| `runtime-jobs.ts` / `runtime-realtime.ts` / `runtime-notify-retention.ts` / `runtime-cache.ts` / `runtime-purge.ts` / `runtime-replica.ts` | `app.config.ts` sections the boot obeys, and what each wires |
+| `framework-schema-apply.ts` / `framework-schema-stamp.ts` | the framework tables: `ROLE=migrate`, `x dev` and every CLI command APPLY them in one transaction behind `MIGRATION_LOCK_KEY` (`pg_advisory_xact_lock`) with a bounded `lock_timeout`, then stamp the build on `x_jobs`' table comment; a serving role on an external database runs no DDL and VERIFIES the stamp (`X_FRAMEWORK_SCHEMA_UNAPPLIED`, a major skew is a warning). A comment, never a table: a new framework table moves every app's schema dump |
+| `runtime-isr.ts` | the ISR controller both boots serve through, ATTACHED to `invalidateTags` and released on stop (`attachedIsr`); `appRoutes` without one builds and attaches its own |
+| `runtime-mfa-warning.ts` / `runtime-idempotency-scope.ts` | boot warnings an operator can act on: unsealed MFA secrets (web role, `x auth seal-mfa`), a per-process idempotency store after the app loaded |
+| `app-config-load.ts` | the ONE reader of an app's `app.config.ts`: `loadAppConfig(root)` — the `config` export through core's `defineConfig`, so validated and default-merged; `undefined` with no file; no `config` object is `X_CONFIG_INVALID`. Every boot fact (`app-auth.ts`, `theme-boot.ts`, `site-config.ts`, `pwa-artifacts.ts`, …) reads a section off it, and `startServices` loads it once. An `import(` of the config module anywhere else is `X_CONFIG_IMPORT_OUTSIDE_LOADER` (`scripts/lib/config-import.ts`) |
+| `runtime-jobs.ts` / `runtime-realtime.ts` / `runtime-notify-retention.ts` / `runtime-cache.ts` / `runtime-purge.ts` / `runtime-replica.ts` | `app.config.ts` sections the boot obeys (`*Of(config)` over the one loaded config), and what each wires |
 | `role-start.ts` / `role-start-types.ts` / `role-realtime.ts` | `--role` selection and start/stop for `web`, `sync`, `worker`, `scheduler`; `realtime.enabled: false` drops `sync` and `replicator` |
 | `role-wake.ts` | the worker's LISTEN session (`@ultimat3/jobs`' `startQueueWake`) — worker role only, only over a client that `canListen` — and `queue_wake_live` |
 | `role-sync.ts` / `role-replicator.ts` / `runtime-live-feed.ts` | the sync node, the change feed |
 | `runtime-render.ts` / `runtime-assets.ts` / `runtime-storage.ts` / `runtime-hooks.ts` / `api-routes.ts` | the HTTP surface: pages, `/icons` + `/media`, `/_storage`, authz, the app's API — plus its bearer mounts (`apiMountRoutes`) and pages' bound `POST`s (`pagePostRoutes`), mounted by BOTH boots |
+| `stored-object-headers.ts` | how `/_storage` and `/media` present a stored object: inline only for raster images, audio and video; every other type (`text/html`, SVG, XML, PDF) is `content-disposition: attachment` with a `sandbox` CSP, which http's security stage keeps beside the app's |
 | `runtime-overrides.ts` | the one field a host hands the framework a driver through — and `routes`, the plain routes for a wire format no primitive speaks (OAuth token endpoint) |
 | `app-openapi.ts` | `openapi.json` (complete when `defineApi({ openapi })` is declared) and each bearer mount's own document; staleness for all of them |
 | `script-csp.ts` / `style-csp.ts` / `style-bundle.ts` / `page-sync.ts` / `worker-bundle.ts` | CSP hashes, the CSS file, the page's sync target and worker |
@@ -102,6 +108,7 @@ Commands: `bun test packages/cli` (from the repo root — the test preload lives
 | `island-bundle.ts` / `island-store.ts` / `island-realtime.ts` / `solid-loader.ts` | islands: one `Bun.build` each, source-addressed; the image build writes a verified store the container loads |
 | `serve-prebuilt.ts` / `serve-prebuilt-paths.ts` | the image's prebuilt store (`node_modules/.cache/ultimate`, never `.x/` — state, tmpfs): every role adopts its compiled stylesheets before importing the app; a boot that built an island or ran Sass logs `X_IMAGE_NOT_PREBUILT` once |
 | `dev-*.ts` | `x dev` only: dashboard sources, traces, the N+1 ledger, the watcher, the reload, the lock, the port |
+| `dev-dashboard-guard.ts` / `loopback-host.ts` | `/_x` answers a loopback `Host` only (`X_DEV_HOST_REFUSED`, 421 — DNS rebinding); the SQL panel runs on a same-origin `POST /_x/db` only, through admin's `readOnlySql`. Checked in the route, never left to the app's `csrf` config |
 
 ### Build and data
 
@@ -118,7 +125,8 @@ Commands: `bun test packages/cli` (from the repo root — the test preload lives
 | File | Job |
 |---|---|
 | `cmd-registries.ts` / `cmd-jobs.ts` / `cmd-tasks.ts` / `cmd-policy.ts` / `cmd-i18n.ts` | project a framework registry; each pairs CLI wiring with a facts module |
-| `cmd-mcp.ts` / `mcp-host.ts` / `mcp-errors.ts` / `mcp-db-target.ts` | `x mcp serve`: 18 tools, two transports |
+| `cmd-auth.ts` / `cmd-auth-spec.ts` / `doctor-auth.ts` | `x auth seal-mfa`: the one-shot that seals plaintext `x_users.mfa_secret` through auth's `sealMfaSecrets` (compare-and-set per row; `{ sealed, alreadySealed, skipped }`), over `startQueue`'s client, `open` injectable. `doctor-auth.ts` is the deploy-time half: unsealed secrets and retired framework tables (`RETIRED_TABLE_FIXES`, a `Map` holding a whole literal per table), asked of an external `DATABASE_URL` only |
+| `cmd-mcp.ts` / `mcp-host.ts` / `mcp-errors.ts` / `mcp-db-target.ts` | `x mcp serve`: 18 tools, two transports; a taken port is `X_PORT_IN_USE`. `mcp-test-run.ts` folds `bun test`'s `N errors` line and exit code into `tests.run` |
 | `cmd-shot*.ts` / `cdp-shot-*.ts` / `browser-launcher*.ts` / `island-*` | `x shot` over raw CDP; `verdict.json` names its own blind spots. Not a gate step |
 | `cmd-pr.ts` / `cmd-ci.ts` | GitHub through `gh`, parsed against a schema. Not gate steps |
 | `error-catalog.ts` | imports every `@ultimat3/*` package so `x errors` answers for any code |

package/README.md

@@ -16,7 +16,7 @@ Commands and the `x verify` step count, `As of 2026-08`:
 | `x g <primitive> <name>` | scaffolds a primitive **with a passing test** | never a TODO stub |
 | `x db gen\|migrate\|reset\|branch\|backfill` | everything DB | `branch` = copy-on-write clone + preview URL; `backfill` dry-runs unless `--write`. `x db studio` is **planned** — it parses, and exits `X_NOT_IMPLEMENTED` naming `/_x`'s db panel |
 | `x mcp serve` | `@ultimat3/mcp`'s 18 dev tools, over stdio or HTTP | one catalog, one scope set, both transports |
-| `x doctor` | environment, ports, drift, PWA prerequisites | every finding carries a fix command |
+| `x doctor` | environment, ports, drift, PWA prerequisites, `APP_URL` | every finding carries a fix command; probes the port `x dev` binds ([which one](../../wiki/CLI-Reference.md#x-doctor)) |
 | `x deploy` | container deploy plan | compose or helm; zero platform primitives |
 | `x manifest` / `x routes` | generated facts | `x.manifest.json`, `openapi.json`, route table |
 | `x actions` / `x queries` / `x entities` | the declaration registries | `list` and `describe <name>`, straight off the registries |
@@ -24,6 +24,7 @@ Commands and the `x verify` step count, `As of 2026-08`:
 | `x jobs ls\|show\|retry\|cancel\|drain` | the queue | depth, dead letters, step traces, `retry --from-step`, `cancel --reason`, `drain --to` |
 | `x test [type]` | one of the six test types, or all | same type rule as the gate; `--filter`, `--sample N` |
 | `x env check\|example` | the typed environment `envSchema` declares | and the `.env.example` rendered from it |
+| `x auth seal-mfa` | one-shot auth maintenance | seals every `x_users.mfa_secret` still in the clear; idempotent, `{ sealed, alreadySealed, skipped }` |
 | `x secrets show\|init\|edit\|set\|rotate` | the committed encrypted secrets | decrypted into the `envSchema` variables of the same names |
 | `x policy list\|explain <subject>` | which clause decided a permission, and why | five packages print `x policy explain` as a denial's `fix:` |
 | `x i18n check\|add\|sync` | catalogs: gaps, a new locale, key sync | all three of i18n's own error fixes name it |
@@ -192,14 +193,13 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | Class | Code | Declared in |
 |---|---|---|
 | `BadFlagError` | `X_CLI_BAD_FLAG` | `src/errors.ts` |
-| `BuildEntryMissingError` | `X_BUILD_ENTRY_MISSING` | `src/build-errors.ts` |
+| `BuildEntryMissingError` | `X_BUILD_ENTRY_MISSING` | `src/cmd-build.ts` |
 | `BunVersionError` | `X_BUN_VERSION` | `src/errors.ts` |
 | `CatalogExistsError` | `X_GENERATE_CONFLICT` | `src/errors.ts` |
 | `CdpBrowserMissingError` | `X_CDP_BROWSER_MISSING` | `src/cdp-errors.ts` |
 | `CdpCallFailedError` | `X_CDP_CALL_FAILED` | `src/cdp-errors.ts` |
 | `CdpLaunchFailedError` | `X_CDP_LAUNCH_FAILED` | `src/cdp-errors.ts` |
 | `CdpTimeoutError` | `X_CDP_TIMEOUT` | `src/cdp-errors.ts` |
-| `CliNotImplementedError` | `X_NOT_IMPLEMENTED` | `src/errors.ts` |
 | `DeclarationUnknownError` | `X_DECLARATION_UNKNOWN` | `src/errors.ts` |
 | `E2eAppFailedError` | `X_E2E_APP_FAILED` | `src/e2e-errors.ts` |
 | `E2eEvaluateCapturedError` | `X_E2E_EVALUATE_CAPTURED` | `src/e2e-errors.ts` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "23.0.0",
+  "version": "24.0.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -39,33 +39,33 @@
   },
   "dependencies": {
     "@babel/core": "^8.0.1",
-    "@ultimat3/action": "23.0.0",
-    "@ultimat3/admin": "23.0.0",
-    "@ultimat3/ai": "23.0.0",
-    "@ultimat3/auth": "23.0.0",
-    "@ultimat3/cache": "23.0.0",
-    "@ultimat3/core": "23.0.0",
-    "@ultimat3/db": "23.0.0",
-    "@ultimat3/entity": "23.0.0",
-    "@ultimat3/flags": "23.0.0",
-    "@ultimat3/http": "23.0.0",
-    "@ultimat3/i18n": "23.0.0",
-    "@ultimat3/jobs": "23.0.0",
-    "@ultimat3/mail": "23.0.0",
-    "@ultimat3/manifest": "23.0.0",
-    "@ultimat3/mcp": "23.0.0",
-    "@ultimat3/money": "23.0.0",
-    "@ultimat3/notify": "23.0.0",
-    "@ultimat3/policy": "23.0.0",
-    "@ultimat3/pwa": "23.0.0",
-    "@ultimat3/query": "23.0.0",
-    "@ultimat3/realtime": "23.0.0",
-    "@ultimat3/render": "23.0.0",
-    "@ultimat3/schema": "23.0.0",
-    "@ultimat3/seo": "23.0.0",
-    "@ultimat3/storage": "23.0.0",
-    "@ultimat3/testing": "23.0.0",
-    "@ultimat3/time": "23.0.0",
+    "@ultimat3/action": "24.0.0",
+    "@ultimat3/admin": "24.0.0",
+    "@ultimat3/ai": "24.0.0",
+    "@ultimat3/auth": "24.0.0",
+    "@ultimat3/cache": "24.0.0",
+    "@ultimat3/core": "24.0.0",
+    "@ultimat3/db": "24.0.0",
+    "@ultimat3/entity": "24.0.0",
+    "@ultimat3/flags": "24.0.0",
+    "@ultimat3/http": "24.0.0",
+    "@ultimat3/i18n": "24.0.0",
+    "@ultimat3/jobs": "24.0.0",
+    "@ultimat3/mail": "24.0.0",
+    "@ultimat3/manifest": "24.0.0",
+    "@ultimat3/mcp": "24.0.0",
+    "@ultimat3/money": "24.0.0",
+    "@ultimat3/notify": "24.0.0",
+    "@ultimat3/policy": "24.0.0",
+    "@ultimat3/pwa": "24.0.0",
+    "@ultimat3/query": "24.0.0",
+    "@ultimat3/realtime": "24.0.0",
+    "@ultimat3/render": "24.0.0",
+    "@ultimat3/schema": "24.0.0",
+    "@ultimat3/seo": "24.0.0",
+    "@ultimat3/storage": "24.0.0",
+    "@ultimat3/testing": "24.0.0",
+    "@ultimat3/time": "24.0.0",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/affected.ts

@@ -25,23 +25,6 @@ import { readWorkspaceGraph } from './workspace-graph';
 /** The branch a change is measured against when `--base` says nothing. */
 export const DEFAULT_BASE = 'main';
 
-/**
- * Root files that belong to no workspace and change what every workspace compiles to: a compiler
- * option, a lint rule, the root manifest, the resolved dependency tree, the test preload, the app
- * config. A "scoped" run that skipped them reports green over packages the edit just broke.
- *
- * Matched on the WHOLE path — `packages/cli/package.json` is the cli workspace's own file and
- * reaches only cli's dependents, `package.json` at the root reaches everything.
- */
-export const ROOT_WIDE_FILES: readonly string[] = [
-  'app.config.ts',
-  'biome.json',
-  'bun.lock',
-  'bunfig.toml',
-  'package.json',
-  'tsconfig.json',
-];
-
 /**
  * A file with no compilation unit behind it. A doc or a plan re-checks nothing, so it maps to no
  * workspace at all rather than to the one it happens to sit inside — `packages/cli/README.md` is
@@ -107,7 +90,13 @@ export interface AffectedPlan {
   readonly changed: readonly string[];
   /** The subset with no compilation unit behind it, named so an empty answer explains itself. */
   readonly ignored: readonly string[];
-  /** The root files that forced every workspace in, empty when none did. */
+  /**
+   * The changed files no workspace owns, which forced every workspace in — and the root itself — or
+   * empty when none did. A root file (`tsconfig.base.json`, `biome.json`, `bun.lock`, the test
+   * preload, `scripts/`, `guards/`) changes what every workspace compiles to or is checked by, and
+   * a scoped run that skipped it reports green over packages the edit just broke. Matched on
+   * ownership, never on a list of names: a list misses the file nobody thought to add to it.
+   */
   readonly rootWide: readonly string[];
   readonly workspaces: readonly WorkspaceNode[];
 }
@@ -124,14 +113,15 @@ export function planAffected(
 ): AffectedPlan {
   const ignored = changed.filter(isDoc);
   const considered = changed.filter((path) => !isDoc(path));
-  const rootWide = considered.filter((path) => ROOT_WIDE_FILES.includes(path));
-  if (rootWide.length > 0) {
-    return { changed, ignored, rootWide, workspaces: [...graph].sort(byName) };
-  }
+  const rootWide: string[] = [];
   const seeds = new Set<string>();
   for (const path of considered) {
     const node = owningWorkspace(graph, path);
-    if (node !== undefined) seeds.add(node.name);
+    if (node === undefined) rootWide.push(path);
+    else seeds.add(node.name);
+  }
+  if (rootWide.length > 0) {
+    return { changed, ignored, rootWide, workspaces: [...graph].sort(byName) };
   }
   const reached = withDependents(graph, seeds);
   return {
@@ -263,14 +253,20 @@ export interface AffectedScope {
 }
 
 /**
- * An empty prefix means the scan root IS an affected workspace, so every path it yields is in
- * scope; a prefix starting with `..` is a workspace outside that root, which has no file there to
- * select and must not be allowed to collapse into a match-everything empty string.
+ * The plan's scope, relative to the directory the caller scans. A ROOT-WIDE plan is the whole scan
+ * root (`''`): every workspace is in it, and so is every file no workspace owns — a `scripts/` test
+ * stayed out of the run while `package.json` changed when only workspace directories were listed.
+ *
+ * Otherwise an empty prefix means the scan root IS an affected workspace, so every path it yields
+ * is in scope; a prefix starting with `..` is a workspace outside that root, which has no file there
+ * to select and must not be allowed to collapse into a match-everything empty string.
  */
-const scopePrefixes = (root: string, cwd: string, dirs: readonly string[]): readonly string[] =>
-  dirs
-    .map((dir) => relative(cwd, join(root, dir)).split('\\').join('/'))
-    .filter((path) => !path.startsWith('..'));
+export const scopePrefixes = (plan: AffectedPlan, root: string, cwd: string): readonly string[] =>
+  plan.rootWide.length > 0
+    ? ['']
+    : plan.workspaces
+        .map((workspace) => relative(cwd, join(root, workspace.dir)).split('\\').join('/'))
+        .filter((path) => !path.startsWith('..'));
 
 export const inScope = (path: string, prefixes: readonly string[]): boolean =>
   prefixes.some((prefix) => prefix === '' || path === prefix || path.startsWith(`${prefix}/`));
@@ -300,11 +296,7 @@ export async function affectedScope(options: AffectedScopeOptions): Promise<Affe
     selection,
     root,
     plan,
-    prefixes: scopePrefixes(
-      root,
-      options.cwd,
-      plan.workspaces.map((workspace) => workspace.dir),
-    ),
+    prefixes: scopePrefixes(plan, root, options.cwd),
   };
 }
 

package/src/api-registration.ts

@@ -4,8 +4,10 @@
 // `x.manifest.json` and in every dead-letter trace — under a green gate (plan 101 slice 11 b).
 // Actions and queries are listed for the TYPE: `Api` is what the browser's client is shaped from.
 
+import { ERROR_DOCS_URL } from '@ultimat3/core';
 import { API_INDEX } from './app-root';
 import { containedPath } from './generate-write';
+import type { Finding } from './output';
 import { camel } from './templates/naming';
 import { wrapList } from './templates/wrap';
 
@@ -143,6 +145,93 @@ function withImport(source: string, importLine: string): string {
   return lines.join('\n');
 }
 
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+
+/** Every binding an import clause declares: `* as x`, `x`, `{ a, b as c, type d }`. */
+const clauseBindings = (clause: string): readonly string[] =>
+  clause
+    .replace(/^type\s+/, '')
+    .replace(/[{}]/g, ',')
+    .split(',')
+    .map((part) =>
+      part
+        .trim()
+        .replace(/^type\s+/, '')
+        .replace(/^\*\s+as\s+/, ''),
+    )
+    .map(
+      (part) =>
+        part
+          .split(/\s+as\s+/)
+          .at(-1)
+          ?.trim() ?? '',
+    )
+    .filter((name) => IDENTIFIER.test(name));
+
+/**
+ * Every top-level name the index declares, and what holds it: a namespace import by its
+ * specifier, anything else (`defineApi`, `api`, `Api`, a named import) by its own name. A second
+ * binding of any of them is a module that does not load — `import * as api` beside
+ * `export const api` is a ReferenceError in every app-loading command.
+ */
+function declaredBindings(source: string): ReadonlyMap<string, string> {
+  const held = new Map<string, string>();
+  for (const found of source.matchAll(/^import\s+([^;]*?)\s+from\s+'([^']+)';/gm)) {
+    const [, clause = '', specifier = ''] = found;
+    const namespace = /^\*\s+as\s+([A-Za-z_$][\w$]*)$/.exec(clause.trim())?.[1];
+    if (namespace !== undefined) held.set(namespace, specifier);
+    else for (const name of clauseBindings(clause)) held.set(name, `an import from ${specifier}`);
+  }
+  const declaration =
+    /^(?:export\s+)?(?:declare\s+)?(?:const|let|var|function\*?|class|type|interface|enum)\s+([A-Za-z_$][\w$]*)/gm;
+  for (const found of source.matchAll(declaration)) {
+    const [, name = ''] = found;
+    if (!held.has(name)) held.set(name, `the index's own ${name}`);
+  }
+  return held;
+}
+
+/**
+ * A written primitive whose namespace binding the index already holds — for another module, or as
+ * one of its own names — is a finding, decided BEFORE anything is written. Skipped silently, the
+ * job stayed unregistered under a green run; inserted, the index stopped loading.
+ */
+export function apiBindingFindings(
+  source: string,
+  written: readonly string[],
+  fix: string,
+): readonly Finding[] {
+  const held = new Map(declaredBindings(source));
+  const findings: Finding[] = [];
+  for (const entry of apiEntriesFor(written)) {
+    const holder = held.get(entry.binding);
+    if (holder === entry.specifier) continue;
+    if (holder === undefined) {
+      held.set(entry.binding, entry.specifier);
+      continue;
+    }
+    findings.push({
+      code: 'X_GENERATE_CONFLICT',
+      cause: `${API_INDEX} binds every listed module under its file name, and "${entry.binding}" is already ${holder.startsWith('.') ? `the namespace of ${holder}` : holder} — ${entry.specifier} cannot be listed under it`,
+      fix,
+      docs: ERROR_DOCS_URL,
+      at: API_INDEX,
+    });
+  }
+  return findings;
+}
+
+/** `apiBindingFindings` against the app's own index; none when the app has no index. */
+export async function indexBindingFindings(
+  root: string,
+  written: readonly string[],
+  fix: string,
+): Promise<readonly Finding[]> {
+  const file = containedPath(root, API_INDEX);
+  if (!(await Bun.file(file).exists())) return [];
+  return apiBindingFindings(await Bun.file(file).text(), written, fix);
+}
+
 /** Performs `insertApiEntries` on the app's index. Answers the paths it rewrote. */
 export async function registerGeneratedPrimitives(
   root: string,

package/src/app-artifacts.ts

@@ -1,6 +1,6 @@
 // The two generated contracts an app commits — `x.manifest.json` and `openapi.json` — written by one
 // function, because two commands wrote them and only one wrote both: `x g` refreshed the manifest
-// and left `openapi.json` behind, so its own output failed the `contract-diff` step next.
+// and left `openapi.json` behind, so its own output failed the gate's `manifest` step next.
 
 import { join } from 'node:path'; // why: Bun ships no path-join primitive.
 import type { Manifest } from '@ultimat3/manifest';

package/src/app-auth.ts

@@ -1,32 +1,9 @@
 // The one fact `x dev` and `serve.ts` need out of `app.config.ts` before a listener binds: where
-// this app's sign-in page is. Sibling of `app-env.ts`'s `loadEnvSchema`, and imports the config
-// for the same reason — a regex over the app's source is the pattern `app-load.ts` refuses.
+// this app's sign-in page is, off the one loader (`app-config-load.ts`).
 
-import { existsSync } from 'node:fs';
-import { join } from 'node:path';
-import { APP_CONFIG_FILE } from './app-root';
+import { loadAppConfig } from './app-config-load';
 
-/** The export every app declares. Named, never default — the CLI and the runtime both import it. */
-export const APP_CONFIG_EXPORT = 'config';
-
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null;
-
-/**
- * `auth.signInPath`, or `null` when the app declares none.
- *
- * Structural, not `instanceof`: `defineConfig` returns a plain object, and a config that resolved
- * through an older version of core simply has no `auth` section. `null` is the safe answer either
- * way — it is what turns the browser redirect off and leaves the problem document in place.
- */
+/** `auth.signInPath`, or `null` when the app declares none or the root has no config file. */
 export async function loadSignInPath(root: string): Promise<string | null> {
-  const configPath = join(root, APP_CONFIG_FILE);
-  if (!existsSync(configPath)) return null;
-  const module = (await import(configPath)) as Record<string, unknown>;
-  const config = module[APP_CONFIG_EXPORT];
-  if (!isRecord(config)) return null;
-  const auth = config['auth'];
-  if (!isRecord(auth)) return null;
-  const path = auth['signInPath'];
-  return typeof path === 'string' && path.startsWith('/') ? path : null;
+  return (await loadAppConfig(root))?.auth.signInPath ?? null;
 }

package/src/app-config-load.ts

@@ -0,0 +1,51 @@
+// The one reader of an app's `app.config.ts`: imported here and nowhere else in the tree
+// (`bun run boundaries`, `X_CONFIG_IMPORT_OUTSIDE_LOADER`), its `config` export handed back through
+// core's own `defineConfig` — so every boot fact the CLI reads is the validated, default-merged
+// `AppConfig`, never a structural walk with a fallback of its own.
+
+// why: Bun exposes no path-join primitive, and the config path is app-root-relative.
+import { join } from 'node:path';
+import type { AppConfig, AppConfigInput } from '@ultimat3/core';
+import { ConfigInvalidError, defineConfig, describeValue } from '@ultimat3/core';
+import { APP_CONFIG_FILE } from './app-root';
+
+/** The export every app declares. Named, never default — the CLI and the runtime both import it. */
+export const APP_CONFIG_EXPORT = 'config';
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/**
+ * One named export of `root`'s `app.config.ts`, or `undefined` when the root has no such file or
+ * the module does not export `name`. A module that will not import throws as it did — the callers
+ * that report rather than crash (`x doctor`'s env check) turn that into a finding.
+ */
+export async function appConfigExport(root: string, name: string): Promise<unknown> {
+  const path = join(root, APP_CONFIG_FILE);
+  if (!(await Bun.file(path).exists())) return undefined;
+  const module = (await import(path)) as Record<string, unknown>;
+  return Object.hasOwn(module, name) ? module[name] : undefined;
+}
+
+/**
+ * `root`'s `AppConfig`, or `undefined` when the root has no `app.config.ts` — not an app, and each
+ * caller's "nothing declared" answer is its own. A file that IS there is held to `defineConfig`'s
+ * one validator: a hand-built `config` object, or one resolved through an older core, reaches the
+ * boot validated and defaulted exactly as one built by `defineConfig` does, which re-merges to
+ * itself. A file with no `config` object is refused rather than read as "every default".
+ */
+export async function loadAppConfig(root: string): Promise<AppConfig | undefined> {
+  const path = join(root, APP_CONFIG_FILE);
+  if (!(await Bun.file(path).exists())) return undefined;
+  const exported = await appConfigExport(root, APP_CONFIG_EXPORT);
+  if (!isRecord(exported)) {
+    throw new ConfigInvalidError({
+      cause: `${path} exports no ${APP_CONFIG_EXPORT} object (${describeValue(exported)})`,
+      fix: "export const config = defineConfig({ name: 'my-app' });",
+      meta: { key: APP_CONFIG_EXPORT },
+    });
+  }
+  // A cast over a record whose structure `defineConfig` screens first (`shapeIssues`, per layer):
+  // the validator IS the parse, and a second hand-written schema here would be a second answer.
+  return defineConfig(exported as unknown as AppConfigInput);
+}

package/src/app-env.ts

@@ -2,8 +2,6 @@
 // `app.config.ts`, the `.env.example` projected from it, and the drift between the two. One
 // declaration, both files (axiom 2) — nothing here holds a second list of variable names.
 
-// why: Bun ships no synchronous exists; `existsSync` answers whether this root is an app.
-import { existsSync } from 'node:fs';
 // why: Bun exposes no path API — the two files this module reads are joined to the app root.
 import { join } from 'node:path';
 import type { EnvSchema, EnvVarDecl } from '@ultimat3/core';
@@ -13,6 +11,7 @@ import {
   ERROR_DOCS_URL,
   renderEnvExample,
 } from '@ultimat3/core';
+import { appConfigExport } from './app-config-load';
 import { APP_CONFIG_FILE } from './app-root';
 import type { Finding } from './output';
 import { findingFrom } from './output';
@@ -45,17 +44,12 @@ export const isEnvSchema = (value: unknown): value is EnvSchema =>
   isRecord(value) && Object.values(value).every(isDecl);
 
 /**
- * Import `app.config.ts` and hand back the declaration it exports. Importing is the only honest
- * way to read it — the alternative is a regex over the app's source, which is the pattern
- * `app-load.ts` exists to refuse. `undefined` means "this root declares no environment"; a config
- * that will not import throws, and the caller turns that into the finding.
+ * The declaration `app.config.ts` exports, through the one loader (`app-config-load.ts`).
+ * `undefined` means "this root declares no environment"; a config that will not import throws, and
+ * the caller turns that into the finding.
  */
 export async function loadEnvSchema(root: string): Promise<EnvSchema | undefined> {
-  const configPath = join(root, APP_CONFIG_FILE);
-  if (!existsSync(configPath)) return undefined;
-  const module = (await import(configPath)) as Record<string, unknown>;
-  const declared = module[ENV_SCHEMA_EXPORT];
-  if (declared === undefined) return undefined;
+  const declared = await appConfigExport(root, ENV_SCHEMA_EXPORT);
   return isEnvSchema(declared) ? declared : undefined;
 }
 

package/src/app-manifest.ts

@@ -117,14 +117,8 @@ const routeFacts = (): readonly RouteFact[] =>
       ...budgetOf(route),
     }));
 
-function budgetOf(route: RouteDescriptor): { budget?: { js?: string; lcp?: number } } {
-  if (route.budgetJs === null && route.budgetLcp === null) return {};
-  return {
-    budget: {
-      ...(route.budgetJs === null ? {} : { js: route.budgetJs }),
-      ...(route.budgetLcp === null ? {} : { lcp: route.budgetLcp }),
-    },
-  };
+function budgetOf(route: RouteDescriptor): { budget?: { js: string } } {
+  return route.budgetJs === null ? {} : { budget: { js: route.budgetJs } };
 }
 
 /**

package/src/app-mcp.ts

@@ -9,7 +9,7 @@
 
 // why: a directory's existence — `Bun.file().exists()` answers for files, and `apps/` is a directory.
 import { existsSync } from 'node:fs';
-// why: Bun exposes no path-join primitive; the config file and each candidate are joined to root.
+// why: Bun exposes no path-join primitive; each candidate is joined to root.
 import { join } from 'node:path';
 import { logger } from '@ultimat3/core';
 import type { Route } from '@ultimat3/http';
@@ -20,8 +20,7 @@ import {
   McpPathDuplicateError,
   PROTECTED_RESOURCE_WELL_KNOWN,
 } from '@ultimat3/mcp';
-import { APP_CONFIG_EXPORT } from './app-auth';
-import { APP_CONFIG_FILE } from './app-root';
+import { loadAppConfig } from './app-config-load';
 
 /** The one file an app writes, per app directory. */
 export const APP_MCP_GLOB = 'apps/*/mcp.ts';
@@ -57,26 +56,9 @@ interface ExposeDeclaration {
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   typeof value === 'object' && value !== null;
 
-/**
- * `config.ai.mcp`, off the app's own resolved config — the exported `config` is what
- * `defineConfig` returned, so both keys are present and defaulted. Read the same way
- * `loadSignInPath` reads `auth.signInPath`: the config file is imported, never re-parsed.
- * An app with no config file has nothing exposed and nothing to warn about.
- */
+/** `config.ai.mcp` off the one loader (`app-config-load.ts`); nothing exposed with no config file. */
 async function exposeDeclaration(root: string): Promise<ExposeDeclaration | undefined> {
-  const configPath = join(root, APP_CONFIG_FILE);
-  if (!(await Bun.file(configPath).exists())) return undefined;
-  const module = (await import(configPath)) as Record<string, unknown>;
-  const config = module[APP_CONFIG_EXPORT];
-  if (!isRecord(config) || !isRecord(config['ai']) || !isRecord(config['ai']['mcp'])) {
-    return undefined;
-  }
-  const mcp = config['ai']['mcp'];
-  const path = mcp['path'];
-  return {
-    expose: mcp['expose'] === true,
-    path: typeof path === 'string' && path.startsWith('/') ? path : '/mcp',
-  };
+  return (await loadAppConfig(root))?.ai.mcp;
 }
 
 const isAppMcp = (value: unknown): value is AppMcp =>
@@ -213,8 +195,13 @@ function endpointRoutes(route: Descriptor, path: string, index: number): readonl
       // The PUBLIC origin, as the pipeline resolved it (`ctx.https` honours a trusted proxy's
       // `x-forwarded-proto`): behind a TLS-terminating ingress the raw request URL is `http://`
       // on an internal host, and a `resource_metadata` naming that is a URL no client can reach.
+      // The client ADDRESS likewise: failed tokens are metered per address, and the descriptor
+      // has no other way to learn it.
       handler: (request, ctx) =>
-        route.handle(request.raw, { origin: selfOrigin(ctx.url, ctx.https) }),
+        route.handle(request.raw, {
+          origin: selfOrigin(ctx.url, ctx.https),
+          address: ctx.ip ?? undefined,
+        }),
       meta: { name, auth: 'public', enforcedBy: 'handler' },
     },
     ...metadata,