No framework seam for a model's own execute() to post background work and later update its own state

[Yaraslaut]

Summary

No framework-level seam exists for a model's own execute() to post work to a background executor and later update its own persisted state. Every existing "background job" pattern in the ladder examples (bookmarks' metadata-fetch worker) lives at the App/Bridge/RemoteServer layer and re-enters the model as a fresh, ordinary, fully-authorized client dispatch (through a minted service-principal token) — never something a plain model instance with no App/Bridge/RemoteServer around it can do.

Discovered while implementing rung 5 (ledger)'s SubmitReport/GetReportStatus submit→poll job (design spec called for "the job runs off the model's own strand ... following the ladder-wide 'background jobs' pattern from LADDER.md's ... internal-client-with-service-principal seam that rung 2 establishes" — this claim turned out not to be accurate; see below).

Evidence

• morph::exec::IExecutor/ThreadPoolExecutor (include/morph/core/executor.hpp) has zero usages anywhere inside a model's own execute() across examples/bank, examples/bookmarks, examples/pastebin, examples/polls. Every real usage sits at the App/server layer (examples/bank/include/bank/app/app.hpp, examples/bookmarks/include/bookmarks/app/app.hpp, examples/bank/src/cli/main.cpp).
• There is no process-wide singleton executor analogous to morph::journal::setActionLog's own install pattern — ThreadPoolExecutor has no set/get global accessor.
• Bookmarks' real background job (examples/bookmarks/src/app/app.cpp, App::fetchMetadataOnce()) reads rows needing metadata via a raw SqlStatement, then for each dispatches a new client call through morph::bridge::BridgeHandler<BookmarkModel> — which itself posts through the worker pool and re-enters BookmarkModel::execute(const RecordMetadata&) as an ordinary, fully-authorized dispatch with a minted auth::kMetadataFetcherPrincipal service-principal token. BookmarkModel::execute(const RecordMetadata&) itself is synchronous, ordinary model code — it never touches an executor.
• App::fetchMetadataOnce() is driven by a QTimer, i.e. triggered from the Qt event loop outside the model entirely — not something a headless/non-Qt model consumer (or a model with no App wrapper at all, like ledger::LedgerModel) could reach.

Impact

Any future rung/model that needs a genuine "submit now, compute later, poll for status" job (report generation, batch export, long-running aggregation) has no sanctioned framework mechanism to reach for, and must invent its own per-model workaround — exactly what ledger::LedgerModel did (a private std::shared_ptr<morph::exec::IExecutor> member, posting directly from execute(SubmitReport)). This works, but:

