# Generated protocol artifacts

Harn publishes downstream protocol artifacts under
`spec/protocol-artifacts/`. The directory is generated by:

```sh
make gen-protocol-artifacts
```

CI and `make all` verify drift with:

```sh
make check-protocol-artifacts
```

The generated contract includes:

- `manifest.json`: protocol versions, schema provenance, ACP method names,
  `sessionUpdate` discriminators, Harn extension fields, tool lifecycle
  metadata fields, A2A task states, MCP metadata vocabulary, and a `bindings`
  block enumerating the published TypeScript, Swift, Python, and Go modules
  with their stability tier and (for Go) the canonical module path.
- `schemas/*.schema.json`: stable copies of the ACP, A2A, and MCP adapter
  profiles validated by `harn test protocols`. MCP publishes both the stable
  `2025-11-25` profile and the opt-in `DRAFT-2026-v1` RC profile so
  downstreams can prepare without changing runtime negotiation behavior.
- `harn-protocol.ts`: TypeScript bindings for JSON-RPC messages, ACP
  `session/update`, Harn tool lifecycle metadata, A2A task events, and MCP
  tool/resource/prompt metadata.
- `HarnProtocol.swift`: Swift `Codable` definitions for the same
  host-facing surface.
- `python/harn_protocol.py`: stdlib-only Python 3.9+ module with `Enum`
  classes for every wire vocabulary, dataclasses for the JSON-RPC envelopes,
  ACP session updates, Harn tool lifecycle metadata, A2A task structures, and
  MCP tool/resource metadata, plus `to_wire`/`from_wire` helpers that strip
  unset optional fields so envelopes stay byte-equivalent to the Rust adapter
  output. Field names match the wire JSON (camelCase).
- `go/harnprotocol/`: Go module (`harnprotocol` package) mirroring the same
  surface with typed string aliases and `encoding/json`-tagged structs. The
  `go.mod` declares `github.com/burin-labs/harn/spec/protocol-artifacts/go/harnprotocol`
  as the canonical module path so consumers can `go get` directly from the
  repository.
- `fixtures/round_trip.json`: representative request/response/notification
  envelopes plus an A2A task and an MCP tool entry. `make check-bindings`
  decodes and re-encodes these through the Python and Go bindings on every
  CI run, catching wire-vocabulary drift before downstream consumers see it.

MCP RC helpers include `DRAFT-2026-v1`, the final scheduled
`2026-07-28` identity, required request `_meta` keys, standard Streamable HTTP
headers (`MCP-Protocol-Version`, `Mcp-Method`, `Mcp-Name`), `server/discover`,
`ttlMs`/`cacheScope` cache hints, `input_required` results, the `-32004`
unsupported-version error, and the JSON Schema 2020-12 dialect URL. The RC
profile is data-only until the final spec lands; servers and clients should
opt in explicitly instead of assuming Harn's stable MCP runtime negotiates it.

## Stability

The host-facing surface listed above is **stable**: existing wire values and
field names will not change without a Harn minor-version migration note plus a
regenerated artifact diff. Hosts can pin to the artifact directory for the
full surface or to the `manifest.json` `bindings` block when they only need to
detect generator/runtime mismatch.

VM internals (the AST, code-index, scanner schemas under
`crates/harn-hostlib/schemas/**` aside from the published wire profiles) are
**not** part of this surface. They evolve with the runtime and should be
consumed via the Rust crates rather than vendored as bindings.

## Versioning

Artifacts follow the Harn crate version in `manifest.json`.

Additive changes are minor-version compatible:

- new `sessionUpdate` or `_harn/agentEvent` values;
- new optional fields under `_meta.harn`;
- new `ToolKind`, `ToolCallStatus`, `ToolCallErrorCategory`, A2A task state,
  or MCP metadata values that clients can ignore safely.

Breaking changes require a Harn minor-version migration note:

- removing or renaming a wire value;
- moving a field between canonical ACP locations and `_meta.harn`;
- changing a required field's type;
- tightening a schema so previously valid Harn adapter output is rejected.

## Consumer migration

Hosts should consume the generated bindings or schema artifacts instead of
mirroring Harn protocol enums by hand. Burin consumers can replace local
`ACPSessionUpdate`, `ACPToolKind`, and `ACPToolCallStatus` mirrors with
`spec/protocol-artifacts/harn-protocol.ts`, and can use
`spec/protocol-artifacts/HarnProtocol.swift` as the Swift contract source for
ACP session updates and tool-call metadata. Python and Go integrators can
import `spec/protocol-artifacts/python/harn_protocol.py` (e.g. by vendoring
the file or pinning the artifact directory) and the
`harnprotocol` Go module under `spec/protocol-artifacts/go/harnprotocol`
respectively.

Cross-repo release jobs can run:

```sh
BURIN_CODE_ROOT=/path/to/burin-code make check-burin-protocol-artifacts
```

to fail when Burin Code's vendored Swift or TypeScript protocol bindings drift
from the Harn source artifacts.

For ACP, clients should still follow the wire namespacing rules in
[Bridge protocol](./bridge-protocol.md): canonical ACP fields remain at the
session-update root, while Harn vendor fields live under `_meta.harn`.
