feat: add access module boundary migrations

docs/ACCESS_MODULE_BOUNDARY.md

@@ -0,0 +1,157 @@
+# GovOPlaN Access Module Boundary
+
+`govoplan-access` is the platform module that owns login identity and runtime
+authorization state. Core remains the kernel: it composes modules, mounts
+routes, owns process/database lifecycle, and exposes stable capability
+contracts.
+
+## Access-Owned Capabilities
+
+`govoplan-access` owns the canonical implementation for:
+
+- accounts and global login identity
+- interactive authentication routes and session lifecycle
+- API-key creation, verification, revocation, and scope delegation
+- tenant-local users, memberships, groups, roles, and role assignments
+- identity-to-account projection used for explainability
+- organization-bound functions, function assignments, and delegation facts
+- principal resolution and request authentication dependencies
+- permission evaluation for access-owned scopes and legacy access aliases
+- access-decision explain output with identity/account/function/role/right
+  provenance
+- access administration backend routes for users, groups, roles, system
+  accounts, sessions, and API keys
+- access administration WebUI route contribution for `/admin`
+- tenant owner provisioning and default access bootstrap
+- materializing governance templates into access-owned groups and roles
+- access-owned SQLAlchemy metadata and migrations for `access_*` tables
+
+The active access tables use the `access_*` namespace while the model classes
+live in this module: `access_accounts`, `access_users`, `access_groups`,
+`access_roles`, `access_system_role_assignments`,
+`access_user_group_memberships`, `access_user_role_assignments`,
+`access_group_role_assignments`, `access_api_keys`, and
+`access_auth_sessions`.
+
+## Kernel-Owned Contracts
+
+`govoplan-core` owns the stable contracts that let modules interact without
+importing access internals:
+
+- `ModuleManifest`, route factories, migration specs, and registry validation
+- database engine/session lifecycle and migration orchestration
+- capability registry and capability names in `govoplan_core.core.access`
+- access DTO/protocol contracts such as `PrincipalRef`, `AccountRef`,
+  `UserRef`, `GroupRef`, `RoleRef`, `IdentityRef`,
+  `OrganizationUnitRef`, `FunctionRef`, `FunctionAssignmentRef`,
+  `FunctionDelegationRef`, `AccessDecisionProvenance`,
+  `PrincipalResolver`, `AccessDirectory`, `AccessSemanticDirectory`,
+  `PermissionEvaluator`, `AccessExplanationService`,
+  `TenantAccessProvisioner`, `AccessAdministration`, and
+  `AccessGovernanceMaterializer`
+- health, platform metadata, and module startup ordering
+- generic security helpers that are not access-state semantics, such as
+  secret encryption and UTC time helpers
+
+Feature modules should depend on these kernel contracts or the published
+`govoplan_access.auth` request dependency API, not on access ORM models or
+`govoplan_access.backend.*` implementation internals.
+
+## Principal Context Contract
+
+The stable runtime principal is `govoplan_core.core.access.PrincipalRef`.
+Access resolves request credentials into that DTO and `ApiPrincipal` keeps the
+legacy ORM objects only for routers that have not yet moved to pure kernel
+contracts. New module code should pass around `PrincipalRef` or primitive IDs.
+
+`PrincipalRef.to_dict()` is the canonical API/WebUI serialization shape:
+
+- `account_id`, `membership_id`, and `tenant_id`
+- optional `identity_id`
+- sorted `scopes`, `group_ids`, `role_ids`, `function_assignment_ids`, and
+  `delegation_ids`
+- `auth_method` plus optional `session_id`, `api_key_id`, or
+  `service_account_id`
+- optional `acting_for_account_id` for acting-in-place flows
+- optional display fields `email` and `display_name`
+
+`/api/v1/auth/me`, `/api/v1/auth/login`, profile refreshes, and tenant switches
+include this payload as `principal` alongside the existing compatibility
+fields. Modules that need current user context should prefer
+`auth.principal`/`AuthInfo.principal` in the WebUI and
+`principal.to_platform_principal()` in backend request handlers.
+
+## Identity And Function Boundary
+
+The full semantic model is documented in
+[IDENTITY_ACCOUNT_FUNCTION_MODEL.md](IDENTITY_ACCOUNT_FUNCTION_MODEL.md).
+In short:
+
+- `govoplan-idm` imports and previews external identity and organization facts
+  from IDM systems.
+- `govoplan-identity` owns canonical identities and identity/account links.
+- `govoplan-organizations` owns canonical organization units, functions, and
+  account-held function assignments.
+- `govoplan-access` owns the authorization projection that maps organization
+  and identity facts to roles, rights, delegation enforcement, and explainable
+  permission decisions.
+
+Function assignments are account-held and organization-scoped. They can apply
+only to the selected organization unit or to that unit and all subunits.
+Delegation and acting-in-place must remain explicit facts with audit
+provenance; modules must not infer either from plain group membership.
+
+The backend foundation exposes these administration routes:
+
+- `/api/v1/admin/identities`
+- `/api/v1/admin/organization-units`
+- `/api/v1/admin/functions`
+- `/api/v1/admin/function-assignments`
+- `/api/v1/admin/function-delegations`
+
+Dedicated WebUI management panels and explicit acting-in-place context
+selection are still follow-up work on top of these routes.
+
+## Removed Compatibility Paths
+
+These legacy imports were removed from core. Use access-owned modules, the
+public `govoplan_access.auth` request dependency API, or kernel capabilities
+instead:
+
+- `govoplan_core.security.api_keys`
+- `govoplan_core.security.sessions`
+- `govoplan_core.security.passwords`
+- `govoplan_core.api.v1.auth`
+- `govoplan_core.api.v1.admin`
+- `govoplan_core.api.v1.admin_schemas`
+- `govoplan_core.admin.service`
+- `govoplan_core.admin.governance`
+
+HTTP route compatibility remains at the API layer: the access manifest
+contributes the same `/api/v1/auth/*` and `/api/v1/admin/*` paths through module
+route aggregation.
+
+## Route Ownership
+
+The access manifest contributes the `/api/v1/auth/*` interactive auth routes
+and the access-owned `/api/v1/admin/*` administration routes through its module
+route factory. Core default server configuration must not register auth or
+admin routers as base routers.
+
+Governance-template metadata CRUD is not access-owned. It is contributed by
+`govoplan-admin`; access only materializes those templates into access-owned
+groups and roles through the `access.governanceMaterializer` capability.
+
+## Verification References
+
+Focused verification is run from `/mnt/DATA/git/govoplan-core`.
+
+- `tests.test_module_system` verifies manifest discovery, access startup in
+  module permutations, admin route ownership, governance-template route
+  separation, and legacy compatibility imports.
+- `tests.test_api_smoke.ApiSmokeTests.test_cookie_session_requires_csrf_for_mutations`
+  verifies the access-owned session/auth route behavior.
+- `tests.test_api_smoke.ApiSmokeTests.test_tenant_user_group_role_and_api_key_administration`
+  verifies access-owned administration and API-key behavior.
+- `tests.test_api_smoke.ApiSmokeTests.test_profile_refresh_and_system_role_protection_model`
+  verifies profile/session refresh and protected system role behavior.