Core Concepts
The evidence model: Declared, Verified, Observed
Not all compliance evidence is equally strong. Codevidence is explicit about the difference instead of collapsing it into one undifferentiated “evidence” label — and today it takes you from what a developer declared all the way to what a test confirms.
A cryptographic artifact hash tells you evidence came from this exact build. Whether the control actually behaves as claimed is a separate question — the one Verified answers.
| Tier | Status | What it proves | Mechanism |
|---|---|---|---|
declared |
Available now | A developer marked this code as implementing a specific control, in this exact build. | A build-time bytecode scan reads the @ComplianceControl annotation off compiled classes. |
verified |
Available now | A JUnit test exercised the code and a typed assertion confirmed it behaves as the control claims (or recorded that it didn't). | A JUnit 5 extension records each ComplianceAssertions call in a @VerifiesControl test; the plugin turns those into records after the test phase. |
observed |
Coming next | The control executed in a real production deployment, not just in a test. | Runtime instrumentation — see the roadmap page. |
Declared
Developers annotate compliance-relevant code with
@ComplianceControl, a
lightweight, typed annotation. A build-time step extracts it directly
from compiled bytecode — your source code never leaves your environment.
Verified
A @VerifiesControl JUnit test
calls a typed assertion from
ComplianceAssertions, and
Codevidence records whether it passed or failed — linked to the Declared
control it verifies. This closes the gap between what a developer
declared and what the code actually does.
Observed
Runtime instrumentation would confirm the control executed in production, tied to a specific deployment and commit — the strongest possible evidence tier, generated from real behavior rather than developer intent or test coverage. It’s the one tier still in design; see the roadmap.
Why the distinction matters
An auditor's first question about any automated evidence is "why should I trust a developer's self-reported annotation?" Answering that honestly — an artifact hash proves provenance, a test proves behavior, and they're different things — is more credible than implying a single annotation is proof of compliance. That's why Codevidence labels evidence strength explicitly instead of collapsing everything into one undifferentiated "evidence" claim.