railiance-master/workplans/RMASTER-WP-0019-knative-qonto-runtime-on-reef-railiance.md

---
id: RMASTER-WP-0019
type: workplan
title: "Knative Qonto Runtime on reef-railiance"
domain: financials
repo: railiance-master
status: finished
owner: codex
topic_slug: railiance
planning_priority: high
planning_order: 19
created: "2026-07-26"
updated: "2026-07-29"
related_repos:
  - railiance-master
  - qonto-assistant
  - key-cape
  - rail-kubernetes
  - reef-railiance
  - railiance-platform
  - railiance-fabric
state_hub_workstream_id: "d2b082db-ecc3-4322-8be3-22aa00a2af5c"
---

# RMASTER-WP-0019 - Knative Qonto Runtime on reef-railiance

## Goal

Turn the Qonto internet-runtime direction into an explicit second-wave
Railiance repo-family plan: `reef-railiance` hosts a new `rail-knative`, and
that rail dynamically runs a new `rapp-qonto` package extracted from the
current `qonto-assistant` deployment path.

This workplan exists to replace the remaining "custom activator or maybe
Knative" ambiguity with a concrete cross-repo architecture path before new
runtime implementation starts.

The second-wave design also establishes a general rule for reliable and
cost-efficient operation: deterministic work should progress from attended
human operation, to agent-executable interaction, to idempotent functional
automation as its contract stabilizes. Human interaction remains appropriate
for irreducible policy acceptance and privileged authority, not for repeated
evidence collection or routine reconciliation.

## Why This Exists

`RMASTER-WP-0018` finished the first wave:

- `rail-kubernetes` exists as the default base rail
- `reef-railiance` exists as the grouped home reef for the Railiance servers
- `rapp-openbao` proved the first managed package split
- Fabric can now project `governed_by`, `supports_rail`, `hosts_rail`, and
  `binds_rapp`

The next concrete runtime pressure comes from `QONTO-WP-0004`. That workload
needs internet reachability, bounded cold-start behavior, strong identity, and
strict secret custody. Those are exactly the conditions that justify a second
rail instead of extending the direct `rail-kubernetes` path indefinitely.

At the same time, `KEY-WP-0004` is provisioning the first tenant and workload
identity lane for Binky Hedgehog GmbH. That lane should target the future
runtime package and not harden a permanent direct deployment shape that the
framework now intends to replace.

## Current Starting Point

The current ecosystem state is:

- `reef-railiance` is the grouped reef for the Railiance server fleet
- `rail-kubernetes` owns the current baseline deployment and lifecycle contract
- `qonto-assistant` already contains the Qonto domain code, hardening work, and
  an initial direct Kubernetes placement request
- `key-cape` has `KEY-WP-0004` open for the Binky tenant and qonto workload
  identity lane
- no `rail-knative` repo exists yet
- no `rapp-qonto` repo exists yet

## Target Outcome

When this workplan is complete:

1. The boundary between `rail-kubernetes` and a new derived `rail-knative` is
   written and approved.
2. The boundary between `qonto-assistant` and a future `rapp-qonto` is written
   and approved.
3. `reef-railiance` is confirmed as the first host reef for this runtime path,
   including the rail/reef binding assumptions.
4. Identity, secret, and routing lanes are aligned to the future
   `rapp-qonto` runtime instead of a permanent direct `qonto-assistant`
   deployment.
5. Repo-local follow-up workplans can launch `rail-knative` and `rapp-qonto`
   without reopening the architecture question.
6. Reef admission, contract compatibility, credential routing, and operational
   evidence have automation-ready contracts before production implementation.

## Boundaries

This workplan may define architecture, sequencing, and repo-boundary contracts
across Railiance, `qonto-assistant`, and `key-cape`.

It must not:

- bootstrap `rail-knative` yet
- bootstrap `rapp-qonto` yet
- move code or manifests between repos
- implement runtime changes in `reef-railiance`, `rail-kubernetes`,
  `qonto-assistant`, or `key-cape`

Implementation starts only after the follow-up workplans opened from this plan
are reviewed and accepted.

## Tasks

## T01 - Define the `rail-knative` boundary against `rail-kubernetes`

```task
id: RMASTER-WP-0019-T01
status: done
priority: high
state_hub_task_id: "336cb298-9107-4519-ad64-5b23853c84fa"
```

Write the contract for what `rail-knative` must own versus what remains owned
by `rail-kubernetes`.

