rcf-lite 0.27.0 → 0.28.0

package/blueprints/deploy-hetzner-server/contributions/probes/manifest-schema-validate.mjs

@@ -1,69 +1,221 @@
-// Probe: manifest schema validate.
+// Probe: manifest schema validate (v1.1.8).
 //
-// anchorAcId: AC-37102-1 (also covers AC-37106-1 firewall shape and
-// AC-37107-1 snapshot cadence enum via the same schema). accountBound: false.
+// This is an offline schema validator: it reads the shipped fixture
+// manifests and checks them against `hetzner-server.schema.json`.
+// It has no engine-minted identifier - the sha256 of a manifest is
+// computed by this probe with Node's `createHash` and therefore
+// does not satisfy the semantic anatomy identifier rule; the
+// manifest name and JSON path are the probe's own choices.
+// Every result row is a `conformanceOnly` de-claim naming the
+// shipped AC clause the offline check does not observe:
 //
-// Validates every hetzner/servers/*.json under the shared throwaway-server
-// fixture against blueprints/deploy-hetzner-server/contributions/schemas/
-// hetzner-server.schema.json. A lightweight in-process draft-07 subset
-// validator ships with the probe so the shelf gains no runtime dependency
-// on ajv or similar. See validate() at the bottom.
+//   - AC-37102-1  general nine-required-fields schema shape,
+//   - AC-37106-1  firewall rule shape (ssh restricted, 80/443 open,
+//                 no other inbound),
+//   - AC-37107-1  snapshotCadence enum {weekly, daily, off}.
 //
