feat: Standardize module lifecycle and cleanup

Co-authored-by: hongwei.xi <hongwei.xi@myob.com>

Author: cursoragent

openspec/changes/standardize-module-lifecycle-cleanup/proposal.md

@@ -0,0 +1,16 @@
+# Change: Standardize module lifecycle and cleanup
+
+## Why
+- Module lifecycle lacks a clear Loaded/Active/Error state machine; initialization can run without a bound host, causing inconsistent state.
+- Detail pages are eagerly loaded; this increases startup cost and risks failures before the user navigates.
+- Unload/disable paths are inconsistent, leaving menus/navigation/messages and scoped resources registered, causing leaks and unstable hot-reload.
+
+## What Changes
+- Define a runtime module state machine with explicit transitions: Loaded (metadata/menus ready, host not bound), Active (initialized with host), Error (failed init or detail load) plus retry rules.
+- Default to menu-only load; lazily load and render module detail on first navigation with async flow and cancellation/timeout handling.
+- Gate initialization on host binding; when a host binds, batch-initialize eligible modules and persist state transitions.
+- Standardize unload/disable cleanup: invoke module deregistration hooks (menu/navigation/message), dispose scoped providers and caches, and unload the module AssemblyLoadContext.
+
+## Impact
+- Affected specs: runtime
+- Affected code: module runtime loader/state manager, navigation/detail loader, host bind/unbind flow, module cleanup pipeline

openspec/changes/standardize-module-lifecycle-cleanup/specs/runtime/spec.md

@@ -0,0 +1,42 @@
+## ADDED Requirements
+
+### Requirement: Standardized module lifecycle states and lazy activation
+Runtime modules SHALL follow a Loaded/Active/Error state machine, gate initialization on host binding, and lazily activate detail views.
+
+#### Scenario: Host not bound keeps module Loaded
+- **WHEN** a module is discovered/installed and the host is not yet bound
+- **THEN** the runtime loads manifest/menu metadata only
+- **AND** marks the module state as `Loaded`
+- **AND** defers module initialization, services, and detail view creation.
+
+#### Scenario: Host binding activates eligible modules
+- **WHEN** the host binds
+- **THEN** the runtime initializes all Ready+enabled modules using the lifecycle pipeline
+- **AND** updates their state to `Active` upon success
+- **AND** records diagnostics for any module that fails to activate.
+
+#### Scenario: Lazy detail load on first navigation
+- **WHEN** a user first navigates to a module’s detail view
+- **THEN** the runtime asynchronously loads and renders the module detail/page
+- **AND** supports cancellation/timeout for the detail load
+- **AND** surfaces errors and sets the module state to `Error` if detail load fails.
+
+#### Scenario: Initialization failure transitions to Error
+- **WHEN** module initialization or detail load fails
+- **THEN** the module state becomes `Error`
+- **AND** diagnostics are recorded for recovery
+- **AND** the module is not reused until a retry/repair is attempted.
+
+### Requirement: Unified unload and cleanup pipeline
+Runtime modules MUST expose and execute a standardized cleanup path on unload/disable to remove registrations and release resources.
+
+#### Scenario: Unload cleans registrations and resources
+- **WHEN** a non-system module is unloaded or disabled
+- **THEN** the runtime invokes module-provided deregistration hooks for menus/navigation/messages/subscriptions
+- **AND** disposes the module-scoped ServiceProvider, caches, and other scoped resources
+- **AND** removes the module’s UI/navigation projections from the host
+- **AND** unloads the module AssemblyLoadContext and returns the module to the `Loaded` state (metadata only).
+
+#### Scenario: System modules protected from unload
+- **WHEN** an unload is requested for a system module
+- **THEN** the runtime rejects the request with a clear diagnostic.

openspec/changes/standardize-module-lifecycle-cleanup/tasks.md

@@ -0,0 +1,6 @@
+## 1. Implementation
+- [ ] 1.1 Define Loaded/Active/Error state machine with diagnostics and persistence
+- [ ] 1.2 Add lazy detail load/render flow (async, cancel/timeout, error to state)
+- [ ] 1.3 Gate initialization on host binding; batch activate eligible modules
+- [ ] 1.4 Implement standardized unload cleanup (menus/navigation/messages, scoped resources, ALC)
+- [ ] 1.5 Add tests/telemetry for state transitions, lazy load, and cleanup paths