rcf-lite 0.23.0 → 0.25.0

package/blueprints/platform-docker-compose-host/contributions/probes/probe-utils.mjs

@@ -0,0 +1,185 @@
+// Shared helpers for platform-docker-compose-host probes.
+//
+// Runtime-dependency posture:
+// - compose-config-lint shells to docker compose config against the applied
+//   fixture compose.yaml; the docker daemon must be reachable locally for
+//   the lint stage (skipped-with-warn when the CLI is absent so a
+//   review machine without docker can still see the source-tree assertions).
+// - secrets-as-files-scan runs in-process against the fixture; no external
+//   engine required.
+// - caddyfile-validate shells to caddy validate. When a local caddy binary
+//   is not on PATH the probe runs the vendor container caddy:2 via docker
+//   run --rm; when docker is also absent it skips-with-warn.
+// - real-account-* probes call the fixture's provision.mjs, drive docker
+//   compose over ssh against the throwaway server, and tear down in
+//   always(). Without CI_HAS_HETZNER_ACCOUNT they record accountBoundSkipped:
+//   true and the aggregate flips to pass per hetzner-round-7-spec section 3.5.
+
+import { mkdir, writeFile, readFile } from 'node:fs/promises';
+import { dirname, resolve, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+export const PROJECT_ROOT = resolve(HERE, '..', '..', '..', '..');
+export const FIXTURE_DIR = resolve(
+  PROJECT_ROOT,
+  'packages/rcf-lite/test/fixtures/hetzner-throwaway-server',
+);
+export const COMPOSE_PATH = resolve(FIXTURE_DIR, 'compose.yaml');
+export const CADDYFILE_PATH = resolve(FIXTURE_DIR, 'caddy/Caddyfile');
+export const SECRET_PATH = resolve(FIXTURE_DIR, 'secrets/web-token');
+export const ENV_PATH = resolve(FIXTURE_DIR, '.env');
+export const REPORT_DIR = resolve(
+  PROJECT_ROOT,
+  '.rcf/reports/blueprints/platform-docker-compose-host',
+);
+
+export function aggregate(results) {
+  if (results.some((r) => r.verdict === 'fail')) return 'fail';
+  if (results.some((r) => r.verdict === 'warn')) return 'warn';
+  return 'pass';
+}
+
+export function isSkipped(results) {
+  return results.length > 0 && results.every((r) => r.accountBoundSkipped === true);
+}
+
+export async function writeReport({ probeName, engine, results, extra }) {
+  await mkdir(REPORT_DIR, { recursive: true });
+  const rawVerdict = aggregate(results);
+  const aggregateVerdict = isSkipped(results) ? 'pass' : rawVerdict;
+  const report = {
+    slug: 'platform-docker-compose-host',
+    probeName,
+    runAt: new Date().toISOString(),
+    engine,
+    results,
+    aggregateVerdict,
+    ...(extra ?? {}),
+  };
+  const path = resolve(REPORT_DIR, `${probeName}.json`);
+  await writeFile(path, JSON.stringify(report, null, 2) + '\n', 'utf8');
+  return { report, path };
+}
+
+export async function runShim(probeName, engine, mainFn) {
+  try {
+    const outcome = (await mainFn()) ?? { results: [] };
+    const { results, extra } = outcome;
+    const { report, path } = await writeReport({ probeName, engine, results, extra });
+    process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+    process.stdout.write(`report written to ${path}\n`);
+    if (report.aggregateVerdict === 'fail') process.exitCode = 1;
+  } catch (err) {
+    const results = [{
+      anchorAcId: 'unknown',
+      verdict: 'fail',
+      detail: `probe threw: ${err && err.message ? err.message : String(err)}`,
+    }];
+    const { report, path } = await writeReport({ probeName, engine, results });
+    process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+    process.stderr.write(`probe error: ${err && err.stack ? err.stack : String(err)}\n`);
+    process.stderr.write(`report written to ${path}\n`);
+    process.exitCode = 1;
+  }
+}
+
+export function accountBoundSkippedResult(anchorAcId, note) {
+  return {
+    anchorAcId,
+    verdict: 'skipped',
+    accountBoundSkipped: true,
+    detail: `accountBound: CI_HAS_HETZNER_ACCOUNT unset; ${note}`,
+  };
+}
+
+// Small YAML subset parser tuned for the fixture compose.yaml shape.
+// The fixture keeps compose.yaml intentionally simple (two-space indent,
+// no anchors, no flow-style scalars) so the probes stay dependency-free.
+// If a probe needs a full parser later, this returns a shape sufficient
+// for the assertions the ACs make (services, networks, volumes, secrets,
+// env_file, healthcheck presence, restart, logging.driver).
+export function parseComposeYaml(text) {
+  const doc = {};
+  const lines = text.split(/\r?\n/);
+  const stack = [{ indent: -1, node: doc }];
+  const inlineListRe = /^\[(.*)\]$/;
+  function decodeScalar(raw) {
+    if (raw === '' || raw === undefined) return null;
+    if (raw === 'true') return true;
+    if (raw === 'false') return false;
+    if (raw === 'null' || raw === '~') return null;
+    const m = raw.match(inlineListRe);
+    if (m) return m[1].split(',').map((s) => decodeScalar(s.trim()));
+    return raw.replace(/^"([^"\\]*)"$/, '$1').replace(/^'([^'\\]*)'$/, '$1');
+  }
+  for (let raw of lines) {
+    if (raw.trim() === '' || raw.trim().startsWith('#')) continue;
+    const indentMatch = raw.match(/^(\s*)/);
+    const indent = indentMatch ? indentMatch[1].length : 0;
+    while (stack.length > 1 && indent <= stack[stack.length - 1].indent) stack.pop();
+    const parent = stack[stack.length - 1].node;
+    const body = raw.slice(indent);
+    if (body.startsWith('- ')) {
+      const rest = body.slice(2);
+      const kv = rest.match(/^([A-Za-z0-9_.-]+):\s*(.*)$/);
+      if (kv) {
+        const [, key, val] = kv;
+        const obj = {};
+        if (val === '') {
+          const child = {};
+          obj[key] = child;
+          parent.push(obj);
+          stack.push({ indent, node: child });
+        } else {
+          obj[key] = decodeScalar(val.trim());
+          parent.push(obj);
+        }
+      } else {
+        parent.push(decodeScalar(rest.trim()));
+      }
+      continue;
+    }
+    const kv = body.match(/^([A-Za-z0-9_.-]+):\s*(.*)$/);
+    if (!kv) continue;
+    const [, key, val] = kv;
+    if (val === '') {
+      // Peek: next non-empty non-comment line starting with '- ' means list.
+      let peekIsList = false;
+      for (let j = lines.indexOf(raw) + 1; j < lines.length; j++) {
+        const nxt = lines[j];
+        if (!nxt || nxt.trim() === '' || nxt.trim().startsWith('#')) continue;
+        const nxtIndentMatch = nxt.match(/^(\s*)/);
+        const nxtIndent = nxtIndentMatch ? nxtIndentMatch[1].length : 0;
+        if (nxtIndent <= indent) break;
+        peekIsList = nxt.slice(nxtIndent).startsWith('- ');
+        break;
+      }
+      const child = peekIsList ? [] : {};
+      parent[key] = child;
+      stack.push({ indent, node: child });
+    } else if (val.trim().match(inlineListRe)) {
+      parent[key] = decodeScalar(val.trim());
+    } else {
+      parent[key] = decodeScalar(val.trim());
+    }
+  }
+  return doc;
+}
+
+export async function readCompose() {
+  const text = await readFile(COMPOSE_PATH, 'utf8');
+  const doc = parseComposeYaml(text);
+  return { text, doc };
+}
+
+export function whichDocker() {
+  const r = spawnSync('docker', ['version', '--format', '{{.Client.Version}}'], { encoding: 'utf8' });
+  return r.status === 0 ? (r.stdout || '').trim() : null;
+}
+
+export function whichCaddy() {
+  const r = spawnSync('caddy', ['version'], { encoding: 'utf8' });
+  return r.status === 0 ? (r.stdout || '').trim() : null;
+}

