@ultimat3/cli 22.15.0 → 24.0.0

package/src/error-codes.ts

@@ -141,6 +141,11 @@ export const CLI_OWNED_ERROR_CODES = [
   'X_GUARD_INVALID',
   'X_GUARD_FAILED',
   'X_GUARD_FINDING_INVALID',
+  // The browser-transport rule, on `boundaries` in every app (`app-transport.ts`). Both codes
+  // shipped as this repository's own script findings; the rule moved into the gate, so the CLI
+  // emits them and therefore owns them — the code strings and their meaning are unchanged.
+  'X_BROWSER_TRANSPORT_BYPASS',
+  'X_BROWSER_SERVER_BARREL',
   // The CLI's own declarations, held to each other. A flag the parser accepts and no code reads
   // is a promise in `x help` with nothing behind it — `x deploy --critical` said "forces clients
   // to reload" and reached no reader outside the plan JSON it was written into.
@@ -205,11 +210,29 @@ export const CLI_OWNED_ERROR_CODES = [
   'X_SITEMAP_EXTRA_INVALID',
   'X_DEV_RESTART_REQUIRED',
   'X_DEV_ROOT_GONE',
+  'X_SEAL_RESEAL_PENDING',
+  'X_VERIFY_STEP_TIMEOUT',
+  'X_COVERAGE_BELOW_FLOOR',
+  'X_COVERAGE_FLOOR_UNSTATED',
+  'X_COVERAGE_FLOOR_STALE',
+  'X_DB_HANDLE_UNREGISTERED',
+  'X_ROLE_LOAD_INCOMPLETE',
+  'X_ADMIN_RESOURCE_UNWIRED',
+  'X_IMAGE_NOT_PREBUILT',
+  'X_ADMIN_UNSCANNED',
+  'X_FRAMEWORK_TABLE_ORPHANED',
+  'X_BUILD_OUT_UNSAFE',
+  'X_FRAMEWORK_SCHEMA_UNAPPLIED',
+  'X_APP_URL_PORT_MISMATCH',
+  'X_DEV_HOST_REFUSED',
+  'X_TRUSTED_PROXY_HOPS_INVALID',
+  'X_PERMISSION_BORROWED',
+  'X_ERROR_CODE_UNTHROWN_STALE',
 ] as const;
 
 /**
- * `X_NOT_IMPLEMENTED` is `@ultimat3/core`'s — `CliNotImplementedError` and every planned command
- * throw it, and none of them may declare a title for it. The CLI is the process that imports every
+ * `X_NOT_IMPLEMENTED` is `@ultimat3/core`'s — every planned command throws it through core's
+ * own `NotImplementedError`, and none of them may declare a title for it. The CLI is the process that imports every
  * package (`error-catalog.ts`), so a title declared twice here is the one that would win by load
  * order rather than by ownership.
  *
@@ -270,7 +293,7 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_ERROR_CODE_UNREGISTERED: 'the error reference documents a code no package registers',
   X_ERROR_CODE_UNRESOLVED: 'an error code is written as a name this repository cannot resolve',
   X_ERROR_CODE_UNTHROWN:
-    'a registered error code is constructed by nothing and its reference row does not say so',
+    'a registered error code is constructed by nothing and UNTHROWN_CODES in packages/cli/src/unthrown-codes.ts does not list it',
   X_FRAMEWORK_SCHEMA_FAILED: 'a framework table could not be created at boot',
   X_STORAGE_UNWRITABLE: 'the storage disk this process needs cannot be written to',
   X_STORAGE_SECRET_DEV: 'upload grants would be signed with the shipped development key',
@@ -314,6 +337,10 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_GUARD_INVALID: 'a file in guards/ exports no usable guard',
   X_GUARD_FAILED: 'an app guard threw instead of returning findings',
   X_GUARD_FINDING_INVALID: "an app guard's finding breaks the error contract",
+  X_BROWSER_TRANSPORT_BYPASS:
+    'browser-reachable code opens its own connection instead of using the one seam',
+  X_BROWSER_SERVER_BARREL:
+    "browser-reachable code imports a package's server barrel where the package publishes a browser entry",
   X_CLI_FLAG_UNREAD: 'a command declares a flag no code reads',
   X_SECRETS_EDITOR_MISSING: 'no $EDITOR to open the decrypted secrets in',
   X_SECRETS_EDIT_FAILED: 'the editor exited non-zero, so nothing was resealed',
@@ -360,6 +387,31 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_DEV_RESTART_REQUIRED:
     'a save reached a module that defines a primitive; only a new process serves it',
   X_DEV_ROOT_GONE: 'the app root x dev serves was deleted or moved',
+  X_SEAL_RESEAL_PENDING: 'sealed columns still hold values under a retired master key',
+  X_VERIFY_STEP_TIMEOUT: 'a gate step ran past its deadline and was stopped',
+  X_COVERAGE_BELOW_FLOOR: 'the unit suite covers less of the app than x.verify.json states',
+  X_COVERAGE_FLOOR_UNSTATED:
+    'x.verify.json states no coverage floor, or one under 95 with no reason',
+  X_COVERAGE_FLOOR_STALE: 'the app now covers more than the floor in x.verify.json states',
+  X_DB_HANDLE_UNREGISTERED: "an entity x g wrote is not in the app's typed database handle",
+  X_ROLE_LOAD_INCOMPLETE: 'a worker or scheduler did not register a job or task the manifest names',
+  X_ADMIN_RESOURCE_UNWIRED: "an admin override x g wrote is not in the app's defineAdmin() call",
+  X_IMAGE_NOT_PREBUILT:
+    'a container role built at boot what the image build should have: island chunks or stylesheets',
+  X_ADMIN_UNSCANNED:
+    'a defineAdmin() declaration sits outside the app scan, so the admin is never mounted',
+  X_FRAMEWORK_TABLE_ORPHANED:
+    'a framework table no release reads any more is still in the database',
+  X_BUILD_OUT_UNSAFE: 'the static export directory is not one a build may empty',
+  X_FRAMEWORK_SCHEMA_UNAPPLIED:
+    'a serving role booted over a database whose framework schema this build never applied',
+  X_APP_URL_PORT_MISMATCH: 'APP_URL names a loopback port x dev does not serve',
+  X_DEV_HOST_REFUSED: 'a /_x request named a host that is not this machine',
+  X_TRUSTED_PROXY_HOPS_INVALID:
+    'TRUSTED_PROXY_HOPS is not a whole number of proxies the boot accepts',
+  X_PERMISSION_BORROWED: 'an app rule requires a permission only an imported package declared',
+  X_ERROR_CODE_UNTHROWN_STALE:
+    'a code UNTHROWN_CODES lists as thrown by nothing is thrown again — delete it from UNTHROWN_CODES in packages/cli/src/unthrown-codes.ts',
 };
 
 // One unconditional call, so a second package claiming one of the CLI's codes throws

package/src/error-unthrown.ts

@@ -1,7 +1,8 @@
 // A registered code nothing constructs. The registry and the reference keep a shipped code alive
 // forever — which is right — and that is exactly why a code can outlive its last thrower with no
 // gate noticing: `X_RPC_FAILED` sat registered and documented as live after the transport change
-// took its only throw site away. The reference row has to SAY so, or this reports it.
+// took its only throw site away. It has to be LISTED as unthrown (`UNTHROWN_CODES`), or this
+// reports it.
 
 import { join } from 'node:path';
 import { ERROR_DOCS_URL, maskLiterals, stripComments } from '@ultimat3/core';
@@ -9,6 +10,7 @@ import { RESERVED_HEADING } from './error-contract';
 import type { Finding } from './output';
 import { eachSourceFile, isGenerated, isTest } from './source-files';
 import { isCodeRegistry } from './ts-scan';
+import { UNTHROWN_CODES, UNTHROWN_CODES_FILE } from './unthrown-codes';
 
 const CODE_LITERAL = /(['"`])(X_[A-Z0-9_]+)\1/g;
 const TITLE_KEY = /^[\t ]*(X_[A-Z0-9_]+)\s*:/gm;
@@ -18,9 +20,6 @@ const LIST_LINE = /^[\t ]*(['"`])X_[A-Z0-9_]+\1\s*,?\s*$/;
 const TABLE_ENTRY = /\b([a-z][A-Za-z0-9]*)\s*:\s*(['"`])(X_[A-Z0-9_]+)\2/g;
 const MEMBER_READ = /\.([A-Za-z_$][\w$]*)/g;
 
-/** Phrases a reference row uses to say, in words, that nothing throws the code any more. */
-const DECLARED_UNTHROWN = /thrown by nothing|not thrown/i;
-
 export interface CodeUse {
   /** Every code a package registry names. */
   readonly registered: ReadonlySet<string>;
@@ -78,6 +77,8 @@ export async function collectCodeUse(root: string): Promise<CodeUse> {
   const members = new Set<string>();
   for await (const source of eachSourceFile(root)) {
     if (!/^packages\/[^/]+\/src\//.test(source) || isTest(source) || isGenerated(source)) continue;
+    // The list names every code it waives, and naming one is not throwing it.
+    if (source === UNTHROWN_CODES_FILE) continue;
     const use = codeUseOf(await Bun.file(join(root, source)).text());
     for (const code of use.registered) registered.add(code);
     for (const code of use.used) used.add(code);
@@ -88,28 +89,36 @@ export async function collectCodeUse(root: string): Promise<CodeUse> {
   return { registered, used };
 }
 
-/** Codes whose reference row says nothing throws them, or that sit under the reserved heading. */
+/** Codes that sit under the reserved heading — declared unthrown by WHERE they are, not by words. */
 export function declaredUnthrown(markdown: string): ReadonlySet<string> {
   const out = new Set<string>();
   let reserved = false;
   for (const line of markdown.split('\n')) {
     if (line.trim() === RESERVED_HEADING) reserved = true;
     const row = /^\|\s*`(X_[A-Z0-9_]+)`\s*\|/.exec(line);
-    if (row !== null && (reserved || DECLARED_UNTHROWN.test(line))) out.add(row[1] ?? '');
+    if (row !== null && reserved) out.add(row[1] ?? '');
   }
   return out;
 }
 
 const unthrownFinding = (code: string, page: string): Finding => ({
   code: 'X_ERROR_CODE_UNTHROWN',
-  cause: `${code} is registered and ${page} presents it as live, but no shipped source constructs it — a reader matching on it waits for an error that cannot arrive`,
+  cause: `${code} is registered and ${page} presents it as live, but no shipped source constructs it — a reader matching on it waits for an error that cannot arrive. Add it to UNTHROWN_CODES in ${UNTHROWN_CODES_FILE} and say so in its row, or throw it again where it belongs`,
   // Never "delete the registration": a shipped code is stable forever, and an old log line must
   // still explain. The row is what has to change.
-  fix: `write "registered, thrown by nothing since <version>" into ${code}'s row in ${page}, naming the code that replaced it — or throw it again where it belongs`,
+  fix: 'x errors explain X_ERROR_CODE_UNTHROWN --json',
   docs: ERROR_DOCS_URL,
   at: page,
 });
 
+const staleFinding = (code: string): Finding => ({
+  code: 'X_ERROR_CODE_UNTHROWN_STALE',
+  cause: `${code} is listed in UNTHROWN_CODES and shipped source constructs it again — the listing would excuse a code that is live, so delete it from UNTHROWN_CODES in ${UNTHROWN_CODES_FILE}`,
+  fix: 'x errors explain X_ERROR_CODE_UNTHROWN_STALE --json',
+  docs: ERROR_DOCS_URL,
+  at: UNTHROWN_CODES_FILE,
+});
+
 /**
  * Registered, used by nothing, and not declared unthrown on the reference. A host check — the page
  * is the host repo's to name, and only a monorepo's walk sees every package's source; in a
@@ -118,13 +127,22 @@ const unthrownFinding = (code: string, page: string): Finding => ({
 export async function checkErrorCodesThrown(
   root: string,
   page: string,
+  listed: ReadonlySet<string> = UNTHROWN_CODES,
 ): Promise<readonly Finding[]> {
   const reference = Bun.file(join(root, page));
   if (!(await reference.exists())) return [];
-  const exempt = declaredUnthrown(await reference.text());
+  const reserved = declaredUnthrown(await reference.text());
   const { registered, used } = await collectCodeUse(root);
-  return [...registered]
-    .filter((code) => !used.has(code) && !exempt.has(code))
+  const unthrown = [...registered]
+    .filter((code) => !used.has(code) && !listed.has(code) && !reserved.has(code))
     .sort()
     .map((code) => unthrownFinding(code, page));
+  // Only the THROWN-again direction: a listed name no registry holds waives nothing (the code it
+  // was meant to name is still reported), and a host repo's fixture registering none of this
+  // repo's codes would otherwise read every listing as stale.
+  const stale = [...listed]
+    .filter((code) => used.has(code))
+    .sort()
+    .map((code) => staleFinding(code));
+  return [...unthrown, ...stale];
 }

package/src/errors.ts

@@ -2,6 +2,7 @@
 // that resolves it — the codes themselves, their titles and their registration are `./error-codes`,
 // so a package importing a class does not pull the table and vice versa.
 import { UltimateError } from '@ultimat3/core';
+import type { Finding } from './output';
 import { quoteArg } from './shell-quote';
 
 /** An unknown command or subcommand. Carries a suggestion so the retry is one keystroke away. */
@@ -301,14 +302,59 @@ export class FixTargetUnknownError extends UltimateError {
   }
 }
 
-// The build and bundle refusals live in `build-errors.ts` (split at the 500-line ceiling); re-exported
-// here so every existing `from './errors'` import keeps resolving.
-export type { FrameworkScriptKind } from './build-errors';
-export {
-  BuildEntryMissingError,
-  FrameworkScriptBuildFailedError,
-  IslandBuildFailedError,
-} from './build-errors';
+/**
+ * A client entry would not compile. `X_BUILD_FAILED`, not a code of its own: an island is a bundle
+ * entry point like any other, and the target's own logs are what says which line. The fix builds
+ * exactly that one file, so the next message an author reads is the compiler's and not the CLI's.
+ */
+export class IslandBuildFailedError extends UltimateError {
+  constructor(input: { file: string; logs: string }) {
+    super({
+      code: 'X_BUILD_FAILED',
+      cause: `${input.file} is an island entry point and would not bundle: ${input.logs}`,
+      fix: `bun build --target browser ${input.file}`,
+    });
+  }
+}
+
+/** Which framework script a page ships: the sync worker, the page boot, or the client router. */
+export type FrameworkScriptKind = 'sync worker' | 'page boot' | 'client router';
+
+/**
+ * One of the page's framework scripts would not bundle. Same code as an island: "a browser entry
+ * the framework builds did not build" is one condition, and the entry here is framework code, not
+ * the app's — the cause names WHICH script, so the reader knows what the page is now missing.
+ */
+export class FrameworkScriptBuildFailedError extends UltimateError {
+  constructor(input: { what: FrameworkScriptKind; entry: string; logs: string }) {
+    super({
+      code: 'X_BUILD_FAILED',
+      cause: `the ${input.what} (${input.entry}) would not bundle for the browser: ${input.logs}`,
+      fix: `bun build --target browser --format iife ${quoteArg(input.entry)}`,
+    });
+  }
+}
+
+/**
+ * A static build over an app whose modules did not all import. The route registry is filled BY the
+ * import, so a page whose module threw is not skipped but absent — and an export without it, with
+ * `x build` green, is a deploy that deletes a page. The `manifest` step owns load findings
+ * (`load-findings.ts`), so the fix is the command that lists every one with its own fix.
+ */
+export class PrerenderLoadFailedError extends UltimateError {
+  constructor(findings: readonly Finding[]) {
+    const listed = findings.map((finding) =>
+      finding.at === undefined
+        ? `${finding.code} ${finding.cause}`
+        : `${finding.at}: ${finding.code} ${finding.cause}`,
+    );
+    super({
+      code: 'X_BUILD_FAILED',
+      cause: `the static export renders the routes the app's modules register, and ${findings.length} module load finding(s) left it short: ${listed.join('; ')}`,
+      fix: 'x verify --only manifest --json',
+    });
+  }
+}
 
 /**
  * `ROLE` selects what a container is. One image runs every role, so a typo is a process that would
@@ -363,36 +409,6 @@ export class PortInvalidError extends UltimateError {
   }
 }
 
-/**
- * `x env` was run in an app whose `app.config.ts` exports no `envSchema`. Not a silent success:
- * writing a `.env.example` with no variables in it, or reporting "0 declared variables, all
- * present", both read as a working environment declaration to whoever runs the command next.
- *
- * `X_CONFIG_INVALID` is core's code for "a configuration this process cannot boot on — env or
- * `app.config.ts`", which is exactly this; the CLI names it in `CLI_BORROWED_ERROR_CODES` rather
- * than minting a synonym.
- */
-export class EnvSchemaMissingError extends UltimateError {
-  constructor(input: { subcommand: string }) {
-    super({
-      code: 'X_CONFIG_INVALID',
-      cause: `x env ${input.subcommand} needs the env declaration, and app.config.ts exports no "envSchema"`,
-      fix: "add to app.config.ts: export const envSchema = { DATABASE_URL: { type: 'url', description: 'Postgres connection URL' } } satisfies EnvSchema; export const env = defineEnv(envSchema);",
-    });
-  }
-}
-
-/** An interface-complete command path whose remote/native half is not written yet. */
-export class CliNotImplementedError extends UltimateError {
-  constructor(input: { feature: string; fix: string }) {
-    super({
-      code: 'X_NOT_IMPLEMENTED',
-      cause: `${input.feature} is not implemented in this build`,
-      fix: input.fix,
-    });
-  }
-}
-
 /**
  * The process could not obtain a storage disk to write to.
  *
@@ -432,48 +448,3 @@ export class LocalDiskUnsafeError extends UltimateError {
     });
   }
 }
-
-/**
- * `x secrets edit` decrypts into a buffer and hands it to `$EDITOR`. There is no fallback editor:
- * guessing one and opening a decrypted file in it is the last place a surprise belongs.
- */
-export class SecretsEditorMissingError extends UltimateError {
-  constructor(input: { vars: readonly string[] }) {
-    super({
-      code: 'X_SECRETS_EDITOR_MISSING',
-      cause: `x secrets edit opens the decrypted secrets in an editor and none of ${input.vars.join(', ')} is set`,
-      fix: 'EDITOR=nano x secrets edit',
-    });
-  }
-}
-
-/**
- * The editor exited non-zero — a crash, or a deliberate abort. The buffer is discarded either way
- * and the committed file is left exactly as it was: resealing a buffer whose editor failed would
- * commit whatever half-written state the crash left behind.
- */
-export class SecretsEditFailedError extends UltimateError {
-  constructor(input: { editor: string; code: number }) {
-    super({
-      code: 'X_SECRETS_EDIT_FAILED',
-      cause: `"${input.editor}" exited ${input.code}, so the decrypted buffer was discarded and the committed secrets file was not rewritten`,
-      fix: 'x secrets edit',
-    });
-  }
-}
-
-/**
- * `x secrets init` would overwrite a file that already exists. `X_GENERATE_CONFLICT` is this
- * package's own code for exactly that, and a second name for "a generator would clobber something"
- * is the duplication the code registry exists to prevent. Losing a master key is unrecoverable —
- * the committed file it opens is then ciphertext nobody can read again.
- */
-export class SecretsExistsError extends UltimateError {
-  constructor(input: { path: string; fix: string }) {
-    super({
-      code: 'X_GENERATE_CONFLICT',
-      cause: `${input.path} already exists, and x secrets init would replace it`,
-      fix: input.fix,
-    });
-  }
-}

package/src/framework-schema-apply.ts

@@ -0,0 +1,78 @@
+// The two ways a boot meets the framework schema (plan 101, s1-con #5): `applyLockedSchema` runs the
+// DDL in ONE transaction behind the migration advisory lock with a bounded `lock_timeout`, then
+// stamps the build; `verifySchema` runs no DDL and refuses a database this build was never applied
+// to. Which boot takes which is `runtime-queue.ts`'s `SchemaMode`.
+
+import { frameworkVersion, logger } from '@ultimat3/core';
+import type { DbClient } from '@ultimat3/db';
+import {
+  literal,
+  MIGRATION_LOCK_KEY,
+  MIGRATION_LOCK_WAIT_MS,
+  poolProfileFor,
+  raw,
+  withTransaction,
+} from '@ultimat3/db';
+import { applyFrameworkSchema } from './framework-schema';
+import {
+  FrameworkSchemaUnappliedError,
+  frameworkSchemaHash,
+  nextStamp,
+  parseStamp,
+  STAMP_RELATION,
+  type StampEntry,
+  stampVerdict,
+} from './framework-schema-stamp';
+
+const thisBuild = (): StampEntry => ({
+  version: frameworkVersion(),
+  schema: frameworkSchemaHash(),
+});
+
+/** The stamp as the catalog holds it; `null` when the relation or its comment is absent. */
+async function readStamp(client: DbClient): Promise<string | null> {
+  const rows = await client.query<{ readonly stamp: string | null }>(
+    raw(`select obj_description(to_regclass('${STAMP_RELATION}'), 'pg_class') as stamp`),
+  );
+  return rows[0]?.stamp ?? null;
+}
+
+/**
+ * The migration lock, not a lock of its own: a second migrator — another `ROLE=migrate` pod, an
+ * `x db migrate` — waits behind this one instead of racing its `create table`s into `23505`. A
+ * transaction-scoped lock (`pg_advisory_xact_lock`), so no pinned session: COMMIT releases it.
+ *
+ * Two `lock_timeout`s: the lock wait is the migrator's own (`MIGRATION_LOCK_WAIT_MS`), and every
+ * DDL statement after it is the migrate pool's (`poolProfileFor('migrate')`), so an `alter table`
+ * behind an open transaction fails in seconds rather than queueing every enqueue behind it.
+ */
+export async function applyLockedSchema(client: DbClient): Promise<void> {
+  await withTransaction(
+    async (tx) => {
+      await tx.execute(raw(`set local lock_timeout = ${Math.round(MIGRATION_LOCK_WAIT_MS)}`));
+      await tx.execute(raw(`select pg_advisory_xact_lock(${MIGRATION_LOCK_KEY})`));
+      const ddlTimeoutMs = Math.round(poolProfileFor('migrate').lockTimeoutMs);
+      await tx.execute(raw(`set local lock_timeout = ${ddlTimeoutMs}`));
+      await applyFrameworkSchema((statement) => tx.execute(raw(statement)));
+      const stamp = nextStamp(await readStamp(tx), thisBuild());
+      await tx.execute(raw(`comment on table ${STAMP_RELATION} is ${literal(stamp).text}`));
+    },
+    { client },
+  );
+}
+
+/**
+ * One catalog read. A build absent from the stamp is refused with the command that applies it; a
+ * fleet straddling a major is reported once and served — refusing it would crash-loop the old pods
+ * of every rolling deploy across a breaking release.
+ */
+export async function verifySchema(client: DbClient): Promise<void> {
+  const mine = thisBuild();
+  const verdict = stampVerdict(parseStamp(await readStamp(client)), mine);
+  if (!verdict.applied) throw new FrameworkSchemaUnappliedError({ mine, newest: verdict.newest });
+  if (verdict.skew === undefined) return;
+  logger.warn('ultimate framework major skew', {
+    cause: `this process runs ${mine.version} and the database's framework schema was last applied by ${verdict.skew.version}: a fleet across a major boundary is mid-rollout or half rolled back`,
+    fix: 'kubectl rollout status deployment --selector app.kubernetes.io/component=web',
+  });
+}

package/src/framework-schema-stamp.ts

@@ -0,0 +1,96 @@
+// Which builds have applied the framework schema to this database: a stamp `ROLE=migrate` leaves
+// in `x_jobs`' table comment, and the verdict a serving role reads from it instead of running DDL
+// itself (plan 101, s1-con #5). Pure: the statements live in `framework-schema-apply.ts`.
+
+import { UltimateError } from '@ultimat3/core';
+import { FRAMEWORK_SCHEMA } from './framework-schema';
+
+/**
+ * The relation that carries the stamp. A comment, not a table: a new framework table moves every
+ * app's committed schema dump (`packages/db/schema/framework/`), and a comment is in none of them.
+ */
+export const STAMP_RELATION = 'x_jobs';
+
+/** The first line of a stamp — what tells it apart from a comment someone else wrote. */
+const STAMP_HEADER = 'ultimate-framework-schema';
+
+/** Enough for a rolling deploy and its rollback, small enough to stay one readable comment. */
+const STAMP_KEEP = 16;
+
+export interface StampEntry {
+  readonly version: string;
+  readonly schema: string;
+}
+
+/** This build's DDL, as one short hash: two builds with the same DDL are the same schema. */
+export function frameworkSchemaHash(): string {
+  const hasher = new Bun.CryptoHasher('sha256');
+  for (const entry of FRAMEWORK_SCHEMA) for (const ddl of entry.ddl) hasher.update(ddl);
+  return hasher.digest('hex').slice(0, 16);
+}
+
+/** Every build a stamp records, newest first. Anything that is not a stamp records none. */
+export function parseStamp(comment: string | null | undefined): readonly StampEntry[] {
+  if (typeof comment !== 'string') return [];
+  const [header, ...lines] = comment.split('\n');
+  if (header !== STAMP_HEADER) return [];
+  return lines.flatMap((line) => {
+    const [version, schema] = line.trim().split(' ');
+    return version !== undefined &&
+      /^[0-9A-Za-z.+-]{1,64}$/.test(version) &&
+      schema !== undefined &&
+      /^[0-9a-f]{16}$/.test(schema)
+      ? [{ version, schema }]
+      : [];
+  });
+}
+
+/** The stamp after `mine` applied: it first, every other build kept, the oldest dropped. */
+export function nextStamp(previous: string | null | undefined, mine: StampEntry): string {
+  const kept = parseStamp(previous).filter((entry) => entry.schema !== mine.schema);
+  const entries = [mine, ...kept].slice(0, STAMP_KEEP);
+  return [STAMP_HEADER, ...entries.map((entry) => `${entry.version} ${entry.schema}`)].join('\n');
+}
+
+const majorOf = (version: string): string => version.split('.')[0] ?? version;
+
+export type StampVerdict =
+  | { readonly applied: true; readonly skew?: StampEntry }
+  | { readonly applied: false; readonly newest?: StampEntry };
+
+/**
+ * Applied when this build's hash is anywhere in the stamp: an old pod restarting mid-rollout finds
+ * its own build there, behind the new one. `skew` is the newest build when its MAJOR differs from
+ * this process's — a fleet straddling a breaking release, which a boot reports and never refuses.
+ */
+export function stampVerdict(entries: readonly StampEntry[], mine: StampEntry): StampVerdict {
+  const newest = entries[0];
+  if (!entries.some((entry) => entry.schema === mine.schema)) {
+    return newest === undefined ? { applied: false } : { applied: false, newest };
+  }
+  return newest !== undefined && majorOf(newest.version) !== majorOf(mine.version)
+    ? { applied: true, skew: newest }
+    : { applied: true };
+}
+
+/** A serving role over a database its build's framework tables were never applied to. */
+export class FrameworkSchemaUnappliedError extends UltimateError {
+  constructor(input: { readonly mine: StampEntry; readonly newest: StampEntry | undefined }) {
+    super({
+      code: 'X_FRAMEWORK_SCHEMA_UNAPPLIED',
+      cause:
+        `this build (${input.mine.version}, framework schema ${input.mine.schema}) has not been applied ` +
+        `to this database — ${
+          input.newest === undefined
+            ? `${STAMP_RELATION} carries no stamp, so no ROLE=migrate of this release ran`
+            : `the newest applied build is ${input.newest.version} (${input.newest.schema})`
+        }. A serving role verifies and never runs DDL: the migrate step must run first`,
+      fix: 'x db migrate',
+      meta: {
+        version: input.mine.version,
+        schema: input.mine.schema,
+        ...(input.newest === undefined ? {} : { newest: { ...input.newest } }),
+      },
+    });
+  }
+}

package/src/framework-schema.ts

@@ -7,10 +7,15 @@
 // the one code path that needs it, and it surfaces as a Postgres `42P01` from inside a worker.
 
 import { SQL_AUDIT_TABLE, SQL_IDEMPOTENCY_TABLE } from '@ultimat3/action';
+import { ADMIN_AUDIT_TABLE, SQL_ADMIN_AUDIT_TABLE } from '@ultimat3/admin/schema';
 import { AUTH_TABLE_NAMES, AUTH_TABLES, SQL_AUTH_LIMIT_TABLES } from '@ultimat3/auth';
 import { SQL_RATE_LIMIT_TABLE } from '@ultimat3/http';
 import { SQL_JOBS_TABLE } from '@ultimat3/jobs';
-import { SQL_NOTIFY_DELIVERIES_TABLE, SQL_NOTIFY_INBOX_TABLE } from '@ultimat3/notify';
+import {
+  SQL_NOTIFY_DELIVERIES_TABLE,
+  SQL_NOTIFY_DIGESTS_TABLE,
+  SQL_NOTIFY_INBOX_TABLE,
+} from '@ultimat3/notify';
 import { FrameworkSchemaFailedError } from './schema-errors';
 
 export interface FrameworkSchema {
@@ -49,6 +54,9 @@ export const FRAMEWORK_SCHEMA: readonly FrameworkSchema[] = Object.freeze([
       'x_scheduler_leader',
       'x_job_leases',
       'x_job_events',
+      'x_job_pauses',
+      'x_job_workers',
+      'x_job_counters',
     ]),
     ddl: Object.freeze([SQL_JOBS_TABLE]),
   }),
@@ -72,7 +80,7 @@ export const FRAMEWORK_SCHEMA: readonly FrameworkSchema[] = Object.freeze([
   }),
   Object.freeze({
     pkg: '@ultimat3/auth',
-    tables: Object.freeze(['x_auth_failures', 'x_auth_lockouts']),
+    tables: Object.freeze(['x_auth_lockouts']),
     ddl: Object.freeze([SQL_AUTH_LIMIT_TABLES]),
   }),
   /**
@@ -109,6 +117,24 @@ export const FRAMEWORK_SCHEMA: readonly FrameworkSchema[] = Object.freeze([
     tables: Object.freeze(['x_notify_inbox']),
     ddl: Object.freeze([SQL_NOTIFY_INBOX_TABLE]),
   }),
+  // `createPgDigestStore`'s windows. Installed whether or not the app picks that store, for the
+  // reason every notify row is: `setNotifyStores` is the app's boot line and runs after this one.
+  Object.freeze({
+    pkg: '@ultimat3/notify',
+    tables: Object.freeze(['x_notify_digests']),
+    ddl: Object.freeze([SQL_NOTIFY_DIGESTS_TABLE]),
+  }),
+  /**
+   * The admin's durable audit trail — what `postgresAuditLog()` writes and every detail page's
+   * history card reads. Without this row an app that chose the durable log met `42P01` on the
+   * first audited request. Imported through `@ultimat3/admin/schema`, a leaf module: the DDL is
+   * on every role's boot path, and not one admin screen is (`serve-graph.test.ts`).
+   */
+  Object.freeze({
+    pkg: '@ultimat3/admin',
+    tables: Object.freeze([ADMIN_AUDIT_TABLE]),
+    ddl: Object.freeze([SQL_ADMIN_AUDIT_TABLE]),
+  }),
 ]);
 
 /** Every relation this boot creates, flattened. */