# CARBON Browser Contract v1

`carbon-browser/v1` is CARBON's stable, evidence-aware boundary between test
intent and browser execution. CARBON owns the semantics; interchangeable
adapters perform the work.

```text
CARBON plans, intent tests, exploration, and regressions
                              |
                    carbon-browser/v1
                              |
 host agent | Vibium/BiDi | Playwright/CDP | Selenium | testers.ai devices
```

This is not a browser fork. CARBON's first executable third-party bridge calls
the official Vibium CLI and can run existing Vibium tests while preserving
their command surface. Other engines integrate through the same capability
contract as their executable bridges become available.

## Contract invariants

1. Negotiate capabilities before dispatch. Missing operations and evidence
   channels remain explicit; adapters never silently downgrade.
2. Store semantic intent separately from selectors. Prefer role, accessible
   name, label, visible text, test ID, and a stable adapter reference; re-map
   after navigation or re-render.
3. Every operation returns a result envelope with actual behavior, before and
   after state, timestamps, adapter identity/version, evidence handles, and
   unavailable evidence channels.
4. Preserve CARBON's E0-E3 truth model. A successful click is evidence that the
   adapter clicked; it is not proof that the product is correct.
5. Classify actions before dispatch. Destructive, paid, public, privileged,
   privacy-sensitive, and consequential third-party actions require the same
   scoped human approval as every other CARBON workflow.
6. Redact credentials, tokens, cookies, unrelated private data, and sensitive
   values before durable storage.

The machine-readable source is
[`carbon-browser-v1.json`](carbon-browser-v1.json).

## Adapter manifest

An adapter declares its protocol, identity, version, transport, operations,
evidence channels, session features, and safety behavior. CARBON validates the
manifest and compares it with the current run's required capabilities.

```json
{
  "protocol": "carbon-browser/v1",
  "id": "host-agent.local-browser",
  "name": "Host agent local browser",
  "version": "1.0.0",
  "family": "host-agent",
  "transport": "host-agent",
  "operations": ["session.start", "session.stop", "page.open", "discover.map", "action.click", "capture.screenshot"],
  "evidenceChannels": ["screenshot", "dom", "accessibility"],
  "sessionFeatures": ["isolated-context"],
  "safety": {
    "actionClassification": true,
    "approvalGates": true,
    "redaction": true
  }
}
```

Use `carbon-runtime browser negotiate` to validate an adapter and produce the
explicit supported/missing capability result.

## Operation request

Adapters accept the operation name plus semantic intent and operation-specific
arguments. A request should also carry the test ID, current state, element
description, desired evidence channels, and action classification when those
fields apply.

```json
{
  "protocol": "carbon-browser/v1",
  "requestId": "REQ-0007",
  "sessionId": "CBS-20260801-ABC123",
  "testId": "TEST-CHECKOUT-004",
  "operation": "action.click",
  "intent": "Continue from shipping to payment",
  "target": {
    "role": "button",
    "accessibleName": "Continue to payment",
    "stableRef": "@e17",
    "selectorHints": ["[data-testid='continue-payment']"]
  },
  "actionClass": "state-changing",
  "desiredEvidence": ["screenshot", "dom", "console", "network"]
}
```

## Evidence result envelope

Every completed, failed, blocked, skipped, or cancelled operation returns the
same envelope. `unavailableEvidence` is mandatory so absence is distinguishable
from an empty, clean channel.

```json
{
  "protocol": "carbon-browser/v1",
  "requestId": "REQ-0007",
  "sessionId": "CBS-20260801-ABC123",
  "adapter": {"id": "vibium.local", "version": "0.1.0"},
  "operation": "action.click",
  "status": "succeeded",
  "actual": "The payment step became visible.",
  "startedAt": "2026-08-01T18:00:00Z",
  "finishedAt": "2026-08-01T18:00:01Z",
  "before": {"url": "https://example.test/checkout/shipping", "state": "shipping"},
  "after": {"url": "https://example.test/checkout/payment", "state": "payment"},
  "evidence": [
    {"kind": "screenshot", "handle": "evidence/payment.png"},
    {"kind": "network", "handle": "evidence/payment.har"}
  ],
  "unavailableEvidence": ["video"],
  "warnings": []
}
```

Recorded operation envelopes live in
`.carbon/browser/sessions/<session-id>/operations.jsonl`. CARBON page-evidence
bundles may ingest their safe artifact handles and preserve the adapter and
protocol provenance in the final report.

## Runtime and MCP surface

```bash
bin/carbon-runtime browser contract
bin/carbon-runtime browser validate-adapter --manifest adapter.json
bin/carbon-runtime browser negotiate --manifest adapter.json --require-operation action.click --require-evidence screenshot
bin/carbon-runtime browser init --root <project> --manifest adapter.json --target <url>
bin/carbon-runtime browser record --session-dir <session-dir> --result result.json
bin/carbon-runtime browser summary --session-dir <session-dir>
```

The standalone MCP exposes the same lifecycle through
`carbon_manage_browser_session`. This keeps the protocol useful to hosts that
do not invoke the local CLI directly.

The `carbon_vibium` MCP tool and `bin/carbon-runtime vibium` executable add the
actual Vibium bridge:

```bash
bin/carbon-runtime vibium doctor --root <project>
bin/carbon-runtime vibium exec --root <project> -- map
bin/carbon-runtime vibium run-test --root <project> --file tests/flow.mjs
bin/carbon-runtime vibium generate --root <project> --request "Generate tests" --target <url>
```

CARBON-owned workflows must use this bridge instead of calling `vibium`
directly. For `dialog accept` and `dialog dismiss`, the bridge waits up to five
seconds by default for a dialog produced by asynchronous application code; use
`--dialog-wait-ms 0` only when an immediate probe is intentional. Screenshot
files reported by Vibium are copied into the command's `.carbon/vibium/runs/`
artifact directory before they are referenced as evidence.

CARBON invokes the official binary rather than copying its WebDriver BiDi
implementation. Existing commands and tests remain Vibium-authored; CARBON's
generation, intent, evidence, regression, confidence, and reporting APIs are
additive. Missing evidence channels remain unavailable instead of being
inferred from successful command output.

## Versioning

Additive optional fields and capabilities remain compatible within v1.
Renamed operations, changed required fields, or changed evidence semantics
require a new protocol version. Every session pins the contract and adapter
version so an old run remains explainable.
