Generated protocol artifacts

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

make gen-protocol-artifacts

CI and make all verify drift with:

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:

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: canonical ACP fields remain at the session-update root, while Harn vendor fields live under _meta.harn.