Define Qonto Knative runtime handoff

docs/knative-runtime-and-rapp-handoff.md

@@ -0,0 +1,78 @@
+# Knative Runtime And `rapp-qonto` Handoff
+
+Date: 2026-07-26
+
+## Ownership Boundary
+
+`qonto-assistant` keeps:
+
+- Qonto API domain behavior
+- default-deny, no-spend/no-volume-cost policy
+- tenant and actor authorization integration
+- application audit events and deny-escalation behavior
+- request idempotency behavior for financial operations
+- application health semantics
+
+`rapp-qonto` receives:
+
+- runtime image and configuration binding
+- Knative Service and rail-binding manifests
+- service account and secret references
+- workload-specific network policy
+- rollout, smoke, rollback, and revocation checks
+- measured cold-start and scale-down evidence
+
+`rail-knative` owns:
+
+- request activation and buffering
+- Knative revisions and traffic routing
+- scale-to-zero, minimum scale, concurrency, and autoscaling semantics
+- bounded cold-start behavior
+- rail-specific revision rollback
+
+The current `deploy/k8s/qonto-assistant/` tree and `railiance/app.toml` are
+migration input. They must not continue growing as an unreviewed parallel
+production target.
+
+## Application-Side Runtime Contract
+
+- Caller authentication and coarse authorization happen before activation
+  whenever the entry architecture permits it.
+- The raw application port is never publicly exposed.
+- Workload readiness must include policy and dependency readiness, not merely a
+  listening socket.
+- The runtime fails closed when identity, authorization, or the OpenBao
+  credential lane is unavailable.
+- Financial requests carry an idempotency key across cold start, retry, and
+  reconnect.
+- A caller timeout does not assert that an upstream financial operation was
+  never attempted.
+- Application audit context survives activation and upstream failure.
+
+## Identity And Credential Boundary
+
+Steady-state names target the package:
+
+- service account and workload principal: `rapp-qonto`
+- OpenBao workload role: `rapp-qonto`
+- caller client: `rapp-qonto-client`
+- bank credential reference: `tenants/binky/qonto-api`
+
+Any role named for `qonto-assistant` is a time-bounded migration bridge.
+Secret values never appear in manifests, workplans, logs, State Hub, or agent
+output. Credential planning uses `warden plan`; use uses sanctioned execution,
+file-output, or wrapped transports.
+
+## Evidence Required Before Production Approval
+
+- measured cold start, request timeout, concurrency, and idle scale-down
+- unauthenticated, wrong-tenant, and denied-capability negative tests
+- retry/idempotency test across activation
+- positive and negative OpenBao access
+- Qonto-only egress enforcement or a recorded compensating exception
+- audit delivery and credential revocation
+- previous-revision rollback
+- failure behavior for identity, authorization, OpenBao, and Qonto outages
+
+Direct Kubernetes deployment is an exceptional, expiring fallback rather than
+a parallel steady state.