@stravica-ai/rcf-verify-lite 0.1.0

package/src/provision/index.js

@@ -0,0 +1,249 @@
+// Prerequisite provisioning (spec §6, amendment 2). Adversarial verification
+// usually can't start from nothing. One mechanism, three kinds of
+// prerequisite the chain's ACs may imply: auth accounts (common), third-party
+// service sandboxes/keys, and seeded test data.
+//
+// Hard rules this module enforces (each a §10 acceptance criterion):
+//  - the `zzverify-` prefix on ALL provisioned artefacts, so they are
+//    greppable and sweepable;
+//  - credentials/keys go ONLY to the --provision file, NEVER inline, NEVER
+//    echoed to logs or the report body (redactSecrets is the guard);
+//  - what cannot be provisioned is BLOCKED (naming the missing prerequisite)
+//    and its dependent ACs are marked BLOCKED — never silently skipped;
+//  - cleanup removes provisioned artefacts and the report states what it did.
+
+import { writeFile, readFile } from 'node:fs/promises';
+
+import { rcfError } from '@stravica-ai/rcf-lite-core/errors';
+
+/** Greppable prefix on every provisioned artefact (accounts + data alike). */
+export const ZZVERIFY_PREFIX = 'zzverify-';
+
+/** v1 auth provisioning stands up at least this many accounts (multi-user isolation journeys). */
+export const MIN_AUTH_ACCOUNTS = 2;
+
+/** Field names whose VALUES must never reach a log or the report body. */
+export const SECRET_FIELDS = Object.freeze(['password', 'token', 'secret', 'key', 'apiKey', 'credential', 'cookie']);
+
+const AUTH_PATTERNS = /\b(sign[\s-]?in|sign[\s-]?up|log[\s-]?in|logout|register|registration|authenticat|account|password|credential|session|onboard)/i;
+const SERVICE_PATTERNS = /\b(payment|stripe|checkout|billing|sandbox|webhook|third[\s-]?party|external api|e-?mail send|sms|twilio|sendgrid|oauth provider)/i;
+const SEEDDATA_PATTERNS = /\b(admin[\s-]?(created|seeded)|seeded|pre[\s-]?populated|existing (record|row|dataset)|another user|user b\b|other user)/i;
+
+/**
+ * Classify the prerequisite kind an AC implies (or null if none). Matches on
+ * the AC's given/when/then/description text. Heuristic — the honest hard part
+ * (§6): where the route can't be derived, the caller BLOCKS rather than skips.
+ *
+ * @param {object} ac - a flattened AC ({acId, description, given, when, then})
+ * @returns {'authAccount'|'serviceSandbox'|'seedData'|null}
+ */
+export function classifyPrerequisite(ac) {
+  const text = [ac.description, ac.given, ac.when, ac.then, ac.title].filter(Boolean).join(' ');
+  if (SERVICE_PATTERNS.test(text)) return 'serviceSandbox';
+  if (SEEDDATA_PATTERNS.test(text)) return 'seedData';
+  if (AUTH_PATTERNS.test(text)) return 'authAccount';
+  return null;
+}
+
+/**
+ * Derive the provisioning plan from the chain's ACs: which prerequisite kinds
+ * are required, and which ACs depend on each. v1 automates authAccount against
+ * signup-exposing apps; serviceSandbox / seedData routes are honestly BLOCKED
+ * unless an out-of-band route is supplied (§6 v1 scope note).
+ *
+ * @param {Array<object>} acs
+ * @returns {{ required: string[], acsByKind: Record<string, string[]> }}
+ */
+export function deriveProvisioningPlan(acs = []) {
+  const acsByKind = {};
+  for (const ac of acs) {
+    const kind = classifyPrerequisite(ac);
+    if (!kind) continue;
+    (acsByKind[kind] ??= []).push(ac.acId);
+  }
+  return { required: Object.keys(acsByKind), acsByKind };
+}
+
+/**
+ * Deep-redact secret values for anything bound for a log or the report body.
+ * Returns a new object; input untouched. Any key in SECRET_FIELDS (case-
+ * insensitive) has its value replaced with '[redacted]'.
+ *
+ * @param {unknown} value
+ * @returns {unknown}
+ */
+export function redactSecrets(value) {
+  if (Array.isArray(value)) return value.map(redactSecrets);
+  if (value && typeof value === 'object') {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      out[k] = SECRET_FIELDS.some((f) => f.toLowerCase() === k.toLowerCase())
+        ? '[redacted]'
+        : redactSecrets(v);
+    }
+    return out;
+  }
+  return value;
+}
+
+/**
+ * Write provisioned credentials to the --provision file (spec §3 rule 3, §6).
+ * This is the ONLY sink for secrets. Never returns the secrets to the caller
+ * for logging.
+ *
+ * @param {string} provisionPath
+ * @param {object} data - full provisioning record including credentials
+ * @returns {Promise<import('@stravica-ai/rcf-lite-core/errors').RcfError | null>}
+ */
+export async function writeProvisionFile(provisionPath, data) {
+  if (typeof provisionPath !== 'string' || provisionPath.length === 0) {
+    return rcfError({ kind: 'usage', message: '--provision requires a file path', field: 'provision' });
+  }
+  try {
+    await writeFile(provisionPath, JSON.stringify(data, null, 2), 'utf8');
+    return null;
+  } catch (err) {
+    return rcfError({ kind: 'ioFailure', message: `failed to write provision file: ${err.message}`, filePath: provisionPath, stack: err.stack });
+  }
+}
+
+/**
+ * Read a provisioning file (credentials/fixtures) back for a run/cleanup.
+ *
+ * @param {string} provisionPath
+ * @returns {Promise<object | import('@stravica-ai/rcf-lite-core/errors').RcfError>}
+ */
+export async function readProvisionFile(provisionPath) {
+  try {
+    return JSON.parse(await readFile(provisionPath, 'utf8'));
+  } catch (err) {
+    return rcfError({ kind: 'ioFailure', message: `failed to read provision file: ${err.message}`, filePath: provisionPath, stack: err.stack });
+  }
+}
+
+/**
+ * Provision auth accounts against a signup-exposing app. The actual signup is
+ * app-specific and agent-driven — supplied via the injected `signup` function
+ * (the seam; §6 "the provisioning route is app-specific"). Without a signup
+ * route the whole kind is BLOCKED, honestly.
+ *
+ * @param {object} opts
+ * @param {string} opts.url
+ * @param {number} [opts.count]
+ * @param {((ctx: {url: string, username: string}) => Promise<object>)} [opts.signup]
+ *   - returns account credentials; may throw to signal an unprovisionable app
+ * @returns {Promise<{ provisioned: object[], blocked: object[], credentials: object[] }>}
+ */
+export async function provisionAuth({ url, count = MIN_AUTH_ACCOUNTS, signup } = {}) {
+  const provisioned = [];
+  const blocked = [];
+  const credentials = [];
+  if (typeof signup !== 'function') {
+    blocked.push({ kind: 'authAccount', reason: 'cannot provision: app exposes no derivable signup route (invite-only / admin-seeded / out-of-band). See §6 deferred.' });
+    return { provisioned, blocked, credentials };
+  }
+  const suffixes = 'abcdefghijklmnopqrstuvwxyz';
+  for (let i = 0; i < Math.max(count, MIN_AUTH_ACCOUNTS); i += 1) {
+    const ref = `${ZZVERIFY_PREFIX}${suffixes[i] ?? String(i)}`;
+    try {
+      const creds = await signup({ url, username: ref });
+      provisioned.push({ kind: 'authAccount', ref });
+      credentials.push({ ref, ...creds });
+    } catch (err) {
+      blocked.push({ kind: 'authAccount', reason: `cannot provision ${ref}: ${err.message}` });
+    }
+  }
+  return { provisioned, blocked, credentials };
+}
+
+/**
+ * Run provisioning end-to-end for a `run` (spec §6, run-internalised). Derives
+ * the plan, provisions auth where a signup route exists, BLOCKS every other
+ * required kind (naming the missing prerequisite), marks dependent ACs as
+ * BLOCKED, and writes credentials to the --provision file only.
+ *
+ * @param {object} opts
+ * @param {Array<object>} opts.acs
+ * @param {string} opts.url
+ * @param {string} [opts.provisionPath]
+ * @param {'run'|'skip'} [opts.mode]
+ * @param {((ctx: object) => Promise<object>)} [opts.signup] - injected signup route
+ * @returns {Promise<{ provisioning: object, blockedAcs: object[] }>}
+ */
+export async function runProvisioning({ acs = [], url, provisionPath, mode = 'run', signup } = {}) {
+  const provisioning = { provisioned: [], blocked: [], cleanupRan: false, cleanupRemoved: [] };
+  const blockedAcs = [];
+
+  if (mode === 'skip') return { provisioning, blockedAcs };
+
+  const plan = deriveProvisioningPlan(acs);
+  const allCredentials = [];
+
+  for (const kind of plan.required) {
+    const dependentAcIds = plan.acsByKind[kind] ?? [];
+    if (kind === 'authAccount') {
+      const { provisioned, blocked, credentials } = await provisionAuth({ url, signup });
+      provisioning.provisioned.push(...provisioned);
+      provisioning.blocked.push(...blocked);
+      allCredentials.push(...credentials);
+      // If auth could not be provisioned at all, its dependent ACs are BLOCKED.
+      if (provisioned.length === 0) {
+        const reason = blocked[0]?.reason ?? 'cannot provision: authAccount';
+        for (const acId of dependentAcIds) blockedAcs.push({ acId, reason });
+      }
+    } else {
+      // serviceSandbox / seedData — v1 honest BLOCK unless an out-of-band route exists.
+      const reason = `cannot provision: ${kind} (out-of-band route required — §6 v1 deferred)`;
+      provisioning.blocked.push({ kind, reason });
+      for (const acId of dependentAcIds) blockedAcs.push({ acId, reason });
+    }
+  }
+
+  // Credentials go ONLY to the provision file — never into `provisioning`
+  // (which lands in the report body) and never returned for logging.
+  if (allCredentials.length > 0 && provisionPath) {
+    const writeErr = await writeProvisionFile(provisionPath, {
+      schemaVersion: '1',
+      url,
+      credentials: allCredentials,
+    });
+    // Surface the write failure as data instead of discarding it: a failed
+    // credential write means the run's provisioned accounts are unusable
+    // downstream, and silently swallowing it hid a real fault (w-2026-07-21-006).
+    // Only the message + path are recorded — never the credentials themselves.
+    if (writeErr) {
+      provisioning.provisionWriteError = { message: writeErr.message, filePath: writeErr.filePath ?? provisionPath };
+    }
+  }
+
+  return { provisioning, blockedAcs };
+}
+
+/**
+ * Tear down provisioned artefacts (spec §6 cleanup contract). The actual
+ * teardown is app-specific — supplied via the injected `teardown` function.
+ * Records what it removed for the report.
+ *
+ * @param {object} opts
+ * @param {object[]} [opts.provisioned] - [{kind, ref}]
+ * @param {((ref: string) => Promise<void>)} [opts.teardown]
+ * @returns {Promise<{ cleanupRan: boolean, cleanupRemoved: string[], cleanupBlocked: object[] }>}
+ */
+export async function cleanup({ provisioned = [], teardown } = {}) {
+  const cleanupRemoved = [];
+  const cleanupBlocked = [];
+  if (typeof teardown !== 'function') {
+    // No teardown route — report honestly rather than claim a clean sweep.
+    for (const p of provisioned) cleanupBlocked.push({ ref: p.ref, reason: 'no teardown route supplied' });
+    return { cleanupRan: false, cleanupRemoved, cleanupBlocked };
+  }
+  for (const p of provisioned) {
+    try {
+      await teardown(p.ref);
+      cleanupRemoved.push(p.ref);
+    } catch (err) {
+      cleanupBlocked.push({ ref: p.ref, reason: err.message });
+    }
+  }
+  return { cleanupRan: true, cleanupRemoved, cleanupBlocked };
+}

