@ultimat3/cli 7.0.0 → 9.0.0

package/src/templates/guard-untranslated-string.ts

@@ -0,0 +1,138 @@
+// The `untranslated-string` guard `x new` ships: no user-facing string is typed into a page.
+// `AGENTS.md` has always stated the rule and NOTHING enforced it — a hardcoded JSX string sitting
+// beside a `t()` call in a scaffolded page was green on `x verify`, and `x i18n check` cannot see
+// it either: a literal that is in no catalog is a literal the catalog audit has no key for.
+
+import { guardCode } from './guard';
+import type { GeneratedFile } from './naming';
+
+/**
+ * Derived from the guard's name, never written as a literal — the same rule `x g guard` follows.
+ * An `X_*` literal in framework source is a FRAMEWORK code: `error-catalog.test.ts` refuses one the
+ * registry does not hold, and `wiki/Error-Codes.md` would owe it a row. The APP owns the codes its
+ * own conventions raise, so this one is spelled by the file it lands in and nowhere else.
+ */
+const NAME = 'untranslated-string';
+const CODE = guardCode(NAME);
+
+const source =
+  (): string => `// untranslated-string: every user-facing string on a rendered surface goes through \`t()\`.
+// \`x verify\` discovers every file in \`guards/\` and runs its \`guard\` inside the \`boundaries\`
+// step — nothing registers this file, so nothing can forget to.
+
+import type { Finding, Guard } from '@ultimat3/cli';
+
+/** The app owns the codes its own conventions raise — this one is named for the guard. */
+const CODE = '${CODE}';
+
+/**
+ * \`<tag …>text</tag>\`, matched on the CLOSING tag rather than on the next \`<\`.
+ *
+ * That is the whole reason this rule can run over TypeScript at all: \`createSignal<State>('idle')\`
+ * is a \`>\` followed by prose-shaped source, and a pattern reading to the next \`<\` reports every
+ * generic in the file. A closing tag that names the same element cannot be a type argument.
+ *
+ * Only the INNERMOST element matches — the content class excludes \`<\` and \`>\` — which is what the
+ * rule wants: a parent whose children are elements has no text of its own.
+ */
+const ELEMENT = /<([A-Za-z][\\w.:-]*)(?:\\s[^<>]*)?>([^<>]*?)<\\/\\1>/g;
+/** A \`{…}\` child is an expression — \`{t('key')}\`, \`{props.row.title}\` — never typed prose. */
+const EXPRESSION = /\\{[^{}]*\\}/g;
+/** Two word characters in a row. One is \`&\`, \`×\`, an initial — never a sentence. */
+const PROSE = /[\\p{L}\\p{N}]{2,}/u;
+
+export interface SourceFile {
+  /** App-root-relative POSIX path, so the finding names the file an author opens. */
+  readonly path: string;
+  readonly source: string;
+}
+
+/** Comments blanked IN PLACE — not deleted — so a reported line number still points at the source. */
+const blank = (text: string): string =>
+  text
+    .replaceAll(/\\/\\*[\\s\\S]*?\\*\\//g, (match) => match.replaceAll(/[^\\n]/g, ' '))
+    .replaceAll(/(?<![:\\w])\\/\\/[^\\n]*/g, (match) => ' '.repeat(match.length));
+
+const lineOf = (text: string, index: number): number => text.slice(0, index).split('\\n').length;
+
+/** Pure — the caller does the I/O — so the rule is testable without a filesystem. */
+export function untranslatedStrings(files: readonly SourceFile[]): readonly Finding[] {
+  const findings: Finding[] = [];
+  for (const file of files) {
+    const text = blank(file.source);
+    for (const match of text.matchAll(ELEMENT)) {
+      const typed = (match[2] ?? '').replaceAll(EXPRESSION, ' ').trim();
+      if (!PROSE.test(typed)) continue;
+      findings.push({
+        code: CODE,
+        cause: \`\${file.path}:\${lineOf(text, match.index)} renders the typed string "\${typed}" inside <\${match[1] ?? 'element'}> — it is in no catalog, so every locale but the one it was typed in reads it verbatim\`,
+        fix: \`add a key for "\${typed}" to packages/i18n/catalogs/en.json, render it as {t('…')} in \${file.path}, then: x i18n check\`,
+        at: file.path,
+      });
+    }
+  }
+  return findings;
+}
+
+export const guard: Guard = {
+  summary: 'a rendered string comes from t(), never typed into the page',
+  async check(root) {
+    const files: SourceFile[] = [];
+    // Every rendered surface: an app's \`site/\` and \`app/\`, and the shared components under
+    // \`packages/*/src\` — \`x new\` scaffolds a \`packages/ui\` whose components render to a user, so
+    // a hardcoded string there used to be green. \`api/\` renders nothing and \`shared/\` is a leaf of
+    // helpers; \`packages/*/dist\` is a build output, not source.
+    //
+    // TWO globs, never one with a leading \`{a,b}\` group: \`Bun.Glob.scan()\` matches nothing at all
+    // for a pattern that starts with a brace group — measured — so folding these into one line
+    // silently turns the guard off, which is worse than the hole it closes.
+    for (const pattern of ['apps/*/{site,app}/**/*.tsx', 'packages/*/src/**/*.tsx']) {
+      for await (const entry of new Bun.Glob(pattern).scan({ cwd: root, absolute: false })) {
+        const path = entry.split('\\\\').join('/');
+        if (path.includes('node_modules/') || /\\.test\\.tsx?$/.test(path)) continue;
+        files.push({ path, source: await Bun.file(\`\${root}/\${path}\`).text() });
+      }
+    }
+    return untranslatedStrings(files);
+  },
+};
+`;
+
+const test =
+  (): string => `// The rule, driven directly. Failure case first: a guard whose rule silently stopped matching is
+// a green gate over the convention it was written to enforce.
+
+import { expect, unitTest } from '@ultimat3/testing';
+import { untranslatedStrings } from './untranslated-string';
+
+const file = (source: string) => [{ path: 'apps/web/site/page.tsx', source }];
+
+unitTest('a typed JSX string is refused, and the finding quotes it', () => {
+  const findings = untranslatedStrings(file('<h1>Welcome back</h1>'));
+  expect(findings).toHaveLength(1);
+  expect(findings[0]?.code).toBe('${CODE}');
+  expect(findings[0]?.cause).toContain('Welcome back');
+});
+
+unitTest('a t() child satisfies it, and so does any other expression', () => {
+  expect(untranslatedStrings(file("<h1>{t('site.home.title')}</h1>"))).toEqual([]);
+  expect(untranslatedStrings(file('<li class={styles.item}>{row.title}</li>'))).toEqual([]);
+});
+
+// The reason the rule reads a CLOSING tag: a generic type argument is a > followed by source that
+// looks exactly like prose, and a pattern reading to the next < reports every one of them.
+unitTest('a generic type argument is not a JSX text node', () => {
+  const generic = "const [state, setState] = createSignal<SaveState>('idle');\\nconst n = 1;";
+  expect(untranslatedStrings(file(generic))).toEqual([]);
+});
+
+unitTest('one word character is a symbol, not a sentence', () => {
+  expect(untranslatedStrings(file('<span>&</span>'))).toEqual([]);
+});
+`;
+
+/** `guards/untranslated-string.ts` and its test. The directory is the registration. */
+export const untranslatedStringGuardFiles = (): readonly GeneratedFile[] => [
+  { path: 'guards/untranslated-string.ts', contents: source() },
+  { path: 'guards/untranslated-string.test.ts', contents: test() },
+];

