create-stitchkit 0.4.0 → 0.4.2

package/template/scripts/client-boundary.ts

@@ -0,0 +1,148 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+/**
+ * What a `'use client'` graph is allowed to reach.
+ *
+ * The project declaration is not application data — it is what the repository
+ * says about how it is built and run: role commands, working directories,
+ * artifact and migration paths, and the name of every environment variable a
+ * deployment supplies. One `import` from a module a client component happens to
+ * use puts all of it, plus the Zod schema that parses it, into the browser
+ * bundle. That is the exact mistake `app-identity.generated.ts` exists to
+ * prevent, made from the other side — and it shipped, because nothing checked
+ * the graph, only the file that imports directly.
+ *
+ * The check is a resolved FILE, not a spelling. Matching the string
+ * `@app/config/declaration` catches the one way the leak was written the first
+ * time and misses the two ways it comes back: a barrel that re-exports it, and
+ * a relative path into the config package. Both end at the same file, so that
+ * is what this follows.
+ */
+export interface ClientBoundaryScan {
+  /** Repository root — where `packages/<name>` lives. */
+  root: string;
+  /** The client graph's entry directory. */
+  frontendSrc: string;
+  /** The module no client graph may reach. */
+  declaration: string;
+}
+
+export function sourceFiles(directory: string): string[] {
+  const found: string[] = [];
+  for (const entry of readdirSync(directory)) {
+    const path = join(directory, entry);
+    if (statSync(path).isDirectory()) {
+      if (entry === 'node_modules' || entry === 'generated') continue;
+      found.push(...sourceFiles(path));
+    } else if (/\.tsx?$/.test(entry)) {
+      found.push(path);
+    }
+  }
+  return found;
+}
+
+/**
+ * Every module specifier in a source file, in either quote style.
+ *
+ * Formatting is enforced elsewhere, which is exactly why this must not depend
+ * on it: a check that only reads the house style stops being a check the day
+ * someone pastes a line from somewhere else.
+ */
+export function specifiers(source: string): string[] {
+  const quoted = `'([^']+)'|"([^"]+)"`;
+  return [
+    // `import … from 'x'` and `export … from 'x'`.
+    ...[...source.matchAll(new RegExp(String.raw`from\s+(?:${quoted})`, 'g'))],
+    // `import 'x'` and `import('x')`. Written out because a side-effect import
+    // has no `from` — and a module pulled in for its side effects is in the
+    // bundle exactly as much as one whose value is used.
+    ...[...source.matchAll(new RegExp(String.raw`import\s*\(?\s*(?:${quoted})`, 'g'))],
+  ].flatMap((match) => {
+    const specifier = match[1] ?? match[2];
+    return specifier ? [specifier] : [];
+  });
+}
+
+function firstExistingFile(base: string): string | undefined {
+  for (const candidate of [
+    base,
+    `${base}.ts`,
+    `${base}.tsx`,
+    join(base, 'index.ts'),
+    join(base, 'index.tsx'),
+  ]) {
+    if (existsSync(candidate) && statSync(candidate).isFile()) return candidate;
+  }
+  return undefined;
+}
+
+/** `@app/config/declaration` → the file its package's `exports` map names. */
+function resolveWorkspace(scan: ClientBoundaryScan, specifier: string): string | undefined {
+  const parts = specifier.split('/');
+  if (parts[0] !== '@app' || !parts[1]) return undefined;
+  const packageRoot = join(scan.root, 'packages', parts[1]);
+  const manifestPath = join(packageRoot, 'package.json');
+  if (!existsSync(manifestPath)) return undefined;
+  const subpath = parts.length > 2 ? `./${parts.slice(2).join('/')}` : '.';
+  const manifest: unknown = JSON.parse(readFileSync(manifestPath, 'utf8'));
+  const exportsField =
+    typeof manifest === 'object' && manifest !== null
+      ? Reflect.get(manifest, 'exports')
+      : undefined;
+  const target =
+    typeof exportsField === 'object' && exportsField !== null
+      ? Reflect.get(exportsField, subpath)
+      : undefined;
+  if (typeof target !== 'string') return undefined;
+  return firstExistingFile(resolve(packageRoot, target));
+}
+
+export function resolveSpecifier(
+  scan: ClientBoundaryScan,
+  from: string,
+  specifier: string,
+): string | undefined {
+  if (specifier.startsWith('@app/')) return resolveWorkspace(scan, specifier);
+  const base = specifier.startsWith('@/')
+    ? join(scan.frontendSrc, specifier.slice(2))
+    : specifier.startsWith('.')
+      ? resolve(dirname(from), specifier)
+      : undefined;
+  return base ? firstExistingFile(base) : undefined;
+}
+
+/** The import chain from a client entry to the declaration, if one exists. */
+export function pathToDeclaration(
+  scan: ClientBoundaryScan,
+  entry: string,
+): string[] | undefined {
+  const seen = new Set<string>();
+  const queue: Array<{ file: string; chain: string[] }> = [{ file: entry, chain: [entry] }];
+  while (queue.length > 0) {
+    const step = queue.shift();
+    if (!step || seen.has(step.file)) continue;
+    seen.add(step.file);
+    const source = readFileSync(step.file, 'utf8');
+    for (const specifier of specifiers(source)) {
+      const next = resolveSpecifier(scan, step.file, specifier);
+      if (next === scan.declaration) return [...step.chain, next];
+      if (next && !seen.has(next)) queue.push({ file: next, chain: [...step.chain, next] });
+    }
+  }
+  return undefined;
+}
+
+export function clientEntries(scan: ClientBoundaryScan): string[] {
+  return sourceFiles(scan.frontendSrc).filter((file) =>
+    /^\s*['"]use client['"]/m.test(readFileSync(file, 'utf8')),
+  );
+}
+
+/** Every client entry whose graph reaches the declaration, as a readable chain. */
+export function findDeclarationLeaks(scan: ClientBoundaryScan): string[][] {
+  return clientEntries(scan).flatMap((entry) => {
+    const chain = pathToDeclaration(scan, entry);
+    return chain ? [chain] : [];
+  });
+}

package/template/scripts/declaration.ts

@@ -1,11 +1,12 @@
 import { resolve } from 'node:path';
-import { z } from 'zod';
-import { appDeclaration } from '../packages/config/src/declaration';
 import type {
   ProjectDeclaration,
   ProjectEnvVariable,
   ProjectRole,
-} from '../packages/config/src/project-declaration.generated';
+} from 'stitchkit/declaration';
+import { z } from 'zod';
+import { appDeclaration } from '../packages/config/src/declaration';
+import * as shutdownBudgets from '../packages/config/src/shutdown';
 import { applicationVariables } from '../packages/config/src/variables';
 
 /**
@@ -52,12 +53,14 @@ export const LOCAL_SUPERVISION: SupervisionPolicy = {
  * the earlier check, comparing against the floor only, reported that supervision
  * "allows the full shutdown" while 15s + 5s met a 20s kill timeout exactly.
  */
