rcf-lite 0.26.0 → 0.28.0

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

@@ -1,19 +1,32 @@
-// Shared helpers for platform-docker-compose-host probes.
-//
+// Shared helpers for platform-docker-compose-host probes (v1.1.4,
+// v1.1.5, 2026-09-11).
+
+// Every result row a probe returns MUST carry either an `evidence`
+// object naming the observed artefact (compose service list, on-server
+// response body excerpt, burst counters, event body sample) OR
+// `accountBoundSkipped: true` with a `reason` field naming exactly
+// one unset variable (the shape rule). Empty or null probe outcomes
+// FAIL with detail exactly `no checks ran`.
+
 // 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.
+//   engine required. Scans compose.yaml, .env, every service config
+//   under caddy/, secrets/ metadata and the compose secret-shape.
 // - 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.
+//   run --rm; when docker is also absent it skips-with-warn. The probe
+//   also asserts the compose file bind-mounts the Caddyfile read-only.
 // - 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.
+//   always(). Without CI_HAS_HETZNER_ACCOUNT set to exactly the string
+//   "true" the probe records accountBoundSkipped: true and a reason
+//   naming CI_HAS_HETZNER_ACCOUNT (set-but-not-true reported as such,
+//   distinguished from unset). A second-tier HCLOUD_TOKEN unset once
+//   past the first-tier gate has its own honest skip row.
 
 import { mkdir, writeFile, readFile } from 'node:fs/promises';
 import { dirname, resolve, join } from 'node:path';
@@ -30,31 +43,75 @@ 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 const REPORT_DIR = process.env.RCF_REPORT_DIR_OVERRIDE
+  ? resolve(process.env.RCF_REPORT_DIR_OVERRIDE, 'blueprints/platform-docker-compose-host')
+  : resolve(PROJECT_ROOT, '.rcf/reports/blueprints/platform-docker-compose-host');
+export const BLUEPRINT_JSON_PATH = resolve(HERE, '..', '..', 'blueprint.json');
+
+// The report's `version` field is read from the blueprint's own
+// blueprint.json at write time; every regenerated record therefore
+// carries the version the shipped code was at when the record was
+// written. The strict walker compares each record's `version` to
+// blueprint.json's `version` and FAILS on any mismatch (a record
+// at an older version fails the walk). The read is deliberately
+// per-call so a version bump between two writes in one process is
+// picked up honestly.
+async function readBlueprintVersion() {
+  const raw = await readFile(BLUEPRINT_JSON_PATH, 'utf8');
+  const doc = JSON.parse(raw);
+  if (typeof doc.version !== 'string' || doc.version.length === 0) {
+    throw new Error(`blueprint.json at ${BLUEPRINT_JSON_PATH} carries no string version`);
+  }
+  return doc.version;
+}
 
 export function aggregate(results) {
+  if (!Array.isArray(results) || results.length === 0) return 'fail';
   if (results.some((r) => r.verdict === 'fail')) return 'fail';
   if (results.some((r) => r.verdict === 'warn')) return 'warn';
   return 'pass';
 }
 
+// An empty results array is an honest failure of the probe: no anchor
+// can be manufactured. Callers that KNOW the anchor may pass it in;
+// otherwise the row carries anchorAcId: null so downstream tallies do
+// not see an invented AC id.
+export function emptyResultsFail(anchorAcId = null) {
+  return {
+    anchorAcId: anchorAcId ?? null,
+    verdict: 'fail',
+    detail: 'no checks ran',
+    evidence: { reason: 'the probe returned zero result rows', probeName: '(unknown at empty-fail construction)' },
+  };
+}
+
 export function isSkipped(results) {
-  return results.length > 0 && results.every((r) => r.accountBoundSkipped === true);
+  return Array.isArray(results) && 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 rows = Array.isArray(results) && results.length > 0 ? results : [emptyResultsFail()];
+  // the anchor-prefix rule: every row's detail starts with the first eight
+  // words of the anchored AC text. The prepend is idempotent so a
+  // caller that already wrapped its detail via `anchored()` does not
+  // double up.
+  for (const r of rows) {
+    const prefix = r && r.anchorAcId && AC_ANCHOR_PREFIX[r.anchorAcId];
+    if (prefix && typeof r.detail === 'string' && !r.detail.startsWith(prefix)) {
+      r.detail = `${prefix}. ${r.detail}`;
+    }
+  }
+  const rawVerdict = aggregate(rows);
+  const aggregateVerdict = isSkipped(rows) ? 'pass' : rawVerdict;
+  const version = await readBlueprintVersion();
   const report = {
     slug: 'platform-docker-compose-host',
     probeName,
+    version,
     runAt: new Date().toISOString(),
     engine,
-    results,
+    results: rows,
     aggregateVerdict,
     ...(extra ?? {}),
   };
@@ -65,17 +122,26 @@ export async function writeReport({ probeName, engine, results, extra }) {
 
 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 });
