wasmagent-protocol

Canonical source of truth for every cross-repository contract in the WasmAgent org. One public schema → one canonical source.

WasmAgent is open infrastructure for provable AI agents. Proving an agent ran correctly requires that every repository — the runtime, the gateway, the evidence pipelines, the audit product — speak the same evidence and compliance vocabulary. wasmagent-protocol is where that vocabulary is defined, versioned, and published, so no repository has to keep its own copy.

This repository holds specifications only. It contains no business logic, no runtime, and no product code — only JSON Schemas, conformance fixtures, and thin loader packages that expose the schemas to JavaScript and Python consumers.

Why this repository exists

The Agent Evidence Protocol (AEP) and the compliance schemas were originally authored inside wasmagent-js and independently copied into trace-pipeline. By the time this repository was extracted, those copies had drifted: five shared schemas differed (one had a copy-paste title bug, and the same logical schema carried two conflicting $id URLs). Drift in a shared contract silently breaks cross-repo evidence validation — exactly the failure mode WasmAgent exists to prevent.

Per the org repository boundary policy: one public schema has exactly one canonical source. That source is here.

What's in scope

Only contracts that genuinely cross a repository boundary:

The machine-readable registry is schemas/index.json.

Out of scope: schemas owned by a single repository (e.g. trace-pipeline's *-training-record output formats, open-agent-audit's audit-run). A schema belongs here only when two or more repositories must agree on it.

Standards alignment

AEP is an evidence-integrity layer on top of OpenTelemetry GenAI, not a competing telemetry protocol. If your agents already emit OTel GenAI spans, docs/AEP-OTEL-MAPPING.md shows field by field what AEP reuses from OTel and what it adds (signing, tamper-evidence, capability decisions, budget ledgers, side-effect provenance).

Consuming the schemas

Downstream repositories must not copy schema JSON. Depend on the published package instead.

JavaScript / TypeScript

npm install @wasmagent/protocol

import { schemas, getSchema } from "@wasmagent/protocol";

const aep = getSchema("aep-record"); // parsed JSON Schema object

Python

pip install wasmagent-protocol

from wasmagent_protocol import get_schema, schema_path

aep = get_schema("aep-record")        # parsed dict
path = schema_path("aep-record")      # pathlib.Path to the .json file

Preventing cross-repo drift

Downstream repos must not keep local copies of these schemas — but "must not" is now also enforced in CI, not just written down. This repo ships a reusable drift gate.

CLI

Both packages expose wasmagent-protocol check. It fails non-zero when a vendored schema differs from the canonical version, when a canonical $id is re-declared without depending on the package, or when a competing schemas/index.json is shipped.

# compare one vendored file against the pinned canonical version
wasmagent-protocol check path/to/aep-record.schema.json --id aep-record

# scan a whole repo for drift and competing registries
wasmagent-protocol check --scan --root .

Reusable GitHub workflow

Consumer repos call the shared gate with one job:

jobs:
  schema-drift:
    uses: WasmAgent/wasmagent-protocol/.github/workflows/schema-drift.yml@v0.1.9

A PR in any consumer that forks or drifts a canonical schema now fails CI automatically. See docs/CONTRACT-CHANGE-PROCESS.md.

Versioning & stability

• Each schema carries a version string (see the registry).
• Additive changes (new optional field) → minor package bump.
• Breaking changes (removed/renamed field, tightened required) → major package bump and a new version value, announced in the org release ledger before merge.
• Every schema has at least one valid and one invalid conformance fixture under tests/fixtures/. CI rejects any schema without both.

See docs/CONTRACT-CHANGE-PROCESS.md for the full change workflow and docs/GOVERNANCE.md for maintainer and exit-condition policy.

Development

# validate every schema is well-formed and every fixture conforms
python3 -m pip install -e ".[dev]"
python3 tests/conformance.py

# run the drift gate against this repo (auto-detects the canonical source)
python3 -m wasmagent_protocol check --scan --root .

Releases

Published to npm and PyPI from CI via OIDC trusted publishing on v* tags — no tokens stored. See docs/CONTRACT-CHANGE-PROCESS.md.

• 0.1.10 — selective-omission defense: authorization_evidence_count (integer ≥ 0) added to aep-record (aep/v0.5+). Without this field, a producer can omit a weak authorization entirely and report only the strong ones — the observed set still looks self-consistent. The count commits the producer to a specific evidence population; an auditor who later discovers the true count differs has a tamper indicator. Floor description strengthened to reference the count cross-check. Per the OWASP #44 expert recommendation on floor completeness (selective omission is the strongest attack against weakest-grade semantics).
• 0.1.9 — attribution grading lands in aep-record (aep/v0.5): authority_origin (consent-origin axis: subject-consented / administrator-assigned / organization-wide / unknown), identity_source (self-asserted / organization-attested / notified eID / qualified certificate), attribution_backing with the run-level run_attribution_backing_floor (weakest-grade rollup, MUST NOT round up) plus run_attribution_backing_observed (floor and itemization ship together), and authorized_by (requester vs authorizer). Vocabulary shared with the OWASP MCP Top 10 "Verifiable Authorization Lineage" recommended control. All fields optional and additive — aep/v0.1–v0.4 records stay valid.
• 0.1.8 — AEP evidence types beyond execution: memory-evidence, replay-evidence, checkpoint-evidence, and artifact-attestation join the registry, alongside canonical-event, checkpoint, fork, and the shared evidence-envelope/_base scaffolding. aep-record widens schema_version to aep/v0.4 with an optional dsse_envelope (DSSE PAE, matching @wasmagent/aep useDsse emission; legacy signature stays optional and accepted). Python wheel loader fixed for Python 3.9; parity gate now enumerates all canonical schemas automatically.
• 0.1.7 — aep-record unified to aep/v0.3: reconciles the wasmagent-js and trace-pipeline forks into one canonical record. Additive optional fields user_id, subject_id, side_effect_class (per-record) + run_side_effect_class_max (per-run) sharing one enum, recording_mode, argument_drift. aep/v0.1/aep/v0.2 stay accepted; signature stays optional.
• 0.1.6 — cross-repo schema-drift gate: wasmagent-protocol check CLI (npm + PyPI) and the reusable .github/workflows/schema-drift.yml workflow.
• 0.1.5 — first successful npm OIDC publish (trusted publisher now registered on npmjs).
• 0.1.4 — npm OIDC groundwork; trusted publisher was not yet saved on npmjs.
• 0.1.3 — npm OIDC attempt: dropped registry-url (ENEEDAUTH); PyPI only.
• 0.1.2 — npm OIDC attempt (Node 24); PyPI only.
• 0.1.1 — release-pipeline verification (PyPI); no schema changes.
• 0.1.0 — initial canonical extraction of the AEP + compliance schema family.

License

Apache-2.0.