veronica
f0d2dd9920
Applies the document contract from
docs/plans/2026-08-20_stack-docs-flatten-and-alignment.md section 3, partially:
`kind` and `status` only. `parent` is deliberately held until the flatten in
section 4 lands, so that 127 documents do not have to be re-pointed by hand
when docs/fleet/NORTH_STAR.yaml moves to docs/NORTH_STAR.yaml.
Scope, measured on origin/next at 63069149:
127 live docs = all *.md under docs/ minus docs/archive/ minus docs/_old_structure/
104 stamped here
19 held operator judgement (plan section 9), worklist in the same PR
3 held the SUPERSEDED TASKS.md stamps, which cite the moving path
1 untouched docs/fleet/FLEET-DOCTRINE.md, already stamped in W1
Kinds applied: 54 guide, 34 record, 9 spec, 6 tracking, 1 projection.
Every row carries a confidence and a one-line rationale in the worklist.
Two collisions with the existing state, both flagged rather than resolved:
1. docs/README.md:150-160 already documents a front-matter convention
(title/type/audience/status/source_of_truth) with its own allowed values.
It is applied to 4 of 127 files. Its `status` vocabulary is
current|draft|deprecated|historical; the new contract's is active|superseded-by.
The key collides. This commit lets the new contract win and rewrites
`status: current` to `status: active` on those 4 files, keeping their other
legacy keys untouched. No code reads any of them: `git grep source_of_truth`
outside docs/ returns nothing. docs/README.md still prescribes the old
convention and is an operator row, so it is not edited here.
2. Two of the plan's 20 operator rows are YAML files, not markdown
(docs/fleet/examples/roster-v2.yaml, docs/openapi-tess.yaml), and the
contract's front-matter form has no defined meaning for a .yaml document.
That gap also applies to docs/fleet/NORTH_STAR.yaml, the source of truth
itself. Raised in the worklist.
A third row from the plan, docs/fleet/north-star.md, no longer exists: W1
renamed it to docs/fleet/FLEET-DOCTRINE.md.
Verification: 104/104 parse with the expected kind and status in front matter;
the check was shown to reject a wrong kind before it was trusted. The diff
removes 4 lines total, all of them `status: current`.
73 lines
4.6 KiB
Markdown
73 lines
4.6 KiB
Markdown
---
|
||
kind: guide
|
||
status: active
|
||
---
|
||
|
||
# Deployment Guide
|
||
|
||
> **Status: non-operative for PostgreSQL, federated, and bare-metal production.** The checked-in
|
||
> Compose PostgreSQL service mounts legacy initialization SQL and the KBN-101 bootstrap, runner,
|
||
> secret-renderer, and process-exec interfaces do not exist yet. This page does not authorize a
|
||
> production deployment, database initialization, manual DDL, secret provisioning, or service
|
||
> activation.
|
||
|
||
## Current safe local route
|
||
|
||
Use PGlite only for current in-process data-layer work; it requires no PostgreSQL. A Gateway/Web
|
||
local process is held because its unguarded dotenv loader can inherit a daemon PostgreSQL DSN and
|
||
reach runtime DDL. If a local queue service is useful, start only Valkey:
|
||
|
||
```bash
|
||
docker compose up -d valkey
|
||
```
|
||
|
||
This command intentionally does not start PostgreSQL. Do not run a broad Compose start, use its
|
||
PostgreSQL initialization mount, infer that current Compose is a production/federated route, or
|
||
start Gateway/Web until KBN-101-02 supplies fail-closed local-tier/DSN isolation.
|
||
|
||
## Held future procedure
|
||
|
||
PostgreSQL local, federated, Compose, and bare-metal production activation are held until these
|
||
artifacts land and pass their independent gates:
|
||
|
||
1. **KBN-101-00** external privileged bootstrap artifact;
|
||
2. **KBN-101-03** sole `mosaic-db-migrator` runner and verified-readiness artifact; and
|
||
3. **KBN-101-05** Vault/secret-renderer-backed deployment and consumer-isolation artifact.
|
||
|
||
The required future order is external bootstrap → TLS/roles → `mosaic-db-migrator --run` → `mosaic-db-migrator --verify` → Gateway/Compose readiness.
|
||
|
||
This is a held, non-operative future activation specification with no current command authority. Do not invoke the named
|
||
runner, start PostgreSQL, or substitute a Compose/init/manual-SQL route until the owned artifacts
|
||
are implemented and reviewed.
|
||
|
||
## Future production secret and unit boundary (schematic only)
|
||
|
||
No current bare-metal production unit or command is published. KBN-101-05 must supply a reviewed,
|
||
generation-pinned Vault renderer and a process-exec or systemd `LoadCredential` interface before
|
||
production units can exist. The interface must preserve these exact consumer boundaries:
|
||
|
||
| Consumer | May receive | Must never receive |
|
||
| ----------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
|
||
| Gateway/runtime | Its own runtime URL and DB client CA at process exec | Migrator URL, importer URL/version, attestation material, signing key, PostgreSQL private key |
|
||
| One-shot migrator | Its own migration URL, DB client CA, and runner-only signing capability | Runtime URL, importer consumer copy, Gateway/private PostgreSQL keys |
|
||
| Data importer | Its own immutable URL/version copies, importer CA, pinned public key, and sealed attestation | Runtime/migrator URLs, signing key, shared writable mount |
|
||
| PostgreSQL | Its own server certificate/key and only its approved server material | Application, migrator, importer, or Gateway secrets |
|
||
|
||
A future unit specification is non-executable until KBN-101-05 supplies it. It must obtain
|
||
credentials through the renderer’s Vault generation and process-exec/`LoadCredential` boundary;
|
||
it must not place credentials in a production environment file, a monorepo auto-load path, a shell
|
||
export, command arguments, logs, or a manual secret-activation lifecycle instruction. Rotation and
|
||
process replacement semantics must be delivered by the reviewed renderer/interface with generation,
|
||
consumer-isolation, mode/owner, and no-mixed-generation evidence—not improvised in this guide.
|
||
|
||
## Readiness and troubleshooting status
|
||
|
||
Until the future procedure is implemented, do not diagnose PostgreSQL with ad hoc SQL, connection
|
||
strings, or initialization scripts. The future sanitized runner-verification readiness artifact is
|
||
the required PostgreSQL readiness authority after its bootstrap/TLS prerequisites pass.
|
||
For local PGlite development, diagnose application behavior without introducing a PostgreSQL
|
||
connection.
|
||
|
||
Non-database local services may be inspected with their ordinary local health/log tools. Those
|
||
checks do not certify PostgreSQL, federated deployment, or production readiness.
|