-// Purity: the probe reads only the manifest dir and the shipped schema;
-// no process.env.SIMULATE_ switch is read here. The fixture-side shim
-// packages/rcf-lite/test/fixtures/hetzner-throwaway-server/
-// run-manifest-schema-validate.mjs is the sole reader of
-// SIMULATE_MANIFEST_INVALID and it mutates INPUT (a temp manifest dir
-// pointed at via RCF_FIXTURE_MANIFEST_DIR) only; the probe then FAILS
-// naming the offending field per hetzner-round-7-spec-2026-09-07.md
-// section 3.4 lesson 4.  (2026-09-08).
+// A single manifest emits ONE row per property, each carrying its
+// own `evidence` object. The hash of the manifest bytes and the
+// validator output stay on the row as derived context.
+//
+// Purity: no process.env.SIMULATE_ switch is read. Fixture-side
+// mutations live in the fixture-side run-manifest-schema-validate.mjs
+// shim; the probe reads only the schema and manifest tree.
 
 import { readFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
 import { readManifestFiles, SCHEMA_PATH } from './probe-utils.mjs';
 
-export const anchorAcId = 'AC-37102-1';
+function sha256(text) {
+  return createHash('sha256').update(text, 'utf8').digest('hex');
+}
+
+export const anchorAcId = null;
 export const accountBound = false;
 
+const NINE_REQUIRED = [
+  'name', 'serverType', 'location', 'image', 'sshKeyIds',
+  'firewallId', 'cloudInitPath', 'labels', 'firewallRules', 'snapshotCadence',
+];
+
+const LIMIT_37102 = 'AC-37102-1: manifest schema shape is validated offline against the shipped hetzner-server.schema.json; the live observation (a real-account apply that consumes the same manifest) is carried by real-account-throwaway-server-provision.';
+const LIMIT_37106 = 'AC-37106-1: firewall rule shape is validated offline against the shipped schema and the TAC-3804 binding; the live-account observation (a `hcloud firewall describe` on the applied firewall) would live on a real-account firewall probe.';
+const LIMIT_37107 = 'AC-37107-1: snapshotCadence enum is validated offline against the shipped schema enum; the live observation (a real-account server label matching the manifest cadence) lives on real-account-snapshot-on-demand.';
+
 export default async function runProbe() {
   const schema = JSON.parse(await readFile(SCHEMA_PATH, 'utf8'));
   const { present, files } = await readManifestFiles();
   if (!present) {
     return {
       results: [{
-        anchorAcId,
+        anchorAcId: null,
+        conformanceOnly: true,
+        limitation: LIMIT_37102,
         verdict: 'fail',
-        detail: 'fixture hetzner/servers/ holds zero JSON files; ship at least ci-throwaway.json.',
+        detail: 'offline manifest scan: fixture hetzner/servers/ holds zero JSON files; ship at least ci-throwaway.json.',
+        evidence: { manifestCount: 0 },
       }],
     };
   }
   const results = [];
   for (const f of files) {
+    const manifestSha256 = sha256(f.text);
     let doc;
     try {
       doc = JSON.parse(f.text);
     } catch (err) {
       results.push({
-        anchorAcId,
+        anchorAcId: null,
+        conformanceOnly: true,
+        limitation: LIMIT_37102,
         verdict: 'fail',
-        detail: `manifest ${f.name} does not parse: ${err.message}`,
+        detail: `offline manifest scan: manifest ${f.name} does not parse: ${err.message}`,
+        evidence: { manifestSha256, manifestName: f.name, parseError: err.message },
       });
       continue;
     }
     const errors = validate(schema, doc, `#/${f.name}`);
-    if (errors.length > 0) {
-      for (const e of errors) {
-        const anchor = anchorForError(e);
+    // General schema errors that are neither firewall- nor snapshot-
+    // scoped anchor to AC-37102-1 (as their limitation).
+    const generalErrors = errors.filter((e) => (
+      e.field !== 'firewallRules' && !(e.path || '').includes('firewallRules')
+      && e.field !== 'snapshotCadence' && !(e.path || '').includes('snapshotCadence')
+    ));
+    if (generalErrors.length > 0) {
+      for (const e of generalErrors) {
         results.push({
-          anchorAcId: anchor,
+          anchorAcId: null,
+          conformanceOnly: true,
+          limitation: LIMIT_37102,
           verdict: 'fail',
-          detail: `manifest ${f.name} schema violation at ${e.path}: ${e.message}`,
+          detail: `offline manifest scan: manifest ${f.name} schema violation at ${e.path}: ${e.message}`,
+          evidence: { manifestSha256, manifestName: f.name, jsonPath: e.path, message: e.message, field: e.field || null },
         });
       }
     } else {
+      const observedKeys = Object.keys(doc).sort();
       results.push({
-        anchorAcId,
+        anchorAcId: null,
+        conformanceOnly: true,
+        limitation: LIMIT_37102,
         verdict: 'pass',
-        detail: `manifest ${f.name} validates against hetzner-server.schema.json (nine required fields, firewall rule shape, snapshotCadence enum all satisfied).`,
+        detail: `offline manifest scan: manifest ${f.name} carries the nine required fields per hetzner-server.schema.json.`,
+        evidence: {
+          manifestSha256,
+          manifestName: f.name,
+          requiredFields: NINE_REQUIRED,
+          observedKeys,
+        },
+      });
+    }
+    const firewallErrors = errors.filter((e) => e.field === 'firewallRules' || (e.path || '').includes('firewallRules'));
+    if (firewallErrors.length > 0) {
+      for (const e of firewallErrors) {
+        results.push({
+          anchorAcId: null,
+          conformanceOnly: true,
+          limitation: LIMIT_37106,
+          verdict: 'fail',
+          detail: `offline firewall shape scan: manifest ${f.name} firewall rule shape violation at ${e.path}: ${e.message}`,
+          evidence: { manifestSha256, manifestName: f.name, jsonPath: e.path, message: e.message },
+        });
+      }
+    } else if (Array.isArray(doc.firewallRules)) {
+      const rules = doc.firewallRules;
+      const REQUIRED_BINDING = {
+        ssh:   { protocol: 'tcp', direction: 'in', port: 22,  sourceMustOpen: false },
+        http:  { protocol: 'tcp', direction: 'in', port: 80,  sourceMustOpen: true },
+        https: { protocol: 'tcp', direction: 'in', port: 443, sourceMustOpen: true },
+      };
+      const nameCounts = {};
+      for (const r of rules) if (r && typeof r.name === 'string') nameCounts[r.name] = (nameCounts[r.name] || 0) + 1;
+      const duplicates = Object.entries(nameCounts).filter(([, n]) => n > 1).map(([n]) => n);
+      const bindingErrors = [];
+      const bindingEvidence = {};
+      for (const [name, want] of Object.entries(REQUIRED_BINDING)) {
+        const rule = rules.find((r) => r && r.name === name);
+        if (!rule) {
+          bindingErrors.push(`missing required rule '${name}'`);
+          continue;
+        }
+        const observed = {
+          name, protocol: rule.protocol, direction: rule.direction,
+          port: rule.port, sourceIps: Array.isArray(rule.sourceIps) ? rule.sourceIps : [],
+        };
+        bindingEvidence[name] = observed;
+        if (rule.protocol !== want.protocol) bindingErrors.push(`'${name}' protocol '${rule.protocol}' != required '${want.protocol}'`);
+        if (rule.direction !== want.direction) bindingErrors.push(`'${name}' direction '${rule.direction}' != required '${want.direction}'`);
+        if (rule.port !== want.port) bindingErrors.push(`'${name}' port ${rule.port} != required ${want.port}`);
+        if (!Array.isArray(rule.sourceIps) || rule.sourceIps.length === 0) {
+          bindingErrors.push(`'${name}' sourceIps empty or not array`);
+        } else if (want.sourceMustOpen) {
+          const hasOpen = rule.sourceIps.includes('0.0.0.0/0');
+          if (!hasOpen) bindingErrors.push(`'${name}' must include '0.0.0.0/0' per open-service contract`);
+        } else if (name === 'ssh') {
+          const openLeak = rule.sourceIps.filter((s) => s === '0.0.0.0/0' || s === '::/0');
+          if (openLeak.length > 0) bindingErrors.push(`'ssh' sourceIps must not include ${openLeak.join(', ')}; use operator-nominated set per TAC-3804`);
+        }
+      }
+      if (duplicates.length > 0) bindingErrors.push(`duplicate rule names: ${duplicates.join(', ')}`);
+      if (bindingErrors.length > 0) {
+        results.push({
+          anchorAcId: null,
+          conformanceOnly: true,
+          limitation: LIMIT_37106,
+          verdict: 'fail',
+          detail: `offline firewall shape scan: manifest ${f.name} firewall rule shape violation: ${bindingErrors.join('; ')}.`,
+          evidence: {
+            manifestSha256,
+            manifestName: f.name,
+            ruleNames: rules.map((r) => r && r.name).filter(Boolean),
+            observedBinding: bindingEvidence,
+            duplicates,
+            errors: bindingErrors,
+          },
+        });
+      } else {
+        const ssh = rules.find((r) => r && r.name === 'ssh');
+        results.push({
+          anchorAcId: null,
+          conformanceOnly: true,
+          limitation: LIMIT_37106,
+          verdict: 'pass',
+          detail: `offline firewall shape scan: manifest ${f.name} firewall rule shape valid: ssh (tcp/in/22, restricted to ${(ssh && ssh.sourceIps || []).join(', ')}, no 0.0.0.0/0), http (tcp/in/80, open), https (tcp/in/443, open); no duplicates.`,
+          evidence: {
+            manifestSha256,
+            manifestName: f.name,
+            ruleNames: rules.map((r) => r && r.name).filter(Boolean),
+            observedBinding: bindingEvidence,
+            duplicates: [],
+          },
+        });
+      }
+    }
+    const snapshotErrors = errors.filter((e) => e.field === 'snapshotCadence' || (e.path || '').includes('snapshotCadence'));
+    if (snapshotErrors.length > 0) {
+      for (const e of snapshotErrors) {
+        results.push({
+          anchorAcId: null,
+          conformanceOnly: true,
+          limitation: LIMIT_37107,
+          verdict: 'fail',
+          detail: `offline snapshotCadence scan: manifest ${f.name} snapshotCadence violation at ${e.path}: ${e.message}`,
+          evidence: { manifestSha256, manifestName: f.name, jsonPath: e.path, message: e.message },
+        });
+      }
+    } else if (typeof doc.snapshotCadence === 'string') {
+      results.push({
+        anchorAcId: null,
+        conformanceOnly: true,
+        limitation: LIMIT_37107,
+        verdict: 'pass',
+        detail: `offline snapshotCadence scan: manifest ${f.name} snapshotCadence "${doc.snapshotCadence}" is in the shipped enum {weekly, daily, off}.`,
+        evidence: {
+          manifestSha256,
+          manifestName: f.name,
+          snapshotCadence: doc.snapshotCadence,
+          shippedEnum: ['weekly', 'daily', 'off'],
+        },
       });
     }
   }
@@ -76,20 +228,8 @@ export default async function runProbe() {
   };
 }
 
-function anchorForError(err) {
-  if (err.field === 'firewallRules' || (err.path || '').includes('firewallRules')) {
-    return 'AC-37106-1';
-  }
-  if (err.field === 'snapshotCadence' || (err.path || '').includes('snapshotCadence')) {
-    return 'AC-37107-1';
-  }
-  return 'AC-37102-1';
-}
-
-// Draft-07 subset validator: required, type, enum, minLength, minItems,
-// additionalProperties, items, properties, required-on-array-items.
-// Extra rule: on firewallRules the ssh rule sourceIps must NOT include
-// 0.0.0.0/0 (per TAC-3804); handled after schema validation.
+// Draft-07 subset validator (unchanged from v1.1.3 apart from the
+// caller splitting per-property).
 export function validate(schema, doc, pathPrefix = '#') {
   const errors = [];
   walk(schema, doc, pathPrefix, errors);
@@ -112,6 +252,35 @@ export function validate(schema, doc, pathPrefix = '#') {
         });
       }
     }
+    // Reject duplicate rule names (defect: firewall
+    // validation must prohibit duplicates).
+    const counts = {};
+    for (const r of doc.firewallRules) if (r && typeof r.name === 'string') counts[r.name] = (counts[r.name] || 0) + 1;
+    for (const [name, n] of Object.entries(counts)) {
+      if (n > 1) {
+        errors.push({
+          path: `${pathPrefix}/firewallRules`,
+          field: 'firewallRules',
+          message: `firewallRules contains a duplicate rule named '${name}' (${n} occurrences); each of {ssh, http, https} must appear exactly once.`,
+        });
+      }
+    }
+    // Bind each required rule name to protocol/direction/port
+    // (defect).
+    const bindings = { ssh: { protocol: 'tcp', direction: 'in', port: 22 }, http: { protocol: 'tcp', direction: 'in', port: 80 }, https: { protocol: 'tcp', direction: 'in', port: 443 } };
+    for (const [name, want] of Object.entries(bindings)) {
+      const rule = doc.firewallRules.find((r) => r && r.name === name);
+      if (!rule) continue;
+      for (const k of ['protocol', 'direction', 'port']) {
+        if (rule[k] !== want[k]) {
+          errors.push({
+            path: `${pathPrefix}/firewallRules/${name}/${k}`,
+            field: 'firewallRules',
+            message: `firewallRules '${name}' ${k} '${rule[k]}' does not match required '${want[k]}' per TAC-3804.`,
+          });
+        }
+      }
+    }
   }
   return errors;
 }

