Provenance · PG-06 # Every mutation is a provenanced event — no write path exempt who · when · where · why on every commit, exported as OCEL 2.1 — object-centric logs an auditor can load and verify independently, with 2.0 accepted inbound. - who / when / where / why - OCEL 2.1 out · 2.0 in - scope-filtered exports - chain-sealed event stream Provenance in Ledgerbook is not a log line bolted onto write paths — the event is the only write path. Every mutation appends an event carrying who acted (actor kind, credential id, model id for agents), when it was recorded (server timestamp plus a monotonic sequence), through which channel (REST, MCP, CLI, streaming, batch or connector), and why (reason code, policy id, approval state, materiality tier). No write path is exempt — ingestion included — and incomplete provenance fails closed rather than defaulting to a system actor. The event stream is chain-hashed — on by default, deliberately unlike ledgers that ship it off, and not disableable — and exported as OCEL 2.1, the current standard revision, with OCEL 2.0 accepted inbound. Ledgerbook AI is a headless, MCP-native ledger of record. Verified 2026-09-19 · Sources: Ledgerbook product docs — provenance model (FR-234–238) and audit export (FR-905) · Phase: PH-1 Phase legend: ✓ PH-1 shipped now · ◇ Roadmap arrives with PH-2. Labels are always present — colour is never the only signal. ## Export the whole lifecycle as object-centric events An export is a projection of the immutable log, not a translation: internal provenance tables map 1:1 onto the OCEL metamodel, so what you load is what the ledger stored. - **OCEL 2.1 outbound, JSON** — the current standard revision, validated against the official schemas in CI, with an external-loader smoke test (a permissively licensed OCEL reader) catching serialization regressions schema checks miss. - **OCEL 2.0 accepted inbound** — a 2.0 artefact loads without conversion on your side, preserving external ids, connector channel and dual attribution. - **Scope-filtered and reproducible** — the same (scope, E, K) re-exports byte-identically, and the pipeline recomputes a trial balance from the OCEL alone; a mismatch fails the export job before delivery. - **Who/when/where per event** — the envelope travels with every event, not only in a summary header. ◇ Roadmap Bundled dense formats (.ocel.zip, SQLite, CSV/Parquet) for multi-million-event periods, plus audit evidence packages — both PH-2. Request an export by profile — org, ledger, book, scenario, period, as-believed — and receive the artefact with a manifest and head hash. Export jobs are idempotent: the same profile exported twice yields byte-identical artefact hashes. FR-905, FR-531 · PH-1 (JSON) Page the event stream directly — filter by sequence, actor or event type — with the resolved knowledge instant echoed on every response. FR-234/235, FR-515 · PH-1 `# one event, one object — every export carries the full envelope { "event": { "id": "e-00412", "type": "entry.finalized", "time": "2026-09-19T09:41:07Z", "attributes": [ { "name": "ledger_seq", "value": 184220 }, { "name": "actor", "value": "controller@grp-eu" }, { "name": "channel", "value": "rest" }, { "name": "policy_id", "value": "tier-t1-2026-08" }, { "name": "prev_hash", "value": "9f2c…7ad1" }, { "name": "hash", "value": "3d81…c04e" } ] }, "relations": [ { "objectId": "entry-7741", "qualifier": "finalized" } ] }` Event anatomy — what every event carries, validated before append. AxisWhat it recordsTrace **Who**Actor kind (human, agent, service, system), identity, hashed credential id, on_behalf_of where delegated, model id for agents.FR-235 **When**Server-authoritative timestamp plus a strictly monotonic ledger_seq; client times are recorded but never used for ordering.FR-235, FR-237, FR-501 **Where**Channel — rest, mcp, cli, streaming, batch, connector — with client name/version and trace id when interactive.FR-235 **Why**Reason code, policy id, approval state, materiality tier — evaluated, stamped and re-performable.FR-235, FR-218 **Integrity**prev_hash and hash over the canonical serialization, including schema version.FR-237, FR-524 **Effective time**Business date inside the hashed payload, so retroactive changes are detectable.FR-500, FR-505 What is the full ancestry of this number? Objects and events are linked by qualified relationships, so lineage is a graph walk, not a report. Relationships are traversable across ledger objects and business documents — and every hop carries its own actor and time. ### Documentary lineage, multi-hop Purchase request → purchase order → invoice → payment: any posting can answer where it came from and what it touched. The object-type registry is frozen and additive-versioned — entries, source documents, accounts, actors, sessions, approval tasks, periods — and inbound foreign objects map to it or are rejected with a per-object error list, never silently coerced. FR-518, FR-525 · PH-1 ### Correction graphs Corrections are new objects linked reverses / adjusts / corrects to the original, with the typed correction on every edge. The original entry stays byte-identical; the graph shows both the mistake and its fix, attributable at each step. FR-205, FR-525 · PH-1 Direction, depth, relation filters and as-believed (K): hops created after K are absent, and a depth cut returns truncated with a cursor rather than a partial graph pretending to be complete. FR-525–527 · PH-1 Every correction linked to an entry, typed by the unified enum — reversal, adjustment, restatement — with the corrected and correcting sides both visible. FR-205, FR-228 · PH-1 Projection mode: the default OCEL projection is cold — materialised per export profile from the immutable log and discarded once the artefact is written. ◇ Roadmap A continuously materialised hot projection for auditor-query latency is a PH-2 option gated on sizing evidence (OI-36). Both modes project the same log; neither is authoritative. Reconciliation rides the same graph: a matched finding is a lineage path — billing totals, terminal batches, channel payouts and the bank deposit tied into one verified number, every match, exception and adjustment on one traversable evidence path ([reconciliation by relationship](/reconciliation), FR-150–157). ## A day in the life of an auditor No vendor assurance, no exported spreadsheet, no data request filed to IT. Time-boxed, read-only, and verifiable by the auditor alone. Verify immutability instead of trusting it — run the chain check yourself, without ledger access. - **1 · Scope.** An auditor receives time-boxed, read-only credentials scoped to one entity's books — row-level access composed server-side, never an existence oracle. - **2 · Export.** Pull the OCEL 2.1 export for the period: an object-centric log with who/when/where on every event. - **3 · Load.** Open it in a conformant OCEL tool of choice — the artefact is standard-shaped and independently loadable. - **4 · Walk.** For a sampled invoice: the ingest event, three revision events on the same entry object, the one-way finalization, a later correction with its typed semantics. - **5 · Verify.** Run the chain check against published roots — tamper-evident, not vendor-assured. [How verification works](/immutable-ledger#verify). ### Sample audit export A fixture export with a small entry lifecycle — create, revise, approve, finalize, correct — ships with the developer preview so the format can be inspected before deployment. ◇ Roadmap Bundled evidence packages that wrap the export, the manifest and the verifier for a filing-ready handoff are PH-2. FR-905 · PH-1 (JSON export); evidence packages PH-2 (FR-907) [Get the developer preview](/developers) ## Provenance & audit FAQ OCEL 2.0 (Object-Centric Event Log) is an open standard for recording events together with the business objects they touch — the format process-mining and audit tooling can consume directly. Provenance matters because a balance without its event history is an assertion, not evidence: Ledgerbook stores the full path — ingest, revisions, approvals, finalization, corrections — and exports it as OCEL 2.1, the current revision, accepting 2.0 inbound. Related: [hash chain](/glossary#hash-chain) · [AI-agent audit trail](/ai-agent-audit-trail) Ledgerbook emits OCEL 2.1 — the current standard revision — as JSON, validated against the official schemas in CI, with 2.0 and 2.1 both accepted inbound: a 2.0 artefact imports without conversion on the caller's side, preserving external ids, channel and dual attribution. ◇ Roadmap Bundled dense formats and audit evidence packages are PH-2. No. Draft edits, submissions, approvals, finalizations, corrections, cancellations, period changes and every ingestion path emit events through a single append path — missing or incomplete provenance fails closed, and it never defaults to a system actor. Even autosave micro-commits emit an event; storage may coalesce revision bodies, but the event trail is complete. FR-234, FR-236, FR-522 · PH-1 Through qualified relationships: purchase request → purchase order → invoice → payment, and corrections as reverses / adjusts / corrects links on new entries. A lineage query walks the graph with per-hop actor and time, and as-believed reads show the ancestry as it was known at a past instant. [As-of reads](/provisional-lifecycle#as-of). ## What Ledgerbook is not We produce the evidence. Reading it is deliberately somebody else's job. - **No analysis tooling in the product (NG-4).** Process-mining and analytics run in the auditor's or analyst's environment, against the export. We keep AGPL-licensed tooling out of the product on purpose, so what you receive is a standard file and a verifier — not a dependency you inherit. - **No statutory filing or tax reporting (NG-5).** We do not submit anything to a tax authority or an e-invoicing network. The export is what a filing is defended with, not the filing itself. - **No UI for the evidence (NG-1).** There is no audit viewer to log into. The artefact is a file an auditor can load in tooling they already trust, and verify without asking us for anything. ## Audit the record, not the vendor Chain-hashed events, OCEL 2.1 exports and a verifier you run yourself — design partners first.