# 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.