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