-const FORCE_BUDGET_MS = 5_000;
-const CLEANUP_MARGIN_MS = 5_000;
+// Imported, not restated: the role enforces these, and a number in two places
+// is two numbers that can disagree — which is exactly how a 15s drain met a
+// 20s kill timeout.
+const { FORCE_BUDGET_MS, CLEANUP_BUDGET_MS } = shutdownBudgets;
 
 /** The shortest time a supervisor may allow this role and still see it finish. */
 export function terminationBudgetMs(role: ProjectRole): number {
-  return role.drainFloorMs + FORCE_BUDGET_MS + CLEANUP_MARGIN_MS;
+  return role.drainFloorMs + FORCE_BUDGET_MS + CLEANUP_BUDGET_MS;
 }
 
 /**
@@ -165,7 +168,7 @@ export function assertSupervisionAllowsShutdown(
     const budget = terminationBudgetMs(role);
     if (budget > killTimeoutMs) {
       throw new Error(
-        `Role "${role.name}" needs up to ${budget}ms to finish shutting down (${role.drainFloorMs}ms drain + ${FORCE_BUDGET_MS}ms force + ${CLEANUP_MARGIN_MS}ms cleanup) but supervision allows ${killTimeoutMs}ms — it would be killed mid-shutdown.`,
+        `Role "${role.name}" needs up to ${budget}ms to finish shutting down (${role.drainFloorMs}ms drain + ${FORCE_BUDGET_MS}ms force + ${CLEANUP_BUDGET_MS}ms cleanup) but supervision allows ${killTimeoutMs}ms — it would be killed mid-shutdown.`,
       );
     }
   }

package/template/scripts/deployment-preflight.ts

@@ -0,0 +1,41 @@
+/**
+ * The deployment a runtime smoke dials has to be there.
+ *
+ * `runtime:smoke` checks a RUNNING deployment — that is what makes it a runtime
+ * smoke rather than a build check. Without this the first `fetch` inside some
+ * assertion fails with a bare `ECONNRESET`, which reads like a broken check
+ * instead of an absent deployment and says nothing about what to do next. The
+ * packed lane never saw it because the lane starts the roles itself; everyone
+ * following the README's gate list saw it first.
+ */
+export async function assertDeploymentIsAnswering(
+  origins: Readonly<Record<string, string>>,
+): Promise<void> {
+  const closed: string[] = [];
+  for (const [role, origin] of Object.entries(origins)) {
+    if (!(await answers(origin))) closed.push(`${role} (${origin})`);
+  }
+  if (closed.length === 0) return;
+  throw new Error(
+    [
+      `Nothing is listening for ${closed.join(' and ')}.`,
+      '`runtime:smoke` checks a deployment that is already running, and the one it is about is',
+      'the artifact `bun run build` produced: start it with `bun run pm2:prod`, then rerun.',
+      '(`bun run dev` serves it too, from a development build.)',
+      'If the deployment is somewhere else, point SMOKE_API_ORIGIN and SMOKE_WEB_ORIGIN at it.',
+    ].join(' '),
+  );
+}
+
+/**
+ * Answering, not healthy: the checks that follow are what judge health. A role
+ * that returns 404 for `/` has still proved the thing this asks about.
+ */
+async function answers(origin: string): Promise<boolean> {
+  try {
+    await fetch(new URL(origin), { method: 'HEAD', signal: AbortSignal.timeout(10_000) });
+    return true;
+  } catch {
+    return false;
+  }
+}

