railiance-master/docs/rapp-first-wave-candidates.md

# First-Wave `rapp-*` Candidates

Date: 2026-07-25
Updated: 2026-08-13 (RMASTER-WP-0021-T08)

## Purpose

Choose and order the first `rapp-*` candidates for Railiance, and record
what was actually built against that plan.

`rapp-*` repos are for managed workload packaging and scaffolding. They are
not new ownership homes. The decision is not "which repos are important?"
but "which workloads already have a strong enough package boundary to become
first-class managed wrappers without weakening ownership?"

## What Was Actually Built

The 2026-07-25 plan was:

1. `rapp-openbao`
2. `rapp-vergabe-teilnahme`
3. `rapp-forgejo` after the forge runtime target stabilized

What exists on 2026-08-13:

| Repo | Status | How it arrived |
|---|---|---|
| `rapp-openbao` | live, declared | as planned |
| `rapp-postgres` | live, declared | ad hoc, from the need for a shared platform database |
| `rapp-qonto` | live, declared | ad hoc, from the need to run Qonto on `rail-knative` |
| `rapp-vergabe-teilnahme` | never built | the user-facing wrapper it existed to prove is unproven |
| `rapp-forgejo` | not built | forge placement is now decided (`d151d817`): workload to `rapp-forgejo`, layer to S4 |
| `rapp-secrets-engine` | exists, undeclared | family prefix, no `declarations/` |
| `rapp-tenant-engine` | exists, undeclared | family prefix, no `declarations/` |
| `rapp-user-engine` | exists, undeclared | family prefix, no `declarations/` |

The platform-service pattern is proven twice (`rapp-openbao`,
`rapp-postgres`). The user-facing wrapper pattern is unproven. That is the
consequence of building to immediate need instead of to the planned second
slot.

The operator decision that follows is: build `rapp-vergabe-teilnahme` to
prove the user-facing shape before mass extraction. Do not treat the three
engine repos, or any other live undeclared workload, as a substitute for
that proof.

## Selection Criteria

The first-wave candidates should satisfy most of the following:

- stable workload identity
- clear upstream or source workload boundary
- clear Kubernetes package surface already visible in Git
- explicit runtime-secret and dependency handling
- deploy, verify, and recover behavior already described
- low ambiguity between packaging ownership and domain ownership
- good demonstration value for later `rapp-*` extractions

## Planned First-Wave Assessment (2026-07-25)

The original assessment is kept below so the gap between plan and outcome
stays visible. It is not the current worklist.

### 1. OpenBao from `railiance-platform`

Assessment: **choose first** — and this one landed.

Why it fitted:

- It is a clear third-party upstream product with durable identity.
- The workload already had a substantial Railiance packaging surface.
- The repo already distinguished the OpenBao workload from the wider S3
  platform policy that consumes it.
- It proved that `rapp-*` is not only for user-facing apps.

What stayed in `railiance-platform`: secrets custody as a platform
capability, lane policy, credential approval, and cross-workload
secret-delivery conventions.

### 2. Forge workload from `railiance-forge`

Assessment then: **defer from first wave**. That deferral still holds as a
first-wave fact, but the placement question is now closed. Decision
`d151d817` puts the Forgejo workload in `rapp-forgejo` and the layer
responsibility (runner placement and labels, registry retention, artifact
lifecycle, package credentials) in S4 `railiance-enablement`.
`railiance-forge` is placed, not retired. Gitea is confirmed replaced.

`rapp-forgejo` is therefore a wave-2 package with a decided home, not an
open placement debate.

### 3. User-facing S5 workload from `railiance-apps`

Assessment then: **choose `vergabe-teilnahme` for wave 1**. It was never
built. The reasons it was the right user-facing slot remain: one named
workload, explicit release surface, secret handling that is not entangled
with shared platform semantics. That is why it is still the package that
must prove the user-facing shape before mass extraction.