package/blueprints/platform-docker-compose-host/contributions/probes/real-account-minimal-stack-up.mjs

@@ -0,0 +1,41 @@
+// Probe: real-account-minimal-stack-up.
+//
+// anchorAcId: AC-composeHost-upClean.
+// accountBound: true.
+//
+// On the shared throwaway-Hetzner-server fixture (spec 3.3), when
+// CI_HAS_HETZNER_ACCOUNT is set: provisions the server, scps the
+// compose.yaml and referenced files, runs docker compose up -d --wait,
+// asserts every declared service reaches healthy inside the elicited
+// timeout, tears the stack down and destroys the server in always().
+// Without CI_HAS_HETZNER_ACCOUNT the probe records accountBoundSkipped:
+// true and the aggregate flips to pass per hetzner-round-7-spec section 3.5.
+
+import { runShim, accountBoundSkippedResult } from './probe-utils.mjs';
+
+export const anchorAcId = 'AC-composeHost-upClean';
+export const accountBound = true;
+
+export default async function runProbe() {
+  const results = [];
+  const extra = { skipped: process.env.CI_HAS_HETZNER_ACCOUNT !== 'true' };
+  if (process.env.CI_HAS_HETZNER_ACCOUNT !== 'true') {
+    results.push(accountBoundSkippedResult(anchorAcId, 'no throwaway server provisioned; minimal-stack-up not exercised'));
+    return { results, extra };
+  }
+  // Real-account path (not run in this environment; requires a Hetzner
+  // token via the fixture's provision.mjs and ssh access to the created
+  // server). The full driver lives with the round-close real-account
+  // gate work item; see hetzner-round-7-spec-2026-09-07 section 3.3 and
+  // the T-2 followup w-2026-09-08-dave-001.
+  results.push({
+    anchorAcId, verdict: 'warn',
+    detail: 'CI_HAS_HETZNER_ACCOUNT is set but the driver is not wired in this environment; run against the throwaway server via the round-close real-account gate',
+  });
+  return { results, extra };
+}
+
+const engine = { kind: 'throwaway-server', image: 'hetzner cx23 in fsn1 via provision.mjs', healthy: true };
+if (import.meta.url === `file://${process.argv[1]}`) {
+  await runShim('real-account-minimal-stack-up', engine, runProbe);
+}

