# Cost governance: what Bucker will never do with your cloud spend

**Draft, awaiting the owner's ratification of version 1.0.** It is published ahead of the cost work
so the boundary is on record first. It is version 1.0, as of 2026-11-04.

Bucker reads cost data, attributes it, and can hold a budget or a cap. It does not spend your money
and it does not change your cloud. This page lists what that means in practice, who decides what
Bucker does own, and the *never list*: the acts no tool, action or provider integration is allowed
to name.

## Who decides what

Cost has three scopes, narrower than anything that existed before it:

| Scope | Lets you | Held by |
| --- | --- | --- |
| `cost:read` | See cost data, budgets and attribution. | Owners, admins and the billing role |
| `cost:write` | Create and change budgets, allocation rules, units and cost sources. | Owners, admins and the billing role |
| `cost:cap` | Set a provider cap that pauses spend. | Owners, admins and the billing role |

**The billing role decides what it owns.** A request to change a cost budget, a provider cap or a
usage alert can be approved by someone holding `fix:approve` **or** `billing:write`, and the
approver must also hold the relation that act costs on your organization (`configure_cost`,
`cap_cost` or `configure_usage`; the billing role holds the first two). A billing member can
therefore approve a budget change and cannot approve a code fix; a member who can approve fixes
cannot approve a budget change unless they hold the cost relation too. Everything else about how requests are
decided is in [Agent governance](agent-governance.md).

Some cost acts are human-only, whatever the policy: raising or removing a cap, detaching a budget's
authority effects, deleting a budget, an allocation rule, a unit or a source, and entering a
credential. An agent can narrow a cap, never lift one, and no agent lifts its own.

## Lifting a cap

A cap is in force only because a person approved it. Raising or removing one is a different act, and
it is a person's own, done from the cost page in the dashboard or over REST on that person's session.

| Step | Route | Body |
| --- | --- | --- |
| 1. Ask for a challenge | `POST /orgs/:org/cost/caps/:capId/lift/challenge` | `reason`, and `amountMicro` for a raise |
| 2. Lift | `POST /orgs/:org/cost/caps/:capId/lift` | the same `reason` and `amountMicro`, plus `stepUp` |

`amountMicro` is the new cap in millionths of a dollar, as a string of digits (`"5000000000"` is
5,000 USD). Leave it out and the cap is removed. `reason` is stored scrubbed and lands on the
organization's audit row.

- **Step-up.** The challenge is single use and lasts five minutes. It is bound to you, to this cap,
  to the cap's current amount and status, to the new amount (or the removal) and to the reason. Answer
  it with a security key or passkey, or with a TOTP code (`stepUp` is `{ "kind": "totp", "code":
  "123456" }`). Change the amount, the reason or the cap, or let it expire, and the lift answers `403`
  `STEP_UP_REQUIRED`.
- **Who.** An organization **owner** only. An org admin and a member get `403`. An agent (including one
  holding `org:admin`), a service principal, an OAuth client and a delegated token are refused before
  any role, organization or row is read, and there is no MCP tool for it.
- **Refused up front.** The challenge runs every check the lift does, so a cap that is not in force, or
  one with no approved request behind it (`422`), gets no challenge. A cap that changed after you signed
  answers `409` `cap_changed` and nothing is lifted.
- **What Bucker does not do.** It never lifts a cap at the provider. The response carries the checklist
  of what you do on the provider's own screen, with `status`, `readBackState` and `rearm`.
- **Record.** One audit row on your own organization, `provider_cap.widen`, with the step-up method. A
  refusal writes none.

## Certifying a unit

A unit cost is a definition: a cost query over one lane divided by a count Bucker already holds
(transactions, sessions, subjects, agent runs, agent sessions or verified fixes). An agent or a person
**proposes** one with `cost_allocation_rules_update` and `target: "units"` (the unit's arguments go
under `units`); a proposal is a draft and reads no figure. Only a person's
certification makes it answer, and a later proposal never replaces a certified version until a person
certifies that one too.

| Step | Route |
| --- | --- |
| 1. Ask for a challenge | `POST /orgs/:org/cost/units/:key/certify/challenge` |
| 2. Certify | `POST /orgs/:org/cost/units/:key/certify` with `stepUp` |

The key alone names the unit. The server finds the key's one proposal and binds the challenge to its
digest, so a proposal replaced between the challenge and the certification voids the proof. A key with
no proposal answers `422` `no_proposal`, and an unknown key `404`. The step-up, the owner-only rule and
the refusal of agents, services, OAuth clients and delegated tokens are the same as for a cap. The
audit row is `cost_unit.certify`.

Once certified, `cost_status_get` with `unit=<key>` (and the same figure over REST) returns the value
with its `n`, window, freshness, lane and basis. It is `null`, with the reason, below the unit's minimum
denominator, when the denominator is gated or unavailable, or when the ledger read was incomplete.
A unit nobody certified answers `not_available`. A subject or session denominator counts end users and
is read only for a project whose product-analytics gate is open ([Product analytics gate](product-analytics-gate.md)).

## Previewing an allocation rule

`POST /orgs/:org/cost/allocation-rules/preview` with `{ "ruleKey": "ar_…" }` answers what removing that
rule would change: for each owner and lane (at most 50 rows, the largest moves first), the dollars
before and after. It is a read and records nothing. It needs `cost:read` for the figures (without it they
are `null` and `moneyRedacted` is `true`) and whole-organization reach, because a move between owners
is a sum over everyone. A key that is no live rule of the organization is `404`; an organization with
more cost rows than a preview reads is `422` `preview_unmeasured`, never a guess. Owners are named by
id only. See [Cost](cost.md) for lanes and bases.

## The never list

No registry action, no tool (planned or live) and no provider descriptor may be named for any of
these. The list is enforced by a test that walks all three and fails on a name that says so.

| Never | Includes |
| --- | --- |
| Purchases | Buying credits, commitments, reservations, savings plans or marketplace items |
| Resource deletion | Terminating, destroying or decommissioning instances, volumes, buckets, clusters or snapshots |
| Plan and add-on changes | Upgrading, downgrading or changing a cloud plan, subscription or add-on |
| Billing disablement | Switching off, closing or cancelling billing on an account |
| Key minting | Creating or rotating a cloud access key or API key on your behalf |

Related lines that follow from it: Bucker holds no standing write role in your cloud beyond one
cap-only credential; a credential that can purchase or mint keys is refused at entry; there is no
chat assistant that acts on spend, no "autonomous" mode, no in-network inference proxy, and no fee
taken as a share of your savings.

## Where this is enforced

The approver rule is read from the action registry for each request and checked when someone decides
it, on the organization the request belongs to, so `billing:write` earned as a billing member of
another organization satisfies nothing here. The never list is a registry-wide test that passes on
the current registry and fails on a synthetic row for a purchase or a tool named `buy_credits`. See
[Security scope](security-scope.md) for the equivalent boundary around security work.
