# Agent Blueprint Protocol — specification

Status: published pre-1.0 protocol (0.x release line). This document is
the normative specification of the Agent Blueprint Protocol. The
reference implementation and its conformance corpus (digest
`sha-256:sg6Fo7p8nZpJDzxFn4dXHBWgbGvEvtOk-7t3m7OT7Yo`, 94 cases) are
certified against this document at every release through the release
identity chain — the specification digest, the package version, and the
corpus and registry digests are pinned together per release, and the
release-candidate check asserts the chain from live state. Where this
document and the implementation disagree, one of them is defective and
the release does not ship until the chain is reconciled.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. Keywords apply to what a conforming
implementation (the Conformance clause) is required to do; prose that
describes the reference implementation without stating a requirement is
informative.

**The protocol is non-authorizing.** It validates structure, canonical
bytes, bounds, compatibility, and evidence. Protocol validity never
grants authority: a consuming host remains responsible for identity,
tenancy, live policy, effect ownership, execution, and evidence
retention. Every verification result — including a fully green one — is
evidence, never a decision.

## 1. Scope, non-goals, and terminology

Two language-neutral artifacts:

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

Deliberately out of scope (host-owned): runtime kernel, live authority
and grants, effect admission/replay/recovery, product schemas, transport
clients, billing, evaluation truth. The package compiles to an inert
library: no supervision tree, no application callback, zero third-party
production dependencies.

### Terminology

- **Artifact** — a Blueprint or Deployment Manifest value together with
  its exact canonical bytes; the artifact's identity is its content
  digest — the digest of the artifact's digest-covered members over
  those canonical bytes (the digest section defines the exact input;
  the digest member itself, signatures, and attestations are
  excluded).
- **Host** — the consuming runtime. Every non-establishment obligation
  in this protocol belongs to a host, and a green result never
  transfers one to the package.
- **Deny** — the fail-closed outcome: a typed error code with subject
  and optional detail. A deny is never a repair and never a silent
  skip; where this document states a requirement as a deny, the
  requirement is absolute (MUST-level) and the error code named is the
  code that enforces it.
- **Quarantine** — retain byte-exactly without validating or executing:
  an unknown optional extension's payload round-trips, is typed as
  unscanned, and confers no portability claim.
- **Clamp** — the effective narrowing of an operational bound, emitted
  with evidence whenever effective differs from requested; protected
  bounds deny instead of clamping.
- **Ceiling vs bound** — operational bounds are magnitude limits that
  narrow pointwise; protected ceilings are ordinal-lattice positions
  (classification, disclosure, effect impact, authority, approval) that
  never widen and deny narrowing by default (both in the evolution
  laws). A parse ceiling is neither: it is a tighten-only decoder
  limit, never an intersection input.
- **Evidence** — a structured observation about bytes or structure:
  per-surface check results, clamp records, and the non-empty
  `not_verified` set naming what was NOT established. Evidence is
  input to a host decision; it is never a decision.
- **Portability** — the property that an artifact carries no
  environment-bound values (secrets, keys, grants, tenant ids,
  endpoints, engine ids); enforced structurally and honestly limited
  (the portability section).
- **Posture** — the declared stance of a surface: fail-closed (deny),
  acknowledge-and-record (clamp with evidence, or a typed notice), or
  opt-in (a host-supplied policy).
- **Authored channel** — the `:authored_extensions` path by which a
  producer-declared critical extension body, validated against a
  digest-pinned host schema, is treated as authored content and spared
  the generic value-shape heuristics (still covered by the artifact's
  digest).

## 2. Artifacts and the closed world

Both artifacts MUST decode as JSON objects under the bounded ceilings
(depth, members, items, nodes, string bytes, key bytes, number lexemes
— the ceiling family). Decoding MUST be fail-closed under the pinned
failure precedence: unknown member → missing required → type →
constraint → cardinality → nested → cross-field hooks.

The registries are closed worlds — the exact member sets the shipped
tables define:

- **Blueprint Core (18 members).** Required: `blueprint_id`,
  `protocol_revision`, `producer`, `release_number`,
  `capability_requirements`, `input_ports`, `output_ports`,
  `output_contract`, `triggers`, `ceilings`, `classification_ceiling`,
  `effect_intents`, `evaluation_assertions`, `extensions`,
  `required_core_fields`, `content_digest`. Optional: `signatures`,
  `attestations`.
- **Deployment Manifest (19 members).** Required: `protocol_revision`,
  `blueprint_release`, `scope_projection`, `tool_bindings`,
  `data_bindings`, `authority_requirement`, `effect_owner`,
  `signer_custody`, `eligibility`, `model_policy`, `host_bounds`,
  `lifecycle`, `build_identities`, `evaluation_binding`, `extensions`,
  `required_core_fields`, `deployment_digest`. Optional: `signatures`,
  `attestations`.

Every core member addition MUST be accompanied by a protocol revision
increment: an older consumer rejects an unknown member, so the
vocabulary can only evolve at a revision boundary. No identifier in the
package — module, function, path, corpus, or config — carries a version
token; the Hex package version is the sole version number.

A complete, valid Blueprint as it travels on the wire (the conformance
corpus's `blueprint-decode-valid` case, byte-exact — every fenced
JSON example in this specification is a corpus case):

