Define group retirement and retained-state disposition

[nathanhruby]

Question

After a group enters pending retirement and its owner-cancellable recovery window ends, what preconditions and operator approval govern permanent purge; does retirement honor, accelerate, or override the current per-version retention policy; what happens to memberships, pending invitations, the shared Terraform credential, logical-state identity markers, retained versions, immutable group identity, display name, and administrative history; and which records, identities, or names may later be restored or reused?

[nathanhruby]

Resolution

Entering pending retirement

• One owner may request retirement for an active group after an explicit destructive-impact warning.
• A suspended group may enter pending retirement only through a system operator.
• The retirement transition and security audit event commit atomically.
• A repeated request while already pending returns 409 Conflict and does not reset the request time or create another audit event.
• Pending retirement freezes the Terraform data plane but leaves the administrative control plane available. Membership and invitation administration, invitation acceptance, credential lifecycle actions, display-name changes, and retention-policy changes may continue.
• Administrative changes made while pending survive cancellation; there is no retirement-time snapshot to restore.

Dynamic recovery period and cancellation

• The recovery period is the group's current retention policy, measured from its latest retirement request.
• Eligibility is dynamic like version cleanup eligibility: reducing retention may make the group immediately retirement-eligible, while increasing retention may make an eligible but not-yet-purged group ineligible again.
• Any owner may cancel while the group is not retirement-eligible. Only a system operator may cancel while it remains eligible. An operator may cancel at any point before authoritative purge commits.
• Extending retention enough to make the group ineligible restores owner cancellation authority.
• Cancellation restores the status preceding retirement: active returns to active and operator-suspended returns to suspended.
• Cancellation and its security audit event commit atomically.
• A later retirement request begins a new recovery period from its own request time. Earlier attempts remain in permanent audit history.
• While a group is pending, every retention-policy change and its security audit event commit atomically. A reduction must warn that it may make the entire group immediately purge-eligible.

Automatic purge

• Explicit operator authorization is no longer required. This supersedes that part of Define group roles and membership lifecycle.
• Regular scheduled cleanup queries retirement-eligible groups, processes them sequentially without claims or an intermediate status, and immediately rechecks each group before purge.
• A remaining Terraform lock does not postpone purge and is removed with the group.
• Cancellation or a retention extension committed before the recheck prevents purge. Once authoritative purge commits, retirement is final.

Interaction with state retention

• Pending retirement does not change version lifecycle. Existing non-current versions remain subject to normal retention cleanup, while current versions remain current and retained.
• Final group purge overrides version retention and removes every remaining state version and logical-state marker.
• Retirement retains no state document or state metadata for later recovery.

Authoritative purge and retries

One database transaction must recheck eligibility; create the permanent retired-group marker; remove operational group data, memberships, invitations, logical-state and version metadata, the credential verifier, the wrapped group key, and remaining locks; preserve a non-authenticating reservation of the credential username; and write the successful-purge security audit event. Audit failure rolls back the transition.

Physical encrypted-object deletion remains outside the database transaction:

• A database-transition failure leaves the group pending and eligible for a later scheduled retry.
• After authoritative purge commits, residual objects are inaccessible because their metadata and wrapped key are gone.
• Physical deletion failures become orphan-reconciliation work and never restore the group.
• Failed purge attempts go to operational logs and metrics rather than permanent security audit events.
• A cancellation or purge race is decided by database commit order. Cancellation committed first prevents purge; purge committed first is irreversible.

Permanent disposition

A retired group retains only:

• its immutable machine identity;
• original creation time;
• latest retirement-request time;
• completed purge time;
• a non-authenticating reservation of its Terraform credential username; and
• permanent security audit history visible only to system operators.

Purge removes the mutable display name, memberships, invitations, operational credential and verifier, locks, logical-state markers, version metadata, state documents, and wrapped group key material. User identities and their relationships with other groups are unaffected.

Immutable group and route identifiers and Terraform credential usernames are never reused. Human-facing display names may be reused. A retired group cannot be restored or recreated by an owner or operator. Former owners and members have no visibility into the retired marker; operators may view it and permanent audit history. Old Terraform credentials receive the same generic 401 as any unknown credential.

Backup boundary

Application-level purge guarantees removal from the live application. Host backup retention remains an infrastructure responsibility; United does not edit historical backups. Whole-system disaster recovery must avoid silently reactivating already-retired groups.

The canonical vocabulary for pending retirement, retirement eligibility, retired groups, permanently reserved credential usernames, and permanent security audit events is recorded in CONTEXT.md.