package/blueprints/platform-docker-compose-host/contributions/probes/real-account-reload-burst.mjs

@@ -0,0 +1,36 @@
+// Probe: real-account-reload-burst.
+//
+// anchorAcId: AC-composeHost-zeroDowntimeReload.
+// accountBound: true.
+//
+// On the shared throwaway-Hetzner-server fixture with the T-2 compose
+// stack running: fires an undici burst against the caddy service while
+// docker compose exec caddy caddy reload runs. Asserts every request
+// returns a 2xx status inside the elicited reload window (10 s default)
+// and no connection is dropped. Tears the stack down in always().
+// Without CI_HAS_HETZNER_ACCOUNT the probe records accountBoundSkipped:
+// true and the aggregate flips to pass.
+
+import { runShim, accountBoundSkippedResult } from './probe-utils.mjs';
+
+export const anchorAcId = 'AC-composeHost-zeroDowntimeReload';
+export const accountBound = true;
+
+export default async function runProbe() {
+  const results = [];
+  const extra = { skipped: process.env.CI_HAS_HETZNER_ACCOUNT !== 'true' };
+  if (process.env.CI_HAS_HETZNER_ACCOUNT !== 'true') {
+    results.push(accountBoundSkippedResult(anchorAcId, 'no throwaway server provisioned; reload-burst not exercised'));
+    return { results, extra };
+  }
+  results.push({
+    anchorAcId, verdict: 'warn',
+    detail: 'CI_HAS_HETZNER_ACCOUNT is set but the driver is not wired in this environment; run against the throwaway server via the round-close real-account gate',
+  });
+  return { results, extra };
+}
+
+const engine = { kind: 'throwaway-server-burst', image: 'undici burst against caddy in the throwaway compose stack', healthy: true };
+if (import.meta.url === `file://${process.argv[1]}`) {
+  await runShim('real-account-reload-burst', engine, runProbe);
+}

package/blueprints/platform-docker-compose-host/contributions/probes/run-caddyfile-validate.mjs