```json corpus:blueprint-decode-valid
{"blueprint_id":"example.demo/echo","capability_requirements":[{"approval_trait":"none","argument_schema":{"type":"object"},"authority_trait":"none","classification_ceiling":"internal","impact_class":"ordinary","operation_family":"example.demo.read_shape","operation_kind":"read","result_schema":{"type":"object"}}],"ceilings":{"max_attempts":3,"max_concurrency":2,"max_cost":{"amount":1000,"currency":"USD"},"max_depth":8,"max_descendants":64,"max_elapsed_ms":60000,"max_fan_out":4,"max_tokens":100000},"classification_ceiling":"internal","content_digest":"sha-256:b1Aw4cU5AbV9k8bdbZkRCsySDHGpTAwB-aQm57Wh7B8","effect_intents":[{"impact_class":"ordinary","logical_operation":"record_summary","operation_kind":"mutation"}],"evaluation_assertions":[{"kind":"output_schema","port":"result","schema":{"type":"object"}}],"extensions":{"critical":{},"optional":{}},"input_ports":[{"classification_ceiling":"internal","name":"request","required":true,"schema":{"type":"object"}}],"output_contract":{"classification_ceiling":"internal","port":"result"},"output_ports":[{"classification_ceiling":"internal","name":"result","required":true,"schema":{"type":"object"}}],"producer":{"created_at":"2026-08-20T00:00:00Z","identity":"example.demo","toolchain":"example.demo.toolchain"},"protocol_revision":1,"release_number":1,"required_core_fields":[],"triggers":["manual"]}
```

### Member grammar — Blueprint Core (18 members)

Cardinality `1` members are required; `0..1` members are optional.
The failure precedence is the pinned closed-world order: unknown
member → missing required → type → constraint → cardinality →
nested → cross-field hooks. Every sub-member listed inside an
object/array type is required unless marked `(opt)`. The machine-
readable grammar artifacts (CDDL under `spec/grammar/`, with the
derived JSON Schema beside them) are bound to these tables by the
grammar-derivation gate: root member sets and required flags are
cross-read against the compiled registries, and the corpus goldens
validate under the derived schemas. The derived schemas close the
artifact root; sub-object closure and cross-member hooks remain the
reference implementation's to enforce.

| Member | Card. | Type | Constraints |
|---|---|---|---|
| `blueprint_id` | 1 | string | value: producer-qualified name |
| `capability_requirements` | 1 | array<object{ operation_family:string; argument_schema:custom; result_schema:custom; operation_kind:enum(computation\|mutation\|read); impact_class:enum(authority\|money\|ordinary\|secret); classification_ceiling:enum(confidential\|internal\|public\|restricted); approval_trait:enum(human_required\|none\|separated_human_required); authority_trait:enum(external_authority_required\|local_policy\|none) }> | max 64, unique by operation_family |
| `ceilings` | 1 | object{ max_attempts:integer; max_concurrency:integer; max_depth:integer; max_descendants:integer; max_elapsed_ms:integer; max_fan_out:integer; max_tokens:integer; max_cost:object{ amount:integer; currency:string } } | — |
| `classification_ceiling` | 1 | enum(confidential\|internal\|public\|restricted) | — |
| `effect_intents` | 1 | array<object{ logical_operation:string; operation_kind:enum(computation\|mutation\|read); impact_class:enum(authority\|money\|ordinary\|secret) }> | max 64, unique by logical_operation |
| `evaluation_assertions` | 1 | array<custom> | max 128 |
| `extensions` | 1 | custom | — |
| `input_ports` | 1 | array<object{ name:string; schema:custom; classification_ceiling:enum(confidential\|internal\|public\|restricted); required:boolean }> | max 64, unique by name |
| `output_contract` | 1 | object{ port:string; classification_ceiling:enum(confidential\|internal\|public\|restricted) } | — |
| `output_ports` | 1 | array<object{ name:string; schema:custom; classification_ceiling:enum(confidential\|internal\|public\|restricted); required:boolean }> | max 64, unique by name |
| `producer` | 1 | object{ identity:string; created_at:string; toolchain:string } | — |
| `protocol_revision` | 1 | integer | value: positive integer |
| `release_number` | 1 | integer | value: positive integer |
| `required_core_fields` | 1 | array<string> | unique by value |
| `triggers` | 1 | array<enum(condition\|delegated\|evaluation\|manual\|schedule)> | min 1, unique by value |
| `signatures` | 0..1 | array<custom> | max 16 |
| `attestations` | 0..1 | array<any> | max 16 |
| `content_digest` | 1 | string | value: tagged digest |

### Member grammar — Deployment Manifest (19 members)

Cardinality `1` members are required; `0..1` members are optional.
The failure precedence is the pinned closed-world order: unknown
member → missing required → type → constraint → cardinality →
nested → cross-field hooks. Every sub-member listed inside an
object/array type is required unless marked `(opt)`. The machine-
readable grammar artifacts (CDDL under `spec/grammar/`, with the
derived JSON Schema beside them) are bound to these tables by the
grammar-derivation gate: root member sets and required flags are
cross-read against the compiled registries, and the corpus goldens
validate under the derived schemas. The derived schemas close the
artifact root; sub-object closure and cross-member hooks remain the
reference implementation's to enforce.

