# Governed operations

A **governed operation** is one change to your organization's configuration that went through
the approvals engine: a rule muted, a freeze window opened, a policy edited, a setting moved. The
operation is the record of the whole story, in one row: who asked, the exact plan an approver
saw, what was approved, whether it was applied, whether it worked, and how to undo it.

This page is the contract for people and for agents. The page that lists operations is
**Operations** in your organization's navigation (`/org/<your-org>/operations`).

## What a change goes through

1. **Plan.** The change is turned into a plan: the fields that change, the change as a
   configuration fragment, a blast radius and the stored inverse. The plan has a **digest**. Nothing
   is applied from the plan until that digest has been approved.
2. **Class.** The risk class (Safe, Elevated, Sensitive, Critical) is derived from the difference
   between before and after, never from an argument the requester supplies. The same change can be
   Elevated when it narrows something and Critical when it silences a paging rule.
3. **Decision.** Your [approval policy](/docs/agent-governance) turns the class into Allow, Ask or
   Deny. Conditions on a policy row, floors the product keeps (some acts always ask), change freezes,
   per-surface switches and [review mode](/docs/review-mode) can only make the answer stricter or
   leave it; none of them lifts a Deny.
4. **Approval.** An Ask files an approval request bound to the plan digest. A person approves it in
   the inbox. An approval is spent once, on that plan, against the version of the object the plan
   was made on.
5. **Apply.** The change is applied only if the object is still at the version the plan was made on.
   If someone changed it in between, the apply is refused as a moved target and nothing is written.
6. **Verify.** Many changes name a signal and a window. When the window closes, and the data for it
   is complete, Bucker measures the signal before and after and records a verdict.
7. **Receipt.** The apply and the verification each produce a signed receipt stored on the
   operation.

A preview is its own call, never a flag on the change: previewing can never become applying.

## States

| State | Meaning |
| --- | --- |
| Planned | A plan exists and nothing has been asked yet. |
| Waiting for approval | An approval request is open. |
| Approved | A person approved the plan digest; the apply has not run yet. |
| Applying, Applied | The change is being written, or was. |
| Checking the result | Applied, and the verification window is open. |
| Verified | The signal moved the way the change claimed, or held. |
| Did not work | The signal did not move as claimed, or got worse. Bucker opens a question about undoing it; it never undoes the change on its own. |
| Not measured | Nothing could be measured: no signal, no data, or too few observations. |
| Expired | The approval or the time limit lapsed. |
| Undone | The change was reverted through its stored inverse. |
| Superseded | A later operation replaced it. |
| Denied by policy, Rejected | Policy refused it, or a person did. Nothing was applied. |
| No longer applicable | The object moved or went away before the apply. |
| Unavailable, Failed | The change could not be applied. |

## The verification verdict

A verdict is one of: **Improved**, **No change**, **Got worse**, **Not enough data**, **Not
measured**.

- The signal is a stored query that Bucker runs as its own service identity; the read appears in
  your query log.
- A verdict is only given once the data for the window is complete. Before that the operation stays
  in "Checking the result", and a window whose data never completes is settled as Not measured.
- "Did not work" and "Got worse" are findings, not actions. They record reversal debt and notify the
  requester's sponsor and the approver.

## Time limits

A change may carry a time limit. When it ends the operation does what it says in the detail:
ask a person to undo it, lapse on its own, or alert the owners. Time limits are checked once a
minute by a pass that cannot be paused from the console; a deployment's operator can switch the pass
off, which is a deployment decision.

## Undoing a change

Every change that can be undone stores its **inverse** at plan time. The detail shows the sentence
the inverse carries and the act it performs. Undo is offered only when:

- the operation was applied and not already undone;
- the change is not marked irreversible or self-healing;
- an inverse was stored.

Undoing is itself a governed act. It is classed from the inverse plan, so undoing a Safe change
usually applies at once and undoing something Critical files an approval request. The operations
page offers the button only to a person whose role holds the approver relation for the inverse act,
and the answer is still decided on the server: a request that needs approval answers "approval
required" with the request, and nothing changes until a person decides it. Asking again once the
request is approved spends that approval exactly once.

## Who sees what

- You see the operations on the organization itself and on the projects you can read. An operation
  on a project you cannot read is neither listed nor counted, and opening it by id reads the same as
  an id that does not exist.
- An operation of another organization is never visible, by any route.
- The requester's free text (the reason, the plan fragment, the inverse's sentence) is shown as
  text. When it reaches an agent over MCP it is fenced and marked untrusted.

## Receipts

A receipt is a signed envelope (DSSE) over a canonical payload naming the operation, the
organization and the plan digest, for one of three kinds: applied, verified, reverted. Receipts are
stored on the operation, and the signed organization is checked when one is read, so one
organization's receipt cannot be presented as another's. They are not entries in the remediation
proof ledger. You can verify a receipt's signature offline with `bucker-verify`; it reports the
receipt kind as one this version of the format does not yet rank, which can never satisfy a tier
requirement.

A receipt that cannot be signed (no signing key configured) never blocks an applied change: the
failure is recorded, the requester is told, and the receipt is left empty rather than half written.

## What agents may and may not do

- An agent reads operations with `operations_list` and `operation_get`, and the same answer is a
  resource, `bucker://operations/<id>`.
- An agent can ask for an undo with `operation_revert`; the stored inverse is planned, classed and
  asked like any other act.
- Agents are capped per family and project: a window cap bounds how many operations an agent or an
  OAuth client may have in flight. An organization can add ceilings, never remove the default one.
  Three denials in a row in one family pause that actor in the family for an hour and tell its
  sponsor.
- Acts reserved for a person stay with a person. Merging code, changing the window caps and the
  dual-control acts are never available to an agent or to an OAuth client, even a human's.
- A held act that needs a second person (dual control) can be filed by a person only: it waits
  through its hold, can be rejected by any eligible person during it, and is confirmed by the
  requester with a fresh security-key or code check.

## REST

| Route | Use |
| --- | --- |
| `GET /orgs/:org/operations` | List, newest first. Filters `family`, `state`, `objectKind` with `objectId`; opaque `cursor`; `limit` up to 100. |
| `GET /orgs/:org/operations/:id` | One operation: plan, state, verdict, time limit, revert hint, receipts. |
| `POST /orgs/:org/operations/:id/revert` | Undo: 200 when done, 202 with the approval request when a person must decide. |
| `GET`, `PUT /orgs/:org/operation-window-caps` | The organization's window-cap overrides. A person with organization admin, on their own session. |

Every route resolves the organization from the slug you hold read access on. A project-scoped
operation you cannot read answers 404.
