@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.
- package/CHANGELOG.md +137 -0
- package/LICENSE +1 -1
- package/NOTICE +2 -2
- package/README.md +164 -255
- package/dist/corpus/cases/blueprint-decode.json +1 -1
- package/dist/corpus/cases/bounds-new.json +1 -1
- package/dist/corpus/cases/bounds_algebra-intersect.json +1 -1
- package/dist/corpus/cases/canonicalization-encode.json +1 -1
- package/dist/corpus/cases/deployment-decode.json +1 -1
- package/dist/corpus/cases/extension-resolve.json +1 -1
- package/dist/corpus/cases/federation-decode.json +1 -1
- package/dist/corpus/cases/federation-verify_commitment.json +1 -1
- package/dist/corpus/cases/json-decode.json +1 -1
- package/dist/corpus/cases/negotiation-negotiate.json +1 -1
- package/dist/corpus/cases/predicate.json +1 -0
- package/dist/corpus/cases/reconcile.json +1 -0
- package/dist/corpus/cases/schema-validate_instance.json +1 -1
- package/dist/corpus/cases/signature-verify.json +1 -1
- package/dist/corpus/index.json +1 -1
- package/dist/kit/cli.mjs +1 -4
- package/dist/release-history.json +1 -0
- package/dist/release-metadata.json +1 -1
- package/dist/spec/FOUNDATION-TRANSITION.md +67 -0
- package/dist/spec/IPR.md +27 -0
- package/dist/spec/LICENSE +190 -0
- package/dist/spec/NOTICE +4 -0
- package/dist/spec/README.md +47 -0
- package/dist/spec/conformance/base64url-decode.schema.json +176 -0
- package/dist/spec/conformance/blueprint-decode.schema.json +280 -0
- package/dist/spec/conformance/bounds-new.schema.json +302 -0
- package/dist/spec/conformance/bounds_algebra-intersect.schema.json +457 -0
- package/dist/spec/conformance/canonicalization-encode.schema.json +280 -0
- package/dist/spec/conformance/case-file.schema.json +122 -0
- package/dist/spec/conformance/certified-results.json +1 -0
- package/dist/spec/conformance/claim.schema.json +52 -0
- package/dist/spec/conformance/compatibility-verify.schema.json +262 -0
- package/dist/spec/conformance/deployment-decode.schema.json +322 -0
- package/dist/spec/conformance/digest-tagged.schema.json +200 -0
- package/dist/spec/conformance/evidence.schema.json +249 -0
- package/dist/spec/conformance/execution.md +80 -0
- package/dist/spec/conformance/extension-resolve.schema.json +264 -0
- package/dist/spec/conformance/federation-decode.schema.json +318 -0
- package/dist/spec/conformance/federation-verify_commitment.schema.json +342 -0
- package/dist/spec/conformance/index.schema.json +102 -0
- package/dist/spec/conformance/json-decode.schema.json +287 -0
- package/dist/spec/conformance/negotiation-negotiate.schema.json +264 -0
- package/dist/spec/conformance/portability-scan.schema.json +188 -0
- package/dist/spec/conformance/predicate.schema.json +201 -0
- package/dist/spec/conformance/reconcile.schema.json +287 -0
- package/dist/spec/conformance/runner.md +182 -0
- package/dist/spec/conformance/schema-validate_instance.schema.json +206 -0
- package/dist/spec/conformance/signature-verify.schema.json +224 -0
- package/dist/spec/conformance/support.schema.json +72 -0
- package/dist/spec/errata.md +13 -0
- package/dist/spec/grammar/blueprint.cddl +92 -0
- package/dist/spec/grammar/deployment.cddl +125 -0
- package/dist/spec/grammar/derived/blueprint.schema.json +340 -0
- package/dist/spec/grammar/derived/deployment.schema.json +496 -0
- package/dist/spec/grammar/derived/taskenvelope.schema.json +244 -0
- package/dist/spec/grammar/taskenvelope.cddl +77 -0
- package/dist/spec/protocol.md +1238 -0
- package/dist/spec/registry/OPERATIONS.md +69 -0
- package/dist/spec/registry/registry.json +68 -0
- package/dist/verifier/b64url.d.ts +6 -2
- package/dist/verifier/b64url.js +7 -1
- package/dist/verifier/blueprint.d.ts +12 -16
- package/dist/verifier/blueprint.js +40 -112
- package/dist/verifier/bounds.d.ts +1 -1
- package/dist/verifier/bounds.js +2 -2
- package/dist/verifier/bounds_algebra.d.ts +9 -0
- package/dist/verifier/bounds_algebra.js +10 -7
- package/dist/verifier/canonical.d.ts +1 -1
- package/dist/verifier/canonical.js +41 -8
- package/dist/verifier/cli.js +97 -45
- package/dist/verifier/compatibility.js +5 -7
- package/dist/verifier/corpus.d.ts +1 -1
- package/dist/verifier/corpus.js +10 -2
- package/dist/verifier/decode.js +24 -6
- package/dist/verifier/deployment.d.ts +20 -3
- package/dist/verifier/deployment.js +48 -10
- package/dist/verifier/digest.d.ts +12 -0
- package/dist/verifier/digest.js +17 -3
- package/dist/verifier/errors.d.ts +2 -0
- package/dist/verifier/errors.js +1 -0
- package/dist/verifier/execution.d.ts +13 -0
- package/dist/verifier/execution.js +82 -0
- package/dist/verifier/extension.js +4 -4
- package/dist/verifier/facade.d.ts +325 -0
- package/dist/verifier/facade.js +78 -0
- package/dist/verifier/federation.d.ts +2 -2
- package/dist/verifier/federation.js +26 -79
- package/dist/verifier/harness.d.ts +16 -0
- package/dist/verifier/harness.js +201 -0
- package/dist/verifier/index.d.ts +3 -0
- package/dist/verifier/index.js +2 -0
- package/dist/verifier/mapping.d.ts +139 -0
- package/dist/verifier/mapping.js +1 -0
- package/dist/verifier/negotiation.d.ts +2 -1
- package/dist/verifier/negotiation.js +12 -3
- package/dist/verifier/plain.d.ts +4 -0
- package/dist/verifier/plain.js +38 -0
- package/dist/verifier/portability.d.ts +1 -1
- package/dist/verifier/portability.js +19 -6
- package/dist/verifier/predicate.d.ts +7 -0
- package/dist/verifier/predicate.js +63 -7
- package/dist/verifier/reconcile.d.ts +37 -0
- package/dist/verifier/reconcile.js +115 -0
- package/dist/verifier/registry.js +10 -1
- package/dist/verifier/registry_engine.d.ts +3 -0
- package/dist/verifier/registry_engine.js +37 -20
- package/dist/verifier/report.d.ts +8 -0
- package/dist/verifier/report.js +9 -2
- package/dist/verifier/results.d.ts +3 -0
- package/dist/verifier/results.js +13 -0
- package/dist/verifier/run_corpus.js +4 -80
- package/dist/verifier/runner.d.ts +6 -0
- package/dist/verifier/runner.js +123 -17
- package/dist/verifier/schema.js +14 -55
- package/dist/verifier/signature.d.ts +19 -8
- package/dist/verifier/signature.js +51 -29
- package/dist/verifier/value.d.ts +9 -2
- package/dist/verifier/value.js +81 -11
- 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
package/NOTICE
CHANGED
package/README.md
CHANGED
|
@@ -1,269 +1,178 @@
|
|
|
1
|
-
# Agent Blueprint Protocol
|
|
1
|
+
# Agent Blueprint Protocol for TypeScript
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
[
|
|
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
|
-
|
|
8
|
-
|
|
9
|
-
|
|
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
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
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
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
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
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
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
|
-
|
|
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
|
-
|
|
143
|
-
|
|
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
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
the
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
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
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
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`.
|