package/src/report/index.js

@@ -0,0 +1,107 @@
+// Report artifact (spec §5.3). The report is NOT a dead-end artifact — it is
+// build-lite's next input (§5.4), so it is emitted chain-node-addressed and
+// camelCase, with `schemaVersion` from day one so build-lite's ingest can
+// version-gate. Credentials never appear in the report body (§10) — the
+// builder passes an already-clean provisioning record, and redactSecrets is a
+// defence-in-depth guard on top.
+
+import { rcfError } from '@stravica-ai/rcf-lite-core/errors';
+
+import { redactSecrets } from '../provision/index.js';
+import { VERDICTS } from '../verdict/index.js';
+
+/** The report schema version. Present from day one for build-lite's version-gated ingest. */
+export const SCHEMA_VERSION = '1';
+
+const DEFAULT_PERSONA = 'generic-sceptic';
+
+/**
+ * Assemble the §5.3 report object. Pure — all runtime facts are passed in.
+ *
+ * @param {object} p
+ * @returns {object} the report artifact
+ */
+export function buildReport(p) {
+  const report = {
+    schemaVersion: SCHEMA_VERSION,
+    run: {
+      profile: p.profile,
+      url: p.url,
+      parityEnv: Boolean(p.parityEnv),
+      reachability: p.reachability ?? null,
+      chainRef: p.chainRef ?? null,
+      repo: p.repo ?? null,
+      persona: p.persona ?? DEFAULT_PERSONA,
+      startedAt: p.startedAt ?? null,
+      finishedAt: p.finishedAt ?? null,
+      verifierIsolation: p.verifierIsolation ?? { autoMemory: false, nonEssentialTraffic: false },
+      // Agent usage/timing from the --output-format json envelope (§5.3, additive).
+      // Omit-not-fake: null when the launcher could not report it.
+      runStats: p.runStats ?? null,
+    },
+    verdict: p.verdict,
+    verdictAuthority: p.verdictAuthority,
+    findings: Array.isArray(p.findings) ? p.findings : [],
+    blockedAcs: Array.isArray(p.blockedAcs) ? p.blockedAcs : [],
+    provisioning: p.provisioning ?? null,
+    // Present (non-null) only on a LAUNCH-FAILURE verdict: the agent could not
+    // run or its output could not be ingested. Carries the error + the path to
+    // the preserved raw transcript so the §5.4 fix loop has something to ingest.
+    launchFailure: p.launchFailure ?? null,
+  };
+  // Defence-in-depth: never let a secret reach the report body (§10).
+  return redactSecrets(report);
+}
+
+/**
+ * Serialise a report to the on-disk artifact string (camelCase JSON).
+ *
+ * @param {object} report
+ * @returns {string}
+ */
+export function serialiseReport(report) {
+  return `${JSON.stringify(report, null, 2)}\n`;
+}
+
+/**
+ * Parse a report artifact back (for `rcf-verify report`). Errors as data.
+ *
+ * @param {string} raw
+ * @returns {object | import('@stravica-ai/rcf-lite-core/errors').RcfError}
+ */
+export function parseReport(raw) {
+  let doc;
+  try {
+    doc = JSON.parse(raw);
+  } catch (err) {
+    return rcfError({ kind: 'parseFailure', message: `report is not valid JSON: ${err.message}` });
+  }
+  const shapeErr = validateReportShape(doc);
+  if (shapeErr) return shapeErr;
+  return doc;
+}
+
+/**
+ * Minimal shape check on a report artifact.
+ *
+ * @param {object} doc
+ * @returns {import('@stravica-ai/rcf-lite-core/errors').RcfError | null}
+ */
+export function validateReportShape(doc) {
+  if (!doc || typeof doc !== 'object') {
+    return rcfError({ kind: 'validation', message: 'report must be an object' });
+  }
+  if (doc.schemaVersion !== SCHEMA_VERSION) {
+    return rcfError({ kind: 'validation', message: `unsupported report schemaVersion: ${doc.schemaVersion ?? '(missing)'}`, field: 'schemaVersion' });
+  }
+  if (!VERDICTS.includes(doc.verdict)) {
+    return rcfError({ kind: 'validation', message: `unknown verdict: ${doc.verdict}`, field: 'verdict' });
+  }
+  if (doc.verdictAuthority !== 'ship' && doc.verdictAuthority !== 'correctness') {
+    return rcfError({ kind: 'validation', message: `verdictAuthority must be ship|correctness (got ${doc.verdictAuthority})`, field: 'verdictAuthority' });
+  }
+  if (!doc.run || typeof doc.run !== 'object') {
+    return rcfError({ kind: 'validation', message: 'report.run is required', field: 'run' });
+  }
+  return null;
+}

