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

title	version	status	review	created	workplan	task	decisions
Business-App Service Contract	v0.1	accepted	approved by Bernd 2026-07-10	2026-07-10	CUST-WP-0058	CUST-WP-0058-T04	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.