# Instrumentation patches

An instrumentation patch is a **pull request that fixes how a service is instrumented**: installs the
SDK, turns tracing on, lists the hosts that receive trace context, upgrades a stale SDK, documents the
environment variables it reads, adds the OpenTelemetry configuration for a cluster or a host. It is
proposed by a person or an agent, approved by a person as an **exact plan**, opened as a **draft** pull
request, and merged by a person. Bucker never commits to a default branch and never merges.

It is the fix behind the findings on the SDK inventory (`instrumentation_health_get`): a silent SDK, one
below its floor, tracing that is off, a service that calls hosts nobody traces.

## How a patch happens

1. **Propose.** Name a recipe and its typed slots (below), the finding it answers, and why.
   `POST /orgs/:org/projects/:project/instrumentation-patches` or the MCP tool
   `instrumentation_patch_propose`. A request that carries a diff, a file or a branch is refused: the
   body is a recipe and slots, never code.
2. **Plan.** Bucker reads the repository at its default branch's head, runs the recipe (a pure,
   versioned function) and renders the diff. The diff is **validated** before anyone is asked.
3. **Ask.** `pr.propose` on the project is `SENSITIVE` and asks. The approver reads the recipe and its
   version, the files (an edit to a file Bucker did not write is marked), the finding, the diff excerpt,
   the base commit and the diff's digest. The approval is bound to that digest **and** to the base
   commit.
4. **Apply.** After a person approves, the retry records the patch and opens ONE draft pull request on a
   `bucker/instrumentation-<recipe>-<digest>` branch. The diff is rendered again from the same base and
   must still have the approved digest.
5. **Merge.** A person reviews and merges. Bucker has no merge operation.
6. **Watch.** Seven days after the merge the finding is re-checked; `verifiedAt` (or `revertedAt`, if a
   person reverted the merge) lands on the patch.

The patch moves through `proposed` (recorded, nobody has approved it, so nothing is delivered),
`approved`, `opened`, `merged`, `verified`, `reverted` or `rejected` (closed without a merge).

## Recipes

Each recipe is versioned. The version is part of the digest, so an approval never survives a recipe
change.

| Recipe | What it changes | Frameworks |
| --- | --- | --- |
| `install` | the dependency, one init module that reads the DSN from the environment, `.env.example` names, one import line in the entry file you name | node, nextjs, browser, python |
| `add_tracing` | `tracesSampleRate` on the existing init call | node, nextjs, browser |
| `outbound_spans` | `tracePropagationTargets` (the listed hosts only) and `outboundHttpSpans` | node, nextjs |
| `session_propagation` | the browser session id on requests that already carry `traceparent` | browser, nextjs |
| `track_calls` | one module naming the product events a service may send | node, nextjs, browser |
| `code_origin` | `codeOrigin` on the init call | node, nextjs |
| `sdk_upgrade` | a dependency range, to a version Bucker has published (a major bump only when asked) | node, nextjs, browser, python |
| `config_file` | the variable names the SDK reads, in `.env.example`, empty | node, nextjs, browser, python |
| `drop_unused_entry` | one single-line import of an unused SDK entry point | node, nextjs, browser |
| `tunnel` | one first-party route that forwards browser envelopes | nextjs |
| `sqlcommenter` | one module holding the `traceparent` SQL comment option | node, nextjs |
| `otel_operator_instrumentation` | one Kubernetes `Instrumentation` resource | kubernetes |
| `otel_injector` | one injector configuration file | host |
| `obi` | one OBI configuration file | host, kubernetes |

`tracking_plan` and `csp_policy` are named by the plan and **reserved**: they belong to SDK-19 and SDK-26
and are refused, naming their owner.

### The three configuration-only recipes

`otel_operator_instrumentation`, `otel_injector` and `obi` write **upstream configuration into your
repository and execute nothing**. They create YAML or `.conf` files only, delete nothing, and their diffs
are refused if they contain an install, a download, a shell, a cluster command or a preload. Bucker does
not ship an injector or a recorder of its own: you apply the file with your own tooling, after review.
Each is named as configuration-only on the plan the approver reads.