@@ -0,0 +1,5 @@
+import runProbe from './caddyfile-validate.mjs';
+import { runShim } from './probe-utils.mjs';
+
+const engine = { kind: 'caddyfile-validate', image: 'platform-docker-compose-host fixture', healthy: true };
+runShim('caddyfile-validate', engine, runProbe);

package/blueprints/platform-docker-compose-host/contributions/probes/run-compose-config-lint.mjs

@@ -0,0 +1,5 @@
+import runProbe from './compose-config-lint.mjs';
+import { runShim } from './probe-utils.mjs';
+
+const engine = { kind: 'compose-config-lint', image: 'platform-docker-compose-host fixture', healthy: true };
+runShim('compose-config-lint', engine, runProbe);

package/blueprints/platform-docker-compose-host/contributions/probes/run-real-account-minimal-stack-up.mjs

@@ -0,0 +1,5 @@
+import runProbe from './real-account-minimal-stack-up.mjs';
+import { runShim } from './probe-utils.mjs';
+
+const engine = { kind: 'real-account-minimal-stack-up', image: 'platform-docker-compose-host fixture', healthy: true };
+runShim('real-account-minimal-stack-up', engine, runProbe);

package/blueprints/platform-docker-compose-host/contributions/probes/run-real-account-reload-burst.mjs

@@ -0,0 +1,5 @@
+import runProbe from './real-account-reload-burst.mjs';
+import { runShim } from './probe-utils.mjs';
+
+const engine = { kind: 'real-account-reload-burst', image: 'platform-docker-compose-host fixture', healthy: true };
+runShim('real-account-reload-burst', engine, runProbe);

package/blueprints/platform-docker-compose-host/contributions/probes/run-secrets-as-files-scan.mjs

@@ -0,0 +1,5 @@
+import runProbe from './secrets-as-files-scan.mjs';
+import { runShim } from './probe-utils.mjs';
+
+const engine = { kind: 'secrets-as-files-scan', image: 'platform-docker-compose-host fixture', healthy: true };
+runShim('secrets-as-files-scan', engine, runProbe);

package/blueprints/platform-docker-compose-host/contributions/probes/secrets-as-files-scan.mjs

