> ## Documentation Index
> Fetch the complete documentation index at: https://docs.swarmd.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Lifecycle and governance policy
> The governance states a system moves through, how suspension and retirement work, and the tenant-wide policy that decides whether unmet obligations warn or block.
# Lifecycle and governance policy
Each system has a **governance state** beside its operational status. The
operational status says whether it is registered, healthy and reachable; the
governance state says whether it has been assessed, put into service,
suspended or withdrawn under the Act. Every transition is an immutable event
with a reason, the person who made it, any approver, and the system's
mandatory readiness at that moment.
You manage the state on a system's **Governance › Governance lifecycle**
page. The **State log** there lists every event.
***
## States
| State | Meaning | Effect on traffic |
| - | - | - |
| **Draft** | No classification is effective yet. Every system starts here, including every existing one after the upgrade. | None |
| **Assessed** | Classified, and approved where a second signature is needed; not yet put into service. | None |
| **In service** | In use for its intended purpose (Art. 3(11)). The date of the first entry starts the ten-year documentation clock. | None |
| **Suspended** | Corrective action under Art. 20. The kill switch is engaged until the suspension is lifted. | **Blocked**: callers get `Sink agent is frozen` |
| **Retiring** | A retirement case is open. | None until the case completes |
| **Retired** | Withdrawn. Terminal. The record is sealed and the retention clocks are running. | The system is deregistered |
Only Suspended (and the deregistration at the end of a retirement) changes
traffic. A system in Draft, Assessed or Retiring keeps serving.
***
## Transitions
| From | To | How | Conditions |
| - | - | - | - |
| Draft | Assessed | Automatic, when a classification takes effect | Immediately for tiers up to Limited and for Prohibited; after the second signature for High-risk and High-risk (exempt) |
| Assessed | In service | **Put into service** | Passes the [readiness gate](#what-the-gate-checks). A Prohibited system is always refused |
| In service | Suspended | **Suspend** | A suspension reason is required. Not available for LLM gateways |
| In service | Suspended | Automatic, when the system is classified **Prohibited** | Reason recorded as *Non-conformity* |
| Suspended | In service | **Lift suspension** | High-risk tiers need a second person to approve |
| In service | Assessed | **Require reassessment** | For a substantial modification (Art. 3(23)); put it back into service when the new assessment is done |
| Any except Retired and Retiring | Retiring | **Retire…** | Opens a retirement case |
| Retiring | The state before | **Cancel the retirement case** | |
| Retiring | Retired | **Retire** on the last step of the retirement drawer | Checklist complete, and second signature for high-risk tiers |
Every manual transition needs a free-text reason. Reclassifying a system does
not move it out of In service (except to Suspended when the new tier is
Prohibited); use **Require reassessment** when the change is substantial.
***
## Suspension
**Suspend** is the kill switch with a governance reason attached. It is
available only for a system that is **In service**.
| Reason | Shown as | Legal basis |
| - | - | - |
| `NON_CONFORMITY` | Non-conformity | Art. 20(1) |
| `SERIOUS_INCIDENT` | Serious incident | Art. 73 |
| `RISK_UNDER_ART_79` | Risk to health, safety or rights | Art. 79 |
| `PENDING_REASSESSMENT` | Pending reassessment | Art. 25 |
What it does, and does not do:
* It **freezes the agent or MCP server** through the same kill switch as the
**Freeze** button. Every request to it is refused with
`Sink agent is frozen`, whatever else is true about it.
* **LLM gateways cannot be suspended**: they have no kill switch. Suspend the
agents that use the gateway instead.
* While the governance state is Suspended, the kill switch **cannot be
released by hand**. Unfreezing directly is refused; lifting the suspension
releases it.
* Suspension **does not notify anyone**. Tell dependants yourself, or retire
the system, which does notify them.
* It is not available from Draft or Assessed. To stop a system in those
states — for example one you have just classified Prohibited — use the
**Freeze** button on its page.
### Lifting a suspension
**Lift suspension** returns the system to In service and releases the kill
switch. For an effective tier of High-risk or High-risk (exempt), it instead
creates an approval request: the system stays suspended until a different
person approves it in **Govern › Approvals**, *Governance* tab. A rejected
request changes nothing; request the lift again when ready.
***
## Retirement
Retirement withdraws a system with evidence instead of simply deleting it.
Open it with **Retire…** on the lifecycle page. A drawer walks through five
steps — Reason, Impact, Evidence, Approval, Confirm — and **Open the case**
on the first step moves the system to Retiring. A case can be opened from any
state except Retiring and Retired, and the system keeps serving until the
case is completed.
Choose a reason and describe it. For a corrective retirement, say whether
the system is withdrawn from the market or recalled from users, and
optionally name the successor system.
| Reason | Legal basis | Market action |
| - | - | - |
| End of life | Art. 18 | Optional |
| Superseded | Art. 18 | Optional; name the successor |
| Non-conformity | Art. 20(1) | **Required**: Withdrawn or Recalled |
| Serious incident | Art. 20(1); Art. 73 | **Required**: Withdrawn or Recalled |
| Contract ended | Art. 26 | Optional |
| Never used | Art. 3(11) | Optional |
For the two corrective reasons, dependants are notified as soon as the
case is opened.
The case shows the impact: agents sending to it and agents it sends to,
people subscribed, channels routing to it, MCP servers and gateways it
uses (and whose inherited tier will drop), policy bindings that name it,
open human-review holds, and monitors that filter on it.
Mandatory items must be satisfied before the case can complete:
| Item | Applies to | Satisfied by |
| - | - | - |
| Decommissioning plan linked | Minimal to Prohibited | An approved *Decommissioning plan* document |
| Data disposition stated | Every system | An attestation of what happens to inputs, outputs and fine-tuned artefacts |
| EU database status update prepared | High-risk tiers, provider roles | An attestation |
| Affected persons and deployers informed | High-risk tiers | An attestation |
| Log retention hold recorded | Every system | Computed at completion |
| Documentation retention computed | High-risk tiers | Computed at completion |
For an effective tier of High-risk or High-risk (exempt), opening the case
creates an approval request in **Govern › Approvals**, *Governance* tab.
A different person must approve it. If it is rejected, cancel the case
and open a new one when ready.
On the Confirm step, type the system's name and press **Retire**.
Completion happens in one step: dependants are notified, the system is
deregistered, the RETIRED event is written, the retention dates are set
and the record is snapshotted.
While a case is open, the lifecycle page shows it with its checklist,
approval status and **Cancel case**. To pick it up again — for example once
the second signature is in — press **Continue retirement…**; the drawer
opens at the step the case has reached.
### What completion does
* **Notifies dependants** by e-mail: the system's owner, deputy and
oversight persons, the people subscribed to it, and the owners of agents
and MCP servers connected to it. Who was addressed is recorded as an
event on the audit chain even if a mailbox bounces. Delivery needs
notification-service and SMTP — see
[Configuration](/self-hosting/configuration#smtp).
* **Deregisters** the system through the normal path: its subscriptions and
grants are removed and traffic to it stops.
* **Sets the retention holds**:
* logs: the completion date plus the larger of **183 days** and the
governance policy's minimum retention;
* documentation: **10 years** from when the system was first put into
service, or from completion if it never was.
* **Takes an immutable snapshot** of the whole record. From then on the
evidence pack is read from the snapshot.
* **Seals the snapshot** with an audit integrity checkpoint shortly
afterwards (the platform waits about 15 seconds so the checkpoint covers
the retirement events, then requests it). The case shows the checkpoint
id once sealed.
A trusted RFC 3161 timestamp is added to the checkpoint only if qualified
timestamping is enabled on audit-service (`AUDIT_QTS_ENABLED=true`, off by
default; set it under `services.audit.settings` — see
[Per-service overrides](/self-hosting/configuration#per-service-overrides)).
Without it, the checkpoint is signed and hash-chained but not timestamped by
a third party.
**Retired is terminal.** A retired system cannot be put back into service,
reactivated or have a new version registered. To bring the capability back,
register it as a new system and classify it again.
***
## Tenant governance policy
**Manage › Governance policy** holds the tenant-wide rules. Anyone with
Tenant Read can view it; editing needs **Tenant Admin**. Every save creates a
new numbered version with an optional reason and an audit event; until the
first save, the platform defaults apply.
| Setting | Per tier? | Default | Range | Effect |
| - | - | - | - | - |
| Gate mode | Yes (the page shows High-risk and High-risk (exempt), the only tiers the gate checks) | **Warn** | Warn / Block | What happens when a gated action finds unmet mandatory obligations — see below |
| Additional required documents | Yes (High-risk, High-risk (exempt), Limited, Minimal) | None | Any document kinds | Makes an already-applicable document obligation mandatory |
| Review interval | Yes | 12 months for High-risk and High-risk (exempt); 24 months for every other tier | 1–60 months | Sets the review date of classifications signed after the change |
| Evaluation validity | No | 30 days | 1–365 days | How long a passed evaluation run counts for *Tested against predefined metrics recently* |
| Minimum audit retention | No | 183 days | 183–3,650 days | The floor used for the log retention hold at retirement |
Some details worth knowing:
* **Additional required documents only promote.** They make an advisory
document obligation that already applies count as mandatory (for example
the DPIA for a High-risk deployer). Adding a kind that no obligation asks
for at that tier has no effect, and nothing can make a default-mandatory
obligation optional.
* **Review intervals are applied at signing.** Existing review dates are not
recalculated when you change an interval.
* **Through the API, a save replaces the whole policy.**
`PUT /registry/v1/tenants/{tenantId}/governance-policy` fills any field you
leave out with the platform default, not with your previous value. Read the
current policy first and send it back with your change.
There are **two retention floors**. The governance policy's *Minimum audit
retention* is used for the log retention hold when a system is retired. The
*Logs kept at least six months* readiness check reads a separate floor held
by audit-service (`GET /audit/v1/retention`), which is 183 days unless
changed through that API. Keep both at or above 183 days; neither schedules
deletion.
***
## What the gate checks
The gate runs on four actions:
| Action | Applies to | Triggered by |
| - | - | - |
| `REGISTER_VERSION` | Agents | Registering a new version of an agent |
| `REACTIVATE` | Agents | Reactivating a deregistered agent |
| `MARKETPLACE_PUBLISH` | Agents | Saving an agent version with public visibility |
| `PUT_INTO_SERVICE` | Agents, MCP servers, LLM gateways | **Put into service** on the lifecycle page |
What it decides:
1. A **Prohibited** system is always refused, in every mode.
2. A **Retired** system is always refused, except for marketplace publish.
3. Otherwise only systems whose **effective tier** is High-risk (exempt) or
High-risk are checked. For them, the gate takes the unmet **mandatory**
obligations from readiness:
* under **Warn**, the action goes ahead and the response carries a `gate`
object listing what is unmet (the UI shows it as a warning);
* under **Block**, the action is refused with **HTTP 409** and the same
`gate` object, so a client can show exactly what to fix.
4. Publishing an **unclassified** agent to the marketplace always returns a
warning that it has no classification. It is never blocked.
5. For every other tier, the gate says nothing.
A refusal looks like this (obligation entries abbreviated):
```json theme={null}
{
"error": "…",
"gate": {
"action": "REGISTER_VERSION",
"mode": "BLOCK",
"riskTier": "HIGH_RISK",
"passed": false,
"unmetObligations": [
{
"id": "human-oversight-procedure",
"article": "Art. 14; Art. 26(1)-(2)",
"label": "Human oversight procedure",
"status": "UNMET",
"detail": "No document linked",
"fixTarget": "COMPLIANCE_RECORD"
}
]
}
}
```
Under **Block** there is one more rule: a High-risk or High-risk (exempt)
system that is In service or Suspended cannot be **deregistered directly**.
It must go through a retirement case, so the withdrawal is recorded with
evidence. Under Warn, direct deregistration is allowed and logged.
**Block never refuses traffic.** It refuses registry actions: a new version,
a reactivation, a marketplace publish, a put-into-service, a direct
deregistration. A high-risk agent that is already running keeps serving
requests however many obligations are unmet, and an obligation that lapses
later (an owner leaving, an attestation expiring) is not re-checked until the
next gated action. To stop traffic, suspend the system or freeze it.
***
## API
Through the gateway, under `/registry`. Replace `agents/{agentId}` with
`mcp-servers/{mcpServerId}` or `llm-gateways/{llmGatewayId}` for the other
subject types.
| Method and path | Purpose |
| - | - |
| `POST /registry/v1/agents/{agentId}/governance/state` | `PUT_INTO_SERVICE`, `SUSPEND` (with `suspensionReason`), `LIFT_SUSPENSION`, `REQUIRE_REASSESSMENT`; `reason` is required |
| `GET /registry/v1/agents/{agentId}/governance/state/events` | The state log |
| `POST /registry/v1/agents/{agentId}/retirement` | Open a retirement case (`reasonCategory`, `reason`, `marketAction`, `successorSubjectId`) |
| `GET /registry/v1/agents/{agentId}/retirement` | The current or last case, with impact and checklist |
| `POST /registry/v1/agents/{agentId}/retirement/cancel` | Cancel the open case |
| `POST /registry/v1/agents/{agentId}/retirement/complete` | Complete it |
| `GET /registry/v1/governance/approvals?status=PENDING` | Retirements and suspension lifts waiting for a second person |
| `POST /registry/v1/governance/approvals/{approvalId}/decide` | Body `{"decision": "APPROVE", "note": "…"}`, or `"REJECT"` |
| `GET`, `PUT /registry/v1/tenants/{tenantId}/governance-policy` | Read or replace the governance policy |
***
## Next
Where things live, day one after upgrading, permissions.
Risk tiers, the wizard, second signatures and inherited tiers.
Owners, oversight, documents, readiness and Art. 50 transparency.
Serious incidents, the register, exports and the evidence pack.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.