package/src/templates/guard-unzoned-date.ts

@@ -0,0 +1,142 @@
+// The `unzoned-date` guard `x new` ships: no date is formatted without an explicit IANA zone.
+// `AGENTS.md` has always stated the rule and NOTHING enforced it — `toLocaleDateString('en-US')`
+// in a scaffolded page was green on `x verify`, and it renders the SERVER's zone, so the same row
+// reads as two different days depending on which container answered.
+
+import { guardCode } from './guard';
+import type { GeneratedFile } from './naming';
+
+/**
+ * Derived from the guard's name, never written as a literal — the same rule `x g guard` follows.
+ * An `X_*` literal in framework source is a FRAMEWORK code: `error-catalog.test.ts` refuses one the
+ * registry does not hold, and `wiki/Error-Codes.md` would owe it a row. The APP owns the codes its
+ * own conventions raise, so this one is spelled by the file it lands in and nowhere else.
+ */
+const NAME = 'unzoned-date';
+const CODE = guardCode(NAME);
+
+const source =
+  (): string => `// unzoned-date: a date is stored in UTC and formatted with an explicit IANA zone, never with the
+// host's ambient one. \`x verify\` discovers every file in \`guards/\` and runs its \`guard\` inside
+// the \`boundaries\` step — nothing registers this file, so nothing can forget to.
+
+import type { Finding, Guard } from '@ultimat3/cli';
+
+/** The app owns the codes its own conventions raise — this one is named for the guard. */
+const CODE = '${CODE}';
+
+/** Every call whose output depends on a zone. The \`(\` is the start of the argument list. */
+const FORMATTER = /(?:\\.toLocale(?:Date|Time)?String|Intl\\.DateTimeFormat)\\s*\\(/g;
+
+export interface SourceFile {
+  /** App-root-relative POSIX path, so the finding names the file an author opens. */
+  readonly path: string;
+  readonly source: string;
+}
+
+/**
+ * Comments blanked IN PLACE — not deleted — so the line number a finding reports still points at
+ * the source line. What it does not blank is a string body: a call spelled inside a quoted string
+ * is reported, which is the one false positive this rule can produce and the reason its own test
+ * lives in \`guards/\`, which nothing here scans.
+ */
+const blank = (text: string): string =>
+  text
+    .replaceAll(/\\/\\*[\\s\\S]*?\\*\\//g, (match) => match.replaceAll(/[^\\n]/g, ' '))
+    .replaceAll(/(?<![:\\w])\\/\\/[^\\n]*/g, (match) => ' '.repeat(match.length));
+
+/**
+ * The call's own argument list, from its \`(\` to the \`)\` that closes it. Depth-counted rather
+ * than "up to the next \`)\`": \`toLocaleDateString(locale, { timeZone: zoneFor(x) })\` closes twice
+ * before the one that ends the call, and reading only the first would report a zoned call.
+ */
+function argumentsOf(text: string, open: number): string {
+  let depth = 0;
+  for (let index = open; index < text.length; index += 1) {
+    const char = text[index];
+    if (char === '(') depth += 1;
+    else if (char === ')') {
+      depth -= 1;
+      if (depth === 0) return text.slice(open + 1, index);
+    }
+  }
+  return text.slice(open + 1);
+}
+
+const lineOf = (text: string, index: number): number => text.slice(0, index).split('\\n').length;
+
+/** Pure — the caller does the I/O — so the rule is testable without a filesystem. */
+export function unzonedDates(files: readonly SourceFile[]): readonly Finding[] {
+  const findings: Finding[] = [];
+  for (const file of files) {
+    const text = blank(file.source);
+    for (const match of text.matchAll(FORMATTER)) {
+      const open = match.index + match[0].length - 1;
+      if (argumentsOf(text, open).includes('timeZone')) continue;
+      const line = lineOf(text, match.index);
+      findings.push({
+        code: CODE,
+        cause: \`\${file.path}:\${line} calls \${match[0].trim()}) with no timeZone — it formats in whatever zone the process happens to run in, so one row reads as two different days across two containers\`,
+        fix: \`pass an explicit IANA zone in \${file.path} — toLocaleDateString(locale, { timeZone: 'UTC' }) — then: x verify\`,
+        at: file.path,
+      });
+    }
+  }
+  return findings;
+}
+
+export const guard: Guard = {
+  summary: 'a date is never formatted without an explicit IANA time zone',
+  async check(root) {
+    const files: SourceFile[] = [];
+    for await (const entry of new Bun.Glob('{apps,packages}/**/*.{ts,tsx}').scan({
+      cwd: root,
+      absolute: false,
+    })) {
+      const path = entry.split('\\\\').join('/');
+      // A test's subject is often the wrong shape on purpose, and \`node_modules\` is not this
+      // app's source. Neither exclusion hides a rendered date from a user.
+      if (path.includes('node_modules/') || /\\.(?:test|d)\\.tsx?$/.test(path)) continue;
+      files.push({ path, source: await Bun.file(\`\${root}/\${path}\`).text() });
+    }
+    return unzonedDates(files);
+  },
+};
+`;
+
+const test =
+  (): string => `// The rule, driven directly. Failure case first: a guard whose rule silently stopped matching is
+// a green gate over the convention it was written to enforce.
+
+import { expect, unitTest } from '@ultimat3/testing';
+import { unzonedDates } from './unzoned-date';
+
+const file = (source: string) => [{ path: 'apps/web/app/dashboard/page.tsx', source }];
+
+unitTest('toLocaleDateString with no timeZone is refused', () => {
+  const findings = unzonedDates(file("const shown = at.toLocaleDateString('en-US');"));
+  expect(findings).toHaveLength(1);
+  expect(findings[0]?.code).toBe('${CODE}');
+  expect(findings[0]?.fix).toContain('timeZone');
+});
+
+unitTest('an explicit zone satisfies it, even nested behind another call', () => {
+  const zoned = "at.toLocaleDateString('en-US', { timeZone: zoneFor(actor) });";
+  expect(unzonedDates(file(zoned))).toEqual([]);
+});
+
+unitTest('Intl.DateTimeFormat and toLocaleTimeString are the same rule', () => {
+  expect(unzonedDates(file("new Intl.DateTimeFormat('en-US').format(at);"))).toHaveLength(1);
+  expect(unzonedDates(file("at.toLocaleTimeString('en-US');"))).toHaveLength(1);
+});
+
+unitTest('a commented-out call is a note, not a call', () => {
+  expect(unzonedDates(file("// at.toLocaleDateString('en-US');"))).toEqual([]);
+});
+`;
+
+/** `guards/unzoned-date.ts` and its test. No index, no registry — the directory registers it. */
+export const unzonedDateGuardFiles = (): readonly GeneratedFile[] => [
+  { path: 'guards/unzoned-date.ts', contents: source() },
+  { path: 'guards/unzoned-date.test.ts', contents: test() },
+];