At minimum this boundary must decide ownership for:

- scale-to-zero and cold-start semantics
- service activation / ingress entry behavior
- Knative Serving primitives versus generic Railiance lifecycle semantics
- compatibility expectations for `reef-railiance`
- what stays reusable from the base Kubernetes rail instead of being forked

Acceptance:

- one written boundary contract exists
- the contract names explicit non-goals for `rail-knative`
- the split does not duplicate the generic lifecycle contract already owned by
  `rail-kubernetes`

2026-07-26: Added `docs/rail-composition-contract.md` and
`docs/adr/ADR-0005-derived-rail-composition.md`. `rail-knative` is now a
derived rail with a versioned `rail-kubernetes` base contract. The contract
defines inheritance, overrides, non-goals, readiness states, and a rail-neutral
workload/binding model.

## T02 - Define the `rapp-qonto` extraction boundary from `qonto-assistant`

```task
id: RMASTER-WP-0019-T02
status: done
priority: high
state_hub_task_id: "54fcea7d-3c4e-444f-b184-f18f3c4b3a7c"
```

Write the contract for what moves into `rapp-qonto` and what stays in
`qonto-assistant`.

This task must keep `qonto-assistant` as the ownership home for the Qonto
domain logic while using `rapp-qonto` as the managed runtime/package boundary.

At minimum the contract must decide ownership for:

- deployment packaging and runtime manifests
- runtime configuration and secret references
- smoke, rollout, rollback, and promotion expectations
- how the current direct Kubernetes material becomes migration input rather
  than a permanent target shape

Acceptance:

- one written boundary contract exists
- `qonto-assistant` remains the ownership repo in the contract
- `rapp-qonto` is justified as a managed package repo and not as a new
  ownership mirror

2026-07-26: Added the ownership and request-flow boundary in
`docs/qonto-knative-runtime-contract.md`. `qonto-assistant` retains domain
logic, financial policy, authorization integration, and application audit
events. `rapp-qonto` owns packaging, rail bindings, runtime configuration,
secret references, and workload-specific rollout evidence.

## T03 - Define the `reef-railiance` hosting model for the qonto runtime

```task
id: RMASTER-WP-0019-T03
status: done
priority: high
state_hub_task_id: "b0233f06-3dee-4cac-bae4-d8add5ac29c8"
```

Confirm how `reef-railiance` hosts the first `rail-knative` runtime slice and
what that means for ingress, isolation, and criticality.

This task must decide:

- whether the qonto path lives entirely on `reef-railiance` in wave 2
- how `rail-knative` is declared as a hosted rail there
- whether a primary-rail versus mixed-rail statement needs revision
- what existing S1/S2 approvals or substrate notes must be updated before
  runtime work starts

Acceptance:

- the hosting assumption is written
- the reef/rail relation update path is named
- unresolved substrate risks are listed instead of buried in repo-local work

2026-07-26: Added `docs/reef-production-readiness-contract.md` and
`docs/adr/ADR-0006-reef-production-admission.md`. `reef-railiance` may host
`rail-knative` during wave 2 while keeping `rail-kubernetes` primary, but
topology no longer implies readiness. Critical Qonto admission requires
capacity, ingress, identity, isolation, observability, recovery, and explicit
single-server/shared-control-plane risk evidence.

## T04 - Align identity and secret custody to the future runtime path

```task
id: RMASTER-WP-0019-T04
status: done
priority: high
state_hub_task_id: "0086eb68-a852-4fe7-834c-4a19dd763b77"
```

Align `KEY-WP-0004`, the OpenBao lane, and the ops-warden routing lane so the
credential path terminates at the future `rapp-qonto` runtime on
`rail-knative`, while still allowing a clearly temporary migration bridge from
the current `qonto-assistant` repo.

Acceptance:

- the future runtime principal and lane names are defined
- the transitional use of any current `qonto-assistant` runtime role is
  explicitly marked temporary
- no workplan still assumes a permanent direct deployment target for the lane

2026-07-26: `docs/qonto-knative-runtime-contract.md` defines steady identifiers
for `rapp-qonto`, its service account, OpenBao role, and caller client while
making any `qonto-assistant` role a time-bounded bridge. Credential values must
use sanctioned custody and execution transports; only route and conformance
metadata may enter workplans, Git, chat, or State Hub.

## T05 - Define second-wave bootstrap and Fabric registration sequence

