--- id: RAILIANCE-WP-0019 type: workplan title: "Knative Qonto Runtime on reef-railiance" domain: financials repo: railiance-master status: active owner: codex topic_slug: railiance planning_priority: high planning_order: 19 created: "2026-07-26" updated: "2026-07-26" 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" --- # RAILIANCE-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 `RAILIANCE-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: RAILIANCE-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: RAILIANCE-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: RAILIANCE-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: RAILIANCE-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: RAILIANCE-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 `RAILIANCE-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: RAILIANCE-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: RAILIANCE-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: RAILIANCE-WP-0019-T08 status: progress 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 ## T09 - Establish Qonto SLO, threat, rollback, and fallback evidence ```task id: RAILIANCE-WP-0019-T09 status: progress 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 ## T10 - Automate routing, conformance, reconciliation, and evidence ```task id: RAILIANCE-WP-0019-T10 status: progress 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 ## 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 - [ ] 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.