Agent Blueprint Protocol

Copy Markdown View Source

Agent Blueprint Protocol is a portable, non-authorizing contract for describing an agent capability and binding one immutable release to an execution environment.

The package is being built as the public reference implementation for two language-neutral artifacts:

  • Blueprint Core — stable identity, typed ports, logical capability requirements, bounds, evidence commitments, and registered extensions.
  • Deployment Manifest — environment-local tool, principal, data, authority, effect, evaluation, and exact-build bindings for one Blueprint release digest.

Protocol validity never grants authority. A consuming host remains responsible for identity, tenancy, policy, live authorization, effect ownership, execution, and evidence retention.

Installation

def deps do
  [
    {:agent_blueprint_protocol, "~> 0.1.0"}
  ]
end

The package has zero production dependencies, no application callback, and no supervision tree.

What it provides

Decoding and validation (every result is a typed fact or a typed denial — never an authorization decision):

  • decode_blueprint/2 — bounded, fail-closed decode of a Blueprint: canonical byte verification, registry validation, portability scan, digest comparison.
  • decode_deployment/2 — the same pipeline for a Deployment Manifest bound to one Blueprint release digest.
  • decode_federation_envelope/2 — the 23-member federation task envelope through the shared registry engine; federation_mapping/0 returns the A2A/MCP Tasks field mapping as data.
  • canonical_bytes/1 — the exact canonical (JCS) wire bytes of a decoded artifact.

Semantics:

  • negotiate/2 — the evolution gate: revision sets, required core fields, and the positional extension state machine (unknown critical denies, unknown optional quarantines byte-exactly).
  • intersect/1 — the bounds algebra: the pointwise narrowest intersection of Blueprint bounds, Deployment host_bounds, and host policy; protected narrowings deny or clamp-with-evidence, never silently.
  • verify_compatibility/2 — identity-exact matching of manifest build identities against host-observed identities.
  • reconcile/3 — the one call per import: the pinned eight-stage pass (canonical, digest, negotiation, structure, portability, signatures, bind, bounds), reject-or-annotate, never repair, under host-supplied inputs.

Tooling: mix conformance.verify executes the shipped 88-case corpus; mix conformance.mutations re-proves the corpus catches named implementation breaks; mix verifier.agreement byte-agrees the Elixir runner with the independent TypeScript verifier.

Status

The protocol API, schemas, canonicalization profile, extension registry, and conformance corpus are implemented and gated locally: 882 tests (59 properties) at 100% coverage, zero Dialyzer errors, --strict Credo clean, an 88-case conformance corpus with a mutation gate, and a byte-agreement gate against an independent second-language verifier. The normative protocol document, docs/protocol.md, ships in the Hex archive. Every build gate's recorded red proof is the requirement map (docs/design/requirement-map.md) — public in this repository, deliberately not in the archive (its verbatim red receipts quote the very internal tokens the publish guard bans from the archive), and mix release.candidate re-derives its completeness from the live project on every run.

The 0.1.x line is the first public release line. The package is pre-1.0: shipped contracts may change within 0.x under pre-1.0 conventions, and every contract change lands with a red-capable test.

Intended properties

  • Language-neutral canonical artifacts with bounded parsing.
  • Fail-closed protocol revision and required-field handling.
  • Bounds that can narrow host policy but can never widen it.
  • Critical extensions that deny when unsupported; optional extensions that round-trip without execution.
  • Exact compatibility manifests and red-capable tamper/downgrade corpora.
  • Zero third-party/Hex production dependencies and no supervision tree.
  • No product-specific tenant, key, grant, endpoint, database, provider, or engine identifiers in portable artifacts.

Development

Built and tested against Elixir 1.20.x on OTP 29.x — the single Elixir/OTP target exercised in CI. Broader target support is not claimed until its own CI receipts exist.

mix deps.get
mix quality

mix quality runs dependency audits, formatting, warnings-as-errors compilation, Credo, tests with the 100% coverage threshold, the conformance corpus and its mutation gate, the second-language verifier agreement gate, Dialyzer, documentation with warnings-as-errors, and the release-candidate check (requirement-map completeness plus protocol-doc coupling). Every gate carries a recorded red proof — see the requirement map at docs/design/requirement-map.md in this repository.

Conformance corpus

The package ships a portable conformance corpus (priv/conformance/) — 88 cases covering every required cell of the 16-surface × 29-class applicability floor, full-registry golden artifacts, RFC 8785 number vectors, and deterministic Ed25519 fixtures. Run it:

mix conformance.verify    # loads, integrity-verifies, and executes the corpus
mix conformance.mutations # breaks the implementation at named points; the corpus must go red

The loader is pure over %{path => binary} and refuses corrupted, incomplete, or empty corpora with typed errors; the report refuses a vacuous green. The corpus is regenerated by MIX_ENV=test mix run --no-start scripts/generate_conformance_corpus.exs, which refuses to write a corpus that does not verify.

Second-language verifier

conformance/verifier/ is a repo-side TypeScript implementation (Node ≥ 24, node: builtins only, zero npm runtime deps — never shipped in the Hex archive) that independently recomputes every corpus verdict and integrity check: its own bounded JSON scanner with duplicate rejection and the integer-window rule, its own JCS canonicalizer (number digits anchored to the native ECMAScript serializer, member sort by UTF-16 code units), domain- separated digests, detached-JWS Ed25519 verification through node:crypto with small-order key rejection, and the negotiation, bounds-algebra, compatibility, and federation semantics. Run it:

node conformance/verifier/cli.ts --corpus priv/conformance  # exit 0/1/2, report bytes on stdout
node conformance/verifier/self_checks.ts                    # RFC 8785 Appendix B, window matrix,
                                                            # Ed25519 keys, stored JOSE vectors
mix verifier.agreement                                     # byte-agrees the TS report with the
                                                            # escript's (repo AND built archive),
                                                            # runs the self-checks, and proves three
                                                            # seeded reds fire

The agreement gate is part of mix quality: the two implementations must produce byte-identical JCS reports over the same corpus, and node ≥ 24 is a hard prerequisite of the gate.

Security

See SECURITY.md. A successful verifier result is structural evidence only, never an authorization decision.

License

Apache License 2.0. See LICENSE and NOTICE.