Status: Accepted Date: 2026-08-11 Deciders: Bernd Worsch, Claude

## Context

NetKingdom's runtime services are deployed today outside the Railiance reef/rail/`rapp` model. `tenant-engine` and `user-engine` run on the coulomb substrate with digest-pinned images (`forgejo.coulomb.social/coulomb/{tenant,user}-engine@sha256:…`), but their Kubernetes manifests live in this repo at `sso-mfa/k8s/<service>/runtime.yaml` — a canon repo holding runtime YAML — applied imperatively, with `verify-t0*.sh` scripts as verification. Neither service declares `railiance/app.toml`, appears in `reef-railiance/bindings/rapps.yaml`, or is reconciled by a GitOps controller.

The decision to bring NetKingdom under Railiance governance forces two questions this ADR settles.

Packaging granularity. `railiance-master/docs/repository-axes.md` maps `rapp-*` to "one Railiance-managed workload" and states that a `rapp` "does not replace the responsibility repo that owns the broader domain. It is explicitly about managed wrapping, not ownership." Precedent exists in two shapes: `rapp-qonto` (`ownership_repo: qonto-assistant`, one workload, thin package repo pointing back at the domain repo) and `rapp-postgres` (`ownership_repo: railiance-platform`, one workload with a `consumers:` list and a `consumer_contract`). The open question was whether NetKingdom's engines are one workload or several.

Relational storage. The engines have diverged. `user-engine` already runs CloudNative PG (`kind: Cluster` in its own namespace) with NetworkPolicies and a `migrations/` surface. `tenant-engine` runs SQLite on a 1 Gi RWO PVC, chosen in TEN-WP-0004 for expedience. `railiance-platform` (S3) declares CloudNative PG the canonical database operator, and `rapp-postgres` packages it with a `database-per-consumer` boundary unit and OpenBao dynamic credentials. Separately, `rail-kubernetes`'s wave-1 contract explicitly states the rail must not assume "a generic persistent-storage contract" — so a per-workload PVC is unsupported by the rail regardless of which database is chosen.

TEN-WP-0005 was drafted against PostgreSQL and implemented against SQLite, because T05 must roll out against the runtime that exists. That workplan's `TenantStore` Protocol was kept as an explicit seam for this decision.

## Decision

### 1. Separate `rapp-*` repos per engine

Each deployed NetKingdom engine gets its own managed workload package repo:

    rapp-tenant-engine    ownership_repo: tenant-engine
    rapp-user-engine      ownership_repo: user-engine

Following `rapp-qonto`'s shape: the `rapp` owns Railiance packaging, rail compatibility, workload-specific smoke/health checks, rollout and rollback expectations, secret references, and dependency declarations. The engine repo retains domain ownership; `net-kingdom` retains canon.

This follows the one-workload rule rather than working around it. The engines are already independent on every axis a `rapp` declaration must state: separate namespaces, separate image digests, separate release cadence, and (until decision 2 lands) different storage. A single `rapp-netkingdom` would have to declare one `workload_identity`, one `rollout_contract`, and one `rollback_contract` across services that genuinely differ.

The decisive property is independent rollback: rolling back a bad `tenant-engine` revision must not force a `user-engine` revision change. A single rapp would make that either impossible or fictional.

Rollout ordering between the engines is a declared constraint between rapps, not a reason to merge them: `tenant-engine` before `user-engine`, following the dependency direction.

### 2. `secrets-engine` is not packaged as a `rapp`

`secrets-engine` has no deployed workload — no Containerfile, no Makefile, no Kubernetes manifests. It is a catalog/policy/workflow layer over OpenBao, whose packaging already belongs to `rapp-openbao` with custody and lane policy in `railiance-platform`.

A `rapp` wraps a workload; `secrets-engine` has none to wrap. Revisit only if it becomes a runtime service, at which point this decision reopens for that repo alone and not for the packaging model.

### 3. CloudNative PG is the default relational platform for production

