epic(saas-control-plane): add opt-in tenant provisioning, entitlement, metering, subscription, and payment foundations #868

Context

The validated AWCMS-Mini platform-evolution roadmap places SaaS provisioning, entitlement, metering, subscription billing, and payment orchestration in an opt-in SaaS control plane, separate from tenant business data and separate from ERP accounting domains.

Epic #738 and child issues #739–#755 have completed the prerequisites: deterministic build-time module composition, derived compatibility contracts, domain-event runtime, capacity/performance evidence, data lifecycle, business scope/SoD, workflow, party, organization structure, reference data, document infrastructure, data exchange, reporting projections, integration hub, and ERP extension contracts.

The repository had no dedicated implementation backlog for the SaaS control plane. This epic fills that remaining validated recommendation without reopening completed foundations or embedding Platform Masjid, Jualanku.info, marketplace, POS, or ERP functional rules into the base.

Objective

Provide reusable, provider-neutral SaaS control-plane capabilities for derived applications:

• service/plan catalog;
• tenant provisioning and lifecycle orchestration;
• effective entitlements, feature/module access, and quotas;
• usage metering and aggregation;
• subscriptions, invoices, credits, and dunning state;
• payment-provider adapters, webhook inbox, and reconciliation;
• operator administration, reporting, audit, security, deployment, and pilot evidence.

Placement decision

All runtime implementation is blocked by #869. The expected conceptual model is:

Platform/control-plane scope
├── service_catalog
├── tenant_entitlement
├── tenant_provisioning
├── tenant_lifecycle
├── usage_metering
├── subscription_billing
└── payment_gateway

Tenant/application scope
├── business modules and tenant data
└── consumes effective entitlement contracts only

The control plane may be admitted as optional modules in this repository or moved to a separately composed official extension if the ADR concludes that this is safer. Child issues must follow that decision rather than forcing placement.

Child issues

Wave 0 — architecture and admission

• docs(saas-control-plane): decide module admission, control-plane boundary, trust model, and lifecycle contracts #869 — Decide module admission, control-plane boundary, trust model, data ownership, and lifecycle contracts.

Wave 1 — commercial access and tenant lifecycle

• feat(service-catalog): add versioned SaaS plans, features, quotas, pricing, and offer lifecycle #870 — Versioned service catalog: plans, offers, features, quotas, pricing, and publication lifecycle.
• feat(tenant-entitlement): compute and enforce effective features, modules, quotas, and overrides #871 — Effective tenant entitlements, module/feature/quota enforcement, overrides, and explanation.
• feat(tenant-provisioning): add idempotent provisioning workflow, compensation, reconciliation, and readiness #872 — Idempotent/resumable tenant provisioning, compensation, reconciliation, and readiness.
• feat(tenant-lifecycle): enforce trial, active, grace, suspended, canceled, restore, and downgrade semantics #873 — Trial/active/grace/suspended/canceled/restore/downgrade lifecycle semantics.
• feat(saas-contracts): add static feature, quota, meter, and commercial-event registries with conformance gates #874 — Static feature/quota/meter/commercial-event registries and derived conformance gates.

Wave 2 — usage, billing, and payments

• feat(usage-metering): add idempotent usage events, aggregation, quotas, corrections, and reconciliation #875 — Usage events, aggregation, quotas, corrections, lifecycle, and reconciliation.
• feat(subscription-billing): add subscription, invoice, credit, renewal, and dunning state machines #876 — Subscription, invoice, credit, renewal, upgrade/downgrade, and dunning state machines.
• feat(payment-gateway): add provider-neutral checkout, signed webhook inbox, retries, and reconciliation #877 — Provider-neutral checkout, signed webhook inbox, retry/DLQ, refunds, and reconciliation.

Wave 3 — management, security, operations, and proof

• feat(saas-admin): add platform-operator dashboard and tenant commercial self-service views #878 — Platform-operator dashboard and bounded tenant commercial self-service views.
• security(saas-control-plane): enforce platform/tenant separation, SoD, step-up, privacy, and support-access controls #879 — Platform/tenant separation, SoD, step-up, support access, privacy, DB-role, and readiness controls.
• feat(saas-operations): add control-plane projections, reconciliation jobs, SLOs, lifecycle, and incident evidence #880 — Reporting projections, reconciliation jobs, SLOs, data lifecycle, capacity, and incident evidence.
• test(saas-control-plane): prove derived-app onboarding, sandbox billing, deployment, restore, and upgrade end-to-end #881 — Derived-app end-to-end pilot covering onboarding, sandbox billing, deployment, restore, and upgrade.

