ADR 0005: Explicit Generated Lifecycle Coordination

Status: Accepted

Decision

Generated applications use the small public lifecycle.Coordinator for generic state transitions and ordered callback execution. Generated code remains responsible for concrete provider calls, concrete receiver method calls, stable provider IDs, and dependency order.

The coordinator accepts only explicit typed callbacks:

• construction cleanups are registered immediately after provider success;
• start hooks run serially in dependency-first generated order;
• a start failure stops only previously successful hooks in reverse order;
• construction cleanups always run in reverse construction order;
• normal stop reverses successful starts, then reverses cleanups;
• every rollback/stop callback is attempted and failures are deterministically joined while preserving errors.Is and errors.As;
• stop is idempotent and concurrent stop callers wait or honor their own cancellation;
• concurrent start/stop and other invalid state transitions return a typed error;
• caller-owned contexts are passed unchanged to callbacks.

Run accepts a run context and a caller-supplied ContextFactory. After successful startup it waits for run-context cancellation, invokes the factory to obtain a fresh shutdown context and release function, stops, and releases that context. Run-context cancellation is the normal shutdown signal and is not returned as an application error.

Generated hooks and cleanups carry optional owning-module import paths. Observers register while the coordinator is constructed and synchronously receive begin/end events for start, stop, and cleanup callbacks. Events contain module ID, stable component/provider ID, operation, phase, and callback error. Observers have no error return and must not panic or block indefinitely.

The observable states are constructed, starting, ready, stopping, stopped, and failed. Construction abort and startup rollback end in failed; normal stop ends in stopped.

Boundaries

The coordinator does not:

• discover providers or hooks;
• resolve types or dependency order;
• scan packages or use reflection;
• own process signals, timeouts, logging, or exit behavior;
• own a tracer, meter, exporter, or global observer registry;
• create background, timeout, or signal contexts;
• recover panics;
• store a global registry or application singleton.

These boundaries keep generated application behavior ordinary, inspectable Go while centralizing the concurrency-sensitive state machine.