Sync Repo-docs-MODULE-ARCHITECTURE from project files

Repo-docs-MODULE-ARCHITECTURE.-.md

@@ -1,4 +1,4 @@
-<!-- codex-wiki-sync:0f7bb6be739af735cbaade1b -->
+<!-- codex-wiki-sync:0b250b14c736a0cc7e27f2c5 -->
 
 > Mirrored from `/mnt/DATA/git/govoplan-core/docs/MODULE_ARCHITECTURE.md`.
 > Origin: `repository`.
@@ -40,7 +40,14 @@ The kernel must not own product semantics such as users, tenants, RBAC decisions
 
 ## Current Compatibility Responsibilities
 
-During the staged split, `govoplan-core` still contains compatibility surfaces for access, auth, tenancy, RBAC, governance, audit, CSRF/API helpers, and secret helpers. The extracted access seed implementation now lives in `govoplan-access`; core keeps import shims and live legacy routes/models until the remaining ownership moves finish. These paths are temporary compatibility surfaces until the matching platform modules exist:
+During the staged split, `govoplan-core` still contains compatibility surfaces
+for access, auth, tenancy, RBAC, governance, audit, CSRF/API helpers, and
+secret helpers. The extracted access implementation now lives in
+`govoplan-access`; live legacy ORM table definitions have been split across
+their platform owners while retaining historical table names, and core keeps
+import shims until all callers move to module-owned imports or kernel
+capabilities. These paths are temporary compatibility surfaces until the
+matching platform modules are fully self-contained:
 
 - `govoplan-access`
 - `govoplan-tenancy`
@@ -85,17 +92,33 @@ Known access-related capability names are defined in
 `govoplan-access` currently registers `access.principalResolver`,
 `access.permissionEvaluator`, `access.directory`, and
 `access.tenantProvisioner`. `govoplan-tenancy` registers
-`tenancy.tenantResolver`. Feature modules should prefer these capabilities over
+`tenancy.tenantResolver`. The minimal authenticated platform set is now
-direct reads of access/tenant ORM models when they need labels, group
+`tenancy` plus `access`; the registry inserts `tenancy` before `access` when
-membership, default access provisioning, or tenant metadata.
+only feature modules are requested. Feature modules should prefer these
+capabilities over direct reads of access/tenant ORM models when they need
+labels, group membership, default access provisioning, or tenant metadata.
+
+Current live table ownership:
+
+- `govoplan-tenancy`: `tenants`
+- `govoplan-access`: `accounts`, `users`, `groups`, `roles`,
+  `system_role_assignments`, `user_group_memberships`,
+  `user_role_assignments`, `group_role_assignments`, `api_keys`,
+  `auth_sessions`
+- `govoplan-admin`: `governance_templates`,
+  `governance_template_assignments`
+- `govoplan-audit`: `audit_log`
+- `govoplan-core`: `system_settings`
 
 Cross-module feature contracts live under focused kernel contract modules. For
 example, `govoplan_core.core.campaigns` defines
-`campaigns.mailPolicyContext` and `campaigns.access`. The campaign module
+`campaigns.access`, `campaigns.mailPolicyContext`,
-registers these capabilities so mail can resolve campaign owner/policy context
+`campaigns.policyContext`, `campaigns.deliveryTasks`, and
-and files can validate campaign file-share access without importing campaign ORM
+`campaigns.retention`. The campaign module registers these capabilities so mail
-models. Keep these contracts small DTO/protocol surfaces and register concrete
+can resolve campaign owner/policy context and delivery tasks, files can validate
-behavior from the owning module.
+campaign file-share access, and core retention can call campaign-owned cleanup
+logic without importing campaign ORM models. Keep these contracts small
+DTO/protocol surfaces and register concrete behavior from the owning module.
 
 ## Module Responsibilities
 
@@ -156,6 +179,9 @@ Rules:
 - Keep module-owned tables and migrations in the module repository.
 - Keep cross-module foreign-key assumptions explicit and conservative.
 - Register module metadata in `MigrationSpec` so core can discover it.
+- Optional module migrations may create multiple Alembic heads. Verification
+  should compare the database heads to the configured script heads instead of
+  assuming one linear revision when multiple modules are enabled.
 
 ## WebUI Contract
 
@@ -194,6 +220,7 @@ Modules must provide icon names with `iconName` in frontend nav contributions an
 Current core icon names include:
 
 - `activity`
+- `admin`
 - `campaign`
 - `dashboard`
 - `file`
@@ -206,6 +233,9 @@ Current core icon names include:
 
 If a module needs a new navigation icon, add the name-to-component mapping in core first, then use the name in backend and frontend metadata.
 
+The access module uses the `admin` icon for its `/admin` route. Core only
+resolves that icon name; it does not hard-code the admin route in the rail.
+
 ## Shared Component Rules
 
 Use this rule of thumb:
@@ -242,9 +272,11 @@ The repository includes `scripts/check_dependency_boundaries.py`. It enforces th
 - access source may not import files/mail/campaign internals
 - feature modules may not import access implementation internals
 - feature modules may not add new direct imports of sibling feature modules
-- known transitional exceptions are listed in the script with a reason
+- the transitional allowlist is expected to stay empty
 
-Every exception is extraction debt. When a capability/API/event contract replaces an exception, remove it from the allowlist.
+Any future exception is extraction debt and must be temporary, documented in the
+script with a reason, and removed when a capability/API/event contract replaces
+it.
 
 ## Build And Verification