Dependency map

#869 Architecture/admission
 ├── #870 Service catalog
 │    └── #871 Entitlements
 │         ├── #872 Provisioning ──► #873 Tenant lifecycle
 │         └── #874 SaaS contracts ──► #875 Usage metering
 │                                      └── #876 Subscription billing
 │                                           └── #877 Payment gateway
 │
 ├── #879 Cross-cutting security (consumes implemented surfaces)
 ├── #878 Admin/self-service (after domain APIs are usable)
 └── #880 Operations/reporting (after event/job sources are usable)

#870–#880 ──► #881 external derived-app proof

Parallel work is allowed only where dependency and file ownership are disjoint. Generated inventories, OpenAPI/AsyncAPI bundles, i18n POT/catalogs, and registry artifacts must be regenerated once after integration rather than resolved by choosing a stale side.

Entry criteria

• docs(saas-control-plane): decide module admission, control-plane boundary, trust model, and lifecycle contracts #869 architecture/module-admission decision is accepted before runtime module implementation merges.
• main baseline is green using the repository's required Bun/PostgreSQL environment.
• No open security finding blocks the affected foundation.
• Each issue identifies reused base modules and does not rebuild tenant, identity, RBAC/ABAC, RLS, workflow, events, reporting, data lifecycle, integration hub, domain routing, module management, or compatibility mechanisms.
• Provider-specific implementation is optional and must include fake/sandbox coverage.

Non-negotiable boundaries

• Tenant remains the security boundary; platform-operator scope does not bypass tenant RLS silently.
• Service catalog is not an ERP product/item master.
• Subscription billing is not a tenant general ledger, AR/AP, cash/bank, or tax engine.
• Payment allocation/settlement metadata is not double-entry accounting.
• Provider calls occur outside database transactions through adapters/outbox workers.
• Full-online provider capabilities are opt-in; LAN/offline deployments remain operational when disabled.
• No hardcoded provider, credential, secret, or pricing rule.
• No runtime plugin marketplace, arbitrary code upload, eval, or tenant-supplied executable logic.
• Downgrade/suspension never silently deletes tenant data.
• All high-risk mutations use explicit permission, idempotency, audit, correlation ID, safe errors, and concurrency controls.
• Every tenant-scoped table uses tenant_id, ENABLE + FORCE RLS, tenant-first indexes, and least-privilege DB roles.

Epic Definition of Done

• Every child issue is completed or explicitly closed not_planned with an ADR-backed reason.
• Placement and dependency direction are documented and enforced by module composition/source-boundary gates.
• A derived application can define plans, provision a tenant, apply entitlements, meter usage, create a subscription/invoice, initiate a sandbox payment, process a signed webhook, and reconcile the result.
• Suspension/downgrade preserves data and produces deterministic access behavior across API, SSR, public routing, and workers.
• Platform operator and tenant administrator permissions are separated and tested with SoD/step-up/support-access controls.
• Payment/provider outage never holds a database transaction and has retry/DLQ/reconciliation evidence.
• OpenAPI/AsyncAPI, migrations, RLS, audit, idempotency, data lifecycle, reporting projections, docs, generated inventories, and changesets are synchronized.
• bun run check, PostgreSQL integration tests, security/adversarial tests, E2E, accessibility, performance/load/soak, production build, readiness, backup/restore, and non-production preflight pass.
• One base-version upgrade is rehearsed against the derived pilot without migration or tenant-data loss.
• No ERP accounting tables or application-specific business rules are added to the base.

Standards and compliance mapping

Implementation should map practical controls to UU PDP, UU ITE, PP 71/2019, ISO/IEC 27001/27002/27005/27017/27018/27034/27701, ISO/IEC 20000-1, ISO 22301, ISO/IEC 15408 as an assurance reference, OWASP ASVS/API Security Top 10, NIST CSF, and CIS Controls without claiming certification.

Evidence-gated exclusions

Do not add distributed cache, microservice extraction, sharding, or automated tenant placement merely as part of this epic. Those remain evidence-gated follow-ups requiring benchmark/operational proof, ADR, ownership, cutover, rollback, and no-dual-write plans.