# Infrastructure

**Explore, Infrastructure** is a ledger of the machines, pods, containers, workloads, functions,
platform services and datastores that have sent your project telemetry, and of how well each one
is covered. It is not a map and not a dashboard of gauges: it answers "what do I have, what has
gone quiet, what is not being collected, and what changed", and it says plainly what it does not
measure.

An **entity** is created when a metric or log resource resolves to one (the precedence table in
[Infrastructure scope](infrastructure-scope.md) and [OpenTelemetry](otlp.md) decides which machine
a resource is). Every point and log record then carries the entity's id.

## The ledger

| Section | What it answers |
| --- | --- |
| **Counts** | Entities by kind, provider and environment, largest first (ten groups, the rest folded into one). |
| **Stale** | Entities whose metrics or logs have been silent for more than three of their expected intervals. |
| **Coverage gaps** | Per signal (metrics, logs, events, traces): how many entities are `missing`, `stale` or `unknown`. |
| **Not measured** | Saturation and provider incidents, each with the card that owes the answer. See below. |
| **Changes** | Restarts, scaling, machine and cloud configuration, host events and collector changes recorded in the last 24 hours. |
| **Entities** | One row per entity, most recently seen first, with a four-letter coverage code. Open a row for its detail. |

The filters are closed: kind, provider and environment are picked from the values the digest
counted, and coverage is a signal and a state (for example *logs, missing*). There is no free-text
search. An `infra` saved view stores exactly those filters.

### The coverage code

Four letters, in the order **metrics, logs, events, traces**: `L` live, `Y` lossy (sampled or
thinned), `S` stale, `M` missing, `U` unknown. `LSUU` is "metrics live, logs stale, events and
traces not decidable yet". The code is also spelled out for a screen reader, and it is never colour
alone. Events and traces are `unknown` until error events and spans are attributed to entities; they
are never `missing`, because Bucker cannot yet say they should be there.

### One entity

The side sheet and `infra_entity_get` serve the same blocks:

| Block | Source | Until its source ships |
| --- | --- | --- |
| `metrics` | The entity's own metric points over the last 60 minutes, per metric name (latest, min, max, average, points), and the service's request rate from the RED rollup when that pillar is on | always answered; the RED line says why it is not measured when the pillar is off or the entity names no service |
| `saturation` | INFRA-14 | `not_checked` |
| `changes` | Change events recorded against the entity, last 7 days | always answered |
| `issues` | Error events attributed to entities | `not_checked` |
| `coverage` | The entity's stored coverage, per signal, with the reason | always answered |
| `config` | Aliases and the declared, observed and inferred fields | always answered |

## Not checked is not healthy

A block whose source card has not shipped answers **`not_checked`**, names that card, and is drawn as
that sentence. It is never an empty list and never a zero, because either would read as "I looked
and found nothing". A block that has a source and holds nothing says that in words (no points, no
changes). Today `saturation` (INFRA-14), `findings` (INFRA-11), `issues` and provider incidents
(INFRA-12, shown the moment any producer records one) are `not_checked`.

## Names are the sender's text

Entity names, identities, providers, environments, services, releases, aliases, field keys and
values, metric names and change summaries are chosen by whatever sent the telemetry. They are
labelled `untrusted` in every response (`trust.untrustedFields`), shown in the dashboard as text and
never as a link or markup, and, for an agent, a service principal or a person's OAuth client, passed
through the infrastructure field policy first: credentials and Secret data are dropped or hashed,
environment values are hashed, and injection-shaped text is redacted. See
[Scrubbing and privacy](scrubbing-and-privacy.md).

## For agents

Two MCP reads: they need the `infra:read` scope
(relation `read_infra`), which the `telemetry:read` tier does not grant, and the `infra` toolset. A token without
it does not see them.

| Tool | Price | What it returns |
| --- | --- | --- |
| `infra_fleet_digest` | 1,500 tokens (2,000 with `entities`) | Counts, stale entities, coverage gaps, saturation (`not_checked`), 24-hour changes and provider incidents. `include: ["entities"]` adds a page of up to 50 entities as a table, about 30 tokens an entity. `include: ["findings"]` is `not_checked`. |
| `infra_entity_get` | 500 tokens (2,000 with blocks) | One entity of any kind with `include` blocks: `metrics`, `saturation`, `changes`, `issues`, `coverage`, `config`. |

