coulomb/railiance-master
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Define derived rail and Qonto readiness architecture

Browse source
This commit is contained in:
codex 2026-07-26 11:45:07 +02:00
parent 0b95c3029c
commit 8901ae4b15
9 changed files with 845 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

413
workplans/RAILIANCE-WP-0019-knative-qonto-runtime-on-reef-railiance.md Normal file
View file

@ -0,0 +1,413 @@
---
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: progress
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.
## T07 - Version the rail-neutral workload and compatibility contract
```task
id: RAILIANCE-WP-0019-T07
status: progress
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
## 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
- [ ] common and rail-binding schemas are implemented
- [ ] repo-local implementation workplans are registered and active
- [ ] conformance and credential-routing paths are agent-executable
- [x] 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.