# Examples: an API change, a package upgrade and an incident

## An agent removes an API field, and a person accepts it

```text
$ jadpo check
error: `api/main.jadpo_record` is out of date
  …
  next: Run `jadpo api update`, and commit the record with the code (agent)

$ jadpo api update
$ jadpo check
error: removing an output field can break clients: main.TodoSummary.priority, main.TodoView.priority
 --> api/main.jadpo_record:31:1
  …
  next: A person accepts it: `jadpo acceptance new <purpose>` writes the draft for them (human)

$ jadpo acceptance new remove_todo_priority
✓ Wrote acceptances/20261020T1400_remove_todo_priority.jadpo
    main.TodoSummary.priority  ApiChange.output_field_removed
    main.TodoView.priority     ApiChange.output_field_removed

◆ decision  2 changes wait for a person's reason
  at        acceptances/20261020T1400_remove_todo_priority.jadpo:1
  next      Stop and hand over: a person reads the changes and writes why
            they are accepted on a `///` line above `acceptance`. (human)
```

The agent commits and opens the pull request, saying a reason is needed.
CI runs `jadpo check`, which fails on the missing reason
([`acceptance.no_reason`](/docs/errors/acceptance.no_reason.md)). The code
owner reads the diff of `api/main.jadpo_record` and the acceptance,
writes the `///` line, and approves. CI passes and the change merges. On
the default branch the acceptance is now history.

## A provider package upgrade

```text
$ jadpo package update acme_couriers
✓ Updated AcmeCouriers.v2 from 2.3.0 to 2.4.0
    folder   packages/acme_couriers/v2
    source   git github.com/acme/couriers tag v2.4.0
    surface  matches its code

Changes since 2.3.0
  ~ operation bookings.create  used by the app
  ~ type Booking               used by the app
  ~ provider

Needs a person
  + bookings.create  new failure    address_unverifiable
  - bookings.get     field removed  Booking.driver_phone
  ~ host             changed        https://api.acme.example → https://api.eu.acme.example

✓ package updated  AcmeCouriers.v2 2.4.0 · 3 changed · 3 need a person

→ jadpo acceptance new upgrade_acme_couriers  writes these up for a person's reason
```

The removed field is also a compile error in `delivery_view`, which the
agent fixes first. The agent then runs
`jadpo acceptance new upgrade_acme_couriers` and hands over. A person
writes one reason covering all three changes, and the owner approves.

A new major version is a new package beside the old one ([External services](/docs/external-services.md)),
so `update` refuses it: the agent adds it, moves the calls across and removes
the old one, and `jadpo check` compares what the app used of the old
version with the new one in the same way.

## A production incident traced to source

A Worker logs a fault carrying its stamp (`build b_9a1f…`,
`commit 8d113e6`), its `.jadpo` frames and a path number. Someone pastes
it into `jadpo incident`:

```text
$ jadpo incident
int_overflow in action price_line
  build  b_9a1f03c6d2e4  rebuilt from 8d113e6, matches
  then   domains/ordering/actions/price_line.jadpo:4
  now    domains/ordering/actions/line_price.jadpo:6   renamed, changed since (2 commits)
  path   POST /orders → place_order → price_line, branch "discounted"
  next   jadpo test new --from-event
```

"Now" comes from the registry and the current manifest. If the local
compiler is a different version, the build id can't match. The frames and
names are still exact, because they are in the event, and the output says
that the path number can't be decoded.

`jadpo incident` isn't built yet ([What is built](/docs/records-and-manifest-built.md)).