--- 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.