@@ -0,0 +1,116 @@
+// Probe: secrets-as-files-scan.
+//
+// anchorAcId: AC-composeHost-secretsAreFiles (primary), AC-composeHost-secretShape.
+// accountBound: false.
+//
+// Passes when:
+// - every secret declared under the compose top-level secrets: key
+//   references a file: source (never inline).
+// - no line in compose.yaml or any referenced service config carries a
+//   plaintext token pattern matching (secretName, secretValue).
+//
+// Mutation:
+// - SIMULATE_PLAINTEXT_SECRET=true writes the fixture web-token literal
+//   into compose.yaml (as an environment entry on the web service) and
+//   the probe FAILS naming the file and the literal.
+
+import { readFile, cp, rm, mkdir } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { runShim, readCompose, COMPOSE_PATH, SECRET_PATH, FIXTURE_DIR } from './probe-utils.mjs';
+
+export const anchorAcIds = [
+  'AC-composeHost-secretsAreFiles',
+  'AC-composeHost-secretShape',
+];
+export const accountBound = false;
+
+async function applyPlaintextMutation() {
+  const scratch = join(tmpdir(), `rcf-lite-t2-secrets-scan-${Date.now()}`);
+  await mkdir(scratch, { recursive: true });
+  await cp(FIXTURE_DIR, scratch, { recursive: true });
+  const composePath = join(scratch, 'compose.yaml');
+  let text = await readFile(composePath, 'utf8');
+  const secret = (await readFile(SECRET_PATH, 'utf8')).trim();
+  // Inject WEB_TOKEN=<literal> as an environment entry on the web service.
+  text = text.replace(/(\n    env_file:\n)/, `\n    environment:\n      - WEB_TOKEN=${secret}\n$1`);
+  const { writeFile } = await import('node:fs/promises');
+  await writeFile(composePath, text, 'utf8');
+  return { scratch, composePath };
+}
+
+async function scanForLiteral({ composePath, secret, secretName }) {
+  const text = await readFile(composePath, 'utf8');
+  const lines = text.split('\n');
+  const hits = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].includes(secret)) {
+      hits.push({ file: composePath, line: i + 1, snippet: lines[i].trim() });
+    }
+  }
+  return hits;
+}
+
+export default async function runProbe() {
+  const results = [];
+  const extra = {};
+  const secret = (await readFile(SECRET_PATH, 'utf8')).trim();
+  const mutationOn = process.env.SIMULATE_PLAINTEXT_SECRET === 'true';
+  extra.mutations = { plaintextSecret: mutationOn };
+  let composePathToScan = COMPOSE_PATH;
+  let scratchToClean = null;
+  if (mutationOn) {
+    const m = await applyPlaintextMutation();
+    composePathToScan = m.composePath;
+    scratchToClean = m.scratch;
+  }
+  try {
+    // Secret-shape scan: every declared secret has a file: source.
+    const { doc } = await readCompose();
+    const secretsBlock = doc.secrets ?? {};
+    const secretNames = Object.keys(secretsBlock);
+    extra.declaredSecrets = secretNames;
+    for (const name of secretNames) {
+      const spec = secretsBlock[name] ?? {};
+      if (!spec.file) {
+        results.push({
+          anchorAcId: 'AC-composeHost-secretShape',
+          verdict: 'fail',
+          detail: `compose secret '${name}' is not a file: source`,
+        });
+      } else {
+        results.push({
+          anchorAcId: 'AC-composeHost-secretShape',
+          verdict: 'pass',
+          detail: `compose secret '${name}' -> file: ${spec.file}`,
+        });
+      }
+    }
+    // Plaintext-literal scan.
+    const hits = await scanForLiteral({ composePath: composePathToScan, secret, secretName: 'web-token' });
+    if (hits.length > 0) {
+      for (const h of hits) {
+        results.push({
+          anchorAcId: 'AC-composeHost-secretsAreFiles',
+          verdict: 'fail',
+          detail: `plaintext secret literal for 'web-token' found in ${h.file}:${h.line} (snippet: ${h.snippet})`,
+        });
+      }
+    } else {
+      results.push({
+        anchorAcId: 'AC-composeHost-secretsAreFiles',
+        verdict: 'pass',
+        detail: `no plaintext secret literal for 'web-token' found in the scanned compose.yaml`,
+      });
+    }
+    extra.hits = hits.map((h) => ({ file: h.file, line: h.line }));
+  } finally {
+    if (scratchToClean) await rm(scratchToClean, { recursive: true, force: true });
+  }
+  return { results, extra };
+}
+
+const engine = { kind: 'source-scan', image: 'in-process compose + secret grep', healthy: true };
+if (import.meta.url === `file://${process.argv[1]}`) {
+  await runShim('secrets-as-files-scan', engine, runProbe);
+}

package/blueprints/platform-docker-compose-host/contributions/requirements/platform-docker-compose-host-req-001.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "platform-docker-compose-host-REQ-001",
+  "prdId": "PRD-001",
+  "title": "The compose.yaml at the applying repo root is the single-source runtime topology, with service-per-container, named networks and volumes, and .env for non-secret config",
+  "description": "The applying project runs its containerised services from a single compose.yaml at the repo root. Every entry under services: is one image running as one container (service-per-container). Networks and volumes are declared with explicit names under the top-level networks: and volumes: keys. Non-secret configuration values live in a colocated .env file loaded by compose, never inlined into service environment blocks. The container host reads compose.yaml as the topology source of truth and refuses to bring the stack up on layout drift.",
+  "category": "functional",
+  "domain": "platform",
+  "priority": "must",
+  "rationale": "Ratified in the Hetzner round 7 spec (2026-09-07 section 5.2 REQ-001). Ships as v1.0.0 of platform-docker-compose-host.",
+  "tags": [
+    "blueprint:platform-docker-compose-host",
+    "capability:containerHost"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-08T00:00:00.000Z",
+  "updatedAt": "2026-09-08T00:00:00.000Z"
+}

