core: HasLifetime and lifetime-bound Completion overloads (stage 1, draft)

[Yaraslaut]

Draft — stage 1 of #138 only. The primitive and its tests, no caller migration. Opened as a draft per your instruction that library features come to you unfinished.

What's here

• morph::async::HasLifetime (include/morph/core/lifetime.hpp) — opt-in base owning a lifetime token.
• Completion<T>::then(Owner*, Handler) / onError(Owner*, Handler) — constrained on a LifetimeBound concept, so a receiver that hasn't opted in is a compile error rather than a silent fall-through to the unguarded overload.
• thenDetached / onErrorDetached — exact aliases of the unguarded overloads, so a genuinely detached callback says so at the call site and the unguarded spelling stays greppable.
• Tests, and a new section in docs/spec/core/completion.md.

completion.then(this, [this](GetBoardResult r) { ... });  // runs only while `this` lives
completion.thenDetached([](GetBoardResult r) { ... });    // deliberately unguarded

Design choices, and why not the alternatives

enable_shared_from_this would force heap allocation and shared ownership on every receiver — stack-allocated presenters and QML-owned bridges can't comply, and #137's BoardBridge is a stack object in the failing test. QPointer would force Qt into morph core, and Bridge/EventPoller are not QObjects. A returned cancellation handle would have to be stored and reset by the caller: the same "remember to do it" failure mode the guard exists to remove.

Copy and move give the new object its own token — a token is an identity, not a value. Sharing one would let a copy's destruction silence the original's callbacks.

On the guarantee's boundary

The spec section states it plainly: this closes the ordinary "destroyed before the reply arrived" hole. A receiver destroyed on a different thread from its callback executor still needs external synchronisation — the token check is not a substitute for one. Worth your eye, since it's the kind of thing an API like this can be assumed to promise and doesn't.

Verification

Tests hold their call counters in shared_ptrs that outlive the receiver, so "the callback body did not run" is directly observable rather than resting on undefined behaviour being detected. My first draft asserted only REQUIRE_NOTHROW, which would have passed with no guard at all. Mutation-verified: disabling the expiry check fails 3 assertions.

I tried to confirm under ASan as well, but the ASan-instrumented morph_tests binary hangs on macOS here, unrelated to this change. The counter-based assertions don't depend on a sanitizer, so the evidence stands without it — but CI's ASan job is worth watching.

What's left (stage 2+, yours)

• Migrate ~25 call sites; the 5 hand-rolled _liveness tokens collapse into this.
• Bridge's own guards become uses of the primitive rather than a private reimplementation.
• docs/spec/core/bridge.md and docs/spec/VERSIONING.md.
• Decide whether the unguarded then(std::function) gets deprecated or kept.

[codecov]

Codecov Report

❌ Patch coverage is 72.72727% with 6 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
include/morph/core/completion.hpp	80.00%	2 Missing and 1 partial ⚠️
include/morph/core/lifetime.hpp	57.14%	3 Missing ⚠️

📢 Thoughts on this report? Let us know!

[Yaraslaut]

Closed in favour of a generalised design; see the rewritten #138.

Two problems with what this PR shipped:

• It used inheritance. HasLifetime as a base class is a large demand on every consumer of BridgeHandler — it constrains the type's hierarchy for what should be a plain implementation detail, and a type that already has a base (or is a QObject, or is an aggregate) pays for it.
• It only covered liveness. "The receiver was destroyed" is one reason to drop a callback; "the GUI decided this result is no longer wanted" is another, and is not expressible at all today.

The replacement is a separate token type held as a data member, which the handler captures and checks, and which also carries an explicit stop mechanism. Design is in #138.