ledger: give rung 5 an App layer and move the report job's scheduling out of the model

[Yaraslaut]

Closes #160.

Which of the two options, and why

Option 1: give ledger an App layer — with one correction to the issue's own suggested fix.

#160's step 2 says "the App layer picks up pending jobs, computes, and dispatches an action carrying the result". Taken literally that would put a monthly-statement aggregation in the App, which examples/IMPLEMENTATION.md rule 1 forbids: all business logic lives in models. The precedent the issue cites doesn't do that either — bookmarks::app::App does only the non-domain half (fetch a URL) and dispatches RecordMetadata for the domain half.

So the split here is: the App decides when, the model computes what.

• execute(SubmitReport) writes a Pending row carrying kind and params, and returns. No executor, no thread. ledger_model.hpp no longer includes <morph/core/executor.hpp> — it was the only ladder model that did.
• New execute(RunReportJob) holds the aggregation the posted lambda used to, unchanged apart from where it gets its params.
• New ledger::app::App owns the worker pool and a QTimer that sweeps ledger_report_jobs for Pending rows and fire-and-forget dispatches RunReportJob through an internal-client Bridge carrying kReportRunnerPrincipal, with the stopBackgroundJobs() / reportsInFlight() settle seam bookmarks and pastebin both have.

Option 2 ("something smaller") isn't actually available: the only smaller move is making the model's executor injectable, which is #222 and leaves the model owning it.

One thing that contradicts #160

The issue says "bookmarks, polls and kanban each have an App … bookmarks::App::fetchMetadataOnce() is the working precedent, including its service-principal token minting for the re-entering dispatch." That precedent does not transfer, and the reason is worth reading before reviewing app.hpp:

RemoteServer::dispatchExecute clears the session principal whenever the authorizer's authenticate() returns nullopt — correct per docs/spec/security.md, and the default for AllowAllAuthorizer. Rung 5 ships no src/auth/, no AuthModel, no token secret. So a RemoteServer-based App is not merely unauthenticated here; it is one on which no action can carry a principal, and every mutating LedgerModel action refuses an empty one.

I hit this as a real failure, not by reading:

[ERROR] [ledger::App] RunReportJob dispatch failed for job 1: RunReportJob: only the report runner may run a report job

The runner therefore dispatches over a LocalBackend — which is also exactly the backend this rung's shipped client uses (AppContext's Local mode) — and App owns no RemoteServer and no server() accessor. That is documented at length in app.hpp rather than left to be rediscovered. For the same reason this PR adds no src/server/main.cpp: an unauthenticated financial server is not a thing to ship. Rung 5's missing login/authorizer/server story is filed as #242, not folded in here.

In-flight jobs at teardown

The most interesting consequence, and it is an improvement rather than a regression.

Before: a job was a lambda in a ThreadPoolExecutor the model owned. ~ThreadPoolExecutor drains its queue before joining, so a job in flight when the model died did finish — but only inside that exact process. A process that was killed lost the job entirely, with nothing anywhere that could tell it had ever been submitted, and the row stayed Pending forever.

After: the job is the row. A pass is "find the Pending rows, dispatch each". So:

• A job accepted by a process that then dies is still Pending, and the first pass of the next runner picks it up. test_app.cpp's "A job submitted before the App existed is picked up by its first pass" is exactly that scenario, with two App scopes standing in for two processes.
• This is why SubmitReport::params had to become a persisted column (params_json, new nullable ALTER TABLE migration 20260819000014): the params used to be decoded on the submitting thread and captured into the lambda, so they never needed to outlive it. A later runner has nothing but the row.
• A teardown that does not drain is still safe for the data — the aggregation either committed or it did not, and an uncommitted job is simply still Pending. What it is not safe for is App's own completion callbacks, hence reportsInFlight() and the pastebin-style _reportExecutor-declared-first member ordering.
• The cost, stated plainly in app.hpp: a job whose aggregation crashes the process is retried on restart rather than abandoned. A job whose aggregation merely throws is recorded Failed and is not retried.

