@agent-blueprint-protocol/verifier 0.8.4 → 1.0.0-rc.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (107) hide show
  1. package/CHANGELOG.md +139 -0
  2. package/LICENSE +1 -1
  3. package/NOTICE +2 -2
  4. package/README.md +143 -255
  5. package/dist/corpus/cases/blueprint-decode.json +1 -1
  6. package/dist/corpus/cases/bounds-new.json +1 -1
  7. package/dist/corpus/cases/bounds_algebra-intersect.json +1 -1
  8. package/dist/corpus/cases/canonicalization-encode.json +1 -1
  9. package/dist/corpus/cases/deployment-decode.json +1 -1
  10. package/dist/corpus/cases/extension-resolve.json +1 -1
  11. package/dist/corpus/cases/federation-decode.json +1 -1
  12. package/dist/corpus/cases/federation-verify_commitment.json +1 -1
  13. package/dist/corpus/cases/json-decode.json +1 -1
  14. package/dist/corpus/cases/negotiation-negotiate.json +1 -1
  15. package/dist/corpus/cases/predicate.json +1 -0
  16. package/dist/corpus/cases/reconcile.json +1 -0
  17. package/dist/corpus/cases/schema-validate_instance.json +1 -1
  18. package/dist/corpus/cases/signature-verify.json +1 -1
  19. package/dist/corpus/index.json +1 -1
  20. package/dist/release-history.json +1 -0
  21. package/dist/release-metadata.json +1 -1
  22. package/dist/spec/FOUNDATION-TRANSITION.md +67 -0
  23. package/dist/spec/IPR.md +27 -0
  24. package/dist/spec/LICENSE +190 -0
  25. package/dist/spec/NOTICE +4 -0
  26. package/dist/spec/README.md +47 -0
  27. package/dist/spec/conformance/base64url-decode.schema.json +176 -0
  28. package/dist/spec/conformance/blueprint-decode.schema.json +280 -0
  29. package/dist/spec/conformance/bounds-new.schema.json +302 -0
  30. package/dist/spec/conformance/bounds_algebra-intersect.schema.json +457 -0
  31. package/dist/spec/conformance/canonicalization-encode.schema.json +280 -0
  32. package/dist/spec/conformance/case-file.schema.json +122 -0
  33. package/dist/spec/conformance/certified-results.json +1 -0
  34. package/dist/spec/conformance/claim.schema.json +52 -0
  35. package/dist/spec/conformance/compatibility-verify.schema.json +262 -0
  36. package/dist/spec/conformance/deployment-decode.schema.json +322 -0
  37. package/dist/spec/conformance/digest-tagged.schema.json +200 -0
  38. package/dist/spec/conformance/evidence.schema.json +249 -0
  39. package/dist/spec/conformance/execution.md +80 -0
  40. package/dist/spec/conformance/extension-resolve.schema.json +264 -0
  41. package/dist/spec/conformance/federation-decode.schema.json +318 -0
  42. package/dist/spec/conformance/federation-verify_commitment.schema.json +342 -0
  43. package/dist/spec/conformance/index.schema.json +102 -0
  44. package/dist/spec/conformance/json-decode.schema.json +287 -0
  45. package/dist/spec/conformance/negotiation-negotiate.schema.json +264 -0
  46. package/dist/spec/conformance/portability-scan.schema.json +188 -0
  47. package/dist/spec/conformance/predicate.schema.json +201 -0
  48. package/dist/spec/conformance/reconcile.schema.json +287 -0
  49. package/dist/spec/conformance/runner.md +185 -0
  50. package/dist/spec/conformance/schema-validate_instance.schema.json +206 -0
  51. package/dist/spec/conformance/signature-verify.schema.json +224 -0
  52. package/dist/spec/conformance/support.schema.json +72 -0
  53. package/dist/spec/errata.md +13 -0
  54. package/dist/spec/grammar/blueprint.cddl +92 -0
  55. package/dist/spec/grammar/deployment.cddl +125 -0
  56. package/dist/spec/grammar/derived/blueprint.schema.json +340 -0
  57. package/dist/spec/grammar/derived/deployment.schema.json +496 -0
  58. package/dist/spec/grammar/derived/taskenvelope.schema.json +244 -0
  59. package/dist/spec/grammar/taskenvelope.cddl +77 -0
  60. package/dist/spec/protocol.md +1237 -0
  61. package/dist/spec/registry/OPERATIONS.md +78 -0
  62. package/dist/spec/registry/registry.json +23 -0
  63. package/dist/verifier/b64url.js +1 -1
  64. package/dist/verifier/blueprint.d.ts +2 -15
  65. package/dist/verifier/blueprint.js +21 -107
  66. package/dist/verifier/bounds_algebra.d.ts +9 -0
  67. package/dist/verifier/bounds_algebra.js +6 -6
  68. package/dist/verifier/cli.js +14 -31
  69. package/dist/verifier/corpus.d.ts +1 -1
  70. package/dist/verifier/corpus.js +5 -1
  71. package/dist/verifier/decode.js +15 -3
  72. package/dist/verifier/deployment.d.ts +8 -0
  73. package/dist/verifier/deployment.js +17 -2
  74. package/dist/verifier/digest.js +1 -1
  75. package/dist/verifier/errors.d.ts +2 -0
  76. package/dist/verifier/errors.js +1 -0
  77. package/dist/verifier/execution.d.ts +13 -0
  78. package/dist/verifier/execution.js +82 -0
  79. package/dist/verifier/facade.d.ts +311 -0
  80. package/dist/verifier/facade.js +78 -0
  81. package/dist/verifier/federation.d.ts +2 -2
  82. package/dist/verifier/federation.js +10 -7
  83. package/dist/verifier/harness.d.ts +16 -0
  84. package/dist/verifier/harness.js +201 -0
  85. package/dist/verifier/index.d.ts +3 -0
  86. package/dist/verifier/index.js +2 -0
  87. package/dist/verifier/mapping.d.ts +139 -0
  88. package/dist/verifier/mapping.js +1 -0
  89. package/dist/verifier/negotiation.d.ts +2 -1
  90. package/dist/verifier/negotiation.js +6 -3
  91. package/dist/verifier/plain.d.ts +4 -0
  92. package/dist/verifier/plain.js +38 -0
  93. package/dist/verifier/predicate.d.ts +7 -0
  94. package/dist/verifier/predicate.js +60 -1
  95. package/dist/verifier/reconcile.d.ts +37 -0
  96. package/dist/verifier/reconcile.js +115 -0
  97. package/dist/verifier/registry.js +9 -51
  98. package/dist/verifier/registry_engine.d.ts +3 -0
  99. package/dist/verifier/registry_engine.js +8 -8
  100. package/dist/verifier/results.d.ts +3 -0
  101. package/dist/verifier/results.js +13 -0
  102. package/dist/verifier/runner.d.ts +2 -0
  103. package/dist/verifier/runner.js +115 -16
  104. package/dist/verifier/signature.d.ts +17 -6
  105. package/dist/verifier/signature.js +41 -25
  106. package/package.json +17 -12
  107. package/dist/corpus/schemas/estate-contract.schema.json +0 -1
