diff --git a/README.md b/README.md index 7ec04bf..3190338 100644 --- a/README.md +++ b/README.md @@ -15,10 +15,15 @@ recorded before they are spread across implementation repos. - [docs/reef-first-wave-rollout.md](docs/reef-first-wave-rollout.md) - [docs/fabric-state-hub-adaptation.md](docs/fabric-state-hub-adaptation.md) - [docs/repo-family-bootstrap-contract.md](docs/repo-family-bootstrap-contract.md) +- [docs/rail-composition-contract.md](docs/rail-composition-contract.md) +- [docs/reef-production-readiness-contract.md](docs/reef-production-readiness-contract.md) +- [docs/qonto-knative-runtime-contract.md](docs/qonto-knative-runtime-contract.md) - [docs/adr/ADR-0001-repository-prefix-architecture.md](docs/adr/ADR-0001-repository-prefix-architecture.md) - [docs/adr/ADR-0002-rail-kubernetes-wave-1-boundary.md](docs/adr/ADR-0002-rail-kubernetes-wave-1-boundary.md) - [docs/adr/ADR-0003-rapp-first-wave-selection.md](docs/adr/ADR-0003-rapp-first-wave-selection.md) - [docs/adr/ADR-0004-first-wave-reef-rollout.md](docs/adr/ADR-0004-first-wave-reef-rollout.md) +- [docs/adr/ADR-0005-derived-rail-composition.md](docs/adr/ADR-0005-derived-rail-composition.md) +- [docs/adr/ADR-0006-reef-production-admission.md](docs/adr/ADR-0006-reef-production-admission.md) ## Current Explorations diff --git a/WORK-RECORDS.md b/WORK-RECORDS.md index 58db712..f01398f 100644 --- a/WORK-RECORDS.md +++ b/WORK-RECORDS.md @@ -10,6 +10,7 @@ | --- | --- | --- | --- | --- | | workplan | RAILIANCE-WP-0017 | finished | — | workplans/RAILIANCE-WP-0017-rail-rapp-reef-repo-separation.md | | workplan | RAILIANCE-WP-0018 | finished | — | workplans/RAILIANCE-WP-0018-first-wave-repo-family-materialization.md | +| workplan | RAILIANCE-WP-0019 | active | — | workplans/RAILIANCE-WP-0019-knative-qonto-runtime-on-reef-railiance.md | | task | RAILIANCE-WP-0017-T01 | done | — | workplans/RAILIANCE-WP-0017-rail-rapp-reef-repo-separation.md | | task | RAILIANCE-WP-0017-T02 | done | — | workplans/RAILIANCE-WP-0017-rail-rapp-reef-repo-separation.md | | task | RAILIANCE-WP-0017-T03 | done | — | workplans/RAILIANCE-WP-0017-rail-rapp-reef-repo-separation.md | @@ -23,3 +24,13 @@ | task | RAILIANCE-WP-0018-T04 | done | — | workplans/RAILIANCE-WP-0018-first-wave-repo-family-materialization.md | | task | RAILIANCE-WP-0018-T05 | done | — | workplans/RAILIANCE-WP-0018-first-wave-repo-family-materialization.md | | task | RAILIANCE-WP-0018-T06 | done | — | workplans/RAILIANCE-WP-0018-first-wave-repo-family-materialization.md | +| task | RAILIANCE-WP-0019-T01 | done | — | workplans/RAILIANCE-WP-0019-knative-qonto-runtime-on-reef-railiance.md | +| task | RAILIANCE-WP-0019-T02 | done | — | workplans/RAILIANCE-WP-0019-knative-qonto-runtime-on-reef-railiance.md | +| task | RAILIANCE-WP-0019-T03 | done | — | workplans/RAILIANCE-WP-0019-knative-qonto-runtime-on-reef-railiance.md | +| task | RAILIANCE-WP-0019-T04 | done | — | workplans/RAILIANCE-WP-0019-knative-qonto-runtime-on-reef-railiance.md | +| task | RAILIANCE-WP-0019-T05 | done | — | workplans/RAILIANCE-WP-0019-knative-qonto-runtime-on-reef-railiance.md | +| task | RAILIANCE-WP-0019-T06 | progress | — | workplans/RAILIANCE-WP-0019-knative-qonto-runtime-on-reef-railiance.md | +| task | RAILIANCE-WP-0019-T07 | progress | — | workplans/RAILIANCE-WP-0019-knative-qonto-runtime-on-reef-railiance.md | +| task | RAILIANCE-WP-0019-T08 | progress | — | workplans/RAILIANCE-WP-0019-knative-qonto-runtime-on-reef-railiance.md | +| task | RAILIANCE-WP-0019-T09 | progress | — | workplans/RAILIANCE-WP-0019-knative-qonto-runtime-on-reef-railiance.md | +| task | RAILIANCE-WP-0019-T10 | progress | — | workplans/RAILIANCE-WP-0019-knative-qonto-runtime-on-reef-railiance.md | diff --git a/docs/adr/ADR-0005-derived-rail-composition.md b/docs/adr/ADR-0005-derived-rail-composition.md new file mode 100644 index 0000000..71f3252 --- /dev/null +++ b/docs/adr/ADR-0005-derived-rail-composition.md @@ -0,0 +1,31 @@ +# ADR-0005: Derived Rail Composition + +Date: 2026-07-26 +Status: Accepted + +## Context + +Knative provides distinct workload activation and revision semantics but runs +on Kubernetes. Treating it as an unrelated peer rail would duplicate generic +workload lifecycle and substrate assumptions. + +## Decision + +Railiance distinguishes base and derived rails. + +`rail-kubernetes` is the default base rail for platform workloads. +`rail-knative` is a derived rail that inherits a versioned +`rail-kubernetes` common contract and overrides only Knative-specific +activation, revision, autoscaling, traffic, cold-start, and rollback semantics. + +The detailed contract is +[`docs/rail-composition-contract.md`](../rail-composition-contract.md). + +## Consequences + +- New platform workloads continue to use `rail-kubernetes` unless a specialized + rail is justified. +- Derived rails declare base-rail compatibility rather than copying lifecycle + contracts. +- Fabric and conformance tooling must understand rail dependency and readiness. +- Knative installation stays with the S2 substrate owner. diff --git a/docs/adr/ADR-0006-reef-production-admission.md b/docs/adr/ADR-0006-reef-production-admission.md new file mode 100644 index 0000000..34c5380 --- /dev/null +++ b/docs/adr/ADR-0006-reef-production-admission.md @@ -0,0 +1,29 @@ +# ADR-0006: Reef Production Admission + +Date: 2026-07-26 +Status: Accepted + +## Context + +Fabric topology can say that a reef hosts a rail or binds a workload, but that +does not demonstrate capacity, isolation, recoverability, or approval for a +critical internet-facing service. + +## Decision + +Rail and `rapp` bindings use explicit readiness states: `declared`, +`installed`, `verified`, `production-approved`, and `deprecated`. + +Critical workloads require machine-readable conformance evidence plus explicit +acceptance of residual risks that cannot be automated. Mixed-rail reefs use +defined split triggers. + +The detailed contract is +[`docs/reef-production-readiness-contract.md`](../reef-production-readiness-contract.md). + +## Consequences + +- `hosts_rail` and `binds_rapp` no longer imply deployability. +- `reef-railiance` may host Knative in wave 2, but Qonto cannot be called + production-approved solely from that declaration. +- Repeated evidence collection should become functional automation. diff --git a/docs/qonto-knative-runtime-contract.md b/docs/qonto-knative-runtime-contract.md new file mode 100644 index 0000000..aa055ef --- /dev/null +++ b/docs/qonto-knative-runtime-contract.md @@ -0,0 +1,121 @@ +# Qonto Knative Runtime Contract + +Date: 2026-07-26 +Status: Architecture baseline; implementation values require measured evidence + +## Purpose + +Define the end-to-end runtime boundary for an internet-reachable Qonto service +that holds access to a company bank credential and scales to zero. + +## Ownership And Flow + +```text +authenticated client + -> reef ingress capability + -> rail-knative request activation and revision routing + -> rapp-qonto package + -> qonto-assistant domain service + -> OpenBao credential lane + -> Qonto API +``` + +- `railiance-cluster` owns ingress, DNS, certificate, Knative installation, + and cluster-level network capabilities. +- `rail-knative` owns activation, buffering, revisions, autoscaling, traffic, + cold-start, and rail-specific rollback semantics. +- `rapp-qonto` owns package manifests, runtime configuration, rail bindings, + workload-specific smoke checks, and secret references. +- `qonto-assistant` owns Qonto domain behavior, default-deny financial policy, + authorization integration, and application audit events. +- `reef-railiance` owns placement, local binding, and readiness evidence. + +The raw workload service is never a public unauthenticated endpoint. + +## Steady-State Identity And Secret Names + +The steady runtime identity is named for `rapp-qonto`, not its source repo. + +Recommended stable identifiers: + +- workload principal: `rapp-qonto` +- tenant: the canon-approved Binky tenant identifier +- Kubernetes service account: `rapp-qonto` +- OpenBao role: `rapp-qonto` +- bank credential reference: `tenants/binky/qonto-api` +- caller OIDC client: `rapp-qonto-client` + +Any `qonto-assistant` runtime principal or secret role is a time-bounded +migration bridge and must not become the steady-state declaration. + +## Request And Cold-Start Contract + +Implementation must measure and publish: + +- cold-start service-level objective +- caller timeout +- activator or gateway buffering timeout +- maximum concurrency +- retry ownership and retry limit +- readiness deadline +- scale-down grace period + +Financial or side-effecting operations must carry an idempotency key across +activation, retries, and client reconnects. A timeout must not silently imply +that an operation did not reach Qonto. + +Until measured values exist, implementation may use conservative development +defaults but must not claim `production-approved`. + +## Dependency Failure Rules + +- If caller identity cannot be verified: deny before activation when possible. +- If workload identity cannot be established: fail closed. +- If OpenBao or the bank-credential lane is unavailable: fail closed and emit + an audit event; never fall back to a static embedded secret. +- If Qonto is unavailable: return a bounded upstream failure and preserve + idempotency/audit context. +- If audit delivery is unavailable: follow the application security contract; + critical mutations must not become unaudited best-effort operations. + +## Network And Secret Controls + +- default-deny ingress and egress +- ingress only through the approved authenticated entry path +- egress only to DNS, the approved OpenBao endpoint, required identity and + authorization services, and Qonto API endpoints +- `0.0.0.0/0:443` is not production-approved without a documented exception + and compensating control +- short-lived workload identity and least-privilege secret access +- no secret value in Git, logs, State Hub, chat, or parent-shell output +- automated revocation and negative-access tests + +## Rollback And Fallback + +Rollback order is: + +1. previous verified Knative revision +2. keep the verified revision warm by setting a temporary minimum scale +3. declare the service unavailable + +A direct `rail-kubernetes` deployment is an exceptional, time-bounded fallback. +It requires an explicit exception record, the same security controls, an owner, +and an expiry. It is not a parallel steady-state production path. + +## Verification + +Before production approval, automated evidence must cover: + +- authenticated activation from scale zero +- rejected unauthenticated and wrong-tenant requests +- bounded cold start and timeout behavior +- idempotent retry behavior +- OpenBao positive and negative access +- Qonto-only egress enforcement +- audit delivery +- revision rollback +- credential revocation +- dependency-failure behavior + +The implementation path should progress from attended proof to agent-executed +conformance and finally to scheduled functional automation. diff --git a/docs/rail-composition-contract.md b/docs/rail-composition-contract.md new file mode 100644 index 0000000..978248c --- /dev/null +++ b/docs/rail-composition-contract.md @@ -0,0 +1,143 @@ +# Rail Composition Contract + +Date: 2026-07-26 +Status: Adopted for the second implementation wave + +## Purpose + +Define how a specialized Railiance execution rail composes with the default +`rail-kubernetes` contract without duplicating it. + +Railiance platform workloads use `rail-kubernetes` by default. A specialized +rail is justified only when a workload needs materially different execution +semantics and those semantics cannot be expressed safely as a small workload +profile. + +## Rail Kinds + +Rails have one of two composition kinds: + +- `base`: owns a complete workload execution contract for a substrate class +- `derived`: inherits a versioned base-rail contract and owns only its + specialization + +`rail-kubernetes` is the default base rail. + +`rail-knative` is a derived rail: + +```text +Kubernetes substrate profile + -> rail-kubernetes common workload contract + -> rail-knative activation and revision specialization + -> rapp-qonto workload binding +``` + +Knative installation remains an S2 cluster capability. The derived rail owns +how Railiance workloads use that installed capability. + +## Required Declaration Fields + +Every rail declaration must publish: + +- `contract_version` +- `composition_kind` +- `ownership_repo` +- `execution_architecture` +- `required_substrate_capabilities` +- `supported_rollout_modes` +- `readiness_state` + +A derived rail must additionally publish: + +- `base_rail` +- `base_rail_contract` +- `inherited_semantics` +- `overridden_semantics` +- `compatibility_constraints` + +## Inheritance Rule + +A derived rail inherits, rather than copies: + +- workload identity and ownership metadata +- common criticality and approval semantics +- health, evidence, promotion, and rollback vocabulary +- common dependency and secret-reference representation +- common audit and conformance requirements + +A derived rail may override only semantics intrinsic to its execution model. +For `rail-knative`, those are: + +- revisions +- request activation and buffering +- scale-to-zero and minimum scale +- concurrency and autoscaling +- traffic splitting between revisions +- cold-start readiness and timeout behavior +- Knative-specific rollback + +## Non-Goals For `rail-knative` + +`rail-knative` must not own: + +- Kubernetes or k3s bootstrap +- Knative operator installation or cluster-scoped lifecycle +- generic namespace, RBAC, ingress-controller, certificate, storage, or + observability ownership +- Qonto-specific manifests, policies, secret paths, or health checks +- a fork of the generic Railiance promotion vocabulary + +## Rail-Neutral Workload Contract + +Managed workload declarations have a common section and one or more rail +bindings. + +The common section owns: + +- workload and ownership identity +- criticality and data classification +- dependencies +- workload identity and secret references +- health, smoke, audit, recovery, and approval requirements +- reliability objectives + +Each rail binding owns: + +- rail and contract version constraint +- rail-specific deployment artifacts +- scaling, routing, rollout, and rollback parameters +- required substrate capabilities + +This makes Kubernetes the default binding while allowing a workload such as +Qonto to add a justified Knative binding without changing domain ownership. + +## Compatibility And Readiness + +Declarations distinguish: + +- `declared`: source-controlled contract exists +- `installed`: required runtime components are present +- `verified`: conformance and smoke evidence passes +- `production-approved`: criticality-specific admission gates pass +- `deprecated`: no new bindings are accepted + +Fabric relations describe topology, not readiness. A `hosts_rail` or +`binds_rapp` edge must carry or resolve a readiness state before automation +may treat it as deployable. + +## Automation Requirement + +All deterministic checks should be function-executable and idempotent: + +- schema validation +- base-rail compatibility resolution +- substrate-capability matching +- binding and ownership integrity +- readiness evidence freshness +- drift detection + +Human interaction is reserved for policy acceptance, exceptional risk, or +authority that cannot safely be delegated. Repeated evidence collection, +credential routing, reconciliation, and deployment verification should move +from human operation to agentic interaction and then to functional automation +as the contract stabilizes. diff --git a/docs/reef-production-readiness-contract.md b/docs/reef-production-readiness-contract.md new file mode 100644 index 0000000..9da0f6a --- /dev/null +++ b/docs/reef-production-readiness-contract.md @@ -0,0 +1,79 @@ +# Reef Production Readiness Contract + +Date: 2026-07-26 +Status: Adopted for the second implementation wave + +## Purpose + +Prevent a topology declaration from being mistaken for permission to run a +critical workload. + +`hosts_rail` and `binds_rapp` describe intended composition. Production use +requires explicit readiness evidence. + +## Admission States + +Every hosted rail and bound `rapp` uses: + +- `declared` +- `installed` +- `verified` +- `production-approved` +- `deprecated` + +Promotion is monotonic only while its evidence remains current. Failed or +expired evidence returns the binding to the last proven state. + +## Required Reef Evidence + +Before a rail becomes `verified`, the reef must provide machine-readable +evidence for: + +- substrate and Kubernetes version compatibility +- control-plane and workload capacity with documented headroom +- ingress, DNS, and certificate path +- storage and stateful-workload constraints +- workload identity and approved secret-delivery path +- network isolation and egress enforcement +- logs, metrics, traces, alerting, and audit delivery +- backup, restore, and rollback path +- upgrade and maintenance ownership +- failure-domain and recovery assumptions + +## Critical Workload Gate + +Before a critical, internet-facing, or high-value-credential workload becomes +`production-approved`, its binding must additionally record: + +- threat-model reference +- availability, cold-start, and recovery objectives +- identity, secret revocation, and audit evidence +- negative authorization and network tests +- rollback and temporary-fallback rules +- accepted residual risks and their owner + +The single-server and shared-control-plane risks of `reef-railiance` must be +explicitly accepted or mitigated for `rapp-qonto`; the reef name or `high` +criticality label is not evidence by itself. + +## Mixed-Rail Rule + +`reef-railiance` may host `rail-kubernetes` and `rail-knative` during the +second wave, while `rail-kubernetes` remains primary. + +Reassess or split the reef when any of these triggers occurs: + +- incompatible maintenance or upgrade windows +- inability to meet a critical workload recovery objective +- control-plane or workload resource contention +- materially different network or tenant-isolation requirements +- independent scaling or availability requirements +- failure in one rail cannot be contained from the other +- premium-security or regulatory policy requires a separate boundary + +## Automation Requirement + +Readiness evidence should be produced by idempotent probes and stored as +source-linked, timestamped records. Agents may execute and reconcile the +probes. Human approval should consume the evidence only where policy requires +explicit risk acceptance; it should not be used as a substitute for tests. diff --git a/docs/repository-axes.md b/docs/repository-axes.md index d17c800..928b9e5 100644 --- a/docs/repository-axes.md +++ b/docs/repository-axes.md @@ -31,6 +31,11 @@ For the current phase of Railiance: This means the repo model is intentionally ahead of the repo count. +Rails may compose. `rail-kubernetes` is the default base rail, while +Kubernetes-hosted execution specializations such as `rail-knative` are derived +rails with an explicit, versioned base-rail dependency. A derived rail owns +only the semantics it changes; it does not fork the common workload lifecycle. + ## The Four Repo Families | Prefix | Axis | Unit | Primary question answered | @@ -90,6 +95,10 @@ A rail owns the execution semantics for workloads on that architecture: A rail is not the workload itself and not the substrate it runs on. +A rail declaration identifies whether it is a `base` or `derived` rail. A +derived rail names its base contract, inherited semantics, overrides, +compatibility constraints, and readiness state. + In the current Railiance model, `rail-kubernetes` is the default base rail. Other rails should be introduced only when their runtime semantics justify a distinct lifecycle, contract, or operator model. @@ -187,6 +196,10 @@ This separation reduces confusion between: - workload identity - deployment location +Topology and readiness are also separate. A reef may declare that it hosts a +rail or binds a `rapp` without that combination yet being installed, verified, +or production-approved. + ## Creation Rules Use the following default rules. diff --git a/workplans/RAILIANCE-WP-0019-knative-qonto-runtime-on-reef-railiance.md b/workplans/RAILIANCE-WP-0019-knative-qonto-runtime-on-reef-railiance.md new file mode 100644 index 0000000..490ad73 --- /dev/null +++ b/workplans/RAILIANCE-WP-0019-knative-qonto-runtime-on-reef-railiance.md @@ -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.