# 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.