Skip to main content

Crate g8_obligations

Crate g8_obligations 

Source
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 as status = Unknown with evidence.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, against subject; repo-wired obligations are skipped entirely (excluded from the returned Vec, 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.json deserialization — 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§

AttestationRecord
AttestationSidecar
ReceiptSubject
A parsed, content-hashed action receipt — the subject receipt_query checks evaluate against. Built exactly once per g8 check --receipt invocation via load_receipt_subject and threaded through run_obligations, never re-parsed per obligation.

Enums§

AttestationClaim
AttestationError
ReceiptSubjectError
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.wiring value 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 sha256 on its Err), 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).