docs(#771): hold unimplemented runner routes

This commit is contained in:
Hermes Agent
2026-07-15 07:35:40 -05:00
parent be0ebfdc6a
commit d857463a8a
16 changed files with 110 additions and 104 deletions

View File

@@ -20,7 +20,7 @@ This command intentionally does not start PostgreSQL. Do not run a broad Compose
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.
## PostgreSQL and federated activation (future procedure)
## Held future procedure
PostgreSQL local, federated, Compose, and bare-metal production activation are held until these
artifacts land and pass their independent gates:
@@ -29,12 +29,9 @@ artifacts land and pass their independent gates:
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:
The required future order is external bootstrap → TLS/roles → `mosaic-db-migrator --run``mosaic-db-migrator --verify` → Gateway/Compose readiness.
> external bootstrap → TLS/roles → `mosaic-db-migrator --run` →
> `mosaic-db-migrator --verify` → Gateway/Compose readiness
This is a future activation specification, not an executable procedure. Do not invoke the named
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.
@@ -61,8 +58,8 @@ consumer-isolation, mode/owner, and no-mixed-generation evidence—not improvise
## 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 `mosaic-db-migrator --verify` readiness
artifact is the required PostgreSQL readiness authority after its bootstrap/TLS prerequisites pass.
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.

View File

@@ -116,11 +116,11 @@ until KBN-101-02 rejects a daemon, inherited, root, or app-local PostgreSQL DSN
tier before connection or DDL; KBN-101-05 then supplies the production renderer/Vault process-exec
or `LoadCredential` boundary.
### 4. PostgreSQL and federated activation (held)
### Held future procedure
PostgreSQL local and federated deployment are held until KBN-101-00 (external bootstrap),
KBN-101-03 (runner), and KBN-101-05 (renderer-backed deployment) land. The following is the
**future activation order, not a command sequence that is currently executable**:
**held, non-operative future activation order with no current command authority**:
external bootstrap → TLS/roles → `mosaic-db-migrator --run`
`mosaic-db-migrator --verify` → Gateway/Compose readiness.

View File

@@ -1,15 +1,16 @@
# Migrating to the Federated Tier
> **KBN-101-07 ownership:** This active documentation is a **non-operative KBN-101
> contract** until KBN-101-02/-03/-05/-06 land and KBN-101-08 activates an exact reviewed
> release. The commands below describe the produced interface only. Do not run them on the
> contract** with no current command authority until KBN-101-00, KBN-101-02, KBN-101-03, KBN-101-05, and KBN-101-06 land and
> KBN-101-08 activates an exact reviewed release. The commands below describe the produced interface only. Do not run them on the
> current branch or replace them with direct PostgreSQL, raw SQL, legacy storage migration, or
> credential-on-argv procedures.
## Required activation sequence
## Held future procedure
The deployment control plane executes, in order: external privileged bootstrap; verified TLS and
roles; `mosaic-db-migrator --run`; `mosaic-db-migrator --verify`; then Gateway readiness. The
This section is non-operative and grants no current command authority until KBN-101-00, KBN-101-03, and KBN-101-05 land.
The deployment control plane executes the complete held future procedure, in order: external bootstrap → TLS/roles → `mosaic-db-migrator --run``mosaic-db-migrator --verify` → Gateway/Compose readiness. The
runner is the only attestation producer after its verified TLS, identity, manifest, and schema
checks. A data importer is never a schema bootstrap, extension installer, repair command, or DDL
consumer.
@@ -43,15 +44,14 @@ fd. It neither logs nor exposes a URL/version/attestation/key oracle.
After activation and only after approved target preparation, the future interface is:
```bash
mosaic-db-migrator --run
mosaic-db-migrator --verify
# Deployment control plane has already completed the held runner procedure above.
mosaic storage migrate-tier --to federated \
--target-url-file /run/secrets/mosaic-migrate-target-url \
--target-attestation-file /run/mosaic-attestations/migrate-target.v1.json \
--dry-run
```
The provider-version file is fixed deployment material, not argv. This connecting dry-run consumes its nonce; before an actual copy, obtain fresh `mosaic-db-migrator --verify` and a new sealed handoff. The runner uses its migration
The provider-version file is fixed deployment material, not argv. This connecting dry-run consumes its nonce; before an actual copy, the deployment control plane must provide fresh runner verification and a new sealed handoff. The runner uses its migration
identity; the importer connects only as non-DDL `mosaic_data_importer` and only after all
pre-connect validation. After verified TLS and before DML it compares PostgreSQL system ID,
database OID, `current_user`, CA/SPKI, and manifest/schema fingerprints to the artifact.
@@ -77,7 +77,7 @@ verification.
After reviewed dry-run, obtain the required fresh verification/attestation generation, then use:
```bash
mosaic-db-migrator --verify
# Deployment control plane has supplied fresh runner verification and attestation.
mosaic storage migrate-tier --to federated \
--target-url-file /run/secrets/mosaic-migrate-target-url \
--target-attestation-file /run/mosaic-attestations/migrate-target.v1.json \