railiance-platform/docs/rapp-platform-service-pattern.md

The S3 Platform-Service Rapp Pattern

Date: 2026-08-11 Owner: railiance-platform (S3) Work record: RAILIANCE-WP-0015-T01

Purpose

This is the reference shape for packaging a platform service as a rapp-* managed workload package. It generalizes the two boundaries S3 has already drawn — docs/rapp-openbao-boundary.md and docs/rapp-postgres-boundary.md — so the third and fourth platform rapps do not each re-derive the split from scratch.

It is deliberately not a general rapp standard. The four-axis repo family model belongs to railiance-master/docs/repository-axes.md, and the rapp.yaml schema and canon promotion are in flight there and in the-custodian. This document covers only the half S3 owns: what a platform-service rapp looks like, and where the line falls between the package and the platform.

The rule

A rapp owns how its workload is packaged, deployed, verified, rolled back and recovered. S3 retains everything that is true across workloads: policy, credential custody, lane approval, and the shared substrate the package assumes.

Both existing platform rapps already state this in their own words. From rapp-openbao-boundary.md: the package may own how OpenBao is packaged, deployed, verified and skinned, and must not become the home for platform-admin policy, workload KV lane policy, delegated metadata authority, or credential grants. From rapp-postgres-boundary.md: the package owns manifests, consumer declarations, provisioning surface, isolation tests and recovery, while S3 retains the operator, storage policy, backup target and the credential-broker grant catalog.

The ownership test

When an asset's home is unclear, ask in this order. The first answer that applies decides it.

1. Would this asset survive replacing the workload with a different product? If yes, it is S3's. Credential lane approval survives swapping OpenBao for another secrets engine; an OpenBao Helm values file does not.
2. Does any other workload depend on this asset? If yes, it is S3's. A workload-kv-read-* policy is consumed by the workload it names but governed by a lane model shared by all of them.
3. Does it encode who may approve, not how to apply? Approval authority is S3's; application mechanics are the package's. This is the line that keeps a rapp from becoming a shadow S3 repo — the failure mode named explicitly in railiance-master/docs/rapp-first-wave-candidates.md.
4. Otherwise it is the package's. Charts, values, overlays, deploy and verify scripts, workload-specific smoke and recovery procedure, and the Makefile targets that drive them.

Applied

Asset class	Home	Test
Helm values, chart pins, overlays, ingress/middleware manifests	rapp	4
Deploy / dry-run / status / verify / rollback commands	rapp	4
Workload-specific smoke and recovery procedure	rapp	4
Consumer declarations and provisioning surface	rapp	4
Operator and read-only policy surface	S3	1
Credential lane approval, CCRs, grant catalog	S3	3
Cross-workload secret delivery (ESO, KV lanes)	S3	2
Backup target procurement and its credentials	S3	1
Storage class, monitoring substrate, cluster access	S3	1

Reference rapp.yaml for a platform service

The normative shape is railiance-master/schemas/rapp.schema.json (ADR-0007). A platform-service rapp fills that schema as follows. RAILIANCE-WP-0015-T02 converged rapp-openbao and rapp-postgres onto this shape.

kind: managed-workload-package
repo_family: rapp
rapp_id: rapp-<workload>
repo: rapp-<workload>
ownership_repo: railiance-platform      # the S3 home retaining governance
contract_version: 1.0.0
readiness_state: verified
data_classification: <internal|restricted>
criticality: <high|critical>
workload_identity:
  name: <workload>                      # the workload, never the repo name
  package_type: helm-managed-platform-service
  chart: <repo/chart>
  chart_version: <pinned>
  app_version: <pinned>
primary_rail: rail-kubernetes
supported_rails: [rail-kubernetes]
bound_reefs: [reef-railiance]           # empty only if the package is not placed
runtime_dependencies: [...]             # capabilities, not the resource that satisfies them
composition:
  purpose: <what this coherent workload does>
  member_repos:
    - repo: rapp-<workload>             # single-repo rapp: one member, itself
      role: <what it contributes>
      deployables: [<running unit names>]
  upstream_components:
    - name: <chart|image>
      source: <repo/chart or registry ref>
      version: <exact pin>
rollout_contract:
  default_mode: <helm-upgrade-install|kubectl-server-side-apply>
  commands: [...]                       # renamed from supported_commands