`reuse-surface` remains the strongest follow-on self-built service
candidate. `core-hub` should still wait.

## Wave-2 Inventory

Grouped by bounded context, in the composition shape from ADR-0007. These
are indicative packages, not created repos. A package is listed only where
members share rollout and rollback fate. Names that already exist as
undeclared `rapp-*` repos are marked so they are not invented twice.

### `rapp-vergabe-teilnahme` — prove the user-facing wrapper

```yaml
composition:
  purpose: Package the Vergabe Teilnahme application as a managed user-facing workload.
  member_repos:
    - repo: vergabe-teilnahme
      role: application source and chart
      deployables: [vergabe-teilnahme]
```

Build this before any further user-facing extraction.

### `rapp-forgejo` — decided placement

```yaml
composition:
  purpose: Package Forgejo, its runner, and the package registry as one managed forge.
  member_repos:
    - repo: railiance-forge
      role: operational helm, manifests, runner, and registry assets
      deployables: [forgejo, forgejo-runner, forgejo-registry]
```

Layer concerns stay in `railiance-enablement`. Do not create `rapp-gitea`.

### `rapp-netkingdom-identity` — identity bounded context

```yaml
composition:
  purpose: Package NetKingdom identity — users, tenants, SSO, MFA, and authorization — as one rollback unit.
  member_repos:
    - repo: user-engine
      role: user identity
      deployables: [user-engine]
    - repo: tenant-engine
      role: tenant identity
      deployables: [tenant-engine]
    - repo: key-cape
      role: SSO and MFA
      deployables: [keycloak]
    - repo: flex-auth
      role: authorization decisions
      deployables: [flex-auth]
```

`rapp-user-engine` and `rapp-tenant-engine` already exist as undeclared
prefix claims. They are not separate rapps under grouped-by-bounded-context
granularity. Their owners should either fold them into this package or
justify an independent rollback fate and then declare them. `rapp-secrets-engine`
is the same question against `rapp-openbao` / `railiance-platform`, not a
fourth identity member.

### `rapp-coulomb-social`

```yaml
composition:
  purpose: Package the Coulomb Social application as a managed user-facing workload.
  member_repos:
    - repo: coulomb-social
      role: application
      deployables: [coulomb-social]
```

Do not start this until `rapp-vergabe-teilnahme` has proven the user-facing
shape.

### `rapp-helix-forge`

```yaml
composition:
  purpose: Package the Helix Forge methodological workspace as a managed workload.
  member_repos:
    - repo: helix-forge
      role: capability-first development ecosystem
      deployables: [helix-forge]
```

Helix Forge is a different lineage from `railiance-forge`. It is not a
rename of `rapp-forgejo`.

## Risks To Watch

- If `rapp-openbao` absorbs platform-wide policy and credential-governance
  logic, the wrapper becomes a shadow S3 repo.
- If `rapp-postgres` is asked to mint the backup account, key, or bucket, a
  consumed destination is being mistaken for package ownership. The bucket
  is `resource-control` (`RESOURCE-WP-0002`); the credential is
  `railiance-platform` OpenBao custody; purchase is decision `9c21c0e0`.
- If `rapp-vergabe-teilnahme` absorbs generic S5 onboarding, it weakens
  `railiance-apps`.
- If the three undeclared engine repos are treated as rapps without a
  declaration, the coverage check cannot see them and will list their live
  deployables as uncovered.
- If wave-2 extraction starts before the user-facing wrapper is proven,
  Railiance will mass-produce the platform-service shape and still not know
  whether the other shape works.

## Outcome

Wave 1 proved the platform-service wrapper, twice, and did not prove the
user-facing wrapper. The next package that must exist is
`rapp-vergabe-teilnahme`. Everything else in the wave-2 inventory waits on
that proof, on owner-side declaration of the three undeclared prefix
claims, and on the schema migration owned by `RAILIANCE-WP-0015-T02`.