Evidence coverage metric — the demo number that reframes governance from 'less manual work' to '~100% bound'

2026-07-21

securitygovernancedecision-lineage

LOCKSTEP TRACEABILITY MATRIX --- api_endpoints: ["GET /v1/governance/compliance/coverage"] sdk_methods_updated: ["regenerated via pnpm gen:contract (generated SDK trees)"] mcp_tools_updated: ["none (REST-only capability)"] ---

What We Built

GET /v1/governance/compliance/coverage — Phase 2 / step 2a of the governance roadmap. It aggregates the tenant's recorded decision_lineage rows into a single headline: the fraction of recorded decisions that are cryptographically bound to the audit chain (a non-null audit_event_hash means a committed completion_audit row commits over the row's lineage_digest). Optional since bounds the window; the response also splits captured vs aggregated coverage.

The metric math lives in a pure, exhaustively unit-tested summarizeCoverage function; the store method is a thin GROUP BY (bound, aggregated). Empty tenant ⇒ ratio 1 (vacuously complete), never a divide-by-zero.

Why It Matters

This is the product demo. Credo AI's headline value prop is "reduce manual governance work by ~60%." BR answers with a live number showing that near-100% of recorded production decisions already carry bound, verifiable evidence — automatically, because BR sits on the request path. You cannot produce this ratio from a batch documentation/registry posture.

How It Works

GET /v1/governance/compliance/coverage?since=1721520000000
→ { total, binding: { bound, unbound, boundRatio }, byCoverage: { captured, aggregated }, window }

Binding is derivable from decision_lineage alone, so no cross-table join is needed for the headline. Absent-row coverage classes (sampled_out, dropped) live on the completion_audit side and are a follow-up for a full traffic-level denominator; the current denominator is _recorded_ rows, stated precisely in the response docs so it is never over-claimed.

Competitive Edge

The coverage ratio converts an internal observability number into the primary competitive claim — continuous, self-verifying evidence vs. a GRC tool whose value is merely reducing manual effort.

Lockstep Checklist

[x] API Routes: defineCapability in src/api/capabilities/system/governance.ts, registered in _registry.ts (both blocks).
[x] TS/Py SDK: regenerated via pnpm gen:contract (generated trees are gitignored build artifacts); docs/openapi.yaml + llms-full.txt + routes.json regenerated and committed.
[x] MCP Schemas: none (REST-only; add br_get_coverage if it becomes agent-facing).
[x] Behavior: governance.behavior.json entry (SOC2-CC7, OCSF api_activity).
[ ] Master Record: to update alongside the Phase 2 Governance Artifact (2b).

Verification & caveats

Verified: summarizeCoverage unit tests (bound ratio, empty=1, 100%/0%,

non-finite sanitization); _registry completeness gate; pnpm check + pnpm build green; full type check.

NOT verified here: the SQL aggregate itself — no live Postgres in this

environment (DATABASE_URL unset for tests). The GROUP BY is a thin, visually-verified query following the existing withTenant RLS pattern, but it needs a staging run against real decision_lineage data before GA.