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 · consistencyThe 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 section | Module |
|---|---|
Record header (anchor record); Epistemic Type; Typed Links | record; sealing a record as Go’s book does, seal |
| Record/Payload Separation; Retention States | retention |
| Disclosure Records | disclosure |
| Index Classes | index |
| The Commitment-Substrate Interface | substrate; the read-only store an answer reads, store |
| Answering a Request; Three Kinds of “No” | request |
| Answering a Request: the artifact response | answer; 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 Close | reconcile |
| Privacy Considerations: What a Checkpoint Reveals | padding |
| (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-capsulespec/interop-profile-v0.md§6.2 and §6.2.1, andevidence-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
dealfeature. - 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_answeredrecord, as Go’sRespond(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.jsonholds 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’sshelf_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 ashex(SHA-256(salt ‖ JCS(value))), each under its own 32-byte salt, and an opening{salt, value}shows one value.testdata/shelf/facts/vectors.jsonholds the shared vectors. - standard_
history - The
standard_history/1card (agent-action-capsulespec/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
CheckStapleand the Pythoncheck_stapledo, and ahistory_card/1orstandard_history/1staple 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.