API Reference

This page is generated by reading ahl-core’s src/lib.rs and src/receipt.rs directly, not projected from the specification. ahl-core is a private, pre-release repository tracking Core Specification v0.3-draft and Evidence Receipt format 1-draft r3; its public surface can still change before publication. Every signature below is copied from source — none is guessed or aspirational.

Identifiers and canonical form

pub fn jcs(value: &Value) -> Vec<u8>;
pub fn sha256_hex(bytes: &[u8]) -> String;
pub fn statement_id(envelope: &Value) -> AhlResult<String>;  // SHA-256(JCS(payload))
pub fn entry_id(envelope: &Value) -> String;                 // SHA-256(JCS(envelope))

Canonicalization and Merkle node/leaf hashing are delegated to atl-core (pinned by revision, not reimplemented) — the crate’s stated anti-drift guarantee against its sibling implementations (Data Structures §8).

Commitments

pub fn commit_plain(dataset: &str, canonical: &[u8]) -> String;
pub fn commit_keyed(key: &[u8], dataset: &str, canonical: &[u8]) -> AhlResult<String>;

Both apply the dsid || 0x1F || canonical_bytes domain-separation prefix (Data Structures §7). commit_keyed returns AhlError::BadLength only when key cannot be used as an HMAC key; the crate does not otherwise constrain dataset-key length.

Envelopes and signatures

pub fn envelope(payload: Value, key: &TestKey) -> Value;
pub fn verify_envelope<F>(env: &Value, resolve: F) -> AhlResult<bool>
where F: Fn(&str) -> Option<String>;
pub fn verify_signature(key: &VerifyingKey, msg: &[u8], signature: &str) -> AhlResult<bool>;
pub fn decode_pubkey(pubkey: &str) -> AhlResult<VerifyingKey>;

TestKey (from_seed_hex, key_id, pubkey, sign, key_object) builds Ed25519 keys from committed 32-byte seeds. The crate’s own documentation is explicit about what this is for: “Nothing in this crate is suitable for production key handling.” Every key in test_data/keys/ is a published constant. TestKey exists to generate the deterministic test-vector corpus, not to manage producer keys in a deployment.

Checkpoints

pub fn checkpoint(log_id: &str, tree_size: u64, root_hash: &str, checkpoint_time: &str, key: &TestKey) -> Value;
pub fn checkpoint_signing_bytes(cp: &Value) -> AhlResult<Vec<u8>>;
pub fn cosignature_bytes(signed_checkpoint: &Value, witness_id: &str) -> Vec<u8>;

Merkle trees

pub fn leaf_hash(bytes: &[u8]) -> Hash;
pub fn tree_root(leaves: &[Vec<u8>]) -> Hash;
pub fn inclusion_proof(leaves: &[Vec<u8>], index: usize) -> AhlResult<InclusionProof>;
pub fn verify_inclusion_proof(leaf: &[u8], proof: &InclusionProof, root: &Hash) -> AhlResult<bool>;
pub fn record_sorted(leaves: Vec<Value>) -> AhlResult<Vec<Value>>;

Hash and InclusionProof are re-exported from atl_core::core::merkle. Proof generation and verification are atl-core calls, never local reimplementations.

Closure (ahl_core::closure)

pub type RecordRef = (String, String);
pub type TreeMaterial = BTreeMap<String, Vec<Value>>;
 
pub fn edges(envelopes: &[Value], trees: &TreeMaterial, through_size: usize) -> AhlResult<Vec<Edge>>;
pub fn trigger_seeds(envelopes: &[Value], trigger_index: usize) -> AhlResult<BTreeSet<RecordRef>>;
pub fn affected_set(envelopes: &[Value], trees: &TreeMaterial, trigger_index: usize, through_size: usize) -> AhlResult<Closure>;

Closure carries seeds and affected as BTreeSet<RecordRef> — the seeds themselves are never members of the affected set (Protocol §6.1: the affected set is the set of derived records requiring disposition). A retraction seeds exactly {(dataset, record)}; a correction additionally seeds every earlier correction’s superseded replacement, never its own.

Bitemporal scope (ahl_core::bitemporal)

pub enum ValidTime { /* ... */ }
impl ValidTime {
    pub fn from_payload(payload: &Value) -> AhlResult<Self>;
    pub fn intersects_ray(&self, effective_from: OffsetDateTime) -> bool;
}
 
pub struct Scope { pub effective_from: OffsetDateTime, pub retroactive: bool }
impl Scope {
    pub fn from_payload(payload: &Value) -> AhlResult<Self>;
    pub fn covers(&self, valid_time: ValidTime) -> bool;
}

Evidence Receipt verification (ahl_core::receipt)

pub fn verify_receipt(receipt: &Value, policy: &TrustPolicy) -> Result<Verdict, ReceiptError>;

TrustPolicy is the verifier’s locally configured trust anchor (Data Structures §11 design rule 1): genesis anchor, trusted witness key ids, authorized dataset keys, locally possessed adaptor profiles, and resource Limits. Nothing in it is taken from the receipt — a receipt carries its own genesis anchor precisely so policy can reject a mismatch rather than trust it.

Verdict reports claim_type, subject_entry_index, subject_statement_id, the verified Assurance block, and a boundary string rendered only from claim.type + assurance — never from the receipt’s informative note field, and never stronger than what verification established.

ReceiptError is #[non_exhaustive], with one variant per rule that can reject a receipt — among them GenesisAnchorMismatch, KeyNotBound, CompetingRangeInsufficient, CheckpointNotBound, RecordSubjectMismatch, GovernanceRangeNotComplete, ClosureMismatch, and TreeMaterialInvalid. Each names the specific rule that fired rather than reporting a generic failure — a test can assert which rule rejected a deliberately malformed receipt.

Error types

pub enum AhlError { /* ... */ }
pub type AhlResult<T> = Result<T, AhlError>;

A note on this page’s history

An earlier revision of this page described a fictional API surface — an Envelope struct, a Statement enum, ManifestState::resolve_at, a ReceiptVerifier struct with a trust_policy field, and error variants (CommitmentMismatch, TriggerNotEffective) that do not exist anywhere in the crate. None of that ever shipped; it was never checked against source before publication. This revision was generated by reading ahl-core’s src/lib.rs and src/receipt.rs directly. If the crate’s public surface changes before publication, this page can drift again — re-check it against source before trusting it.