@agent-blueprint-protocol/verifier 0.8.3 → 1.0.0-rc.1

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 (123) hide show
  1. package/CHANGELOG.md +137 -0
  2. package/LICENSE +1 -1
  3. package/NOTICE +2 -2
  4. package/README.md +164 -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/kit/cli.mjs +1 -4
  21. package/dist/release-history.json +1 -0
  22. package/dist/release-metadata.json +1 -1
  23. package/dist/spec/FOUNDATION-TRANSITION.md +67 -0
  24. package/dist/spec/IPR.md +27 -0
  25. package/dist/spec/LICENSE +190 -0
  26. package/dist/spec/NOTICE +4 -0
  27. package/dist/spec/README.md +47 -0
  28. package/dist/spec/conformance/base64url-decode.schema.json +176 -0
  29. package/dist/spec/conformance/blueprint-decode.schema.json +280 -0
  30. package/dist/spec/conformance/bounds-new.schema.json +302 -0
  31. package/dist/spec/conformance/bounds_algebra-intersect.schema.json +457 -0
  32. package/dist/spec/conformance/canonicalization-encode.schema.json +280 -0
  33. package/dist/spec/conformance/case-file.schema.json +122 -0
  34. package/dist/spec/conformance/certified-results.json +1 -0
  35. package/dist/spec/conformance/claim.schema.json +52 -0
  36. package/dist/spec/conformance/compatibility-verify.schema.json +262 -0
  37. package/dist/spec/conformance/deployment-decode.schema.json +322 -0
  38. package/dist/spec/conformance/digest-tagged.schema.json +200 -0
  39. package/dist/spec/conformance/evidence.schema.json +249 -0
  40. package/dist/spec/conformance/execution.md +80 -0
  41. package/dist/spec/conformance/extension-resolve.schema.json +264 -0
  42. package/dist/spec/conformance/federation-decode.schema.json +318 -0
  43. package/dist/spec/conformance/federation-verify_commitment.schema.json +342 -0
  44. package/dist/spec/conformance/index.schema.json +102 -0
  45. package/dist/spec/conformance/json-decode.schema.json +287 -0
  46. package/dist/spec/conformance/negotiation-negotiate.schema.json +264 -0
  47. package/dist/spec/conformance/portability-scan.schema.json +188 -0
  48. package/dist/spec/conformance/predicate.schema.json +201 -0
  49. package/dist/spec/conformance/reconcile.schema.json +287 -0
  50. package/dist/spec/conformance/runner.md +182 -0
  51. package/dist/spec/conformance/schema-validate_instance.schema.json +206 -0
  52. package/dist/spec/conformance/signature-verify.schema.json +224 -0
  53. package/dist/spec/conformance/support.schema.json +72 -0
  54. package/dist/spec/errata.md +13 -0
  55. package/dist/spec/grammar/blueprint.cddl +92 -0
  56. package/dist/spec/grammar/deployment.cddl +125 -0
  57. package/dist/spec/grammar/derived/blueprint.schema.json +340 -0
  58. package/dist/spec/grammar/derived/deployment.schema.json +496 -0
  59. package/dist/spec/grammar/derived/taskenvelope.schema.json +244 -0
  60. package/dist/spec/grammar/taskenvelope.cddl +77 -0
  61. package/dist/spec/protocol.md +1238 -0
  62. package/dist/spec/registry/OPERATIONS.md +69 -0
  63. package/dist/spec/registry/registry.json +68 -0
  64. package/dist/verifier/b64url.d.ts +6 -2
  65. package/dist/verifier/b64url.js +7 -1
  66. package/dist/verifier/blueprint.d.ts +12 -16
  67. package/dist/verifier/blueprint.js +40 -112
  68. package/dist/verifier/bounds.d.ts +1 -1
  69. package/dist/verifier/bounds.js +2 -2
  70. package/dist/verifier/bounds_algebra.d.ts +9 -0
  71. package/dist/verifier/bounds_algebra.js +10 -7
  72. package/dist/verifier/canonical.d.ts +1 -1
  73. package/dist/verifier/canonical.js +41 -8
  74. package/dist/verifier/cli.js +97 -45
  75. package/dist/verifier/compatibility.js +5 -7
  76. package/dist/verifier/corpus.d.ts +1 -1
  77. package/dist/verifier/corpus.js +10 -2
  78. package/dist/verifier/decode.js +24 -6
  79. package/dist/verifier/deployment.d.ts +20 -3
  80. package/dist/verifier/deployment.js +48 -10
  81. package/dist/verifier/digest.d.ts +12 -0
  82. package/dist/verifier/digest.js +17 -3
  83. package/dist/verifier/errors.d.ts +2 -0
  84. package/dist/verifier/errors.js +1 -0
  85. package/dist/verifier/execution.d.ts +13 -0
  86. package/dist/verifier/execution.js +82 -0
  87. package/dist/verifier/extension.js +4 -4
  88. package/dist/verifier/facade.d.ts +325 -0
  89. package/dist/verifier/facade.js +78 -0
  90. package/dist/verifier/federation.d.ts +2 -2
  91. package/dist/verifier/federation.js +26 -79
  92. package/dist/verifier/harness.d.ts +16 -0
  93. package/dist/verifier/harness.js +201 -0
  94. package/dist/verifier/index.d.ts +3 -0
  95. package/dist/verifier/index.js +2 -0
  96. package/dist/verifier/mapping.d.ts +139 -0
  97. package/dist/verifier/mapping.js +1 -0
  98. package/dist/verifier/negotiation.d.ts +2 -1
  99. package/dist/verifier/negotiation.js +12 -3
  100. package/dist/verifier/plain.d.ts +4 -0
  101. package/dist/verifier/plain.js +38 -0
  102. package/dist/verifier/portability.d.ts +1 -1
  103. package/dist/verifier/portability.js +19 -6
  104. package/dist/verifier/predicate.d.ts +7 -0
  105. package/dist/verifier/predicate.js +63 -7
  106. package/dist/verifier/reconcile.d.ts +37 -0
  107. package/dist/verifier/reconcile.js +115 -0
  108. package/dist/verifier/registry.js +10 -1
  109. package/dist/verifier/registry_engine.d.ts +3 -0
  110. package/dist/verifier/registry_engine.js +37 -20
  111. package/dist/verifier/report.d.ts +8 -0
  112. package/dist/verifier/report.js +9 -2
  113. package/dist/verifier/results.d.ts +3 -0
  114. package/dist/verifier/results.js +13 -0
  115. package/dist/verifier/run_corpus.js +4 -80
  116. package/dist/verifier/runner.d.ts +6 -0
  117. package/dist/verifier/runner.js +123 -17
  118. package/dist/verifier/schema.js +14 -55
  119. package/dist/verifier/signature.d.ts +19 -8
  120. package/dist/verifier/signature.js +51 -29
  121. package/dist/verifier/value.d.ts +9 -2
  122. package/dist/verifier/value.js +81 -11
  123. package/package.json +17 -12
