bank: give it a server, and a scenario corpus over all 41 actions

[Yaraslaut]

Bank had the largest model surface in the tree and no way to drive it as a real client: eleven models, 41 registered actions, reachable only in process. This gives it a server binary and a scenario corpus that exercises every one of those actions over a WebSocket.

Scope, and what this deliberately does not do

Refs #87 — this does not close it. Issue #87's remaining open question is step 1, bank's slot in the ladder, which its own comments reserve for the maintainer. Nothing here numbers bank, adds it to examples/rungs.txt, or renumbers anything. scripts/check_rung_filters.sh passes all 37 checks untouched, because bank stays invisible to it: it never calls morph_add_rung().

Steps 2–5 of #87's original 2024 plan are addressed by its own later comments (step 2 dissolved when #86 closed deciding nothing would land for bank's GUI to migrate onto; bank's hand-rolled controllers are the recorded, justified pattern). This PR takes the one piece that was blocked on nothing: bank's action surface being undrivable from outside its process.

ladder_bank_server

examples/bank/src/server/main.cpp: bank::db::setup(), a process-wide FileActionLog (the one bank's CLI already installs), a RemoteServer over a worker pool, and a QtWebSocketServer in front. Reads BANK_DB / BANK_PORT and prints the listening on ws://… line run_scenarios.py parses.

Why main() owns the server rather than bank::app::App. Every rung puts its RemoteServer in an App. Bank cannot follow that without changing what App is: it is the client-side context the GUI and CLI build on — a Bridge over a LocalBackend, a MainThreadExecutor for callbacks, and the login()/logout() pair that sets that bridge's session. It hosts no RemoteServer and needs none; adding one would put a listener's machinery into every desktop and CLI process to serve a fourth consumer. The server side bank needs is small enough to live in main.cpp in full.

Why the CMake target is written out locally rather than via morph_add_rung(). Two reasons, the second decisive:

1. The macro links morph::ladder_<rung>_lib, a target only the macro creates. Bank's library is bank_lib, built against a different dependency set (Lightweight/ODBC, and deliberately without apply_warnings() because the ORM headers are not -Werror clean).
2. Calling the macro was not available. examples/rungs.txt documents that "omitting a rung here while examples/<rung>/CMakeLists.txt calls morph_add_rung() is a hard configure error, by design". The call would therefore force bank into rungs.txt, and with it into ladder CI, the sanitizer and WASM matrices, codecov.yml components and coverage.sh — the numbering decision Fold examples/bank into the application ladder's conventions (scoping only, blocked on #86) #87 reserves. So the target is a local add_executable mirroring the macro's server block line for line.

Bank is added to SERVER_RUNGS and run_scenarios.py's RUNGS without touching examples/rungs.txt. That tuple has always actually selected on "has a src/server/main.cpp" — the property deciding whether a scenario can reach the thing. Being a rung and having scenarios were already independent in the other direction: lims and crm are rungs with no scenarios.

Authentication is demo-grade, and commented as such. Bank's AuthModel mints no bearer token — LoginRequest verifies a password and returns the principal for the client to install, which is exactly what App::login() does. There is no signed artefact for a server to verify, so a SigningAuthorizer would refuse every client bank ships. The default allowAllAuthorizer() is not an option either, and this is the subtle part: RemoteServer::stampVerifiedPrincipal clears session.principal when authenticate() returns nullopt, so under the default authorizer every bank action would run with an empty principal and fail with "no session principal" — bank would be registered, reachable, and unable to do anything. So the server installs a BankDemoAuthorizer that vouches for a non-empty asserted principal and refuses an empty one. Per-row ownership is still enforced by the models (db::loadOwned), so cross-customer isolation is genuinely testable; credential proof is not, because bank has none to prove.

The corpus — 22 files, 41/41 actions

	before	after
bank actions dispatched	— (no server)	41/41, 0 allowlist exemptions
bank workflow files	—	22/22 qualifying (floor set to 22)
corpus-wide action total	72/72	113/113

coverage_allowlist.json is unchanged — bank needed no exemptions. Every action is reachable and reached.

Three things the corpus records because they are true, not because they are right

Each is asserted with expect ok, deliberately, so the day it changes something fails:

1. Owner-by-name is not checked against the session. ListAccounts, ListPayees, ListPayments, ListLoans, ListBudgets, ListNotifications, MarkAllRead and GenerateStatement resolve action.owner through bank::resolveOwner, which returns the caller's string verbatim and only falls back to the session principal when it is empty. Nothing compares the two, so any signed-in customer can read another's data by typing their username — and via MarkAllRead, write to it. SpendingByKind is worse: it takes a bare accountId, consults no owner at all, and answers even an anonymous caller. Actions addressed by row id do enforce ownership, and the two spellings sit side by side on the same models. an-owner-named-outright-is-not-checked-against-the-session.scenario is the inventory a fix has to cover.
2. validate() shadows the model's own ValidationError. morph evaluates a DTO's validate() before dispatch, so a client sees "action failed validation: <Model>/<Action>" and never the model's message. Roughly half of bank's hand-written validation messages are unreachable over the wire.
3. GenerateStatement's closingBalanceMinor is the account's current balance, not its balance as at the window's end — narrowing the window moves the credits and debits and leaves it alone.

Verification (actual output)

$ python3 scripts/scenario/run_scenarios.py --rung bank --build-dir build/bank-srv --twice
every scenario passed in: bank
EXIT=0            # 44 file runs = 22 files x 2 passes

$ python3 scripts/scenario/scenario_coverage.py
  bank       actions 41/41 dispatched (0 exempt), workflows 22/22
  total actions dispatched: 113/113
Every registered action is dispatched and every rung meets its floor.
exit=0

$ python3 scripts/scenario/test_morph_scenario.py
Ran 132 tests in 0.467s
OK

$ sh scripts/check_rung_filters.sh
All 37 rung-filter checks passed.

$ python3 scripts/scenario/run_scenarios.py --rung pastebin --build-dir .../build/ladder-srv
every scenario passed in: pastebin      # no regression from the shared-file edits

--twice is what proves the corpus is re-runnable against a database it has already run on. Two files needed real fixes to get there: GenerateStatement fans out over every account its owner has ever opened, so its totals grow each pass — those assertions are now pinned to captured account ids instead.

Mutation testing — necessary, not sufficient

$ python3 scripts/scenario/run_scenarios.py --rung bank --build-dir build/bank-srv --mutate
  ok   a-card-through-its-whole-lifecycle.scenario (+ mutants)
  ... all 22 files ...
every scenario passed in: bank
EXIT=0

Every assertion in all 22 files was flipped one at a time (ok↔err, ==↔!=, ~↔!~) and rerun: zero surviving mutants, so no assertion in the corpus is inert.

Stated as the weak check it is. morph#460 established that mutation cannot detect the vacuous-comparison class — it perturbs the scenario, not the server, and both mutants of a dead assertion die anyway. So that class was checked separately, by hand:

• Bank's DTOs declare no enum-class members at all — all the enum-ish fields are plain int with the enum named only in a doc comment — and there is no glz::meta anywhere under examples/bank/. This re-confirms the morph#445 measurement against current master, and it is why bare integers are the correct encoding here (unlike ledger, whose corpus is red for exactly this reason under morph#460).
• Grepping the corpus for field <name> (==|!=) <integer>: there is no !=-against-an-integer assertion anywhere. Every enum assertion is a passing == against an integer, which can only pass if the wire value really is that integer — the tautology morph#460 found is not expressible here.
• Every !~ assertion is a regex over JSON text, compared with text.

Files touched

examples/bank/ (CMakeLists, README, new src/server/main.cpp) and scripts/scenario/ (README, run_scenarios.py, scenario_coverage.py, test_morph_scenario.py, new scenarios/bank/). Not touched: examples/rungs.txt, codecov.yml, .github/, cmake/, examples/ledger/, docs/spec/. The scripts/scenario/ edits are additive (one dict entry, one tuple entry, one floor, one pinned name-set) and overlap in directory only with the open PRs on scripts/.

🤖 Generated with Claude Code

https://claude.ai/code/session_01C6uB9zxdSG8qp3VNAAyFvF

[Yaraslaut]

Rebased onto master (the only conflict was test_morph_scenario.py's corpus-wide action total, now 114 — ledger gained ListTransactions in #472/#428 while this branch was open) and added a documentation pass. No behaviour changes: every edit outside the four documents is a comment.

Bank takes no rung number

The one question #87 left open (its step 1) is now answered in the tree rather than only in a PR body: bank is unnumbered prior art and gets no slot in the numbered table. Nothing is renumbered, and neither examples/rungs.txt nor LADDER.md's table gains an entry.

• examples/rungs.txt now explains its own omission, in its existing dense-comment style and still pure ASCII: bank predates the ladder, carries no rung number, ships its server via a plain add_executable() and never calls morph_add_rung() — so the hard configure error the file documents never fires for it — and "Adding the name here would not describe bank; it would enrol bank in every consumer above — ci.yml's ladder-tests and ladder-sanitizers, wasm-ladder.yml's build loop, coverage.sh and codecov.yml's per-rung components — which is a scope decision rather than a naming one."
• examples/LADDER.md records the same beside the table: "bank is not on that table and has no rung number. … it stays unnumbered prior art rather than taking a slot: numbering it would mean renumbering everything from rung 4 down, and the numbers here are load-bearing" — plus what bank does have (11 models, 41 actions, a ladder_bank_server, a 22-file corpus dispatching all 41) and which of this document's conventions it does not follow. The convention half of Fold examples/bank into the application ladder's conventions (scoping only, blocked on #86) #87 stays open; only the numbering half is settled.

The caveats now live in the docs

examples/bank/README.md gains a "Bank and the application ladder" section, #### Scenarios (with run_scenarios.py --rung bank --build-dir <dir>), and two prominent warnings:

• "This server authenticates nobody — do not copy it as an authentication example." It vouches for whatever principal a client asserts, because bank's AuthModel mints no token to verify. Per-row ownership is enforced, so cross-customer isolation is real and testable; credential proof is not.
• "Defects the scenario corpus pins on purpose" — #471 (resolveOwner() prefers the caller-supplied owner over the session principal; ten actions across eight models, MarkAllRead writing), the fifteen actions whose DTO validate() shadows the model's own ValidationError message, and GenerateStatement's closingBalanceMinor reporting a live balance. bank: resolveOwner() prefers the caller-supplied owner over the session principal, so 10 actions serve another customer's data #471 is also cited from the two scenario files that pin it, so a passing run reads as a record and not an endorsement.

scripts/scenario/README.md explains why bank is in RUNGS/SERVER_RUNGS while absent from rungs.txt — those lists answer different questions, and the tuples here have always selected on "ships a src/server/main.cpp" — so the next reader does not "fix" the apparent inconsistency. Its WORKFLOW_FLOORS listing is brought up to what the code holds (ledger 16, bank 22).

Gates

Check	Result
ladder_rungs.sh / ladder_rungs.sh ci-path-regex	output byte-identical to before the change
examples/rungs.txt non-ASCII bytes	0
check_rung_filters.sh	all 37 checks pass
check_spec_citations.sh	pass
scenario_coverage.py	exit 0 — bank 41/41 actions, 22/22 workflows; 114/114 corpus-wide
test_morph_scenario.py	132 tests, OK
run_scenarios.py --rung bank --twice	44/44 file runs pass against a freshly built ladder_bank_server

The remaining scripts/check_*.sh gates need a coverage/moc build directory and were not run.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!