rcf-lite 0.26.0 → 0.28.0

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

@@ -1,36 +1,222 @@
-// Probe: real-account-reload-burst.
-//
+// Probe: real-account-reload-burst (v1.1.5).
+
 // 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';
+// 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 pass row carries an `evidence` object with the created
+//     server id, the warm baseline response, the burst counters (total,
+//     2xx, drops, reload duration), the reload exit and the elicited
+//     window (RELOAD_WINDOW_SECONDS, default 10s per AC).
+//   - The AC requires the elicited 10-second window to bound the
+//     reload duration; a reload that exceeds the window FAILS.
+//   - Teardown failure FAILS the verdict (the shape rule).
+
+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-zeroDowntimeReload';
 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; reload-burst not exercised'));
-    return { results, extra };
+    return {
+      results: [firstTierGateSkipResult(
+        anchorAcId,
+        'CI_HAS_HETZNER_ACCOUNT',
+        'real-account reload-burst skipped; run with CI_HAS_HETZNER_ACCOUNT=true to exercise the caddy reload window against a throwaway cx23 stack.',
+      )],
+      extra: { skipped: true, missingEnv: ['CI_HAS_HETZNER_ACCOUNT'] },
+    };
   }
-  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 reloadWindowSeconds = Number(process.env.RELOAD_WINDOW_SECONDS ?? 10);
+  const reloadWindowMs = Math.round(reloadWindowSeconds * 1000);
+  const { provisionThrowawayServer } = await import(resolve(FIXTURE_DIR, 'provision.mjs'));
+  const { destroyThrowawayServer } = await import(resolve(FIXTURE_DIR, 'destroy.mjs'));
+  const { bringUpStack, reloadBurst, tearDownStack, httpProbeOnServer } = await import(resolve(FIXTURE_DIR, 'src/compose-stack-driver.mjs'));
+
+  const evidence = { elicitedReloadWindowSeconds: reloadWindowSeconds };
+  const resultRow = { anchorAcId, verdict: 'fail', detail: '', evidence };
+  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.eventTrail = brought.events;
+    if (!brought.ok) {
+      resultRow.verdict = 'fail';
+      resultRow.detail = `stack failed at phase ${brought.phase} on server ${provisioned.id}: ${JSON.stringify(brought).slice(0, 500)}`;
+      return { results: [resultRow], extra: evidence };
+    }
+    const warm = await httpProbeOnServer(provisioned, '/');
+    evidence.warm = {
+      target: warm.target, statusCode: warm.statusCode,
+      bodyExcerpt: warm.bodyExcerpt, elapsedSeconds: warm.elapsedSeconds,
+    };
+    if (!warm.ok || warm.statusCode !== 200) {
+      resultRow.verdict = 'fail';
+      resultRow.detail = `caddy did not answer 200 before the burst on ${warm.target}: statusCode=${warm.statusCode} error=${warm.error || 'none'}`;
+      return { results: [resultRow], extra: evidence };
+    }
+    // Zero-downtime reload: undici GETs on the throwaway server
+    // (Node global fetch is undici) fired continuously for the
+    // elicited reload-window-seconds, wrapping the caddy reload.
+    // The burst-request window brackets and per-request timestamps
+    // prove the overlap on a single runner clock.
+    const burst = await reloadBurst(provisioned, '/', { total: 40, concurrency: 8, mode: 'undici-on-server', reloadWindowMs, burstDurationMs: reloadWindowMs });
+    evidence.burst = {
+      expectedTotal: burst.expectedTotal,
+      total: burst.total,
+      twoXx: burst.twoXx, drops: burst.drops,
+      reloadDurationMs: burst.reloadDurationMs, reloadExit: burst.reloadExit,
+      reloadStartedAt: burst.reloadStartedAt, reloadEndedAt: burst.reloadEndedAt,
+      burstStartedAt: burst.burstStartedAt, burstEndedAt: burst.burstEndedAt,
+      firstRequestStartedAt: burst.firstRequestStartedAt, lastRequestEndedAt: burst.lastRequestEndedAt,
+      burstDurationMs: burst.burstDurationMs,
+      burstWindowContainsReloadWindow: burst.burstWindowContainsReloadWindow,
+      overlapCount: burst.overlapCount,
+      firstOverlapStart: burst.firstOverlapStart, lastOverlapEnd: burst.lastOverlapEnd,
+      mode: burst.mode,
+      // The fixture returns clockDomain: 'server' to make explicit
+      // that every timestamp in the burst object (burstStartedAt,
+      // reloadStartedAt, per-request startedAt/endedAt, overlap
+      // extrema) originates from the on-server undici script's own
+      // Date.now(); the runner does no local-to-remote rebase.
+      clockDomain: burst.clockDomain,
+      onServerNodeVersion: burst.onServerNodeVersion,
+      reloadStderrExcerpt: burst.reloadStderrExcerpt,
+      burstStderrExcerpt: burst.burstStderrExcerpt,
+      burstParseError: burst.burstParseError,
+      elicitedReloadWindowMs: reloadWindowMs,
+    };
+    if (burst.reloadExit !== 0) {
+      resultRow.verdict = 'fail';
+      resultRow.detail = `caddy reload exited non-zero (${burst.reloadExit}): ${burst.reloadStderrExcerpt}`;
+      return { results: [resultRow], extra: evidence };
+    }
+    // The duration-based burst runs for the elicited window and
+    // fires as many requests as the loopback plus concurrency allow;
+    // expectedTotal is a floor (at least this many GETs must be
+    // observed inside the window), never a ceiling.
+    if (burst.total < burst.expectedTotal) {
+      resultRow.verdict = 'fail';
+      resultRow.detail = `undici burst produced ${burst.total} outcomes in the ${burst.burstDurationMs}ms burst window, below the ${burst.expectedTotal}-request floor AC-composeHost-zeroDowntimeReload requires.`;
+      return { results: [resultRow], extra: evidence };
+    }
+    if (burst.drops > 0 || burst.twoXx < burst.total) {
+      resultRow.verdict = 'fail';
+      resultRow.detail = `zero-downtime-reload violated on server ${provisioned.id}: ${burst.twoXx}/${burst.total} 2xx, ${burst.drops} dropped connections during a ${burst.reloadDurationMs}ms reload.`;
+      return { results: [resultRow], extra: evidence };
+    }
+    // Overlap proof: the burst window must contain the reload window
+    // (AC-composeHost-zeroDowntimeReload requires undici requests to
+    // overlap the reload; the burst being in flight for the whole
+    // reload is the strictest reading), and at least one request must
+    // have overlapped the reload window.
+    if (!burst.burstWindowContainsReloadWindow) {
+      resultRow.verdict = 'fail';
+      resultRow.detail = `undici burst-request window [${burst.firstRequestStartedAt},${burst.lastRequestEndedAt}] did not contain the reload window [${burst.reloadStartedAt},${burst.reloadEndedAt}]; AC-composeHost-zeroDowntimeReload requires the burst to run WHILE the reload runs.`;
+      return { results: [resultRow], extra: evidence };
+    }
+    if (burst.overlapCount === 0) {
+      resultRow.verdict = 'fail';
+      resultRow.detail = `undici burst produced ${burst.total} 2xx results but ZERO request windows [startedAt,endedAt] overlapped the reload window [${burst.reloadStartedAt},${burst.reloadEndedAt}]; AC-composeHost-zeroDowntimeReload requires the burst to run WHILE the reload runs.`;
+      return { results: [resultRow], extra: evidence };
+    }
+    if (burst.reloadDurationMs > reloadWindowMs) {
+      resultRow.verdict = 'fail';
+      resultRow.detail = `caddy reload duration ${burst.reloadDurationMs}ms exceeded the elicited reload-window-seconds ${reloadWindowSeconds}s (${reloadWindowMs}ms); AC-composeHost-zeroDowntimeReload requires the reload to fit inside the elicited window.`;
+      return { results: [resultRow], extra: evidence };
+    }
+    resultRow.verdict = 'pass';
+    resultRow.detail = `zero-downtime-reload OBSERVED on server ${provisioned.id}: ${burst.twoXx}/${burst.total} on-server undici 2xx, 0 dropped connections; burst-request window [${burst.firstRequestStartedAt},${burst.lastRequestEndedAt}] contains reload window [${burst.reloadStartedAt},${burst.reloadEndedAt}]; ${burst.overlapCount}/${burst.total} request windows overlap the ${burst.reloadDurationMs}ms reload (under the elicited ${reloadWindowSeconds}s window); warm baseline statusCode=${warm.statusCode}.`;
+  } catch (err) {
+    resultRow.verdict = 'fail';
+    resultRow.detail = `reload-burst threw: ${err.message}`;
+    evidence.error = err.stack || err.message;
+    return { results: [resultRow], extra: evidence };
+  } finally {
+    if (provisioned && provisioned.id) {
+      try {
+        const 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], extra: evidence };
 }
 