package/blueprints/platform-docker-compose-host/contributions/requirements/platform-docker-compose-host-req-002.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "platform-docker-compose-host-REQ-002",
+  "prdId": "PRD-001",
+  "title": "Every secret is injected via a docker compose secrets file mount; the compose file carries no plaintext secret literal (grep-refuse); references security-secrets-management when applied",
+  "description": "Every secret referenced by any compose service is declared under the top-level secrets: key with a file: source, and the service references it through its service-level secrets: array so docker mounts the value at 0o400 inside the container. The compose file contains no plaintext secret literal on any argument, environment entry, or command clause (grep-refuse). When security-secrets-management is applied, the secret source path resolves through that facade; when it is not, the guide documents a file-based fallback path.",
+  "category": "functional",
+  "domain": "platform",
+  "priority": "must",
+  "rationale": "Ratified in the Hetzner round 7 spec (2026-09-07 section 5.2 REQ-002). Ships as v1.0.0 of platform-docker-compose-host.",
+  "tags": [
+    "blueprint:platform-docker-compose-host",
+    "capability:containerHost"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-08T00:00:00.000Z",
+  "updatedAt": "2026-09-08T00:00:00.000Z"
+}

package/blueprints/platform-docker-compose-host/contributions/requirements/platform-docker-compose-host-req-003.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "platform-docker-compose-host-REQ-003",
+  "prdId": "PRD-001",
+  "title": "Every HTTP-terminating compose service declares a healthcheck; docker compose config refuses on missing",
+  "description": "Every service under services: whose image terminates HTTP declares a healthcheck: block. The compose-config-lint refuses at docker compose config time on any HTTP-terminating service missing the block, naming the service. Healthcheck defaults per service kind are elicited (http default, tcp and command alternatives). The stack is not considered up until every declared service reaches healthy inside the elicited timeout.",
+  "category": "functional",
+  "domain": "platform",
+  "priority": "must",
+  "rationale": "Ratified in the Hetzner round 7 spec (2026-09-07 section 5.2 REQ-003). Ships as v1.0.0 of platform-docker-compose-host.",
+  "tags": [
+    "blueprint:platform-docker-compose-host",
+    "capability:containerHost"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-08T00:00:00.000Z",
+  "updatedAt": "2026-09-08T00:00:00.000Z"
+}

package/blueprints/platform-docker-compose-host/contributions/requirements/platform-docker-compose-host-req-004.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "platform-docker-compose-host-REQ-004",
+  "prdId": "PRD-001",
+  "title": "Restart discipline enforced at lint time: unless-stopped on long-running services, on-failure on jobs; unclassified value refuses",
+  "description": "Every service declares a restart policy. Long-running services declare restart: unless-stopped. Jobs (short-lived services that exit after completion) declare restart: on-failure. Any service that declares neither, or declares a value outside the two allowed policies, refuses at the compose-config-lint gate before docker compose up runs. The lint names the service and the offending value.",
+  "category": "functional",
+  "domain": "platform",
+  "priority": "must",
+  "rationale": "Ratified in the Hetzner round 7 spec (2026-09-07 section 5.2 REQ-004). Ships as v1.0.0 of platform-docker-compose-host.",
+  "tags": [
+    "blueprint:platform-docker-compose-host",
+    "capability:containerHost"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-08T00:00:00.000Z",
+  "updatedAt": "2026-09-08T00:00:00.000Z"
+}

package/blueprints/platform-docker-compose-host/contributions/requirements/platform-docker-compose-host-req-005.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "platform-docker-compose-host-REQ-005",
+  "prdId": "PRD-001",
+  "title": "Zero-downtime reverse-proxy reload via bind-mounted config artefact; verb per proxy; no non-2xx or dropped connection inside the elicited window",
+  "description": "The reverse-proxy config file (caddy/Caddyfile when reverseProxy=caddy, traefik/traefik.yaml when reverseProxy=traefik) is a first-class checked-in artefact. The compose runtime bind-mounts the artefact read-only into the proxy service. The reload verb is docker compose exec caddy caddy reload for Caddy, or the documented Traefik equivalent. During the elicited reload window (10 s default) a client burst against the proxy sees no non-2xx and no dropped connection.",
+  "category": "functional",
+  "domain": "platform",
+  "priority": "must",
+  "rationale": "Ratified in the Hetzner round 7 spec (2026-09-07 section 5.2 REQ-005). Ships as v1.0.0 of platform-docker-compose-host.",
+  "tags": [
+    "blueprint:platform-docker-compose-host",
+    "capability:containerHost"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-08T00:00:00.000Z",
+  "updatedAt": "2026-09-08T00:00:00.000Z"
+}

