Expand description
g8-obligations — typed obligation-checker backends for g8 check.
Executes the 27-obligation self-audit (specs/obligations-v0.1.json)
against g8’s own repository. Every obligation resolves to a member of a
closed Rust enum of checker backends with structured, typed arguments
— see backend::CheckerBackend. There is no shell_command: String
field anywhere in this crate (specs/obligation-checker-contract.md §0).
§Deterministic zone
No LLM calls, no network, no unseeded randomness. Subprocess calls to
cargo/ast-grep/rg/current_exe() are the same class of dependency
g8-extractor already has on ast-grep.
§G8CheckContract design note (contract §8)
§8 describes this backend’s implementation in terms of
g8_core::contract::CheckPayload/CheckError — types that do not exist
yet. Their relocation from crates/g8/src/render/json.rs into
g8-core is explicitly T5’s job (“a small, precisely-scoped refactor for
T5… not something I am doing here” — contract §8 point 1), and
g8-core/g8 are both outside this crate’s writable (and, for
g8, even dependency-able) scope. Since T3 runs before T5 in the
plan’s dependency order, those types cannot exist yet when this code is
written.
This crate’s [exec::check_contract] therefore validates against a
serde_json::Value shape seam instead of the not-yet-relocated concrete
types: it builds the check-contract envelope directly (mirroring exactly
what render_check/render_check_enforcement_disabled in
crates/g8/src/render/json.rs produce today, and what
CLAUDE.md’s locked “Output contract” section documents), using the
REAL g8_store::{PairingError, PairingErrorReason} types (already
Serialize, already living in the allowed g8-store dependency — no
relocation needed for those) for the errors[] array. This keeps the
backend’s trust tier honestly Verified (it runs g8-store’s real
pairing_check against a real in-memory RusqliteStore, not a hollow
shape assertion) while depending on nothing that doesn’t exist today.
Once T5 relocates CheckPayload/CheckError, this seam continues to
work unchanged — it was never coupled to their Rust type identity, only
to the JSON shape they serialize to.
§Receipt mode (contract addendum, o-g8-receipts-20260721)
Signal.wiring == "action_receipt" declares an obligation’s subject is a
parsed action receipt, not the repository. run_obligations’s
receipt parameter selects the choke point:
receipt = None(repo mode): receipt-wired obligations are not executed — they surface asstatus = Unknownwithevidence.detail.scope = "action_receipt"and are exempt from gate classification (their choke point is elsewhere; a green repo stays green). Repo-wired obligations run exactly as before this addendum.receipt = Some(subject)(receipt mode): only receipt-wired obligations run, againstsubject; repo-wired obligations are skipped entirely (excluded from the returnedVec, not represented).
Subject binding is validated either way: a receipt-wired obligation may
only contain receipt_query checks, and receipt_query may not appear
in a repo-wired obligation. A violation is ObligationStatus::Error
(loud, gates) rather than a silent skip.
Re-exports§
pub use artifact::load_artifact;pub use artifact::Obligation;pub use artifact::ObligationArtifact;pub use artifact::ObligationChecker;pub use artifact::ObligationsError;pub use artifact::Signal;pub use backend::*;pub use result::*;
Modules§
- artifact
specs/obligations-v0.1.jsondeserialization — contract §6.- backend
- Checker backend schema — the closed-by-default enum (11 variants as of the o-g8-receipts-20260721 contract addendum) + structured arguments.
- hashing
- Shared SHA-256 helpers for ratification locks and evidence attestations.
- result
- Status / trust semantics + multi-check aggregation — contract §3.
Structs§
- Attestation
Record - Attestation
Sidecar - Receipt
Subject - A parsed, content-hashed action receipt — the subject
receipt_querychecks evaluate against. Built exactly once perg8 check --receiptinvocation viaload_receipt_subjectand threaded throughrun_obligations, never re-parsed per obligation.
Enums§
- Attestation
Claim - Attestation
Error - Receipt
Subject Error - Failure to load a receipt file into a
ReceiptSubject. Carries the SHA-256 when one could still be computed (contract: “even a malformed receipt’s hash is meaningful evidence of exactly what bad input was rejected”) — only a wholly unreadable file has none.
Constants§
- ACTION_
RECEIPT_ WIRING - The
signal.wiringvalue that binds an obligation to the receipt choke point (contract addendum, o-g8-receipts-20260721 §1). Every other (or absent/default) wiring value is repo-wired. - ATTESTATIONS_
RELATIVE_ PATH - STALE_
ATTESTATION_ CLASSIFICATION
Functions§
- attestation_
sidecar_ path - load_
attestation_ sidecar - Load the sidecar once per obligation run. Absence is a normal
None. - load_
receipt_ subject - Parse+hash one receipt file. The file is hashed first (so a merely
malformed-JSON receipt — the file exists and is readable — still yields a
real
sha256on itsErr), then parsed as JSON. - run_
obligations - The one entry point. Never panics; a single backend crashing surfaces as
that one obligation’s
status = Error, not a propagated panic — every backend invocation is isolated (caught, not just?-propagated).