package/template/scripts/dev.ts

@@ -2,6 +2,7 @@ import { resolve } from 'node:path';
 import { z } from 'zod';
 import { appDeclaration } from '../packages/config/src/declaration';
 import { ensureLocalEnvironment } from './local-env';
+import { awaitRolesAnswering, declaredRoleReadiness } from './readiness';
 import { runDeclaredReleaseSteps } from './release-steps';
 import { inheritToolingEnvironment } from './tooling-env';
 
@@ -121,11 +122,12 @@ if (import.meta.main) {
   await runDevelopment();
 
   const environment = await developmentEnvironment();
+  const roles = declaredRoleReadiness(appDeclaration, environment);
+  // Reported only once it is TRUE. The supervisor returns at the spawn, and a
+  // development build needs seconds after that before it listens — so the line
+  // below used to be printed at a moment when nothing answered, and the next
+  // command in the gate list got a connection reset.
+  await awaitRolesAnswering(roles);
   console.log(`${appDeclaration.identity.name} development processes are running`);
-  for (const role of appDeclaration.roles) {
-    if (!role.listener) continue;
-    const port = environment[role.listener.portVariable];
-    const readiness = role.listener.readinessPath;
-    console.log(`${role.name}: http://${environment.BIND_HOST}:${port}${readiness}`);
-  }
+  for (const role of roles) console.log(`${role.name}: ${role.url}`);
 }

package/template/scripts/local-env.ts

