feat(tenant-entitlement): compute and enforce effective features, modules, quotas, and overrides #871

Parent epic: #868
Depends on: #869, #870

Context

Plan definitions do not protect anything until effective entitlements are resolved and enforced consistently. Existing module management supports tenant module lifecycle, but SaaS entitlements must remain a separate commercial/access layer and must not silently disable or delete tenant data.

Objective

Implement a tenant-entitlement capability that derives effective feature/module/quota access from a published offer version plus controlled overrides and exposes one default-deny enforcement contract to modules and derived applications.

Scope

• Add admitted module/extension descriptor, permissions, capability port, events, and navigation.
• Add schema for entitlement assignments, effective dates, source/reason, overrides, revocations, and evaluation snapshots/history as approved by docs(saas-control-plane): decide module admission, control-plane boundary, trust model, and lifecycle contracts #869.
• Resolve effective entitlements from:
  • subscription/offer version;
  • trial/grace policy;
  • platform-approved add-on/override;
  • suspension/lifecycle restrictions;
  • module dependencies and safe downgrade rules.
• Expose pure evaluation and transaction-aware enforcement helpers for:
  • feature allowed/denied;
  • module entitled/not entitled;
  • quota limit and remaining allowance;
  • effective period and source explanation.
• Integrate with module presets/lifecycle without equating entitlement with module installation or deleting disabled data.
• Provide bounded read APIs and controlled assign/override/revoke APIs.
• Emit entitlement-changed events and invalidate derived caches/projections deterministically.
• Add admin UI for effective entitlement explanation and time-bound overrides.
• Audit all override/revoke actions; reason required.

Out of scope

• Usage counting implementation (feat(usage-metering): add idempotent usage events, aggregation, quotas, corrections, and reconciliation #875).
• Subscription state and invoice generation (feat(subscription-billing): add subscription, invoice, credit, renewal, and dunning state machines #876).
• Tenant-specific arbitrary policy code.
• Deleting data when an entitlement is lost.

Security and integrity requirements

• Default deny for unknown feature/quota keys.
• Commercial entitlement cannot grant an authorization permission the actor does not hold; RBAC/ABAC/RLS remain authoritative.
• Tenant-supplied headers/body values are not trusted as entitlement facts.
• Overrides are platform-operator only, explicit, reason-bound, optionally time-bound, and audited.
• Cross-tenant reads/writes are denied by database and application controls.
• Entitlement changes are concurrency-safe and idempotent.
• Effective evaluation is bounded and must avoid per-request N+1 catalog queries.

Acceptance criteria

• Effective feature/module/quota state is deterministic and explainable for a tenant and timestamp.
• Unknown keys fail closed.
• Expired/revoked overrides cease to apply without restart.
• Entitlement loss does not delete tenant data.
• Module entitlement and module enabled-state remain distinct but coordinated.
• RBAC/ABAC denial cannot be bypassed by a positive entitlement.
• Tenant A entitlements never affect tenant B.
• Derived modules can register reviewed feature/quota keys through the static composition contract.
• API/UI/events/audit/docs are synchronized.

Testing

• Unit tests for precedence, effective dates, overrides, suspension, unknown keys, and explanation output.
• PostgreSQL integration tests for RLS, constraints, concurrency, revocation, and event same-commit behavior.
• Cross-tenant and authorization-negative tests.
• Contract test with a dummy derived-module feature and quota.
• Performance/query-count test for effective-entitlement resolution.
• E2E admin override/revoke and tenant-visible explanation.
• Mutation test: changing unknown-key behavior to allow must fail.

Documentation

• ERD/data dictionary, permission matrix, capability contract, OpenAPI/AsyncAPI, downgrade behavior, admin/operator SOP, module README, and changeset.

Dependencies

Consumed by #872 provisioning, #873 lifecycle, #875 usage metering, and #876 subscription billing.