• it duplicates a pattern every future model would reinvent slightly differently,
• it has no defined service-principal/session-propagation story for the worker thread (the ledger implementation avoided this by never touching the calling thread's session — the worker re-derives everything it needs from plain copied values — but a job that genuinely needs to act as a principal on the worker thread has no guidance),
• it cannot be tested with a deferred/deterministic executor double the way client-callback executors can (morph::ladder::testkit::DeterministicExecutor/StepExecutor exist for controlling delivery order of continuations, but no test anywhere substitutes a double for the worker side of an async job — every real async-job test genuinely spins a real thread pool and polls with a bounded, wall-clock-deadline retry loop).

Suggested direction

A first-class "background task from inside a model" primitive, with:

• a defined way for a model to reach a shared (or model-owned) executor without inventing its own member each time,
• a documented service-principal/session-propagation convention for code that runs on the posted task and needs to act with authority (mint a token, or explicitly document "the worker re-derives its own state and never inherits session context"),
• a deferred/synchronous test double for the worker side specifically, so async-job unit tests don't need to spin real threads with real sleeps to get coverage.

Reference

Filed from LASTRADA-Software/morph, branch ladder-ledger-rung5 (not yet merged), as docs/findings/003-no-model-level-background-job-seam.md. See that file for the same summary in the ladder's own findings-pipeline format (examples/FINDINGS.md).

[Yaraslaut]

The title asks for something the strand guarantee forbids

Re-reading this against docs/spec/concurrency_and_lifetimes.md, the framing "post background work and later update its own state" is in direct tension with morph's headline model-side contract:

A model author writes single-threaded code. For a given ModelId, the strand guarantees execute() is never re-entered concurrently, so per-model state needs no locking.

Work running on a background executor is, by definition, off that strand. If it wrote to model state it would break exactly the property that lets every model in this repository be written without a mutex. So "update its own state from the background task" is not a gap to fill — it is a thing that must not be built.

What the motivating implementation actually does

LedgerModel::execute(const SubmitReport&) — the case this issue was filed from — is explicit that it does not do this:

Only plain values cross the thread boundary: the job's own integer id and the ledger id, both copied. Nothing from this stack frame — not mapper, not ctx (a thread-local session pointer), not action — is captured: execute() returns and tears all of that down long before the worker runs.

The worker re-derives everything from copied ids and persists through its own DataMapper. The model is never touched. The single-threaded guarantee holds, and the code is correct as written.

So what is the real gap?

Much narrower than the title suggests. Stripping out the part that cannot exist, what remains is the issue's own three bullets:

1. A defined place to get an executor, so each model does not invent a private member. This is real but modest — it is "where does an executor come from", not a new concurrency capability.
2. A documented session-propagation convention for the posted task.
3. A worker-side test double, so async-job tests stop spinning real threads and polling a wall-clock deadline.

That is a plumbing-and-conventions gap, not a threading-model gap.

And the way a model does update its own state later

Dispatch another action. That re-enters through the normal path and therefore lands back on the model's strand, where mutating state is safe. This issue describes bookmarks' metadata fetcher doing exactly that — re-entering as an ordinary client dispatch with a minted service-principal token — and calls it a workaround. On this reading it is not a workaround; it is the architecture working as designed. The background task's job is to compute and to persist, and if model state must change, the way to change it is an action.

Suggested rescope

Retitle to something like "No defined way for a model's execute() to reach a background executor", and replace the "update its own state" language with the constraint: a background task must not touch the model; it copies the values it needs and persists through its own mapper. Otherwise the next reader implements a data race and believes they are closing this issue.

#154 (the draft primitive) already encodes that constraint — its postBackground doc says "The task must not capture the model. It runs off the model's strand, so anything it touches must be owned by the task itself" — but the PR inherits this issue's framing in its title, so it is worth fixing in both places. Note also that nothing enforces the constraint; it is documentation only.

[Yaraslaut]

Closing: models should not know about the framework

The decisive objection is architectural rather than about threading. A model implements actions; morph handles communication between the GUI and the backend and executes those actions. A model reaching into the framework to schedule work inverts that — and postBackground would have made models framework-aware in a new and deeper way, importing a morph header to fetch a process-global executor.

That is a worse position than the one this issue set out to improve, so the issue is withdrawn rather than rescoped. #154, which implemented the primitive, is closed with it.

The layering that stays:

• A model implements actions. It is single-threaded per ModelId by the strand guarantee, needs no locking, and needs no executor.
• The App / server layer knows about morph, owns any thread pools, and drives background work.
• A model updates its own state later by having an action dispatched at it — which re-enters on its strand, where mutation is safe. bookmarks' metadata fetcher does exactly this, and this issue was wrong to call it a workaround. It is the architecture working.

The consequence worth acting on

ledger::LedgerModel currently deviates: it owns

std::shared_ptr<::morph::exec::IExecutor> _reportExecutor =
    std::make_shared<::morph::exec::ThreadPoolExecutor>(1);

and is the only ladder model that includes <morph/core/executor.hpp> — kanban::BoardModel does not. Under this principle SubmitReport's aggregation belongs at the App layer, with the model doing what every other model does: record the job row, return the id, and let a later action carry the result back.

That is a real follow-up, not a hypothetical, but it is a change to rung 5 rather than to the framework — worth its own issue if it is wanted.

What is genuinely lost

One thing, and it survives the architectural decision: there is still no worker-side test double. DeterministicExecutor and StepExecutor control the delivery order of continuations; nothing substitutes for the worker side of an async job, so every async-job test spins a real thread pool and polls against a wall-clock deadline. If background jobs live at the App layer, that gap moves to the testkit rather than disappearing. Worth filing separately if async-job tests keep costing wall-clock time.