CUST-WP-0058-T04: draft business-app service contract v0.1 (proposal)

Standalone-app shape, instance-per-client tenancy with consolidation-ready
data model (DR-1 C), app-local identity with bounded auth module (DR-3 A),
build/release evidence, ops-hub and fin-hub obligations, data-protection
baseline. Applies to client apps and Binky Hedgehog's own apps alike
(DR-2 B client-#1 model). Awaits canon review.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

canon/standards/business-app-service-contract_v0.1.md

@@ -0,0 +1,107 @@
+---
+title: Business-App Service Contract
+version: v0.1
+status: proposal
+review: pending — requires Bernd's approval before normative use
+created: "2026-07-10"
+workplan: CUST-WP-0058
+task: CUST-WP-0058-T04
+decisions: [DR-1 (d85cd185), DR-2 (1f8b109e), DR-3 (ebcf0573)]
+---
+
+# Business-App Service Contract v0.1
+
+Obligations every client-facing business application on the coulomb/HelixForge
+platform must meet before serving a paying client. Applies **equally** to apps
+sold to external clients and to Binky Hedgehog GmbH's own applications
+(coulomb.social) — per DR-2, Binky Hedgehog is client #1 of its own platform.
+There is one app shape and one contract; no special cases.
+
+**Reference implementation:** `vergabe-teilnahme` (first app through the
+delivery-lane pilot, `CUST-WP-0058-T07`).
+
+## 1. Shape and tenancy (DR-1 C, DR-2 B)
+
+- **1.1** A business app is a **standalone service**: own repo, own database,
+  own release values. It is not a Core Hub extension.
+- **1.2** Default deployment is **instance-per-client**: dedicated deployment
+  and database per client, own entry in `railiance-apps` release values.
+- **1.3** **Consolidation-ready data model** (mandatory): all client-owned
+  data is keyed by a tenant identifier from the first migration onward, even
+  though each instance serves exactly one tenant. Rationale: DR-1's early
+  cost-optimization move may consolidate instances; a tenant-clean schema
+  makes that a data-copy, not a rewrite.
+- **1.4** No app may hard-code the assumption "I am the only tenant" in
+  business logic, exports, or backup formats.
+
+## 2. Identity (DR-3 A)
+
+- **2.1** v1 baseline is **app-local accounts**, scoped to the instance.
+- **2.2** Account data lives in the instance database and is covered by the
+  same tenant keying as §1.3 (consolidation moves accounts with the tenant).
+- **2.3** Apps must isolate authentication behind a single module/boundary so
+  a later switch to platform OIDC (NK-WP-0011 Keycloak) is a bounded change.
+- **2.4** Platform identity activates only on the recorded demand triggers
+  (client SSO/AD request; instance consolidation; local-account toil across
+  >2 apps) — see `docs/business-platform-decision-records.md`.
+
+## 3. Build and release evidence
+
+- **3.1** Images are built from the app repo and tagged with the **immutable
+  commit SHA**; `latest` must never be the only production reference.
+- **3.2** Images are published to `gitea.coulomb.social/coulomb/<app>`.
+- **3.3** Release values live in `railiance-apps`; the app repo owns build
+  scripts and image metadata (railiance-forge pattern).
+- **3.4** Each client-visible release records: source repo, commit SHA,
+  image tag/digest, smoke result, and the release-values change. Evidence
+  reports contain **no secrets** (SOPS/OpenBao references only).
+
+## 4. Operations (ops-hub)
+
+- **4.1** Every client instance is registered in ops-hub: service, endpoint,
+  environment, and owning client.
+- **4.2** **Backup/restore**: each instance database has a scheduled backup
+  and a tested restore path; evidence of the last successful restore test is
+  recorded before the first paying client and after schema-major changes.
+- **4.3** Incidents affecting a client instance are recorded against that
+  instance; every app ships at least a minimal runbook (start/stop, backup,
+  restore, upgrade, known failure modes).
+- **4.4** A deployed smoke check exists and runs after every release.
+
+## 5. Cost and billing (fin-hub)
+
+- **5.1** Every instance carries a **cost attribution key**
+  (`client × app × instance`) usable by fin-hub cost ingestion.
+- **5.2** Infrastructure cost per instance must be reportable — this feeds
+  DR-1's cost-optimization decision point.
+- **5.3** Price-to-invoice flow is out of scope for the app itself; the app
+  only guarantees the attribution key exists (fin-hub gap: CUST-WP-0058-T06).
+
+## 6. Data protection
+
+- **6.1** Client data is processed within the platform's infrastructure;
+  per-instance isolation (§1.2) is the v1 isolation guarantee stated to
+  clients.
+- **6.2** Apps must support export and deletion of a client's complete data
+  set (offboarding = export + instance teardown + backup expiry).
+- **6.3** Personal data inventories and AV/DPA contract mechanics are a
+  Binky Hedgehog GmbH obligation, tracked outside this standard; the app
+  must be able to answer "what personal data do you store" from its schema.
+- **6.4** No plaintext credentials in repos, images, logs, or evidence
+  (existing credential-routing canon applies).
+
+## 7. Client plane integration (forward-looking)
+
+- **7.1** Once client-hub exists (scoping: CUST-WP-0058-T05), each instance
+  registers its client↔instance mapping there; until then the mapping lives
+  in ops-hub instance metadata (§4.1).
+- **7.2** Contract/entitlement state is never encoded in the app itself.
+
+## 8. Conformance
+
+- **8.1** A new app (or new client instance) is conformant when §1–§6 are
+  satisfied and evidenced; §7 applies once client-hub is live.
+- **8.2** The delivery-lane pilot (CUST-WP-0058-T07) validates this contract
+  end-to-end with vergabe-teilnahme; findings feed v0.2.
+- **8.3** Deviations require a recorded State Hub decision, not silent
+  exceptions.

workplans/CUST-WP-0058-business-platform-enablement.md

@@ -101,7 +101,7 @@ for T04: app-local accounts, consolidation-ready.
 
 ```task
 id: CUST-WP-0058-T04
-status: todo
+status: progress
 priority: high
 state_hub_task_id: "a3cec70c-04a1-42a9-a6b0-3d2943b73968"
 ```