Core Concepts
This page explains the fundamental building blocks of Quoderat's evidence model: identity, traceability, and the mechanics of the tamper-evident seal.
The Core Idea
Quoderat produces a receipt for engineering work. The receipt records:
- • What was requested (the intent)
- • What steps ran and what they reported
- • What artifacts were produced (content-identified by hash)
- • What summaries were derived (and which artifacts they came from)
This is a chain-of-custody record, not a correctness guarantee. The receipt tells you what happened; it does not claim the result is correct or secure.
The Evidence Envelope
The Evidence Envelope is the authoritative JSON document that contains the full audit trail for a single run.
Evidence Envelope
The machine-readable JSON contract. Contains hashes, traceability links, and the integrity chain. This is what you validate offline.
Public Pack
A filtered export of the Envelope intended for sharing. Fields not on the public allowlist are stripped. The internal Envelope remains the authoritative record.
If the Envelope's integrity validates, the Public Pack can be treated as a faithful rendering of the allowed subset of evidence.
Identity: Pinning the Subject
Every run must be anchored to a known starting point. Without identity, the receipt has no meaning.
Anchor fields
- •
repo_url— the repository identity - •
commit_sha— an immutable reference to the starting state
Content identity for artifacts: Each artifact is identified by its sha256 hash, not its storage location.
- •
artifacts[].sha256— the unique fingerprint of the bytes - •
artifacts[].content_uri— formatted asurn:sha256:<hash> - •
location_hints[]— optional pointers (S3, GitLab, etc.); may expire, but the content identity remains stable
Traceability: Show the Receipts
Any derived fact (an Observation) must cite the raw artifacts it was parsed from. This prevents unfounded claims.
The mechanic
observations[].basis_artifact_ids[] — a required list of artifact IDs that the observation was derived from.
Example: a test_summary observation must point to the test report artifact.
Hard consumer rule: If an observation has no basis_artifact_ids, treat it as informational only—not as verified evidence.
Tamper-evidence: Detecting Edits
We do not prevent edits; we make them detectable. After finalization, any modification to the covered payloads will cause a hash mismatch.
The mechanic
- •
integrity.canonicalization=rfc8785-jcs(deterministic JSON format) - •
integrity.hash_chain— a sequential chain covering steps, artifacts, and observations
Offline validation at a glance
- 1.Canonicalize JSON using RFC 8785 JCS
- 2.Recompute SHA-256 for covered payloads
- 3.Compare against
integrity.hash_chain(head)
Public vs. Internal Views (Deny-by-default)
A single Evidence Envelope supports both a full internal audit and a filtered public export.
Internal Envelope
Full audit trail for operators and auditors. Contains all fields and artifacts.
Public Pack
Filtered export for external sharing. Only fields on public_allowlist_fields are included.
Public Pack is primarily field stripping by allowlist. Masking (pattern-based redaction) is best-effort and logged in redactions[].
Warning: A Public Pack is only as safe as your public_allowlist_fields configuration. Quoderat guarantees the filtering mechanism, not the wisdom of chosen allowlist entries.
Common Pitfalls
Confusing “recorded” with “verified”
Quoderat records what tools reported. It does not verify that the tools are correct, that tests are comprehensive, or that the code is bug-free.
Assuming redaction = no secrets
redactions[] logs what was masked by the configured rules. It does not guarantee that no secrets exist elsewhere in the artifacts.
Treating events as receipts
Runtime events (SSE) are transient signals for monitoring. They have no ordering or delivery guarantees. Always fetch the finalized Envelope for auditing.
Claiming “tamper-proof”
The correct term is tamper-evident. Edits are detectable via hash mismatch, not prevented by the system.
Glossary
Evidence Envelope
The authoritative JSON document containing the full audit trail for a run.
Public Pack
A filtered export of the Envelope intended for external sharing. Deny-by-default.
Artifact
A raw output (diff, log, report) identified by its sha256 hash.
Observation
A derived fact (e.g., test summary) that must cite its basis_artifact_ids.
Integrity chain
A hash chain (RFC 8785 JCS + SHA-256) that makes post-hoc edits detectable.
Redaction
A logged record of pattern-based masking applied to outputs. Best-effort, not a guarantee.
Next steps
- Quickstart — get a working run in under 10 minutes
- First Job — full walkthrough from intent to sealed envelope
- Policies — masking rules and public/internal visibility
- Events (SSE) — runtime signals vs authoritative record
- API — programmatic consumption and validation