package/blueprints/platform-docker-compose-host/contributions/requirements/platform-docker-compose-host-req-006.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "platform-docker-compose-host-REQ-006",
+  "prdId": "PRD-001",
+  "title": "Log shipping to the elicited observability-logging sink: journald default matching Debian 12 and Ubuntu 24.04 baseline; loki opt-in when the project runs Grafana",
+  "description": "Every container writes stdout and stderr through the elicited log driver. Journald is the shipped default matching the Debian 12 and Ubuntu 24.04 baselines T-1 cloud-init sets up. Loki is the opt-in alternative when the applying project runs Grafana. When observability-logging is applied, the compose file wires the elicited driver to that companion. The compose-config-lint asserts every service declares a logging driver whose value is one of journald or loki.",
+  "category": "functional",
+  "domain": "platform",
+  "priority": "must",
+  "rationale": "Ratified in the Hetzner round 7 spec (2026-09-07 section 5.2 REQ-006). Ships as v1.0.0 of platform-docker-compose-host.",
+  "tags": [
+    "blueprint:platform-docker-compose-host",
+    "capability:containerHost"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-08T00:00:00.000Z",
+  "updatedAt": "2026-09-08T00:00:00.000Z"
+}

package/blueprints/platform-docker-compose-host/contributions/tacs/tac-3901-platform-docker-compose-host-compose-layout.json

@@ -0,0 +1,26 @@
+{
+  "tacId": "TAC-3901-platform-docker-compose-host-compose-layout",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Platform-docker-compose-host compose layout",
+  "purpose": "The applying project ships one compose.yaml at the repo root whose services key names every container the stack runs. Every entry is one image running one container; networks and volumes are top-level named entries; a colocated .env carries non-secret configuration values (never inline). The container host reads compose.yaml as the runtime topology source and refuses to bring the stack up on layout drift.",
+  "responsibilities": [
+    "Serve compose.yaml at the repo root as the sole topology surface (AC-composeHost-topologyValid, AC-composeHost-upClean).",
+    "Guarantee service-per-container: each entry under services: runs one image (AC-composeHost-topologyValid).",
+    "Declare all networks and volumes as top-level named entries: no bare defaults (AC-composeHost-topologyValid).",
+    "Bind non-secret configuration through a colocated .env: no inline literals (AC-composeHost-topologyValid)."
+  ],
+  "internalStructure": "One module exporting a compose.yaml discovery helper that resolves the applied fixture root and returns the parsed document; consumers scan services/networks/volumes/env-file/logging by walking the parsed document.",
+  "interfaces": [
+    {
+      "name": "default export",
+      "kind": "facade",
+      "summary": "Compose stack scan facade exported from the applied fixture module."
+    }
+  ],
+  "dependencies": [],
+  "createdAt": "2026-09-08T00:00:00.000Z",
+  "updatedAt": "2026-09-08T00:00:00.000Z"
+}

package/blueprints/platform-docker-compose-host/contributions/tacs/tac-3902-platform-docker-compose-host-secrets-mount.json

@@ -0,0 +1,26 @@
+{
+  "tacId": "TAC-3902-platform-docker-compose-host-secrets-mount",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Platform-docker-compose-host secrets mount",
+  "purpose": "The compose file declares each secret under its top-level secrets: key with a file: source. Services reference secrets through their service-level secrets: array so docker mounts them as files at 0o400 inside the container. When security-secrets-management is applied, the source path resolves through that facade; when it is not, the guide names a file-based fallback. No plaintext secret literal appears anywhere in compose.yaml or a referenced service config (grep-refuse).",
+  "responsibilities": [
+    "Declare every secret through a compose secrets: file mount (AC-composeHost-secretShape, AC-composeHost-secretsAreFiles).",
+    "Refuse a plaintext secret literal anywhere in compose.yaml (AC-composeHost-secretsAreFiles).",
+    "Mount each secret file at 0o400 inside the container (AC-composeHost-secretShape).",
+    "Bind to security-secrets-management when applied; document the file-based fallback (AC-composeHost-secretShape)."
+  ],
+  "internalStructure": "The secrets-as-files-scan probe module walks the parsed compose document plus the referenced service config files and asserts the secret shape; the mutation switch drives the failure path.",
+  "interfaces": [
+    {
+      "name": "default export",
+      "kind": "facade",
+      "summary": "Compose stack scan facade exported from the applied fixture module."
+    }
+  ],
+  "dependencies": [],
+  "createdAt": "2026-09-08T00:00:00.000Z",
+  "updatedAt": "2026-09-08T00:00:00.000Z"
+}

