feat(saas-contracts): add static feature, quota, meter, and commercial-event registries with conformance gates #874

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

Context

Service catalog, entitlements, usage metering, and derived applications need shared identifiers for features, quotas, meters, aggregation semantics, and commercial events. Free-form strings would allow silent drift between plan definitions, enforcement code, meter producers, and billing consumers.

Objective

Add deterministic build-time SaaS contract registries and conformance gates that allow reviewed derived modules to contribute commercial capability metadata without runtime code loading.

Scope

• Define versioned descriptor contracts for:
  • feature keys and descriptions;
  • quota keys, units, reset periods, and enforcement mode;
  • meter keys, event version, quantity/value type, aggregation rule, correction semantics, and privacy classification;
  • billable versus informational classification;
  • lifecycle/commercial domain-event identifiers.
• Merge base and application contributions using the existing deterministic module-composition seam.
• Reject duplicate keys, incompatible versions, unknown owners, unsafe units, unbounded values, and conflicting aggregation semantics.
• Generate machine-readable inventories and human-readable documentation.
• Add compatibility-manifest integration so derived repositories declare the supported SaaS contract version/range.
• Add CI/check scripts for registry freshness, source ownership, event/AsyncAPI parity, and catalog/entitlement/meter references.
• Provide test fixtures for a dummy derived module.

Out of scope

• Persisting usage events (feat(usage-metering): add idempotent usage events, aggregation, quotas, corrections, and reconciliation #875).
• Defining plan prices (feat(service-catalog): add versioned SaaS plans, features, quotas, pricing, and offer lifecycle #870) or subscriptions (feat(subscription-billing): add subscription, invoice, credit, renewal, and dunning state machines #876).
• Runtime registry installation or tenant-authored descriptors.
• Application-specific business calculations in the base.

Security and integrity requirements

• Descriptors are trusted source code reviewed at build time.
• Unknown or conflicting keys fail the build and fail runtime validation closed.
• Privacy classification must be explicit; descriptors cannot request raw sensitive payload storage by default.
• Meter quantity types and bounds must prevent overflow, NaN, negative-value abuse unless correction semantics explicitly permit signed deltas.
• Contract changes follow semantic versioning and changeset policy.

Acceptance criteria

• Base and derived descriptors merge deterministically.
• Duplicate/incompatible keys and versions fail with actionable messages.
• Catalog, entitlement, and usage code can resolve descriptors from one source of truth.
• Generated inventory lists owner module, version, unit, aggregation, privacy class, and billable status.
• AsyncAPI event identifiers remain synchronized with meter/commercial event descriptors.
• A dummy derived module contributes one feature, quota, and meter without editing base registry files.
• CI and bun run check include the new gates with parity enforcement.

Testing

• Unit tests for merge/order/version/conflict/validation.
• Contract tests for derived compatibility manifest.
• Mutation tests for duplicate key, wrong unit, missing privacy class, and stale generated inventory.
• Build test with and without application registry contributions.

Documentation

• Contract schema/reference, contribution guide, compatibility/versioning policy, generated inventory, relevant skills, and changeset.

Dependencies

Blocks #875 usage metering and must be consumed by #870/#871 implementations rather than creating private key lists.