package/src/report/renderer.js

@@ -0,0 +1,104 @@
+// Self-contained finding-renderer (spec §5.3, §7.2). v1 core is store + errors
+// + mcp-shell ONLY — the build `view/` layer is NOT a clean shell and is
+// firmly OUT of v1 core. So verify ships its OWN minimal, dependency-free human
+// render for `rcf-verify report`. Plain text, British English, ASCII hyphens —
+// mirrors build's help-surface conventions without importing any core view code.
+//
+// Honest-limit language (§9): the render NEVER says "fully verified" / "safe".
+
+/** One-line human summary of a verdict, including its ship implication. */
+const VERDICT_LINE = {
+  PASS: 'PASS — every AC verified against the running app; no defect above COSMETIC.',
+  BROKEN: 'BROKEN — one or more ACs fail on the running app. Blocks ship.',
+  DEGRADED: 'DEGRADED — app works but a criterion is materially weakened. Reported; may block per gate.',
+  COSMETIC: 'COSMETIC — hygiene only; no AC touched. Does not block.',
+  'NOT-DEPLOYED': 'NOT-DEPLOYED — deployed profile declared but no real deploy reachable. A refusal to issue a verdict, not a pass.',
+  BLOCKED: 'BLOCKED — a prerequisite could not be provisioned; dependent ACs were not exercisable.',
+  'LAUNCH-FAILURE': 'LAUNCH-FAILURE — the verifier agent could not run or its output could not be ingested. A refusal to issue a verdict, not a pass.',
+};
+
+/**
+ * Render a report artifact to a human-readable string.
+ *
+ * @param {object} report
+ * @returns {string}
+ */
+export function renderReport(report) {
+  const lines = [];
+  const run = report.run ?? {};
+  lines.push('RCF Verify — verification report');
+  lines.push('='.repeat(40));
+  lines.push(`Verdict:   ${report.verdict}  [authority: ${report.verdictAuthority}]`);
+  lines.push(`  ${VERDICT_LINE[report.verdict] ?? ''}`.trimEnd());
+  lines.push('');
+  lines.push('Runtime provenance');
+  lines.push(`  profile:   ${run.profile}`);
+  lines.push(`  url:       ${run.url}`);
+  lines.push(`  parityEnv: ${run.parityEnv === true}`);
+  if (run.reachability) {
+    lines.push(`  reachable: ${run.reachability.reachable}  looksLocal: ${run.reachability.looksLocal}`);
+  }
+  lines.push(`  chainRef:  ${run.chainRef ?? '(none)'}`);
+  lines.push(`  persona:   ${run.persona ?? '(default)'}`);
+  if (run.verifierIsolation) {
+    lines.push(`  isolation: autoMemory=${run.verifierIsolation.autoMemory} nonEssentialTraffic=${run.verifierIsolation.nonEssentialTraffic}`);
+  }
+  lines.push('');
+
+  const findings = report.findings ?? [];
+  lines.push(`Findings (${findings.length})`);
+  if (findings.length === 0) {
+    lines.push('  (none)');
+  } else {
+    for (const f of findings) {
+      lines.push(`  [${f.severity}] ${f.acId} — ${f.journey}`);
+      for (const step of f.reproSteps ?? []) lines.push(`      - ${step}`);
+      if (f.evidence) {
+        const detail = f.evidence.detail ?? f.evidence.kind ?? JSON.stringify(f.evidence);
+        lines.push(`      evidence: ${detail}`);
+      }
+    }
+  }
+  lines.push('');
+
+  const blocked = report.blockedAcs ?? [];
+  if (blocked.length > 0) {
+    lines.push(`Blocked ACs (${blocked.length}) — NOT exercisable, not silently skipped`);
+    for (const b of blocked) lines.push(`  ${b.acId}: ${b.reason}`);
+    lines.push('');
+  }
+
+  if (report.launchFailure) {
+    lines.push('Launch failure');
+    lines.push(`  ${report.launchFailure.message}`);
+    if (report.launchFailure.rawOutputPath) lines.push(`  raw transcript: ${report.launchFailure.rawOutputPath}`);
+    lines.push('');
+  }
+
+  if (run.runStats) {
+    const s = run.runStats;
+    const bits = [];
+    if (typeof s.durationMs === 'number') bits.push(`duration=${s.durationMs}ms`);
+    if (typeof s.numTurns === 'number') bits.push(`turns=${s.numTurns}`);
+    if (s.tokens) bits.push(`tokens in/out=${s.tokens.inputTokens ?? '?'}/${s.tokens.outputTokens ?? '?'}`);
+    if (typeof s.totalCostUsd === 'number') bits.push(`cost=$${s.totalCostUsd.toFixed(4)}`);
+    if (bits.length) {
+      lines.push(`Run stats: ${bits.join('  ')}`);
+      lines.push('');
+    }
+  }
+
+  const prov = report.provisioning;
+  if (prov) {
+    lines.push('Provisioning');
+    lines.push(`  provisioned: ${(prov.provisioned ?? []).map((p) => p.ref).join(', ') || '(none)'}`);
+    if ((prov.blocked ?? []).length) {
+      lines.push(`  blocked:     ${prov.blocked.map((b) => `${b.kind} (${b.reason})`).join('; ')}`);
+    }
+    lines.push(`  cleanupRan:  ${prov.cleanupRan === true}  removed: ${(prov.cleanupRemoved ?? []).join(', ') || '(none)'}`);
+    lines.push('');
+  }
+
+  lines.push('Note: this is an independent ship-readiness signal, not a correctness guarantee.');
+  return `${lines.join('\n')}\n`;
+}