package/CHANGELOG.md CHANGED
@@ -2,6 +2,145 @@
2
2
 
3
3
  All notable public changes to `agent_blueprint_protocol` are documented here.
4
4
 
5
+ ## [1.0.0-rc.2] — 2026-11-11
6
+
7
+ Documentation corrections cover the README, npm package README, guides, Livebooks, and site. The npm package description states the verifier's checks.
8
+ The unused TypeScript `Context` type is no longer exported; no exported function
9
+ accepted it. Release tooling works for any candidate or final version.
10
+
11
+ The shipped registry contains only the protocol's federation registrations:
12
+ `io.github.baselabs/federation` (active) and `com.example/federation`
13
+ (deprecated), both critical and schema-pinned. Hosts that negotiated the five
14
+ earlier product example namespaces supply their own entries through the host
15
+ support registry and provide the schema documents they hold. Compiled entries
16
+ retain their criticality and schema pins under host overrides. The product
17
+ schema and product-specific projection fixture are removed.
18
+
19
+ The registry digest changes and verification-semantics version is now 3;
20
+ protocol revision remains 1. All six prior censuses, covering 0.3.0 through
21
+ 0.8.4 and 1.0.0-rc.1, are declared `diverged_by_registry_census`. In each,
22
+ `negotiation-estate-contract-valid` now denies `extension_unknown_critical`;
23
+ the digest-mismatch, schema-absent, and tier-bound cases deny the same code;
24
+ the criticality-conflict case becomes valid with the optional body quarantined;
25
+ and `extension-resolve-estate-deprecated-retained` changes from a deprecated
26
+ notice to unknown-optional quarantine. For 1.0.0-rc.1, the two
27
+ `*-deprecated-optional-notice` cases also report unknown-optional quarantine,
28
+ and `reconcile-deprecated-optional` changes its extension evidence from
29
+ retained to quarantined and removes it from the retained list. All other
30
+ prior-census projections remain equivalent. Compatibility replay checks these
31
+ changes against the registry difference, including composed imports.
32
+
33
+ Generic host registrations replace the earlier examples in the current corpus.
34
+ The corpus contains 626 cases, including 22 new host lifecycle and schema-pin
35
+ cases. Its digest is `sha-256:0B_9tnAAo05n3bWVvnIPDxFeqEr2XhJoDdaxNJv0_9A`;
36
+ the registry digest is `sha-256:hreDA2_XbV5J9geMJDDYG5BB42AGkh9jmQ9bqHe8kRk`.
37
+
38
+ The obsolete `verifier/RUNNER.md` redirect is removed from the repository and
39
+ the standalone archive. The runner contract is `spec/conformance/runner.md`.
40
+
41
+ ## [1.0.0-rc.1] — 2026-11-11
42
+
43
+ ### Breaking
44
+
45
+ - TypeScript imports use the package root. Previous `dist/verifier/blueprint.js`
46
+ `decode` becomes `decodeBlueprint`; Deployment and federation `decode` become
47
+ `decodeDeployment` and `decodeFederationEnvelope`. Internal `negotiate`,
48
+ `intersect`, signature and compatibility `verify`, corpus `load`, runner
49
+ `run`, and report builders map to root `negotiate`, `intersect`,
50
+ `verifySignature`, `verifyCompatibility`, `loadCorpus`, `runCorpus`,
51
+ `buildReport`, and `buildResultsDocument`. Deep paths no longer resolve;
52
+ public results use `value` and typed `error` members. The TypeScript guide
53
+ lists the complete migration, including artifact `canonicalBytes`.
54
+
55
+ - All fallible public Elixir operations return `{:error, %Error{}}`.
56
+ Decoder ceilings carry `{:ceiling, key}` in `Error.code`; value-returning
57
+ helpers retain their success form and declare the failure branch.
58
+ Denial details are `nil`, including protected-clamp denials; acknowledged
59
+ clamp results retain their typed evidence.
60
+ - Evidence marks unsigned artifacts and skipped observations unverified.
61
+ Typed signature details identify distinct verifying keys; binding details
62
+ list checks performed and skipped. Unverified surfaces are explicit.
63
+ - `Signature.verify/2` returns verified signed attributes in both languages.
64
+ Repeated signer key identifiers deny `invalid_constraint` during structure validation.
65
+ - Implementation modules and helper functions are hidden from the public API.
66
+ - The registry digest changes for the controlled federation registration.
67
+ Verification-semantics version is 2; protocol revision remains 1.
68
+
69
+ ### Changed
70
+
71
+ - The 1.x evolution contract preserves existing revisions and error codes,
72
+ keeps runtime and compiler floors, and defines additive paths for new
73
+ revisions, profiles, execution versions, and evidence identifiers.
74
+ - Detached signatures accept dotted key identifiers under RFC 7797 §5.1.
75
+ Monetary amounts consistently count millionths of a currency unit.
76
+ - Federation carriage describes native reconstruction; discovery signature
77
+ envelopes remain distinct. The EU AI Act guide states the enacted dates.
78
+ - TypeScript output identifiers are open with known-value constants;
79
+ packed declarations support TypeScript 5.0.2 and newer. Node 26 joins
80
+ the platform matrix while Node 24 remains the runtime floor.
81
+ - GitHub release publication waits for a live Hex version whose checksum
82
+ matches the verified archive, including after staged approval.
83
+
84
+ - The specification separates protocol requirements from implementation notes
85
+ and states the byte, grammar, lattice, predicate and schema profiles with
86
+ pinned normative references.
87
+
88
+ - Byte-error precedence and malformed conformance inputs agree across the
89
+ implementations. Binding evidence requires every descriptor observation
90
+ and a complete age check before reporting those checks verified.
91
+ - Dotted key identifiers are accepted in detached signatures.
92
+ - Revision 1 accepts `EdDSA` and `Ed25519` protected-header identifiers;
93
+ producers SHOULD emit `Ed25519`. Existing signed bytes remain valid.
94
+ - `io.github.baselabs/federation` is active with the existing schema pin.
95
+ `com.example/federation` is deprecated and remains supported throughout
96
+ 1.x. Both carrier spellings verify; ambiguous double carriage denies.
97
+ - Registration checks MCP metadata key syntax. Artifact namespace decoding
98
+ remains unchanged. Prerelease versions retain their complete identity
99
+ across Hex, npm, release metadata, comparisons, and install instructions.
100
+
101
+ ### Added
102
+
103
+ - A conformance product: bounded case schemas, a normative runner contract,
104
+ reconcile and predicate cases, canonical certified results, an external
105
+ execution harness and adapters, and unsigned implementation claims.
106
+ - A package-root TypeScript library with typed import evidence, exhaustive
107
+ errors, isolated consumer declarations, and its own package README.
108
+ - A stability and deprecation policy for both packages and three-platform
109
+ contributor and published-package lanes on Linux, macOS, and Windows.
110
+ - Candidate promotion checks preserve certified bytes; further publication
111
+ waits for the staged npm version to be live and byte-verified.
112
+
113
+ - Mixed-order Ed25519 vectors distinguish the required cofactorless equation
114
+ from cofactored verification, without rejecting mixed-order points.
115
+ - Deterministic test-only signing for new fixtures, preserving every existing
116
+ fixture signature. Corpus cases pin algorithm spellings, duplicate signers,
117
+ both federation namespaces, and effect impact as an obligation.
118
+ - A public module and function declaration prevents silent API expansion.
119
+ Error descriptions distinguish overlapping conditions; evidence explicitly
120
+ names timestamp and lifecycle facts it does not establish.
121
+
122
+ ### Documentation
123
+
124
+ - Added `architecture.md`, `positioning.md`, `compose-and-sign.md`,
125
+ `handling-errors.md`, `reading-evidence.md`, `verifying-in-ci.md`,
126
+ `verifying-releases.md`, `security-model.md`, and `extensions.md`.
127
+ - Added `cheatsheet.cheatmd`; rewrote `examples.md` and expanded `errors.md` and `faq.md`.
128
+ - Reworked the Blueprint, Deployment, portability, federation, and
129
+ evidence-commitment concept guides.
130
+ - Reworked `producer.md` and `host-integration.md` to link the new how-to guides.
131
+ - Merged extension authoring and registry reference material into `extensions.md`.
132
+ - Updated the Federation carrier mapping reference.
133
+ - Added five standalone Livebook walkthroughs for the tour, producing artifacts, host import,
134
+ extensions and federation, and conformance and attacks. Each notebook runs with persisted
135
+ outputs and is included in the Hex package.
136
+
137
+ The corpus contains 604 cases, digest
138
+ `sha-256:oYnkSmTkHGk4AmZ8Sul99_6KYJUIuj2SN2GZAiT1glw`; registry
139
+ `sha-256:d98vF3duE_8P7N5aGLrmaqcj3uSDf0NsI4dzF7bXBDg`.
140
+ Prior released verdicts remain equivalent. The
141
+ `negotiation-estate-contract-valid` case now projects the
142
+ `extension_deprecated` notice for the legacy federation namespace.
143
+
5
144
  ## [0.8.4] — 2026-11-10
