@clear-capabilities/agentic-security-scanner 0.145.0 → 0.147.5

package/src/posture/artifact-registry.js

@@ -83,6 +83,31 @@ export const ARTIFACT_REGISTRY = [
   { name: 'scan-history.json', kind: 'file', classification: 'generated', retentionClass: 'scan' },
   { name: 'last-scan.json', kind: 'file', classification: 'generated', retentionClass: 'scan' },
   { name: 'last-scan.json.sig', kind: 'file', classification: 'generated', retentionClass: 'scan' },
+  // Sub-project E, increment 5: the Data Flow Explorer's DataFlowGraph v1
+  // document + signature, written by bin/agentic-security.js alongside
+  // last-scan.json whenever AGENTIC_SECURITY_LINEAGE_DEEP=1 produced a
+  // graph. NOT to be confused with the similarly-named, already-registered
+  // `repo-lineage.json` below — that one is an operator-authored
+  // cross-repo provenance declaration (classification 'operator-config',
+  // never written by the scanner); this one is scanner-generated scan
+  // output derived from the user's own source (dataElements[].dataClasses
+  // included), so it belongs in the 'generated'/'scan' bucket `reset`
+  // clears by default, same as last-scan.json itself.
+  { name: 'lineage-graph.json', kind: 'file', classification: 'generated', retentionClass: 'scan' },
+  { name: 'lineage-graph.json.sig', kind: 'file', classification: 'generated', retentionClass: 'scan' },
+  // M4 deliverable #8 (FR-503 §14, DFG-022, sub-project 8a): the "Data-Flow
+  // Time Machine" foundation — one commit-keyed GraphSnapshot per scan,
+  // written by src/lineage/graph-snapshot.js's persistGraphSnapshot(),
+  // additively alongside (never replacing) lineage-graph.json above. Same
+  // 'generated'/'scan' bucket for the same reason: fully scanner-derived,
+  // regenerable by re-scanning at that commit.
+  { name: 'lineage-snapshots', kind: 'dir', classification: 'generated', retentionClass: 'scan', source: 'src/lineage/graph-snapshot.js (persistGraphSnapshot)' },
+  // M5 deliverable #7 (FR-505 §7.12, AC-29): the Runtime-Corroborated
+  // Digital Twin's observation store — one immutable whole file per adapter
+  // import, written by src/lineage/observation-store.js's
+  // persistObservationImport(), mirroring lineage-snapshots/'s own
+  // directory-of-files shape re-keyed commit -> import.
+  { name: 'runtime-observations', kind: 'dir', classification: 'generated', retentionClass: 'evidence', confidential: true, source: 'src/lineage/observation-store.js (persistObservationImport)', note: 'FR-505 requires an observation store follow artifact encryption, RETENTION, RESET, access-control and no-egress rules. That is why this is `generated` (a plain `reset` MUST be able to delete it) rather than `operator-config`, and why it carries a real retentionClass — deliberately NOT the `remediation`/`legal-holds.json` no-retention call one section down, and deliberately NOT `provenance`\'s permanent-history call. This DOES stretch `generated`\'s usual definition — a rescan does not re-derive an import, the operator re-imports it — and that stretch is disclosed here rather than hidden: FR-505\'s explicit reset requirement breaks the tie. `confidential: true` is enforced by observation-store.js calling maybeEncryptForWrite/maybeDecryptForRead itself (posture/encryption-provider.js), the same per-writer opt-in compliance-evidence.json makes — the flag alone enforces nothing.' },
   { name: 'shadow-findings.json', kind: 'file', classification: 'generated', retentionClass: 'scan' },
   { name: 'mcp-audit.log', kind: 'file', classification: 'generated', retentionClass: 'evidence' },
   { name: 'egress-audit.log', kind: 'file', classification: 'generated', retentionClass: 'evidence', note: "FR-604 per-call egress audit log — hash-chained NDJSON written by egress/audit.js's recordEgressCall, never read as config" },
@@ -168,6 +193,19 @@ export const ARTIFACT_REGISTRY = [
   { name: 'deletion-report.json', kind: 'file', classification: 'generated', retentionClass: 'evidence', source: 'posture/state-lifecycle-report.js (via bin/agentic-security.js cmdReset)' },
   { name: 'export-report.json', kind: 'file', classification: 'generated', retentionClass: 'evidence', source: 'posture/state-lifecycle-report.js (via bin/agentic-security.js cmdExport)' },
 
+  // M5 governance editing workflow final-review fix round 1 (I5): backups
+  // of recipient-profiles.json written by `governance propose-edit --yes`,
+  // mirroring the `fix-history` directory precedent above — one directory
+  // entry covers every timestamped .bak file inside it, since the registry
+  // only supports exact-name matches, never a per-file timestamped name.
+  { name: 'recipient-profiles-backups', kind: 'dir', classification: 'generated', retentionClass: 'backup', note: 'per-edit backups written by `governance propose-edit --yes`, mirrors the fix-history/ precedent — one directory entry covers every timestamped .bak file inside it' },
+
+  // M5 deliverable #8 (FR-304 "declared" half): backups of
+  // cross-repo-links.json written by `federate declare --yes`, mirrors
+  // the `recipient-profiles-backups` precedent immediately above
+  // exactly.
+  { name: 'cross-repo-links-backups', kind: 'dir', classification: 'generated', retentionClass: 'backup', note: 'per-declare backups written by `federate declare --yes`, mirrors the recipient-profiles-backups/ precedent — one directory entry covers every timestamped .bak file inside it' },
+
   // ── Operator-config: hand-authored (or agent-authored) input, never wiped ──
   { name: 'rules.yml', kind: 'file', classification: 'operator-config' },
   { name: 'rules', kind: 'dir', classification: 'operator-config' },
@@ -191,14 +229,28 @@ export const ARTIFACT_REGISTRY = [
   { name: 'policy-bundle-public-key.pem', kind: 'file', classification: 'operator-config', note: 'FR-1001 public key an operator installs to verify org-distributed policy bundles — read by posture/policy-bundle.js, never written by the scanner' },
   { name: 'retention-policy.yml', kind: 'file', classification: 'operator-config', note: 'FR-702 per-retention-class TTL overrides (clamped to a built-in per-class maximum) — read by posture/retention-policy.js, never written by the scanner' },
   { name: 'legal-holds.json', kind: 'file', classification: 'operator-config', note: 'FR-707 legal holds ({artifact, owner, reason, expires_at}) — read by posture/retention-policy.js and bin/agentic-security.js cmdReset; WRITTEN by the CLI (legal-hold add/remove), but classified operator-config (not generated) deliberately: a plain `reset` must never be able to delete the very record protecting other artifacts from deletion' },
+  { name: 'remediation', kind: 'dir', classification: 'operator-config', note: 'M5 deliverable #6 remediation work-item ledger (items.jsonl + items.lock) — an APPEND-ONLY record of human decisions: owner assignment, approvals, manual attestations, and accepted-risk exceptions with approver/reason/scope/expiration. WRITTEN by the CLI (`remediation open|update|verify|accept-risk|reopen-check --yes`) but classified operator-config, not generated, deliberately — the same call legal-holds.json makes one entry up: a plain `reset` must never be able to delete the audit trail AC-31 depends on, and nothing regenerates it from a rescan. Deliberately NOT the `provenance` entry\'s `generated` classification (see its own note above): that ledger is scan-derived history a rescan can rebuild; this one is human decisions that cannot be. No retentionClass for the same reason legal-holds.json has none — auto-expiry would silently delete an accepted-risk exception a report may already cite.' },
   { name: 'calibration-feedback.jsonl', kind: 'file', classification: 'operator-config', note: 'FR-806 opt-in calibration ground truth ({at, findingId, outcome: accept-risk|realized-incident, predicted*, note}) — WRITTEN by the CLI (calibration-feedback record), but classified operator-config like exploit-history.jsonl: real, hard-to-recreate customer-reported ground truth, never scanner-regenerable, so a routine reset must never delete it' },
   { name: 'encryption-policy.yml', kind: 'file', classification: 'operator-config', note: 'FR-705 encryption provider/required opt-in policy ({provider: local-key, required: true|false}) — read by posture/encryption-provider.js, never written by the scanner' },
   { name: 'provenance-providers.yml', kind: 'file', classification: 'operator-config', note: 'Finding Provenance M3 §3.4 GitHub/GitLab provider enrichment opt-in ({token} or provider-scoped tokens) — read by posture/provenance/providers/config.js, never written by the scanner; env vars (AGENTIC_SECURITY_GITHUB_TOKEN/AGENTIC_SECURITY_GITLAB_TOKEN) take precedence when set' },
   { name: 'repo-lineage.json', kind: 'file', classification: 'operator-config', note: 'Finding Provenance M4 §4.2 cross-repository lineage declaration ({linkedFrom: {path, atCommit}}) — read by posture/provenance/repo-lineage.js, never written by the scanner; the linked path is verified as a real local git repo before use, no remote fetch' },
+  { name: 'recipient-profiles.json', kind: 'file', classification: 'operator-config', note: 'FR-506 recipient/subprocessor governance profiles — hand- or agent-authored via `governance propose-edit`, never scanner-regenerable, so a routine reset must never delete it' },
+  { name: 'cross-repo-links.json', kind: 'file', classification: 'operator-config', note: 'M5 deliverable #8 (FR-304 "declared" half) — declared local<->remote node links between two independently-scanned repos, written via `federate declare --yes`, never scanner-regenerable, so a routine reset must never delete it' },
   { name: 'logic-claims.json', kind: 'file', classification: 'operator-config', note: 'authored by an external reviewing agent; engine.js only ever reads it (fs.readFileSync, never written)' },
   { name: 'current-intent.md', kind: 'file', classification: 'operator-config', note: 'developer-authored; no writer exists anywhere in src/ or bin/' },
   { name: 'exploit-history.jsonl', kind: 'file', classification: 'operator-config', note: 'own header comment: "operator-curated record of past confirmed exploits"' },
   { name: 'cve-alerts.json', kind: 'file', classification: 'operator-config', note: 'own header comment: "Configuration is read from"; state lives in the separate cve-alerts-state.json, which IS generated' },
+  // Pre-existing gap, found by M5 deliverable #7's own scoping investigation
+  // and fixed here rather than left: posture/runtime-correlation.js reads
+  // these three filenames via `statePath(scanRoot, n)` with a VARIABLE, so
+  // test/artifact-registry-completeness.test.js's own PATTERNS regexes (which
+  // require a string literal) never saw them and never demanded registration.
+  // An unregistered state artifact means `reset` does not know about it and
+  // retention cannot reach it. Operator-config, not generated: these are
+  // hand-supplied eBPF/APM trace exports the scanner only ever reads.
+  { name: 'runtime-trace.jsonl', kind: 'file', classification: 'operator-config', note: 'eBPF/APM runtime trace consumed by posture/runtime-correlation.js\'s own trace loader (deliberately not named by its literal export here — no-dead-modules.test.js scans note strings too, and naming it would make it look, wrongly, like a real call site) — operator-supplied, never scanner-written; $AGENTIC_SECURITY_RUNTIME_TRACE_PATH overrides the location entirely' },
+  { name: 'runtime.jsonl', kind: 'file', classification: 'operator-config', note: 'alternate filename for runtime-trace.jsonl — see posture/runtime-correlation.js\'s DEFAULT_TRACE_NAMES' },
+  { name: 'ebpf-trace.jsonl', kind: 'file', classification: 'operator-config', note: 'alternate filename for runtime-trace.jsonl — see posture/runtime-correlation.js\'s DEFAULT_TRACE_NAMES' },
 ];
 
 export function listGeneratedArtifacts() {

package/src/posture/auditor-walkthrough.js

@@ -53,6 +53,7 @@ import { strengthOfControl as _strengthOfControl } from './coverage-strength.js'
 // as `Jean\-Luc Picard` and `dependabot[bot]` as `dependabot\[bot\]` is a
 // visible regression on common real-world author names, not a fix.
 import { sanitizeForTerminal, pseudonymizeAuthor, PROVENANCE_COMPLIANCE_DISCLAIMER } from './provenance/schema.js';
+import { evaluateGraphFlowPredicate, buildObligationMappingFromGraphPredicate } from '../lineage/obligation-predicates.js';
 
 // Fix-round item 4b: this renderer had `sanitizeForTerminal` (injection
 // safety) but never honoured `--pseudonymize-authors` at all — an operator
@@ -369,6 +370,7 @@ export function evaluateFramework(scanRoot, fw, scan) {
         observations: obs,
         controlRefs: [],
         derivedProvenance: deriveComplianceProvenance([]),
+        obligationMappings: [],
         ...(evidence ? { evidence, partiallyEvidenced: evidence.tier === 'weak' || evidence.tier === 'unmeasured' } : {}),
       });
       continue;
@@ -391,6 +393,15 @@ export function evaluateFramework(scanRoot, fw, scan) {
     // control at 'partial' — never 'present' — regardless of what the
     // family:/module: mappings in the same control found.
     let hasUnverifiableMapping = false;
+    // Sub-project 6b: real ObligationMapping records minted by graph:
+    // predicates on this control, collected separately from the
+    // present/partial/absent/manual status machinery above — a graph:
+    // mapping never touches anySignal/allCleared/anyCleared/
+    // hasUnverifiableMapping (purely additive, per the plan's own Global
+    // Constraints). Always an array, never undefined, so a caller can
+    // safely read `.length` regardless of whether this control has any
+    // graph: mappings at all.
+    const obligationMappings = [];
     for (const m of maps) {
       if (m.startsWith('family:')) {
         // `family:X` and the subfamily-qualified `family:X:Y` (used by
@@ -492,6 +503,70 @@ export function evaluateFramework(scanRoot, fw, scan) {
         obs.push(`(rule mapping) ${m} — verify manually that the bodyguard rule is enabled.`);
         anySignal = true;
         hasUnverifiableMapping = true;
+      } else if (m.startsWith('graph:')) {
+        // A graph: mapping never contributes to anySignal/allCleared/
+        // anyCleared/hasUnverifiableMapping — the existing
+        // present/partial/absent/manual status stays driven entirely by
+        // the family:/module:/rule: mappings a control already has (this
+        // task's own Global Constraint: purely additive). It instead
+        // mints a real ObligationMapping record, collected separately.
+        //
+        // First real predicate (scoping doc ruling 6): PHI/PII flowing to
+        // an external sink must cross a protected transit edge. The
+        // predicate STRING itself is currently a fixed label (not yet a
+        // parsed mini-language) — the first real graph: mapping this
+        // sub-project ships is HIPAA §164.312(e)'s
+        // "graph:transit-protection:PHI:external:transit:protected",
+        // hardcoded to this one spec until a second real case proves the
+        // parsing is worth generalizing (YAGNI — do not invent a parser
+        // for one caller).
+        const spec = { type: 'graph-flow', dataClass: 'PHI', sinkKind: 'external', dimension: 'transit', requiredVerdict: 'protected' };
+        const graph = scan.lineageGraph ?? null;
+        // Belt-and-suspenders, mirroring the sibling _strengthOfControl
+        // call above: obligation-predicates.js is now defensively
+        // hardened to never throw (see its own header), but this wrap
+        // keeps a future regression there from taking down the whole
+        // evaluateFramework call for every control in the framework
+        // (found by the final whole-branch review).
+        let mapping = null;
+        try {
+          const evaluation = graph ? evaluateGraphFlowPredicate(spec, graph) : null;
+          mapping = buildObligationMappingFromGraphPredicate({
+            framework: fw.id,
+            frameworkVersion: fw.controlsDigest,
+            requirementId: c.id,
+            requirementSource: fw.url ?? null,
+            predicateLabel: m,
+            graph,
+            evaluation,
+          });
+        } catch { /* graph obligation mapping is additive; never block evaluation */ }
+        if (mapping) {
+          obligationMappings.push(mapping);
+          // Found by the final whole-branch review of sub-project 6b: a
+          // graph: mapping's state is intentionally independent of the
+          // pre-existing present/partial/absent/manual status glyph
+          // (Global Constraint — see the block comment above), so a
+          // control can render a green ✅ header with a 'gap_detected'
+          // line buried underneath it in the observations. A ⚠️ prefix on
+          // a genuine gap keeps that visible to a reader who only scans
+          // headers, without touching the status computation itself.
+          // RE-CONFIRMED (sub-project 6c's own final review, F4): at the
+          // time this ⚠️ prefix was written, `graph:` mappings could only
+          // ever read 'unknown' end-to-end through the real CLI (a
+          // separate, then-undiscovered bug — see obligation-predicates.js
+          // and cmdCompliance/cmdAttest's own fix history), so this exact
+          // ✅-header-hiding-a-real-gap scenario was structurally
+          // unreachable. Sub-project 6c's CLI fixes make it genuinely
+          // reachable for the first time; the ruling above was written
+          // anticipating exactly this and needs no change — confirmed
+          // live via a real assessed HIPAA §164.312(e) gap
+          // (test/cli/attest-obligations.test.js's own gap_detected case).
+          const flag = mapping.state === 'gap_detected' ? '⚠️ ' : '';
+          obs.push(`${flag}(graph mapping) ${m} -> ${mapping.state}.`);
+        } else {
+          obs.push(`(graph mapping) ${m} -> evaluation failed, skipped.`);
+        }
       }
     }
 
@@ -547,6 +622,7 @@ export function evaluateFramework(scanRoot, fw, scan) {
       observations: obs,
       controlRefs: dedupedRefs,
       derivedProvenance: deriveComplianceProvenance(contributingFindings),
+      obligationMappings,
       ...(evidence ? { evidence, partiallyEvidenced: evidence.tier === 'weak' || evidence.tier === 'unmeasured' } : {}),
     });
   }

package/src/posture/compliance-frameworks/hipaa-security-rule.json

@@ -5,7 +5,7 @@
   "license": "US Federal regulation (public)",
   "url": "https://www.ecfr.gov/current/title-45/subtitle-A/subchapter-C/part-164",
   "scope": "SELECTIVE SUBSET. 8 of the Security Rule technical safeguards. Administrative and physical safeguards are outside what a code scanner can observe and are NOT represented here.",
-  "controlsDigest": "a99f9c4015ffbf72",
+  "controlsDigest": "7e94038dd9a64d3d",
   "controlCount": 8,
   "controls": [
     {
@@ -102,7 +102,8 @@
       ],
       "mapsTo": [
         "family:crypto-tls-no-verify",
-        "family:crypto-tls-version"
+        "family:crypto-tls-version",
+        "graph:transit-protection:PHI:external:transit:protected"
       ]
     }
   ]

package/src/posture/obligation-evidence-pack.js

@@ -0,0 +1,202 @@
+// obligation-evidence-pack.js — Milestone 4 sub-project 6c: signed,
+// versioned evidence packs for a Regulatory Obligation Overlay framework
+// evaluation (FR-504, PRD §10.10). Fourth sibling in the
+// evidence-bundle.js family — see that module's own header for the
+// shared-key rationale, and provenance-evidence-bundle.js for the most
+// directly mirrored precedent (same reused ensureKeyPair/keyPaths/
+// canonicalJson, own schema string, own build/sign/verify trio, own
+// top-level-key allowlist).
+//
+// WHAT THIS IS NOT
+// -----------------
+// Not a reuse of evidence-bundle.js's own bundle shape (that's a single
+// FINDING's evidence — proofTier/taintPath/etc; this artifact has no
+// finding at all). Not compliance-evidence-signing.js's ComplianceEvidence
+// manifest either — that signs the pre-existing family:/module:/rule:-
+// driven present/partial/absent/manual walkthrough status; this signs the
+// newer, additive graph: mapping type's own real ObligationMapping
+// records (evaluateGraphFlowPredicate/buildObligationMappingFromGraphPredicate,
+// sub-project 6b) — a distinct FR-504 artifact with its own field list
+// (scope, framework versions, facts, evidence index, unknown/manual
+// items, accepted exceptions, scan health, limitations, graph digest,
+// reproducibility metadata).
+//
+// THE EVIDENCE-INDEX DESIGN DECISION (see the scoping doc for the full
+// writeup)
+// -----------------------------------------------------------------
+// A real ObligationMapping record's own `evidence[]` is structurally
+// always empty today (graph-builder.js hardcodes `edge.evidenceRefs: []`
+// on every minted edge, disclosed in obligation-predicates.js's own
+// header). Rather than ship an evidence pack whose "evidence index" is
+// honestly, permanently empty, this module builds a REAL evidence index
+// from each fact's own `contributingGraphIds` (real flow ids
+// evaluateGraphFlowPredicate already returns) — resolving each flow id
+// back into a small, real summary (source/sink kind, dataElement
+// dataClasses, the edge's own transit/atRest/handling verdicts) by
+// joining against the graph's own entity arrays. `record.evidence` is
+// still carried through verbatim on each fact (honest, even though
+// empty) — the evidence index is an ADDITIONAL section built from data
+// that genuinely IS populated, not a replacement that hides the gap.
+
+import { ensureKeyPair, keyPaths, canonicalJson } from './evidence-bundle.js';
+import { EVIDENCE_GRADE_DISCLAIMER } from './evidence-grade-wording.js';
+import { computeGraphDigest } from '../lineage/export-json.js';
+import * as crypto from 'node:crypto';
+
+export const OBLIGATION_EVIDENCE_PACK_SCHEMA = 'agentic-security/obligation-evidence-pack@1';
+
+function _asArray(v) {
+  return Array.isArray(v) ? v : [];
+}
+
+/**
+ * Resolve one ObligationMapping fact's contributingGraphIds (real flow
+ * ids) into a small, real, human-and-machine-readable summary per flow —
+ * the evidence index's own per-fact contribution. Never throws: a flow id
+ * that no longer resolves against this graph (a stale pack re-evaluated
+ * against a newer graph, or a malformed fact) is simply skipped, not
+ * fabricated.
+ */
+function _resolveEvidenceForFact(fact, joins) {
+  const { flowsById, nodesById, edgesById, dataElementsById } = joins;
+  const flowIds = _asArray(fact?.contributingGraphIds);
+  const resolved = [];
+  for (const flowId of flowIds) {
+    const flow = flowsById.get(flowId);
+    if (!flow) continue;
+    const sourceNode = nodesById.get(flow.source);
+    const sinkNode = nodesById.get(flow.sink);
+    // Reads only edgeIds[0] — mirrors obligation-predicates.js's own
+    // disclosed, currently-unreachable limitation (graph-builder.js always
+    // mints single-edge flows; see that module's own header) rather than
+    // inventing a different convention for the same case here.
+    const edge = edgesById.get(_asArray(flow.edgeIds)[0]);
+    const dataClasses = _asArray(flow.dataElementIds)
+      .map((id) => dataElementsById.get(id))
+      .filter(Boolean)
+      .flatMap((d) => _asArray(d.dataClasses));
+    resolved.push({
+      flowId,
+      source: sourceNode ? { kind: sourceNode.kind ?? null, subtype: sourceNode.subtype ?? null } : null,
+      sink: sinkNode ? { kind: sinkNode.kind ?? null, subtype: sinkNode.subtype ?? null } : null,
+      dataClasses: [...new Set(dataClasses)],
+      transitVerdict: edge?.protection?.transit?.verdict ?? null,
+      atRestVerdict: edge?.protection?.atRest?.verdict ?? null,
+      handlingVerdict: edge?.protection?.handling?.verdict ?? null,
+    });
+  }
+  return resolved;
+}
+
+function _buildJoins(graph) {
+  return {
+    flowsById: new Map(_asArray(graph?.flows).filter(Boolean).map((f) => [f.id, f])),
+    nodesById: new Map(_asArray(graph?.nodes).filter(Boolean).map((n) => [n.id, n])),
+    edgesById: new Map(_asArray(graph?.edges).filter(Boolean).map((e) => [e.id, e])),
+    dataElementsById: new Map(_asArray(graph?.dataElements).filter(Boolean).map((d) => [d.id, d])),
+  };
+}
+
+/**
+ * Build an unsigned evidence pack from a framework evaluation. Never
+ * throws: every field degrades honestly on missing input rather than
+ * fabricating a value — a null/absent graph yields empty facts/
+ * evidenceIndex and a null graphDigest/scope, never a guess.
+ *
+ * @param {object} args
+ * @param {object|null} args.graph - the scan's DataFlowGraph v1 document (scan.lineageGraph), or null
+ * @param {object} args.framework - the loaded framework object (auditor-walkthrough.js#loadFramework's return)
+ * @param {Array}  args.evaluation - auditor-walkthrough.js#evaluateFramework's return (per-control entries, each carrying .obligationMappings)
+ * @param {object|null} [args.scanHealth] - scan.scanHealth, passed through verbatim; null if not supplied, never fabricated
+ * @param {string|null} [args.engineVersion]
+ * @param {string|null} [args.rulesetVersion]
+ * @param {string|null} [args.bundleSha]
+ * @param {string} [args.generatedAt] - defaults to new Date().toISOString()
+ */
+export function buildObligationEvidencePack({
+  graph, framework, evaluation, scanHealth, engineVersion, rulesetVersion, bundleSha, generatedAt,
+} = {}) {
+  const facts = _asArray(evaluation).flatMap((e) => _asArray(e?.obligationMappings));
+  const joins = _buildJoins(graph);
+  const evidenceIndex = facts.map((fact) => ({
+    obligationId: fact?.id ?? null,
+    requirementId: fact?.requirementId ?? null,
+    evidence: _resolveEvidenceForFact(fact, joins),
+  }));
+
+  return {
+    schema: OBLIGATION_EVIDENCE_PACK_SCHEMA,
+    framework: {
+      id: framework?.id ?? null,
+      name: framework?.name ?? null,
+      version: framework?.controlsDigest ?? null,
+      publisher: framework?.publisher ?? null,
+      url: framework?.url ?? null,
+    },
+    scope: graph?.scope ?? null,
+    facts,
+    evidenceIndex,
+    unknownItems: facts.filter((f) => f?.state === 'unknown'),
+    manualItems: facts.filter((f) => f?.state === 'manual_required'),
+    acceptedExceptions: facts.filter((f) => f?.state === 'accepted_exception'),
+    scanHealth: scanHealth ?? null,
+    limitations: _asArray(graph?.limitations),
+    graphDigest: graph ? computeGraphDigest(graph) : null,
+    reproducibility: {
+      graphId: graph?.graphId ?? null,
+      graphDigest: graph ? computeGraphDigest(graph) : null,
+      engineVersion: engineVersion ?? null,
+      rulesetVersion: rulesetVersion ?? null,
+      bundleSha: bundleSha ?? null,
+      generatedAt: generatedAt ?? new Date().toISOString(),
+    },
+    disclaimer: EVIDENCE_GRADE_DISCLAIMER,
+  };
+}
+
+/** Sign a pack. Returns a new object; the input is not mutated. */
+export function signObligationEvidencePack(pack, privateKeyPem) {
+  const sig = crypto.sign(null, Buffer.from(canonicalJson(pack), 'utf8'), privateKeyPem);
+  return {
+    ...pack,
+    signature: { algorithm: 'ed25519', canonicalisation: OBLIGATION_EVIDENCE_PACK_SCHEMA, value: sig.toString('base64') },
+  };
+}
+
+const OBLIGATION_EVIDENCE_PACK_TOP_LEVEL_KEYS = new Set([
+  'schema', 'framework', 'scope', 'facts', 'evidenceIndex', 'unknownItems',
+  'manualItems', 'acceptedExceptions', 'scanHealth', 'limitations',
+  'graphDigest', 'reproducibility', 'disclaimer', 'signature',
+]);
+
+/**
+ * Verify with a PUBLIC key only. Rejects any top-level key outside the
+ * allowlist BEFORE checking the signature — same EA-03 discipline every
+ * sibling in this family carries: a signature only covers the bytes it
+ * was computed over, so a key stapled on after signing would otherwise
+ * verify as authentic.
+ */
+export function verifyObligationEvidencePack(pack, publicKeyPem) {
+  if (!pack || typeof pack !== 'object') return { ok: false, reason: 'pack is not an object' };
+  if (pack.schema !== OBLIGATION_EVIDENCE_PACK_SCHEMA) return { ok: false, reason: `unrecognised schema: ${pack.schema}` };
+  const unknownKeys = Object.keys(pack).filter((k) => !OBLIGATION_EVIDENCE_PACK_TOP_LEVEL_KEYS.has(k));
+  if (unknownKeys.length) {
+    return { ok: false, reason: `unrecognised top-level key(s) not covered by the signature: ${unknownKeys.join(', ')}` };
+  }
+  const sig = pack.signature;
+  if (!sig?.value) return { ok: false, reason: 'pack is unsigned' };
+  if (sig.algorithm !== 'ed25519') return { ok: false, reason: `unsupported algorithm: ${sig.algorithm}` };
+  if (!publicKeyPem) return { ok: false, reason: 'no public key supplied' };
+  const { signature, ...unsigned } = pack;
+  let ok = false;
+  try {
+    ok = crypto.verify(null, Buffer.from(canonicalJson(unsigned), 'utf8'), publicKeyPem, Buffer.from(sig.value, 'base64'));
+  } catch (e) {
+    return { ok: false, reason: `verification error: ${e.message}` };
+  }
+  return ok
+    ? { ok: true, reason: null }
+    : { ok: false, reason: 'signature does not match the pack contents — it was modified after signing' };
+}
+
+export { ensureKeyPair, keyPaths };