Every result carries `basis`, freshness, what was scanned, a cursor, why it is empty when it is, and
the untrusted label.

**Walking the fleet.** The first call carries the summary and 40 entities (it must fit its
2,000-token ceiling); a call with a `cursor` returns the entities alone, 50 at a time, at the same
filters. Two hundred entities cost under 8,000 tokens in all. A page the token budget cut resumes
after its last row, so none is repeated or skipped. The walk is ordered by when each entity was
FIRST seen, newest first, because that never changes: an entity that reports between two pages
keeps its place instead of jumping past the cursor. When a fleet's names or change summaries are
long enough to outgrow the price, the summary's text (or, for `infra_entity_get`, the entity's own
names) is clipped and `textClippedTo` says to how many characters; counts, ids and times are never
cut. The cursor is signed and bound to the project and
the filters: another project, another filter set or an edited cursor is refused.

**Reading 1,000 entities is recorded.** The page whose running total reaches 1,000 rows writes one
`infra.entities.export` audit row (the filter and the count, never a row) before the page is
returned; a read that cannot be recorded is refused. It is a tripwire on one walk, not a quota.

## Who owns it, how much it matters, and how many series it may spend

An entity can carry **declared** facts a person or an approved agent states: an owner, a team, tags,
a tier (`best_effort`, `standard`, `critical`) and a `protected` flag. They are stored on the entity
with the basis `declared`, and a collector's observations never overwrite them. Two governed writes
change them, and a third kind of act is only ever a person's.

**`infra_entity_update` (MCP) and `PATCH .../infra/entities/:entityId` (REST).** The owner, team,
tags, raising the tier, and setting `protected`. It is a governed write: the plan is digested, a
human decides, and one apply lands against the entity's revision (a hash of the declared fields, so
an edit through any other door between the yes and the retry closes the request unspent). The
approval card names what the change touches: the approval-policy rows, alert rules and saved views
whose stored conditions mention a changed value or the entity (a text match over what is stored,
bounded, and labelled so). It is refused before anyone is asked when the change would move the entity
under a **looser** approval-policy row (an agent may not make that move; a person with
`configure_infra` may), and when it changes nothing. **Clearing `protected` or lowering the tier is
human-only** (`org:admin`): the governed path refuses it, and a person makes it on the same REST
route, where it is audited as `infra_entity_protection.disable`.

**The series budget.** A collector can send more series than a plan can afford, so each entity has a
budget of live metric series: **230 on Free, 2,300 on Pro, 11,500 on Team, 46,000 on Enterprise** at
60-second grain, and the whole project's collector has the same figure (raised by exactly what a
person widened individual entities by). A series past a budget is **folded** into the metric's one
overflow series instead of being dropped: its points are stored, only the per-series detail is gone,
and the usage receipt says so under the reason `infra_series_budget`, apart from the older
per-metric cap (`metric_series_overflow`). A series with no entity is not budgeted. If the budget
cannot be read, series are admitted: the monitor is never the outage.

`infra_series_budget_update` (MCP) and `PUT .../infra/series-budget` (REST) **lower** the budget of
one entity, or of one metric of one entity, as a governed write whose card carries the numbers the
change is made on (the live series now above the proposed figure, which is exactly what would fold).
`POST .../infra/series-budget/preview` returns the same numbers and writes nothing. **A raise is a
person's own act** (`billing:write`, human-only): the MCP tool refuses it with that remedy, and the
REST route performs it only for a person acting for themselves, audited as `series_budget.widen`.
A protected entity bars every lever, so a narrowing on one is refused until a person clears it.

## Asking for a change: restarts, scaling, rollbacks and collector rollouts

The two reads above show the fleet. A third family of tools lets an agent **ask** for a change on your
platform. Every one of them only opens a request; a person decides, and what each is allowed to do is
fixed by the act's class, not by the tool.

