Collapse nested application-owned sharing beneath PreparedApp

[leynos]

Summary

Once PreparedApp is the deliberate shared root, remove inner Arc layers for application-owned values that cannot escape with an independent lifetime.

This is a follow-up to #641, #642, and #643. It should land only after the prepared-application and connection-runtime boundaries make each value's lifetime explicit.

Problem

WireframeApp currently stores several values behind Arc because connections may use them concurrently:

• connection setup callback;
• connection teardown callback;
• message assembler;
• protocol implementation;
• route handlers and prepared route table.

Concurrency alone does not require each child value to own a separate reference count when one Arc<PreparedApp> already keeps the entire immutable object graph alive.

Some children may still need independent ownership:

• a protocol handle exposed through a public clone-returning accessor;
• a handler supplied as an externally shared Arc;
• an application data value intentionally returned as an owned shared handle.

The task is therefore semantic classification, not mechanical replacement.

Scope

Lifecycle callbacks

Store setup and teardown callback definitions directly or behind Box<dyn ... + Send + Sync> inside PreparedApp when they are only borrowed during one connection lifecycle.

Do not clone callback owners per connection. The connection runtime should borrow the callback through its Arc<PreparedApp> root and own only the produced state C.

Message assembler

If the assembler is immutable and only called through &self, store it directly behind Box<dyn MessageAssembler> in PreparedApp and borrow &dyn MessageAssembler from connection runtimes.

Review the public message_assembler() accessor tracked by #598. Choose and document one disposition:

• replace it with a borrowed Option<&dyn MessageAssembler> in a semver-appropriate release;
• deprecate/remove it if no supported use case exists;
• retain independent Arc ownership only if downstream code genuinely needs to clone the assembler out of the app.

Protocol definition

Coordinate with #644. Do not independently redesign protocol ownership here. The final graph should have no more protocol strong references than the accepted #644 representation requires.

Routes and handlers

Ensure the prepared route table is owned directly by PreparedApp, as required by #641.

Move handler ownership from the consumed builder into prepared services without an avoidable clone. Retain an Arc<Handler> only where the public handler value may have legitimate owners outside Wireframe or where middleware/service representation requires independent cloning.

Application data

Do not remove the per-value Arc contract from AppDataStore in this issue. SharedState<T> intentionally returns an owned handle that may outlive request extraction scope. Review map-level sharing separately only if benchmarks show repeated map cloning or contention.

Acceptance criteria

• Every nested Arc field under PreparedApp has a documented independent-lifetime justification or is replaced by direct/boxed ownership.
• Connection setup and teardown callback owners are not cloned per connection.
• Message assembler use does not require an inner Arc unless the public API explicitly promises clone-out ownership.
• The Mutation testing: untested public accessor survivors #598 accessor disposition is implemented and tested or deferred to a named breaking-release issue.
• Handler ownership moves from the consumed builder into prepared route services without an avoidable clone.
• Protocol ownership agrees with Consolidate protocol ownership and hook dispatch per connection #644 and is not duplicated here.
• AppDataStore shared-value semantics remain intact.
• No shared mutable callback or assembler state is introduced behind a mutex.
• Drop-count tests prove application-owned values are released when the final PreparedApp root drops.
• Establish runtime ownership and task-churn baselines #639 allocation benchmarks record the effect on application preparation and connection startup.

Tests

• Use drop probes around setup, teardown, assembler, protocol, and handler objects to verify expected owner counts and final release.
• Serve multiple concurrent connections and verify immutable callbacks/assembler calls remain thread-safe.
• Assert setup returns separate connection-state values while sharing only callback definition.
• Assert the assembler can serve interleaved connections without per-connection owner clones.
• Preserve all public accessor tests retained from Mutation testing: untested public accessor survivors #598.

Non-goals

• Removing legitimate shared handles from AppDataStore, PushHandle, Tokio channels, or semaphores.
• Replacing externally shared route handlers merely to achieve an Arc-free field list.
• Combining protocol and lifecycle mutable state.
• Changing callback behaviour or ordering.

Dependencies

• ADR 011 proposal ADR 011 proposal: Runtime ownership and task-lifetime boundaries #636.
• ADR 012 proposal ADR 012 proposal: Prepared application templates and connection-local runtimes #637.
• Prepared application foundation Introduce PreparedApp and one-time route/middleware preparation #641.
• Server integration Prepare the application before server readiness and share it across connection tasks #642.
• Connection runtime Extract a connection-local runtime and centralize lifecycle finalization #643.
• Protocol ownership Consolidate protocol ownership and hook dispatch per connection #644 for the protocol portion.

References

• Epic Epic: Align Tokio task boundaries with ownership boundaries #635
• Mutation testing: untested public accessor survivors #598
• Establish runtime ownership and task-churn baselines #639
• Introduce PreparedApp and one-time route/middleware preparation #641
• Prepare the application before server readiness and share it across connection tasks #642
• Extract a connection-local runtime and centralize lifecycle finalization #643
• Consolidate protocol ownership and hook dispatch per connection #644
• src/app/builder/core.rs
• src/app/builder/lifecycle.rs
• src/app/builder/protocol.rs
• src/app_data_store.rs

[coderabbitai]

🔗 Related PRs

#540 - Approve the actor and codec-driver boundary (10.1.3) [merged]
leynos/pg-embed-setup-unpriv#157 - Add verification tests for lifecycle invariants (#152) [merged]
#552 - Align roadmap footnotes with the roadmap grammar [open]
#612 - Kill mutation-testing survivors and widen scaffolding excludes (#566, #567, #569, #570, #593, #595, #598) [merged]
leynos/cuprum#232 - docs: mark #125 FD-ownership hazard resolved in roadmap 8.1 (#125) [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!