# `coproduct.provable-coordination.v1`

An [A2A Protocol](https://a2a-protocol.org/latest/) extension that
adds **categorically-grounded coordination guarantees** to any A2A
interaction: capability-bounded execution, provenance lineage on
every response, Pa.Parallel cohort enforcement, and presheaf-log
duality on state.

- **Stable URI**: `https://coproduct.one/ext/provable-coordination/v1`
- **Permanent alias** (planned): `https://w3id.org/coproduct/provable-coordination/v1`
- **Reference implementation**: [coproduct-a2a](https://github.com/coproduct-private/olog/tree/main/crates/coproduct-a2a)
- **A2A version**: v1.0 (JSON-RPC 2.0 primary transport)
- **Breaking-change policy**: any breaking change gets a new URI (`/v2`, …), per A2A spec

## 1. What this extension provides

Three orthogonal guarantees, each backed by a categorical theorem:

1. **Capability envelope** — every call declares the capabilities it
   requires; the server rejects calls whose effective capabilities
   exceed the envelope. Equivalent to a characteristic morphism
   into the capability classifier; rejection is a pullback-square
   failure.
2. **Provenance manifest** — every response carries a signed
   lineage manifest back to concrete inputs, the acting agent, and
   the underlying state revision. Equivalent to the provenance
   fibration from [olog-core](https://github.com/coproduct-private/olog/tree/main/crates/olog-core);
   missing provenance on a visible row is a lift-failure.
3. **Cohort guarantees (Pa.Parallel)** — multi-agent coordinations
   are checked against seven invariants (I1–I7) at the A2A boundary.
   Violations return structured A2A error code `-32006
   PaParallelViolation`.

Responses additionally carry a **hydrate-log revision number** so
clients can verify they observed a single consistent cut of
server state (per the hydrate-log duality theorem — see the
[Pa.DB.* design doc](https://github.com/coproduct-private/olog/blob/main/docs/pa-db-presheaf-design.md)).

## 2. Declaration in the Agent Card

An A2A server that supports this extension MUST advertise it in
its Agent Card's `extensions[]` array:

```json
{
  "name": "Coproduct",
  "service_endpoint": "https://coproduct-a2a.fly.dev/a2a",
  "extensions": [
    {
      "uri": "https://coproduct.one/ext/provable-coordination/v1",
      "required": false,
      "config": {
        "capability_classifier": "https://coproduct.one/classifiers/capability/v1",
        "provenance_signer_pubkey": "ed25519:<base64>"
      }
    }
  ],
  ...
}
```

Clients that need the guarantees declare `required: true` in their
side of the handshake. Per A2A v1.0 semantics, a server that does
not support a `required: true` extension MUST refuse the connection
with A2A error `-32005 UnsupportedExtension`.

## 3. Capability envelope — request shape

Callers SHOULD include a `capability_envelope` field in the
`params` of any A2A method call. The envelope lists the
capabilities the call intends to exercise. If the server's
authorization for the caller does not cover the declared set, the
server MUST reject with A2A error `-32005 UnsupportedExtension`
(extension-semantic subcase).

Envelope schema:

```json
{
  "capabilities": [
    "write:workspace/alice",
    "read:workspace/alice",
    "delegate:agent/reporter"
  ],
  "ttl_seconds": 300,
  "issued_at_ms": 1776960000000,
  "signature": "ed25519:<base64>"
}
```

- `capabilities` — opaque strings following the implementer's
  capability vocabulary. The reference implementation uses the
  Denning-lattice flow-control labels from
  [nucleus-ifc](https://github.com/coproduct-private/nucleus-ifc).
- `ttl_seconds` — envelope expiry from `issued_at_ms`. The server
  MUST reject envelopes past TTL.
- `signature` — ed25519 signature over the canonicalized envelope
  (JCS per RFC 8785). Keys provisioned out-of-band.

## 4. Provenance manifest — response shape

Every response from a server supporting this extension MUST carry
a `provable_coordination` object alongside the A2A result:

```json
{
  "jsonrpc": "2.0",
  "id": "...",
  "result": { ... A2A-standard task/result ... },
  "extensions": {
    "https://coproduct.one/ext/provable-coordination/v1": {
      "manifest_version": "1",
      "provenance_trail": [
        {
          "source": "row:workspace/alice/customer#c1",
          "timestamp_ms": 1776960000012,
          "acting_agent": "agent:reporter",
          "capability": "read:workspace/alice"
        },
        ...
      ],
      "capability_envelope_sha": "<sha256>",
      "cohort_witnesses": [
        { "invariant": "I1", "witness_row": "coop:fanout/reporter-2026-04-22" },
        { "invariant": "I3", "witness_row": "coop:commit/abc123" }
      ],
      "hydrate_log_rev": 418,
      "signature": "ed25519:<base64>"
    }
  }
}
```

The signature is over the JCS-canonicalized manifest payload.
Clients verify the signature against the public key from the
Agent Card's `config.provenance_signer_pubkey`.

## 5. Cohort witnesses (Pa.Parallel I1–I7)

Each witness cites a row in the cooperation log that evidences the
named invariant:

| Invariant | What it proves |
|---|---|
| I1 (FK closure) | Every row referenced has its foreign keys resolved |
| I2 (cohort ≥ 2) | Fanout has at least 2 distinct principals |
| I3 (per-member evidence) | Each cohort member has at least one commit row |
| I4 (fresh fanout) | Fanout row authored in current PR |
| I5 (exempt vs classifier) | Classifier agrees on exempt-reason |
| I6 (strict-no-downgrade) | No silent downgrade from strict to warn |
| I7 (author-binding) | Commit authors match cohort emails |

If any invariant is not satisfied, the server MUST reject with A2A
error `-32006 PaParallelViolation` and include the offending
invariant in the error's `data` field.

## 6. Hydrate-log revision

`hydrate_log_rev` is a monotonic u64 naming the exact delta-log
position at which the response was computed. Clients can re-query
the server with this revision to get deterministic replay (useful
for audit + reproducibility).

Revision 0 is the initial empty state. Each applied delta
increments the revision by exactly one. Applying the same delta
twice is rejected by the underlying presheaf substrate (the
[olog-presheaf](https://github.com/coproduct-private/olog/tree/main/crates/olog-presheaf)
crate pins this with `apply_insert_row_rejects_duplicate`).

## 7. Error taxonomy

| A2A code | Meaning in this extension |
|---|---|
| -32005 UnsupportedExtension | Capability envelope exceeds caller's authorization, or required extension absent from server |
| -32006 PaParallelViolation | One of the seven Pa.Parallel invariants was not satisfied; see `data.invariant` |
| -32603 InternalError | Signing key unavailable; provenance trail could not be assembled |

## 8. Versioning

Per [A2A extension versioning](https://a2a-protocol.org/latest/topics/extensions/),
any breaking change to this document — new required fields, semantic
reinterpretation of existing fields, changes to signature canonicalization —
requires a NEW URI. The `/v1` segment at the end of this URI is
load-bearing.

Non-breaking additions (new optional fields, new error codes in the
`-32006..-32009` band) are permitted without a URI change.

## 9. Compliance mapping (EU AI Act)

For enterprise deployments in the EU:

| Article | How this extension supports it |
|---|---|
| 13 (Transparency) | Provenance manifest on every response is machine-readable AI-output provenance |
| 14 (Human Oversight) | Pa.Parallel I2 (cohort ≥ 2) can be configured to require ≥ 1 human principal for non-exempt fanouts |
| 15 (Accuracy + Cybersecurity) | Signed manifest (ed25519) + capability envelope enforcement |
| 50 (AI Output Marking) | The manifest IS the marking, in a machine-parseable canonical form |

## 10. Reference implementation

The reference implementation is the [coproduct-a2a](https://github.com/coproduct-private/olog/tree/main/crates/coproduct-a2a)
Rust crate. It:

- Advertises this URI in its default Agent Card (`bin/server.rs`)
- Serves this document at `/ext/provable-coordination/v1` (same server, for quick inspection)
- Defines typed Rust structs (`provable_coordination::ProvableCoordinationManifest`,
  `::CapabilityEnvelope`, `::ProvenanceStep`, `::CohortWitness`) that match this schema
- Wires the manifest onto every A2A response in the
  [`a2a.provenance`](https://github.com/coproduct-private/olog/blob/main/docs/pa-a2a-1-prd.md) slice

## 11. Contact + contributions

Maintained by [coproduct.one](https://coproduct.one). Extensions
are not yet publicly registered with AAIF; we plan to submit this
once the reference implementation has at least one external
adopter. Feedback via GitHub issues against the olog repo.