Skip to main content

Crate evidencebook

Crate evidencebook 

Source
Expand description

evidencebook – evidence semantics over an embedded commitment history.

This crate implements the store-level semantics of the Evidence Layer Internet-Draft, draft-mih-agent-evidence-layer-00 (“the I-D”; source: https://github.com/action-state-group/agent-action-capsule/blob/main/spec/draft-mih-agent-evidence-layer-00.md). Each public item names the I-D section it implements. The I-D is implementation-independent: a store conforms by meeting its requirements, not by using this crate.

Two layers, kept distinct:

evidencebook   records · epistemic types · links · retention · disclosure
               index classes · request answers · reconcile/close
  embeds
cll            append order · MMR · checkpoint · inclusion · consistency

The Checkpointed Local Log (cll, published as checkpointed-local-log) is the reference commitment substrate. It is embedded, never exposed: no public item of this crate takes or returns a cll type (tests/public_api.rs enforces this), except the CLL backend a shelf’s host log hands its host, whose own log layer runs on it. Callers ask the book’s substrate for checkpoints and inclusion evidence in this crate’s own types.

Answers, reconcile inputs and index rebuilds read a book through the read-only store traits, which the substrate implements. A caller whose own checkpointer owns the log files implements them over its own index instead, and this crate never opens those files.

The crate carries no deployment vocabulary. Record kinds, correlation key names and content comparators belong to the calling profile and are supplied by it.

I-D sectionModule
Record header (anchor record); Epistemic Type; Typed Linksrecord; sealing a record as Go’s book does, seal
Record/Payload Separation; Retention Statesretention
Disclosure Recordsdisclosure
Index Classesindex
The Commitment-Substrate Interfacesubstrate; the read-only store an answer reads, store
Answering a Request; Three Kinds of “No”request
Answering a Request: the artifact responseanswer; the requests a book was asked, received; definition-digest derivations, derivation; the served-summary derivation, served_summary
Answering a Request: the responder (gate, decision, the record of having answered) and the requester (the record of having asked, recorded absence)respond, ask
Reconcile and Closereconcile
Privacy Considerations: What a Checkpoint Revealspadding
(record identity: JCS and JSON-DIGEST)canonical

One module is not Evidence Layer semantics but an opt-in reference profile, built only with the cargo feature deal: deal, the x-deal-v0 deal record profile (its names, identifier fingerprints, record checks and the members of the Capsules a deal’s steps and reports are sealed with), byte for byte with the Go package dealprofile. Nothing else in the crate depends on it, and without the feature none of its dependencies is built.

The cargo feature shelf adds shelf (evidencebook#254): one subject key’s books in one SQLite file, the same file the Go and Python shelves write, with books that write, host logs, the writer lock and the heartbeat cadence. Without the feature none of its dependencies is built.

Modules§

answer
Building the artifact response to an evidence request over the book’s Checkpointed Local Log, in the interop profile’s form (evidence-interop/0, agent-action-capsule spec/interop-profile-v0.md §6.2 and §6.2.1, and evidence-interop/1, whose envelope is the same and names the profile the request asked for).
ask
The requester’s side of a request: the record of having asked, sealed before the request is sent, and the record that nothing came back in the waiting window.
canonical
Canonicalization and JSON-DIGEST (draft-mih-scitt-agent-action-capsule-04 §2, §5.1).
deal
The x-deal-v0 deal record profile: an opt-in reference profile, built only with the crate’s deal feature.
derivation
Definition-digest derivations: the derivations a responder serves by the digest of their definition document (request draft -00 §3.3).
disclosure
Disclosure records.
index
The three index classes.
padding
Padding records and store nonces.
received
“Asked of you”: a book owner’s log of the requests others made of it, and what it answered. The responder’s half of the double entry.
reconcile
Reconcile two independently held accounts, and read a Close’s status.
record
The record header, its epistemic type, and typed links.
request
Request subjects, the three outcomes of a request, and the three kinds of “no”.
respond
Answering one request as a book: the gate, the decision, the signed reply and the evidence_request_answered record, as Go’s Respond (interop_respond.go).
retention
Retention states and the lifecycle records that change them.
row_status
The status of one term row of a deal, computed from the two sides’ statements on it and the dates (evidencebook#461, acceptance 6). No record holds a status and nobody declares it: whoever holds the inputs computes it, as of any time, and gets the same answer. This is the Go package rowstatus, result for result; testdata/row-status/vectors.json holds the shared vectors, and the Go package comment states the rule.
seal
Sealing a record: the header a book commits, the record capsule that commits it, and that capsule’s Producer Envelope.
served_summary
The served summary (served_summary/1): what a book’s owner served, per group, over its checkpointed range. Never who asked.
shelf
The shelf: one subject key’s books in one SQLite file (evidencebook#254 §2), built with the cargo feature shelf.
shelf_facts
The entry documents of a shelf log of book facts (evidencebook#461, docs/design/461-shelf-facts.md §2), byte for byte with the Go package’s shelf_facts.go: every entry after the format-switch marker is the SHA-256 of one document’s RFC 8785 bytes; a fact commits to its link and status values as hex(SHA-256(salt ‖ JCS(value))), each under its own 32-byte salt, and an opening {salt, value} shows one value. testdata/shelf/facts/vectors.json holds the shared vectors.
standard_history
The standard_history/1 card (agent-action-capsule spec/standard-history-v0.md, cited as SH): a card, as of one anchor, that counts the holder’s deals in the window its policy sets. It is recipient-free: every requester answered gets the same bytes.
staple
A History card stapled to the holder’s own message (evidencebook#275): the check a reader runs on a staple it received, as the Go CheckStaple and the Python check_staple do, and a history_card/1 or standard_history/1 staple built from a book.
store
The read-only store a book’s answers, reconcile inputs and indexes read.
substrate
The commitment substrate a book embeds.