+    const outcome = await mainFn();
+    const results = (outcome && Array.isArray(outcome.results)) ? outcome.results : null;
+    const extra = outcome && outcome.extra;
+    const rows = results && results.length > 0 ? results : [emptyResultsFail()];
+    const { report, path } = await writeReport({ probeName, engine, results: rows, 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) {
+    // A probe that throws has no known anchor at this layer; use null
+    // rather than the invented "unknown" fallback (defect).
     const results = [{
-      anchorAcId: 'unknown',
+      anchorAcId: null,
       verdict: 'fail',
       detail: `probe threw: ${err && err.message ? err.message : String(err)}`,
+      evidence: {
+        probeName,
+        errorMessage: err && err.message ? err.message : String(err),
+        errorStack: (err && err.stack ? err.stack : String(err)).slice(0, 800),
+      },
     }];
     const { report, path } = await writeReport({ probeName, engine, results });
     process.stdout.write(JSON.stringify(report, null, 2) + '\n');
@@ -85,21 +151,46 @@ export async function runShim(probeName, engine, mainFn) {
   }
 }
 
-export function accountBoundSkippedResult(anchorAcId, note) {
+// Skip helper (the shape rule): the reason field names exactly one
+// unset variable; the gateState field distinguishes unset from
+// set-but-not-true, so a variable set to `false` is never reported as
+// unset. Callers hand the anchor plus a short note.
+export function firstTierGateSkipResult(anchorAcId, varName = 'CI_HAS_HETZNER_ACCOUNT', note = '') {
+  const observed = process.env[varName];
+  const state = observed === undefined
+    ? `unset`
+    : `set-but-not-true (observed value ${JSON.stringify(observed)})`;
   return {
     anchorAcId,
     verdict: 'skipped',
     accountBoundSkipped: true,
-    detail: `accountBound: CI_HAS_HETZNER_ACCOUNT unset; ${note}`,
+    reason: varName,
+    gateState: state,
+    detail: `accountBoundSkipped: gate variable ${varName} ${state}; ${note || 'run with CI_HAS_HETZNER_ACCOUNT=true to exercise the account-bound branch.'}`,
   };
 }
 
+// Second-tier skip helper (the shape rule): the account-bound branch
+// requires HCLOUD_TOKEN once the first-tier gate is true. When only the
+// second-tier is missing the skip row names HCLOUD_TOKEN literally and
+// still aggregates to pass; missing configuration is a skip, not a
+// failure.
+export function secondTierMissingSkipResult(anchorAcId, varName, note = '') {
+  return {
+    anchorAcId,
+    verdict: 'skipped',
+    accountBoundSkipped: true,
+    reason: varName,
+    gateState: 'unset',
+    detail: `accountBoundSkipped: second-tier variable ${varName} unset while CI_HAS_HETZNER_ACCOUNT=true; ${note || 'the probe cannot open the vendor client.'}`,
+  };
+}
+
+export function accountBoundSkippedResult(anchorAcId, note) {
+  return firstTierGateSkipResult(anchorAcId, 'CI_HAS_HETZNER_ACCOUNT', 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/);
@@ -135,6 +226,15 @@ export function parseComposeYaml(text) {
         } else {
           obj[key] = decodeScalar(val.trim());
           parent.push(obj);
+          // Push the list-item object onto the stack so subsequent
+          // lines indented deeper than the list marker are added as
+          // sibling fields on the same object (e.g. the compose
+          // long-form service-secret entry:
+          //   - source: web-token
+          //     target: web-token
+          //     mode: 0400
+          // must land as {source, target, mode} on one item).
+          stack.push({ indent, node: obj });
         }
       } else {
         parent.push(decodeScalar(rest.trim()));
@@ -145,7 +245,6 @@ export function parseComposeYaml(text) {
     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];
@@ -183,3 +282,24 @@ export function whichCaddy() {
   const r = spawnSync('caddy', ['version'], { encoding: 'utf8' });
   return r.status === 0 ? (r.stdout || '').trim() : null;
 }
+
+// the anchor-prefix rule: every result row's detail starts with the first
+// eight words of the anchored AC text. This map holds those prefixes
+// for the platform-docker-compose-host ACs; callers wrap their detail
+// via `anchored(anchorAcId, detail)`.
+export const AC_ANCHOR_PREFIX = {
+  'AC-composeHost-upClean': 'The real-account-minimal-stack-up probe, when CI_HAS_HETZNER_ACCOUNT is set, scps the',
+  'AC-composeHost-zeroDowntimeReload': 'The real-account-reload-burst probe, when CI_HAS_HETZNER_ACCOUNT is set, runs undici',
+  'AC-composeHost-healthcheckLint': 'The compose-config-lint probe shells to docker compose config against',
+  'AC-composeHost-restartClassification': 'The compose-config-lint probe asserts every service in the compose.yaml',
+  'AC-composeHost-logDriverClassification': 'Every service in the applied compose.yaml declares a logging',
+  'AC-composeHost-reverseProxyArtefactValid': 'The applied fixture ships caddy/Caddyfile under a caddy/ directory',
+  'AC-composeHost-secretsAreFiles': 'The secrets-as-files-scan probe walks compose.yaml plus every referenced service',
+  'AC-composeHost-secretShape': 'The applied compose.yaml declares at least one secret under',
+  'AC-38107-4': 'Read-only bind-mount: the reverse-proxy config bind-mount in compose.yaml is',
+};
+
+export function anchored(anchorAcId, body) {
+  const prefix = AC_ANCHOR_PREFIX[anchorAcId];
+  return prefix ? `${prefix}. ${body}` : body;
+}

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

@@ -1,38 +1,251 @@
-// Probe: real-account-minimal-stack-up.
-//
+// Probe: real-account-minimal-stack-up (v1.1.5).
+
 // 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';
+// Contract:
+//   - First-tier gate CI_HAS_HETZNER_ACCOUNT must equal exactly the
+//     string "true"; anything else records an honest skip row.
+//   - Second-tier HCLOUD_TOKEN missing carries its own honest skip row.
+//   - The AC-composeHost-upClean pass row carries an `evidence`
+//     object with the created server id, the compose ps service
+//     list, the on-server HTTP response (statusCode and body
+//     excerpt) proving the deployed stack URL answers, and the
+//     root-path body sample that reads the mounted secret file
+//     (`tokenPresence`).
+//   - After the stack is up, the probe emits one additional row per
+//     mounted secret anchored to AC-composeHost-secretShape whose
+//     evidence carries the in-container mode observed via
+//     `docker exec <container> stat -c %a /run/secrets/<name>`; this
+//     is the "mounted at mode 0o400" observation the offline scan
+//     cannot make. The row FAILS if the observed mode is anything
+//     other than 400.
+//   - Teardown failure FAILS the verdict.
+
+import { spawn } from 'node:child_process';
+import { resolve } from 'node:path';
+import {
+  runShim, firstTierGateSkipResult, secondTierMissingSkipResult, FIXTURE_DIR,
+} from './probe-utils.mjs';
 
 export const anchorAcId = 'AC-composeHost-upClean';
 export const accountBound = true;
 
+function hcloudJson(argv, { timeoutMs = 60_000 } = {}) {
+  return new Promise((resolvePromise, reject) => {
+    const p = spawn('hcloud', argv, { stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    const timer = setTimeout(() => { try { p.kill('SIGKILL'); } catch (_) {} reject(new Error(`hcloud ${argv.join(' ')} timed out after ${timeoutMs}ms`)); }, timeoutMs);
+    p.stdout.on('data', (d) => { stdout += d.toString(); });
+    p.stderr.on('data', (d) => { stderr += d.toString(); });
+    p.on('error', (err) => { clearTimeout(timer); reject(err); });
+    p.on('close', (code) => {
+      clearTimeout(timer);
+      if (code !== 0) return reject(new Error(`hcloud ${argv.join(' ')} exited ${code}: ${stderr}`));
+      const trimmed = stdout.trim();
+      if (trimmed.length === 0) return resolvePromise([]);
+      try {
+        const parsed = JSON.parse(trimmed);
+        resolvePromise(Array.isArray(parsed) ? parsed : (parsed.servers || []));
+      } catch (err) {
+        reject(new Error(`hcloud stdout not JSON: ${err.message}`));
+      }
+    });
+  });
+}
+
 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 };
+    return {
+      results: [firstTierGateSkipResult(
+        anchorAcId,
+        'CI_HAS_HETZNER_ACCOUNT',
+        'real-account minimal-stack-up skipped; run with CI_HAS_HETZNER_ACCOUNT=true to exercise the compose stack against a throwaway cx23.',
+      )],
+      extra: { skipped: true, missingEnv: ['CI_HAS_HETZNER_ACCOUNT'] },
+    };
   }
-  // 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 };
+  if (!process.env.HCLOUD_TOKEN) {
+    return {
+      results: [secondTierMissingSkipResult(
+        anchorAcId,
+        'HCLOUD_TOKEN',
+        'the throwaway cx23 cannot be provisioned without HCLOUD_TOKEN.',
+      )],
+      extra: { skipped: true, missingEnv: ['HCLOUD_TOKEN'] },
+    };
+  }
+  const { provisionThrowawayServer } = await import(resolve(FIXTURE_DIR, 'provision.mjs'));
+  const { destroyThrowawayServer } = await import(resolve(FIXTURE_DIR, 'destroy.mjs'));
+  const { bringUpStack, httpProbe, httpProbeOnServer, tearDownStack, observeSecretModes } = await import(resolve(FIXTURE_DIR, 'src/compose-stack-driver.mjs'));
+
+  const evidence = {};
+  const resultRow = { anchorAcId, verdict: 'fail', detail: '', evidence };
+  const extraRows = [];
+  let provisioned = null;
+  try {
+    provisioned = await provisionThrowawayServer({ runId: process.env.GITHUB_RUN_ID ?? `local-${Date.now()}` });
+    evidence.serverId = provisioned.id;
+    evidence.primaryIpv4 = provisioned.primaryIpv4;
+    const brought = await bringUpStack(provisioned);
+    evidence.services = brought.services;
+    evidence.declaredServices = brought.declared;
+    evidence.observedNames = brought.observedNames;
+    evidence.eventTrail = brought.events;
+    evidence.elicitedTimeoutSeconds = brought.elicitedTimeoutSeconds;
+    if (!brought.ok) {
+      resultRow.verdict = 'fail';
+      const detailPieces = [`stack failed at phase ${brought.phase} on server ${provisioned.id} (elicited timeout ${brought.elicitedTimeoutSeconds}s)`];
+      if (brought.missingServices && brought.missingServices.length > 0) {
+        detailPieces.push(`missing services: ${brought.missingServices.map((m) => m.name).join(', ')}`);
+        evidence.missingServices = brought.missingServices;
+      }
+      if (brought.unhealthy && brought.unhealthy.length > 0) {
+        detailPieces.push(`unhealthy services: ${brought.unhealthy.map((u) => `${u.service}(${u.reason})`).join('; ')}`);
+        evidence.unhealthyServices = brought.unhealthy;
+      }
+      resultRow.detail = `${detailPieces.join('; ')}. Trailer: ${JSON.stringify(brought).slice(0, 400)}`;
+      return { results: [resultRow], extra: evidence };
+    }
+    const onServer = await httpProbeOnServer(provisioned, '/live');
+    const onServerRoot = await httpProbeOnServer(provisioned, '/');
+    const externalUrl = `http://${provisioned.primaryIpv4}/live`;
+    const external = await httpProbe(externalUrl, { timeoutMs: 5000 });
+    evidence.onServer = {
+      target: onServer.target, statusCode: onServer.statusCode,
+      bodyExcerpt: onServer.bodyExcerpt, elapsedSeconds: onServer.elapsedSeconds,
+      requestId: onServer.requestId,
+    };
+    evidence.onServerRoot = {
+      target: onServerRoot.target, statusCode: onServerRoot.statusCode,
+      bodyExcerpt: onServerRoot.bodyExcerpt,
+    };
+    evidence.external = {
+      url: externalUrl, statusCode: external.statusCode, error: external.error || null,
+      note: 'off-host fetch expected to fail under the deploy-hetzner-server DOCKER-USER hardening',
+    };
+    if (!onServer.ok || onServer.statusCode !== 200) {
+      resultRow.verdict = 'fail';
+      resultRow.detail = `caddy /live did not return 200 on ${onServer.target}: statusCode=${onServer.statusCode} error=${onServer.error || 'none'} bodyExcerpt=${onServer.bodyExcerpt || ''}`;
+      return { results: [resultRow], extra: evidence };
+    }
+    resultRow.verdict = 'pass';
+    resultRow.detail = `stack up on server ${provisioned.id} (${provisioned.primaryIpv4}); ${brought.services.length} services declared; caddy answered ${onServer.target} with ${onServer.statusCode} body="${(onServer.bodyExcerpt || '').replace(/\n/g, ' ')}" elapsed=${onServer.elapsedSeconds}s; root ${onServerRoot.target} returned ${onServerRoot.statusCode}.`;
+
+    // In-container secret mode observation. AC-composeHost-secretShape
+    // requires the mounted secret file to land at mode 0o400 inside
+    // the container; the offline scan cannot see that. Run
+    // `docker exec ... stat -c %a /run/secrets/<name>` for every
+    // consuming service.
+    try {
+      const modes = await observeSecretModes(provisioned);
+      evidence.observedSecretModes = modes;
+      for (const obs of modes.observations) {
+        const modePass = obs.mode === '400';
+        extraRows.push({
+          anchorAcId: 'AC-composeHost-secretShape',
+          verdict: modePass ? 'pass' : 'fail',
+          detail: modePass
+            ? `service '${obs.service}' secret '${obs.secretName}' mounted at ${obs.mountPath} with observed mode ${obs.mode} inside container ${obs.containerName} (id ${obs.containerId}, docker exec stat -c %a)`
+            : `service '${obs.service}' secret '${obs.secretName}' mounted at ${obs.mountPath} with observed mode ${obs.mode}; AC-composeHost-secretShape requires 0o400 (400)`,
+          evidence: {
+            service: obs.service,
+            secretName: obs.secretName,
+            mode: obs.mode,
+            mountPath: obs.mountPath,
+            containerId: obs.containerId,
+            containerName: obs.containerName,
+            source: 'docker exec stat -c %a; container id via docker inspect --format {{.Id}}',
+          },
+        });
+      }
+      for (const err of modes.errors) {
+        extraRows.push({
+          anchorAcId: 'AC-composeHost-secretShape',
+          verdict: 'fail',
+          detail: `could not observe in-container mode for service '${err.service}' secret '${err.secretName}': ${err.error}`,
+          evidence: {
+            service: err.service,
+            secretName: err.secretName,
+            error: err.error,
+            containerName: err.containerName || null,
+            source: 'docker exec stat -c %a',
+          },
+        });
+      }
+      // Every top-level secret must be consumed by at least one
+      // service (an orphan is a defect the offline scan also catches;
+      // this real-account row confirms the same on the live compose
+      // graph).
+      for (const [secretName, consumers] of Object.entries(modes.consumingServicesBySecret)) {
+        if (!consumers.length) {
+          extraRows.push({
+            anchorAcId: 'AC-composeHost-secretShape',
+            verdict: 'fail',
+            detail: `top-level secret '${secretName}' has no consuming service in the applied compose graph`,
+            evidence: { secretName, consumingServices: [], source: 'live docker compose ps + compose.yaml services block' },
+          });
+        }
+      }
+      if (extraRows.some((r) => r.verdict === 'fail')) {
+        resultRow.verdict = 'fail';
+        resultRow.detail = `${resultRow.detail} SECRET MODE observation carries at least one fail row; see evidence.observedSecretModes.`;
+      }
+    } catch (err) {
+      extraRows.push({
+        anchorAcId: 'AC-composeHost-secretShape',
+        verdict: 'fail',
+        detail: `observeSecretModes threw: ${err.message}`,
+        evidence: { error: err.message, source: 'docker exec stat -c %a' },
+      });
+      resultRow.verdict = 'fail';
+      resultRow.detail = `${resultRow.detail} SECRET MODE observation threw: ${err.message}.`;
+    }
+  } catch (err) {
+    resultRow.verdict = 'fail';
+    resultRow.detail = `minimal-stack-up threw: ${err.message}`;
+    evidence.error = err.stack || err.message;
+    return { results: [resultRow], extra: evidence };
+  } finally {
+    if (provisioned && provisioned.id) {
+      let tearDownDown = null;
+      try {
+        tearDownDown = await tearDownStack(provisioned);
+        evidence.composeDown = { code: tearDownDown && tearDownDown.code, stderrExcerpt: (tearDownDown && tearDownDown.stderr || '').slice(0, 300) };
+        if (tearDownDown && tearDownDown.code !== 0) {
+          resultRow.verdict = 'fail';
+          resultRow.detail = `${resultRow.detail} TEARDOWN docker compose down exited ${tearDownDown.code}: ${(tearDownDown.stderr || '').slice(0, 300)}`;
+        }
+      } catch (err) {
+        resultRow.verdict = 'fail';
+        resultRow.detail = `${resultRow.detail} TEARDOWN docker compose down failed: ${err.message}`;
+        evidence.composeDownError = err.message;
+      }
+      try {
+        await destroyThrowawayServer(provisioned);
+        evidence.teardown = { destroyed: provisioned.id };
+        try {
+          const postList = await hcloudJson(['server', 'list', '--output', 'json']);
+          evidence.postTeardownServerIds = postList.map((s) => s.id);
+          if (postList.some((s) => s.id === provisioned.id)) {
+            resultRow.verdict = 'fail';
+            resultRow.detail = `${resultRow.detail} TEARDOWN INCOMPLETE: server ${provisioned.id} still present in hcloud server list.`;
+          }
+        } catch (err) {
+          evidence.postTeardownListError = err.message;
+          resultRow.verdict = 'fail';
+          resultRow.detail = `${resultRow.detail} TEARDOWN CONFIRMATION FAILED: post-teardown hcloud server list threw (${err.message}); cannot confirm server ${provisioned.id} was removed.`;
+        }
+      } catch (err) {
+        resultRow.verdict = 'fail';
+        resultRow.detail = `${resultRow.detail} TEARDOWN FAILED for server ${provisioned.id}: ${err.message}.`;
+        evidence.teardownError = err.message;
+        evidence.orphanServerId = provisioned.id;
+      }
+    }
+  }
+  return { results: [resultRow, ...extraRows], extra: evidence };
 }
 
 const engine = { kind: 'throwaway-server', image: 'hetzner cx23 in fsn1 via provision.mjs', healthy: true };