| Member | Card. | Type | Constraints |
|---|---|---|---|
| `authority_requirement` | 1 | object{ adapter_identity:string; profile_identity:string } | — |
| `blueprint_release` | 1 | object{ blueprint_id:string; release_number:integer; content_digest:string } | — |
| `build_identities` | 1 | array<object{ kind:enum(adapter\|build\|extension\|package); name:string; version:string; digest:string }> | max 128, min 1, unique by name |
| `data_bindings` | 1 | array<object{ logical_dataset:string; classification_ceiling:enum(confidential\|internal\|public\|restricted); as_of:object{ mode:enum(none\|required); max_age_ms:custom } }> | max 64, unique by logical_dataset |
| `effect_owner` | 1 | object{ adapter_identity:string; idempotency:object{ key_derivation:enum(host); recovery:enum(authoritative\|none) } } | — |
| `eligibility` | 1 | object{ owner:custom; beneficiary:custom; runtime_principal:custom } | — |
| `evaluation_binding` | 1 | object{ adapter_identity:string; corpus:object{ name:string; digest:string } } | — |
| `extensions` | 1 | custom | — |
| `host_bounds` | 1 | object{ approval_trait:enum(human_required\|none\|separated_human_required); authority_trait:enum(external_authority_required\|local_policy\|none); classification_ceiling:enum(confidential\|internal\|public\|restricted); disclosure_ceiling:enum(detail\|full\|none\|summary); effect_impact_ceiling:enum(authority\|money\|ordinary\|secret); max_attempts:integer; max_concurrency:integer; max_cost:object{ amount:integer; currency:string }; max_depth:integer; max_descendants:integer; max_elapsed_ms:integer; max_fan_out:integer; max_tokens:integer } | — |
| `lifecycle` | 1 | object{ state:enum(active\|draft\|retired); activated_at (opt):string; retired_at (opt):string } | — |
| `model_policy` | 1 | object{ allowed_model_roles:array<string>; max_tokens:integer; max_cost:object{ amount:integer; currency:string } } | — |
| `protocol_revision` | 1 | integer | value: positive integer |
| `required_core_fields` | 1 | array<string> | unique by value |
| `scope_projection` | 1 | object{ adapter_identity:string } | — |
| `signer_custody` | 1 | enum(external_kms\|holder_edge\|host_managed) | — |
| `tool_bindings` | 1 | array<object{ logical_operation:string; adapter_identity:string; descriptor_digest:string; schema_digest:string; attested_at:string }> | max 128, unique by logical_operation |
| `signatures` | 0..1 | array<custom> | max 16 |
| `attestations` | 0..1 | array<any> | max 16 |
| `deployment_digest` | 1 | string | value: tagged digest |

## 3. Bytes

- **Encoding:** interchange bytes MUST be UTF-8 JSON within the decoder
  ceilings. Duplicate members MUST deny `:duplicate_member` (I-JSON);
  trailing bytes MUST deny `:trailing_bytes`.
- **Integer window:** a pure-digit lexeme above ±(2^53−1) decodes as a
  float iff that double's canonical ECMAScript serialization reproduces
  the lexeme byte-exactly; every other above-bound lexeme MUST deny
  `:number_not_double_expressible`. Core fields are integer-typed by
  schema: a float-tagged window value in a core field MUST deny
  `:invalid_type`.
- **base64url:** unpadded, exact alphabet; padded input MUST deny
  `:base64url_padded`, non-alphabet input MUST deny `:base64url_invalid`.
- **Canonicality:** interchange bytes MUST already be canonical —
  decode → re-encode → byte-compare; non-canonical bytes MUST deny
  `:non_canonical_bytes` before any semantic read, and digests MUST be
  computed only over the exact received bytes.

## 4. Canonicalization

The canonical form MUST be RFC 8785 JSON Canonicalization Scheme:

