# `rapp-openbao` Compatibility Handoff

## Purpose

Define the migration-window handoff between `railiance-platform` and
`rapp-openbao` for the deployable OpenBao package surface.

Wave 1 makes `rapp-openbao` the durable owner of the OpenBao package contract.
`railiance-platform` remains the S3 owner of custody, policy, credential-lane
governance, and root-of-trust handling. During the migration window,
`railiance-platform` keeps a thin compatibility surface so current operators do
not need a flag day.

## Canonical Package Owner

Use `rapp-openbao` as the canonical home for these package-owned assets and
behaviors:

- `helm/openbao-values.yaml`
- `helm/openbao-middleware.yaml`
- `helm/openbao-ui-overlay-k8s.yaml`
- `helm/openbao-ui-overlay/`
- `scripts/openbao-ui-overlay-apply.sh`
- `scripts/openbao-verify.sh`
- `scripts/openbao-verify-login-overlay.sh`
- `scripts/openbao-validate-emergency-drill-evidence.sh`
- `scripts/openbao-validate-restore-evidence.sh`
- the drill-evidence example JSON files
- the package-owned `Makefile` targets:
  `openbao-repo`, `openbao-dry-run`, `openbao-overlay-apply`,
  `openbao-deploy`, `openbao-status`, `openbao-verify`,
  `openbao-verify-post-unseal`, `openbao-verify-login-overlay`,
  `openbao-validate-restore-evidence`, and
  `openbao-validate-emergency-evidence`

New behavior, docs, and fixes for that deploy/overlay/smoke surface should land
in `rapp-openbao` first.

## Platform-Side Compatibility Surface

During the migration window, `railiance-platform` may still expose the same
package-owned `Makefile` targets and keep compatibility copies of the
package-owned files listed above.

Those copies are for operator continuity only. They are not the long-term
source of truth.

If package-owned behavior changes:

1. update `rapp-openbao` first;
2. refresh the compatibility copy in `railiance-platform` only when current
   operators or automation still depend on it; and
3. avoid evolving the platform copy independently.

## What Stays In `railiance-platform`

The handoff does not expand the package boundary.

Still retained in `railiance-platform` as S3 ownership:

- `docs/openbao.md` sections covering init, unseal, custody, auth bootstrap,
  audit posture, and platform-owned policy
- `scripts/openbao-apply-initial-config.sh`
- `scripts/openbao-verify-authenticated.sh`
- `scripts/openbao-apply-ssh-engine.sh`
- `scripts/openbao-verify-ssh-engine.sh`
- `scripts/openbao-apply-workload-kv-lanes.sh`
- `scripts/openbao-apply-credential-change-appliers.py`
- `scripts/openbao-apply-token-grants.py`
- the matching `Makefile` targets:
  `openbao-configure-initial`, `openbao-configure-ssh`,
  `openbao-verify-ssh`, `openbao-verify-authenticated`,
  `openbao-configure-workload-kv-lanes`,
  `openbao-configure-credential-change-appliers`,
  `openbao-configure-token-grants`, and related verification targets
- platform policy, credential-grant, and delegated-metadata source under
  `openbao/policies/`, `credential-change-requests/`, and `credential-grants/`

## Operator Migration Path

Operators can move without a flag day:

1. Use `rapp-openbao` for package deploy, overlay, smoke, and package-owned
   drill-evidence work.
2. Continue using `railiance-platform` for attended bootstrap, authenticated
   verification, and policy/governance flows.
3. If existing automation still calls the package-owned OpenBao targets from
   `railiance-platform`, it may keep doing so during the migration window, but
   canonical fixes still land in `rapp-openbao` first.
4. Split mixed docs and scripts before removing the platform compatibility
   copies.

## Exit Condition

The migration window can end once current operators and automation no longer
depend on `railiance-platform` copies of package-owned OpenBao files or
targets, and the remaining mixed material has been split cleanly.