From 8c838bf38a755c8eeeba542c851bf5af93aa1656 Mon Sep 17 00:00:00 2001 From: codex Date: Fri, 10 Jul 2026 01:17:03 +0200 Subject: [PATCH] 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 --- .../business-app-service-contract_v0.1.md | 107 ++++++++++++++++++ ...ST-WP-0058-business-platform-enablement.md | 2 +- 2 files changed, 108 insertions(+), 1 deletion(-) create mode 100644 canon/standards/business-app-service-contract_v0.1.md diff --git a/canon/standards/business-app-service-contract_v0.1.md b/canon/standards/business-app-service-contract_v0.1.md new file mode 100644 index 0000000..cfca7e2 --- /dev/null +++ b/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/`. +- **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. diff --git a/workplans/CUST-WP-0058-business-platform-enablement.md b/workplans/CUST-WP-0058-business-platform-enablement.md index 1feaf95..f581d3b 100644 --- a/workplans/CUST-WP-0058-business-platform-enablement.md +++ b/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" ```