| Tool | What it asks for | Platforms | Who decides |
| --- | --- | --- | --- |
| `infra_restart_propose` | A rolling restart of one workload | Fly, Render, Railway, Heroku, DigitalOcean | Two people |
| `infra_scale_propose` | A new instance count for one workload, inside a band | same | Two people |
| `release_rollback_propose` | Roll an environment back to an earlier release | Vercel, Cloudflare Workers, Render | An independent person (two when the organization says so) |
| `collector_rollout_propose` | Roll a collector profile revision or a package upgrade out in waves | your collectors | A person approves the canary wave; each later wave is a person's act in the dashboard |
| `provider_incidents_list` | Nothing: a read of whether a provider's own status feed reports an incident that overlaps your issues | n/a | n/a |

**Restart, scale and rollback are critical and denied by default.** Their acts (`workload.restart`,
`mitigation.workload_scale`, `mitigation.release_rollback`) ship as `CRITICAL` rows whose decision is
`DENY`: until an organization deliberately relaxes the row to **ASK**, a call is refused with the
engine's reason and nothing is stored. They are never `ALLOW` under any policy row, review mode or
autonomy rung. The tools hold `infra:act`, which buys opening a request and nothing more; a proposer
can neither approve nor apply what it opened. In [Actions](actions.md), the rollback act is live; the
restart and scale acts are listed as planned.

- **Restart** has no inverse (it is self-healing): no time limit and no revert, with a 30-minute
  verification on `endpoint_error_rate` instead. An agent may open at most two restarts of one workload
  in a rolling hour. A restart that would leave fewer healthy instances than the floor through the roll
  is refused before anyone is asked, as is a datastore, a protected entity, a workload with a change in
  flight and a platform with no lever provider.
- **Scale** works only inside a **band** a person set (`GET` and `PUT /orgs/:org/projects/:project/infra/lever-bands`,
  `minReplicas` and `maxReplicas` per workload and lever). Setting a band is human-only, org `admin`, and
  has no tool: an agent could not be allowed to widen the band it then proposes inside. A scale outside
  the band, with no band, to zero, to the count already running, under platform autoscaling, or on a
  datastore is refused. The approver sees the count before and after, the band and the cost delta, and the
  previous count comes back by itself at the time limit (one hour by default, at most 24).
- **Rollback** targets a deployment your resource catalog already holds, older than the current one and
  finished building. The approver sees the measured blast radius, or `not_measured`.
- **Collector rollout** pushes nothing to your collectors: a released wave is the bundle Bucker renders
  and a draft pull request, and a person applies and merges them.
- **`provider_incidents_list`** answers "is it us or them": per provider, `incident_reported`,
  `none_reported` or `unknown`. A stale, failing or missing feed reads `unknown`, never an all-clear,
  and a link between an incident and an issue is a correlation with a stated strength, not a cause.

The restart, scale, rollback and provider-incident tools sit in the `infra` toolset. The holds on the wider MCP surface were lifted by owner decision
on 2026-11-16 without a signed-off security review of the OAuth server; see [MCP setup](mcp-setup.md).
Approvals are described in [Approvals](approvals.md) and the agent rules in [Agent governance](agent-governance.md).

## REST

| Route | Purpose |
| --- | --- |
| `PUT /orgs/:o/projects/:p/infra/series-budget` | Lower an entity's (or one metric's) series budget; a raise is the person's own act. A first call answers 202 with the request to decide; the retry names it in `approvalRequestId`. |
| `POST /orgs/:o/projects/:p/infra/series-budget/preview` | What a proposed budget would fold. Writes nothing. |
| `PATCH /orgs/:o/projects/:p/infra/entities/:entityId` | Declared owner, team, tags, tier and `protected`; same ask-then-retry shape. Needs `configure_infra`. |
| `GET /orgs/:o/projects/:p/infra/digest` | The summary; `include=entities` adds a page; `limit` (at most 50), `cursor`, `kind`, `provider`, `environment`, `service`, `signal` with `state`. |
| `GET /orgs/:o/projects/:p/infra/entities/:id/detail` | One entity; `include=metrics,saturation,changes,issues,coverage,config`. |

The two reads need `infra:read` on the project and write nothing but the query log. The three writes
need `configure_infra` (`collection:write`) on it. An entity of another project or organization is a
404 on every door, the same answer as an id that does not exist.
