docs: add architecture migration guardrails (#3253)

This commit is contained in:
安正超
2026-06-07 14:43:55 +08:00
committed by GitHub
parent 61f0dfbc40
commit f8aa4fa221
8 changed files with 345 additions and 0 deletions
+38
View File
@@ -0,0 +1,38 @@
# Runtime And Lifecycle Contracts
Runtime and lifecycle work must preserve startup ordering, readiness behavior, and
shutdown semantics.
## Startup And Readiness
- HTTP can listen early, but normal requests must remain behind readiness gates.
- `FullReady = storage_ready && iam_ready && lock_quorum_ready`.
- Boot phases must keep the old fatal and non-fatal boundaries.
- AppContext migration keeps context-first lookup with global fallback until the
global path is proven unused.
- Notify and audit lifecycle behavior must not drift during lifecycle movement.
- IAM and KMS startup, deferred recovery, and fatal boundary behavior must not be
changed by pure movement PRs.
## Service Registry Scope
`ServiceRegistry` is only for lifecycle and shutdown ordering. It must not become a
general dependency injection container.
Allowed responsibilities:
- Register start and stop order.
- Expose read-only status snapshots.
- Coordinate graceful shutdown.
Disallowed responsibilities:
- Construct arbitrary dependencies for business logic.
- Hide globals behind a service-locator API.
- Change startup side effects while moving code.
## AppContext Foundation
Early AppContext work should split resolver files and add compatibility tests before
boot extraction or consumer migration. This keeps the migration context-first while
preserving the old global fallback path during transition.