@ultimat3/cli 23.0.0 → 25.0.0

package/src/templates/scaffold-docs.ts

@@ -1,5 +1,5 @@
 // The human-authored half of what `x new` writes: the READMEs, the agent-facing convention files,
-// the bin/ shims and the optional dev compose. Separated from the config half so neither file has
+// the bin/ scripts and the optional dev compose. Separated from the config half so neither file has
 // to be scrolled to find the other — one file, one job applies to templates too. The image, its
 // ignore file, the production topology and the deploy page are `scaffold-container.ts`; the
 // `.claude/` harness that reads AGENTS.md is `scaffold-claude.ts`; the one workflow is
@@ -8,6 +8,7 @@
 import { LINE_CEILING } from '../workspace-checks';
 import { githubFiles } from './github/ci.yml';
 import type { GeneratedFile, NameSet } from './naming';
+import { binFiles } from './scaffold-bin';
 import { claudeFiles } from './scaffold-claude';
 import { containerFiles } from './scaffold-container';
 
@@ -21,7 +22,7 @@ not exist — five of these had an empty column and were each measured green on
 
 | Rule | Detail | Refused by |
 |---|---|---|
-| One gate | \`bin/check\` — \`x build\` and then \`x verify\`. Green means shippable; never merge red. | the gate itself, and \`.github/workflows/ci.yml\` on every push and pull request |
+| One gate | \`bun run check\` — \`x build\` and then \`x verify\`. Green means shippable; never merge red. | the gate itself, and \`.github/workflows/ci.yml\` on every push and pull request; \`.github/workflows/image.yml\` publishes only a commit it passed |
 | Coverage | the unit suite covers 95% of the lines and functions of this app's own source — every file under \`apps/\` and \`packages/\`, one no test loads counted at 0%. A floor, not the goal: a test added to raise it is proven by mutation — break the source, watch it go red, restore | \`X_COVERAGE_BELOW_FLOOR\` on the \`unit\` step; \`coverage\` in \`x.verify.json\` states the floor, and it only rises |
 | 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\` |
@@ -75,14 +76,14 @@ Every test the scaffold and the generators write is the idiom to copy. All of th
 | an island | \`mountIsland\`, once per state its \`*.island.states.ts\` declares | \`apps/web/shared/theme-toggle.island.test.ts\` |
 | an action or a query | \`target.as(actor, input)\` — the refusal first, then what it answers | \`apps/web/api/health.test.ts\` |
 | a job, a task, a backfill | \`test('…', async ({ runJobs }) => …)\` — a worker in this process; assert on \`trace.steps\` and each run's \`outcome\` | what \`x g job\` writes |
-| a repo, a seed | as an actor, \`runWithContext(createContext({ actor }), …)\`, with \`driver.reset?.()\` after each | \`packages/db/src/seed.test.ts\` |
+| a repo, a seed | as an actor, \`runWithContext(ctxOf({ actor }), …)\`, with \`driver.reset?.()\` after each | \`packages/db/src/seed.test.ts\` |
 
 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.
 
-\`bin/check\` is the gate and \`x verify\` is only its second half: the first is
+\`bun run check\` is the gate and \`x verify\` is only its second half: the first is
 \`x build --target static\`, and the build is what writes the \`.x/build-stats.json\` the
 \`budgets\` step measures. Run \`x verify\` on a tree nobody has built and \`budgets\` is red with
 X_BUDGET_UNMEASURED — the gate reporting on a file that does not exist, not on your code.
@@ -93,8 +94,9 @@ here is generated from it. So the scaffold never clobbers a maintainer policy, t
 clobbers \`AGENTS.md\`, \`bin/\`, \`.claude/\` or \`.github/\`, and deleting either side leaves the
 other exactly as it was.
 
-Commands: \`bin/setup\`, \`bin/dev\`, \`bin/check\`, \`x g <primitive>\`, \`x g guard <name>\`,
-\`x db branch create <name>\`, \`x doctor\`.
+Commands: \`bun run setup\`, \`bun run dev\`, \`bun run check\`, \`x g <primitive>\`,
+\`x g guard <name>\`, \`x db branch create <name>\`, \`x doctor\`. \`setup\` and \`check\` are
+\`bin/*.ts\` files Bun runs, so all three are the same command in PowerShell, cmd and bash.
 
 Project notes for ${app.kebab}: replace this line with the conventions a newcomer could not guess.
 `;
