transcription/docs/adr/ADR-0001-lifespan-owned-runtime-resources.md

ADR-0001: Lifespan-owned runtime resources

• Status: accepted
• Date: 2026-06-25

Context

MVP initialized core runtime resources (database engine and worker dependencies) through module-level globals and startup side effects. REQ-7 requires lifespan-owned runtime resources with explicit ownership and cleanup.

Decision

Adopt lifespan-owned runtime resource initialization in transcription.app:

1. Initialize database runtime during app lifespan startup.
2. Store runtime handles on app.state.
3. Pass runtime-owned dependencies (engine) to worker startup.
4. Dispose runtime resources explicitly during lifespan shutdown.

Consequences

Positive

• Explicit startup and shutdown ownership.
• Predictable cleanup ordering.
• Reduced hidden global side effects.

Tradeoffs

• Minor wiring complexity in app startup.
• Some call-sites still support fallback lazy initialization for compatibility.

Alternatives Considered

1. Keep module-level global ownership
   • Rejected: conflicts with REQ-7 and increases ambiguity.
2. Introduce full async DB stack immediately
   • Rejected for Step 1: too broad for architecture-consolidation scope.