feat(reference-data): add effective-dated value sets and module-contributed reference catalogs #750

Parent epic: #738
Depends on: #739
Admission requirement: apply docs/awcms-mini/21_module_admission_governance.md before implementation.

Context

The repository now contains a specific Indonesia administrative-regions module, but it does not provide a generic, effective-dated reference-data foundation for reusable code sets such as currencies, units of measure, fiscal calendars, document classifications, or module-owned value sets. Derived modules need a controlled way to contribute catalogs without direct imports, mutable hardcoded enums, or destructive replacement of codes already referenced by data.

Objective

Add an optional provider-neutral reference-data capability with value sets, codes, localization, provenance, effective dates, deprecation, global baseline/tenant override rules, validated import, and module-contributed catalogs.

Scope

• Complete module-admission decision/ADR before scaffold.
• Define value-set metadata: stable key, owner module, scope, version/provenance, description, lifecycle, override policy, and validation schema.
• Define code entries with stable code/key, localized labels/descriptions, sort order, metadata, valid_from/valid_to, deprecation/supersession, and provenance.
• Support clearly separated catalog scopes:
  • code-defined/module-contributed baseline;
  • deployment/global curated baseline where allowed;
  • tenant override/extension where allowed by each value set.
• Define deterministic precedence and as-of resolution; unknown/ambiguous codes fail safely.
• Add static module contribution descriptors and validation during composed-registry checks.
• Add tenant-safe CRUD/list/search/version/history/preview APIs and accessible admin UI for mutable catalogs.
• Add validated import/update workflow with dry-run, diff, provenance, checksum, idempotent commit, and rollback/recovery notes.
• Provide seed packs or fixtures for currency, unit-of-measure, and fiscal-calendar references only as neutral examples; authoritative data sources and update ownership must be documented.
• Add capability ports for resolving codes and exposing safe snapshots to modules.
• Add lifecycle events to AsyncAPI/feat(domain-events): add transactional event outbox, idempotent consumers, retries, ordering, and dead-letter handling #742 when available.
• Define how existing specialized catalogs such as idn_admin_regions remain module-owned and may expose compatible ports without migrating all data into the generic tables.

Security and integrity requirements

• A code already referenced by business data is never silently deleted or repurposed in place; deprecate/supersede instead.
• Tenant override cannot mutate global/module baseline rows or affect another tenant.
• Module owner and override policy are enforced server-side, not trusted from request input.
• Import is schema/size bounded, staged, permission-gated, checksummed, and audited.
• Reference data contains no executable expressions, SQL, templates, secrets, or unbounded arbitrary metadata.
• RLS applies to tenant-owned overrides; reviewed global baseline tables are explicitly documented if RLS-exempt.

Out of scope

• Replacing specialized administrative-region governance or copying every external standard into the repository.
• Product/item catalogs, chart of accounts, tax rules, payroll rules, or domain master data.
• Real-time external provider calls during reference resolution.

Acceptance criteria

• Admission decision/ADR confirms module category, ownership, dependencies, and offline behavior.
• Value sets and codes support localization, provenance, effective dates, deprecation, supersession, and as-of lookup.
• Baseline versus tenant override precedence is deterministic and tested.
• Used codes cannot be deleted or semantically repurposed in place.
• Module-contributed catalogs compose without direct source import or direct table writes.
• Currency, UoM, and fiscal-calendar fixtures demonstrate the contract without claiming comprehensive regulatory authority.
• Existing idn_admin_regions ownership remains clear and no duplicate region dataset is introduced.
• Import dry-run/diff is non-mutating; commit is idempotent, audited, and recoverable.
• Cross-tenant RLS/ABAC, precedence, effective-date, deprecation, import bounds/checksum, and capability-port tests pass.
• OpenAPI/AsyncAPI, ERD/data dictionary, architecture/admission docs, provenance/update SOP, admin/user guide, repository inventory, and changeset are updated.
• bun run modules:dag:check, bun run api:spec:check, bun run security:readiness, tests, build, and bun run check pass.