mosaicstack/stack
1
0
Fork 0
Code Issues 58 Pull Requests Actions Packages Projects Releases 15 Wiki Activity

docs(#771): freeze database runtime role split

Browse Source
This commit is contained in:
Hermes Agent
2026-07-15 00:15:56 -05:00
parent bc5e73629e
commit d1b657d2b6
7 changed files with 296 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

27
docs/PRD.md
View File

@@ -125,6 +125,33 @@ are defined in [docs/TASKS.md](./TASKS.md) and must remain one card/one PR.
---
## KBN-101 Database Runtime/Migration Role Split (#771)
### Problem and objective
PostgreSQL Gateway/storage currently uses one `DATABASE_URL` for runtime queries and migrations. That makes the deployed application identity an owner and prevents certification that KBN immutable event, artifact, checkpoint, and evidence relations reject runtime `UPDATE`/`DELETE`. KBN-101 freezes a least-privilege runtime/migration split before KBN-100 schema work.
### Normative requirements
1. `K101-REQ-01`: `DATABASE_URL` SHALL be the non-owner PostgreSQL runtime connection and `DATABASE_MIGRATION_URL` SHALL be the migration-only owner/migrator connection. They are required respectively for runtime and explicit migration phases in `standalone`/`federated`; local PGlite is the explicit exception. A missing migration URL SHALL never fall back to the runtime URL/default/configuration URL.
2. `K101-REQ-02`: Gateway runtime/replicas SHALL not execute migrations or DDL. A serialized, advisory-locked migration phase SHALL verify the exact shipped-versus-applied schema ledger before replicas become ready; mismatch SHALL fail closed.
3. `K101-REQ-03`: PostgreSQL SHALL separate non-login platform database owner, non-login schema owner, login migrator, non-login runtime capability, and login runtime roles; runtime ownership, superuser/role-creation/schema-creation/TEMPORARY, unsafe membership, untrusted search path, missing grants, unauthenticated TLS, and immutable privilege drift SHALL fail startup/readiness closed.
4. `K101-REQ-04`: KBN immutable relations SHALL permit the real runtime role INSERT/SELECT only and deny UPDATE/DELETE; parent retention remains RESTRICT/no-cascade. Role/password/Vault creation is external platform control, never application migration/source.
5. `K101-REQ-05`: N-1 single-URL compatibility, rollout/rollback, Vault ownership/rotation/redaction, CI, installer, compose/Portainer, observability, and deployment handoffs SHALL be separately bounded one-card/one-PR work. KBN-101 planning itself SHALL not mutate production.
6. `K101-REQ-06`: KBN-100 SHALL begin only after the KBN-101 foundation role/schema-boundary certificate; it SHALL rebase on that main head, restore generated Drizzle declaration/snapshot/journal consistency, and bound procedural immutable-table grant/trigger/backfill additions to its schema slice. KBN-101 real deployed-role immutable-operation certification SHALL complete after KBN-100 creates those relations and before KBN-105.
### Acceptance criteria
1. `AC-K101-01`: Runtime/migration DTO and environment contract tests prove required modes, PGlite exception, and no migration-to-runtime fallback.
2. `AC-K101-02`: Explicit migration lock/schema-readiness tests prove no replica race or runtime auto-migration and fail closed on ledger mismatch.
3. `AC-K101-03`: Catalog tests and a real deployed-role certificate prove platform/schema-owner/migrator/runtime separation, ownership/membership/search-path/ledger-read/TEMP/default grants, authenticated TLS, and unsafe privilege denial.
4. `AC-K101-04`: Real runtime-role evidence proves INSERT/SELECT succeeds and UPDATE/DELETE fails for every frozen immutable KBN relation.
5. `AC-K101-05`: N-1 rollout/rollback, Vault/rotation/redaction, health/operator behavior, CI/deployment handoff, independent security review, and terminal-green CI evidence the foundation before KBN-100; after KBN-100, the real deployed-role immutable-operation certificate and Ultron approval release KBN-105.
**Normative implementation contract:** [`docs/native-kanban-sot/KBN-101-DB-ROLE-SPLIT.md`](./native-kanban-sot/KBN-101-DB-ROLE-SPLIT.md). `ASSUMPTION:` existing `standalone` and `federated` are all PostgreSQL production-like modes; any new PostgreSQL tier inherits these requirements until an explicit versioned amendment.
---
## Tess Interaction Agent Workstream (TESS)
### Problem and Objective