railiance-platform/docs/s3-consumer-interfaces.md

S3 consumer service interfaces

Work record: RAILIANCE-WP-0016 item 17; RPF-WP-0018 T04
Date: 2026-08-15, revised 2026-08-17
Contract version of this index: 1.1.0

Consumers bind to these contracts, not to Helm chart names or pod topology. Changing an engine behind a versioned interface does not bump the interface unless the consumer-visible fields change.

Interface	Version	Who it is for	Authority
Shared application database	apps-pg.v1	S5 apps that need an isolated database on apps-pg	docs/apps-pg.md
Isolated platform database	rapp-postgres.v1	Platform services that need a CNPG consumer on platform-pg	rapp-postgres/declarations/rapp.yaml consumer_contract
Standing runtime secret	ccr-workload-kv.v1	Workloads that need a KV path via External Secrets	schemas/credential-change-request.schema.yaml
Short-lived lease	credential-grant.v1	Operators/agents and dynamic DB roles	credential-grants/catalog.yaml
Rapp credential bind	rapp-lane.v1	How a rapp names the two lanes above	docs/rapp-credential-lane-binding.md
Consumption-mode gate	consumption-mode.v1	New orders for a restricted financial entity	docs/consumption-mode-enforcement.md

Compatibility rules

• A vN document may add optional fields. Removing or renaming a required field is vN+1.
• Values never appear in an interface document. Paths, grant ids, CCR ids, and role names are the contract.
• make pg-deploy / Bitnami DSN postgresql-ha-pgpool.platform.svc.cluster.local is not an interface. That stack is retired.

Quota disclosure

Added in 1.1.0 — additive, so no consumer contract breaks.

Tenancy Posture §10.2: quotas are disclosed, not discovered. Every consumer is told at provisioning what the platform will refuse to do for it, and told again when that changes. A consumer learning its statement timeout by hitting it in production is a disclosure failure, not a consumer bug.

The obligation this places on S3 is a standing one: a change to any value in the tables below is announced to bound consumers before it takes effect. The values themselves are read from the cluster CR and are the package owner's to set — this index publishes them, it does not choose them.

Retention disclosure carries the additional §7 rule from docs/placement-policy.md: on a shared cluster the effective erasure horizon is the maximum declared across co-residents, not the value the consumer requested. That number is disclosed, and it moves when a co-resident changes.

apps-pg.v1

Consumer supplies: app name, namespace, database name, role name. Platform provisions the role and CNPG Database, labels the namespace railiance.io/postgres-client=apps-pg, and publishes a runtime Secret. RW endpoint: apps-pg-rw.databases.svc.cluster.local:5432. Bootstrap role apps_admin is not a consumer credential.

Quotas and limits — read from helm/apps-pg-cluster.yaml, 2026-08-17:

Property	Value	Note
max_connections	PostgreSQL default (100)	Not tuned in the CR. Not partitioned per consumer — there is no per-consumer connection allowance, so one consumer can exhaust the cluster.
statement_timeout	none	Not set. A runaway query runs until it finishes.
idle_in_transaction_session_timeout	none	Not set.
CPU / memory limits	none declared	The pod is BestEffort QoS and is the first thing evicted under node pressure.
Instances	1	No HA. Restart recovery only, per the single-node rail.
Storage	10Gi
Backup	none configured	No barmanObjectStore, no retentionPolicy.
Effective erasure horizon	undefined	Follows from the line above.

Read the backup row before provisioning against this cluster. apps-pg has no backup at all — not a short retention, none. Recovery from data loss is not available on this interface today. This is disclosed rather than fixed because §10.2 requires disclosure now and the fix needs a backup target; it is recorded as the R-axis gap in docs/tenancy-posture.md and is the highest value item that declaration surfaced.

The unpartitioned connection pool is the same shape of risk rapp-postgres reported for platform-pg: the bound is aggregate, so every consumer can be politely inside its own expectations while the cluster still fails.

rapp-postgres.v1

Consumer is a consumers[].declaration. Boundary unit is database-per-consumer. Credential type is openbao-dynamic-database-credential via grant rapp-postgres/<consumer>-<role>. Tenant identifiers are opaque.

Quotas and limits — authority is rapp-postgres's helm/platform-pg-cluster.yaml; reproduced here for disclosure, 2026-08-17:

Property	Value	Note
max_connections	100	Aggregate, not per consumer. ~14 per consumer (12 runtime + 2 migration) puts the practical ceiling near 6.
Memory limit	1Gi	Expected to bind before connections do — ~10MB per backend. Memory pressure OOM-kills; connection exhaustion errors cleanly.
CPU	100m request / 1 limit
Instances	1	No HA.
Storage	20Gi
Backup retention	30d	Instance-wide, per rapp-postgres ADR-0002.
Effective erasure horizon	30d, or the max across co-residents	A consumer needing shorter cannot have it at P1. See docs/placement-policy.md §7.
Statement timeout	consumer-set	tenant-engine sets 5s for its own path; not a platform default.
Declared ceiling / overflow target	not yet declared	Owed by rapp-postgres before the third consumer, per docs/placement-policy.md Rule P-4.1.

Service classes currently co-resident on platform-pg: latency-critical (tenant-engine) and batch (audit-core). Nothing prioritises between them — community PostgreSQL has no resource governor. Reported per Tenancy Posture §8.3.3.

ccr-workload-kv.v1 and credential-grant.v1

Unchanged semantics from docs/credential-change-approval.md and docs/credential-broker.md. The version name exists so a rapp can cite the lane without restating TTL, delivery, or revocation rules.

Not yet an interface

Valkey and in-cluster MinIO have capability blocks in SCOPE.md and no live service. They do not receive a v1 until a consumer exists.