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

id	type	title	domain	repo	status	owner	topic_slug	planning_priority	planning_order	created	updated	related_repos	state_hub_workstream_id
RMASTER-WP-0019	workplan	Knative Qonto Runtime on reef-railiance	financials	railiance-master	finished	codex	railiance	high	19	2026-07-26	2026-07-29	railiance-master qonto-assistant key-cape rail-kubernetes reef-railiance railiance-platform railiance-fabric	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

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

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

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

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

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

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

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

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

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

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

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