package/blueprints/deploy-hetzner-server/contributions/probes/probe-utils.mjs

@@ -1,4 +1,12 @@
-// Shared helpers for deploy-hetzner-server probes.
+// Shared helpers for deploy-hetzner-server probes (v1.1.4, criterion e
+// v1.1.5, 2026-09-11).
+//
+// Every result row a probe returns MUST carry either an `evidence`
+// object naming the observed artefact (server id, inventory-diff,
+// response body excerpt, deploy record) OR `accountBoundSkipped: true`
+// with a `reason` field naming exactly one unset variable. Empty or
+// null probe outcomes FAIL with detail exactly `no checks ran` per
+// binding rule 3 of the criterion e .
 //
 // Runtime-dependency posture:
 // - cloud-init-render-lint, manifest-schema-validate and
@@ -7,9 +15,10 @@
 //   server/. No real API call fires; hcloud is mocked via
 //   src/hcloud-mock.mjs so the shim never crosses the process boundary.
 // - real-account-* probes call the fixture's provision.mjs / destroy.mjs
-//   / snapshot verbs. Without CI_HAS_HETZNER_ACCOUNT they record
-//   accountBoundSkipped: true and the aggregate flips to pass per
-//   hetzner-round-7-spec-2026-09-07.md section 3.5.
+//   / snapshot verbs. Without CI_HAS_HETZNER_ACCOUNT set to exactly the
+//   string "true", each probe records accountBoundSkipped: true and a
+//   reason naming CI_HAS_HETZNER_ACCOUNT (set-but-not-true is reported
+//   as such, distinguished from unset).
 
 import { mkdir, writeFile, readFile, readdir } from 'node:fs/promises';
 import { dirname, resolve, join } from 'node:path';
