Close S5 app readiness workplan

docs/app-data-backup-restore-handoff.md

@@ -0,0 +1,94 @@
+# App Data Backup And Restore Handoff
+
+This document defines the S5 app release boundary for data durability. It does
+not create backup jobs, authorize a live restore drill, or move platform
+backup ownership into `railiance-apps`.
+
+## Current App Data
+
+`vergabe-teilnahme` stores relational app data in `vergabe_db` on the shared
+CloudNativePG cluster `apps-pg` in the `databases` namespace. The cluster is an
+S3 platform service owned by `railiance-platform`; see
+`/home/worsch/railiance-platform/docs/apps-pg.md`.
+
+The app currently has no durable media PVC enabled. `persistence.media.enabled`
+is `false`, so uploaded media is deferred rather than an S5 durability promise.
+
+## Ownership Matrix
+
+| Concern | S5 app repo owns | Upstream owner |
+| --- | --- | --- |
+| App database request | App name, namespace, database name, role name, intended use, and production-readiness need | `railiance-platform` reviews and provisions the role/database |
+| Runtime DB Secret use | Secret name in the app namespace and URL-encoded DSN rebuild helper | `railiance-platform` owns platform credential source and future secret delivery |
+| Database backup job | Readiness gate and consumer evidence requirement | `railiance-platform` owns CNPG backup and restore implementation |
+| App restore verification | App-specific post-restore checks, migrations, login/smoke path, and rollback note | `railiance-platform` restores the backing database |
+| Forge images/packages | Artifact identity and consumer evidence cited by app runbooks | `railiance-forge` owns registry/package restore evidence |
+| App media/blob data | PVC declaration and app-level restore checks if enabled | `railiance-platform` owns storage backup mechanism once media is production-critical |
+
+## Production Readiness Gate
+
+Before an app release treats data as production-critical, the app runbook should
+record:
+
+- data class: disposable, externally reproducible, or production-critical;
+- owning platform workplan or doc for the backup mechanism;
+- latest non-secret backup evidence reference;
+- latest restore-drill evidence reference, ideally from an isolated
+  environment;
+- app-specific post-restore checks, such as migrations, health endpoint,
+  login/admin path, and representative business workflow;
+- rollback or disable path if restore fails;
+- assertion that no secret material was copied into Git, logs, screenshots, or
+  State Hub notes.
+
+If this gate is missing, the app can still be used for smoke, development, or
+migration validation, but promotion beyond that should create or link a
+`railiance-platform` workplan.
+
+## `vergabe-teilnahme` Gate
+
+Current posture:
+
+- database: `vergabe_db` on `databases/apps-pg`;
+- app role Secret: `vergabe-app-credentials`;
+- env Secret: `vergabe-teilnahme-env`;
+- current backup status: platform docs state that `apps-pg` backup coverage is
+  follow-up work;
+- restore status: no app-level restore drill evidence is recorded in this repo.
+
+Minimum evidence before production-trust use:
+
+- platform confirms `apps-pg` backup coverage for `vergabe_db`;
+- an isolated restore drill proves the database can be restored;
+- `vergabe-teilnahme` runs migrations successfully after restore;
+- health endpoint and HTTPS smoke checks pass;
+- operator verifies the app can complete a representative tender-management
+  workflow after restore;
+- any app media path remains disabled or has its own storage restore evidence.
+
+## Forge Artifact Evidence
+
+S5 runbooks may cite forge-owned package and blob restore evidence, but must not
+own Gitea package backup procedures or registry credentials. Use
+`/home/worsch/railiance-forge/docs/backup-restore-secret-handoff.md` for the
+forge artifact boundary.
+
+For app releases, cite:
+
+- image repository, tag, and digest when available;
+- source commit and package version;
+- forge publish job or evidence reference;
+- package/blob restore drill evidence when the artifact is production-critical;
+- namespace-local pull Secret or approved workload secret path, without token
+  values.
+
+## Filing Upstream Gaps
+
+When the missing durability item is not local to S5:
+
+1. Keep the S5 task focused on the app release impact.
+2. Create or link the platform/forge workplan that owns the missing mechanism.
+3. Mark the S5 task `blocked` only when the app release cannot safely continue
+   without that upstream evidence.
+4. Record the State Hub workstream/task id in the app runbook or workplan.
+5. Revisit the S5 promotion gate after upstream evidence exists.