@@ -1,10 +1,16 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { appDeclaration } from '../packages/config/src/declaration';
+import { appIdentity } from '../packages/config/src/app-identity.generated';
 
 /**
  * Create `.env` from `.env.example` on first run, rendering the application
- * identity into the database name. `.env.example` is the ONLY environment
+ * identity into the database name.
+ *
+ * Identity, not the whole declaration: this needs one slug, and the identity
+ * module carries no dependencies. That matters here more than elsewhere —
+ * a project scaffolded with `--no-install` renders its `.env` before anything
+ * is installed, and a script that reaches for the framework's schema to read a
+ * name cannot run in that window. `.env.example` is the ONLY environment
  * source the repository ships — the scaffolder never writes `.env`, so a
  * rename in `project.json` changes the database of the next created
  * environment too. Synchronous on purpose: `playwright.config.ts` and other
@@ -14,7 +20,7 @@ export function ensureLocalEnvironment(root: string): void {
   const destination = resolve(root, '.env');
   if (existsSync(destination)) return;
   const example = readFileSync(resolve(root, '.env.example'), 'utf8');
-  const databaseName = appDeclaration.identity.slug.replaceAll('-', '_');
+  const databaseName = appIdentity.slug.replaceAll('-', '_');
   writeFileSync(destination, example.replaceAll('stitchkit_starter', databaseName));
 }
 

package/template/scripts/readiness.ts

@@ -0,0 +1,92 @@
+import type { ProjectDeclaration } from 'stitchkit/declaration';
+
+/** Where a declared role answers once it is ready. */
+export interface RoleReadiness {
+  name: string;
+  url: string;
+}
+
+/**
+ * The readiness address of every role that listens — from the DECLARATION.
+ *
+ * Which variable holds the port and which holds the bind address are the
+ * role's own statement, so a new role is covered by declaring it rather than by
+ * a second list here that would go stale.
+ */
+export function declaredRoleReadiness(
+  declaration: ProjectDeclaration,
+  environment: Record<string, string | undefined>,
+): RoleReadiness[] {
+  return declaration.roles.flatMap((role) => {
+    const listener = role.listener;
+    if (!listener) return [];
+    const port = environment[listener.portVariable];
+    // Not skipped: a role that declares a listener and has no port is a
+    // deployment that cannot have started it, and quietly waiting for nothing
+    // is the failure this module exists to remove.
+    if (!port) {
+      throw new Error(
+        `Role "${role.name}" declares a listener on ${listener.portVariable}, and this environment does not set it.`,
+      );
+    }
+    // `0.0.0.0` is what a role BINDS, never an address to dial: it means every
+    // interface, and loopback is the one this machine can always reach.
+    const bind = environment[listener.bindVariable];
+    const host = !bind || bind === '0.0.0.0' || bind === '::' ? '127.0.0.1' : bind;
+    return [
+      { name: role.name, url: `http://${authority(host, port)}${listener.readinessPath}` },
+    ];
+  });
+}
+
+/**
+ * An IPv6 literal is bracketed; everything else is written as it stands.
+ *
+ * `http://::1:3211/health` is not an address with a port — it is not a URL at
+ * all, and `fetch` refuses it. A role bound to a specific IPv6 address is a
+ * legitimate deployment, and it used to make the readiness wait fail on the
+ * spelling rather than on the role.
+ */
+function authority(host: string, port: string): string {
+  const literal = host.includes(':') && !host.startsWith('[');
+  return `${literal ? `[${host}]` : host}:${port}`;
+}
+
+/**
+ * Wait until every role answers — because starting is not running.
+ *
+ * A supervisor returns as soon as it has SPAWNED a process, and a role needs
+ * seconds after that before it listens. Printing "running" at the moment of the
+ * spawn is a claim nobody checked: the next command in the gate list dialled
+ * the declared port and got a connection reset, which reads as a broken check
+ * rather than an application still booting.
+ */
+export async function awaitRolesAnswering(
+  roles: readonly RoleReadiness[],
+  { timeoutMs = 120_000 }: { timeoutMs?: number } = {},
+): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  const pending = [...roles];
+  while (pending.length > 0) {
+    const role = pending[0];
+    if (!role) break;
+    if (await answers(role.url)) {
+      pending.shift();
+      continue;
+    }
+    if (Date.now() >= deadline) {
+      throw new Error(
+        `${role.name} did not answer at ${role.url} within ${Math.round(timeoutMs / 1000)}s. It is under the supervisor but not serving — read its output with \`pm2 logs\`.`,
+      );
+    }
+    await Bun.sleep(250);
+  }
+}
+
+async function answers(url: string): Promise<boolean> {
+  try {
+    return (await fetch(url, { signal: AbortSignal.timeout(5_000) })).ok;
+  } catch {
+    return false;
+  }
+}

package/template/scripts/release-steps.ts

@@ -1,7 +1,8 @@
 import { existsSync } from 'node:fs';
 import { resolve } from 'node:path';
+import type { ProjectDeclaration } from 'stitchkit/declaration';
 import { appDeclaration } from '../packages/config/src/declaration';
-import type { ProjectDeclaration } from '../packages/config/src/project-declaration.generated';
+import { assertArtifactMatchesSource } from './build-stamp';
 import { inheritToolingEnvironment } from './tooling-env';
 
 const root = resolve(import.meta.dir, '..');
@@ -87,6 +88,9 @@ export function assertBuildArtifacts(declaration: ProjectDeclaration = appDeclar
       `Missing build artifacts: ${missing.join(', ')} — run \`${formatCommand(build.command)}\` first.`,
     );
   }
