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" } ]
}| Axis | What it records | Trace |
|---|---|---|
| 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, 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.
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)
Provenance & audit FAQ
What is OCEL 2.0 and why does provenance matter in finance?
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 · AI-agent audit trail
Which OCEL version does Ledgerbook emit, and can it import older logs?
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.
Is any write path exempt from provenance?
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
How do I trace a number back to its source document?
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.
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.