Skip to content
Codevidence Docs

Core Concepts

Why bytecode, not source

Enterprises won’t grant a third-party SaaS access to their codebase — and they shouldn’t have to, just to prove they’re compliant. Codevidence is architected around that constraint from day one.

Declared: a read-only bytecode scan

  1. Your code — stays in your version control. Never leaves your environment, never read by Codevidence.
  2. Compiled bytecode — produced by your normal build. Nothing Codevidence-specific runs to produce it.
  3. Codevidence extractor — parses bytecode structure to pull @ComplianceControl metadata. Never loads or runs a class.
  4. Evidence record — control id, artifact hash, commit, build, timestamp, written as JSON in your build output.
  5. Optional publish — you can POST each record to an ingestion endpoint you configure. There’s no Codevidence-hosted destination yet; by default records stay local.

@ComplianceControl has CLASS retention specifically so it survives into the bytecode for this scan, without adding a runtime dependency to your application.

Verified: your tests, not your code

Verified works differently. @VerifiesControl has RUNTIME retention and is read by reflection inside a JUnit 5 extension while your own test runs. Codevidence records the outcome of the typed assertion your test called. Your production code still never runs under Codevidence — only your tests, in your pipeline, the same as any other test run.

What this buys you

  • No source-code access request to get through security review.
  • No risk of a scanner executing code it doesn’t understand — Declared is a static pass over compiled classes; Verified is your existing test suite.
  • An evidence chain (hash → commit → build) an auditor can verify independently, instead of trusting a vendor’s word.
  • Provenance that’s explicit about its own gaps — commit: null, commitSource: "unavailable" when it genuinely can’t be resolved.

What this doesn’t cover

Reading bytecode tells you a control was declared and in which build. Confirming it behaves correctly is what Verified does. Confirming it ran in production is Observed, still in design.