There is no src/server/main.cpp in this rung to add a drain to, so the stopBackgroundJobs()-then-drain-then-destroy sequence is exercised by test_app.cpp and by test_report_presenter.cpp instead. When rung 5 gets a server (#242), that main copies bookmarks' drainMetadataFetches against reportsInFlight().

Interaction with #222 — direct collision

#222 and this PR cannot both land as they stand. #222 adds explicit LedgerModel(std::shared_ptr<IExecutor>) so a test can inject a deterministic executor for _reportExecutor. This PR deletes _reportExecutor, so that constructor has nothing left to inject and the <morph/core/executor.hpp> include it depends on is gone.

Branched from master as instructed, not from #222. Concretely:

• examples/ledger/include/ledger/models/ledger_model.hpp / src/models/ledger_model.cpp — testkit: a worker-side executor double, and ledger's report tests driven by it #222 adds a constructor and its null check; this PR removes the member both exist for. Merging testkit: a worker-side executor double, and ledger's report tests driven by it #222 first leaves a constructor to delete here; merging this first leaves testkit: a worker-side executor double, and ledger's report tests driven by it #222 with nothing to add.
• examples/ledger/tests/test_ledger_reports.cpp — both rewrite it, toward different end states. testkit: a worker-side executor double, and ledger's report tests driven by it #222 keeps one deliberately-real-ThreadPoolExecutor case and converts the rest to StepExecutor. Here there is no executor under the model at all: the run is a plain synchronous action, so pollUntilSettled is deleted outright — no sleep, no cap, no test double, and examples/TESTING.md's ban on sleep_for outside pump.hpp is satisfied by construction rather than by budget. testkit: a worker-side executor double, and ledger's report tests driven by it #222's careful justification for its one retained real-pool case ("the worker runs on a genuinely different thread, where session::current() is not the caller's") no longer describes anything: the worker is the caller's strand, and it has a session on purpose.
• examples/common/testkit/step_executor.hpp — testkit: a worker-side executor double, and ledger's report tests driven by it #222's other half, and it does not collide. It is a general testkit component, wanted independently (morph#161 names every ladder async-job test, not just ledger's). It just loses ledger as its first consumer.

Suggested resolution, if the maintainer agrees: land step_executor.hpp + its own test_step_executor.cpp + the TESTING.md entry from #222, and drop #222's LedgerModel constructor and its test_ledger_reports.cpp conversions. I have not touched #222's branch.

Verification

Measured locally, on this branch, with -DCMAKE_CXX_COMPILER=/opt/homebrew/opt/llvm/bin/clang++ and QT_QPA_PLATFORM=offscreen:

• ladder_ledger_tests builds warning-free and passes: 392 assertions in 79 test cases.
• bash scripts/check_spec_citations.sh → Prose lint OK.

Mutation check (AGENTS.md, "ask whether the check would still pass if the feature did nothing"), two mutations, each built and run, each reverted:

1. App::runPendingReportsOnce() returns immediately after its query, dispatching nothing → 7 failed (72 passed | 7 failed): all five test_app.cpp cases, plus ReportQmlBridge drives submit->poll to done and The App's report timer settles a job with no pass driven by hand.
2. execute(RunReportJob) skips its finishReportJob(..., Done, ...) → 12 failed (67 passed | 12 failed), spanning both test_app.cpp and test_ledger_reports.cpp (SubmitReport returns immediately…, Re-polling the same completed job…, Running an already-settled job recomputes nothing, SubmitReport stores its params on the job row…).

Left to CI, not measured here: the Application ladder job's full-ladder build and every other rung's suite; the Docs (Doxygen FAIL_ON_WARNINGS) job over the new public symbols; sanitizer and coverage presets; every non-macOS platform. Only ledger's own targets were configured locally (-DMORPH_LADDER_RUNGS=ledger), deliberately — another agent was compiling on the same machine.

Filed in passing, not folded in

• ledger rung 5 has no auth story: the shipped GUI installs no principal, and RemoteServer would clear one anyway #242 — rung 5 has no auth story at all: the shipped GUI never installs a principal, so every mutating action already fails in Local mode, and RemoteServer would clear one anyway. Pre-existing; it is what forced the LocalBackend choice above.

[codecov]

Codecov Report

❌ Patch coverage is 66.66667% with 34 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
examples/ledger/src/app/app.cpp	62.50%	20 Missing and 1 partial ⚠️
examples/ledger/src/models/ledger_model.cpp	72.50%	10 Missing and 1 partial ⚠️
...ples/ledger/include/ledger/models/ledger_model.hpp	0.00%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!