A report job whose ledger no longer exists settles Done with an empty body, indistinguishable from a ledger with no activity

[Yaraslaut]

What happens

ledger::app::App's report runner dispatches RunReportJob for every Pending
row. If the row's ledger_id names a ledger that does not exist, the
aggregation does not fail — it finds no accounts, produces [], and the job
settles Done.

Measured on branch fix/160-ledger-app-layer (PR #243):

orphan-ledger job  status=1 (Done)  body=[]

Why it matters

The result is indistinguishable from a successful report over a real ledger
that happens to have no activity. Both are Done with [].

For a rung whose point is auditable financial records, that is the wrong
default: "I computed your report and there was nothing in it" and "the ledger
you asked about is not there" are different answers, and only one of them should
satisfy a caller.

It also means the runner's own failure arm is unreachable this way — see below.

How it was found

While raising patch coverage on PR #243. The uncovered lines in
examples/ledger/src/app/app.cpp are its error arms — the .then() branch that
logs a Failed result, and the .onError() branch with its describe() helper
— and the obvious way to reach them was a job whose aggregation fails. Pointing
a job at a missing ledger turned out not to fail, which is how this surfaced.

A characterisation test asserting the current behaviour is landed in PR #243
(test_app.cpp, "A job whose ledger no longer exists settles Done with an empty
report") so it cannot change silently while this is open. That test asserts
Done deliberately — it pins today's behaviour, and should be updated by
whoever decides the intended one.

The adjacent, larger point

The App's error arms appear unreachable through any existing seam. The
aggregation is robust in every direction I could reach from outside:

• a missing ledger yields an empty report (above);
• malformed params_json does not throw — decodeMonthlyParams returns
  std::nullopt and the report falls back to all-time;
• DbFaultFixture contends on a named advisory lock, and LedgerModel takes
  none, so it cannot fault the aggregation.

So covering those lines needs a fault seam that does not exist, which is a
design decision rather than a missing test. Recorded here rather than papered
over with tests that execute the lines without asserting anything.

Options

1. Refuse the job: RunReportJob throws NotFound when the ledger is gone,
   settling the row Failed with a reason. Makes the two cases distinguishable
   and incidentally makes the runner's failure arm reachable.
2. Report it in the body: keep Done but emit a document that says the
   ledger was not found, so the distinction survives to the caller.
3. Keep it and document it: defensible only if a vanished ledger is
   considered impossible — but the row can outlive its ledger, which is exactly
   how this was produced.

(1) looks right and is the smallest change; it also removes the need for a
separate fault seam to test the failure path.

Verification status

Measured, not inferred: the status and body above are actual output from a
compiled run against a real SQLite store. The three unreachability claims were
each checked by reading the relevant code (decodeMonthlyParams,
db_fault_fixture.hpp, and a grep for SqlScopedLock in LedgerModel), not by
attempting each in a test.

[Yaraslaut]

Triage: triage: valid, area: ladder

Verified empirically against the branch this issue was raised from
(fix/160-ledger-app-layer, commit e59c03f8, PR #243), which already lands
the pinning characterization test this issue references. Built and ran
ladder_ledger_tests (SQLite backend) rather than trusting the read.

The premise holds, exactly as described

execute(RunReportJob) (examples/ledger/src/models/ledger_model.cpp:1049)
never checks whether action.ledgerId names a real row. It goes straight to
computeReportJson, which queries AccountRecord/TransactionJournalRecord
filtered by ledgerId (lines 303–387) and only conditionally checks
anything at all — nothing there distinguishes "zero rows because the ledger
doesn't exist" from "zero rows because it does exist and has none". With
accountRows empty, lines stays empty, glz::write_json(lines, ...)
produces "[]", and finishReportJob(..., ReportStatus::Done, ...) settles
the row Done.

Ran the existing test directly:

$ ladder_ledger_tests.exe "A job whose ledger no longer exists settles Done with an empty report"
All tests passed (5 assertions in 1 test case)

I then wrote two throwaway probe cases (not committed) to pin down exactly
which real-ledger state collides with the orphan case, since "no activity"
is ambiguous between "zero accounts" and "accounts with zero transactions":

• Real ledger, zero accounts (a LedgerRecord row with no OpenAccount
  ever called) → Done, body "[]". Identical to the orphaned-ledger
  case. This is the actual collision.
• Real ledger, one account, zero transactions (makeLedger's shape, used
  throughout the existing suite) → Done, body
  [{"currency":"USD","numerator":0,"denominator":1,"decimalPlaces":2,"transactionCount":0}].
  Distinguishable — a real account reports a zero-balance line even with
  no journal entries.

So the issue's claim is confirmed and, if anything, understated in one
direction and overstated in another: the ambiguity is real, but it is
specifically "ledger absent" vs. "ledger present with zero accounts", not
every shape of "no activity".

Against the invariants

Invariant 3 (a value type reports the fact; the layer decides the
policy) applies, and in the direction the issue's own Option 1 already
points: ledger::ReportStatus (include/ledger/core/types.hpp:46) already
has a Failed value — no new enum member is needed. NotFound
(include/ledger/core/errors.hpp:20) is already the type this exact file
throws for "no such ledger" at every other ledger-scoped mutating action:

• OpenAccount → throw NotFound{"OpenAccount: no such ledger"}; (line 480)
• StoreTransaction → throw NotFound{"StoreTransaction: no such ledger"}; (line 611)
• ImportLedgerChunk → throw NotFound{"ImportLedgerChunk: no such ledger"}; (line 892)
• SubmitReport → throw NotFound{"SubmitReport: no such ledger"}; (line 1015)
• storeJournalImpl → throw NotFound{"storeJournalImpl: no such ledger"}; (line 1222)

execute(RunReportJob) is the only ledger-scoped action that omits this
check — invariant 6 territory (a guarantee applied everywhere but one site),
just inverted from the usual "three copies" framing: here it's "N copies of a
guard, one silent gap". The existing catch (...) block
(lines 1124–1153) already turns any thrown exception into
RunReportJobResult{.status = ReportStatus::Failed} and logs it, and already
records Failed on the job row via finishReportJob. So the fix is:
add the same ledgerRows.empty() → throw NotFound{...} guard already used
five other places in this file, at the top of execute(RunReportJob) (or
inside computeReportJson, gated by the same WalSnapshotGuard snapshot).
No new mechanism, no new status value, no fault seam — it composes with
machinery that already exists and is already exercised by the catch block's
own tests.

Against docs/spec/ and the README

examples/ledger/README.md's report section (lines 98–134) documents the
submit→poll job idiom, snapshot semantics, and who runs the job (morph#160),
in detail — but says nothing about a vanished ledger. This is a genuine gap,
not a documented tradeoff the issue is second-guessing.

Valid-vs-rescope

The issue names three options but explicitly picks one and gives the
concrete mechanism ("(1) looks right and is the smallest change; it also
removes the need for a separate fault seam to test the failure path"): throw
NotFound from RunReportJob when the ledger row is gone, settling Failed
through the exception path that already exists. That's a single, buildable
change reusing existing types (ReportStatus::Failed, NotFound) and an
existing catch-all — not an open menu of designs. bug is dropped: this
isn't a regression in shipped behavior (rung 5's App layer, PR #243, is still
unmerged), so I'm leaving the label set to triage: valid + area: ladder
without re-adding bug.

Verdict: triage: valid. Implement as written — add the missing
ledgerRows.empty() → throw NotFound{"RunReportJob: no such ledger"} guard
to execute(RunReportJob) (or computeReportJson), matching the pattern
already used by every sibling action in ledger_model.cpp, and update the
characterization test at test_app.cpp:241 (currently asserting today's
Done/"[]" behavior on purpose) to assert Failed instead once the fix
lands.