# Browser Compensating Actions

Implementation task: `180.C.11.11`

Browser automation has no reliable native undo stack for form submissions,
downloads, uploads, account changes, or managed-session lifecycle changes.
Bellona browser mutations therefore declare explicit compensating-action
metadata instead of implying that the browser can undo an operation.

This document defines the Browser CDP MVP compensating-action framework and the
requirements future mutating browser commands must satisfy before dispatch.

## Protocol Catalog

The source of truth lives in `libs/bellona/remote-protocol/src/browser.ts`:

- `RemoteBrowserCompensatingAction`
- `RemoteBrowserCompensatingActionKind`
- `RemoteBrowserCompensatingActionVerification`
- `RemoteBrowserMutatingCommandName`
- `REMOTE_BROWSER_COMPENSATING_ACTIONS`
- `REMOTE_BROWSER_COMPENSATING_ACTION_METADATA_KEY`

Command envelope metadata stays primitive-only for compatibility with
`RemoteCommandEnvelope`. Mutating browser commands therefore carry a
`compensating_action_id` plus primitive summary fields, and clients resolve the
full descriptor from the protocol catalog.

## Current Mutating Commands

| Command                  | Rollback strategy         | Compensating action id                                              | Reversal path                                                                                                                                       | Verification           |
| ------------------------ | ------------------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
| `browser.launch_managed` | `compensating_action`     | `compensating-action:browser-launch-managed-close-session`          | Dispatch `browser.close` for the launched managed session with profile cleanup enabled.                                                             | `profile_removed`      |
| `browser.close`          | `manual_remediation_only` | `compensating-action:browser-close-managed-session-manual-relaunch` | No previous profile state is restored. If needed, an operator launches a new isolated session and replays explicitly approved read-only navigation. | `operator_attestation` |

`browser.navigate`, `browser.snapshot`, and `browser.screenshot` remain
read-only Browser CDP MVP commands. They do not require rollback strategy
metadata because they do not mutate remote browser state under the current
schema.

## Future Mutating Command Requirements

Future mutating browser commands must add a catalog entry before becoming
routable. The descriptor must include:

- stable action id
- mutating browser command name
- rollback strategy, either `compensating_action` or `manual_remediation_only`
- action kind
- operator-readable label and limitations
- suggested Bellona command when an automated compensating command exists
- verification method and verification description

Expected future action kinds are:

- `back_navigation` for reversible page transitions that can return to a known
  previous URL
- `cancel_navigation` for in-flight navigations or downloads that can be safely
  stopped
- `delete_download` for downloaded artifacts that Bellona owns and can remove
- `revoke_form_submission` for site-specific form/account changes that have an
  explicit revocation path
- `manual_remediation` when no truthful automated reversal exists

If a command cannot name a truthful reversal path, it must use
`manual_remediation_only` and state the operator action required. It must not
claim `compensating_action` just because a best-effort cleanup exists.

## Dispatch Boundary

`180.C.11.11` introduces and documents the catalog and populates current browser
mutation metadata. `180.C.11.12` makes `compensating_action_id` mandatory for
mutating browser envelopes and rejects missing, unknown, or command-mismatched
ids before dispatch.

Agents should treat the catalog as binding metadata: every mutating browser
command must carry the catalog id and primitive summary fields so audit,
timeline, and rollback planning can name the available reversal path.
