railiance-platform/docs/placement-policy.md

S3 database placement policy

Work record: RPF-WP-0018 T02, T03, T06 Effective: 2026-08-17 Framework: net-kingdom/canon/standards/tenancy-posture_v0.1.md §4.4, §8 Contract version of this document: 1.0.0 Status: provisional — binding on this repo now; formally conditional on the framework reaching accepted.

Answers tenant-engine's 2026-08-16 request ("a default and the conditions that override it, so migrations stop being decided by whichever neighbour was consulted") and Tenancy Posture §19.2.

1. Ownership, and its limit

Draft-8 §8.2 assigns the placement rule to railiance-platform, substrate numbers to the package repo, workload requirements to the consumer and tier minimums to adaptive-pricing. Accepted, with the scope stated:

This repo owns the rule. The package repo owns the number.

We decide that a cluster must publish a ceiling, what happens when it is reached, what the default placement is, and who is accountable for each workload's placement. We do not decide what platform-pg's max_connections is — that is rapp-postgres's cluster CR, and RAILIANCE-WP-0012 / RAILIANCE-WP-0015 moved that surface there deliberately.

This matters for §19.8, which asks this repo for platform-pg's declared maximum size. That question is misrouted by one hop. rapp-postgres's own analysis makes the case better than we could: memory probably binds before connections do, at roughly 10MB per backend against a 1Gi limit, and that is an observation only the operator of the package can make. Our obligation under this policy is §4 below — that a ceiling and an overflow target exist and are published. Theirs is what they are.

adaptive-pricing declined a standing co-signature on 2026-08-17 and supplied the stronger replacement adopted by draft-8: typed tier minima are joined to consumer and provider declarations at tier definition and on change. This repo therefore owns this policy singly; it must validate, not copy, the commercial constraint artifact.

2. The default, and what overrides it

The ladder is net-kingdom canon and is not restated here. Adopted by reference: P0–P4 per Tenancy Posture §4.4.

Default: P1 — database per consumer, shared cluster — for platform services. P3 for client-facing business apps, per business-app-service-contract §1.2. Both already ratified as Decision 4.4.1; this document adopts rather than re-decides them.

P0 is not a sanctioned target. It is the state repos arrive in. A consumer sharing a database with another consumer is a defect with a migration owed, not a placement.

The distinction tenant-engine asked us to preserve, preserved: sharing a cluster is a capacity decision and is cheap to undo — create target, dump, restore, swap the secretKeyRef, restart. Sharing a database entangles schemas and makes relocation a schema merge. This policy says "shared" only ever in the first sense. Any consumer on an S3-custody cluster owns a whole database.

Portability is an expectation, not a courtesy. A consumer connects by injected URL only; no cluster, namespace, host or database name in source. tenant-engine adopted this unprompted and it is hereby the rule, because a placement policy that cannot be executed is a preference.

3. Placement owner per workload

§19.2 asks for a recorded owner per workload so that "should this be dedicated" has an answer that is not archaeology. The placement owner decides placement changes for that workload and is accountable for watching its triggers. It is not the same role as the operator of the cluster.

Workload	Substrate	Provided level	Placement owner	Co-signer	§13 evidence
audit-core	platform-pg	P1	audit-core	this repo	probes exist
tenant-engine	SQLite PVC current; platform-pg desired	off-ladder current; P1 desired	tenant-engine	this repo	source conformance; live cutover absent
user-engine	user-engine-pg	P2	net-kingdom	this repo	not assessed here
target-revenue	target-revenue-pg	P2	target-revenue	this repo	not assessed here
forgejo	forgejo-db	P2	this repo	—	single consumer
vergabe	apps-pg	P1	vergabe-teilnahme	this repo	absent
coulomb_social	apps-pg	P1	coulomb-social	this repo	absent

3.1 Two of these P1 levels are asserted without evidence

§13.1 claims a level only with its artifact present. The P1–P4 artifact is "provisioning declaration plus the platform's isolation probes".