6
145
 
7
146
  ### Fixed
package/LICENSE CHANGED
@@ -175,7 +175,7 @@
175
175
 
176
176
  END OF TERMS AND CONDITIONS
177
177
 
178
- Copyright 2026 BaseLabs
178
+ Copyright 2026 BaseLabs Holdings
179
179
 
180
180
  Licensed under the Apache License, Version 2.0 (the "License");
181
181
  you may not use this file except in compliance with the License.
package/NOTICE CHANGED
@@ -1,4 +1,4 @@
1
1
  agent_blueprint_protocol
2
- Copyright 2026 BaseLabs
2
+ Copyright 2026 BaseLabs Holdings
3
3
 
4
- This product includes software developed by BaseLabs.
4
+ This product includes software developed by BaseLabs Holdings.
package/README.md CHANGED
@@ -1,269 +1,157 @@
1
- # Agent Blueprint Protocol
1
+ # Agent Blueprint Protocol for TypeScript
2
2
 
3
- [![CI](https://github.com/baselabs/agent_blueprint_protocol/actions/workflows/ci.yml/badge.svg)](https://github.com/baselabs/agent_blueprint_protocol/actions/workflows/ci.yml)
4
- [![Hex Version](https://img.shields.io/hexpm/v/agent_blueprint_protocol.svg)](https://hex.pm/packages/agent_blueprint_protocol)
5
- [![License](https://img.shields.io/hexpm/l/agent_blueprint_protocol.svg)](https://hex.pm/packages/agent_blueprint_protocol)
3
+ A typed, non-authorizing verifier library and conformance CLI. Node 24 or
4
+ newer; zero runtime dependencies. For Elixir, see
5
+ [agent_blueprint_protocol](https://hex.pm/packages/agent_blueprint_protocol).
6
+ The specification is [published with the project](https://github.com/baselabs/agent_blueprint_protocol/blob/main/spec/protocol.md).
6
7
 
7
- Agent Blueprint Protocol is a portable, non-authorizing contract for describing
8
- an agent capability and binding one immutable release to an execution
9
- environment.
10
-
11
- The public package is the reference implementation for three
12
- language-neutral artifacts:
13
-
14
- - **Blueprint Core** — stable identity, typed ports, logical capability
15
- requirements, bounds, evidence commitments, and registered extensions.
16
- - **Deployment Manifest** — environment-local tool, principal, data,
17
- authority, effect, evaluation, and exact-build bindings for one Blueprint
18
- release digest.
19
- - **Federation TaskEnvelope** — the cross-protocol task record: 23 members
20
- carrying task identity, terminal state, and signed terminal commitments
21
- over A2A and MCP transports, with receipt-equivocation denial. The
22
- blueprint rides IN those transports; the envelope is how a task's
23
- verifiable record travels between them.
24
-
25
- Protocol validity never grants authority. A consuming host remains responsible
26
- for identity, tenancy, policy, live authorization, effect ownership, execution,
27
- and evidence retention.
28
-
29
- ## Installation
30
-
31
- ```elixir
32
- def deps do
33
- [
34
- {:agent_blueprint_protocol, "~> 0.8.4"}
35
- ]
36
- end
8
+ ```sh
9
+ npm install @agent-blueprint-protocol/verifier
10
+ npx @agent-blueprint-protocol/verifier --help
37
11
  ```
38
12
 
39
- The package has **zero production dependencies**, no application callback, and
40
- no supervision tree. It requires Elixir 1.19 or newer on OTP 27, 28, or 29.
41
-
42
- ## A first verification
43
-
44
- From a checkout of this repository (or with the example file fetched as
45
- the [quickstart](documentation/quickstart.md) shows), decode the example
46
- Blueprint, then watch a value that is not a Blueprint get a typed denial:
47
-
48
- ```elixir
49
- bytes = File.read!("examples/echo-blueprint.json")
50
- {:ok, blueprint} = AgentBlueprintProtocol.decode_blueprint(bytes)
51
- AgentBlueprintProtocol.canonical_bytes(blueprint) == {:ok, bytes} # => true
52
- {:ok, other} = AgentBlueprintProtocol.Canonicalization.encode({:object, [{"a", {:integer, 1}}]})
53
- AgentBlueprintProtocol.decode_blueprint(other) # => {:error, :unknown_member}
13
+ Install the published package and run its CLI with `npx @agent-blueprint-protocol/verifier`. `npm view @agent-blueprint-protocol/verifier version` identifies the published package version.
14
+
15
+ ## CLI
16
+
17
+ | Mode | Behavior |
18
+ |---|---|
19
+ | no arguments | run the embedded certified corpus |
20
+ | `--corpus <dir>` | run an integrity-checked corpus, emit the aggregate report |
21
+ | `--prior-corpus <dir>` | verify an earlier released corpus under this release's semantics |
22
+ | `--results --corpus <dir>` | emit canonical per-case results |
23
+ | `--serve --corpus <dir>` | speak the external execution protocol |
24
+ | `--artifact <file>` | decode a Blueprint, Deployment, or federation envelope |
25
+ | `--help`, `--version` | usage or package version |
26
+ | `conformance run --corpus <dir> --results <file> -- <command...>` | drive and judge another implementation |
27
+
28
+ Runner exit codes: 0 for agreement, a valid artifact, help, or version; 1 for disagreement or an invalid artifact; 2 for a usage, read, or corpus-integrity failure; 3 for an internal error. On a corpus run, standard error states whether the digest matches the release-certified corpus. Corpus readers reject symbolic links and non-regular files, and cap a corpus at 1,000 files and 5,000,000 bytes. Reports and results on standard output are JSON Canonicalization Scheme (JCS, RFC 8785) bytes without a trailing newline. Harness exit codes 10 to 19 mean, in order: handshake mismatch, duplicate, missing, extra, or reordered response, malformed line, oversized line, timeout, early exit, and disagreement. The execution contract in the specification defines each.
29
+
30
+ ## Library
31
+
32
+ The shipped extension registry contains only the protocol's active and
33
+ deprecated federation registrations. Supply other namespaces through
34
+ `Support.registry`, including criticality, lifecycle state, and `schemaDigest`;
35
+ put held schema documents in `Support.schemas`. A host cannot change the
36
+ criticality or schema pin of a compiled entry. See the
37
+ [host registration examples](https://github.com/baselabs/agent_blueprint_protocol/blob/main/documentation/extensions.md#register-a-namespace-with-the-host).
38
+
39
+ The package is ESM-only; `require()` is not supported.
40
+ Only the package root and `package.json` are exported. Import has no command
41
+ or filesystem side effects. Every function returns `Result<T>`:
42
+ `{ok:true,value}` or `{ok:false,error:{code,subject}}`. Public types use
43
+ `Uint8Array` and strings; consumers need no Node global declarations.
44
+ `ErrorCode` is exhaustive, including `ceiling:<key>` denials.
45
+
46
+ Save [`examples/echo-blueprint.json`](https://github.com/baselabs/agent_blueprint_protocol/blob/main/examples/echo-blueprint.json) beside the script; the npm package does not include it.
47
+
48
+ ```js
49
+ // verify.mjs — run beside echo-blueprint.json
50
+ import { readFileSync } from "node:fs";
51
+ import { decodeBlueprint } from "@agent-blueprint-protocol/verifier";
52
+ const result = decodeBlueprint(readFileSync("echo-blueprint.json"));
53
+ console.log(result.ok ? "valid" : result.error.code); // valid
54
54
  ```
55
55
 
56
- The quickstart runs this from a new Mix project, and the
57
- [Livebook walkthrough](docs/livebooks/abp-walkthrough.livemd)
58
- goes end to end: compose, sign, negotiate, reconcile, and the attacks that
59
- fail closed.
60
-
61
- ## Installation (TypeScript)
62
-
63
- The verifier ships as an installable npm kit,
64
- `@agent-blueprint-protocol/verifier`: the compiled verifier, its
65
- declarations, and the conformance corpus embedded byte-identically to
66
- the release-certified copy. Zero runtime dependencies; Node 24+.
67
-
68
- ```bash
69
- npx @agent-blueprint-protocol/verifier # verify the embedded corpus
70
- npx @agent-blueprint-protocol/verifier --artifact <file.json> # verify one artifact
56
+ The following examples assume canonical artifact bytes `blueprintBytes`, `deploymentBytes`, and `envelopeBytes`; caller-supplied `keys`, `observed`, `signatureEntry`, `requestedBounds`, `deploymentBounds`, and `hostBounds`; and `files`, a `Map` from corpus-relative path to file bytes. They return evidence, never permission. Check `ok` before reading `value`.
57
+
58
+ ```ts
59
+ import {
60
+ decodeBlueprint, decodeDeployment, decodeFederationEnvelope, canonicalBytes,
61
+ negotiate, intersect, verifyCompatibility, reconcile, federationMapping,
62
+ verifySignature, loadCorpus, runCorpus, buildReport, buildResultsDocument
63
+ } from "@agent-blueprint-protocol/verifier";
64
+
65
+ const bp = decodeBlueprint(blueprintBytes, {bounds: {depth: 32}});
66
+ const dep = decodeDeployment(deploymentBytes);
67
+ const envelope = decodeFederationEnvelope(envelopeBytes);
68
+ if (bp.ok) canonicalBytes(bp.value);
69
+
70
+ const support = {revisions: new Set([1]), coreFields: new Set<string>(),
71
+ registry: {}, schemas: {}};
72
+ if (bp.ok) negotiate(bp.value, support);
73
+
74
+ // Each source supplies all thirteen bounds; classification uses
75
+ // {ordinal: "internal", markers: []}, cost uses {amount, currency}.
76
+ intersect({blueprint: requestedBounds, deployment: deploymentBounds,
77
+ host: hostBounds, protectedClamp: "acknowledge"});
78
+ if (dep.ok) verifyCompatibility(dep.value, observed);
79
+ if (bp.ok && dep.ok) reconcile(bp.value, dep.value, {
80
+ hostBounds, support, keys, protectedClamp: "deny",
81
+ observations: {now: null, maxAttestationAgeMs: null, observed: {}}
82
+ });
83
+ federationMapping();
84
+ verifySignature(signatureEntry, keys);
85
+
86
+ const corpus = loadCorpus(files);
87
+ if (corpus.ok) {
88
+ const run = runCorpus(corpus.value);
89
+ if (run.ok) buildReport(corpus.value, run.value);
90
+ buildResultsDocument(corpus.value);
91
+ }
71
92
  ```
72
93
 
73
- npx runs the latest published kit; `npm view @agent-blueprint-protocol/verifier version` shows which.
74
-
75
- See the [TypeScript quickstart](documentation/typescript.md) and the
76
- [examples gallery](documentation/examples.md).
77
-
78
- ## When to use — and when NOT
79
-
80
- **Use this protocol when** you need a portable, verifiable contract for
81
- what an agent is and what it may do: bounds that can only narrow,
82
- evidence commitments that survive independent verification, and a
83
- conformance corpus that proves the whole surface. It complements the
84
- transport and discovery protocols — a blueprint rides IN A2A task
85
- metadata and MCP `_meta`.
86
-
87
- **Do NOT use it if you need an agent to HAVE authority.** This grants
88
- none: identity, tenancy, live policy, effect ownership, execution,
89
- billing, and evaluation truth stay with the host, always. If your
90
- problem is granting permissions, this is the wrong layer — you need a
91
- policy engine, and a blueprint can carry its requirements to one.
92
-
93
- ## What it provides
94
-
95
- Decoding and validation (every result is a typed fact or a typed denial —
96
- never an authorization decision):
97
-
98
- - `decode_blueprint/2` — bounded, fail-closed decode of a Blueprint: canonical
99
- byte verification, registry validation, portability scan, digest comparison.
100
- - `decode_deployment/2` — the same pipeline for a Deployment Manifest bound to
101
- one Blueprint release digest.
102
- - `decode_federation_envelope/2` — the 23-member federation task envelope
103
- through the shared registry engine; `federation_mapping/0` returns the
104
- A2A/MCP Tasks field mapping as data.
105
- - `canonical_bytes/1` — the exact canonical (JCS) wire bytes of a decoded
106
- artifact.
107
-
108
- Semantics:
109
-
110
- - `negotiate/2` — the evolution gate: revision sets, required core fields,
111
- and the positional extension state machine (unknown critical denies,
112
- unknown optional quarantines byte-exactly).
113
- - `intersect/1` — the bounds algebra: the pointwise narrowest intersection of
114
- Blueprint bounds, Deployment `host_bounds`, and host policy; protected
115
- narrowings deny or clamp-with-evidence, never silently.
116
- - `verify_compatibility/2` — identity-exact matching of manifest build
117
- identities against host-observed identities.
118
- - `reconcile/3` — the one call per import: the pinned eight-stage pass
119
- (canonical, digest, negotiation, structure, portability, signatures, bind,
120
- bounds), reject-or-annotate, never repair, under host-supplied inputs.
121
-
122
- Tooling: `mix conformance.verify` executes the shipped 199-case corpus;
123
- `mix conformance.mutations` re-proves the corpus catches named implementation
124
- breaks; `mix verifier.agreement` byte-agrees the Elixir runner with the
125
- independent TypeScript verifier; `mix compatibility.replay` certifies the
126
- release's compatibility claims — every prior release's census replays under
127
- the current verifier in both languages, and the release history verifies
128
- against its tags' actual trees.
129
-
130
- ## Status
94
+ Decoded views expose read-only JSON `value`, `canonicalBytes`, and
95
+ `contentDigest` (null for a federation envelope, whose commitment is a
96
+ separate identity). `Support`, `Inputs`, `Observations`, `Observed`, `PublicKey`, `BoundSet`, and decoder `Bounds` describe the
97
+ caller-supplied facts. `Evidence` includes typed checks, effective bounds,
98
+ clamps, and a nonempty `not_verified` list. Unsigned artifacts succeed with
99
+ signature verification explicitly unestablished; absent descriptor and
100
+ freshness observations remain unverified.
131
101
 
132
- The protocol API, schemas, canonicalization profile, extension registry,
133
- and conformance corpus are implemented and gated: 985 tests
134
- (64 properties) at 100% coverage, zero Dialyzer errors, `--strict`
135
- Credo clean, a 199-case conformance corpus with a mutation gate, and a
136
- byte-agreement gate against an independent second-language verifier.
137
- The normative specification, [`spec/protocol.md`](spec/protocol.md),
138
- ships in the Hex archive. The full gate battery and every gate's
139
- recorded red proof are public in this repository under
140
- [`docs/design/requirement-map.md`](https://github.com/baselabs/agent_blueprint_protocol/blob/main/docs/design/requirement-map.md).
102
+ ## External implementations and claims
141
103
 
142
- Since 0.8.0 the release identity is a versioned public contract: the
143
- manifest (`manifest_version`, additive-only) splits verification
144
- semantics from census, certifies the compatibility matrix per prior
145
- census, and the append-only release history maps every release — so
146
- exact-pinned consumers upgrade pins without breaking historical
147
- replays ([upgrading guide](documentation/upgrading.md)).
148
-
149
- The 0.x series is the public pre-1.0 line: shipped contracts may
150
- change within 0.x under pre-1.0 conventions, and every contract change
151
- lands with a red-capable test.
152
-
153
- ## Intended properties
154
-
155
- - Language-neutral canonical artifacts with bounded parsing.
156
- - Fail-closed protocol revision and required-field handling.
157
- - Bounds that can narrow host policy but can never widen it.
158
- - Critical extensions that deny when unsupported; optional extensions that
159
- round-trip without execution.
160
- - Exact compatibility manifests and red-capable tamper/downgrade corpora.
161
- - Zero third-party/Hex production dependencies and no supervision tree.
162
- - No product-specific tenant, key, grant, endpoint, database, provider, or
163
- engine identifiers in portable artifacts.
164
-
165
- ## Development
166
-
167
- The toolchain enforces itself: the declared Elixir range in `mix.exs`
168
- (`~> 1.19` — Mix refuses anything outside it at compile) and the
169
- supported-OTP set in `config/config.exs` (27/28/29 — the build refuses
170
- any other OTP major before anything compiles; see the
171
- [supported-OTP-set decision record](docs/adr/supported-otp-set.md)). CI
172
- exercises every lane of that matrix: Elixir 1.19 on OTP 28, and Elixir
173
- 1.20 on OTP 27, 28, and 29 (the dev pin, mirrored in `.tool-versions`);
174
- the full battery runs on the dev lane and tests plus the conformance
175
- corpus on every lane. The four declarations — Elixir range, supported-OTP
176
- set, dev pin, and CI lanes — move together in one commit.
177
-
178
- ```bash
179
- mix deps.get
180
- mix quality
104
+ ```sh
105
+ agent-blueprint-protocol conformance run --corpus ./conformance --results results.json -- ./example-adapter
181
106
  ```
182
107
 
183
- `mix quality` runs dependency audits (retirement, the unused-lock-entry
184
- check `deps.unlock --check-unused`, advisories, and dependency
185
- currency), formatting, warnings-as-errors compilation, Credo,
186
- tests with the 100% coverage threshold, the conformance corpus and its
187
- mutation gate, the npm kit build, the TypeScript guide's import example,
188
- the second-language verifier agreement gate, the compatibility replay, Dialyzer, documentation with
189
- warnings-as-errors, the specification-extraction, grammar-derivation,
190
- registry-equality, and release-asset gates, and the release-candidate
191
- check (requirement-map completeness, specification coupling, and the
192
- release identity chain). Every gate carries a recorded red proof — see the requirement map at
193
- `docs/design/requirement-map.md` in this repository.
194
-
195
- ### Conformance corpus
196
-
197
- The package ships a portable conformance corpus (`priv/conformance/`) — 199
198
- cases covering every required cell of the 16-surface × 31-class applicability
199
- floor, full-registry golden artifacts, RFC 8785 number vectors, and
200
- deterministic Ed25519 fixtures. Run it:
201
-
202
- ```bash
203
- mix conformance.verify # loads, integrity-verifies, and executes the corpus
204
- mix conformance.mutations # breaks the implementation at named points; the corpus must go red
108
+ After a pass, add `--claim claim.json --implementation example-verifier
109
+ --implementation-version 1 --source https://example.com/source
110
+ --platform example-platform --date 2026-11-10` before `--`. A claim is unsigned
111
+ and identifies the implementation, corpus, registry and results bytes. A
112
+ non-certified corpus requires `--prior-corpus-digest <exact-digest>` to name
113
+ the prior released corpus explicitly. Publish the claim and exact results
114
+ document beside source and the reproducible command. A public corpus pass
115
+ proves neither honest computation nor behavior outside the corpus nor any
116
+ host behavior. The package includes the runner and execution contracts under
117
+ `dist/spec/`.
118
+
119
+ ## Migrating from 0.8
120
+
121
+ Deep imports from `dist/verifier/` no longer resolve; import from the package root. The [TypeScript guide](https://github.com/baselabs/agent_blueprint_protocol/blob/main/documentation/typescript.md#import-migration) maps each previous import to its replacement.
122
+
123
+ ## Compatibility within 1.x
124
+
125
+ Node 24 remains the runtime floor for all of 1.x; Node 26 is also supported.
126
+ TypeScript 5.0.2 is the compiler floor. Packed declarations are checked at
127
+ that floor and at the TypeScript version used in CI with `moduleResolution: "nodenext"`,
128
+ `skipLibCheck: false`, and no `@types/node` dependency.
129
+
130
+ `ErrorCode` stays a closed union throughout 1.x, so exhaustive switches are
131
+ safe. Output identifiers are open string types: `Notice`, `EvidenceSurface`,
132
+ `EvidenceCheckKind`, `SignatureAlgorithm`, and `SignaturePurpose`. Their
133
+ `KNOWN_*` constants list known values. Inputs remain strict. Evidence check
134
+ kinds and detail variants can grow; look up the names you know and never
135
+ interpret an unknown entry as proof. Keep a default branch:
136
+
137
+ ```ts
138
+ import { KNOWN_NOTICES, type Notice } from "@agent-blueprint-protocol/verifier";
139
+ function deprecated(notice: Notice): boolean {
140
+ switch (notice) {
141
+ case KNOWN_NOTICES.extension_deprecated: return true;
142
+ default: return false;
143
+ }
144
+ }
205
145
  ```
206
146
 
207
- The loader is pure over `%{path => binary}` and refuses corrupted, incomplete,
208
- or empty corpora with typed errors; the report refuses a vacuous green. The
209
- corpus is regenerated by `MIX_ENV=test mix run --no-start
210
- scripts/generate_conformance_corpus.exs`, which refuses to write a corpus that
211
- does not verify.
212
-
213
- ### Second-language verifier
214
-
215
- `verifier/` is a first-class repo-side TypeScript implementation (Node ≥ 24,
216
- `node:` builtins only, zero npm runtime deps — never shipped in the Hex
217
- archive) that independently recomputes every corpus verdict and integrity
218
- check: its own bounded JSON scanner with duplicate rejection and the
219
- integer-window rule, its own JCS canonicalizer (number digits anchored to the
220
- native ECMAScript serializer, member sort by UTF-16 code units), domain-
221
- separated digests, detached-JWS Ed25519 verification through `node:crypto`
222
- with small-order key rejection, and the negotiation, bounds-algebra,
223
- compatibility, and federation semantics. Run it:
224
-
225
- ```bash
226
- node verifier/cli.ts --corpus priv/conformance # exit 0/1/2, report bytes on stdout
227
- node verifier/self_checks.ts # RFC 8785 Appendix B, window matrix,
228
- # Ed25519 keys, stored JOSE vectors
229
- mix verifier.agreement # byte-agrees the TS report with the
230
- # escript's (repo AND built archive),
231
- # runs the self-checks, and proves its
232
- # seeded reds (planted breaks) fire
233
- ```
234
-
235
- The agreement gate is part of `mix quality`: the two implementations must
236
- produce byte-identical JCS reports over the same corpus, and node ≥ 24 is a
237
- hard prerequisite of the gate.
238
-
239
- ## Documentation
240
-
241
- Every guide ships in the package and renders on HexDocs:
242
-
243
- - Start here: [getting started](documentation/getting-started.md) ·
244
- [quickstart](documentation/quickstart.md) ·
245
- [TypeScript quickstart](documentation/typescript.md) ·
246
- [Livebook walkthrough](docs/livebooks/abp-walkthrough.livemd)
247
- - Concepts: [what a blueprint is](documentation/what-a-blueprint-is.md) ·
248
- [what a deployment is](documentation/what-a-deployment-is.md) ·
249
- [portability](documentation/portability.md) ·
250
- [federation](documentation/federation.md)
251
- - By role: [producing artifacts](documentation/producer.md) ·
252
- [authoring extensions](documentation/extension-author.md) ·
253
- [host integration](documentation/host-integration.md) ·
254
- [operations](documentation/operations.md)
255
- - Reference: [the 74-code error guide](documentation/errors.md) ·
256
- [evidence commitments](documentation/evidence-commitments.md) ·
257
- [the extension registry](documentation/registry.md) ·
258
- [upgrading and stability](documentation/upgrading.md) ·
259
- [FAQ](documentation/faq.md) · [examples](documentation/examples.md)
260
- - The normative contract: [`spec/protocol.md`](spec/protocol.md)
261
-
262
- ## Security
263
-
264
- See [`SECURITY.md`](SECURITY.md). A successful verifier result is
265
- structural evidence only, never an authorization decision.
266
-
267
- ## License
268
-
269
- Apache License 2.0. See [`LICENSE`](LICENSE) and [`NOTICE`](NOTICE).
147
+ Release-manifest readers ignore unknown additive members but reject unknown
148
+ equivalence claims. Every unknown nonzero harness exit is failure. New revisions,
149
+ profiles, execution versions, modes, and flags are opt-in; existing contracts
150
+ and earlier corpus claims keep their meaning.
151
+
152
+ Every `max_cost.amount` is an integer count of millionths (10^-6) of one unit
153
+ of its uppercase ISO 4217 currency, independent of the currency's minor-unit
154
+ exponent. For example, `{amount: 1000, currency: "USD"}` means 0.001 USD.
155
+ Amounts compare as integers; mixed currencies deny. Federation
156
+ `resource_policy.cost` has the same scale in the bound Deployment Manifest's
157
+ `host_bounds.max_cost.currency`.