smoke_contract:
  required: [...]                       # outcomes the commands establish
  commands: [...]
rollback_contract:
  order: [...]                          # most-preferred strategy first
  commands: [...]
source_documents: [...]

Two conventions worth stating because they have already drifted:

• workload_identity.name is the workload, not the repo. openbao, not rapp-openbao.
• ownership_repo is the repo that retains governance after extraction — for platform services that is railiance-platform, and it is not the same thing as the repo the package was carved out of.

Grouped rapps

Operator decision of 2026-08-11: rapp granularity is grouped by bounded context — one rapp per cohesive group of services that deploys, versions and rolls back together, rather than one rapp per deployable.

Rapp context is its own dimension

A bounded rapp context is not derived from a Forgejo organization, nor from a State Hub domain. It is a grouping in its own right. This follows OAS P1 (canon/standards/orthogonal-architecture_v1.0.md) — independent perspectives MUST stay in separate dimensions — and it is forced by cardinality:

Grouping	Answers	Cardinality to repos
Forgejo org	who may push; what is discoverable together	1:many (a repo has one org — it is a path segment in the clone URL)
State Hub domain	which strand of work, for attention and priority	1:many
Rapp context	what deploys, versions and rolls back together	many:many

A repo can legitimately contribute to more than one rapp — a shared library, or a service that is both a member of one bundle and a dependency of another. A many:many grouping cannot be derived from a 1:many one. Domains fail in both directions: several rapps sit within one domain, and a cross-cutting rapp such as an identity bundle serves every domain rather than sitting inside one.

The three also change at different speeds — org membership is expensive to change, domains change occasionally, rapp contexts change often as workloads consolidate. Deriving the volatile grouping from the expensive one guarantees churn in the wrong place.

One precision matters for enforcement: repos are many:many with rapps, but deployables are 1:1 — each running deployable has exactly one rapp owning its rollout. That distinction is what makes the coverage check well-defined: does every live deployable belong to exactly one rapp?

Declaring the composition

A rapp declares what it combines: first-party repos and pinned third-party components, plus the purpose the combination serves. The normative shape is railiance-master/schemas/rapp.schema.json; the form is:

composition:
  purpose: <what this coherent workload does>
  member_repos:
    - repo: <slug>
      role: <what it contributes>
      deployables: [<names>]
  upstream_components:
    - name: <chart|image|operator>
      source: <repo/chart or registry ref>
      version: <pin>

For a grouped rapp:

• members must be declared explicitly; an undeclared bundle is not a rapp, it is a drawer
• grouping is legitimate only where members share rollout and rollback fate. If one member can be rolled back without the others, it is a separate rapp
• the group's smoke contract must cover the group, not just its largest member

rapp-postgres is already a grouped package in this sense — it owns the CNPG cluster manifests plus per-consumer declarations, and declares its consumers explicitly in consumers:. That is the shape to copy.

Credential lanes

A platform-service rapp never owns credential custody. It declares what it needs; S3 vends it through the existing broker. The bind is docs/rapp-credential-lane-binding.md: standing secrets go through a CCR and secret_references; short-lived leases go through the grant catalog and rapp_id. Follow docs/credential-broker.md and docs/credential-change-approval.md for gate, delivery, and revocation — this pattern does not replace them.

The existing rule holds without exception: the package never commits credentials, and a workload receives a short-lived lease through the platform broker rather than a package-managed secret.

Live deployable inventory

railiance-master coverage check (tools/validate-family-declarations.py --inventory) must not query the cluster. S3 emits the interchange file:

docs/evidence/reef-railiance-deployables.json

Refresh with scripts/capture-reef-deployables.py -o docs/evidence/reef-railiance-deployables.json. The file lists non-substrate Deployments, StatefulSets, CNPG Clusters, and Knative Services on reef-railiance. Declared composition.member_repos.deployables names must match these live names.

When a platform service earns a rapp

Not every S3 service needs one. A platform service is ready for extraction when it has a stable workload identity, a package surface already visible in Git, an explicit dependency and secret story, and described deploy/verify/recover behavior — the criteria from rapp-first-wave-candidates.md. A service that fails these is not blocked from being operated; it simply stays owned by S3 until its packaging identity stops moving.