Your First Job
This guide walks you through a complete Quoderat run: issuing an intent, watching execution, and receiving a sealed Evidence Envelope.
What you will have at the end
- One evidence_id — the immutable UUID recorded in the envelope that identifies this receipt
- A finalized Evidence Envelope JSON — the authoritative record of what happened and what was captured
- Internal vs Public Pack — the full internal audit trail vs a filtered, allowlist-based export for external stakeholders
The walkthrough
1Identify the Subject (state anchor)
Record repo identity and a commit_sha as the immutable anchor.
In the envelope: subject.repo (name/url), subject.git.commit_sha, and any reported branch/dirty status if present.
2Issue the Intent (the request)
Intent is the stated goal, not proof.
In the envelope: the recorded intent/trigger metadata (as implemented), plus generated_at.
3Execution (typed steps)
Work runs as discrete, typed steps (lint/test/build/etc.).
In the envelope: execution.steps[*].kind, status, exit_code, and step-level artifact references when present.
4Capture Artifacts (raw bytes)
Logs and reports are stored as bytes and identified by hash.
In the envelope: artifacts[*].content_uri (urn:sha256:...), sha256, kind, and location_hints as best-effort pointers.
5Record Observations (derived claims)
Observations are summaries derived from artifacts.
Rule: every observation must cite basis_artifact_ids; without basis links, treat it as informational/non-verifiable.
6Finalization (the seal)
Canonicalize JSON using RFC 8785 (JCS) and generate a SHA-256 hash chain.
In the envelope: integrity.canonicalization = "rfc8785-jcs" and a non-empty integrity.hash_chain.
Key point: only after finalization is the envelope the authoritative receipt.
Two timelines — Events vs Envelope
| Timeline | Nature | Purpose |
|---|---|---|
| Events (SSE) | Ephemeral runtime signals | Live monitoring and UI progress |
| Evidence Envelope (JSON) | Finalized, portable receipt | Auditing, storage, offline verification |
Rule of thumb: Use events to watch the work; use the envelope to trust the work. Never treat a UI “success” signal as proof.
The Trust Moment — Offline verification
A reviewer can validate without trusting the server:
Integrity
Re-canonicalize (RFC 8785 JCS) and recompute/verify the integrity.hash_chain (SHA-256).
Artifact identity
Download an artifact via location_hints and re-hash bytes; must match sha256/content_uri.
Traceability
Confirm observations cite basis_artifact_ids that exist and point to the right raw reports.
Reviewer checklist (scan order)
- 1
subject— repo + commit_sha - 2
integrity— canonicalization + hash_chain present - 3
execution.steps— exit_code/status for critical steps - 4
artifacts— expected logs/reports present with hashes - 5
observations— basis links present and plausible - 6
redactions[]/ public pack filtering — what was masked/stripped and why
Common misunderstandings
“CI passed” ≠ “no regressions”
“Redactions logged” ≠ “no secrets elsewhere”
Public pack allowlists are your responsibility; Quoderat records filtering, not safety of choices.
Next steps
- Concepts — identity, traceability, canonicalization, integrity
- Policies — masking rules and public/internal visibility
- Events (SSE) — runtime signals vs authoritative record
- API — programmatic consumption and validation