```task
id: RMASTER-WP-0019-T05
status: done
priority: medium
state_hub_task_id: "8905d447-dee9-460d-bbfe-3f0c8e42c7c6"
```

Define the repo-creation and registration sequence for `rail-knative` and
`rapp-qonto`, using the first-wave bootstrap contract already proven by
`RMASTER-WP-0018`.

Acceptance:

- the bootstrap order is named
- the minimum declaration files are named for both future repos
- the expected Fabric relations (`supports_rail`, `hosts_rail`, `binds_rapp`,
  `governed_by`) are named before repo creation starts

Bootstrap order:

1. publish the common contract/schema additions in `rail-kubernetes`
2. add readiness and compatibility support in Fabric
3. open the `reef-railiance` admission work and collect baseline evidence
4. bootstrap `rail-knative` with a derived-rail declaration
5. bootstrap `rapp-qonto` with common and Knative binding declarations
6. register `governed_by`, `base_rail`, `supports_rail`, `hosts_rail`, and
   `binds_rapp` relations
7. promote relations through `declared`, `installed`, `verified`, and
   `production-approved` only as evidence lands

The minimum declaration files remain `declarations/rail.yaml`,
`declarations/rapp.yaml`, and `declarations/reef.yaml`. Rail-neutral workload
and rail-binding schemas must be source-controlled before repo creation is
treated as implementation completion.

## T06 - Open the repo-local follow-up workplans for implementation

```task
id: RMASTER-WP-0019-T06
status: done
priority: medium
state_hub_task_id: "18fe6f04-f8c5-451b-8e3f-38c19f05f682"
```

Once the boundary and sequencing documents exist, open or update the concrete
repo-local implementation workplans that will execute them.

At minimum, this should cover:

- `qonto-assistant`
- `key-cape`
- `reef-railiance`
- the future `rail-knative` repo at bootstrap time
- the future `rapp-qonto` repo at bootstrap time

Acceptance:

- each implementation-owning repo has a concrete follow-up workplan
- no implementation starts from an unwritten architecture assumption
- this framework workplan can later close with repo-local execution delegated

2026-07-26: Architecture is ready for repo-local workplan creation. Workplans
must separate source-repo, package, derived-rail, reef admission, Fabric
compatibility, identity/custody, and S2 runtime installation responsibilities.

2026-07-26: Opened and State Hub registered repo-local execution work in
`rail-kubernetes`, `rail-knative`, `rapp-qonto`, `reef-railiance`,
`railiance-fabric`, `qonto-assistant`, and `key-cape`. The two new repos were
reconciled with their existing Forgejo bootstrap commits and pushed.

## T07 - Version the rail-neutral workload and compatibility contract

```task
id: RMASTER-WP-0019-T07
status: done
priority: high
state_hub_task_id: "5b5f2d41-2860-44ee-a8b6-8b9e1d32854f"
```

Turn the composition decision into source-controlled schemas and conformance
checks.

Acceptance:

- workload declarations separate common facts from rail bindings
- base and derived rails declare contract versions and compatibility
- validation rejects missing owners, incompatible base rails, and unsupported
  substrate capabilities
- Kubernetes remains the default binding for platform workloads

2026-07-26: `rail-kubernetes` now publishes base contract `1.0.0`, common
workload, rail-binding, and derived-rail schemas, a Kubernetes-default example,
and an offline validator. `rail-knative` and `rapp-qonto` pass that validator.

## T08 - Establish reef admission evidence and mixed-rail split triggers

```task
id: RMASTER-WP-0019-T08
status: done
priority: high
state_hub_task_id: "663a319e-2a05-4a35-90a2-4f6b7b5afa22"
```

Implement the production-readiness states and evidence model in
`reef-railiance` and Fabric.

Acceptance:

- topology is distinct from installed, verified, and production-approved state
- capacity, ingress, network, identity, observability, recovery, and failure
  domain evidence have machine-readable locations
- Qonto's single-server/shared-control-plane residual risk is explicit
- mixed-rail split triggers are represented

2026-07-26: Added a reusable, secret-free substrate preflight in
`railiance-cluster` and recorded the failed API reachability result as reef
evidence with `block_installation`. Declared topology was not promoted.

2026-07-26: After the server upgrade, the server-side preflight and complete
Knative lifecycle verification passed. Reef evidence now distinguishes the
verified rail from blocked production approval and retains capacity and
single-node split triggers.

## T09 - Establish Qonto SLO, threat, rollback, and fallback evidence

