docs(saas-control-plane): decide module admission, control-plane boundary, trust model, and lifecycle contracts #869

Parent epic: #868

Context

The roadmap permits an opt-in SaaS control plane only after platform-evolution contracts are stable. Before adding tables or modules, AWCMS-Mini needs an explicit architecture/module-admission decision that prevents the control plane from becoming either application-specific business logic or an implicit super-tenant bypass.

Objective

Publish the authoritative ADR, threat model, module-admission decisions, dependency rules, and state contracts for the SaaS control plane.

Scope

• Decide whether service_catalog, tenant_entitlement, tenant_provisioning, tenant_lifecycle, usage_metering, subscription_billing, and payment_gateway are:
  • optional modules in this repository; or
  • an official separately composed extension/control-plane repository.
• Define platform/control-plane actor versus tenant actor boundaries.
• Define ownership of tenant records, subscriptions, invoices, provider references, usage records, and entitlements.
• Define allowed dependency directions and capability/event contracts.
• Define tenant provisioning and tenant lifecycle state machines.
• Define subscription, invoice, payment, refund/credit, and dunning state boundaries without creating ERP accounting semantics.
• Define online-provider applicability and LAN/offline behavior.
• Define data classification, retention, legal hold, audit, privacy, and incident boundaries.
• Define platform operator, billing operator, support operator, tenant owner/admin, and automation identities.
• Define failure, retry, compensation, reconciliation, and rollback principles.
• Record module admission decisions using existing governance and update architecture/derived-app guides.

Out of scope

• Runtime implementation, migrations, provider integration, or UI.
• Selecting one mandatory payment vendor.
• General ledger, AR/AP, tax engine, inventory, POS, marketplace, or vertical application logic.

Security requirements

• Platform role must not become a hidden PostgreSQL BYPASSRLS path.
• Cross-tenant support access must be explicit, reason-bound, time-bound where appropriate, and audited.
• Provider/network calls stay outside database transactions.
• Secret ownership and rotation must be explicit; no secrets in tenant-readable tables.
• Downgrade/suspension must fail safely while preserving data.
• High-risk operator actions require explicit permissions and SoD/step-up guidance.

Acceptance criteria

• ADR and module-admission records are accepted for every proposed control-plane module.
• Control-plane versus tenant-plane data ownership is unambiguous.
• Dependency/capability/event map contains no reverse dependency from base/core into application-specific SaaS logic.
• State-machine diagrams cover provisioning, tenant lifecycle, subscription, invoice, and payment outcomes.
• LAN/offline behavior and full-online provider behavior are explicit.
• Threat model covers cross-tenant access, operator abuse, webhook replay, duplicate billing, provider outage, downgrade data loss, and secret leakage.
• No implementation child issue may merge before its relevant admission decision is accepted.

Testing and documentation

• Run docs, ADR, Mermaid, module-governance, and repository-inventory checks.
• Add architecture decision examples to agent skills so future issues preserve the boundary.
• No behavior changes; changeset policy should be evaluated according to repository rules.

Dependencies

None. This issue blocks #870 onward.