package/src/templates/index.ts

@@ -39,6 +39,9 @@ export { claudeAgentFiles } from './scaffold-claude-agents';
 export { claudeCommandFiles } from './scaffold-claude-commands';
 export { containerFiles } from './scaffold-container';
 export { docsFiles, EXECUTABLE_FILES } from './scaffold-docs';
+export { entryFiles } from './scaffold-entries';
+// The four guards `x new` ships, distinct from `guardFiles` above, which is `x g guard <name>`.
+export { scaffoldGuardFiles } from './scaffold-guards';
 export { i18nIndex } from './scaffold-i18n';
 export { repoFiles } from './scaffold-repo';
 export type { SliceModule } from './slice-foundation';

package/src/templates/island.ts

@@ -78,7 +78,8 @@ export function mount(el: HTMLElement, props: ${Name}Props): void {
 `;
 };
 
-const islandStyle = (): string => `// Semantic tokens only — a raw hex here is a dark-theme bug and
+const islandStyle =
+  (): string => `// Semantic tokens only — a raw hex here is refused by the boundaries step, not by lint — a dark-theme bug and
 // a lint failure. Scoped by the island build, with the class names the server hashed.
 @use '@ultimat3/ui/tokens' as tokens;
 

package/src/templates/route.ts

@@ -138,7 +138,7 @@ export function ${name}Page() {${translatorBinding(module)}
 };
 
 const styleSource =
-  (): string => `// Semantic tokens only — a raw hex here is a dark-theme bug and a lint failure.
+  (): string => `// Semantic tokens only — a raw hex here is refused by the boundaries step (guards/raw-colour.ts), not by lint — a dark-theme bug in every scheme but the one it was written in.
 @use '@ultimat3/ui/tokens' as tokens;
 
 .page {

package/src/templates/scaffold-app.ts

@@ -4,6 +4,7 @@
 
 import type { GeneratedFile, NameSet } from './naming';
 import { apiFiles } from './scaffold-api';
+import { entryFiles } from './scaffold-entries';
 import { icon } from './scaffold-icon';
 import { rolesFiles } from './scaffold-roles';
 
@@ -349,86 +350,6 @@ export function AdminHome() {
 }
 `;
 
-// The two entry files a deploy needs. Both are deliberately thin: which role a container is, which
-// port it binds, how it drains and what a static build enumerates are the framework's answers, so
-// an upgrade moves them without a codemod in every app that ever shipped.
-
-const server =
-  (): string => `// The production entry. \`docker/Dockerfile\` starts this, and \`x build --target binary\` compiles it.
-// ROLE selects what this process is — web, sync, worker, scheduler, replicator, or migrate, which
-// applies the migrations and exits. PORT is bound on every interface, because a container bound to
-// localhost is unreachable through its own port mapping.
-
-import { join } from 'node:path';
-import { runRole } from '@ultimat3/cli';
-
-// MORE THAN ONE REPLICA? Add these two lines, above \`runRole\`:
-//
-//   import { configureIdempotency } from '@ultimat3/action';
-//   configureIdempotency({ scope: 'shared' });
-//
-// \`idempotent: true\` on an action promises that a retry does not repeat the work. Under the
-// process-scoped default that promise holds inside ONE process — a client retrying
-// \`POST /api/payments/charge\` after a timeout lands on another replica, which has never seen the
-// key, and charges the card twice, silently, with \`x verify\` green. Declaring \`'shared'\` is what
-// makes that a boot error (\`X_IDEMPOTENCY_NOT_SHARED\`) unless a shared store is installed.
-// \`runRole\` installs the Postgres one for you, on the connection it resolved from \`DATABASE_URL\`,
-// so the declaration is all this app owes. It must run before \`runRole\` imports the actions.
-
-/**
- * Where the app is. From this file normally — the image's WORKDIR is not the app root's business.
- * A \`--compile\` binary is the exception: its \`import.meta.dir\` is Bun's virtual filesystem, which
- * holds this module's bundled imports and none of the app's source, and the framework's registries
- * are filled by scanning that source at boot. So a binary reads its root from the directory it is
- * started in — it is a launcher for an app tree, not a self-contained copy of one.
- */
-const root = import.meta.dir.startsWith('/$bunfs')
-  ? process.cwd()
-  : join(import.meta.dir, '..', '..');
-
-// Guarded, because the framework's module scan imports every file under apps/*/ to fill its
-// registries — an unguarded boot would start a server inside \`x verify\`.
-if (import.meta.main) {
-  await runRole({ root, env: Bun.env });
-}
-`;
-
-const prerender =
-  (): string => `// The static entry. \`x build --target static\` runs this with \`--out <dir>\` and it writes one HTML
-// file per \`render: 'static'\` route — a CDN or an object store then serves site/ with no process
-// behind it. Every other render mode needs a running app and is reported as skipped, never emitted.
-//
-// Skipped is not unweighed: a route that declares a \`budget:\` is rendered in memory and measured
-// whatever its mode, so \`x verify\`'s \`budgets\` step has a number for it. \`unmeasured\` is the list
-// this build could not render — each one is an X_BUDGET_UNMEASURED at the gate, and this is where
-// the reason is.
-//
-// It writes the whole of \`pages\` and \`skipped\`, never a COUNT of either. A count is what let a
-// partial artifact read as a complete one: someone pointed a screenshot tool at \`.x/static\` and
-// filed "the island did not mount" against a route that had never been emitted (issue #242). Each
-// skipped route carries its own \`reason\` and \`why\`, and \`report\` is where the same inventory
-// landed on disk — which is what \`x build --target static --json\` reads back.
-
-import { join } from 'node:path';
-import { prerenderSite } from '@ultimat3/cli';
-
-const root = join(import.meta.dir, '..', '..');
-const flag = Bun.argv.indexOf('--out');
-const out = (flag === -1 ? undefined : Bun.argv[flag + 1]) ?? join(root, '.x', 'static');
-// SITE_ORIGIN is what canonical and og:url are built from; the default is only ever a local build.
-// Property access, not \`Bun.env['SITE_ORIGIN']\`: the scaffolded tsconfig does not set
-// \`noPropertyAccessFromIndexSignature\`, so the bracket form is the one biome's useLiteralKeys
-// reports — a diagnostic in an app's first lint run over a file the app never wrote.
-const origin = Bun.env.SITE_ORIGIN;
-
-if (import.meta.main) {
-  const report = await prerenderSite({ root, out, ...(origin === undefined ? {} : { origin }) });
-  await Bun.stdout.write(
-    \`\${JSON.stringify({ ok: true, out: report.out, emitted: report.pages, skipped: report.skipped, unmeasured: report.unmeasured, report: report.report })}\\n\`,
-  );
-}
-`;
-
 const placeholder = (surface: string, app: NameSet): string => `# ${surface}
 
 Placeholder. The monorepo shape exists now so adding ${surface} later is a new directory, not a
@@ -447,8 +368,8 @@ export function appFiles(app: NameSet, example: boolean): readonly GeneratedFile
   return [
     { path: 'apps/web/package.json', contents: webPackage(app) },
     { path: 'apps/web/tsconfig.json', contents: tsconfig() },
-    { path: 'apps/web/server.ts', contents: server() },
-    { path: 'apps/web/prerender.ts', contents: prerender() },
+    // The process a container starts and the artifact a CDN is handed — `scaffold-entries.ts`.
+    ...entryFiles(),
     { path: 'apps/web/site/icon.png', contents: icon() },
     { path: 'apps/web/site/page.tsx', contents: sitePage(app) },
     { path: 'apps/web/site/page.module.scss', contents: siteStyle() },

package/src/templates/scaffold-container.ts

@@ -52,8 +52,10 @@ ENV NODE_ENV=production \\
 # own port mapping, its load balancer and every health probe alike.
 EXPOSE 3000
 
-# Every role serves /healthz and /readyz. /readyz flips to 503 on SIGTERM *before* the socket
-# closes, so a rolling restart drains in-flight work instead of dropping it.
+# The probe for the roles that SERVE HTTP — \`web\` and \`sync\`. /readyz flips to 503 on SIGTERM
+# *before* the socket closes, so a rolling restart drains in-flight work instead of dropping it.
+# Every other role opens the scrape listener alone and never binds $PORT, so each one overrides
+# this in docker/docker-compose.prod.yml rather than reporting \`unhealthy\` for its whole life.
 HEALTHCHECK --interval=10s --timeout=3s --start-period=30s --retries=3 CMD \\
   bun --eval "fetch('http://127.0.0.1:'+(process.env.PORT||3000)+'/readyz').then(r=>process.exit(r.ok?0:1),()=>process.exit(1))"
 
@@ -120,6 +122,22 @@ x-image: &image
   depends_on:
     db: { condition: service_healthy }
 
+# The image's own HEALTHCHECK fetches \`/readyz\` on $PORT, and only \`web\` and \`sync\` open an HTTP
+# socket — every other role gets the scrape listener and nothing else. A service that inherits that
+# probe is fetching a port it never binds: it reports \`unhealthy\` for its whole life and anything
+# gated on it never starts. Probes follow the role here, exactly as they do in \`docker/helm\`.
+x-metrics-probe: &metrics-probe
+  test: ['CMD', 'bun', '--eval', "fetch('http://127.0.0.1:'+(process.env.METRICS_PORT||9090)+'/metrics').then(r=>process.exit(r.ok?0:1),()=>process.exit(1))"]
+  interval: 10s
+  timeout: 3s
+  start_period: 30s
+  retries: 3
+
+# Run-once services exit. A probe against an exited container reports \`unhealthy\` forever, and
+# nothing waits on their health — \`service_completed_successfully\` is what the others gate on.
+x-run-once-probe: &run-once-probe
+  disable: true
+
 services:
   db:
     image: postgres:17-alpine
@@ -138,6 +156,7 @@ services:
     <<: *image
     environment: [ROLE=migrate]
     restart: 'no'
+    healthcheck: *run-once-probe
 
   # Run-once, AFTER the new version serves. Deliberately NOT part of the release gate: a slow
   # UPDATE there holds the deploy open against a database still serving the previous version.
@@ -158,6 +177,7 @@ services:
       # listing this last would only look like "after". The image's HEALTHCHECK is what makes it true.
       web: { condition: service_healthy }
     restart: 'no'
+    healthcheck: *run-once-probe
 
   web:
     <<: *image
@@ -184,6 +204,7 @@ services:
     depends_on:
       db: { condition: service_healthy }
       migrate: { condition: service_completed_successfully }
+    healthcheck: *metrics-probe
     deploy: { replicas: 1 } # scales on queue depth
 
   scheduler:
@@ -192,7 +213,12 @@ services:
     depends_on:
       db: { condition: service_healthy }
       migrate: { condition: service_completed_successfully }
-    deploy: { replicas: 1 } # fixed 1; leadership is a Postgres advisory lock
+    # Fixed 1. Leadership is an EXPIRING LEASE ROW in \`x_scheduler_leader\` (dev-roles.ts,
+    # driver-pg-ddl.ts), NOT an advisory lock: that grant belongs to the session, not to the
+    # process — it outlives every transaction and no pooled node can renew it or prove it still
+    # holds one. A second instance is harmless but idle.
+    healthcheck: *metrics-probe
+    deploy: { replicas: 1 }
 
 volumes:
   pgdata:
@@ -208,7 +234,7 @@ nothing to rebuild between staging and production.
 | \`web\` | HTTP: pages, actions, assets | \`$PORT\` (default 3000) |
 | \`sync\` | websockets for live queries | \`$PORT + 1\` |
 | \`worker\` | the job queue | — |
-| \`scheduler\` | cron tasks; leadership is a Postgres advisory lock | — |
+| \`scheduler\` | cron tasks; leadership is an expiring lease row in \`x_scheduler_leader\` | — |
 | \`replicator\` | the logical replication slot, exactly one per database | — |
 | \`migrate\` | applies pending migrations and **exits** | — |
 

package/src/templates/scaffold-db-package.ts

@@ -1,6 +1,6 @@
-// The generated app's `packages/db`: the entity re-export list the migration generator reads and
-// the deterministic seed. No business logic — that is the package's own stated boundary, and it is
-// why `example` reaches only the two files describing the slice's table.
+// The generated app's `packages/db`: the entity re-export list the app's own modules import from
+// and the deterministic seed. No business logic — that is the package's own stated boundary, and it
+// is why `example` reaches only the two files describing the slice's table.
 //
 // No migration. `x db gen` is the ONE writer of `packages/db/migrations`, and a scaffold that hand-
 // wrote `0000_initial.sql` was a second one: it declared a `posts` table the generator had never
@@ -56,8 +56,16 @@ export * as schema from './schema';
 // never written, so each one ships its empty counterpart instead of a reference to a file that is
 // not there — `export { post } from …` alone made `x new --no-example` an app that cannot compile.
 
-const SCHEMA_HEADER = `// Every entity the app declares, re-exported here. This list is what the migration generator
-// reads, so an entity that is not exported here does not exist as far as the database is concerned.`;
+// Not "what the migration generator reads" — that claim shipped into every generated app and was
+// false. `x db gen` and `x verify`'s `drift` step both project the ENTITY REGISTRY that `loadApp`
+// fills (`describeEntities()`, `packages/cli/src/app-entities.ts`), so an entity declared anywhere
+// `loadApp` reaches is already in the migration whether or not this file names it. Re-exporting an
+// entity here does exactly one thing, and it is worth doing: it gives `seed.ts` and every other
+// consumer ONE import to reach the app's tables through.
+const SCHEMA_HEADER = `// Every entity the app declares, re-exported here so the seed and anything else that needs a table
+// reach them through one import. It is not what the migration generator reads: \`x db gen\` and the
+// \`drift\` step project the entity registry, so an entity is in the migration because it was
+// declared, never because it was listed here.`;
 
 const dbSchema = (app: NameSet, example: boolean): string =>
   example
@@ -65,7 +73,7 @@ const dbSchema = (app: NameSet, example: boolean): string =>
 export { post } from '@${app.kebab}/web/app/post/entity';
 `
     : `${SCHEMA_HEADER}
-// \`x g entity <name>\` writes the entity; add its export here so the database learns about it.
+// \`x g entity <name>\` writes the entity; add its export here to reach it through \`@${app.kebab}/db\`.
 export {};
 `;
 

package/src/templates/scaffold-docs.ts

@@ -13,19 +13,30 @@ const agents = (app: NameSet): string => `# AGENTS.md
 Human-authored, short, stable. Facts live in \`x.manifest.json\`; this file holds only what an
 agent cannot infer from the code.
 
-| Rule | Detail |
-|---|---|
-| One gate | \`x verify\` — green means shippable. Never merge red. |
-| One way | generators, not hand-rolled files: \`x g resource\`, \`x g action\`, \`x g route\` |
-| Surfaces | \`site/\` is 0kb JS and may not import \`app/\`; \`shared/\` is a leaf |
-| Data | routes call actions and queries; only \`repo.ts\` touches the database |
-| Errors | never \`throw new Error\` — subclass \`UltimateError\` with a code, a cause and a fix |
-| Money | integer minor units + ISO code, never a float |
-| Time | store UTC, format with an explicit IANA time zone |
-| Strings | every user-facing string goes through \`t()\` |
-| Colour | semantic tokens only, never a raw hex |
-
-Commands: \`x dev\`, \`x verify\`, \`x g <primitive>\`, \`x db branch create <name>\`, \`x doctor\`.
+Every row below names what refuses it. A rule with nothing in the last column is a rule that does
+not exist — five of these had an empty column and were each measured green on \`x verify\`.
+
+| Rule | Detail | Refused by |
+|---|---|---|
+| One gate | \`x verify\` — green means shippable. Never merge red. | the gate itself |
+| One way | generators, not hand-rolled files: \`x g resource\`, \`x g action\`, \`x g route\` | review |
+| Surfaces | \`site/\` is 0kb JS and may not import \`app/\`; \`shared/\` is a leaf | \`X_BOUNDARY_SITE_TO_APP\` |
+| Data | routes call actions and queries; only \`repo.ts\` touches the database | \`X_BOUNDARY_ROUTE_TO_DB\` |
+| Errors | never \`throw new Error\` — subclass \`UltimateError\` with a code, a cause and a fix | \`guards/bare-error.ts\` |
+| Money | \`{ minor, currency }\`, never a float — \`money()\` on the column | the type: \`price: 19.99\` is TS2322, \`number\` is not \`MoneyInput\` |
+| Time | store UTC, format with an explicit IANA time zone | \`guards/unzoned-date.ts\` |
+| Strings | every user-facing string goes through \`t()\` | \`guards/untranslated-string.ts\` |
+| Colour | semantic tokens only, never a raw hex | \`guards/raw-colour.ts\` |
+
+\`guards/\` is yours: each file is one rule, discovered by \`x verify\` and run inside its
+\`boundaries\` step. Delete one to drop the rule, and \`x g guard <name>\` writes the next.
+
+Money is the one row with no guard, deliberately: a float has no static signature a text rule can
+see, and the type already fires — measured, \`price: 19.99\` in a seed is
+\`TS2322: Type 'number' is not assignable to type 'MoneyInput'\`. A guard that pretended to check
+it would be worse than the type that really does.
+
+Commands: \`x dev\`, \`x verify\`, \`x g <primitive>\`, \`x g guard <name>\`, \`x db branch create <name>\`, \`x doctor\`.
 
 Project notes for ${app.kebab}: replace this line with the conventions a newcomer could not guess.
 `;
@@ -126,27 +137,34 @@ exec bunx x verify "$@"
 const composeDev = (
   app: NameSet,
 ): string => `# Optional: x dev needs none of this. Use it when you want the real Postgres/NATS/MinIO locally.
+#
+# Every published port binds 127.0.0.1, not 0.0.0.0. This stack ships its credentials in the file,
+# as a dev stack reasonably does — so the short form \`'5432:5432'\` would put an authenticated
+# database and an open object store on every interface this machine has, including the café wifi.
+# Docker publishes a port by writing DNAT rules, so a host firewall does not stop it. To reach this
+# stack from another machine, put a tunnel in front of it (\`ssh -L\`) rather than widening the bind;
+# production topology is docker-compose.prod.yml, and it is a different file for a reason.
 services:
   db:
     image: postgres:17-alpine
     environment:
       POSTGRES_PASSWORD: ${app.kebab}
       POSTGRES_DB: ${app.kebab}
-    ports: ['5432:5432']
+    ports: ['127.0.0.1:5432:5432']
     healthcheck:
       test: ['CMD-SHELL', 'pg_isready -U postgres']
       interval: 5s
   nats:
     image: nats:2-alpine
     command: ['-js']
-    ports: ['4222:4222']
+    ports: ['127.0.0.1:4222:4222']
   s3:
     image: minio/minio
     command: ['server', '/data']
     environment:
       MINIO_ROOT_USER: ${app.kebab}
       MINIO_ROOT_PASSWORD: ${app.kebab}-dev
-    ports: ['9000:9000']
+    ports: ['127.0.0.1:9000:9000']
 `;
 
 /** Docs, shims and container files for a new app, in the order a reader meets them. */