package/src/verdict/index.js

@@ -0,0 +1,103 @@
+// Verdict taxonomy + aggregation (spec §5.1, §5.2). Mirrors the persona
+// programme's PASS/BROKEN/DEGRADED/COSMETIC, plus the structural verdicts
+// NOT-DEPLOYED (§4 refusal), BLOCKED (§6 unprovisionable), and LAUNCH-FAILURE
+// (the verifier agent could not run or its output could not be ingested — a
+// refusal to issue a verdict on the app, never a soft pass; see engine catch).
+//
+// Split verdicts are held split, NEVER averaged (§5.1): a run is BROKEN if
+// ANY finding is BROKEN, regardless of how many ACs passed.
+
+import { rcfError } from '@stravica-ai/rcf-lite-core/errors';
+
+/** Finding severities, low → high. */
+export const FINDING_SEVERITIES = Object.freeze(['PASS', 'COSMETIC', 'DEGRADED', 'BROKEN']);
+
+/** Severity rank for the split-not-averaged max and the severity gate. */
+export const SEVERITY_ORDER = Object.freeze({ PASS: 0, COSMETIC: 1, DEGRADED: 2, BROKEN: 3 });
+
+/** All overall-verdict classes (findings severities + the three structural verdicts). */
+export const VERDICTS = Object.freeze([...FINDING_SEVERITIES, 'NOT-DEPLOYED', 'BLOCKED', 'LAUNCH-FAILURE']);
+
+/**
+ * Required fields on every finding (spec §5.2): the RCF payoff is that every
+ * defect maps to a contract line (acId / chain node), never a free-floating
+ * bug.
+ *
+ * @param {object} finding
+ * @returns {import('@stravica-ai/rcf-lite-core/errors').RcfError | null} error as data, or null if valid
+ */
+export function validateFinding(finding) {
+  if (!finding || typeof finding !== 'object') {
+    return rcfError({ kind: 'validation', message: 'finding must be an object' });
+  }
+  if (!FINDING_SEVERITIES.includes(finding.severity)) {
+    return rcfError({ kind: 'validation', message: `finding.severity must be one of ${FINDING_SEVERITIES.join('/')}`, field: 'severity' });
+  }
+  if (typeof finding.acId !== 'string' || finding.acId.length === 0) {
+    return rcfError({ kind: 'validation', message: 'finding.acId (chain-node reference) is required', field: 'acId' });
+  }
+  if (typeof finding.journey !== 'string' || finding.journey.length === 0) {
+    return rcfError({ kind: 'validation', message: 'finding.journey is required', field: 'journey' });
+  }
+  if (!Array.isArray(finding.reproSteps)) {
+    return rcfError({ kind: 'validation', message: 'finding.reproSteps must be an array', field: 'reproSteps' });
+  }
+  if (!finding.evidence || typeof finding.evidence !== 'object') {
+    return rcfError({ kind: 'validation', message: 'finding.evidence must be an object', field: 'evidence' });
+  }
+  return null;
+}
+
+/**
+ * The worst (max) severity across findings. Empty → PASS. This is the
+ * split-not-averaged rule: the single worst finding drives the class.
+ *
+ * @param {Array<{severity: string}>} findings
+ * @returns {'PASS'|'COSMETIC'|'DEGRADED'|'BROKEN'}
+ */
+export function aggregateSeverity(findings = []) {
+  let worst = 'PASS';
+  for (const f of findings) {
+    if ((SEVERITY_ORDER[f.severity] ?? -1) > SEVERITY_ORDER[worst]) worst = f.severity;
+  }
+  return worst;
+}
+
+/**
+ * The overall run verdict (spec §5.1). NOT-DEPLOYED and a fully-blocked run
+ * are structural verdicts; otherwise the worst finding severity wins
+ * (split-not-averaged). A run with SOME findings and SOME blocked ACs is a
+ * partial verification: the verdict reflects what WAS exercised, and the
+ * blocked ACs are named separately in the report.
+ *
+ * @param {object} opts
+ * @param {Array<{severity: string}>} [opts.findings]
+ * @param {Array<object>} [opts.blockedAcs]
+ * @param {boolean} [opts.notDeployed]
+ * @returns {string}
+ */
+export function aggregateVerdict({ findings = [], blockedAcs = [], notDeployed = false } = {}) {
+  if (notDeployed) return 'NOT-DEPLOYED';
+  if (findings.length === 0 && blockedAcs.length > 0) return 'BLOCKED';
+  return aggregateSeverity(findings);
+}
+
+/**
+ * Whether the severity gate is tripped → the process exits non-zero
+ * (spec §3 rule 5, §8.2). NOT-DEPLOYED, BLOCKED and LAUNCH-FAILURE always trip
+ * (ship cannot be confirmed); otherwise the worst finding severity is compared
+ * against the gate. With no gate configured, nothing trips — the report is
+ * still written.
+ *
+ * @param {object} opts
+ * @param {string} opts.verdict
+ * @param {Array<{severity: string}>} [opts.findings]
+ * @param {string|null} [opts.gate] - one of FINDING_SEVERITIES, or null/undefined
+ * @returns {boolean}
+ */
+export function gateTripped({ verdict, findings = [], gate }) {
+  if (verdict === 'NOT-DEPLOYED' || verdict === 'BLOCKED' || verdict === 'LAUNCH-FAILURE') return true;
+  if (!gate) return false;
+  const worst = aggregateSeverity(findings);
+  return SEVERITY_ORDER[worst] >= SEVERITY_ORDER[gate];
+}