Production NetKingdom services requiring relational storage use CloudNative PG via `rapp-postgres`, consuming the `database-per-consumer` boundary unit and the `openbao-dynamic-database-credential` lane, with tenant-keying per `business-app-service-contract_v0.1` section 1.3.

Per-workload SQLite-on-a-PVC is not a production pattern. It remains acceptable for local development and tests.

`tenant-engine` migrates from SQLite to cnpg. Its `TenantStore` Protocol makes this a backend swap behind an existing seam rather than a rewrite; the lifecycle semantics proven in TEN-WP-0005 (atomic compare-and-swap, durable idempotency receipts, forward-only migration) are the conformance bar the PostgreSQL backend must meet, and its store-conformance suite is already parametrised across backends to enforce exactly that.

## Consequences

- Two new `rapp-*` repos to create, each requiring a `declarations/rapp.yaml`, a binding in `reef-railiance/bindings/rapps.yaml`, and its own readiness evidence progression (`declared` → `installed` → `verified` → `production-approved`).
- Per-binding evidence multiplies, but per-reef evidence does not — the `reef-production-readiness-contract` puts substrate, ingress, storage, network, and backup evidence on the reef, once. What multiplies is the critical-workload gate (threat model, negative authorization tests, rollback rules, residual-risk owner), which identity-plane services warrant individually. A shared NetKingdom threat model may be referenced by both bindings rather than duplicated.
- Runtime manifests move out of `net-kingdom/sso-mfa/k8s/` into the respective `rapp` repos. This repo stops holding runtime YAML and returns to canon, standards, and ADRs.
- `tenant-engine` requires a data migration from SQLite to cnpg, including migration of existing tenants, grants, plan assignments, and idempotency receipts. TEN-WP-0005-T05's rollout plan is affected: it currently targets the SQLite runtime.
- NetKingdom services become subject to the `railiance/app.toml` staged promotion contract (Stage 1 local → Stage 2 canary → Stage 3 production), including declared rollback commands and health endpoints. Digest-pinned images already satisfy `digest_policy = "required"`.
- The reef must accept or mitigate its single-server and shared-control-plane risk for each NetKingdom binding, as it must for `rapp-qonto`. The reef name and a `high` criticality label are not evidence.

## Alternatives Considered

One `rapp-netkingdom` for all associated repos. Rejected. It would reduce binding-evidence count and match the current coupled deployment (both engines' manifests share one tree; `flex-auth` runs per-consumer instances `flex-auth-tenant-engine` and `flex-auth-user-engine`). But it contradicts the one-workload rule in `repository-axes.md`, and would force a single rollback contract across independently versioned services. A rollback contract that depends on which service failed is not a contract. This alternative would be correct only if the engines were always promoted and rolled back as one atomic cutover — which their separate digests and release cadences contradict.

Keep SQLite for `tenant-engine`, standardise later. Rejected. It leaves the two engines operationally dissimilar, which is the opposite of the intent, and `rail-kubernetes` does not support the per-workload persistent-storage contract the PVC depends on. Deferring also grows the migration: every tenant, grant, and receipt written between now and the cutover is data to move.

A `rapp` per NetKingdom concern with a `consumers:` list, mirroring `rapp-postgres`. Rejected as a category error. `rapp-postgres`'s consumers are consumers of one workload (PostgreSQL); NetKingdom's engines are distinct workloads, not consumers of a shared one.

## Follow-Up

- Create `rapp-tenant-engine` and `rapp-user-engine`; move runtime manifests out of `net-kingdom/sso-mfa/k8s/`.
- Add both bindings to `reef-railiance/bindings/rapps.yaml` at `declared`.
- Add `railiance/app.toml` to `tenant-engine` and `user-engine`.
- Open a `tenant-engine` workplan for the cnpg backend and data migration; reconcile with TEN-WP-0005-T05, whose rollout currently targets SQLite.
- Confirm whether `secrets-engine` is intended to remain a non-deployed control layer. This ADR assumes it is.
- Record the NetKingdom-wide threat model that both bindings will reference.