package/CHANGELOG.md CHANGED
@@ -2,6 +2,143 @@
2
2
 
3
3
  All notable public changes to `agent_blueprint_protocol` are documented here.
4
4
 
5
+ ## [1.0.0-rc.1] — 2026-11-11
6
+
7
+ ### Breaking
8
+
9
+ - TypeScript imports use the package root. Previous `dist/verifier/blueprint.js`
10
+ `decode` becomes `decodeBlueprint`; Deployment and federation `decode` become
11
+ `decodeDeployment` and `decodeFederationEnvelope`. Internal `negotiate`,
12
+ `intersect`, signature and compatibility `verify`, corpus `load`, runner
13
+ `run`, and report builders map to root `negotiate`, `intersect`,
14
+ `verifySignature`, `verifyCompatibility`, `loadCorpus`, `runCorpus`,
15
+ `buildReport`, and `buildResultsDocument`. Deep paths no longer resolve;
16
+ public results use `value` and typed `error` members. The TypeScript guide
17
+ lists the complete migration, including artifact `canonicalBytes`.
18
+
19
+ - All fallible public Elixir operations return `{:error, %Error{}}`.
20
+ Decoder ceilings carry `{:ceiling, key}` in `Error.code`; value-returning
21
+ helpers retain their success form and declare the failure branch.
22
+ Denial details are `nil`, including protected-clamp denials; acknowledged
23
+ clamp results retain their typed evidence.
24
+ - Evidence marks unsigned artifacts and skipped observations unverified.
25
+ Typed signature details identify distinct verifying keys; binding details
26
+ list checks performed and skipped. Unverified surfaces are explicit.
27
+ - `Signature.verify/2` returns verified signed attributes in both languages.
28
+ Repeated signer key identifiers deny `invalid_constraint` during structure validation.
29
+ - Implementation modules and helper functions are hidden from the public API.
30
+ - The registry digest changes for the controlled federation registration.
31
+ Verification-semantics version is 2; protocol revision remains 1.
32
+
33
+ ### Changed
34
+
35
+ - The 1.x evolution contract preserves existing revisions and error codes,
36
+ keeps runtime and compiler floors, and defines additive paths for new
37
+ revisions, profiles, execution versions, and evidence identifiers.
38
+ - Detached signatures accept dotted key identifiers under RFC 7797 §5.1.
39
+ Monetary amounts consistently count millionths of a currency unit.
40
+ - Federation carriage describes native reconstruction; discovery signature
41
+ envelopes remain distinct. The EU AI Act guide states the enacted dates.
42
+ - TypeScript output identifiers are open with known-value constants;
43
+ packed declarations support TypeScript 5.0.2 and newer. Node 26 joins
44
+ the platform matrix while Node 24 remains the runtime floor.
45
+ - GitHub release publication waits for a live Hex version whose checksum
46
+ matches the verified archive, including after staged approval.
47
+
48
+ - The specification separates protocol requirements from implementation notes
49
+ and states the byte, grammar, lattice, predicate and schema profiles with
50
+ pinned normative references.
51
+
52
+ - Byte-error precedence and malformed conformance inputs agree across the
53
+ implementations. Binding evidence requires every descriptor observation
54
+ and a complete age check before reporting those checks verified.
55
+ - Dotted key identifiers are accepted in detached signatures.
56
+ - Revision 1 accepts `EdDSA` and `Ed25519` protected-header identifiers;
57
+ producers SHOULD emit `Ed25519`. Existing signed bytes remain valid.
58
+ - `io.github.baselabs/federation` is active with the existing schema pin.
59
+ `com.example/federation` is deprecated and remains supported throughout
60
+ 1.x. Both carrier spellings verify; ambiguous double carriage denies.
61
+ - Registration checks MCP metadata key syntax. Artifact namespace decoding
62
+ remains unchanged. Prerelease versions retain their complete identity
63
+ across Hex, npm, release metadata, comparisons, and install instructions.
64
+
65
+ ### Added
66
+
67
+ - A conformance product: bounded case schemas, a normative runner contract,
68
+ reconcile and predicate cases, canonical certified results, an external
69
+ execution harness and adapters, and unsigned implementation claims.
70
+ - A package-root TypeScript library with typed import evidence, exhaustive
71
+ errors, isolated consumer declarations, and its own package README.
72
+ - A stability and deprecation policy for both packages and three-platform
73
+ contributor and published-package lanes on Linux, macOS, and Windows.
74
+ - Candidate promotion checks preserve certified bytes; further publication
75
+ waits for the staged npm version to be live and byte-verified.
76
+
77
+ - Mixed-order Ed25519 vectors distinguish the required cofactorless equation
78
+ from cofactored verification, without rejecting mixed-order points.
79
+ - Deterministic test-only signing for new fixtures, preserving every existing
80
+ fixture signature. Corpus cases pin algorithm spellings, duplicate signers,
81
+ both federation namespaces, and effect impact as an obligation.
82
+ - A public module and function declaration prevents silent API expansion.
83
+ Error descriptions distinguish overlapping conditions; evidence explicitly
84
+ names timestamp and lifecycle facts it does not establish.
85
+
86
+ ### Documentation
87
+
88
+ - Added `architecture.md`, `positioning.md`, `compose-and-sign.md`,
89
+ `handling-errors.md`, `reading-evidence.md`, `verifying-in-ci.md`,
90
+ `verifying-releases.md`, `security-model.md`, and `extensions.md`.
91
+ - Added `cheatsheet.cheatmd`; rewrote `examples.md` and expanded `errors.md` and `faq.md`.
92
+ - Reworked the Blueprint, Deployment, portability, federation, and
93
+ evidence-commitment concept guides.
94
+ - Reworked `producer.md` and `host-integration.md` to link the new how-to guides.
95
+ - Merged extension authoring and registry reference material into `extensions.md`.
96
+ - Updated the Federation carrier mapping reference.
97
+ - Added five standalone Livebook walkthroughs for the tour, producing artifacts, host import,
98
+ extensions and federation, and conformance and attacks. Each notebook runs with persisted
99
+ outputs and is included in the Hex package.
100
+
101
+ The corpus contains 604 cases, digest
102
+ `sha-256:oYnkSmTkHGk4AmZ8Sul99_6KYJUIuj2SN2GZAiT1glw`; registry
103
+ `sha-256:d98vF3duE_8P7N5aGLrmaqcj3uSDf0NsI4dzF7bXBDg`.
104
+ Prior released verdicts remain equivalent. The
105
+ `negotiation-estate-contract-valid` case now projects the
106
+ `extension_deprecated` notice for the legacy federation namespace.
107
+
108
+ ## [0.8.4] — 2026-11-10
109
+
110
+ ### Fixed
111
+
112
+ - Portability checks cover predicate arguments and path segments at every depth
113
+ and every signature key identifier in both implementations.
114
+ - Schema evaluation memoizes by schema location, avoiding repeated hashing of
115
+ large enum payloads. Federation reconstruction counts nodes across siblings.
116
+ - Malformed host arguments return typed, value-free denials through the
117
+ existing result channels. Direct canonical encoding enforces all structural
118
+ ceilings, including container size, string and key lengths, node count, and
119
+ depth, and rejects non-finite numbers. Producers cannot emit values that
120
+ verifiers refuse to decode.
121
+ - Conformance readers require regular files, reject symlinks, and cap the
122
+ entire directory at 1,000 entries and 5,000,000 bytes. Both CLIs state whether
123
+ the corpus matches the release-certified digest without changing report bytes.
124
+ - The TypeScript decoder retains all ceilings for partial bounds, rejects
125
+ unknown bounds and lone-surrogate string input, and exposes immutable maxima.
126
+ - The installed CLI accepts relative and absolute corpus paths with trailing
127
+ separators, reports help and version with exit 0, and keeps unknown arguments
128
+ at exit 2. Importing the optional corpus entry performs no filesystem access.
129
+ - Dependency installations use the lockfile with lifecycle scripts disabled.
130
+ Only the npm staging job can request an identity token.
131
+ - Malformed host arguments and hand-built values deny with the code of the
132
+ first violated rule; no verdict for decoded bytes changes.
133
+ - Publishing jobs consume the npm tarball and standalone kit produced by the
134
+ verification job.
135
+
136
+ The corpus contains 199 cases, digest
137
+ `sha-256:305LYavPWYaZP_pYGcZBPploy27btWTyMhiKd7XiRb8`; registry
138
+ `sha-256:FG2f38K0hba8tTP7iUaw7vHjgcnN_5F5Mp0v4G6UDVs`; specification digest
139
+ `sha-256:YfVuNANOdTyQD2rXtXPbonyguVQBCZQheb9WCv4DR8E`. Protocol revision and
140
+ `verification_semantics_version` remain 1.
141
+
5
142
  ## [0.8.3] — 2026-11-10
