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

docs(kbn): freeze KBN-101 database role split contract (#774)
All checks were successful
ci/woodpecker/push/publish Pipeline was successful
Details
ci/woodpecker/push/ci Pipeline was successful
Details

Browse Source
This commit was merged in pull request #774.
This commit is contained in:
jason.woltje
2026-07-15 13:34:29 +00:00
parent bc5e73629e
commit c593a15ef8
23 changed files with 1058 additions and 974 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
docs/fleet/backlog-conventions.md
View File

@@ -14,18 +14,17 @@ and surfaced as `mosaic fleet backlog <sub> --json`.
The backlog uses the existing Mosaic storage layer; there is **no** new database
engine (no sqlite, no raw client).
| Condition | Tier | Data location |
| ------------------------------ | -------------------- | -------------------------------- |
| `DATABASE_URL` set | Full server Postgres | the configured database |
| `PGLITE_DATA_DIR` set (no URL) | Embedded PGlite | that directory |
| neither (default) | Embedded PGlite | `~/.config/mosaic/fleet/backlog` |
| Condition | Tier | Data location |
| ---------------------------------- | -------------------- | ---------------------------------------------------------------- |
| `DATABASE_URL` injected at runtime | Full server Postgres | the verified runtime database; it never authorizes migration/DDL |
| `PGLITE_DATA_DIR` set (no URL) | Embedded PGlite | that directory |
| neither (default) | Embedded PGlite | `~/.config/mosaic/fleet/backlog` |
PGlite is real Postgres semantics in-process — including the row locks the atomic
claim relies on — so the **same code** runs on a laptop (embedded, single-host
default) and on a full Postgres deployment. Switching tiers is config-only.
The schema (`backlog` table) is created automatically on first CLI use:
`runMigrations()` for Postgres, `runPgliteMigrations()` for embedded PGlite.
For embedded PGlite only, the local backlog routine may prepare its local schema on first use. **Current operator behavior is PGlite-only.** The PostgreSQL path is held until KBN-101 activation; no current PostgreSQL CLI route, runner, or first-use migration is available or authorized. A future activated PostgreSQL runtime may connect only after its separately certified readiness gate.
### Update safety