Scenario · PG-05
Plan vs actual in one ledger
Actual, provisional, planned and simulated postings share one double-entry core — separated by a mandatory scenario tag, never a parallel store.
- one ledger, many scenarios
- one undeletable Actual
- per-scenario double-entry
- explicit filters
Every number in Ledgerbook names which reality it describes, and scenario planning for finance starts with that axis: Actual, Plan, Forecast, Simulation or a custom variant — a first-class dimension on every posting. It composes with Status (Provisional → Final) and Book (valuation basis) without collapsing any of the three: every posting is (scenario, book, status). The scenario tag is mandatory — untagged rows are rejected at write time — and each tenant has exactly one undeletable Actual. Planned and simulated postings share the same double-entry core as actuals, balanced per scenario. Full-mode planned and simulated scenarios, computed variance and no-copy planning reads and writes ship at PH-1; delta-scenario storage over the Actual base, switchover, and the roll-forward, override and promote operations arrive with PH-2 (Roadmap).
Verified 2026-09-19 · source: scenario registry reference FR-300–309, FR-335/342/344
Phase legend: PH-1 shipped now · Roadmap arrives with PH-2. Labels are always present — colour is never the only signal.
Shipped first: the registry and the Actual scenario
“One ledger, native scenario axis — actual, provisional, planned and simulated postings share the same double-entry core, separated by the scenario tag.” The mechanics behind that sentence are live at PH-1, and they are invariants — not a checkbox on a settings page.
PH-1
The tag is mandatory
Every posting carries a scenario reference resolving to a registry row; untagged rows are rejected at write time. There is no default-ledger hole — and scenario is data on the row, never encoded in a storage location or table name.
PH-1
Exactly one Actual
Created at provisioning, undeletable, full storage. Actual accepts ingestion and lifecycle-governed postings — but never an ungoverned final write that bypassed the lifecycle. No admin action can delete or re-mode it.
PH-1
Kind is immutable
actual · planned · simulated · custom. Forecast, budget and rolling forecast are presets of planned — not separate kinds. Provisional is not a scenario at all; it is Status. Once postings exist, kind and preset can't be re-labelled — a change is a new scenario, linked by lineage.
PH-1
Per-scenario double-entry
Within one scenario, debits equal credits; a transaction that mixes scenarios is rejected. Cross- scenario effects travel through recorded operations that create new entries — they never rewrite existing ones.
PH-1
Discoverable by machines
The registry lists scenarios by kind, preset, role, status, base, writability and owner — with boundary, write window and storage mode — so an agent can find the right scenario before touching any data. The same surface exists over REST and MCP.
PH-1
Writability is server-side
Every write is evaluated against kind × preset × role × status × window × locks × constraints × caller access — server-side, with typed errors. MCP receives no privileged bypass of the matrix.
The closed kind enum — and the public names that map onto it
| Public class | Registry representation | Engine rule | Default storage |
|---|---|---|---|
| Actual | kind=actual |
Governed writes only; undeletable; exactly one per tenant; consolidated | full |
| Plan · Forecast · Budget · Rolling forecast | kind=planned, distinguished by preset |
Governed cycles — publish, lock, write windows; plans self-balance through a plan-only control account | full Roadmap |
| Simulation | kind=simulated |
Sandbox writes within access control; must expire; never consolidated; discard by expiry, never deletion | full |
| Custom | kind=custom + declared behaviour class |
Inherits the rules of the declared class (actual, planned or simulated) while keeping its own name | per class |
Storage modes: full ships at PH-1; delta inheritance over a base scenario is Roadmap (PH-2). The public taxonomy maps without loss — clients never treat a preset as a separate kind. Trace FR-301/302/304/309/335/342/344 · PH-1
Can you run plan and actuals in one ledger?
Yes — in one ledger, as separated scenarios. Planned and simulated postings are scenario-tagged rows in the same double-entry core as actuals: balanced per scenario, never netted across scenarios, and returned as per-scenario subtotals in separate fields. What is on the roadmap is how the two sides meet by *inheritance*: actuals composed into a plan over a boundary rule rather than posted into it. Variance itself is computed from both sides' rows, and switchover that moves the boundary without deleting a plan row. Every read answers as-of on both time axes — the comparison at a date, and the comparison as it was believed at a past instant — which is what keeps plan vs actual audit-safe.
Verified 2026-09-19 · source: planning consumption contract FR-316/318–320/330/341
No copies — a boundary rule
History enters a plan by composition, not duplication: the scenario stores where inherited base data stops and its own rows apply, and the resolved boundary is echoed in every read. Roadmap
Variance — computed, not stored
Variance runs from each side's rows with no data movement, and never implicitly nets scenarios. Ask for it to be materialised and it lands in a read-only variance scenario whose rows carry both source postings. Roadmap
Switchover — forward only
Moving the boundary forward never deletes past plan rows: they stay stored and verifiable, superseded in composition by the base scenario's data. Roadmap
What lives in one ledger — four typed layers
| Layer | What it holds | In the monetary trial balance? |
|---|---|---|
monetary |
Posting amounts — exact decimal arithmetic in minor units, no floats anywhere | Yes — the trial balance runs over this layer |
statistical |
Drivers and quantities — units, headcount, rates; the numbers models act on | No — balances within its own layer, with explicit quantity signs |
commitment |
Encumbrances against a plan, consumed as actuals arrive — relieved by compensating entries that reference the original, never deleted; each retains its link to the source object (PO or contract) for lineage | No — Roadmap the relief lifecycle completes with PH-2 |
forecast |
Forecast-only rows kept typed and scenario-tagged like any other posting | No — excluded from the monetary trial balance |
Rows are typed at posting time and balance within their layer — the monetary trial balance never absorbs statistical, commitment or forecast rows. Trace FR-338
Plans balance without touching the books
Planned scenarios self-balance through a plan-only control account — identifiable by role, excluded from statutory trial balances, and never distorting an actual result. Budget lines are posting rows, not report-time arithmetic.
PH-1
Reserve without posting
The availability primitive: reserve, release, capture — with owner, purpose and expiry, and automatic release when a reservation lapses. Reservations are a distinct, rebuildable projection and never appear in statutory balances.
Trace FR-337 (plan control account), FR-148 (reserves) · PH-1
Scenario planning vs budgeting: one axis, different jobs
They are registry rows, not separate systems. Budgeting is governed and cyclical — publish, lock, write windows. Forecasting rolls forward: a re-plan is a new scenario linked by lineage, never a mutation. Simulation is a sandbox that must expire and is never consolidated. Each is distinguished by a preset, immutable once postings exist. Scenario planning for finance stops being a copy problem when every number names which version of the plan it belongs to.
Verified 2026-09-19 · source: scenario registry reference FR-302/307/324/325, PD Ch.4
Orthogonal, always
Every posting is (scenario, book, status). Scenario says which reality the number describes; book says what it means — group IFRS, local GAAP, tax, management; status says how final it is, Provisional → Final. “IFRS × budget × provisional” needs no special ledger type.
It stores, composes and proves — it does not plan
Grids, formula engines and model logic are third-party, deliberately out of scope: your planning stack is your surface, and the ledger is what it reads and writes. No UI of ours means no workflow to adopt.
No silent default
A read without a scenario filter fails rather than defaulting to Actual, and a filter must be explicit or explicitly wildcarded — with the wildcard recorded in provenance. Silent answers across scenarios are not part of the design.
Trace FR-301/308/342 · PH-1 · boundary with application surfaces: NG-1, NG-6
Cross-scenario operations — every one a recorded act Roadmap
At PH-2, scenarios stop being separate reads and start talking to each other — and every conversation is an operation with a record, never a side effect of a query, and never a rewrite of history.
promote — publish with a conflict policy
Publishes from one scenario to another with an explicit conflict policy — reject, overwrite or non-conflicting. Target rows carry their source posting; the source scenario is retained, never deleted.
copy_scenario — scoped, tagged
Copies none, all, visible or selected rows; every copied row is provenance-tagged with its source, and a copy never bypasses the target's rules — a simulation can never be copied into Actual.
roll_forward — explicit opening rows
Closing balances become explicit opening postings that reference the source period's close — an auditable derivation, never an invisible seeding job, and idempotent per close.
variance — ask, don't assume
Computed from each side's rows with no data movement and no implicit netting; materialising it creates a read-only variance scenario, regenerable and closed to direct writes, with both source postings on every row.
set_switchover — forward only
The boundary moves forward only, and nothing is deleted: superseded plan rows remain stored and verifiable, merely overtaken in composition by the base scenario's data.
Override & discard — appended, never edited
Changing a planned number appends a superseding row — amounts are never updated once written, at any layer. Simulations discard by expiry, never by deletion, and stay queryable by id for audit.
Every one of these operations appends a scenario-operation record — operation, from and to, mode, conflict policy, actor, policy id, timestamp — plus lifecycle events; source rows are never mutated or deleted. The verbs behind them are separable by design: read, write, publish, lock and admin are independent scenario permissions, so planners write and controllers publish. Visibility is private, shared or public; seals are one-way; and planned-number provenance reconstructs how any figure was derived.
None of these operations are in PH-1. What ships first is the registry and the Actual scenario; delta inheritance, promotion, roll-forward, variance runs and switchover are labelled Roadmap and enter with PH-2. Cross-scenario effects always create new entries — no operation above rewrites an existing one.
Trace FR-310–334, FR-345/347–349 · Roadmap (PH-2)
Frequently asked
What is a scenario dimension in a ledger?
A scenario dimension is a first-class axis on every posting naming which version of the plan the number belongs to: Actual, Plan, Forecast, Simulation or a custom variant. In Ledgerbook the scenario tag is mandatory on every posting, and each tenant has exactly one undeletable Actual scenario. Delta storage over the Actual base and cross-scenario operations such as promote are on the roadmap.
Can you run plan and actuals in one ledger?
Yes — in one ledger, as separated scenarios. Planned and simulated postings are scenario-tagged rows in the same double-entry core as actuals, balanced per scenario and never netted across scenarios; multi-scenario reads return each scenario's subtotals in separate fields. What's Roadmap (PH-2) is how they meet: actuals inherited by composition over a boundary rule, variance computed from both sides, and switchover that moves the boundary without deleting plan rows. The full model →
How do scenarios relate to Status and Book?
They are orthogonal axes that compose: every posting is (scenario, book, status). Scenario says which reality the number describes — actual, planned, simulated or custom; book says what it means — group IFRS, local GAAP, tax or management; status says how final it is, Provisional → Final. “IFRS × budget × provisional” is a normal query — it never needs a special ledger type.
Is Ledgerbook a planning tool?
No, and deliberately so. Ledgerbook stores, validates, composes and proves scenario-tagged numbers; planning grids, formula engines and model logic are third-party. A planning stack reads and writes the same ledger through the API and MCP using scenario filters, and that no-copy contract ships at PH-1 — there is no second plan-of-record store. What is on the roadmap is delta-scenario storage, where a plan *inherits* the actual base rather than holding its own rows, together with switchover and the roll-forward, override and promote operations. For planning vendors →
What are Plan, Forecast and Simulation in the model?
Kinds and presets, not separate systems. Plan and Forecast are both kind=planned,
distinguished by a registry preset — plan, forecast, budget or rolling forecast. Simulation is
kind=simulated: a sandbox that must expire, discards by expiry rather than deletion, and
never consolidates. Custom scenarios declare which behaviour class they inherit. Kind, preset and
behaviour class are immutable once postings exist; a change is a new scenario, linked by lineage.
How much of this month is already committed?
Committed is the part of a period that is already determined by an obligation that exists — a signed contract's revenue schedule, a paid prepaid's amortisation, an asset's depreciation, a lease's monthly expense. Ledgerbook records those positions as future-effective entries bound to the obligation behind them, and every forward read reports the committed amount and share alongside the final and provisional ones. It contains no estimate and no model output, which is the whole reason it is named separately.
Committed is a band of effective time, not a status and not a scenario. A committed position carries a Status, a Scenario and a Book like any other entry — it sits in the SCHEDULED state until its effective date, contributes to no view=final balance, and remains revisable and withdrawable by its owner while that date is in the future.
It never posts by itself. When the effective date arrives the position enters the normal lifecycle at Provisional and proceeds like anything else, so the accounting team still reviews and posts under policy. A schedule confers no posting rights — which is the difference between reading a period forward and closing it early.
We record these schedules; we never compute them. Amortisation, depreciation and revenue-recognition schedules are the owning subledger's arithmetic. The ledger runs no business calendars: ask it to expand a recurrence rule and it returns a typed error. What it does is hold the result where every application above it — your planning tool, an agent, an auditor — reads the same forward view rather than an export of it.
- Final — posted to the ledger. Status axis.
- Committed — determined by an obligation that already exists; contains no estimate. A band of effective time, not a status.
- Provisional — in the ledger, awaiting approval. Status axis.
- Plan — a separate scenario on the same ledger. Scenario axis.
Read on the 12th, most of the month is not a forecast — it is already known and simply not yet visible. Three axes compose on one entry (Status, Scenario, Book) and a forward read reports each band separately, so nothing borrows another band's certainty.
Committed positions and the obligation registry: FR-240/FR-241 · the committed band on every composed and variance read: FR-350 — PH-1. The server-computed forecast-ready gate (FR-355) is Roadmap.
What Ledgerbook is not
Scenario is an axis on the ledger. It is not a planning product, and the difference is what keeps both honest.
- Not a planning UX (NG-6). Grids, formula engines, driver trees and multi-year modelling belong to your FP&A tool. What the ledger provides is the axis they read and write against — actual, planned, simulated and custom, each balanced on its own.
- No forecasting models (NG-4). We do not predict your revenue. We hold the numbers a forecast is built from, disclose how mature each one is, and record the plan the forecast becomes — so the model stays yours and its inputs stay checkable.
- We record committed schedules; we never compute them (NG-1). A signed contract's revenue schedule, a paid prepaid's amortisation, an asset's depreciation, a lease's monthly expense — the owning subledger computes those. Ledgerbook records them as committed positions bound to the obligation behind them. The ledger runs no business calendars: asking it to expand a recurrence rule returns a typed error, not a roadmap item.
Put planning on the ledger
The registry model is live; the planning operations arrive with PH-2. If you build planning surfaces, the ledger beneath them is what we do.