+  // Present is not current. Without this, a release applies THIS source's
+  // migrations and then starts the previous source's artifact.
+  assertArtifactMatchesSource(root);
 }
 
 export async function runDeclaredReleaseSteps(

package/template/scripts/release.ts

@@ -1,6 +1,8 @@
 import { resolve } from 'node:path';
 import { appDeclaration } from '../packages/config/src/declaration';
+import { awaitRolesAnswering, declaredRoleReadiness } from './readiness';
 import { assertBuildArtifacts, runDeclaredReleaseSteps } from './release-steps';
+import { deploymentEnvironment } from './tooling-env';
 
 /**
  * Bring this deployment to this source, then hand the roles to the supervisor.
@@ -25,6 +27,12 @@ const supervisor = Bun.spawn(['pm2', 'startOrReload', 'ecosystem.config.cjs', '-
 const exitCode = await supervisor.exited;
 if (exitCode !== 0) process.exit(exitCode);
 
+// Under supervision is not yet serving. A release that returns before the
+// roles answer makes every command after it — a smoke, a health check, a
+// rollout step — race the application it just started.
+const roles = declaredRoleReadiness(appDeclaration, deploymentEnvironment(root));
+await awaitRolesAnswering(roles);
 for (const role of appDeclaration.roles) {
   console.log(`${appDeclaration.identity.slug}-${role.name} is under supervision`);
 }
+for (const role of roles) console.log(`${role.name}: ${role.url}`);

package/template/scripts/runtime-smoke.test.ts

@@ -0,0 +1,178 @@
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { appDeclaration } from '../packages/config/src/declaration';
+import { declaredRoleReadiness } from './readiness';
+import { planPortabilityCheck } from './web-surface-smoke';
+
+const dialled = 'http://127.0.0.1:3210';
+
+describe('the portability check dials addresses the deployment claims', () => {
+  test('two claimed addresses besides the dialled one become the two probes', () => {
+    const plan = planPortabilityCheck(dialled, {
+      hosts: '127.0.0.1:3210,alpha.example,beta.example:8443',
+    });
+    expect(plan.kind).toBe('check');
+    if (plan.kind !== 'check') return;
+    expect(plan.addresses).toEqual([
+      { host: 'alpha.example', proto: 'https' },
+      { host: 'beta.example:8443', proto: 'http' },
+    ]);
+  });
+
+  test('a deployment with nothing but its own address is told what to add', () => {
+    // The reported failure, from the other side: the check used to carry two
+    // fixture hosts of its own, so a deployment that had never been told about
+    // them refused the request and the gate showed a bare 500.
+    const plan = planPortabilityCheck(dialled, { hosts: '127.0.0.1:3210' });
+    expect(plan.kind).toBe('refuse');
+    if (plan.kind !== 'refuse') return;
+    expect(plan.reason).toContain(
+      'PUBLIC_WEB_HOSTS=127.0.0.1:3210,alpha.example,beta.example:8443',
+    );
+    expect(plan.reason).toContain('bun run dev');
+  });
+
+  test('a deployment that claims nothing at all is refused the same way', () => {
+    const plan = planPortabilityCheck(dialled, {});
+    expect(plan.kind).toBe('refuse');
+    if (plan.kind !== 'refuse') return;
+    expect(plan.reason).toContain('no host at all');
+  });
+
+  test('a pinned public origin is a skip with a reason, not a failure', () => {
+    // PUBLIC_WEB_ORIGIN short-circuits the request-derived origin, so the
+    // deployment answers with one address whatever it is asked on. That is a
+    // legitimate configuration; failing it would be a false diagnosis.
+    const plan = planPortabilityCheck(dialled, {
+      origin: 'https://example.com',
+      hosts: '127.0.0.1:3210,alpha.example,beta.example:8443',
+    });
+    expect(plan.kind).toBe('skip');
+    if (plan.kind !== 'skip') return;
+    expect(plan.reason).toContain('https://example.com');
+  });
+
+  test('the forged host is never one the deployment claims', () => {
+    // Otherwise the refusal the check exists to provoke never happens, and an
+    // assertion that cannot fail is worse than no assertion.
+    const plan = planPortabilityCheck(dialled, {
+      hosts: '127.0.0.1:3210,alpha.example,beta.example:8443,attacker.example',
+    });
+    expect(plan.kind).toBe('check');
+    if (plan.kind !== 'check') return;
+    expect(plan.forgedHost).not.toBe('attacker.example');
+    expect(plan.forgedHost).toBe('attacker-1.invalid');
+  });
+
+  test('one host written twice is one address, not two', () => {
+    // The count decides whether the property can be proved at all. Without
+    // deduplication a duplicate entry passed as a second address and the check
+    // compared the deployment with itself — a proof that cannot fail.
+    const plan = planPortabilityCheck(dialled, {
+      hosts: '127.0.0.1:3210,alpha.example,alpha.example',
+    });
+    expect(plan.kind).toBe('refuse');
+  });
+
+  test('the claimed list is matched case-insensitively, like the policy that reads it', () => {
+    const plan = planPortabilityCheck('http://127.0.0.1:3210', {
+      hosts: ' 127.0.0.1:3210 , Alpha.Example , BETA.example:8443 ',
+    });
+    expect(plan.kind).toBe('check');
+    if (plan.kind !== 'check') return;
+    expect(plan.addresses.map((address) => address.host)).toEqual([
+      'alpha.example',
+      'beta.example:8443',
+    ]);
+  });
+});
+
+describe('a gate list is not a deploy instruction', () => {
+  // `runtime:smoke` and `e2e` check a running deployment, so the list has to
+  // bring one up — and the wrong way to do that shipped once already:
+  // `pm2:prod` applies the declared migrations and reloads the deployment the
+  // developer is running. A gate creates and destroys its OWN deployment, and
+  // that is `acceptance:local`.
+  const root = resolve(import.meta.dir, '..');
+  const guidance = ['README.md', 'AGENTS.md'];
+
+  for (const file of guidance) {
+    const text = readFileSync(resolve(root, file), 'utf8');
+    const blocks = [...text.matchAll(/```bash\n([\s\S]*?)```/g)].map(([, body]) => body ?? '');
+    const gates = blocks.filter((body) => body.includes('bun run check'));
+
+    test(`${file} lists gates`, () => {
+      expect(gates.length).toBeGreaterThan(0);
+    });
+
+    test(`${file} puts no deployment command in the gate list`, () => {
+      for (const body of gates) {
+        expect(body).not.toContain('pm2:prod');
+      }
+    });
+
+    test(`${file} brings a deployment up before the checks that dial one`, () => {
+      for (const body of gates) {
+        const lines = body.split('\n').map((line) => line.trim());
+        const dialling = ['bun run runtime:smoke', 'bun run e2e'].filter((command) =>
+          lines.includes(command),
+        );
+        if (dialling.length === 0) {
+          expect(lines).toContain('bun run acceptance:local');
+          continue;
+        }
+        const start = lines.indexOf('bun run acceptance:local');
+        expect(start).toBeGreaterThanOrEqual(0);
+        for (const command of dialling) expect(start).toBeLessThan(lines.indexOf(command));
+      }
+    });
+
+    test(`${file} never tells anyone to delete every supervised application`, () => {
+      // `pm2 delete all` empties the daemon it is pointed at, including
+      // applications that have nothing to do with this project.
+      expect(text).not.toContain('pm2 delete all');
+    });
+  }
+});
+
+describe('a role is ready when it answers, not when it is spawned', () => {
+  const environment = { API_PORT: '3211', WEB_PORT: '3210', BIND_HOST: '127.0.0.1' };
+
+  test('every listening role gets its declared readiness address', () => {
+    expect(declaredRoleReadiness(appDeclaration, environment)).toEqual([
+      { name: 'api', url: 'http://127.0.0.1:3211/health' },
+      { name: 'web', url: 'http://127.0.0.1:3210/' },
+    ]);
+  });
+
+  test('a bind address of every interface is dialled on loopback', () => {
+    // `0.0.0.0` is what a role BINDS. Dialling it as an address is a different
+    // question, and loopback is the one this machine can always answer.
+    const addresses = declaredRoleReadiness(appDeclaration, {
+      ...environment,
+      BIND_HOST: '0.0.0.0',
+    });
+    expect(addresses.every((role) => role.url.startsWith('http://127.0.0.1:'))).toBe(true);
+  });
+
+  test('an IPv6 bind address is bracketed, or it is not a URL at all', () => {
+    // `http://::1:3211/health` cannot be parsed as an address with a port, so
+    // the wait failed on the spelling instead of on the role.
+    const addresses = declaredRoleReadiness(appDeclaration, {
+      ...environment,
+      BIND_HOST: '::1',
+    });
+    expect(addresses.map((role) => role.url)).toEqual([
+      'http://[::1]:3211/health',
+      'http://[::1]:3210/',
+    ]);
+    for (const role of addresses) expect(() => new URL(role.url)).not.toThrow();
+  });
+
+  test('a declared listener with no port is an error, not a silent skip', () => {
+    expect(() =>
+      declaredRoleReadiness(appDeclaration, { ...environment, WEB_PORT: undefined }),
+    ).toThrow(/WEB_PORT/);
+  });
+});

package/template/scripts/runtime-smoke.ts

@@ -1,6 +1,7 @@
 import { systemContract } from '@app/shared';
 import { createClient, createHttpClient } from 'stitchkit';
 import { z } from 'zod';
+import { assertDeploymentIsAnswering } from './deployment-preflight';
 import { runSurfaceConformance } from './surface-conformance';
 import { loadToolingEnv } from './tooling-env';
 import { assertArtifactIsPlacementFree, assertPublicWebSurface } from './web-surface-smoke';
@@ -8,8 +9,17 @@ import { assertArtifactIsPlacementFree, assertPublicWebSurface } from './web-sur
 const toolingEnv = loadToolingEnv();
 const apiOrigin = toolingEnv.SMOKE_API_ORIGIN;
 
+await assertDeploymentIsAnswering({
+  'the API role': apiOrigin,
+  'the web role': toolingEnv.SMOKE_WEB_ORIGIN,
+});
+
 async function json(path: string): Promise<unknown> {
-  const response = await fetch(`${apiOrigin}${path}`);
+  // Bounded: an endpoint that accepts the connection and never answers must
+  // turn this gate red, not hang it with no output and no deadline.
+  const response = await fetch(`${apiOrigin}${path}`, {
+    signal: AbortSignal.timeout(30_000),
+  });
   if (!response.ok) throw new Error(`GET ${path} returned ${response.status}`);
   return response.json();
 }
@@ -29,7 +39,10 @@ if (!Object.keys(openApi.paths).includes('/api/system/status')) {
 
 await runSurfaceConformance({ apiOrigin });
 await assertPublicWebSurface(toolingEnv.SMOKE_WEB_ORIGIN);
-await assertArtifactIsPlacementFree(toolingEnv.SMOKE_WEB_ORIGIN);
+await assertArtifactIsPlacementFree(toolingEnv.SMOKE_WEB_ORIGIN, {
+  origin: toolingEnv.PUBLIC_WEB_ORIGIN,
+  hosts: toolingEnv.PUBLIC_WEB_HOSTS,
+});
 
 console.log(
   'Runtime HTTP, typed client, OpenAPI, MCP, public web and placement-free artifact smoke passed',

package/template/scripts/shutdown-budget.fixture.ts

@@ -0,0 +1,29 @@
+/**
+ * A role whose cleanup will not complete, as a real process.
+ *
+ * The regression this serves cannot be written against a promise. The defect
+ * was never "the helper resolved late" — it was that the role set
+ * `process.exitCode` and then waited for an event loop something was still
+ * holding, so the process lived until the supervisor's SIGKILL: exactly the
+ * ending the cleanup budget exists to prevent. Only a process can show that.
+ *
+ * The interval below is the held handle. Nothing ever clears it, so this
+ * process ends only if something ends it — which is the assertion.
+ */
+import { closeWithinBudget, concludeShutdown } from '../packages/backend/src/cleanup';
+
+setInterval(() => undefined, 1_000);
+
+const budgetMs = Number(Bun.argv[2] ?? '200');
+const mode = Bun.argv[3] ?? 'hang';
+
+const steps = {
+  hang: { name: 'database', close: () => new Promise<void>(() => undefined) },
+  throw: { name: 'database', close: () => Promise.reject(new Error('pool already gone')) },
+  clean: { name: 'database', close: () => Promise.resolve() },
+};
+const step = steps[mode === 'throw' ? 'throw' : mode === 'clean' ? 'clean' : 'hang'];
+
+const result = await closeWithinBudget([step], budgetMs);
+console.log(`FIXTURE ${JSON.stringify({ unfinished: result.unfinished })}`);
+concludeShutdown(result, true);