@ultimat3/cli 20.2.1 → 22.0.0

package/src/templates/resource-form-island.ts

@@ -32,11 +32,14 @@ const formIslandSource = (
 // the PAGE, which is one directory across from this one:
 //   const ${feature.pascal}Form = island({
 //     src: '${specifier}',
-//     props: ['endpoint', 'locale', 'labels'],
+//     props: ['endpoint', 'locale', 'currency', 'labels'],
 //   });
-//   <${feature.pascal}Form endpoint={derivePath('create${feature.pascal}').path} locale={locale} labels={labels} />
+//   <${feature.pascal}Form endpoint={derivePath('create${feature.pascal}').path} locale={locale}
+//     currency="USD" labels={labels} />
 // A string has no import edge, so the page's bundle graph stays the page's (axiom 6).
 
+import { clientTransport } from '@ultimat3/core';
+import { fromDecimal } from '@ultimat3/money';
 import { Button, Form, Input, setSolidRuntime, UiProvider } from '@ultimat3/ui';
 import type { JSX } from 'solid-js';
 import {
@@ -57,8 +60,11 @@ export interface ${feature.pascal}FormProps {
   readonly endpoint: string;
   /** The request's own locale. A browser has no ambient one the server ever agreed to. */
   readonly locale: string;
+  /** The ISO code the price is entered in. The amount is typed as a decimal and sent as minor units. */
+  readonly currency: string;
   readonly labels: {
     readonly title: string;
+    readonly price: string;
     readonly submit: string;
     readonly saved: string;
     readonly retry: string;
@@ -71,25 +77,30 @@ type SaveState = 'idle' | 'saved' | 'failed';
  * Presentation only: the action this submits to owns validation server-side, so the form never
  * re-implements the invariant — a blank title fails at the boundary, not in the DOM.
  *
- * A plain \`fetch\` to the path the server minted, not the typed client: \`rpc()\` pulls
- * \`@ultimat3/action\` into the chunk, which is larger than everything else here put together. The
- * naming rule is still the framework's; only the transport is second.
+ * \`clientTransport\` — the framework's one browser HTTP function — to the path the server minted.
+ * Never a raw \`fetch\`: the transport is what decodes a refusal into its code, fences a sign-out,
+ * and hands any entity rows the answer carries to the page's store.
  */
 function ${feature.pascal}FormBody(props: ${feature.pascal}FormProps): JSX.Element {
   const [title, setTitle] = createSignal('');
+  const [amount, setAmount] = createSignal('');
   const [state, setState] = createSignal<SaveState>('idle');
 
-  // A rejected \`fetch\` — offline, DNS, an aborted request — is the same OUTCOME as a refused one,
-  // and it is the one \`retry\` exists for. Without the catch, \`setState\` is never reached: the
-  // status line stays empty, and the rejection escapes the \`void send()\` below as an unhandled one.
+  // A refusal and a request that never got a response both REJECT here — the transport turns a
+  // non-2xx into its code and an offline \`fetch\` into X_CLIENT_TRANSPORT_FAILED — and both are the
+  // outcome \`retry\` exists for. Without the catch the rejection escapes \`void send()\` unhandled.
+  // The body is the create action's input: the entity's own columns, the price as integer minor
+  // units. \`fromDecimal\` reads the typed digits as a string, never a float, and refuses what is not
+  // a number — the same \`retry\` state, because the server would refuse it too.
   const send = async (): Promise<void> => {
     try {
-      const response = await fetch(props.endpoint, {
+      const price = fromDecimal(amount(), props.currency);
+      await clientTransport({
         method: 'POST',
-        headers: { 'content-type': 'application/json' },
-        body: JSON.stringify({ title: title() }),
+        url: props.endpoint,
+        body: { title: title(), price },
       });
-      setState(response.ok ? 'saved' : 'failed');
+      setState('saved');
     } catch {
       setState('failed');
     }
@@ -113,6 +124,12 @@ function ${feature.pascal}FormBody(props: ${feature.pascal}FormProps): JSX.Eleme
         value={title()}
         onInput={(event) => setTitle(event.currentTarget.value)}
       />
+      <Input
+        aria-label={props.labels.price}
+        inputmode="decimal"
+        value={amount()}
+        onInput={(event) => setAmount(event.currentTarget.value)}
+      />
       <Button type="submit">{props.labels.submit}</Button>
       <p data-role="status" role="status" aria-live="polite">
         {status()}
@@ -177,7 +194,13 @@ const APP_ROOT = join(import.meta.dir, ${upToAppRoot(dir)});
 const ISLAND = '${dir}/${feature.kebab}-form.island.tsx';
 const ENDPOINT = '/api/${feature.kebab}/create-${feature.kebab}';
 
-const LABELS = { title: 'Title', submit: 'Save', saved: 'Saved', retry: 'Try again' };
+const LABELS = {
+  title: 'Title',
+  price: 'Price',
+  submit: 'Save',
+  saved: 'Saved',
+  retry: 'Try again',
+};
 
 const calls: { url: string; body: Record<string, unknown> }[] = [];
 
@@ -194,17 +217,18 @@ beforeAll(async () => {
     build: buildIslands,
     root: APP_ROOT,
     file: ISLAND,
-    props: { endpoint: ENDPOINT, locale: 'en', labels: LABELS },
+    props: { endpoint: ENDPOINT, locale: 'en', currency: 'USD', labels: LABELS },
     // What the server rendered inside the island's wrapper. \`mount\` replaces it.
     shell: '<p>Loading</p>',
     globals: {
-      fetch: (url: string, init: { body: string }): Promise<{ ok: boolean }> => {
+      // The form sends through \`clientTransport\`, which calls \`globalThis.fetch\` — this stub.
+      fetch: (url: string, init: { body: string }): Promise<Response> => {
         calls.push({ url, body: JSON.parse(init.body) as Record<string, unknown> });
-        // What a browser rejects with when there is no network. Not a response: \`response.ok\`
-        // is never read on this path, which is exactly why the form has to catch it.
+        // What a browser rejects with when there is no network. Not a response, which is exactly
+        // why the form has to catch it.
         return networkFails
           ? Promise.reject(new TypeError('Failed to fetch'))
-          : Promise.resolve({ ok: true });
+          : Promise.resolve(Response.json({ id: 'created' }));
       },
     },
   });
@@ -221,6 +245,18 @@ afterAll(() => {
   mounted?.[Symbol.dispose]();
 });
 
+/**
+ * Until the status line changes, a bounded number of macrotasks: the send is several awaits deep
+ * inside \`clientTransport\`, so counting microtasks would pin the transport, not the form.
+ */
+async function statusSettled(): Promise<void> {
+  const before = mounted.text('[data-role="status"]');
+  for (let tick = 0; tick < 50; tick += 1) {
+    if (mounted.text('[data-role="status"]') !== before) return;
+    await new Promise<void>((resolve) => setTimeout(resolve, 0));
+  }
+}
+
 /**
  * One mount, driven as a session: the cases below run in order against the same island, because
  * building the real chunk costs seconds and repeating it per case would pay them for state each
@@ -234,17 +270,25 @@ describe('the ${feature.kebab} form island', () => {
     expect(mounted.code).not.toMatch(/\\bReact\\b/);
   });
 
-  test('the field tracks, and submit posts what was typed', async () => {
-    const field: FakeElement | null = mounted.find('input');
-    expect(field).not.toBeNull();
-    if (field !== null) field.value = 'First ${feature.camel}';
+  test('the fields track, and submit posts the create input', async () => {
+    const title: FakeElement | null = mounted.find('input[aria-label="Title"]');
+    const price: FakeElement | null = mounted.find('input[aria-label="Price"]');
+    expect(title).not.toBeNull();
+    expect(price).not.toBeNull();
+    if (title !== null) title.value = 'First ${feature.camel}';
+    if (price !== null) price.value = '12.50';
     // \`false\` means no handler ran — an island whose onInput never reached the DOM looks
     // identical to a selector typo otherwise.
-    expect(mounted.fire(field, 'input')).toBe(true);
+    expect(mounted.fire(title, 'input')).toBe(true);
+    expect(mounted.fire(price, 'input')).toBe(true);
     expect(mounted.fire('form', 'submit', { preventDefault: () => {} })).toBe(true);
-    await Promise.resolve();
+    await statusSettled();
 
-    expect(calls).toEqual([{ url: ENDPOINT, body: { title: 'First ${feature.camel}' } }]);
+    const body = {
+      title: 'First ${feature.camel}',
+      price: { minor: 1250, currency: 'USD' },
+    };
+    expect(calls).toEqual([{ url: ENDPOINT, body }]);
   });
 
   test('the status line answers the response', () => {
@@ -253,12 +297,11 @@ describe('the ${feature.kebab} form island', () => {
   });
 
   test('a request that never got a response still reaches retry', async () => {
-    // The outcome \`retry\` is FOR. A \`fetch\` that rejects reaches no \`response.ok\`, so without
-    // the catch in \`send\` the status line stays on its last value and the rejection escapes.
+    // The outcome \`retry\` is FOR. A \`fetch\` that rejects produces no answer, so without the
+    // catch in \`send\` the status line stays on its last value and the rejection escapes.
     networkFails = true;
     expect(mounted.fire('form', 'submit', { preventDefault: () => {} })).toBe(true);
-    await Promise.resolve();
-    await Promise.resolve();
+    await statusSettled();
 
     expect(mounted.text('[data-role="status"]')).toBe(LABELS.retry);
   });
@@ -291,10 +334,12 @@ import type { ${feature.pascal}FormProps } from './${feature.kebab}-form.island'
 
 /** What a working render hands the form — the baseline the state below departs from. */
 const BASE = {
-  endpoint: '/api/create-${feature.kebab}',
+  endpoint: '/api/${feature.pluralKebab}/create',
   locale: 'en',
+  currency: 'USD',
   labels: {
     title: 'Title',
+    price: 'Price',
     submit: 'Save',
     saved: 'Saved',
     retry: 'That did not save. Try again.',
@@ -318,6 +363,7 @@ export const ${feature.camel}FormStates = defineIslandStates({
         locale: 'de',
         labels: {
           title: 'Bezeichnung des Beitrags',
+          price: 'Preis',
           submit: 'Änderungen speichern',
           saved: 'Änderungen gespeichert',
           retry: 'Das konnte nicht gespeichert werden. Bitte erneut versuchen.',

package/src/templates/resource.ts

@@ -13,6 +13,7 @@ import type { GeneratedFile, NameSet } from './naming';
 import { names, pascal } from './naming';
 import { policyFiles } from './policy';
 import { queryFiles } from './query';
+import { resourceCreateFiles } from './resource-create';
 import { formIslandFiles } from './resource-form-island';
 import { routeDir, routeFiles } from './route';
 
@@ -178,13 +179,18 @@ export function resourceFiles(rawName: string, target: ResourceOptions): readonl
   // question and only one of them reaches `routeFiles`.
   const pageDir = routeDir('app', feature.pluralKebab);
   const locales = resolveLocales(target.locales);
+  const entity = entityFiles(rawName, slice);
+  // The entity this same call writes, handed to the generators composed below as if it were on
+  // disk: they write into a slice that HAS data, so they read it rather than a neutral body.
+  const sliceEntity = String(entity.find((file) => file.path.endsWith('/entity.ts'))?.contents);
   return [
-    ...entityFiles(rawName, slice),
+    ...entity,
     ...policyFiles(rawName, slice),
-    ...actionFiles(`create-${feature.kebab}`, slice),
-    ...actionFiles(`archive-${feature.kebab}`, slice),
+    // Not `x g action`'s body: a resource's create INSERTS (`resource-create.ts`).
+    ...resourceCreateFiles(rawName, dir),
+    ...actionFiles(`archive-${feature.kebab}`, { ...slice, sliceEntity }),
     ...queryFiles(`${feature.camel}List`, { ...slice, live: true }),
-    ...jobFiles(`reindex-${feature.kebab}`, slice),
+    ...jobFiles(`reindex-${feature.kebab}`, { ...slice, sliceEntity }),
     { path: `${dir}/service.ts`, contents: serviceSource(feature) },
     { path: `${dir}/service.test.ts`, contents: serviceTest(feature) },
     { path: `${dir}/ui.tsx`, contents: uiSource(feature, target.catalogModule) },

package/src/templates/route.ts

@@ -219,6 +219,9 @@ import { e2eTest, expect } from '@ultimat3/testing';
 // \`e2eTest\` reports itself skipped, naming the command that builds what it would drive.
 e2eTest('/${path} renders offline', async ({ page, offline }) => {
   await page.goto('/${sampleUrl(path)}');
+  // \`offline()\` cuts the service worker's network too, so the reload is answered from its cache
+  // or not at all — which needs the worker in control of this page before the cut.
+  await page.waitForServiceWorker();
   await offline();
   await page.reload();
   expect(await page.title()).not.toBe('');

package/src/templates/scaffold-app.ts

@@ -7,6 +7,7 @@ import type { GeneratedFile, NameSet } from './naming';
 import { apiFiles } from './scaffold-api';
 import { authFiles } from './scaffold-auth';
 import { dashboardFiles } from './scaffold-dashboard';
+import { demoOrgFiles } from './scaffold-demo-org';
 import { entryFiles } from './scaffold-entries';
 import { errorPageFiles } from './scaffold-errors';
 import { httpFiles } from './scaffold-http';
@@ -309,11 +310,13 @@ export function appFiles(app: NameSet, example: boolean): readonly GeneratedFile
     { path: 'apps/web/shared/global.ts', contents: sharedGlobalModule() },
     { path: 'apps/web/shared/actor.ts', contents: sharedActor() },
     { path: 'apps/web/shared/actor.test.ts', contents: sharedActorTest() },
+    // The one org the dev actor, the seed and the dashboard all name — `scaffold-demo-org.ts`.
+    ...demoOrgFiles(),
     // The app's role map, beside the actor that reads it. `shared/` and not a feature folder:
     // `defineRoles()` merges, so a per-feature call is legal and is how an app ends up with no
     // answer to "which roles exist?" — see `scaffold-roles.ts`.
     ...httpFiles(app),
-    ...rolesFiles(),
+    ...rolesFiles(example),
     { path: 'apps/admin/package.json', contents: adminPackage(app) },
     { path: 'apps/admin/tsconfig.json', contents: tsconfig() },
     // `apps/admin/app/admin/page.tsx`, not `apps/admin/app/page.tsx`: the directory IS the URL,

package/src/templates/scaffold-auth.ts

@@ -35,6 +35,7 @@ const devActor = (
 // Everything downstream — pages, policies, live subscribers, MCP tools — reads what this returns.
 import { type Actor, logger, tryResolveEnvironment } from '@ultimat3/core';
 import { configureAuthenticator, readCookie } from '@ultimat3/http';
+import { DEMO_ORG_ID } from '../../shared/demo-org';
 
 /** Set it to a role from \`apps/web/shared/roles.ts\` to browse as that role. */
 export const DEV_ROLE_COOKIE = '${app.kebab}_dev_role';
@@ -66,7 +67,8 @@ export const devRoleFrom = (cookieHeader: string | null): DevRole => {
 export const devActorFor = (role: DevRole): Actor => ({
   kind: 'user',
   id: 'dev-actor',
-  orgId: 'dev-org',
+  // The seed's org, never an invented string: a generated tenant policy compares it with a uuid.
+  orgId: DEMO_ORG_ID,
   roles: [role],
   // Both required, and both deliberately empty: \`scopes\` is the framework's own escape hatch
   // (\`tenancy:cross\`) and \`permissions\` is a DIRECT grant that bypasses the role map — a

package/src/templates/scaffold-container-compose.ts

@@ -0,0 +1,184 @@
+// The production topology `x new` writes: one compose service per role, one image. Split from
+// scaffold-container.ts, which holds the image and the page that explains it; this file is what
+// `x deploy --method compose` runs, and the single-node rung of the scale ladder.
+
+import type { NameSet } from './naming';
+
+/**
+ * The production env file, relative to the app root. Named once because two readers must agree:
+ * the compose file's \`env_file:\` (what the containers see) and \`x deploy\`'s \`--env-file\` (what
+ * compose interpolates \`\${VAR:?…}\` from). Two spellings would let them drift apart silently.
+ */
+export const PROD_ENV_FILE = '.env.production';
+
+/** The production topology `x new` writes at `docker/docker-compose.prod.yml`. */
+export const composeProdFile = (
+  app: NameSet,
+): string => `# The production topology: one service per role, one image, differing only by ROLE and replicas.
+# What \`x deploy --method compose\` runs. migrate runs to completion before anything serves.
+#
+#   IMAGE=ghcr.io/you/${app.kebab}:1.2.3 x deploy --image ghcr.io/you/${app.kebab}:1.2.3
+#
+# By hand, always with \`--env-file ${PROD_ENV_FILE}\`: Compose fills \`\${VAR:?…}\` below from the shell
+# and \`--env-file\` only, NEVER from \`env_file:\`, so without it a value set only in that file is
+# "missing" and the parse fails. \`x deploy\` passes it on every step.
+#
+#   docker compose --env-file ${PROD_ENV_FILE} -f docker/docker-compose.prod.yml up -d
+#
+# A published host port has exactly one binder, so \`web\` and \`sync\` run at 1 here. Compose is one
+# box; horizontal scaling of those two belongs to an orchestrator — \`docker/helm\`, beside this
+# file, is the chart \`x deploy --method helm\` installs. To scale them on one box anyway, drop
+# \`ports:\` and put your own proxy on this network — the service name resolves to every replica
+# over the compose DNS round robin.
+name: ${app.kebab}
+
+# Every service's logs, rotated. Docker's default json-file driver never rotates, so a chatty role
+# on a long-lived box fills the disk the database lives on; 3 x 10 MB per container is the ceiling.
+x-logging: &logging
+  driver: json-file
+  options: { max-size: 10m, max-file: '3' }
+
+x-image: &image
+  image: \${IMAGE:-${app.kebab}:dev}
+  env_file: [../${PROD_ENV_FILE}]
+  restart: unless-stopped
+  logging: *logging
+  # SIGTERM → /readyz answers 503 for the readiness grace (5s outside local environments), then the
+  # drain of in-flight requests, jobs and sockets (25s). 40s leaves 10s before Docker SIGKILLs.
+  stop_grace_period: 40s
+  # What the chart's securityContext applies, on the rung that had none: a read-only root
+  # filesystem, no Linux capabilities (nothing here binds below 1024), no setuid escalation, and a
+  # memory ceiling so one runaway role takes down its container rather than the box. /tmp and .x/
+  # are tmpfs — .x/ is where a still-embedded binding keeps state, which production never relies on.
+  read_only: true
+  tmpfs: [/tmp, /app/.x]
+  cap_drop: [ALL]
+  security_opt: ['no-new-privileges:true']
+  mem_limit: 1g
+  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
+    environment:
+      POSTGRES_PASSWORD: \${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}
+      POSTGRES_DB: ${app.kebab}
+    volumes: ['pgdata:/var/lib/postgresql/data']
+    healthcheck:
+      test: ['CMD-SHELL', 'pg_isready -U postgres']
+      interval: 5s
+    restart: unless-stopped
+    logging: *logging
+
+  # The release phase. Applies pending migrations under an advisory lock and exits; every serving
+  # role waits for it to complete, so no replica ever serves against a schema it does not ship.
+  migrate:
+    <<: *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.
+  # Dry run is the default, so \`--write\` is explicit.
+  backfill:
+    <<: *image
+    # The image's ENTRYPOINT is \`bun apps/web/server.ts\`, and that entry reads ROLE and PORT and
+    # NOTHING ELSE — argv never reaches a parser. A bare \`command:\` is appended to it and silently
+    # discarded, so this service used to serve HTTP as ROLE=web under a name that said otherwise.
+    # Overriding the entrypoint is what makes the words below a command. The file path, not
+    # \`node_modules/.bin/x\`: it needs no bin symlink and no executable bit inside the image.
+    entrypoint: ['bun', 'node_modules/@ultimat3/cli/src/bin.ts']
+    command: ['db', 'backfill', '--all', '--write', '--json']
+    depends_on:
+      db: { condition: service_healthy }
+      migrate: { condition: service_completed_successfully }
+      # The barrier, not the ordering. \`docker compose up -d\` returns when a container STARTS, so
+      # 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
+    # The page dials SYNC_URL; unset, it dials /_x/sync on :3000, which web does not serve here.
+    # Set it in ${PROD_ENV_FILE}: \`--env-file\` (header) is what lets this line read it there.
+    environment: [ROLE=web, 'SYNC_URL=\${SYNC_URL:?set SYNC_URL=ws://<host>:3001/_x/sync, see wiki/Deployment.md}']
+    depends_on:
+      db: { condition: service_healthy }
+      migrate: { condition: service_completed_successfully }
+    deploy: { replicas: 1 } # stateless, scales on RPS — pinned by the published port
+    ports: ['3000:3000']
+
+  sync:
+    <<: *image
+    environment: [ROLE=sync]
+    depends_on:
+      db: { condition: service_healthy }
+      migrate: { condition: service_completed_successfully }
+    # OFF by default (zero replicas). A sync node on this database hears committed changes only
+    # from a replicator it can reach, and this file runs none: booted anyway it is refused
+    # (X_REALTIME_TOPOLOGY). To turn live queries and channels on: declare realtime: { enabled:
+    # true, transport: 'nats', urlEnv: 'NATS_URL' } in app.config.ts, add a NATS service and set the
+    # SAME NATS_URL for web, sync and a replicator service (ROLE=replicator, exactly one), start
+    # Postgres with wal_level=logical and a publication for the entity tables, then set replicas: 1.
+    # A NATS_URL under transport 'memory' refuses the boot (X_CONFIG_INVALID), and so does 'nats'
+    # without one.
+    deploy: { replicas: 0 } # when on: scales on concurrent websockets — pinned to 1 by the port
+    # The sync role binds PORT + 1. PORT is unset here, so it is 3000 and this listens on 3001.
+    ports: ['3001:3001']
+    # ...which is why the image's own HEALTHCHECK cannot be inherited here. It fetches $PORT —
+    # 3000 — and this role never binds it, so the container reports \`unhealthy\` from
+    # \`start_period\` onward and never recovers, and anything gated on \`sync: service_healthy\`
+    # would never start. Literal 3001 rather than an expression, for the same reason \`ports:\`
+    # above is literal: PORT is unset in this file, and two ways of saying one number drift.
+    # \`docker/helm\` states the same rule as \`PORT = .port - 1\`.
+    healthcheck:
+      test: ['CMD', 'bun', '--eval', "fetch('http://127.0.0.1:3001/readyz').then(r=>process.exit(r.ok?0:1),()=>process.exit(1))"]
+      interval: 10s
+      timeout: 3s
+      start_period: 30s
+      retries: 3
+
+  worker:
+    <<: *image
+    environment: [ROLE=worker]
+    depends_on:
+      db: { condition: service_healthy }
+      migrate: { condition: service_completed_successfully }
+    healthcheck: *metrics-probe
+    deploy: { replicas: 1 } # scales on queue depth
+
+  scheduler:
+    <<: *image
+    environment: [ROLE=scheduler]
+    depends_on:
+      db: { condition: service_healthy }
+      migrate: { condition: service_completed_successfully }
+    # Fixed 1. Leadership is an EXPIRING LEASE ROW in \`x_scheduler_leader\` (role-start.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:
+`;