@@ -103,10 +105,10 @@ const claude = (app: NameSet): string => `# CLAUDE.md
 
 ${app.kebab} — Ultimate app. Read AGENTS.md first; it is the same content in the same order.
 
-- Gate: \`bin/check\` (add \`--json\` for machine output — it reaches both halves). It is
+- Gate: \`bun run check\` (add \`--json\` for machine output — it reaches both halves). It is
   \`x build --target static\` and then \`x verify\`; \`x verify\` alone leaves \`budgets\` with
-  nothing to measure. \`.github/workflows/ci.yml\` runs \`bin/setup && bin/check\` on every push
-  and pull request, so CI and your terminal run the same two commands.
+  nothing to measure. \`.github/workflows/ci.yml\` runs \`bun run setup && bun run check\` on
+  every push and pull request, so CI and your terminal run the same two commands.
 - \`.dz/\` belongs to the developerz.ai platform and is additive both ways: the scaffold writes
   nothing there, and nothing there is generated from this repo. Neither side clobbers the other.
 - Scaffold, do not hand-write: \`x g <kind> <name>\` — \`x g --help\` lists every kind, and is the
@@ -129,12 +131,12 @@ Built with [Ultimate](https://github.com/developerz-ai/ultimate). Bun-only, Post
 ## 🚀 Start
 
 \`\`\`sh
-bin/setup     # prerequisites, deps, env, the first migration, migrate, seed, the manifest
-bin/dev       # all roles in one process, embedded Postgres, /_x mounted
-bin/check     # the gate: a static build, then typecheck, lint, boundaries, tests, drift, budgets
+bun run setup   # prerequisites, deps, env, the first migration, migrate, seed, the manifest
+bun run dev     # all roles in one process, embedded Postgres, /_x mounted
+bun run check   # the gate: a static build, then typecheck, lint, boundaries, tests, drift, budgets
 \`\`\`
 
-\`packages/db/migrations\` starts empty and \`x db gen\` is its only writer — \`bin/setup\` runs
+\`packages/db/migrations\` starts empty and \`x db gen\` is its only writer — \`bun run setup\` runs
 \`x db gen "initial"\` for you on a fresh clone. Until it has, \`x verify\`'s \`drift\` step is red
 with \`X_DB_DRIFT\`, and that is the fix it names.
 
@@ -150,63 +152,8 @@ with \`X_DB_DRIFT\`, and that is the fix it names.
 | \`packages/*\` | domain, db, i18n, ui, mcp |
 | \`app.config.ts\` | the one config file |
 | \`x.manifest.json\` | generated facts: routes, actions, jobs, policies |
-| \`.github/workflows/ci.yml\` | \`bin/setup\` then \`bin/check\`, on push and pull request |
-`;
-
-const binSetup = (): string => `#!/usr/bin/env bash
-# Fresh clone to running. Idempotent: safe to re-run.
-set -euo pipefail
-cd "$(dirname "$0")/.."
-command -v bun >/dev/null || { echo "X_BUN_MISSING: install bun — https://bun.sh"; exit 1; }
-bun install
-[ -f .env.development.local ] || printf '# per-box secrets, gitignored, wins over .env.development\\n' > .env.development.local
-# \`x db gen\` is the ONE writer of packages/db/migrations — the scaffold no longer hand-writes a
-# 0000_initial.sql, because a second writer is how the source and the ledger ended up disagreeing
-# about what "initial" meant. Guarded on the directory rather than on the generator being a no-op:
-# this script is documented idempotent, and the guard is what makes that true here.
-ls packages/db/migrations/*.sql >/dev/null 2>&1 || bunx x db gen "initial"
-bunx x db migrate "$@"
-# \`x db seed\`, never \`bun run\`: the CLI owns the connection, so this reaches the same embedded
-# PGlite the migration above just wrote to. A plain script goes through \`db()\`, which needs a
-# \`postgres:\` DATABASE_URL and so dies on a clone with no Postgres — one line after reporting a
-# successful migration.
-bunx x db seed
-# The file \`AGENTS.md\` line 3 tells an agent facts live in, and \`x dev\` prints the path of. It
-# is a projection of the loaded app, so \`x new\` cannot write it — node_modules does not exist
-# yet — and nothing else ever ran the command: after \`x new\`, \`bin/setup\` and all 13
-# generators, \`find . -name '*.manifest.json'\` returned nothing while \`x verify\` reported
-# \`\u2713 manifest\`. \`x verify\`'s manifest step now refuses its absence (X_MANIFEST_MISSING).
-bunx x manifest
-echo "setup complete — next: bin/dev"
-`;
-
-const binDev = (): string => `#!/usr/bin/env bash
-# Every role in one process: embedded Postgres, in-process NATS, S3 to a local dir.
-set -euo pipefail
-cd "$(dirname "$0")/.."
-exec bunx x dev "$@"
-`;
-
-const binCheck = (): string => `#!/usr/bin/env bash
-# The gate. Same steps as CI, because a check that lives only in CI cannot be run locally.
-set -euo pipefail
-cd "$(dirname "$0")/.."
-# The build FIRST, and not as a convenience: \`x verify\`'s budgets step compares declared limits
-# against measured bytes in .x/build-stats.json, so with no build it reports X_BUDGET_UNMEASURED and
-# the very first gate anyone runs on a brand-new app is red for a reason that has nothing to do with
-# their code. Cheap on a warm tree, and it makes "green" reachable from a fresh clone.
-#
-# \`--json\` is forwarded to BOTH, or the contract breaks: \`bin/check --json\` would otherwise print
-# the build's human renderer to stdout and then the gate's JSON, and a machine consumer reading one
-# document off stdout gets neither. Both commands emit one object; a reader takes the last line.
-build_flags=""
-for arg in "$@"; do
-  case "$arg" in --json|-j) build_flags="--json" ;; esac
-done
-# \`--no-preflight\`: the build's own preflight is x verify's first six steps (typecheck, lint,
-# boundaries, filesize, package-shape, errors), and the gate below runs them anyway — once is enough.
-bunx x build --target static --no-preflight $build_flags
-exec bunx x verify "$@"
+| \`.github/workflows/ci.yml\` | \`bun run setup\` then \`bun run check\`, on push and pull request |
+| \`.github/workflows/image.yml\` | after a green \`ci\` on the default branch: \`docker/Dockerfile\` to \`ghcr.io\`, tagged \`sha-<7>\`, always on \`ubuntu-latest\` (bash and Docker). \`ci.yml\` runs on \`vars.CI_RUNNER\`, default \`ubuntu-latest\` |
 `;
 
 const composeDev = (
@@ -243,7 +190,7 @@ services:
   # the region a request was signed for, and an app that sets no S3_REGION signs for \`auto\` — so
   # that is this gateway's region. A server for a laptop; production is any S3-compatible endpoint.
   s3:
-    image: versity/versitygw:v1.8.0
+    image: versity/versitygw:v1.8.0@sha256:30292fc2eeacc67a36993b01f7a7a5e3361a19cced0e80c1d71cfa2a4b0a2499
     environment:
       VGW_BACKEND: posix
       VGW_BACKEND_ARG: /data
@@ -264,9 +211,8 @@ export function docsFiles(app: NameSet): readonly GeneratedFile[] {
     { path: 'README.md', contents: readme(app) },
     { path: 'AGENTS.md', contents: agents(app) },
     { path: 'CLAUDE.md', contents: claude(app) },
-    { path: 'bin/setup', contents: binSetup() },
-    { path: 'bin/dev', contents: binDev() },
-    { path: 'bin/check', contents: binCheck() },
+    // The scripts `bun run setup` and `bun run check` run — TypeScript, so one file per OS.
+    ...binFiles(),
     { path: 'docker/docker-compose.dev.yml', contents: composeDev(app) },
     // The harness half of the same job AGENTS.md does. It lands in the app's own repo rather than
     // in a global config, so it is visible in the scaffold's diff and deletable in one line.
@@ -278,6 +224,3 @@ export function docsFiles(app: NameSet): readonly GeneratedFile[] {
     ...containerFiles(app),
   ];
 }
-
-/** Files that must be executable after `x new` writes them. */
-export const EXECUTABLE_FILES: readonly string[] = ['bin/setup', 'bin/dev', 'bin/check'];

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

@@ -23,10 +23,6 @@ import type { MoneyValue as Money } from '@ultimat3/schema';
 
 export type { MoneyValue as Money } from '@ultimat3/schema';
 
-export const ROLES = ['owner', 'member', 'viewer'] as const;
-
-export type Role = (typeof ROLES)[number];
-
 /**
  * Never a bare Error: an agent reading the failure needs the code, the cause and the exact command
  * that resolves it. Adding across currencies is a bug in the caller's data, not a runtime hiccup,

package/src/templates/scaffold-entries.ts

@@ -16,6 +16,7 @@ const server =
 
 import { join } from 'node:path';
 import { runRole } from '@ultimat3/cli/serve';
+import { isCompiledBundle } from '@ultimat3/core';
 
 // MORE THAN ONE REPLICA? Add these two lines, above \`runRole\`:
 //
@@ -36,10 +37,10 @@ import { runRole } from '@ultimat3/cli/serve';
  * 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.
+ * \`isCompiledBundle\` knows both spellings of that filesystem: \`/$bunfs/\` on Linux and macOS,
+ * \`B:\\~BUN\\\` on Windows.
  */
-const root = import.meta.dir.startsWith('/$bunfs')
-  ? process.cwd()
-  : join(import.meta.dir, '..', '..');
+const root = isCompiledBundle(import.meta.dir) ? 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\`.

package/src/templates/scaffold-env.ts

@@ -4,7 +4,7 @@
 // app whose own `x verify` fails on the drift the framework exists to prevent.
 
 import type { EnvSchema, EnvVarDecl } from '@ultimat3/core';
-import { renderEnvExample } from '@ultimat3/core';
+import { appEnvExample } from '../framework-env';
 
 /**
  * Committed defaults only, so a fresh clone boots with `x dev` and no scavenger hunt. Every
@@ -90,9 +90,12 @@ export function envSchemaSource(schema: EnvSchema = SCAFFOLD_ENV_SCHEMA): string
   return lines.join('\n');
 }
 
-/** Byte-identical to what `x env example` writes, because both call core's one renderer. */
+/**
+ * Byte-identical to what `x env example` writes, because both call the one renderer — the app's
+ * declaration, then the framework's deploy-required keys (`framework-env.ts`).
+ */
 export const envExampleSource = (schema: EnvSchema = SCAFFOLD_ENV_SCHEMA): string =>
-  renderEnvExample(schema);
+  appEnvExample(schema);
 
 /** Named so a reader of `repoFiles` can see the two projections come from one declaration. */
 export const scaffoldEnvVarNames = (): readonly string[] =>

package/src/templates/scaffold-gitattributes.ts

@@ -0,0 +1,59 @@
+// The root `.gitattributes` `x new` writes: every text file LF in the index and the checkout, every
+// binary type left byte-for-byte. The framework repo's own root file opens with the same block —
+// `scaffold-gitattributes.test.ts` refuses the two drifting apart.
+
+/** The path, relative to the app root — git reads attributes from here for the whole tree. */
+export const ROOT_GITATTRIBUTES_PATH = '.gitattributes';
+
+/**
+ * Binary types an app or the framework plausibly tracks: images, icons, fonts, WebAssembly and the
+ * archives fixtures arrive in. `text=auto` would usually detect them, but "usually" is a heuristic
+ * over the first 8000 bytes — `binary` is the statement, and it also stops a textual diff.
+ */
+export const BINARY_EXTENSIONS: readonly string[] = [
+  'png',
+  'jpg',
+  'jpeg',
+  'gif',
+  'webp',
+  'avif',
+  'ico',
+  'woff',
+  'woff2',
+  'ttf',
+  'otf',
+  'wasm',
+  'pdf',
+  'zip',
+  'gz',
+  'tgz',
+  'tar',
+];
+
+/**
+ * `* text=auto eol=lf` is not cosmetic. Git for Windows installs with `core.autocrlf=true`, so a
+ * checkout without it rewrites every file to CRLF: Biome (`lineEnding: "lf"`) then flags every
+ * file, every `split('\n')` scanner sees a trailing `\r`, and every byte-compared artifact — the
+ * manifest, the schema dump, a migration's checksum — reads as drift on a correct tree. Pinned
+ * here, it holds for every clone whatever the contributor's git config says.
+ */
+export const LINE_ENDING_ATTRIBUTES = `# Every text file is LF, in the index and in the checkout, whatever \`core.autocrlf\` says. Git for
+# Windows defaults it to true: without this line a Windows clone is CRLF, Biome flags every file and
+# every byte-compared artifact (manifest, schema dump, migration checksum) reads as drift.
+* text=auto eol=lf
+
+# Binary, stated rather than detected: never line-ending converted, never textually diffed.
+${BINARY_EXTENSIONS.map((extension) => `*.${extension} binary`).join('\n')}
+`;
+
+/** The app's root file: the shared block, then the app's one generated file git should collapse. */
+export const rootGitattributes = (): string => `${LINE_ENDING_ATTRIBUTES}
+# Bun's lockfile. Regenerated by \`bun install\`, never edited by hand.
+bun.lock -diff linguist-generated=true
+`;
+
+/** The file `x new` writes at the app root — one entry in `repoFiles`' list. */
+export const rootGitattributesFile = (): { readonly path: string; readonly contents: string } => ({
+  path: ROOT_GITATTRIBUTES_PATH,
+  contents: rootGitattributes(),
+});

package/src/templates/scaffold-helm-fences.ts

@@ -0,0 +1,76 @@
+// What a compromised pod of the scaffolded chart can reach: its `/tmp`, bounded, and its ports,
+// fenced by one NetworkPolicy per role. The framework chart's own (`docker/helm/`), mirrored —
+// `scaffold-helm-parity.test.ts` holds the two to each other.
+
+import type { GeneratedFile, NameSet } from './naming';
+
+const volumes = (app: NameSet): string => `{{/*
+The writable scratch every pod mounts at /tmp — the root filesystem is read-only. Bounded, because
+an emptyDir with no sizeLimit is node disk: one role filling /tmp evicts its NEIGHBOURS for disk
+pressure, where with a limit the kubelet evicts that pod alone.
+*/}}
+{{- define "${app.kebab}.tmpVolume" -}}
+- name: tmp
+  emptyDir:
+    sizeLimit: {{ required "tmp.sizeLimit is unset — set it in your values (e.g. 512Mi): an unbounded /tmp is node disk" (default dict .Values.tmp).sizeLimit | quote }}
+{{- end -}}
+`;
+
+const networkPolicy = (app: NameSet): string => `{{/*
+One NetworkPolicy per enabled role: \`http\` (web, sync) from networkPolicy.httpFrom, \`metrics\`
+(every role) from networkPolicy.metricsFrom, nothing else. A \`from\` that renders empty is omitted,
+which Kubernetes reads as "any source". Egress is filtered only when networkPolicy.egress lists
+rules — the database, NATS and object store are your addresses, so list DNS too. Serving roles
+only: the migrate Job is a pre-install hook that runs before this exists, and opens no port.
+*/}}
+{{- if .Values.networkPolicy.enabled }}
+{{- range $role, $cfg := .Values.roles }}
+{{- if $cfg.enabled }}
+---
+apiVersion: networking.k8s.io/v1
+kind: NetworkPolicy
+metadata:
+  name: {{ include "${app.kebab}.fullname" $ }}-{{ $role }}
+  labels:
+    {{- include "${app.kebab}.labels" $ | nindent 4 }}
+    app.kubernetes.io/component: {{ $role }}
+spec:
+  podSelector:
+    matchLabels:
+      app.kubernetes.io/instance: {{ $.Release.Name }}
+      app.kubernetes.io/component: {{ $role }}
+  policyTypes:
+    - Ingress
+    {{- if $.Values.networkPolicy.egress }}
+    - Egress
+    {{- end }}
+  ingress:
+    {{- if $cfg.port }}
+    - ports:
+        - port: http
+          protocol: TCP
+      {{- with $.Values.networkPolicy.httpFrom }}
+      from: {{- toYaml . | nindent 8 }}
+      {{- end }}
+    {{- end }}
+    - ports:
+        - port: metrics
+          protocol: TCP
+      {{- with $.Values.networkPolicy.metricsFrom }}
+      from: {{- toYaml . | nindent 8 }}
+      {{- end }}
+  {{- with $.Values.networkPolicy.egress }}
+  egress: {{- toYaml . | nindent 4 }}
+  {{- end }}
+{{- end }}
+{{- end }}
+{{- end }}
+`;
+
+/** The bounded /tmp helper and the per-role NetworkPolicy, as two files of the chart's templates. */
+export function helmFenceFiles(app: NameSet): readonly GeneratedFile[] {
+  return [
+    { path: 'docker/helm/templates/_volumes.tpl', contents: volumes(app) },
+    { path: 'docker/helm/templates/networkpolicy.yaml', contents: networkPolicy(app) },
+  ];
+}

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

@@ -3,6 +3,7 @@
 // Split from scaffold-helm.ts, which holds the chart's INPUTS (Chart.yaml, values.yaml).
 
 import type { GeneratedFile, NameSet } from './naming';
+import { helmFenceFiles } from './scaffold-helm-fences';
 
 const helpers = (
   app: NameSet,
@@ -28,11 +29,13 @@ every object would be ${app.kebab}-${app.kebab}-web.
 
 {{/*
 repository:tag, and NOT a single "image" string: x deploy --method helm passes
---set image.repository=... --set image.tag=..., because replacing the map with a string makes
-every workload below fail on .repository and deploy nothing.
+--set-string image.repository=... --set-string image.tag=..., because replacing the map with a
+string makes every workload below fail on .repository and deploy nothing. toString on both halves:
+a plain --set image.tag=1234567 is an int64, which printf renders as %!s(int64=1234567).
 */}}
 {{- define "${app.kebab}.image" -}}
-{{- printf "%s:%s" .Values.image.repository (default .Chart.AppVersion .Values.image.tag) -}}
+{{- $repository := required "image.repository is empty — set it to the registry path your CI pushes the app image to: --set-string image.repository=ghcr.io/<org>/<app>, or x deploy --method helm --image ghcr.io/<org>/<app>:<tag>" .Values.image.repository -}}
+{{- printf "%s:%s" (toString $repository) (toString (default .Chart.AppVersion .Values.image.tag)) -}}
 {{- end -}}
 
 {{- define "${app.kebab}.labels" -}}
@@ -65,7 +68,7 @@ nobody bound. Derived here rather than stated twice in values.yaml, where the tw
 {{- $envPort = sub (int $cfg.port) 1 -}}
 {{- end -}}
 - name: {{ $role }}
-  image: {{ include "${app.kebab}.image" $root }}
+  image: {{ include "${app.kebab}.image" $root | quote }}
   imagePullPolicy: {{ $root.Values.image.pullPolicy }}
   securityContext: {{- toYaml $root.Values.securityContext | nindent 4 }}
   env:
@@ -79,13 +82,28 @@ nobody bound. Derived here rather than stated twice in values.yaml, where the tw
     - name: METRICS_PORT
       value: {{ $root.Values.metricsPort | quote }}
     {{- end }}
+    {{- /*
+    The sync node's page origin, from the one place this chart already knows it. Undeclared, a node
+    reached over plain http behind this Ingress admits BOTH spellings of its host — the plain-http
+    page included. env.APP_URL wins when set; an APP_URL kept in the Secret is shadowed for this
+    role, so pages served from another host than the Ingress's must say so in env.
+    */}}
+    {{- if and (eq $role "sync") $root.Values.ingress.enabled (not (hasKey $root.Values.env "APP_URL")) }}
+    - name: APP_URL
+      value: {{ printf "%s://%s" (ternary "https" "http" $root.Values.ingress.tls) $root.Values.ingress.host | quote }}
+    {{- end }}
     {{- range $key, $value := $root.Values.env }}
     - name: {{ $key }}
       value: {{ $value | quote }}
     {{- end }}
+  {{- /*
+  The Secret a role reads, per role: roles.<role>.existingSecret (or migrate.existingSecret) names a
+  narrower one than the release-wide existingSecret, so the migrate Job's schema-owning credential
+  need not sit on a web pod. Both unset is a render error, not a pod with no configuration.
+  */}}
   envFrom:
     - secretRef:
-        name: {{ $root.Values.existingSecret }}
+        name: {{ required (printf "no Secret for role %s — set existingSecret, or roles.%s.existingSecret, in your values" $role $role) (default $root.Values.existingSecret $cfg.existingSecret) }}
   {{- if or $cfg.port $scraped }}
   ports:
     {{- if $cfg.port }}
@@ -100,8 +118,12 @@ nobody bound. Derived here rather than stated twice in values.yaml, where the tw
   {{/*
   Probes follow the role, because the roles do not agree on what they open. web and sync serve
   HTTP and get both. worker, scheduler and replicator open no HTTP socket at all — the scrape
-  listener is their only port — so they take liveness on it and NO readiness: nothing routes to
-  them, and a readiness flap would drop the pod out of the Service and so out of the scrape.
+  listener is their only port — so they take liveness on it, and readiness on /readyz of that same
+  listener: 503 until the role has started and from the first instant of a drain, so a rollout
+  never counts a worker that has not started its role yet. The replicator reads /readyz?deep=1:
+  503 while the replication stream is down, so the pod shows 0/1 instead of a healthy pod feeding
+  nothing. Their headless Service publishes not-ready addresses, so a not-ready pod is still
+  scraped.
 
   Every one of them takes a startupProbe too, because no listener opens early: the server builds
   the app's islands before any role binds a port, and a liveness probe counting from container
@@ -134,22 +156,69 @@ nobody bound. Derived here rather than stated twice in values.yaml, where the tw
     httpGet: { path: /metrics, port: metrics }
     periodSeconds: 5
     failureThreshold: 30
+  readinessProbe:
+    {{- if eq $role "replicator" }}
+    httpGet: { path: '/readyz?deep=1', port: metrics }
+    periodSeconds: 10
+    {{- else }}
+    httpGet: { path: /readyz, port: metrics }
+    periodSeconds: 5
+    {{- end }}
   livenessProbe:
     httpGet: { path: /metrics, port: metrics }
     periodSeconds: 15
     failureThreshold: 4
+  {{- /*
+  The worker's retire, opt-in: roles.worker.retireSeconds > 0. The preStop sends PID 1 SIGUSR2 —
+  the framework's retire: stop claiming, finish every held job however long it takes, abort
+  nothing, then drain and exit 0 — and waits until PID 1 is gone, so the SIGTERM that follows finds
+  nothing left to cut off. bun -e, never kill/sleep: bun is the image's ENTRYPOINT (exec form, so it
+  IS PID 1). The kubelet counts the preStop against the grace period, so retireSeconds is added to
+  it and is the longest a retire may take.
+  */}}
+  {{- if and (eq $role "worker") (gt (int $cfg.retireSeconds) 0) }}
+  lifecycle:
+    preStop:
+      exec:
+        command:
+          - bun
+          - -e
+          - "process.kill(1, 'SIGUSR2'); for (;;) { try { process.kill(1, 0); } catch { break; } await Bun.sleep(1000); }"
+  {{- end }}
   {{- end }}
   resources: {{- toYaml $cfg.resources | nindent 4 }}
   volumeMounts:
     - name: tmp
       mountPath: /tmp
 {{- end -}}
+
+{{/*
+A role's terminationGracePeriodSeconds, in the order the kubelet's budget is spent: the preStop
+sleep (web and sync, 1.30+), the worker's opt-in retire (roles.worker.retireSeconds), the
+readiness grace (web and sync — every other role drains with none), the drain budget (app.config.ts drain.deadlineMs, every role) and the teardown margin.
+Defaults: 45s web/sync (40s below 1.30), 35s the rest. x deploy --method helm sets
+drain.deadlineSeconds and drain.readinessGraceSeconds from app.config.ts.
+*/}}
+{{- define "${app.kebab}.terminationGracePeriodSeconds" -}}
+{{- $drain := .root.Values.drain -}}
+{{- $total := add (int $drain.deadlineSeconds) (int $drain.teardownMarginSeconds) -}}
+{{- if eq .role "worker" -}}
+{{- $total = add $total (int .cfg.retireSeconds) -}}
+{{- end -}}
+{{- if .cfg.port -}}
+{{- $total = add $total (int $drain.readinessGraceSeconds) -}}
+{{- if semverCompare ">=1.30-0" .root.Capabilities.KubeVersion.Version -}}
+{{- $total = add $total (int $drain.preStopSleepSeconds) -}}
+{{- end -}}
+{{- end -}}
+{{- $total -}}
+{{- end -}}
 `;
 
 const deployments = (app: NameSet): string => `{{/*
 One Deployment per enabled role, from one image. terminationGracePeriodSeconds covers the preStop
-sleep, the framework's readiness grace and its SIGTERM drain: in-flight requests, open websockets
-and running job steps finish.
+sleep, the framework's readiness grace and its SIGTERM drain — in-flight requests, open websockets
+and running job steps finish — derived per role from drain in values.yaml.
 */}}
 {{- range $role, $cfg := .Values.roles }}
 {{- if $cfg.enabled }}
@@ -171,9 +240,21 @@ spec:
     matchLabels:
       app.kubernetes.io/instance: {{ $.Release.Name }}
       app.kubernetes.io/component: {{ $role }}
+  {{/*
+  The replicator is Recreate, never a rolling update: one pod per database holds the replication
+  slot's advisory lock, so a surged pod can only stand by, unready, and maxUnavailable: 0 never
+  terminates the holder it is waiting on — every rollout stalled. Recreate lets the holder go first.
+  */}}
+  {{/* A new pod must stay Ready this long before the rollout counts it and stops an old one, so a
+  role that crashes seconds after its first probe never replaces a working pod. */}}
+  minReadySeconds: {{ $.Values.minReadySeconds | int }}
   strategy:
+    {{- if eq $role "replicator" }}
+    type: Recreate
+    {{- else }}
     type: RollingUpdate
     rollingUpdate: { maxUnavailable: 0, maxSurge: 1 }
+    {{- end }}
   template:
     metadata:
       labels:
@@ -185,17 +266,14 @@ spec:
       code that reaches the filesystem, which for a web role is one path traversal. */}}
       automountServiceAccountToken: false
       securityContext: {{- toYaml $.Values.podSecurityContext | nindent 8 }}
-      {{/* Spent in order: the preStop sleep (drain.preStopSleepSeconds, 1.30+), the framework's
-      readiness grace (5s outside local environments) and its drain deadline (25s, which is what
-      X_SHUTDOWN_TIMEOUT's fix line names) — 35s, so 45 leaves 10s before SIGKILL. Raise this WITH
-      configureLifecycle({ deadlineMs, readinessGraceMs }), never instead of it: the drain
-      abandons its hooks at its own deadline. */}}
-      terminationGracePeriodSeconds: 45
+      {{/* Derived per role from the drain values — see the helper in _helpers.tpl. Raise
+      drain.deadlineMs in app.config.ts, never this: the drain abandons its hooks at its own
+      deadline, so a longer grace period alone buys nothing. */}}
+      terminationGracePeriodSeconds: {{ include "${app.kebab}.terminationGracePeriodSeconds" (dict "role" $role "cfg" $cfg "root" $) }}
       containers:
         {{- include "${app.kebab}.container" (dict "role" $role "cfg" $cfg "root" $) | nindent 8 }}
       volumes:
-        - name: tmp
-          emptyDir: {}
+        {{- include "${app.kebab}.tmpVolume" $ | nindent 8 }}
 {{- end }}
 {{- end }}
 `;
@@ -219,6 +297,9 @@ spec:
   type: ClusterIP
   {{- if not $cfg.port }}
   clusterIP: None
+  # Scraped whether or not ready: a replicator whose stream is down (readiness 503) is the pod
+  # whose metrics matter most, and nothing routes to these addresses anyway.
+  publishNotReadyAddresses: true
   {{- end }}
   selector:
     app.kubernetes.io/instance: {{ $.Release.Name }}
@@ -267,8 +348,7 @@ spec:
       containers:
         {{- include "${app.kebab}.container" (dict "role" "migrate" "cfg" .Values.migrate "root" .) | nindent 8 }}
       volumes:
-        - name: tmp
-          emptyDir: {}
+        {{- include "${app.kebab}.tmpVolume" . | nindent 8 }}
 {{- end }}
 `;
 
@@ -382,5 +462,6 @@ export function helmTemplateFiles(app: NameSet): readonly GeneratedFile[] {
     { path: 'docker/helm/templates/migrate-job.yaml', contents: migrateJob(app) },
     { path: 'docker/helm/templates/ingress.yaml', contents: ingress(app) },
     { path: 'docker/helm/templates/hpa.yaml', contents: hpa(app) },
+    ...helmFenceFiles(app),
   ];
 }