platform-pg has them — rapp-postgres runs 19 adversarial probes against the consumer boundary. apps-pg has none. scripts/capture-apps-pg-evidence.py captures capacity evidence for resource-control; it makes no isolation assertion. So the P1 levels recorded above for vergabe and coulomb_social are, as of 2026-08-17, provisioning declarations without probes — stated here rather than quietly carried, because a table of levels that mixes evidenced and unevidenced entries without saying which is which is the failure §13.1 exists to prevent.

Recorded as owed by this repo. Until the probes exist, those two rows should be read as intended placement, not verified placement.

3.2 apps-pg cannot produce the noisy-neighbour artifact at all

Worth separating from the gap above, because it is not a matter of writing a missing test. §13's P1–P2 noisy-neighbour artifact requires a per-consumer usage baseline, a saturation run, and evidence that the governance controls bind — that the greedy consumer is held at its limits.

apps-pg has no per-consumer governance controls. Its connection pool is not partitioned, there is no per-consumer connection allowance, no statement timeout and no resource limit on the pod. There is nothing that could be shown to bind, so a run against it could only demonstrate that a saturating consumer degrades its co-residents — which §13.4 explicitly rejects as an artifact that "can only fail, or that passes by being run gently enough".

The honest sequence is therefore: controls first, artifact second. Writing the probe before the limits exist would produce an overclaim wearing the costume of evidence. Tracked as RPF-WP-0019.

The consuming repo is the placement owner; this repo co-signs. The consumer knows its latency requirement, its erasure horizon and its compliance position; we know the substrate. Neither can decide alone, and putting the decision solely here would recreate the "ops repo holds a commercial decision" problem §8.2 exists to avoid. A placement change needs both signatures.

New consumers record a placement owner at provisioning. A provisioning request without one is incomplete.

4. Ceiling and overflow — the §19.8 obligation, generalised

Rule P-4.1. Every shared cluster under S3 policy MUST publish a declared maximum consumer count and a named overflow target, both before its third consumer is provisioned.

Rule P-4.2. The ceiling is stated as the binding constraint with its number, not as a capacity boast. Where more than one resource could bind first — connections versus memory is the live case — the declaration names which is expected to bind and why. A ceiling derived from the resource that fails cleanly while another fails catastrophically is a mis-stated ceiling: connection exhaustion errors and is recoverable, memory pressure OOM-kills and degrades every co-resident at once.

Rule P-4.3. The overflow target is a named substrate, not "we will build one". "Provision a second cluster" is an answer; "revisit at the time" is not.

Status against these rules today:

Cluster	Ceiling declared	Overflow target	Standing
platform-pg	4 declarations (estimated; ADR-0004)	platform-pg-2, named but absent	3/4 including the isolation probe; measure before the next workload
apps-pg	3 consumers; 20 connections each, 1Gi memory binds first	apps-pg-2	2/3; overflow must exist before a 4th
forgejo-db	n/a — single consumer	n/a	—

Both live shared clusters are one consumer away from the trigger. This repo owes apps-pg's ceiling under its own rule, which is the correct asymmetry: a policy whose author is exempt is not a policy.

5. Triggers, and who is watching them

§8.1: triggers MUST be monitored, not merely recorded. "A trigger in a YAML comment nobody re-reads is documentation, not control."

This repo has no monitoring plane. SCOPE.md records that S3 emits to railiance-telemetry "once the evidence plane exists — seeded 2026-08-11, not yet implemented". Rather than claim coverage we do not have — the overclaim §6 prohibits — each trigger below carries either a named watcher or the literal marker unmonitored.

#	Trigger (§8)	Signal that would fire it	Watcher	Cadence
1	Noisy neighbour on a latency-critical path	Query latency regression on the consumer's own path	consumer-observed — the consumer notices, we do not	on incident
2	Compliance or residency requirement	Consumer declares it	placement owner	at declaration
3	Plan tier requiring a higher minimum	adaptive-pricing tier definition names a P floor	adaptive-pricing	on tier change
4	Erasure horizon no longer fits	Consumer's declared horizon < cluster retention floor	placement owner + this repo	at provisioning, then unmonitored
5	Connection or memory ceiling reached	Backend count vs declared ceiling; memory vs limit	unmonitored — pending railiance-telemetry	—