- No whitespace between tokens (§3.2.1).
- Control characters U+0000–U+001F escaped as lowercase `\uXXXX` except
  the five short escapes; `"` and `\` escaped; a lone surrogate denies
  (§3.2.2.2).
- Numbers per ECMA-262 7.1.12.1 including the Note 2 enhancement:
  `1.0 → "1"`, `1.0e22 → "1e+22"`, `-0.0 → "0"`, `5.0e-324 → "5e-324"`,
  `1.7976931348623157e308 → "1.7976931348623157e+308"`; NaN and Infinity
  deny (§3.2.2.3).
- Object members sorted as UTF-16 code units compared as unsigned
  integers (§3.2.3) — NOT by UTF-8 byte order: for `U+FF3A` vs
  `U+10000`, UTF-16 order puts `U+10000` first.

## 5. Digest

```
digest_bytes = SHA-256( domain_separator || <<0>> || JCS(digest_input) )
```

`digest_input` is the artifact object minus `content_digest` (or
`deployment_digest`), `signatures`, and `attestations` — everything
else is covered, including extensions and unknown-but-optional
extension payloads retained verbatim.

| Purpose | Separator |
|---|---|
| Blueprint content | `agent-blueprint-protocol/blueprint-content` |
| Deployment content | `agent-blueprint-protocol/deployment-content` |
| Federation envelope | `agent-blueprint-protocol/federation-envelope` |
| Signature input | `agent-blueprint-protocol/signature` |
| Conformance report | `agent-blueprint-protocol/conformance-report` |
| Corpus index | `agent-blueprint-protocol/corpus-index` |

Separators carry no version token: `protocol_revision` is itself a
covered member. The wire form MUST be the self-identifying tagged string
`sha-256:<43-char unpadded base64url>`, never a bare hex blob; an
unknown algorithm tag MUST deny `:digest_algorithm_unsupported`, a
malformed body MUST deny `:digest_encoding_invalid`. Algorithm succession
is therefore a data change, not a format break.

## 6. Signature envelope

Signatures are detached and evidence-only. The package verifies; it
MUST NOT sign, MUST NOT accept a private key on any public function,
and MUST NOT embed public keys in artifacts (the host supplies trusted
keys).

- Format: RFC 7515 compact + RFC 7797 `b64=false` unencoded detached
  payload. Protected header: `{alg: EdDSA, kid, crit: ["b64"], b64:
  false}`. Ed25519 only; an unknown `alg` MUST deny.
- `signed_attributes = {algorithm, content_digest, created_at, key_id,
  purpose}` with `purpose` one of `blueprint` | `deployment` |
  `federation-envelope`; the signing input is the signature domain
  separator, a zero byte, and JCS(signed_attributes).
- Because the digest covers `protocol_revision`, identity members,
  extensions, and `required_core_fields`, a signature cannot be lifted
  onto a different artifact, revision, or purpose; `key_id` prevents key
  substitution. A `key_id` matching no supplied key MUST produce a
  `verified: false` check entry with `:signature_key_unsupported` — the
  package performs no key discovery, fetch, or trust selection.
- Attestations use the identical envelope with a registered `kind` and
  a `statement_digest`. The attestation kind registry is empty by
  design in this release.
- Small-order Ed25519 public keys (identity and order-2 encodings)
  MUST reject `:signature_key_unsupported`.

## 7. Evolution and negotiation

`protocol_revision` is a digest-covered body member. This release is
revision 1. A consumer's support MUST declare an explicit revision SET
(never a range); a revision outside the set MUST deny
`:protocol_revision_unsupported` — above-max and below-min alike, both
fail-closed.

`required_core_fields` is the producer's declaration of which covered
core members a consumer must honor. Three checks, all fail-closed:
every entry names a known core member (`:required_core_field_unsupported`),
is digest-covered (`:required_core_field_not_digest_covered` — an
evidence-only member laundered into a requirement is a tamper blind
spot), and is in the consumer's supported set.

### Extension criticality

For each `namespace → {criticality, payload}` in `extensions`, the
outcomes in this table are absolute requirements:

| Registry state | Declared critical | Declared optional |
|---|---|---|
| unregistered | deny `:extension_unknown_critical` | retained verbatim, quarantined, never executed |
| reserved | deny `:extension_unknown_critical` | retained verbatim; typed notice |
| active, criticality matches | supported | retained and executable |
| active, criticality mismatch | deny `:extension_criticality_conflict` | deny `:extension_criticality_conflict` |
| deprecated | supported + typed notice | supported + typed notice |
| retired | deny `:extension_retired` | retained verbatim; typed notice |

An unknown optional extension MUST round-trip byte-exactly (`decode →
to_value → encode` is a fixed point, property-tested). Lifecycle
asymmetry: optional→critical promotion requires a revision increment;
demotion does not. A retired namespace MUST never be reused.

## 8. Extension registry

Namespace form: reverse-DNS-plus-path (`com.example.commerce/graph`),
lowercase, one `/`, length-ceilinged, and not parseable as an absolute
URI with a network authority (a namespace can never double as an
endpoint). The registry MUST ship as compiled-in data in the package —
registry content is a code release; there is no runtime registry file,
and drift between shipped code and shipped registry is
unrepresentable. The governance-canonical SOURCE is the specification
tree's registry document (`spec/registry/registry.json`), bound to both
compiled twins and the corpus index by the registry equality gate. Registered at this release:

| Namespace | Owner | Criticality | State |
|---|---|---|---|
| `com.example.commerce/graph` | ExampleCommerce | critical | active |
| `com.example.commerce/classification-labels` | ExampleCommerce | optional | active |
| `com.example.commerce/rubric-assertion` | ExampleCommerce | optional | active |
| `com.example.platform/estate` | ExamplePlatform | optional | deprecated |
| `com.example.platform/estate-contract` | ExamplePlatform | critical | active |
| `com.example/federation` | Agent Blueprint Protocol | critical | active |

`com.example.platform/estate-contract` is the product-extension registration:
the first product-owned critical namespace with an authored schema pin. The
document ships as corpus data
(`priv/conformance/schemas/estate-contract.schema.json`); `lib/` carries only
the digest pin, test-bound to the shipped file. The deprecated
`com.example.platform/estate` placeholder retains its optional bodies with a
typed notice — existing artifacts stay verifiable.

Critical-extension bodies validate only against a host-supplied schema
whose digest matches the registry's `schema_digest`; a missing schema
denies `:extension_schema_unavailable`, a mismatched digest denies
`:extension_schema_digest_mismatch`. Entry changes are owner-made,
changelog-recorded, and ADR-recorded. The registry's own digest is
bound into the corpus index but not into artifact digests: an artifact
must remain verifiable against a registry that legitimately gained
entries after it was produced; hosts wanting pinning SHOULD use
`build_identities`.

## 9. Bounds algebra

Two bound families, never conflated with parse ceilings (those are
tighten-only decoder limits):

- **Operational** (8 members, all REQUIRED — absent is
  `:missing_ceiling`, never infinity): `max_attempts`,
  `max_concurrency`, `max_cost`, `max_depth`, `max_descendants`,
  `max_elapsed_ms`, `max_fan_out`, `max_tokens`. Pointwise narrowest
  meet; every narrowing MUST emit clamp evidence.
- **Protected** (5 members: `classification_ceiling`,
  `disclosure_ceiling`, `effect_impact_ceiling`, `authority_trait`,
  `approval_trait`): ordinal lattices (plus set-monotone markers
  `{pci, phi}` on classification). Narrowing a protected bound MUST
  deny `:protected_bound_clamp_denied` by default; a host MAY opt into
  an acknowledge posture, which MUST always record evidence.
  Obligation families (authority, approval, effect impact) meet at the
  STRICTEST value; markers are retained regulatory obligations whose
  effective set is the UNION of sources — dropping one is a widening.

Laws (property-tested): meet is idempotent, commutative, associative;
effective bounds MUST NOT widen host policy (`not widens?(effective,
host)` universally); a clamp is emitted iff effective ≠ requested on an
operational field. `model_policy` and `data_bindings` are not
intersection inputs.

## 10. Compatibility and binding

A manifest's `blueprint_release` MUST bind to exactly one Blueprint
content digest (digest equality only — no fuzzy match).
`build_identities` carry exact identities; compatibility verification
MUST be identity-exact or deny: a range expression, missing entry, or
duplicate denies (`:compatibility_identity_inexact`,
`:compatibility_entry_missing`, `:compatibility_duplicate_entry`).
Binding verification is a pinned deny-ordered check including
attestation freshness (`:binding_attestation_stale`) and
descriptor-digest equality (`:binding_descriptor_mismatch` — the tool
rug-pull case).

## 11. Federation profile

A 23-member task envelope carried in A2A `Task.metadata` / MCP `_meta`
under the registered `com.example/federation` extension; the full
field-by-field A2A/MCP mapping (3 native, 5 partial, 15 extension
members) also ships with the reference implementation's document set.
Zero native wire fields; no native transport. State codecs MUST be
lossy-aware: A2A `REJECTED`/`AUTH_REQUIRED` deny crossing into MCP,
`UNSPECIFIED` is unmapped (`:federation_state_unmappable`);
cancellation MUST remain a request, never a terminal receipt. A
Terminal Commitment digests task identity, terminal state, result
digest, result classification, compatibility ref, authority-proof
refs, and checkpoint-history commitment; ANY divergence between
receipts for one task identity MUST deny
`:federation_terminal_conflict` — not just state divergence.
`Federation.verify_commitment` compares issuer/subject/audience
against the receiving context (`:audience_mismatch`). AgentCard
signing carries a protobuf field-presence pre-normalization on top of
JCS (documented in the mapping so adapters do not inherit silent
verification failure). Correlation grants nothing.

### Member grammar — Federation TaskEnvelope (23 members)

The envelope is a closed world: one wire member per logical field,
carried as the extension body under the `com.example/federation`
namespace on both transports. Cardinality `1` members are required;
`0..1` members are optional (absent — there is no null form). The
machine-readable grammar ships as the CDDL artifact under
`spec/grammar/` with the derived JSON Schema beside it. Cross-
member hooks: `checkpoint_status` MUST NOT coexist with `terminal_state`
(`:invalid_constraint`), and the terminal hooks bind
`terminal_state`/`evidence_receipt` presence together. The receipt's
`terminal_commitment` is the domain-separated digest of the seven
Terminal-Commitment components.

| Member | Card. | Wire form |
|---|---|---|
| `task_identity` | 1 | identifier string |
| `idempotency_identity` | 1 | identifier string |
| `parent_execution_reference` | 0..1 | identifier string |
| `initiating_subject` | 0..1 | identifier string |
| `blueprint_digest` | 1 | tagged digest |
| `deployment_digest` | 1 | tagged digest |
| `input_commitment` | 1 | tagged digest |
| `result_schema` | 1 | tagged digest (result schema identity) |
| `result_classification_ceiling` | 1 | classification enum element |
| `time_policy` | 1 | object{ elapsed_ms: positive integer } |
| `resource_policy` | 1 | object{ attempts, concurrency, tokens, cost: positive integers } |
| `recovery_handle` | 1 | identifier string |
| `issuer` | 1 | identifier string |
| `subject` | 1 | identifier string |
| `audience` | 1 | identifier string |
| `identity_mapping_evidence` | 1 | identity-evidence object (correlation only) |
| `checkpoint_request` | 0..1 | object{ kind: checkpoint enum; request_digest: tagged digest } |
| `checkpoint_status` | 0..1 | checkpoint-status enum |
| `checkpoint_commitment` | 0..1 | tagged digest |
| `terminal_state` | 0..1 | terminal-state enum |
| `evidence_receipt` | 0..1 | object{ result_digest: tagged; checkpoint_history_commitment: tagged; terminal_commitment: tagged; signature: detached JWS envelope } |
| `compatibility_reference` | 1 | array (min 1, unique by name) of object{ name: identifier; identity: nonempty string } |
| `authority_proof_references` | 1 | array of tagged digests |

## 12. Error vocabulary

A closed typed set — `%Error{code, subject, detail}`. An
implementation MUST NOT emit an undeclared code, and every code it
declares MUST be reachable (enforced two-directionally by a build
gate).
The 74 codes of this release, with semantics (when the code is
raised, the subject it names, and the host action it demands):

| Code | Raised when | Subject | Host action |
|---|---|---|---|
| `attestation_malformed` | an attestation envelope fails its structural parse | attestations | reject the artifact |
| `audience_mismatch` | a federation receipt's issuer/subject/audience does not match the receiving context | federation envelope | reject the receipt |
| `base64url_invalid` | a base64url lexeme carries a non-alphabet character | offending member | reject the artifact |
| `base64url_padded` | a base64url value arrives padded | offending member | reject the artifact |
| `binding_attestation_stale` | a tool-binding attestation is older than the pinned freshness window | tool_bindings | reject the import as stale |
| `binding_descriptor_mismatch` | a bound tool's descriptor digest differs from the observed descriptor | tool_bindings | halt the binding (rug-pull guard) |
| `binding_incomplete` | the binding check set is incomplete where completeness is required | bind surface | halt the import (reconcile denies) |
| `bound_source_missing` | an intersection input names a bound source that is absent | bounds sources | reject the intersection call |
| `bound_unit_mismatch` | two bounds meet with incompatible units | bounds | reject the intersection call |
| `bound_unknown` | an unknown bound name appears | bounds | reject the artifact |
| `bound_value_invalid` | a bound value fails its shape or range check | bounds | reject the artifact |
| `compatibility_duplicate_entry` | build_identities carries a duplicate identity | build_identities | reject the manifest |
| `compatibility_entry_missing` | verification names an identity with no manifest entry | build_identities | deny compatibility |
| `compatibility_identity_inexact` | a build identity is a range or fuzzy form | build_identities | reject the manifest |
| `corpus_applicability_incomplete` | the corpus applicability floor has uncovered cells | corpus index | operator: fix the corpus; never a wire condition |
| `corpus_case_id_duplicate` | two corpus cases share an id | corpus | operator: fix the corpus |
| `corpus_case_invalid` | a corpus case fails its own schema | corpus | operator: fix the corpus |
| `corpus_count_mismatch` | the index case total disagrees with the case set | corpus index | operator: regenerate the index |
| `corpus_empty` | the corpus carries no cases | corpus | operator: fix the corpus |
| `corpus_file_set_mismatch` | the corpus file set differs from the index (both directions) | corpus | operator: fix the corpus |
| `corpus_hash_mismatch` | a corpus file's hash differs from the index entry | corpus | operator: fix the corpus |
| `corpus_index_invalid` | the corpus index fails its structural parse | corpus index | operator: regenerate the index |
| `deployment_digest_mismatch` | the declared deployment digest differs from the computed digest | deployment_digest | reject the manifest (tamper) |
| `digest_algorithm_unsupported` | an unknown digest algorithm tag | digest member | reject the artifact |
| `digest_encoding_invalid` | a malformed digest body | digest member | reject the artifact |
| `digest_mismatch` | a content digest differs from the computed digest | content_digest | reject the artifact (tamper) |
| `duplicate_member` | a duplicate JSON member name (I-JSON) | bytes | reject the artifact |
| `extension_criticality_conflict` | declared criticality conflicts with the registry | extensions | reject the artifact |
| `extension_duplicate` | one namespace appears twice in extensions | extensions | reject the artifact |
| `extension_namespace_invalid` | a namespace fails the reverse-DNS-plus-path form | extensions | reject the artifact |
| `extension_payload_forbidden` | a payload appears where the registry forbids one | extensions | reject the artifact |
| `extension_retired` | a retired namespace is declared | extensions | reject the artifact |
| `extension_schema_digest_mismatch` | a critical body's validating schema digest differs from the registry pin | extensions | reject the artifact |
| `extension_schema_unavailable` | no host schema is supplied for a digest-pinned critical body | extensions | reject the artifact |
| `extension_unknown_critical` | an unregistered or reserved namespace is declared critical | extensions | reject the artifact |
| `federation_mapping_conflict` | a state has no consistent mapping on the target transport | federation codec | reject the crossing |
| `federation_state_unmappable` | a state is unmappable (e.g. A2A UNSPECIFIED) | federation codec | reject the crossing |
| `federation_terminal_conflict` | two receipts for one task identity diverge in any commitment component | federation envelope | reject the later receipt |
| `forbidden_portable_value` | a value shape trips the portability denylist | offending member | reject the artifact |
| `integer_magnitude` | an integer above the parse window | offending lexeme | reject the artifact |
| `invalid_cardinality` | an array violates min/max items | offending member | reject the artifact |
| `invalid_constraint` | a member fails its check constraint | offending member | reject the artifact |
| `invalid_encoding` | a member fails its encoding form | offending member | reject the artifact |
| `invalid_number` | a number lexeme is malformed | bytes | reject the artifact |
| `invalid_syntax` | the JSON text is syntactically invalid | bytes | reject the artifact |
| `invalid_type` | a member's JSON type disagrees with the schema | offending member | reject the artifact |
| `lifecycle_state_invalid` | a deployment lifecycle state is unknown | lifecycle | reject the manifest |
| `missing_ceiling` | an operational bound is absent (never infinity) | ceilings | reject the artifact |
| `missing_required_field` | a required member is absent | the member | reject the artifact |
| `no_authoritative_recovery` | a mutation-kind operation is bound while the effect owner's recovery is none | effect_owner | reject the import |
| `non_canonical_bytes` | interchange bytes are not already canonical | bytes | reject before any semantic read |
| `nonportable_content` | an authority-shaped claim rides portable content | offending member | reject the artifact |
| `number_not_double_expressible` | an above-window integer is not exactly double-expressible | offending lexeme | reject the artifact |
| `predicate_nodes_exceeded` | a predicate AST exceeds the node ceiling | predicate | reject the artifact |
| `predicate_op_unknown` | a predicate names an unknown operator | predicate | reject the artifact |
| `predicate_path_unresolved` | a predicate path resolves against no declared port | predicate | reject the artifact |
| `protected_bound_clamp_denied` | a protected bound narrows without the acknowledge opt-in | bounds | reject, or opt in and record evidence |
| `protocol_revision_unsupported` | the revision is outside the declared set (both directions) | protocol_revision | reject the artifact |
| `required_core_field_not_digest_covered` | a required core field names an evidence-only member | required_core_fields | reject the artifact |
| `required_core_field_unsupported` | a required core field names no known core member | required_core_fields | reject the artifact |
| `schema_complexity_exceeded` | a schema exceeds the complexity meter | schema document | reject the artifact |
| `schema_dialect_unknown` | a schema names an unknown dialect | schema document | reject the artifact |
| `schema_invalid_shape` | a schema is structurally malformed | schema document | reject the artifact |
| `schema_keyword_not_allowed` | a schema uses a keyword outside the bounded dialect | schema document | reject the artifact |
| `schema_keyword_value_invalid` | a schema keyword carries an invalid value | schema document | reject the artifact |
| `schema_ref_cycle` | a schema $ref cycle | schema document | reject the artifact |
| `schema_ref_unresolvable` | a schema $ref resolves nowhere | schema document | reject the artifact |
| `signature_algorithm_unsupported` | an unknown signature algorithm | signatures | halt the import (reconcile denies) |
| `signature_key_unsupported` | no supplied key matches, or a small-order key | signatures | halt the import (reconcile denies) |
| `signature_malformed` | a signature envelope fails its parse | signatures | halt the import (reconcile denies) |
| `signature_not_verified` | the cryptographic verification fails | signatures | halt the import (reconcile denies) |
| `trailing_bytes` | bytes follow the JSON value | bytes | reject the artifact |
| `unknown_bound` | a bounds member name is unknown | bounds | reject the artifact |
| `unknown_member` | a member is outside the closed world | the member | reject the artifact |
Plus the parameterized ceiling family `{:ceiling, key}` over the eight
decoder limit names. No authorization vocabulary exists in any
identifier — no `:unauthorized` in either polarity (source-scanned
gate).

## 13. Evidence and reconcile

`reconcile(blueprint, deployment, inputs)` is the one call per import:
canonical → digest → negotiation → structure → portability →
signatures → bind → bounds, in that pinned order. Its result is an
`%Evidence{}` of per-surface checks, effective bounds, clamp evidence,
and `not_verified` — which MUST be non-empty BY CONSTRUCTION, always
naming at least the seven host-owned surfaces this protocol structurally
cannot establish: `tenancy`, `live_policy`, `authority`,
`effect_ownership`, `execution`, `billing`, `evaluation_truth`. A
caller SHOULD NOT read an Evidence record and conclude "everything is
fine": the record itself names what it did not check.

## 14. Portability

Portable artifacts MUST NOT contain secrets, private keys, live grants,
tenant identifiers, raw endpoints, database primary keys, or backend
engine identifiers — enforced structurally (member-name and value-shape
denylists over the open regions, at any depth, name-spelling-normalized)
and red-cased per class in the corpus. A portability pass is not
sufficiency — the guard is necessary, not sufficient: opaque
quarantined extension bodies are typed as unscanned, and portability
claims attach only to schema-validated content. Concrete provider/model
names, credentials, engine ids, and endpoints resolve host-side and are
unrepresentable in self-fulfilling artifacts.

## 15. Conformance

The package ships a portable conformance corpus (`priv/conformance/`):
94 cases covering every required cell of the 16-surface × 31-class
applicability floor, full-registry golden artifacts, RFC 8785 number
vectors, and deterministic Ed25519 fixtures, at corpus digest
`sha-256:sg6Fo7p8nZpJDzxFn4dXHBWgbGvEvtOk-7t3m7OT7Yo`. Corpus identity
is the digest of the domain-separated index — versioned by digest, not
by name. The loader is pure over `%{path => binary}` and verifies
per-file hashes, exact file set (both directions), counts, id-uniqueness,
and applicability totality; the report refuses a vacuous green.

A repo-side second-language verifier (`conformance/verifier/`,
TypeScript on Node ≥ 24, `node:` builtins only, never in the Hex
archive) independently recomputes every corpus verdict and integrity
check with its own scanner, canonicalizer, and `node:crypto` Ed25519
path; the release gate requires its report to be byte-identical to the
Elixir escript's over both the repo corpus and the built archive's
corpus. A mutation gate breaks the implementation at seven named
points and requires the corpus to go red on each — a vacuous case set
is a build failure.

### Conforming implementations (normative)

An implementation conforms to this specification at a given release
when all three of the following hold. Partial conformance is not
conformance: an implementation that skips applicable corpus cells does
not conform at this release.

1. **Corpus pass.** It executes every case of the released conformance
   corpus — pinned by the digest above, every applicable cell of the
   applicability floor — and produces the expected verdict for each,
   refusing a vacuous pass.
2. **Report agreement.** Its case-report document over that corpus is
   byte-identical to the reference implementation's report; the report
   format is part of the wire contract, and the second-language
   verifier carries the discipline.
3. **Release identity.** Its release pins the corpus digest and the
   registry digest it certifies against, so specification, evidence,
   and implementation co-version; a release that cannot name its
   evidence is not a release of this protocol.

## 16. The shipped surface (informative — the reference implementation)

The facade (`AgentBlueprintProtocol`) delegates and never implements;
every public function carries a `@spec` (build-gated), every module a
boundary-stating moduledoc:

| Function | Contract |
|---|---|
| `decode_blueprint/1,2` | bounded, canonical-first Blueprint decode |
| `decode_deployment/1,2` | bounded, canonical-first Deployment decode |
| `decode_federation_envelope/1,2` | bounded TaskEnvelope decode |
| `canonical_bytes/1` | the artifact's canonical JCS bytes |
| `negotiate/2` | revision/required-field/extension evolution gate |
| `intersect/1` | bounds meet over blueprint/deployment/host sources |
| `verify_compatibility/2` | identity-exact build compatibility |
| `reconcile/3` | the one composed non-authorizing pass per import |
| `federation_mapping/0` | the 23-row A2A/MCP mapping as data |

Layered under it: the bytes layer (`Json`, `Canonicalization`,
`Base64Url`, `Digest`, `Bounds`), the artifacts (`Blueprint`,
`Deployment`, `Extension`, `Registry` as the one generic table-driven
engine, `Schema` as the bounded 2020-12 dialect + instance validator,
`Predicate`, `Portability`), the algebra (`BoundsAlgebra`,
`Negotiation`, `Compatibility`, `Signature`, `Federation`, `Error`,
`Evidence`, `Reconcile`, `ExtensionRegistry`), and the conformance
tooling (`Conformance.Corpus/Runner/Report/Cli` + the escript entry).
The module tree is strictly downward (bytes → algebra → artifacts →
conformance); the engine knows tables, never domains.

### Producer surface

Hosts that render artifacts produce them through the per-artifact
constructors, never through facade-level minting: compose the member
value, construct it with `Blueprint.from_value/2` or
`Deployment.from_value/2` (threading `:authored_extensions` for
critical namespaces whose bodies negotiation validated against a
digest-pinned schema), compute the release identity with the
artifact's `content_digest/1`, and serialize with its
`canonical_bytes/1`. The round-trip property (decode → `to_value/1` →
encode is a fixed point) is the byte-exactness guarantee a producer
relies on. The facade stays a verification facade: it delegates and
never implements, and no facade-level producer functions grow (the
accepted producer-surface decision record).

## 17. Security considerations (normative)

The threat model is not invented for this section: every threat below is
exercised by the conformance corpus as a named red class, and the gate
in the reference implementation reds a threat row that cites a class the
corpus does not carry.

| Threat | Vector | Corpus class | Mitigation |
|---|---|---|---|
| Artifact tamper | bytes edited after signing | `tamper_meaningful_byte` `digest_mismatch` | content digests over exact received bytes; `:digest_mismatch` denies (checked after structural validation, before signatures and binding) |
| Canonicality laundering | non-canonical spellings of the same value | `invalid_duplicate` | MUST-already-be-canonical interchange bytes; `:non_canonical_bytes` |
| Signature substitution | a signature lifted onto another artifact/purpose | `signature_invalid` | purpose-pinned signed attributes; digest covers revision + identity members |
| Protocol downgrade | an older/newer revision forced on a consumer | `revision_above_max` `revision_below_min` | explicit revision SETs, both directions deny `:protocol_revision_unsupported` |
| Extension rug-pull via registry | unknown/retired namespace forced critical | `extension_unknown_critical` | registry-state table; deny with typed codes |
| Schema-pin evasion | critical body validated against a different schema | `extension_schema_unavailable` | digest-pinned schemas; `:extension_schema_digest_mismatch` |
| Tool rug-pull | a bound tool's descriptor replaced out-of-band | `binding_stale` `compatibility_range_rejected` | binding verification: descriptor-digest equality + attestation freshness + identity-exact entries |
| Ceiling widening | a bound or ceiling raised after the fact | `bound_widening_operational` `bound_widening_protected` | bounds may narrow only; protected narrowing denies by default; effective bounds never widen host policy |
| Quarantined-content laundering | unscanned payload smuggled into a claim | `extension_unknown_optional_roundtrip` `forbidden_portable_value` | quarantine is typed unscanned; portability claims attach only to schema-validated content |
| Receipt equivocation | two diverging terminal receipts for one task | `terminal_equivocation` `federation_terminal_conflict` | Terminal Commitment over seven components; ANY divergence denies |
| Misaddressed execution | a receipt verified by the wrong receiver | `audience_mismatch` | issuer/subject/audience checked against the receiving context |
| Required-field laundering | an evidence-only member promoted to a requirement | `required_field_not_covered` | required core fields MUST be digest-covered |

The non-authorizing boundary is itself a security property: every
verification result is evidence, the `not_verified` set is non-empty by
construction naming the host-owned surfaces, and no code path grants
authority. Small-order Ed25519 keys reject; the package performs no key
discovery or trust selection — a wrong key is a typed denial, never a
silent pass.

## 18. Privacy considerations (normative)

The portability guard is the protocol's data-minimization profile,
stated as a normative constraint set: portable artifacts MUST NOT carry
secrets, private keys, live grants, tenant identifiers, raw endpoints,
database primary keys, or backend engine identifiers — enforced
structurally at any depth (member-name and value-shape denylists,
name-spelling-normalized) and exercised per class by the corpus
(`forbidden_portable_value`). The honest limits are part of the
contract: identifier-shaped values with the UUID grammar are exempt
by shape, so the guard is structural, not semantic — a tenant
identifier encoded as a UUID is not caught by the value-shape arm; quarantined extension bodies are typed as unscanned
(`extension_unknown_optional_roundtrip` carries the round-trip
obligation), and portability claims attach only to schema-validated
content — a producer MUST NOT present a portability pass as a privacy
guarantee. Federation identity members (`issuer`, `subject`,
`audience`, `identity_mapping_evidence`) are correlation material only:
an authority-shaped claim in the evidence block denies
`:nonportable_content`, and possession of a key is never an identity
claim.

## 19. Positioning — protocol neighbors (informative)

The Agent Blueprint Protocol does not compete with the transport and
discovery protocols; it completes them. AI Catalog owns discovery,
verifiable identity, and attestation; A2A owns agent-to-agent tasks;
MCP owns tools and data. ABP owns the portable CONTRACT layer — the
artifact that says what an agent is, what it may do (bounds, ceilings),
what it must prove (evidence), and how a host verifies all of it
fail-closed without granting authority. A blueprint rides IN A2A task
metadata and MCP `_meta` (the federation profile proves the carriage);
a Trust-Manifest-style discovery record can reference a blueprint by
digest without either protocol subsuming the other. Where a neighbor
mandates a signature envelope, ABP already speaks it: detached JWS over
JCS canonical bytes is the shared primitive.