Sync GovOPlaN module state

README.md

@@ -15,6 +15,9 @@ vendor or protocol.
 
 - inbound synchronization from external identity-management systems
 - identity lifecycle import, update, disable, and reconciliation jobs
+- identity-to-organization-function assignment links inside GovOPlaN
+- bridge views that combine identity and organization facts, such as identity
+  candidates for organization function assignments
 - mapping external identities, accounts, groups, organizational units,
   functions, and attributes to GovOPlaN identity, organization, access, and
   tenancy DTOs
@@ -50,6 +53,77 @@ No feature module should import IDM internals directly. Feature modules should
 ask access, tenancy, or future directory capabilities for normalized identity
 facts.
 
+`govoplan-idm` has hard module dependencies on `govoplan-identity` and
+`govoplan-organizations`, because its core value is connecting those normalized
+facts. Identity remains the owner of identities/accounts. Organizations remains
+the owner of units/functions.
+
+## Current Runtime API
+
+The first runtime API exposes identity lookup and organization-function
+assignment links:
+
+- `GET /api/v1/idm/settings`
+- `PATCH /api/v1/idm/settings`
+- `GET /api/v1/idm/organization-identities`
+- `GET /api/v1/idm/organization-function-assignments`
+- `POST /api/v1/idm/organization-function-assignments`
+- `PATCH /api/v1/idm/organization-function-assignments/{assignment_id}`
+
+The candidate endpoint returns searchable identity/account candidates for IDM
+assignment forms. Assignment writes validate the identity/account link through
+`govoplan-identity` and the function/unit scope through
+`govoplan-organizations`. These endpoints exist only when IDM is enabled, which
+implies both identity and organizations are enabled through module dependency
+planning.
+
+The WebUI exposed by this repository is a normal module UI at `/idm`. It is the
+editing surface for identity-to-organization-function assignment links.
+
+## Migration And Permission Transition
+
+The initial IDM migration creates new IDM-owned tables only. No data is migrated
+from the legacy access/organization assignment tables.
+
+Canonical permissions for assignment work are:
+
+- `idm:organization_identity:read`
+- `idm:organization_assignment:read`
+- `idm:organization_assignment:write`
+- `idm:settings:read`
+- `idm:settings:write`
+
+During the transition, `organizations:function:assign` remains accepted by IDM
+assignment and identity-candidate endpoints as a compatibility scope. New role
+templates and documentation should use the IDM scopes. Organizations remains the
+owner of units and function definitions; IDM owns identity-to-function
+assignment links.
+
+`govoplan-access` can consume IDM assignments through the optional
+`idm.directory` capability when IDM is installed. This is deliberately optional:
+access still works without IDM, and IDM does not require access to store or edit
+assignment links. If the audit module is enabled, IDM records assignment and
+settings audit events; otherwise the assignment API remains usable without an
+audit hard dependency.
+
+An IDM assignment does not grant application permissions by itself. Access grants
+role-derived permissions only when an explicit external function role mapping
+connects the organization function ID to an assignable role. Those mappings are
+managed through the access API at
+`/api/v1/admin/external-function-role-mappings`.
+
+Tenant IDM settings can require recorded change requests before assignment
+creates or updates are applied. The change-control key is
+`idm.organization_assignments`.
+
+Delegated and acting-for assignments are source-specific:
+
+- `delegated` requires a source assignment for the same function, and the
+  organization function must allow delegation.
+- `acting_for` requires a source assignment for the same function, an
+  acting-for account on that source identity, and the organization function must
+  allow acting in place.
+
 ## First Milestone
 
 The first useful milestone is a read-only synchronization preview: