docs: document module database access
Add ADR 0016 recording the accepted module database access design (ModuleDatabase, the frozen ModuleRuntimeServices boundary, one pool/one facade/one services-object identity, explicit migrations, and the trust model), with narrow cross-reference corrections to ADR 0006 and ADR 0015 where their original text is now inaccurate. Sweep docs/development/api.md, docs/development/authorization.md, docs/module-development/README.md, docs/development/testing.md, and docs/development/identity.md for the new database boundary and remaining Phase 4C staleness; correct the stale "Phase 4C is next" roadmap paragraph in platform-architecture.md and the matching gap in README's current-status narrative. Extend the module template with a permissioned GET /records route reading through context.services.database, using the canonical createModuleTable helper, with matching template tests.
This commit is contained in:
@@ -97,6 +97,23 @@ database failure and asserts, against actual `console.error`/`warn`/`log` output
|
||||
Auth's own internal error logging — configured explicitly in `core/src/identity/runtime.ts` — never
|
||||
emits a raw exception, SQL, connection detail, or the rejected request's origin.
|
||||
|
||||
A third dedicated suite (`apps/api/tests/module-database.integration.ts`, included in the same
|
||||
`pnpm test:migrations:integration` run) proves `context.services.database` against a real,
|
||||
installed test module (`core/tests/fixtures/module-database-integration/db-facade/` — never the
|
||||
repository's live `modules/` directory, and invisible to normal discovery/Doctor/`modules:validate`
|
||||
unless a test explicitly points discovery at it): the module's own table does not exist until its
|
||||
migration is explicitly applied, and constructing the pool or facade never creates it; `start`,
|
||||
`stop`, and an authorized HTTP handler all receive the identical `ModuleRuntimeServices` object,
|
||||
proven by reference equality; a real authorized mutation persists and a later read observes it,
|
||||
gated by the same permission/trusted-Origin enforcement every other module route uses; a real
|
||||
committed transaction persists and a real rollback (a deliberate unique-constraint violation)
|
||||
leaves no partial mutation; a module deliberately catching a real PostgreSQL failure returns its
|
||||
own response untouched, while an uncaught one sanitizes to the existing
|
||||
`MODULE_HANDLER_FAILED` boundary with no leaked SQL, error text, or path; and a `stop` hook's write
|
||||
completes and is independently verifiable, through the harness's own administrative connection —
|
||||
never the API's own pool — before that pool closes. See
|
||||
[ADR 0016](../architecture/decisions/0016-module-database-access.md).
|
||||
|
||||
CI runs the same command in the dedicated `migration-smoke` job. After this change is merged, add
|
||||
the following pull-request status context to `main` branch protection:
|
||||
|
||||
|
||||
Reference in New Issue
Block a user