# Identity Model

The identity model answers who the platform subject is, independent of how they
authenticate and independent of what they may do.

## Layers

- Identity: a person, service, or other subject known to GovOPlaN.
- Account link: a reference from that identity to one platform account.
- Primary account: the account used as the default display/explainability
  anchor when multiple accounts exist.

## Lifecycle semantics

An active identity is eligible for ordinary directory search. Deactivation
removes it from default search results but does not delete the identity, its
account links, their source provenance, or the primary-account marker. Direct
identifier/account resolution retains the record with an explicit `inactive`
status so Access and reconcilers do not mistake deactivation for absence.
Authorized lifecycle owners may also include inactive identities in search and
may reactivate them. Deactivation is therefore a reversible directory-state
change, not account suspension or erasure; Access owns those separate
consequences.

Each account link records the origin of the accepted association in `source`
(for example `local` or an IDM reconciliation source). The source is provenance,
not authorization and not proof that the external source remains reachable.
Changing the primary account never rewrites this origin.

An identity may retain multiple account links but has at most one primary
account. A primary-account change may select only an existing link belonging to
that identity, atomically demotes the previous primary, preserves every link,
and records old/new account ids plus link-source provenance in the audit log.
The lifecycle service does not commit: its caller authorizes the operation and
commits the state and audit record together, or rolls both back on validation,
audit, or persistence failure. Repeating the already-effective selection is a
no-op and does not create misleading audit activity.

## Boundary With Access

Access owns authorization. Identity only tells access which identity is behind
an account. Access can then evaluate roles, rights, delegation, and policy.

## Boundary With Organizations

Organization functions live in `govoplan-organizations`.
Identity-to-function assignments live in `govoplan-idm`. Those assignments may
reference identity and account IDs, but identity does not own organizational
structure or assignment workflows.

## Boundary With IDM

`govoplan-idm` imports, previews, reconciles, and applies external identity
facts. Once accepted, normalized identity records belong here.

## Access Projection Migration

`govoplan-access` now prefers `identity.directory` when it needs to resolve the
identity behind an account or render identity labels in semantic access views.
If the identity module is not installed, Access falls back to the legacy
`access_identities` and `access_identity_account_links` projection tables.

Rollout plan:

- keep the Access projection tables readable until existing installations have
  a backfill path;
- backfill `identity_identities` and `identity_account_links` from the Access
  projection where Identity is newly installed on an existing deployment;
- keep Access writes that still create local accounts able to maintain the
  projection during the compatibility window;
- once deployments use `identity.directory` consistently, retire direct Access
  identity reads and leave the projection tables as migration-only data until a
  release-level retirement plan removes them.

The close-out condition is that Access works with canonical Identity installed
and still works without it through the projection fallback.

## Administration surface

Identity now exposes a system-scoped administration API and an embedded
administration workspace. Administrators can create, inspect, update,
deactivate, and reactivate identities, then add or remove opaque platform
account references and promote one link as primary. The first account link is
made primary automatically. A primary link cannot be removed while another
link remains; the replacement must be promoted first.

The current tenant is retained as the actor context, but it does not make the
canonical identity record tenant-owned. Every mutation is therefore written as
a system-scoped audit event. Identity does not inspect account credentials or
authorization state and does not treat deactivation as account suspension.
IDM continues to own external import and reconciliation decisions.