@ultimat3/cli 7.0.0 → 9.0.0

package/src/dev-replicator.ts

@@ -4,13 +4,9 @@
 // roles reading the other end of that transport.
 
 import { describeEntities } from '@ultimat3/entity';
-import type { Replicator, Transport } from '@ultimat3/realtime';
-import {
-  createReplicator,
-  ReplicatorSlotHeldError,
-  replicatorLockKey,
-  selectChangeFeed,
-} from '@ultimat3/realtime';
+import { ReplicatorSlotHeldError } from '@ultimat3/realtime';
+import type { Replicator, Transport } from '@ultimat3/realtime/server';
+import { createReplicator, replicatorLockKey, selectChangeFeed } from '@ultimat3/realtime/server';
 import type { DevServices, Env } from './dev-services';
 import { BadFlagError } from './errors';
 

package/src/dev-roles-fixture.ts

@@ -16,7 +16,7 @@ import {
   resetTasks,
 } from '@ultimat3/jobs';
 import { createMemoryDriver as createMemoryMailDriver } from '@ultimat3/mail';
-import { DEFAULT_PRESENCE_TTL_MS, InProcessTransport } from '@ultimat3/realtime';
+import { DEFAULT_PRESENCE_TTL_MS, InProcessTransport } from '@ultimat3/realtime/server';
 import { defineStorage, localDriver } from '@ultimat3/storage';
 import type { RunningServices } from './dev-runtime';
 import { resolveServices } from './dev-services';

package/src/dev-roles.ts

@@ -8,7 +8,7 @@
 
 import type { Role } from '@ultimat3/core';
 import { createContext, isRole, logger, ROLES } from '@ultimat3/core';
-import type { Route, ServerHandle, ServerHooks } from '@ultimat3/http';
+import type { RateLimitStore, Route, ServerHandle, ServerHooks } from '@ultimat3/http';
 import { configuredAuthenticator, createServer, defineHttpConfig } from '@ultimat3/http';
 import type { OutboxRelay, Scheduler, Worker } from '@ultimat3/jobs';
 import {
@@ -195,11 +195,43 @@ export function trustedHopsFromEnv(env: Env): number | null {
   return hops;
 }
 
+/**
+ * A deployment that substituted a PER-PROCESS store is enforcing every declared number once per
+ * replica, and the shipped chart runs three. Not refused — `assertRateLimitScope` only fires on a
+ * `'shared'` declaration, and the scope below is DERIVED from the store, so the two can never
+ * contradict each other — but the multiplier is stated, in the `warnIfUnauthenticatable` shape:
+ * loud, coded, and naming the call that fixes it.
+ *
+ * Only for a store the host SUPPLIED. A boot with no store at all resolved one of its own
+ * (`startServices`), so the remaining silent case is a hand-built `RunningServices` in a test.
+ */
+function warnIfProcessScoped(store: RateLimitStore): void {
+  if (store.scope === 'shared') return;
+  logger.warn(
+    `X_CONFIG_INVALID: the rate-limit store this deployment passed keeps its counters per process, so every limit the app declares is enforced once per replica — docker/helm/values.yaml runs roles.web.replicas: 3, which is 3x every number — fix: drop runtime.rateLimitStore and the boot installs postgresRateLimitStore({ executor }) on the pool it already opened`,
+  );
+}
+
+/**
+ * Where this web role's limiter keeps its counters: what the deployment SUBSTITUTED, else the
+ * shared Postgres store `startServices` resolved over the pool this boot already opened.
+ *
+ * One expression, one answer, in the order `RuntimeOverrides` documents — an override REPLACES the
+ * resolved default rather than sitting beside it. `undefined` is reachable only from a hand-built
+ * runtime, which is `createServer`'s per-process memory store and `scope: 'process'` below.
+ */
+function rateLimitStoreFor(options: StartRolesOptions): RateLimitStore | undefined {
+  const supplied = options.overrides?.rateLimitStore;
+  if (supplied === undefined) return options.runtime.rateLimitStore;
+  warnIfProcessScoped(supplied);
+  return supplied;
+}
+
 function startWeb(options: StartRolesOptions): ServerHandle {
   warnIfUnauthenticatable(options.routes);
   const binding = options.http ?? DEV_BINDING;
   const hops = trustedHopsFromEnv(options.env);
-  const store = options.overrides?.rateLimitStore;
+  const store = rateLimitStoreFor(options);
   return createServer({
     routes: options.routes,
     role: 'web',
@@ -218,12 +250,12 @@ function startWeb(options: StartRolesOptions): ServerHandle {
       signInPath: options.signInPath ?? null,
       // One declaration, never half of one: `defineHttpConfig` refuses `trustProxy` without hops.
       ...(hops === null ? {} : { trustProxy: true, trustedProxyHops: hops }),
-      // `scope` is mandatory since @ultimat3/http made an undeclared limiter a boot error: the
-      // old `'process'` default meant the shipped chart's three `web` replicas enforced
-      // `login: { limit: 5 }` as fifteen attempts, with `x verify` green. It is DERIVED from the
-      // store rather than hardcoded — a deployment that hands `runtime.rateLimitStore` a shared
-      // store is declaring the fleet-wide numbers, and `assertRateLimitScope` then holds the two
-      // halves together instead of a literal here quietly contradicting the store beside it.
+      // `scope` is mandatory since @ultimat3/http made an undeclared limiter a boot error, and it
+      // is DERIVED from the store rather than hardcoded — a literal here would be a second
+      // declaration quietly contradicting the object beside it, and `assertRateLimitScope` holds
+      // the two halves together. It answered `'process'` on every real boot until `startServices`
+      // resolved a store, so the shipped chart's three `web` replicas enforced `login: { limit: 5 }`
+      // as fifteen attempts, with `x verify` green.
       rateLimit: { scope: store?.scope ?? 'process' },
       // Hashes, never `'unsafe-inline'`: a `render: 'static'` page is a file on disk, so
       // nothing can stamp a per-response nonce into it, but its body is fixed and a hash is a

package/src/dev-runtime.ts

@@ -4,9 +4,19 @@
 // boot installs, only backed by embedded drivers.
 
 import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { configureAuthLimiters, postgresAuthLimiter, resetAuthLimiters } from '@ultimat3/auth';
 import type { PurgeDriver } from '@ultimat3/cache';
 import { isNoopPurgeDriver, selectPurgeDriver } from '@ultimat3/cache';
-import { isLocal, renderThrowable, resolveEnvironment } from '@ultimat3/core';
+import {
+  isLocal,
+  registerReadinessCheck,
+  renderThrowable,
+  resolveEnvironment,
+  systemClock,
+} from '@ultimat3/core';
+import type { RateLimitStore } from '@ultimat3/http';
+import { postgresRateLimitStore } from '@ultimat3/http';
 import type { EventBus, JobDriver, OutboxStore } from '@ultimat3/jobs';
 import type { MailDriver } from '@ultimat3/mail';
 import {
@@ -16,13 +26,14 @@ import {
   selectMailDriver,
   setMailDriver,
 } from '@ultimat3/mail';
-import type { Transport, TransportSelection } from '@ultimat3/realtime';
-import { selectTransport } from '@ultimat3/realtime';
+import type { Transport, TransportSelection } from '@ultimat3/realtime/server';
+import { selectTransport } from '@ultimat3/realtime/server';
 import type { Storage } from '@ultimat3/storage';
 import { defineStorage, localDriver, s3Driver, usesDevStorageSecret } from '@ultimat3/storage';
-import { startCacheTiers } from './dev-cache';
+import { loadCacheTiers, startCacheTiers } from './dev-cache';
+import { installRetentionSweep } from './dev-purge';
 import type { DevDbClient } from './dev-queue';
-import { startQueue } from './dev-queue';
+import { pgExecutorFor, startQueue } from './dev-queue';
 import type { DevServices, Env } from './dev-services';
 import { LocalDiskUnsafeError, StorageUnwritableError } from './errors';
 import { msg } from './messages';
@@ -51,6 +62,20 @@ export interface RunningServices {
    * would show members leaving that never left.
    */
   readonly presenceTtlMs: number;
+  /**
+   * Where the HTTP rate limiter keeps its counters, over the pool this boot already opened.
+   *
+   * Resolved HERE and not at `startWeb` for the reason every other driver is: `startServices` is
+   * what holds the connection, and a store built anywhere else would open a second pool against a
+   * url this boot resolved once. Until it did, no boot installed one at all — so `rateLimit.scope`
+   * derived to `'process'` on every deployment the framework produces, while `docker/helm` runs
+   * `roles.web.replicas: 3` and `x new` scaffolds two.
+   *
+   * OPTIONAL because a `RunningServices` can be hand-built: a test's fixture runtime has a stub
+   * client and no shared store, which is `createServer`'s memory store and `scope: 'process'` —
+   * the honest answer for it, and the one `startWeb` derives.
+   */
+  readonly rateLimitStore?: RateLimitStore;
   readonly purge: PurgeDriver;
   /** Same rule as `mailDetail`: the env key that selected the CDN, never the token behind it. */
   readonly purgeDetail: string;
@@ -176,6 +201,59 @@ export function startStorage(services: DevServices, env: Env, override?: Storage
   return defineStorage({ disks: { local: localDriver({ root }) }, default: 'local' });
 }
 
+/**
+ * A readiness check over a dependency that can only be asked asynchronously.
+ *
+ * `ReadinessCheck` is synchronous and that is the mechanism, not a limitation: a probe that awaits
+ * a network call takes as long as the dependency does, so a slow database makes `/readyz` miss its
+ * `timeoutSeconds`, the kubelet reads that as unready, and capacity is pulled from an already
+ * struggling system — the outage the probe existed to prevent, caused by the probe.
+ *
+ * So the read answers the PREVIOUS probe and schedules the next, which is the standard cached
+ * health shape: staleness is one poll period, and the poll period is the operator's own
+ * `periodSeconds`. Deliberately not a `setInterval`: a timer would probe a process nobody is
+ * asking about, and in `x dev` every probe is a statement — one span, one trace id — so a
+ * one-per-second heartbeat would evict every real request from `/_x/timeline` inside a minute.
+ *
+ * It starts `true` because it is already proven: `startQueue` pinged this pool before this line
+ * ran, and a boot that could not would have thrown instead of reaching here.
+ */
+function probedReadinessCheck(name: string, probe: () => Promise<unknown>): () => void {
+  let live = true;
+  let inFlight = false;
+  const refresh = (): void => {
+    if (inFlight) return;
+    inFlight = true;
+    void probe()
+      .then(
+        () => {
+          live = true;
+        },
+        // Every rejection, including the coded `X_DB_UNAVAILABLE` a closed pool answers with. A
+        // check that threw would be reported as failing anyway; catching it here keeps the reason
+        // out of the endpoint's own path, where nothing could report it.
+        () => {
+          live = false;
+        },
+      )
+      .finally(() => {
+        inFlight = false;
+      });
+  };
+  return registerReadinessCheck(name, () => {
+    refresh();
+    return live;
+  });
+}
+
+/** A transport that says whether it is connected. NATS does; the in-process bus has nothing to be. */
+interface ConnectableTransport {
+  readonly connected: boolean;
+}
+
+const saysConnected = (transport: Transport): transport is Transport & ConnectableTransport =>
+  typeof (transport as Partial<ConnectableTransport>).connected === 'boolean';
+
 /**
  * Release what has already started, newest first, and return every failure instead of throwing on
  * the first: a step that rejects must not skip the ones after it, or one transport that will not
@@ -214,10 +292,45 @@ export async function startServices(
   const bus: TransportSelection = selectTransport(env);
   const queue = await startQueue(services, overrides);
   const { db, jobs, outbox, events } = queue;
+  // The same executor the jobs driver, the outbox, the event bus and the idempotency store run
+  // on — one pool, one `Bun.sql` that does NOT satisfy `PgExecutor` (`Bun.sql.query` is
+  // `undefined`), one wrapper.
+  const executor = pgExecutorFor(db);
+  const rateLimitStore = postgresRateLimitStore({ executor });
   // Boot is a sequence of external resources, and every step after the first can reject — the
   // queue is already up, so from here an unwind must release it exactly like everything after it.
+  // Which is why the `try` opens on the NEXT line and not eight steps further down: it did, and
+  // the steps above it registered process-wide state (`configureAuthLimiters`, the `purge()` job
+  // and its `task`) that throws on a name a previous boot in this process left in the registry —
+  // `X_JOB_NAME_TAKEN`, outside the unwind, so `x dev` exited holding the PGlite lock, the pool
+  // and the ambient accessors. Nothing may be pushed onto `started` from outside this block.
   const started: (() => void | Promise<void>)[] = [() => queue.stop()];
   try {
+    // Where failed sign-ins are counted, installed BEFORE `loadApp` for the reason the idempotency
+    // store is: `defineAuth` is the app's call and it runs when the app's modules import, so a seam
+    // filled afterwards is one every app would have to fill itself. A FACTORY and not a limiter —
+    // the app declares `maxAttempts`/`windowMs`/`lockoutMs` and this boot has not read them yet, so
+    // a limiter built here would be refused by `assertAuthLimiterPolicy` on any app that tuned one.
+    //
+    // Until this line every deployment the framework produces counted lockouts per POD, while
+    // `x new` scaffolds `replicas: 2` and `docker/helm` runs three — `maxAttempts × N` guesses per
+    // account, and a lockout one replica established invisible to the rest.
+    configureAuthLimiters((policy) =>
+      postgresAuthLimiter({ executor, clock: systemClock, policy }),
+    );
+    started.push(() => resetAuthLimiters());
+    // The hourly sweep over the three framework tables this boot is responsible for. Every one of
+    // them ships a `purgeExpired()` that nothing called, so every row written was a row kept —
+    // `x_rate_limit` takes one upsert per request the web role serves, assets included.
+    started.push(
+      installRetentionSweep({ idempotency: queue.idempotency, rateLimit: rateLimitStore }),
+    );
+    // One readiness check per resource this boot OWNS, released with it. Nothing in the tree
+    // registered one, so `/readyz` was `markReady()` alone — "this process bound a socket" — and
+    // `packages/http/src/server.ts` calls that BEFORE `Bun.serve`, while `dev-roles.ts` calls it
+    // before `sync`, `worker` and `scheduler` start. The chart's `readinessProbe` and the container
+    // healthcheck both route on it, so a replica whose pool was gone kept taking traffic.
+    started.push(probedReadinessCheck('database', () => db.ping()));
     // Dialled here rather than at selection: an unreachable bus must fail at `x dev`, not on the
     // first change nobody receives, and the socket is a resource the unwind below has to release.
     // A supplied transport is already connected and is NOT closed here: whoever built it owns its
@@ -228,6 +341,14 @@ export async function startServices(
       started.push(() => bus.transport.close());
       transport = bus.transport;
     }
+    // Only a transport that can be disconnected gets a check. `NatsTransport.connected` is a
+    // synchronous getter over the client's own state, so no probe is needed; the in-process bus
+    // has nothing to lose a connection to, and a check that can only answer `true` is a number in
+    // `registered` that means nothing.
+    if (saysConnected(transport)) {
+      const connectable = transport;
+      started.push(registerReadinessCheck('transport', () => connectable.connected));
+    }
     const storage = startStorage(services, env, overrides?.storage);
     // With no credential this is the memory driver: caught, not sent, so the `/_x` mail panel can
     // show what a template renders in every locale without a mailbox or a message escaping to a
@@ -243,7 +364,13 @@ export async function startServices(
     // recomputed every cached read. Released with `resetTiers()`, which drops the whole registry:
     // this boot is the only thing that registers one, and a tier left behind would purge for a
     // process that has stopped.
-    started.push(startCacheTiers({ env, purge, transport }));
+    // The ladder is the app's declaration, never the environment's. `cache.tiers` was declared,
+    // validated and documented while NOTHING read it — so an app asking for one rung got four,
+    // and one asking for a shared tier got whatever `REDIS_URL` happened to say. `.x` is
+    // `resolveServices`' own join, so its parent is the app root: the one fact this function needs
+    // and does not already carry.
+    const tiers = await loadCacheTiers(dirname(services.stateDir));
+    started.push(startCacheTiers({ env, purge, transport, tiers }));
 
     return {
       services,
@@ -255,6 +382,10 @@ export async function startServices(
       storage,
       mail,
       mailDetail: selection.detail,
+      // Built above, beside the auth limiter factory and the retention sweep that purges its
+      // table: three readers of one executor, resolved once. `startWeb` is what an override
+      // replaces it at.
+      rateLimitStore,
       // The env key that selected the bus — or the honest answer that no env key did, because a
       // boot line reading `NATS_URL` over a transport the host handed in is a lie a script parses.
       transportDetail: overrides?.transport === undefined ? bus.detail : 'runtime override',

package/src/dev-sync.ts

@@ -13,7 +13,7 @@ import {
   PresenceRegistry,
   RingChangeBuffer,
   SocketRegistry,
-} from '@ultimat3/realtime';
+} from '@ultimat3/realtime/server';
 import type { StartRolesOptions } from './dev-roles';
 import { syncAuthenticator } from './sync-authenticator';
 
@@ -69,9 +69,14 @@ export async function startSync(options: StartRolesOptions): Promise<RunningSync
   const hub = new ChannelHub({ transport: options.runtime.transport, sockets });
   // The node evaluated no credential of its own and no host ever handed it one, so every socket
   // the framework opened was anonymous and every guard, gate, presence entry and tenant cap
-  // decided against `null`. An explicit override first — only that one can carry an `expiresAt`
-  // and a `refresh`, which is the whole of re-authorization — then the app's own HTTP resolver,
-  // then nothing at all, which is what `x dev` with no authenticator should stay.
+  // decided against `null`. An explicit override first, then the app's own HTTP resolver, then
+  // nothing at all, which is what `x dev` with no authenticator should stay.
+  //
+  // BOTH of the first two re-authorize: `syncAuthenticator` carries an `expiresAt` and a `refresh`
+  // of its own (`SYNC_GRANT_TTL_MS`), re-asking the app's resolver with the upgrade's own
+  // `cookie`/`authorization`, so `logout` closes the socket and not only the HTTP session. The
+  // override is how a deployment states a window its credential already declares (a token's
+  // `exp`), or resolves identity from a header the adapter deliberately does not retain.
   const authenticate = options.overrides?.syncAuthenticate ?? syncAuthenticator(options.buildId);
   const node = createSyncNode({
     hub,

package/src/dispatch.ts

@@ -3,6 +3,7 @@
 // path as results, so a failure is machine-readable exactly like a success.
 
 import { isAbsolute, resolve } from 'node:path';
+import { setLogStream } from '@ultimat3/core';
 import { requireAppRoot, requireBunVersion } from './app-root';
 import { createHelpCommand } from './cmd-help';
 import { plannedCommandFor } from './cmd-planned';
@@ -23,8 +24,26 @@ export interface DispatchOptions {
   readonly bunVersion: string;
   readonly runner?: Runner;
   readonly write: (line: string) => void;
+  /**
+   * Where a result declaring `stream: 'stderr'` goes. Optional, and it falls back to `write`: an
+   * embedding caller that supplies one sink must still SEE the line, and `create-ultimate`'s entry
+   * point — which can only ever reach `x new` — would otherwise have to declare a sink for a case
+   * it cannot produce. `bin.ts` passes the real fd 2.
+   */
+  readonly writeError?: (line: string) => void;
 }
 
+/**
+ * Which sink a result is written to. One function because `dispatch` writes in five places — the
+ * version refusal, the parse failure, the unknown command, the result and the catch — and a rule
+ * about fd 1 that four of them apply is not a rule.
+ */
+export const sinkFor = (
+  result: CommandResult,
+  options: Pick<DispatchOptions, 'write' | 'writeError'>,
+): ((line: string) => void) =>
+  result.stream === 'stderr' ? (options.writeError ?? options.write) : options.write;
+
 const resolveCwd = (cwd: string, flag: string | undefined): string => {
   if (flag === undefined) return cwd;
   return isAbsolute(flag) ? flag : resolve(cwd, flag);
@@ -48,7 +67,8 @@ export async function dispatch(options: DispatchOptions): Promise<number> {
   try {
     requireBunVersion(options.bunVersion);
   } catch (error) {
-    options.write(render(errorResult('x', error), wantsJson(options.argv)));
+    const failure = errorResult('x', error);
+    sinkFor(failure, options)(render(failure, wantsJson(options.argv)));
     return 1;
   }
 
@@ -70,7 +90,7 @@ export async function dispatch(options: DispatchOptions): Promise<number> {
     // `wantsJson`, not `includes('--json')`: a typo'd flag or a typo'd command is exactly the case
     // an agent hits while always passing `-j`, and the short form rendered prose it then parsed.
     const result = errorResult(planned?.name ?? 'x', failure);
-    options.write(render(result, wantsJson(options.argv)));
+    sinkFor(result, options)(render(result, wantsJson(options.argv)));
     return 1;
   }
 
@@ -83,7 +103,7 @@ export async function dispatch(options: DispatchOptions): Promise<number> {
         known: SPECS.map((spec) => spec.name),
       }),
     );
-    options.write(render(result, args.json));
+    sinkFor(result, options)(render(result, args.json));
     return 1;
   }
 
@@ -105,6 +125,16 @@ export async function dispatch(options: DispatchOptions): Promise<number> {
   };
 
   try {
+    // `--json` means fd 1 carries ONE document, and every command that boots an app logs through
+    // core's module-scope `logger`, whose default writer is stdout: `x db migrate --json` printed
+    // `ultimate migrate applied` and then the command's own object, so `json.load` on the output
+    // of a command whose whole contract is `--json` raised on the second. Decided HERE, once, for
+    // all thirty commands — a rule each booting command had to remember is a rule the next one
+    // forgets. A server's stdout stays its log stream; this is about the CLI process only.
+    // Set on EVERY dispatch, both ways: the stream is process-wide state, so `if (args.json)`
+    // alone left a JSON run's `stderr` in place for the next non-JSON one — one `x` process
+    // dispatching twice (the MCP host, a test, an embedding caller) lost its boot logs off stdout.
+    setLogStream(args.json ? 'stderr' : 'stdout');
     // The reader `CommandSpec.requiresApp` never had. Its doc said "the dispatcher enforces it" and
     // `dispatch` did not read the field at all: the guarantee held only because all 17 declaring
     // commands happen to call `requireAppRoot` themselves, so a new command that declares it and
@@ -115,7 +145,7 @@ export async function dispatch(options: DispatchOptions): Promise<number> {
     // command, which declares nothing: usage for a command must be readable from anywhere.
     if (target.spec.requiresApp === true) requireAppRoot(target.spec.name, ctx.cwd);
     const result = await target.run(ctx);
-    options.write(render(result, args.json, args.flags.get('verbose') === true));
+    sinkFor(result, options)(render(result, args.json, args.flags.get('verbose') === true));
     // `x dev` and `x mcp serve --transport http` are still listening here: report first, so the
     // url is on stdout the moment it is reachable, then stay in the process until the drain that
     // stops them. Without this the exit code below is what takes the server down.
@@ -123,7 +153,7 @@ export async function dispatch(options: DispatchOptions): Promise<number> {
     return exitCodeFor(result);
   } catch (error) {
     const result = errorResult(args.command, error);
-    options.write(render(result, args.json));
+    sinkFor(result, options)(render(result, args.json));
     return 1;
   }
 }

package/src/document-styles.ts

@@ -5,7 +5,8 @@
 // apart from the styling nobody sees missing. A silent failure is exactly what axiom 3 exists for.
 
 import type { Surface } from '@ultimat3/render';
-import { routeEntries, stylesFor } from '@ultimat3/render';
+import { routeEntries } from '@ultimat3/render';
+import { stylesFor } from '@ultimat3/render/server';
 import type { Finding } from './output';
 
 /** The stylesheet an app is expected to own, named in the fix so it is one edit, not a hunt. */

package/src/drift.ts

@@ -11,7 +11,9 @@
 
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
+import { describeEntities } from '@ultimat3/entity';
 import { countDeclaredEntities } from './app-entities';
+import { loadApp } from './app-load';
 // One declaration of where migrations live, and it belongs to the module that reads them —
 // `x db migrate` and this sidecar must never disagree about the directory they share.
 import { hashFileName, MIGRATIONS_DIR } from './migrations';
@@ -20,7 +22,48 @@ import type { Finding } from './output';
 export const DB_PACKAGE = join('packages', 'db');
 const SCHEMA_GLOB = 'packages/db/src/**/*.ts';
 
-/** Content hash of the whole schema, order-independent per file path. */
+/**
+ * Canonical JSON: object keys sorted, arrays in their own order. The registry's description is a
+ * BUILD INPUT committed to disk as a hash, so a field reordered inside `describe()` upstream would
+ * otherwise move every app's hash and report drift over a framework upgrade nobody made.
+ */
+function canonicalJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  if (typeof value === 'object' && value !== null) {
+    const entries = Object.entries(value as Record<string, unknown>).sort(([a], [b]) =>
+      a < b ? -1 : a > b ? 1 : 0,
+    );
+    return `{${entries.map(([key, held]) => `${JSON.stringify(key)}:${canonicalJson(held)}`).join(',')}}`;
+  }
+  // `undefined` has no JSON form and an optional field left unset must hash as absent, not throw.
+  return JSON.stringify(value) ?? 'null';
+}
+
+/**
+ * What the app's entities declare, as the registry describes them — the half `SCHEMA_GLOB` cannot
+ * see. `x new` puts an entity at `apps/web/app/<feature>/entity.ts` and `packages/db/src/schema.ts`
+ * merely re-exports it, so a column added there moved NO byte the glob reads: three generated
+ * entities and one migration reported clean, with every `.hash` sidecar identical. The registry is
+ * the same fact `x db gen` diffs (`describeEntities()`), so the check and the generator now read
+ * one schema instead of two.
+ *
+ * `loadApp` is what fills that registry, and it is called on every path rather than only where the
+ * caller happens to have loaded already: a hash computed against an EMPTY registry would differ
+ * from the one `x db gen` recorded with the app loaded, and every app would read as drifted.
+ * A module that will not import leaves the registry SHORT rather than raising — the stance
+ * `countDeclaredEntities` already documents — so `x doctor` still answers on the app it diagnoses.
+ */
+async function declaredSchemaJson(root: string): Promise<string> {
+  await loadApp(root);
+  return canonicalJson(describeEntities());
+}
+
+/**
+ * Content hash of the whole schema: the entity registry first, then every non-test file under
+ * `packages/db/src`, order-independent per file path. Both halves, because they answer different
+ * questions — the registry is what reaches the database, and the glob is what catches a seed or a
+ * helper moving under it (which is what `reconcileSchemaHash` exists to re-record).
+ */
 export async function schemaHash(root: string): Promise<string> {
   const glob = new Bun.Glob(SCHEMA_GLOB);
   const paths: string[] = [];
@@ -29,6 +72,7 @@ export async function schemaHash(root: string): Promise<string> {
   }
   paths.sort();
   const hasher = new Bun.CryptoHasher('sha256');
+  hasher.update(await declaredSchemaJson(root));
   for (const path of paths) {
     hasher.update(path);
     hasher.update(await Bun.file(join(root, path)).text());
@@ -77,9 +121,10 @@ export interface HashReconciliation {
 }
 
 /**
- * Re-record the sidecar for a migration that is already the right one. `SCHEMA_GLOB` covers every
- * non-test file under `packages/db/src`, not only the ones that imply DDL, so editing a seed or a
- * helper moves the hash with no diff behind it — and `X_DB_DRIFT`'s `fix:` has to have somewhere to
+ * Re-record the sidecar for a migration that is already the right one. Neither half of the hash is
+ * DDL-only — `SCHEMA_GLOB` covers every non-test file under `packages/db/src`, and the registry
+ * carries invariants and tags a diff can leave empty — so an edit can move the hash with no
+ * statement behind it, and `X_DB_DRIFT`'s `fix:` has to have somewhere to
  * land or the instruction is unfollowable. The caller owes the proof that the DDL genuinely did not
  * move (`db-generate.ts` reaches this only on an empty diff off a fully loaded registry); this
  * function decides only whether a write is needed.
@@ -107,9 +152,9 @@ export type DeclaredEntityCount = () => Promise<number>;
  * Empty result = no drift. A missing db package is not drift (an app may have no database yet);
  * a schema with no migration at all is — *provided* the app declares an entity for one to record.
  *
- * The entity count is read lazily and ONLY in that first branch, so an app past its first migration
- * pays nothing for it: every other path answers from file hashes alone, with no app load and no
- * database, which is what lets the gate run this in a CI with neither.
+ * The entity count is read lazily and ONLY in that first branch; the hash itself loads the app on
+ * every path, because the registry is half of what it covers. Still no database anywhere here,
+ * which is what lets the gate run this in a CI with nothing listening.
  */
 export async function checkSourceDrift(
   root: string,

package/src/error-codes.ts

@@ -56,6 +56,10 @@ export const CLI_OWNED_ERROR_CODES = [
   'X_ROLE_UNKNOWN',
   'X_PORT_INVALID',
   'X_DEV_ALREADY_RUNNING',
+  // The OTHER thing the preflight can find, and it was reported as the one above: an unreadable
+  // lock this process could not remove made `DevAlreadyRunningError` name THIS pid as the holder,
+  // so the remedy printed was `kill <self>` — unrunnable, and a cause that was simply untrue.
+  'X_DEV_LOCK_UNREADABLE',
   // The boot's own consistency check. `startServices` captures the drivers it built, and
   // `loadApp` runs AFTER it — so an app module calling `setJobDriver(theirs)` moved the ambient
   // slot and left the captured object alone: every `handle.enqueue()` went to their queue while
@@ -177,6 +181,7 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_ROLE_UNKNOWN: 'ROLE names something that is not a role',
   X_PORT_INVALID: 'PORT is not a TCP port number',
   X_DEV_ALREADY_RUNNING: 'another x dev already owns this checkout',
+  X_DEV_LOCK_UNREADABLE: 'the dev lock file cannot be read or removed',
   X_RUNTIME_DRIVER_SPLIT: 'the ambient driver is not the one this process serves',
   X_GENERATE_CONFLICT: 'a generator would overwrite a file',
   X_PORT_IN_USE: 'the dev port is taken',