Trigger 5 is the one that matters and it is the one nobody is watching. That is the honest position. It is also why Rule P-4.1 forces the ceiling to be declared before the third consumer: a threshold that is written down is at least checkable by a human at provisioning time, which is strictly better than a limit discovered by an OOM kill. Declaring the ceiling is a partial substitute for monitoring it, and it is the part we can do this week.

Closing trigger 5 belongs to railiance-telemetry, not to this workplan. Recorded here as a dependency so it is visible rather than assumed.

6. Service class co-residency — the §8.3.3 report

§8.3.2 declares service class as a category, never a priority. §8.3.3 requires the platform to report which classes are co-resident, because "an unenforceable risk that nobody can see is strictly worse than one that is stated".

Cluster	Co-resident classes	Mismatch
platform-pg	latency-critical (tenant-engine) + batch (audit-core)	yes — reported
apps-pg	interactive + interactive	no
forgejo-db	single consumer	n/a

platform-pg mixes latency-critical with batch today. Under §8.3.1 co-residents are equal — community PostgreSQL has no resource governor, so nothing prioritises tenant-engine's synchronous authorization queries over audit-core's batch work. tenant-engine chose a 5s statement timeout precisely because it sits on flex-auth's synchronous path.

This is reported, not remediated. It may well still be the right call — §8.3.2 says a recognised mismatch "may still be the right call, but it should be a decision, not an accident of who was provisioned when". It is now a decision. The escalation, if the mismatch bites, is P2 for tenant-engine, and the known alternative — gateway-level prioritisation in a connection proxy — is infrastructure this estate does not run and is not adopted here.

7. Retention floor and ceiling — the §19.9 answer

Answered: yes to both, as a rule; the numbers belong to the package repo.

Rule R-7.1 — floor. A consumer's requested backupRetentionDays below the cluster's declared floor is a validation error at provisioning, not a quiet disappointment. A consumer that asks for 1 day and silently gets 30 has been told nothing true; a consumer that gets an error learns the actual constraint at the only moment it can act on it.

Rule R-7.2 — ceiling. A maximum exists so no consumer can exhaust the backup volume. Exceeding it is likewise an error, and the remedy named in the error is P2 — a dedicated cluster whose retention is the consumer's own.

Rule R-7.3 — the floor is a placement trigger, and this is the important one. Per rapp-postgres ADR-0002, physical backup is instance-wide, so on a shared cluster a consumer's erasure horizon is the maximum declared across all co-residents. A consumer needing a horizon shorter than that floor cannot have it at P1 and must move to P2 — for a reason that has nothing to do with performance or capacity, which is exactly why it must be recorded rather than assumed.

This makes someone else's retention choice everyone's, which is what tenant-engine warned about on 2026-08-16 and was right to. Rule R-7.4 follows.

Rule R-7.4 — inherited retention is disclosed, not inherited silently. A consumer joining a shared cluster is told its effective erasure horizon at provisioning, and told again when a co-resident's change moves it. This is §10.2 applied to retention and is implemented in docs/s3-consumer-interfaces.md 1.1.0.

Enforcement is the package repo's. The validator lives where the CR lives. This document states the rule; rapp-postgres and this repo's own apps-pg onboarding enforce it.

8. What this policy deliberately does not do

• It moves no workload. Declaring where things are is separate from changing where they are. Nothing above is a migration instruction.
• It adds no QoS axis. §19.12 resolved that: we could not enforce one.
• It does not decide identity-provider placement (realm-per-tenant versus Organizations, §19.7). That is key-cape's, on a different substrate.
• It claims no monitoring. See §5.

Review interval

Six months, or on: a new shared-cluster consumer, a co-residency class change, railiance-telemetry going live, or the framework reaching accepted. Next review due 2027-02-17.