@@ -21,39 +30,83 @@ export const FIXTURE_DIR = resolve(
   PROJECT_ROOT,
   'packages/rcf-lite/test/fixtures/hetzner-throwaway-server',
 );
-// Config override, not a mutation switch: the fixture-side shim for
-// manifest-schema-validate may write a mutated copy to a scratch dir
-// and point MANIFEST_DIR at it via RCF_FIXTURE_MANIFEST_DIR so the
-// probe stays SIMULATE-free (mutation-purity gate row, 2026-09-08).
 export const MANIFEST_DIR = process.env.RCF_FIXTURE_MANIFEST_DIR
   ? resolve(process.env.RCF_FIXTURE_MANIFEST_DIR)
   : resolve(FIXTURE_DIR, 'hetzner/servers');
 export const SCHEMA_PATH = resolve(HERE, '..', 'schemas', 'hetzner-server.schema.json');
-export const REPORT_DIR = resolve(
-  PROJECT_ROOT,
-  '.rcf/reports/blueprints/deploy-hetzner-server',
-);
+export const REPORT_DIR = process.env.RCF_REPORT_DIR_OVERRIDE
+  ? resolve(process.env.RCF_REPORT_DIR_OVERRIDE, 'blueprints/deploy-hetzner-server')
+  : resolve(PROJECT_ROOT, '.rcf/reports/blueprints/deploy-hetzner-server');
+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;
+}
+
+// Aggregation rule (the shape rule): an empty results array is never
+// pass; it is a fail with detail `no checks ran`. Callers hand the
+// empty case a synthesised fail row via `emptyResultsFail()` before
+// aggregating so the report body itself carries the row.
 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: 'deploy-hetzner-server',
     probeName,
