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.

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.