6
143
 
7
144
  ### Fixed — security
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,178 @@
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. The npm and Hex packages share one version.
5
+ The specification is [published with the project](https://github.com/baselabs/agent_blueprint_protocol/blob/main/spec/protocol.md).
6
6
 
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.3"}
35
- ]
36
- end
7
+ ```sh
8
+ npm install @agent-blueprint-protocol/verifier
9
+ npx @agent-blueprint-protocol/verifier --help
37
10
  ```
38
11
 
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}
12
+ For a candidate, append `@rc` to the install and npx package name. Stable
13
+ releases use `latest`. A staged version is
14
+ installable only after its npm approval. `npm view
15
+ @agent-blueprint-protocol/verifier@rc version` identifies the live candidate.
16
+
17
+ ## CLI
18
+
19
+ | Mode | Behavior |
20
+ |---|---|
21
+ | no arguments | run the embedded certified corpus |
22
+ | `--corpus <dir>` | run an integrity-checked corpus, emit the aggregate report |
23
+ | `--prior-corpus <dir>` | replay the prior census under current semantics |
24
+ | `--results --corpus <dir>` | emit canonical per-case results |
25
+ | `--serve --corpus <dir>` | speak the external execution protocol |
26
+ | `--artifact <file>` | decode a Blueprint, Deployment, or federation envelope |
27
+ | `--help`, `--version` | usage or package version |
28
+ | `conformance run --corpus <dir> --results <file> -- <command...>` | drive and judge another implementation |
29
+
30
+ Runner exits: 0 agreement/valid/help/version, 1 disagreement/invalid artifact,
31
+ 2 usage/readability/integrity failure, 3 internal invariant failure. Corpus
32
+ stderr states whether the digest matches the release-certified corpus.
33
+ Readers reject symlinks and nonregular files and cap a tree at 1,000 entries
34
+ and 5,000,000 bytes. Stdout reports and results are JCS without a trailing LF.
35
+ Harness exits 10–19 identify handshake mismatch, duplicate, missing, extra,
36
+ reordered, malformed, oversized, timeout, early-exit and disagreement outcomes
37
+ in that order. The execution contract in the specification defines each.
38
+
39
+ ## Library
40
+
41
+ The package is ESM-only; `require()` is not supported.
42
+ Only the package root and `package.json` are exported. Import has no command
43
+ or filesystem side effects. Every function returns `Result<T>`:
44
+ `{ok:true,value}` or `{ok:false,error:{code,subject}}`. Public types use
45
+ `Uint8Array` and strings; consumers need no Node global declarations.
46
+ `ErrorCode` is exhaustive, including `ceiling:<key>` denials.
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 use canonical example bytes `blueprintBytes`,
57
+ `deploymentBytes`, `envelopeBytes`, caller-supplied `keys` and `observed`,
58
+ and integrity-checked corpus files `files`. They return evidence, never
59
+ permission. Check `ok` before reading `value`.
60
+
61
+ ```ts
62
+ import {
63
+ decodeBlueprint, decodeDeployment, decodeFederationEnvelope, canonicalBytes,
64
+ negotiate, intersect, verifyCompatibility, reconcile, federationMapping,
65
+ verifySignature, loadCorpus, runCorpus, buildReport, buildResultsDocument
66
+ } from "@agent-blueprint-protocol/verifier";
67
+
68
+ const bp = decodeBlueprint(blueprintBytes, {bounds: {depth: 32}});
69
+ const dep = decodeDeployment(deploymentBytes);
70
+ const envelope = decodeFederationEnvelope(envelopeBytes);
71
+ if (bp.ok) canonicalBytes(bp.value);
72
+
73
+ const support = {revisions: new Set([1]), coreFields: new Set<string>(),
74
+ registry: {}, schemas: {}};
75
+ if (bp.ok) negotiate(bp.value, support);
76
+
77
+ // Each source supplies all thirteen bounds; classification uses
78
+ // {ordinal: "internal", markers: []}, cost uses {amount, currency}.
79
+ intersect({blueprint: requestedBounds, deployment: deploymentBounds,
80
+ host: hostBounds, protectedClamp: "acknowledge"});
81
+ if (dep.ok) verifyCompatibility(dep.value, observed);
82
+ if (bp.ok && dep.ok) reconcile(bp.value, dep.value, {
83
+ hostBounds, support, keys, protectedClamp: "deny",
84
+ observations: {now: null, maxAttestationAgeMs: null, observed: {}}
85
+ });
86
+ federationMapping();
87
+ verifySignature(signatureEntry, keys);
88
+
89
+ const corpus = loadCorpus(files);
90
+ if (corpus.ok) {
91
+ const run = runCorpus(corpus.value);
92
+ if (run.ok) buildReport(corpus.value, run.value);
93
+ buildResultsDocument(corpus.value);
94
+ }
71
95
  ```