```task
id: RMASTER-WP-0019-T09
status: done
priority: high
state_hub_task_id: "6cc2d3a7-33b6-47a7-b59d-04be9318c861"
```

Turn `docs/qonto-knative-runtime-contract.md` into executable package and
source-repo verification.

Acceptance:

- cold start, request timeout, buffering, concurrency, and scale-down values
  are measured before production approval
- retry and idempotency behavior is explicit for financial operations
- public ingress and raw service exposure boundaries are testable
- egress is narrower than unrestricted HTTPS or has an approved exception
- rollback prefers a verified Knative revision; direct Kubernetes fallback is
  time-bounded and exceptional

2026-07-26: `rapp-qonto` now has offline-validated, cluster-local,
digest-pinned, bounded Knative packaging with scale-to-zero, default-deny
networking, ExternalSecret references, and an explicit unverified FQDN egress
gate. Live SLO, identity, failure, and rollback evidence remains outstanding.

2026-07-27: Deployed digest-addressed revision `rapp-qonto-00004` on
rail-knative. The fail-closed proxy gate and cluster-local health smoke pass.
Full cold-start timing, audit/idempotency, revocation, dependency-failure, and
previous-revision rollback evidence remains before T09 completion.

2026-07-29: `rapp-qonto/tools/verify_live.sh` now records reversible,
machine-readable live evidence. The successful railiance01 run measured a
7.384443-second cold activation from zero and proved bounded repeat requests,
metadata-only secret delivery, fail-closed proxy loss, recovery,
missing-secret denial and restoration, previous-revision rollback, and return
to latest traffic. The owner repository's 80-test suite supplies the
domain-level audit, idempotency, authorization, and redaction evidence.

## T10 - Automate routing, conformance, reconciliation, and evidence

```task
id: RMASTER-WP-0019-T10
status: done
priority: high
state_hub_task_id: "1b75308f-f968-4443-aefe-af37550545a1"
```

Move repeatable operation toward reliable functional automation while
preserving least privilege and explicit risk authority.

Acceptance:

- `warden plan` and route lookup cover implementation credential needs before
  any founder interaction is proposed
- agents use sanctioned `--exec`, `--out`, or wrapped transports rather than
  reading secret values
- conformance checks are idempotent and suitable for CI or scheduled execution
- Fabric/State Hub reconciliation consumes source declarations and evidence
- human steps are limited to named authority or residual-risk decisions and
  have an automation follow-up path

2026-07-26: Generic Knative and Qonto conformance is executable offline. The
cluster preflight is idempotent and read-only. Credential routing was attempted
first; its unrelated Forgejo match is tracked as a catalog-quality gap rather
than used for Kubernetes access.

2026-07-26: The cluster now has checksum-locked, idempotent Serving/Kourier
installation and live verification automation. The configured SSH lane
provides agent execution while direct public API access remains unnecessary.

2026-07-27: KeyCape client credentials are live, their OpenBao custody and
rotation route is published as `rapp-qonto-keycape-client`, and the M3/prod
posture manifest passes. Public `kc.coulomb.social` DNS still targets the
older CoulombCore endpoint; railiance01 verification currently uses direct
TLS-preserving resolution pending routing convergence.

2026-07-29: Credential needs are routed before access, installation and
verification use sanctioned SSH execution without secret output, and the live
gate is idempotent, reversible, and emits secret-free JSON suitable for CI or
scheduled reconciliation. Source declarations and reef bindings now consume
the verified evidence. The only remaining human authority is the explicitly
separate production acceptance or mitigation of single-node failure-domain
risk.

## Exit Criteria

- [x] `rail-knative` has a written boundary against `rail-kubernetes`
- [x] `rapp-qonto` has a written boundary against `qonto-assistant`
- [x] `reef-railiance` is explicitly named as the first host reef
- [x] identity and secret custody point at the future runtime path
- [x] derived-rail composition and non-duplication are decided
- [x] reef readiness and mixed-rail split rules are decided
- [x] Qonto end-to-end failure, rollback, and security boundaries are written
- [x] common and rail-binding schemas are implemented
- [x] repo-local implementation workplans are registered and active
- [x] conformance and credential-routing paths are agent-executable
- [x] second-wave repo bootstrap order is defined
- [x] repo-local implementation workplans exist before implementation begins

## Notes

This is a second-wave framework plan. It should stay at the planning and
coordination layer until the relevant repo-local workplans are in place.