refactor: harden application composition

[MartinKalema]

What changed

• Validate the complete etcd configuration before creating database, Kafka, Redis, Elasticsearch, or SendGrid clients.
• Give the API, workflow worker, notification worker, search projection, reservation reaper, CLI, and maintenance jobs separate composition roots and database connection limits.
• Close process-owned resources in reverse order, including when startup only completes partway.
• Make Kafka consumer shutdown safe when a signal and normal cleanup happen together.
• Replace the global circuit-breaker registry with one registry per process.
• Report only enabled API-owned circuit breakers from the API health endpoint.
• Replace ambiguous core/wrapper command names with internal operations and public capabilities such as add_book.
• Replace repeated cache strings with typed cache namespaces and explicit post-command invalidation policies.
• Update environment examples, Docker Compose limits, and deployment documentation.

Why

The old container accepted an arbitrary configuration dictionary. Missing values failed later with unclear errors, while some clients could be created with invalid values.

Resource cleanup was repeated across entry points, so a partial startup failure could leave clients open. Every process also received the same large database pool, which could exceed PostgreSQL capacity when replicas were added.

The API exposed a SendGrid circuit breaker that belonged to another process, so that health result did not describe real notification delivery. Command wiring was also difficult to read because both the business operation and its cache decorator were called handlers.

Impact

The public HTTP API is unchanged.

Database pool environment variables are now role-specific, for example DATABASE_API_POOL_SIZE and DATABASE_WORKFLOW_POOL_SIZE. The config seeder validates the new format and removes obsolete etcd keys.

Configuration is an immutable startup snapshot. Changing etcd configuration requires a controlled process restart.

Checks completed

• 314 Python tests passed locally
• mypy passed across 174 source files
• Python compilation passed
• Docker Compose configuration validation passed
• Git diff whitespace validation passed

GitHub Actions will run the full suite against a fresh migrated PostgreSQL database before merge.