govoplan-idm/docs/TYPED_RELATIONSHIPS.md

Typed groups and effective-dated relationships

IDM owns tenant-scoped business group facts and the effective-dated links from identities to those groups. Identity lifecycle state remains owned by Identity; an active group membership never activates an identity and never grants an application permission.

Contract

The idm.relationships capability exposes immutable Core DTOs. Consumers can:

• list typed groups without importing IDM persistence models;
• resolve one or many identities to their current relationships;
• resolve one or many groups to current identities at a caller-supplied time;
• request a membership decision set that includes future, expired, revoked, inactive-group, and inactive-identity exclusions;
• retain source provider, external resource, revision, typed properties, and provenance data in downstream evidence.

Cross-tenant group references are rejected. The contract carries facts only and does not imply a right, role, or permission.

Persistence and lifecycle

idm_typed_groups stores the stable tenant/type/key identity and external source reference. idm_identity_relationships stores one identity-to-group or identity-to-identity link, its relationship kind, validity window, source, properties, provenance, and optimistic revision.

Create, change, revoke, and elapsed-validity transitions emit versioned platform events:

• idm.typed_group.created.v1
• idm.typed_group.changed.v1
• idm.relationship.created.v1
• idm.relationship.changed.v1
• idm.relationship.revoked.v1
• idm.relationship.expired.v1

The existing IDM lifecycle worker claims an elapsed relationship and records its event marker in the same transaction. Repeated or concurrent sweeps therefore do not publish duplicate expiry events.

Administration workspace

The /idm workspace exposes typed groups and effective relationships to users with idm:relationship:read. Mutations require idm:relationship:write; the write permission also permits the identity search used by the subject and related-identity selectors without broadening read-only relationship access.

Group and relationship editors retain external provider, resource, revision, property, and provenance values. Updates carry the loaded optimistic revision, so a stale editor receives a conflict instead of overwriting another administrator's change. The relationship directory distinguishes future, active, expired, and revoked states from the validity window and lifecycle record. Revocation requires a reason, takes effect immediately, and leaves the record immutable as evidence.

The membership inspector accepts an effective time and one or more relationship kinds. It shows both included and excluded decisions with stable reason codes and identity lifecycle state. This is the same resolution contract used by downstream consumers; it is not a preview with different semantics.

Distribution Lists

When Distribution Lists is enabled, an idm_group entry resolves through this capability. Every effective identity becomes an internal-mail candidate when an active linked account exists. Every rejected relationship remains visible in the expansion evidence with a stable reason code. Distribution Lists stores only the provider reference and frozen expansion evidence, not IDM records.