72
96
 
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 190-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
97
+ Decoded views expose read-only JSON `value`, `canonicalBytes`, and
98
+ `contentDigest` (null for a federation envelope, whose commitment is a
99
+ separate identity). `Support`, `Inputs`, `Observations`, `Observed`,
100
+ `Context`, `PublicKey`, `BoundSet`, and decoder `Bounds` describe the
101
+ caller-supplied facts. `Evidence` includes typed checks, effective bounds,
102
+ clamps, and a nonempty `not_verified` list. Unsigned artifacts succeed with
103
+ signature verification explicitly unestablished; absent descriptor and
104
+ freshness observations remain unverified.
131
105
 
132
- The protocol API, schemas, canonicalization profile, extension registry,
133
- and conformance corpus are implemented and gated: 963 tests
134
- (64 properties) at 100% coverage, zero Dialyzer errors, `--strict`
135
- Credo clean, a 190-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).
106
+ ## External implementations and claims
141
107
 
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
108
+ ```sh
109
+ agent-blueprint-protocol conformance run --corpus ./conformance --results results.json -- ./example-adapter
181
110
  ```
182
111
 
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/`) — 190
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
112
+ After a pass, add `--claim claim.json --implementation example-verifier
113
+ --implementation-version 1 --source https://example.com/source
114
+ --platform example-platform --date 2026-11-10` before `--`. A claim is unsigned
115
+ and identifies the implementation, corpus, registry and results bytes. A
116
+ non-certified corpus requires `--prior-corpus-digest <exact-digest>` to name
117
+ the prior census explicitly. Publish the claim and exact results document
118
+ beside source and the reproducible command. A public corpus pass proves
119
+ neither honest computation nor behavior outside the census nor any host
120
+ behavior. The kit includes the runner and execution contracts under `dist/spec/`.
121
+
122
+ ## Import migration
123
+
124
+ | Previous internal import and symbol | Package-root replacement |
125
+ |---|---|
126
+ | `dist/verifier/blueprint.js`: `decode` | `decodeBlueprint` |
127
+ | `dist/verifier/deployment.js`: `decode` | `decodeDeployment` |
128
+ | `dist/verifier/federation.js`: `decode` | `decodeFederationEnvelope` |
129
+ | artifact modules: `canonicalBytes` | `canonicalBytes` |
130
+ | `dist/verifier/negotiation.js`: `negotiate` | `negotiate` |
131
+ | `dist/verifier/bounds_algebra.js`: `intersect` | `intersect` with a Sources object |
132
+ | `dist/verifier/compatibility.js`: `verify` | `verifyCompatibility` |
133
+ | `dist/verifier/signature.js`: `verify` | `verifySignature` |
134
+ | `dist/verifier/corpus.js`: `load` | `loadCorpus` |
135
+ | `dist/verifier/runner.js`: `run` | `runCorpus` |
136
+ | `dist/verifier/report.js`: `build`, `toBytes` | `buildReport`, `buildResultsDocument` |
137
+
138
+ Deep imports no longer resolve. Internal `{ok,v,e}` records become public
139
+ `{ok,value,error}` results. `reconcile` and `federationMapping` are new root
140
+ operations. Internal byte, schema and codec helpers have no supported deep
141
+ import replacement. The package-root surface is the supported TypeScript API.
142
+
143
+ ## Compatibility within 1.x
144
+
145
+ Node 24 remains the runtime floor for all of 1.x; Node 26 is also supported.
146
+ TypeScript 5.0.2 is the compiler floor. Packed declarations are checked at
147
+ that floor and the current compiler with `moduleResolution: "nodenext"`,
148
+ `skipLibCheck: false`, and no `@types/node` dependency.
149
+
150
+ `ErrorCode` stays a closed union throughout 1.x, so exhaustive switches are
151
+ safe. Output identifiers are open string types: `Notice`, `EvidenceSurface`,
152
+ `EvidenceCheckKind`, `SignatureAlgorithm`, and `SignaturePurpose`. Their
153
+ `KNOWN_*` constants list known values. Inputs remain strict. Evidence check
154
+ kinds and detail variants can grow; look up the names you know and never
155
+ interpret an unknown entry as proof. Keep a default branch:
156
+
157
+ ```ts
158
+ import { KNOWN_NOTICES, type Notice } from "@agent-blueprint-protocol/verifier";
159
+ function deprecated(notice: Notice): boolean {
160
+ switch (notice) {
161
+ case KNOWN_NOTICES.extension_deprecated: return true;
162
+ default: return false;
163
+ }
164
+ }
205
165
  ```
206
166
 
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).
167
+ Elixir consumers match structs on the fields they use. Release-manifest
168
+ readers ignore unknown additive members but reject unknown equivalence
169
+ claims. Every unknown nonzero harness exit is failure. New revisions,
170
+ profiles, execution versions, modes, and flags are opt-in; existing contracts
171
+ and earlier corpus claims keep their meaning.
172
+
173
+ Every `max_cost.amount` is an integer count of millionths (10^-6) of one unit
174
+ of its uppercase ISO 4217 currency, independent of the currency's minor-unit
175
+ exponent. For example, `{amount: 1000, currency: "USD"}` means 0.001 USD.
176
+ Amounts compare as integers; mixed currencies deny. Federation
177
+ `resource_policy.cost` has the same scale in the bound Deployment Manifest's
178
+ `host_bounds.max_cost.currency`.