The entity lifecycle
Every principal in the directory, an organization, user, agent, service account, node, or device, moves through one authoritative state machine, shared by all of them. This page follows that arc end to end: create → provision → active → decommission, and everything that attaches, and detaches, at each stage.
Two invariants shape the whole lifecycle:
- No entity exists without a home. A single provisioning act creates a workspace, a storage namespace, a messaging inbox, default streams, an owner membership, and the entity's own cryptographic material, the "unix home directory" rule, applied to identity.
- Disposal is graded and audited. An entity is never simply deleted; it walks a depth-graded teardown, refused while it is under legal hold or still has live children, and a purge issues a hash-chained certificate of destruction.
For the principals this arc applies to, see the entity model; for how authority flows to a principal, see authorization and delegation.
The lifecycle arc
An entity is provisioned through a short chain of directory-aware states before it becomes active, the one operational state. From active it can be suspended (reversible), archived (read-only, restorable), soft-deleted (recoverable within a window), and finally purged (terminal, key material zeroized). Suspend, archive, and soft-delete are all reversible back to active; purge is not.
Figure I1: the entity lifecycle, read left to right. The three neutral
provisioning states must be walked in order, draft cannot jump to active.
Active (green) is the single operational state; suspended and archived
(cyan) are reversible back to it; soft-deleted (amber) is recoverable within a
retention window; purged (red) is terminal and zeroizes key material.
Ceiling: cells are physical instances, not entities, and follow a separate
tombstone path; a legacy retired terminal alias remains for backward
compatibility.
Table equivalent
| State | Reached from | Reversible to active? | What holds true |
|---|---|---|---|
| Draft | (create) | walks forward only | directory-aware, not yet real |
| Registered | Draft | walks forward only | directory-aware, not yet real |
| Enrolled | Registered | walks forward only | directory-aware, not yet real |
| Active | Enrolled; Suspended; Archived; Soft-deleted | : (is active) | full operation; homes and crypto live |
| Suspended | Active | yes | sessions killed, certs revoked; associations, sealed keys, and homes retained |
| Archived | Active | yes (re-issues crypto) | read-only; associations torn down, key bytes retained |
| Soft-deleted | Active; Archived | yes (re-grant explicitly) | recoverable within the retention window |
| Purged | Soft-deleted | no (terminal) | key material zeroized; certificate of destruction issued |
Provision: one act, many resources
Creating an entity is a single provisioning act that fans out into a whole working environment, so that no entity is ever left without a home. The steps run in a fixed order and are idempotent; the default-workspace marking is fail-closed, if it cannot be set, the entire create is aborted.
Figure I2: the provisioning fan-out: one act, N resources. The two green outcomes are cryptographically material (the provisioning act itself, and the X.509 / SSH / PGP credentials issued per the entity's type policy); the workspace carries its inbox, streams, and owner membership. Ceiling: the default-stream set is kind-dependent, a user gets inbox / feed / alerts, while a service account or device gets a reduced set with no feed; a standalone messaging provisioning collaborator is owed, and messaging is currently owned by the workspace primitive.
Table equivalent
| Resource | Owner | Notes |
|---|---|---|
| Crypto material (X.509 / SSH / PGP) | crypto provisioner | every entity-scope credential the type policy requires; idempotent |
| Storage namespace | storage | a dedicated bucket per home |
| Default workspace | workspace | the universal home; marking it default is fail-closed |
| Messaging inbox | workspace | an addressable inbox subject |
| Default streams | messaging | inbox / feed / alerts: kind-dependent (no feed for service accounts or devices) |
| Owner membership | workspace | an owner-role membership row |
| Private catalog + binding | catalog | a private catalog with a self-admin workspace↔catalog binding |
| Capacity shares | capacity | one share row per resource class: "bound first, classify second" |
| Home service-group binding | service group | deliverability; best-effort and idempotent, converges via reconciliation |
The workspace is the universal ownership and collaboration boundary, every entity gets one automatically. See the entity model for how the workspace sits under the principal, and the estate hierarchy for how a service group collects the cells a home is delivered across.
Active: acting, and acting on behalf
Once active, a session binds exactly one entity, and a principal acts as itself. Two other paths let one principal act as another, and the difference between them is entirely in the audit record:
- Owner mode. A human user may switch to a persona they own, a personal or professional lens on the same base identity, and act as it directly. The cheaper, common path, checked first.
- Admin-on-behalf mode. An administrator may act as a non-user entity they administer (an organization, a node) when they hold the admin authority over it. This is audited as impersonation: the entity is observed being acted through, and the admin is recorded as the actor, a symmetric audit that names both principals. Authority is fail-closed: any error in evaluating it denies the action.
The authority check is composed from injected signals, is this entity owned by the caller? and does the caller administer it?, so the same policy generalizes across entity kinds. Today it resolves node and organization authority (both wired to the single node-authority oracle). This mirrors the delegation model described in authorization and delegation.
Admin-on-behalf of an agent, where an agent's identity is administered by its owner, is not yet implemented. The predicate returns "not authorized" for an agent target, so the gate stays fail-closed (it never grants without real authority), but a legitimate agent owner is refused today. This is a recorded gap, not a decision: it needs an ownership resolver of its own rather than being folded into node authority.
Decommission: depth-graded teardown
Decommissioning runs through one orchestrator, which chooses a cascade depth from the target state. Shallow targets retain more; deeper targets tear down more and, at purge, zeroize. Two gates guard the destructive targets, and the whole cascade is idempotent and resumable across a cell crash, every sub-step is a no-op when already applied, and the coarse status is written before the cascade so it survives a mid-teardown interruption.
Figure I3: the teardown cascade, deepening left to right. Two amber gates refuse a destructive transition: an active legal hold blocks soft-delete and purge (suspend and archive are still allowed), and live children block purging a parent (an organization with live members, a node with live cells). The cyan depths are reversible; purged (red) zeroizes key material and issues a green, hash-chained certificate of destruction. Every transition, restore included, appends to the hash-chained audit chain. Ceiling: the local node is the only place its own private CA and key-encryption keys can be destroyed; a remote node's crypto teardown is refused.
Table equivalent
| Target | Sessions | Associations | Certificates | Sealed private keys | Homes | Entity row |
|---|---|---|---|---|---|---|
| Suspended | killed | retained | revoked | retained | retained | live |
| Archived | killed | torn down | revoked | retired, bytes kept | archived | live |
| Soft-deleted | killed | torn down | revoked | soft-deleted, bytes kept | soft-deleted | soft-deleted |
| Purged | killed | torn down | revoked | zeroized + hard-deleted | purged | hard-deleted |
The teardown reaps every entity-owned resource in a fixed order, role and group assignments, data grants, contracts, ownership edges, then the home workspaces, then the crypto material, then a registry of resource reapers (MFA, API keys, device and agent state, credentials, profiles, verifiable credentials, access grants, catalog credentials, shares). A conformance lint asserts that no entity-owned table escapes disposal. External database credentials are revoked at every depth, including suspend, and the step is non-fatal where that subsystem is not deployed.
Break-glass purge and the retention worker
- Break-glass purge is high-friction: the operator must echo the entity's exact display name, or the purge is refused, and a distinct break-glass attestation is hash-chained before the purge runs, so the authorization is recorded even if legal hold then refuses the destruction.
- Restore un-deletes the entity and reactivates its homes, but does not auto-regrant the roles, memberships, and grants that teardown removed, those must be re-granted explicitly (least privilege). Restoring from a cert-revoked state re-issues crypto through the same idempotent provisioner used at create.
- A retention worker purges soft-deleted entities once the recovery window (30 days by default) elapses, building a certificate of destruction per purge and skipping anything under legal hold.
The retention worker matters most where a job launches ~100 ephemeral cells: each decommission writes a soft-deleted row, and a recovery window that nothing enforces means those rows never elapse. The worker's scheduler wiring was a documented dead-code gap, the purge logic exists; confirm the worker is registered in a given deployment before relying on automatic disposal.
Across the deployment matrix
- Air-gapped / sovereign. Private-key teardown is node-local by construction: a node's CA, key-encryption keys, forward-secret epochs, and fleet-signing keys can be destroyed only on the node that generated them, a remote teardown is refused. This is the multi-cell crypto boundary.
- Multi-cell. An organization's join-authorization teardown spans two stores: the node-local sealed signer is zeroized, while the replicated directory anchor is marked revoked so no further joins verify against it. Soft-deleted rows and cell tombstones are retained through replication convergence before collection.
- Version skew. Legacy status values are mapped forward, so an older database row stays transition-validatable under new code.
This state machine is the core's authority for the entity lifecycle cascade, and the edge does not implement an equivalent one. An Edge Agent has a device lifecycle, not a multi-kind entity lifecycle: it can be decommissioned as a device, and it emits a graceful-disconnect signal pinned to a cross-runtime contract fixture so the two runtimes cannot drift on its shape.
One gap in that signal is worth knowing, because it changes what a disconnect record means. The cell records a disconnect as graceful only from an operator-initiated lifecycle action. There is no inbound path that turns the edge's own graceful-disconnect event into that reason on an otherwise-active device, so a device that shuts down cleanly is still reaped as a timeout. The edge emits the correct signal on the correct lane; the cell-side consumption is owed.
So the cascade below is a core capability, claimed for the core, and not a both-runtimes claim.
Related topics
- The entity model, the principals this lifecycle applies to, and the workspace every entity is provisioned.
- Authorization and delegation, the mirror of act-on-behalf: how authority flows to a principal and narrows as it goes.
- The licensing lifecycle, the capabilities the provisioned entities are entitled to use.
- The estate hierarchy, nodes, service groups, and the cells an entity's home is delivered across.