Define derived rail and Qonto readiness architecture

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.