+    version,
     runAt: new Date().toISOString(),
     engine,
-    results,
+    results: rows,
     aggregateVerdict,
     ...(extra ?? {}),
   };
@@ -64,17 +117,27 @@ 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).
+    // The runShim caller carries the probeName so evidence names it.
     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');
@@ -102,11 +165,66 @@ export async function readManifestFiles(dir = MANIFEST_DIR) {
   return { present: entries.length > 0, entries, files };
 }
 
-export function accountBoundSkippedResult(anchorAcId, note) {
+// Skip helper (the shape rule): the reason field names exactly one
+// unset variable. A gate variable set to a value other than 'true'
+// is reported as `set-but-not-true` with the observed value, not as
+// `unset`. Callers hand the exact variable name and 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 in `reason`,
+// carries accountBoundSkipped: true, and the aggregate still flips 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.'}`,
+  };
+}
+
+// Legacy shim (kept during the update cutover for callers not yet
+// updated). Prefer firstTierGateSkipResult / secondTierMissingSkipResult.
+export function accountBoundSkippedResult(anchorAcId, note) {
+  return firstTierGateSkipResult(anchorAcId, 'CI_HAS_HETZNER_ACCOUNT', note);
+}
+
+// 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 deploy-hetzner-server ACs and the shared AC-14501-1 chain
+// artefact (used elsewhere in the estate); callers wrap their detail
+// via `anchored(anchorAcId, detail)`.
+export const AC_ANCHOR_PREFIX = {
+  'AC-37101-1': 'On process boot the provisioner facade opens against',
+  'AC-37102-1': 'manifest-schema-validate.mjs asserts every hetzner/servers/*.json under the shared throwaway-server',
+  'AC-37103-1': 'The real-account-throwaway-server-provision probe (accountBound: true, skipped without CI_HAS_HETZNER_ACCOUNT)',
+  'AC-37104-1': 'cloud-init-render-lint.mjs renders the template with the fixture manifest',
+  'AC-37105-1': 'real-account-cloud-init-hardened.mjs (accountBound: true, skipped without CI_HAS_HETZNER_ACCOUNT) waits for',
+  'AC-37106-1': 'manifest-schema-validate.mjs asserts every fixture manifest carries a firewallRules',
+  'AC-37107-1': 'manifest-schema-validate.mjs asserts every fixture manifest carries snapshotCadence with',
+  'AC-37108-1': 'real-account-snapshot-on-demand.mjs (accountBound: true, skipped without CI_HAS_HETZNER_ACCOUNT) fires the',
+  'AC-37109-1': 'hcloud-dry-run-mock.mjs drives every lifecycle event through the facade',
+  'AC-37109-3': 'Event fires once per lifecycle moment (repeat-run idempotency).',
+};
+
+export function anchored(anchorAcId, body) {
+  const prefix = AC_ANCHOR_PREFIX[anchorAcId];
+  return prefix ? `${prefix}. ${body}` : body;
+}