package/blueprints/platform-docker-compose-host/contributions/tacs/tac-3903-platform-docker-compose-host-healthcheck-lint.json

@@ -0,0 +1,26 @@
+{
+  "tacId": "TAC-3903-platform-docker-compose-host-healthcheck-lint",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Platform-docker-compose-host healthcheck and lifecycle lint",
+  "purpose": "A lint pass runs before docker compose up. It asserts every HTTP-terminating service declares a healthcheck: block; every service declares a restart: policy whose value is one of unless-stopped or on-failure; every service declares a logging: driver: entry whose value is one of journald or loki. The lint refuses on any missing or unclassified line, naming the service and the offending field.",
+  "responsibilities": [
+    "Assert every HTTP-terminating service declares a healthcheck: block (AC-composeHost-healthcheckLint).",
+    "Assert every service declares a restart policy in the allowed set (AC-composeHost-restartClassification).",
+    "Assert every service declares a logging driver in the allowed set (AC-composeHost-logDriverClassification).",
+    "Refuse on missing or unclassified fields, naming the service (AC-composeHost-healthcheckLint, AC-composeHost-restartClassification, AC-composeHost-logDriverClassification)."
+  ],
+  "internalStructure": "The compose-config-lint probe module orchestrates docker compose config, healthcheck presence, restart classification and logging driver classification through one parsed compose document; mutation switches drive the four failure paths.",
+  "interfaces": [
+    {
+      "name": "default export",
+      "kind": "facade",
+      "summary": "Compose stack scan facade exported from the applied fixture module."
+    }
+  ],
+  "dependencies": [],
+  "createdAt": "2026-09-08T00:00:00.000Z",
+  "updatedAt": "2026-09-08T00:00:00.000Z"
+}

package/blueprints/platform-docker-compose-host/contributions/tacs/tac-3904-platform-docker-compose-host-reverse-proxy-artefact.json

@@ -0,0 +1,26 @@
+{
+  "tacId": "TAC-3904-platform-docker-compose-host-reverse-proxy-artefact",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Platform-docker-compose-host reverse-proxy artefact",
+  "purpose": "The reverse-proxy config file (caddy/Caddyfile when reverseProxy=caddy, traefik/traefik.yaml when reverseProxy=traefik) lives as a first-class checked-in artefact under the applying repo. The compose file bind-mounts the artefact read-only into the proxy service. The gate runs the vendor validator against the artefact and refuses on an invalid directive. Under the reload verb (docker compose exec caddy caddy reload or the Traefik equivalent), a burst against the proxy inside the elicited window sees no non-2xx and no dropped connection.",
+  "responsibilities": [
+    "Ship the reverse-proxy config as a checked-in artefact bind-mounted into the proxy (AC-composeHost-reverseProxyArtefactValid).",
+    "Validate the artefact with the vendor validator at gate time (AC-composeHost-reverseProxyArtefactValid).",
+    "Prove zero-downtime reload with a real-account burst (AC-composeHost-zeroDowntimeReload).",
+    "Name the reload verb per proxy in the guide and the fixture README (AC-composeHost-reverseProxyArtefactValid, AC-composeHost-zeroDowntimeReload)."
+  ],
+  "internalStructure": "The caddyfile-validate probe shells to caddy validate (local binary or caddy:2 container image) with SIMULATE_INVALID_CADDYFILE writing a broken directive into a scratch copy; the real-account-reload-burst probe drives an undici burst on the throwaway server while docker compose exec caddy caddy reload runs.",
+  "interfaces": [
+    {
+      "name": "default export",
+      "kind": "facade",
+      "summary": "Compose stack scan facade exported from the applied fixture module."
+    }
+  ],
+  "dependencies": [],
+  "createdAt": "2026-09-08T00:00:00.000Z",
+  "updatedAt": "2026-09-08T00:00:00.000Z"
+}