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.

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.6

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.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.