-const engine = { kind: 'throwaway-server-burst', image: 'undici burst against caddy in the throwaway compose stack', healthy: true };
+const engine = { kind: 'throwaway-server-burst', image: 'curl 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/secrets-as-files-scan.mjs

@@ -1,30 +1,74 @@
-// Probe: secrets-as-files-scan.
+// Probe: secrets-as-files-scan (v1.1.8).
 //
-// anchorAcId: AC-composeHost-secretsAreFiles (primary), AC-composeHost-secretShape.
-// accountBound: false.
+// This is an offline scanner: it reads the shipped compose.yaml,
+// the shipped .env, and every file under every declared service
+// bind-mount source, looking for a plaintext-token literal and for
+// the file-source shape of every top-level secret. It has no
+// engine-minted identifier - the sha256 of compose.yaml is
+// computed by this probe with Node's `createHash` and the service
+// and secret names are Compose's own choices, not engine-returned
+// identities.
+//
+// Every result row is a `conformanceOnly` de-claim naming the
+// shipped AC clause the offline scan does not observe. The live
+// observation for both AC-composeHost-secretShape ("mounted 0o400"
+// clause, in-container stat) and AC-composeHost-secretsAreFiles
+// (service secrets actually mounted, not present in env) lives on
+// `real-account-minimal-stack-up`, which runs
+// `docker exec ... stat -c %a /run/secrets/<name>` inside every
+// consuming container. The mode observation belongs there, not to
+// this offline scan.
 //
-// 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).
+// accountBound: false.
 //
-// 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.
+// Scans:
+//   - compose.yaml: every declared top-level secret references a
+//     file: source (secretShape); every top-level secret has at
+//     least one consuming service (an orphan top-level entry fails).
+//   - compose.yaml: for every consuming service, the reference lives
+//     in the service-level secrets: array (never in environment).
+//     A long-form entry with an explicit `mode` field is recorded
+//     verbatim; missing modes are NOT assumed to be 0o400 here (that
+//     assertion belongs to the real-account probe that observes the
+//     mounted file inside the container).
+//   - compose.yaml, .env, plus every file under every service's
+//     bind-mount source directory (config discovery walks the compose
+//     service list, not a hardcoded caddy/ dir): no plaintext token
+//     literal appears.
+//   - The mutation switch SIMULATE_PLAINTEXT_SECRET writes a plaintext
+//     literal into a scratch copy of compose.yaml and the probe FAILS
+//     naming file+line.
 
-import { readFile, cp, rm, mkdir } from 'node:fs/promises';
+import { readFile, cp, rm, mkdir, readdir, stat } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
 import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { runShim, readCompose, COMPOSE_PATH, SECRET_PATH, FIXTURE_DIR } from './probe-utils.mjs';
+import { join, resolve, dirname, isAbsolute, relative } from 'node:path';
+import { runShim, readCompose, COMPOSE_PATH, SECRET_PATH, ENV_PATH, FIXTURE_DIR } from './probe-utils.mjs';
 
-export const anchorAcIds = [
-  'AC-composeHost-secretsAreFiles',
-  'AC-composeHost-secretShape',
-];
+function sha256(text) {
+  return createHash('sha256').update(text, 'utf8').digest('hex');
+}
+
+export const anchorAcIds = [];
 export const accountBound = false;
 
+const LIMIT_SHAPE = 'AC-composeHost-secretShape: top-level `file:` source is validated offline against the shipped compose.yaml; the live observation ("mounted at mode 0o400" clause, in-container `stat -c %a /run/secrets/<name>`) is carried by real-account-minimal-stack-up.';
+const LIMIT_FILES = 'AC-composeHost-secretsAreFiles: service-level secrets: reference shape is validated offline against the shipped compose.yaml; the live observation (the service consuming the file mount inside the container) is carried by real-account-minimal-stack-up.';
+
+async function walkFiles(root) {
+  const out = [];
+  const entries = await readdir(root, { withFileTypes: true }).catch(() => []);
+  for (const e of entries) {
+    const full = join(root, e.name);
+    if (e.isDirectory()) {
+      out.push(...await walkFiles(full));
+    } else if (e.isFile()) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
 async function applyPlaintextMutation() {
   const scratch = join(tmpdir(), `rcf-lite-t2-secrets-scan-${Date.now()}`);
   await mkdir(scratch, { recursive: true });
@@ -32,23 +76,61 @@ async function applyPlaintextMutation() {
   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() });
+async function scanFileForLiteral(file, secret) {
+  try {
+    const s = await stat(file);
+    if (s.size > 4 * 1024 * 1024) return []; // skip large binaries
+    const text = await readFile(file, 'utf8');
+    const hits = [];
+    const lines = text.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      if (lines[i].includes(secret)) {
+        hits.push({ file, line: i + 1, snippet: lines[i].trim().slice(0, 200) });
+      }
     }
+    return hits;
+  } catch (_) {
+    return [];
   }
-  return hits;
+}
+
+function collectServiceConfigSources(doc, composeDir) {
+  const sources = new Set();
+  const services = doc.services ?? {};
+  for (const [, svc] of Object.entries(services)) {
+    const vols = (svc && svc.volumes) || [];
+    if (!Array.isArray(vols)) continue;
+    for (const v of vols) {
+      if (typeof v === 'string') {
+        const idx = v.indexOf(':');
+        if (idx <= 0) continue;
+        const src = v.slice(0, idx);
+        if (src.startsWith('./') || src.startsWith('/') || src.startsWith('~')) {
+          sources.add(isAbsolute(src) ? src : resolve(composeDir, src));
+        }
+      } else if (v && typeof v === 'object') {
+        if (v.type === 'bind' && typeof v.source === 'string') {
+          sources.add(isAbsolute(v.source) ? v.source : resolve(composeDir, v.source));
+        }
+      }
+    }
+  }
+  return [...sources];
+}
+
+function getServiceSecretMode(svcSecretsEntry) {
+  if (typeof svcSecretsEntry === 'string') return null;
+  if (svcSecretsEntry && typeof svcSecretsEntry === 'object') {
+    if (svcSecretsEntry.mode === undefined || svcSecretsEntry.mode === null) return null;
+    return svcSecretsEntry.mode;
+  }
+  return null;
 }
 
 export default async function runProbe() {
@@ -65,45 +147,167 @@ export default async function runProbe() {
     scratchToClean = m.scratch;
   }
   try {
-    // Secret-shape scan: every declared secret has a file: source.
+    const composeTextForHash = await readFile(composePathToScan, 'utf8');
+    const composeSha256 = sha256(composeTextForHash);
     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',
+          anchorAcId: null,
+          conformanceOnly: true,
+          limitation: LIMIT_SHAPE,
           verdict: 'fail',
-          detail: `compose secret '${name}' is not a file: source`,
+          detail: `offline secrets-as-files-scan: compose secret '${name}' is not a file: source`,
+          evidence: { composeSha256, declaredSecretName: name, spec, expectedShape: 'file: <path>' },
         });
       } else {
         results.push({
-          anchorAcId: 'AC-composeHost-secretShape',
+          anchorAcId: null,
+          conformanceOnly: true,
+          limitation: LIMIT_SHAPE,
           verdict: 'pass',
-          detail: `compose secret '${name}' -> file: ${spec.file}`,
+          detail: `offline secrets-as-files-scan: compose secret '${name}' declares file: ${spec.file}`,
+          evidence: { composeSha256, declaredSecretName: name, fileSource: spec.file, scannedFrom: 'compose.yaml top-level secrets block' },
         });
       }
     }