## What every patch is held to

A patch is refused, before anyone is asked, when its diff:

- touches a path the recipe does not name, a lockfile, a CI or hook directory, a `.env` file, a key
  file, an agent instruction file, or anything outside the service root you named;
- does not parse (JSON, YAML, `.env` and `.conf` grammar; balanced brackets in source);
- carries a secret-shaped value (a DSN, a key, a value on an environment line: only names are written);
- executes anything (`child_process`, `eval`, `subprocess`, and for the configuration-only recipes any
  install or shell);
- touches more than 20 files or 400 lines, or a file over 256 KiB.

It is also refused when the project maps no repository, consent lacks `contents:read` or
`pull_requests:write`, the project's automation policy stops before a pull request, another patch of the
same recipe is approved or opened for the repository, the framework cannot be told, or the SDK version is
not one Bucker published.

**No slot holds code.** Every slot is a closed charset or a number (a host name, an event name, a sample
rate, a version) and a recipe writes it only as an escaped literal. That, not a scan, keeps a field lifted
from telemetry out of your repository.

## Who may do what

- Proposing is `propose_fix` (`fix:propose`) on the project. An agent also needs the organization's
  `agentPrCreationEnabled` switch.
- The approver holds `fix:approve` and is a person outside the proposing session's delegation chain.
- A policy that allows the proposal outright (or review mode) records the patch as `proposed` and **opens
  nothing**: a pull request is opened only for a patch a **person** approved, with the approval spent on
  this diff digest. Such a `proposed` patch does not count as "open": a later proposal of the same recipe
  that a person approves is planned beside it. Keep `pr.propose` at ASK if you want recipe plans
  delivered.
- A retry reuses the `bucker/...` branch an earlier attempt pushed only when that branch is exactly one
  commit on the base carrying exactly the approved files; anything else on that name is refused for a
  person to clear, never presented under the approval.
- Merging, and reverting a merge, are yours. Neither has a tool.

### Slots from telemetry

A host or an event name an agent read in telemetry is **runtime text**. The plan says so
(`provenance: runtime_text`, with the slots), and when the proposing session was served the same text the
operation is `untrusted_text`: the act stays at the draft-pull-request level whatever autonomy was earned.

## Earned autonomy (`config_pr`)

`pr.propose` on a project is laddered under the `config_pr` category. The ladder covers a recipe only when
its golden diff is byte-stable **and** an earlier merge of it closed its finding inside seven days, and
never when one was reverted inside fourteen. The plan shows the reading (`ladder.covered` and why). No
rung reaches merge.

## REST

| Route | |
| --- | --- |
| `POST /orgs/:o/projects/:p/instrumentation-patches` | Propose. `202` with an approval request, then `200` on the retry with `approvalRequestId`. |
| `GET /orgs/:o/projects/:p/instrumentation-patches` | The project's patches with their state; filter by `state`, `recipe`. |
| `GET /orgs/:o/projects/:p/instrumentation-patches/:patchId` | One patch. |
| `POST /orgs/:o/projects/:p/instrumentation-patches/:patchId/deliver` | Open the pull request of an approved patch whose delivery failed. No second approval; nothing for a patch no person approved. |

A patch of another organization or project is the same `404` as one that does not exist.

## MCP

`instrumentation_patch_propose` (`sdk` toolset, `fix:propose`). It answers `PENDING_APPROVAL` until a
person decided; the call that carries the approval applies the plan and opens the draft
(`DRAFT_PR_OPENED`), and the answer says `merged: false`. File paths, the repository, the diff excerpt and
the provider's URL are declared untrusted. `instrumentation_health_get include: [recipes]` (wired by the SDK-01 package) serves the
catalogue above, and `include: [patches]` the project's patches.

## Adding or changing a recipe

A recipe is a pure function in `domain/src/modules/instrumentation-patches/recipes/`: typed inputs and the
files it asked to read in, a plan of edits out. Add a golden case under
`api/test/instrumentation-patches/golden/<recipe>/<case>/` (see its README), bump the recipe's `version`
whenever its output changes, and read the diff of the golden files: that is the review.
