# Federated Tier Setup Guide

> **KBN-101 N-1 hold:** This page is **non-operative** until KBN-101-08 activates a
> reviewed release. It does not authorize a deployment operation, initialization artifacts,
> implicit extension/schema/migration creation, raw `CREATE`, direct database initialization, or
> a Gateway against an unverified database. The prior direct-start wording is retired; its
> regression fixture is owned by KBN-101-06.

## Activation-only sequence

The deployment control plane—not an operator shell or deployment lifecycle hook—performs this
exact sequence after activation authorization:

1. External privileged bootstrap provisions the approved database/extension prerequisites.
2. The renderer installs the generation-pinned verified-TLS materials and roles.
3. The dedicated one-shot runner executes `mosaic-db-migrator --run`.
4. The same runner executes `mosaic-db-migrator --verify`, including readiness and the
   importer-target attestation where that route is enabled.
5. Only after successful verification may Gateway reach its independent verified-TLS Gateway
   readiness gate.

No step may be reordered, skipped, replaced by a raw SQL command, or delegated to an initialization
hook.
A missing extension, schema, migration, role, secret generation, or readiness proof is a failed
control-plane precondition; it is not an instruction to start Compose, retry startup, or create
anything directly.

## N-1 status and required disposition

The current branch retains historical federation artifacts, but they are not a deployable
procedure. `docs/federation/TASKS.md` records their shipped status only. KBN-101-02 retires
runtime/init DDL; KBN-101-05 owns the renderer/deployment handoff; KBN-101-06 verifies the
finite scanner and command matrix; and KBN-101-07 owns this operator route. A path named in an
inventory, a historical-status label, or a normative requirement cannot suppress the semantic
checks above.

Until the activation certificate names an exact release, use no database startup or recovery
command from this document. For the produced importer interface, see
[the federated tier migration contract](../guides/migrate-tier.md); it is likewise non-operative
until activation.

## Federation and Step-CA reference

Federation uses PostgreSQL 17 with pgvector, Valkey, and a shared configuration across multiple
Gateway instances. Step-CA issues federation peer X.509 certificates whose custom OIDs carry a
grant and subject identity. The following facts are reference material only; provisioning and
secret delivery remain deployment-control-plane work under the activation sequence.

| OID                 | Name                     | Description           |
| ------------------- | ------------------------ | --------------------- |
| 1.3.6.1.4.1.99999.1 | `mosaic_grant_id`        | Federation grant UUID |
| 1.3.6.1.4.1.99999.2 | `mosaic_subject_user_id` | Subject user UUID     |

The internal arc `1.3.6.1.4.1.99999` is development-only. Before an externally reachable
production deployment, register an IANA Private Enterprise Number and version the assignments.
Each value is DER-encoded as an ASN.1 UTF8String containing the UUID.

The future activated Gateway requires `STEP_CA_URL`, `STEP_CA_PROVISIONER_PASSWORD`,
`STEP_CA_PROVISIONER_KEY_JSON`, `STEP_CA_ROOT_CERT_PATH`, and `BETTER_AUTH_SECRET` through the
reviewed secret mechanism. These names do not authorize shell exports, copied credential files,
or an ad hoc service start.

## Failure disposition

- A TLS, CA, SAN, role, runner, or readiness failure is a control-plane incident. Preserve only
  sanitized evidence and follow the approved rollback/repair record.
- A pgvector/extension failure is a failed external-bootstrap or runner precondition. Do not use
  direct extension SQL, init artifacts, or a startup retry as remediation.
- A port, container, or Valkey problem does not permit bypassing the activation sequence.
- Federation peer-key rotation remains deferred until its separately approved migration plan;
  do not rotate `BETTER_AUTH_SECRET` without that plan.