-    // Plaintext-literal scan.
-    const hits = await scanForLiteral({ composePath: composePathToScan, secret, secretName: 'web-token' });
-    if (hits.length > 0) {
-      for (const h of hits) {
+
+    const services = doc.services ?? {};
+    const consumerBySecret = {};
+    for (const name of secretNames) consumerBySecret[name] = [];
+    for (const [svcName, svc] of Object.entries(services)) {
+      const svcSecrets = Array.isArray(svc && svc.secrets) ? svc.secrets : [];
+      for (const entry of svcSecrets) {
+        const secretName = typeof entry === 'string' ? entry : (entry && entry.source) || null;
+        if (secretName && secretNames.includes(secretName)) consumerBySecret[secretName].push(svcName);
+      }
+    }
+    for (const name of secretNames) {
+      const consumers = consumerBySecret[name];
+      if (consumers.length === 0) {
+        results.push({
+          anchorAcId: null,
+          conformanceOnly: true,
+          limitation: LIMIT_SHAPE,
+          verdict: 'fail',
+          detail: `offline secrets-as-files-scan: compose secret '${name}' is declared at the top level but no service references it via the service-level secrets: array (orphan)`,
+          evidence: { composeSha256, declaredSecretName: name, consumingServices: [], expectedShape: 'at least one consuming service' },
+        });
+      } else {
+        results.push({
+          anchorAcId: null,
+          conformanceOnly: true,
+          limitation: LIMIT_SHAPE,
+          verdict: 'pass',
+          detail: `offline secrets-as-files-scan: compose secret '${name}' is referenced by ${consumers.length} service(s): ${consumers.join(', ')}`,
+          evidence: { composeSha256, declaredSecretName: name, consumingServices: consumers, scannedFrom: 'compose.yaml services block' },
+        });
+      }
+    }
+
+    for (const [svcName, svc] of Object.entries(services)) {
+      const svcSecrets = Array.isArray(svc && svc.secrets) ? svc.secrets : [];
+      for (const entry of svcSecrets) {
+        const secretName = typeof entry === 'string' ? entry : (entry && entry.source) || null;
+        if (!secretName) continue;
+        if (!secretNames.includes(secretName)) {
+          results.push({
+            anchorAcId: null,
+            conformanceOnly: true,
+            limitation: LIMIT_FILES,
+            verdict: 'fail',
+            detail: `offline secrets-as-files-scan: service '${svcName}' references undeclared secret '${secretName}' via the service-level secrets: block`,
+            evidence: { composeSha256, serviceName: svcName, declaredSecretName: secretName, declaredSecrets: secretNames },
+          });
+          continue;
+        }
+        const declaredMode = getServiceSecretMode(entry);
+        results.push({
+          anchorAcId: null,
+          conformanceOnly: true,
+          limitation: LIMIT_FILES,
+          verdict: 'pass',
+          detail: `offline secrets-as-files-scan: service '${svcName}' references secret '${secretName}' via service-level secrets: (declaredMode=${declaredMode === null ? 'unset' : String(declaredMode)})`,
+          evidence: {
+            composeSha256,
+            serviceName: svcName,
+            declaredSecretName: secretName,
+            declaredMode: declaredMode === null ? 'unset' : String(declaredMode),
+            scannedFrom: 'compose.yaml service secrets: block',
+          },
+        });
+      }
+      const environment = (svc && svc.environment) || [];
+      const envList = Array.isArray(environment) ? environment : Object.keys(environment).map((k) => `${k}=${environment[k]}`);
+      const svcSecretRefNames = svcSecrets.map((e) => (typeof e === 'string' ? e : (e && e.source) || null)).filter(Boolean);
+      for (const entry of envList) {
+        for (const n of secretNames) {
+          if (String(entry).includes(n) && !svcSecretRefNames.includes(n)) {
+            results.push({
+              anchorAcId: null,
+              conformanceOnly: true,
+              limitation: LIMIT_FILES,
+              verdict: 'fail',
+              detail: `offline secrets-as-files-scan: service '${svcName}' references secret '${n}' via environment entry '${entry}' instead of the service-level secrets: block`,
+              evidence: { composeSha256, serviceName: svcName, envEntry: String(entry), declaredSecretName: n },
+            });
+          }
+        }
+      }
+    }
+
+    const composeDir = dirname(composePathToScan);
+    const scanTargets = [composePathToScan, ENV_PATH];
+    const configSources = collectServiceConfigSources(doc, composeDir);
+    extra.discoveredConfigSources = configSources.map((p) => relative(FIXTURE_DIR, p));
+    for (const src of configSources) {
+      try {
+        const s = await stat(src);
+        if (s.isDirectory()) {
+          for (const f of await walkFiles(src)) scanTargets.push(f);
+        } else if (s.isFile()) {
+          scanTargets.push(src);
+        }
+      } catch (_) { /* skip missing/unresolvable sources */ }
+    }
+
+    const allHits = [];
+    for (const t of scanTargets) {
+      allHits.push(...await scanFileForLiteral(t, secret));
+    }
+    if (allHits.length > 0) {
+      for (const h of allHits) {
         results.push({
-          anchorAcId: 'AC-composeHost-secretsAreFiles',
+          anchorAcId: null,
+          conformanceOnly: true,
+          limitation: LIMIT_FILES,
           verdict: 'fail',
-          detail: `plaintext secret literal for 'web-token' found in ${h.file}:${h.line} (snippet: ${h.snippet})`,
+          detail: `offline secrets-as-files-scan: plaintext secret literal for 'web-token' found in ${h.file}:${h.line} (snippet: ${h.snippet})`,
+          evidence: { composeSha256, scannedFile: h.file, lineNumber: h.line, snippet: h.snippet, declaredSecretName: 'web-token' },
         });
       }
     } else {
       results.push({
-        anchorAcId: 'AC-composeHost-secretsAreFiles',
+        anchorAcId: null,
+        conformanceOnly: true,
+        limitation: LIMIT_FILES,
         verdict: 'pass',
-        detail: `no plaintext secret literal for 'web-token' found in the scanned compose.yaml`,
+        detail: `offline secrets-as-files-scan: no plaintext secret literal for 'web-token' found across ${scanTargets.length} scanned files (compose.yaml, .env, and every file under each service's bind-mount source)`,
+        evidence: {
+          composeSha256,
+          scannedFilenames: scanTargets.map((f) => f.replace(FIXTURE_DIR + '/', '')),
+          fileCount: scanTargets.length,
+          discoveredConfigSources: extra.discoveredConfigSources,
+          declaredSecretName: 'web-token',
+        },
       });
     }
-    extra.hits = hits.map((h) => ({ file: h.file, line: h.line }));
+    extra.scannedFileCount = scanTargets.length;
   } finally {
     if (scratchToClean) await rm(scratchToClean, { recursive: true, force: true });
   }

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

@@ -2,7 +2,7 @@
   "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.",
+  "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. The compose.yaml location is elicited (compose-file-location): the shipped default is the repo-root path; the alternative compose/compose.yaml is chosen when the project already owns a repo-root compose.yaml for another purpose. Both branches must (must) point docker compose config at the elicited file, and the layout invariants (service-per-container, named networks and volumes, .env-backed non-secret config) hold regardless of which location the elicit resolves. The blueprint declares the containerHost capability token: every downstream blueprint that selects containerHost expects the layout invariants this REQ names.",
   "category": "functional",
   "domain": "platform",
   "priority": "must",
@@ -14,5 +14,9 @@
   "version": "1.0.0",
   "status": "approved",
   "createdAt": "2026-09-08T00:00:00.000Z",
-  "updatedAt": "2026-09-08T00:00:00.000Z"
+  "updatedAt": "2026-09-09T20:35:00.000Z",
+  "deliveredBy": {
+    "tacId": "TAC-3901-platform-docker-compose-host-compose-layout",
+    "field": "responsibilities.topology"
+  }
 }

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

