feat(organization-structure): add optional legal entities, organization units, hierarchies, and effective-dated assignments #749

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

Context

Many derived applications need reusable organization primitives: legal entity, department, branch, cost center, warehouse, operational location, or program unit. These are business/operational scopes inside a tenant; they are not tenant records and must not weaken tenant isolation.

This should be an optional reusable business-foundation capability, not a mandatory Core dependency and not an ERP implementation.

Objective

Add an optional, tenant-scoped organization-structure module with legal entities, typed organization units, effective-dated hierarchies, operational locations, and assignments exposed through capability ports.

Scope

• Complete module-admission decision/ADR before scaffold and confirm category, owner, lifecycle, and offline compatibility.
• Add tenant-scoped legal-entity records with minimal neutral metadata, status, effective dates, and stable identifiers.
• Add configurable organization-unit types and units with effective dates.
• Add versioned/effective-dated parent-child hierarchy records with no-cycle validation and history preservation.
• Add operational-location records and location-to-unit relationships; geospatial coordinates remain optional and validated.
• Add effective-dated party/user assignments to units and optional positions/responsibilities without implementing HR/payroll.
• Add hierarchy and scope-resolution capability ports consumed by feat(identity-access): add reusable business-scope assignments and segregation-of-duties policy hooks #746; no direct import from identity-access.
• Add tenant-safe CRUD/list/search/tree/as-of endpoints and accessible admin UI.
• Add import seed hooks through the future data-exchange contract, but do not make feat(reference-data): add effective-dated value sets and module-contributed reference catalogs #750 or feat(data-exchange): add staged import, validation, preview, idempotent commit, export, and reconciliation #752 a hard runtime dependency unless admitted.
• Add organization lifecycle events to AsyncAPI and feat(domain-events): add transactional event outbox, idempotent consumers, retries, ordering, and dead-letter handling #742 when available.
• Add metrics for active units, hierarchy depth, invalid/cyclic attempts, and expiring assignments.

Security and integrity requirements

• Tenant and legal entity remain distinct concepts in schema, API, documentation, and tests.
• All tenant tables use tenant_id, ENABLE + FORCE RLS, tenant-first indexes, default-deny permissions, and least-privilege roles.
• Hierarchy writes use concurrency control and validate no self-parent/cycle/overlapping invalid periods.
• Reorganization does not rewrite historical assignments or past hierarchy state.
• Cross-tenant parent, location, legal entity, unit, and assignment references are rejected.
• Delete behavior is soft-delete/deactivate by default; referenced/effective history is preserved.

Out of scope

• Tenant provisioning or subscription management.
• Chart of accounts, inventory, warehouse stock, HR, payroll, tax, organizational payroll positions, or government-specific organization rules.
• Treating branch or legal entity as an RLS tenant boundary.

Acceptance criteria

• Admission decision and ADR classify the module and dependencies before implementation.
• Legal entity is demonstrably not identical to tenant in schema/API/docs/tests.
• Unit types, units, locations, relationships, and assignments support effective dates and as-of queries.
• Cycle, self-parent, invalid period, and cross-tenant relationships are rejected.
• Reorganization preserves historical hierarchy/assignment views.
• Hierarchy/scope capability port is usable by identity-access without direct table imports/writes.
• CRUD/tree/list/search endpoints are paginated where appropriate, permission-gated, audited for high-risk changes, and accessible in UI.
• Cross-tenant RLS/ABAC, no-cycle, concurrency, effective-date, reorganization, soft-delete, and capability-port tests pass.
• OpenAPI/AsyncAPI, ERD/data dictionary, architecture/admission docs, threat model, 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.