@@ -14,5 +14,9 @@
   "version": "1.0.0",
   "status": "approved",
   "createdAt": "2026-09-08T00:00:00.000Z",
-  "updatedAt": "2026-09-08T00:00:00.000Z"
+  "updatedAt": "2026-09-09T20:00:00.000Z",
+  "deliveredBy": {
+    "tacId": "TAC-3902-platform-docker-compose-host-secrets-mount",
+    "field": "responsibilities.secrets"
+  }
 }

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

@@ -2,7 +2,7 @@
   "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.",
+  "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 (the healthcheck-timeout-seconds answer; default 30, floor 5, ceiling 300). The applied healthcheck kind is elicited per service default (healthcheck-default-kind): http covers the common web service, tcp covers a database or plain socket service (a TCP connect to a named port must (must) succeed inside the healthcheck window), and command lets the operator supply a bespoke test string. Each kind must (must) refuse on a missing block or an invalid target and pass on a bound target within the same docker compose config gate.",
   "category": "functional",
   "domain": "platform",
   "priority": "must",
@@ -14,5 +14,9 @@
   "version": "1.0.0",
   "status": "approved",
   "createdAt": "2026-09-08T00:00:00.000Z",
-  "updatedAt": "2026-09-08T00:00:00.000Z"
+  "updatedAt": "2026-09-09T22:00:00.000Z",
+  "deliveredBy": {
+    "tacId": "TAC-3903-platform-docker-compose-host-healthcheck-lint",
+    "field": "responsibilities.healthcheck"
+  }
 }

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

@@ -14,5 +14,9 @@
   "version": "1.0.0",
   "status": "approved",
   "createdAt": "2026-09-08T00:00:00.000Z",
-  "updatedAt": "2026-09-08T00:00:00.000Z"
+  "updatedAt": "2026-09-09T20:00:00.000Z",
+  "deliveredBy": {
+    "tacId": "TAC-3903-platform-docker-compose-host-healthcheck-lint",
+    "field": "responsibilities.restart"
+  }
 }