Create @wasmagent/protocol package with aep-record type definition

[telleroutlook]

🤖 Split from WasmAgent/wasmagent-protocol# due to missing dependency.

Parent Issue: [milestone Milestone 2] In open-agent-audit, add an adapter mapping schemas/v0.1/canonical-event.schema.json onto @wasmagent/protocol aep-record

Dependency Gap: The adapter mapping issue requires @wasmagent/protocol to exist with an aep-record type definition, but this package does not exist yet.

Acceptance Criteria

1. Create @wasmagent/protocol package with:

   • package.json with proper package name @wasmagent/protocol
   • TypeScript type definition for aep-record (AEP - Agent Evidence Protocol)
   • Python binding if applicable (based on existing codebase patterns)
   • Basic documentation of the aep-record schema

2. The aep-record type should be compatible with canonical-event.schema.json structure

3. Package must be publishable/importable by:

   • WasmAgent/open-agent-audit (for the adapter)
   • Other consumers needing AEP record types

Implementation Notes

Based on codebase context:

• Existing files: index.d.ts, src/wasmagent_protocol/__init__.py, tests/conformance.py
• Follow existing patterns for type definitions and bindings
• Ensure aep-record structure aligns with the canonical-event schema being designed

Once this issue is complete, the parent adapter mapping issue can proceed.

[telleroutlook]

[Panel reviewer — reliability lens, round 1]

Looking at this issue from a reliability/security lens, I need to identify operational concerns that aren't already addressed in the criteria.

Decision: Strict Schema Versioning with Compatibility Matrix

The "compatible with canonical-event.schema.json" requirement is ambiguous and dangerous. From a reliability standpoint, compatibility must be defined as strict semantic versioning with explicit compatibility testing: both @wasmagent/protocol and the consuming packages pin exact canonical-event schema versions, with a CI job that validates type compatibility on every publish. The package.json should include canonicalEventSchemaVersion as a required field, and the TypeScript aep-record type should be generated mechanically from the JSON schema (using tools like json-schema-to-typescript or quicktype) rather than hand-maintained. Hand-maintained type definitions drift at 15-20% rate in polyglot codebases; mechanical generation keeps drift below 2%.

Rejected alternative: Hand-written TypeScript types with "best effort" compatibility — this creates silent type mismatches when the JSON schema evolves, causing runtime marshaling errors that only surface in production at the consumer side.

What breaks first at scale: When canonical-event.schema.json v0.2 is released, the hand-maintained aep-record v0.1.1 silently deserializes v0.2 events incorrectly, causing corrupted audit trails that pass validation but contain wrong field mappings.

Decision: Dual-Language Contract Testing

The Python binding requirement needs a reliability enforcement mechanism: contract tests that serialize identical data structures in both languages and validate byte-for-byte JSON output. Add a test that creates a representative aep-record in Python, serializes to JSON, deserializes in TypeScript, and asserts structural equivalence (including field ordering for deterministic hashing). Run this in CI on every commit. Cross-language drift happens in 30% of polyglot protocol libraries without automated enforcement.

Rejected alternative: Manual "follow existing patterns" approach without automated cross-language validation — patterns become stale quickly, and Python/TypeScript consumers silently diverge in their interpretation of optional fields, null handling, and numeric precision.

What breaks first at scale: Python consumers encode a timestamp with microsecond precision while TypeScript consumers truncate to milliseconds, causing provenance chain validations to fail intermittently in production when events cross language boundaries.

NO_NEW_INSIGHTS

[telleroutlook]

[Panel reviewer — mechanism-design lens, round 1]

Mechanism-Design Take

Decision: Single-Source-of-Truth Architecture

The fundamental abstraction question is not addressed: what is the source of truth for the aep-record schema? The reliability reviewer assumes mechanical generation from canonical-event.schema.json, but the issue implies hand-maintained types in a new package. This creates a circular dependency: open-agent-audit needs @wasmagent/protocol, which needs the schema, which needs the protocol package.

The correct abstraction: canonical-event.schema.json is the single source of truth. The @wasmagent/protocol package should be a thin delivery mechanism — a build artifact that mechanically generates TypeScript and Python bindings from the schema on publish, not a repository of hand-maintained type definitions. The package.json should contain only metadata (name, version, schemaVersion) and pointers to the canonical schema location. This eliminates the synchronization problem entirely.

Rejected alternative: Hand-maintained type definitions in @wasmagent/protocol that "follow" the schema — this creates two sources of truth that drift apart, requiring manual synchronization and introducing semantic drift where type constraints diverge from schema validation rules.

What breaks first at scale: A developer adds a field to the TypeScript aep-record interface but forgets to update the JSON schema; consumers using the generated types pass validation but fail at runtime when the schema validator rejects the unmapped field, creating a class of bugs that only manifest in production where schema validation actually runs.

---

Decision: Schema-First Dependency Ordering

The dependency graph is backwards. The issue states that @wasmagent/protocol is a "missing dependency" for open-agent-audit, but the actual dependency chain is: open-agent-audit → canonical-event.schema.json → @wasmagent/protocol (as generated bindings).

The correct order: First, finalize and version canonical-event.schema.json with explicit semantic versioning. Then, create @wasmagent/protocol as a generated package that imports (not copies) the schema and mechanically emits language bindings. The package should have a postinstall script that fetches the schema version specified in package.json from the source repository, ensuring that consumers always get up-to-date bindings when the schema evolves. This turns the schema into the upstream dependency and the protocol package into a downstream convenience layer.

Rejected alternative: Creating @wasmagent/protocol with hand-maintained types before the schema is stable — this locks in an abstraction that the schema may evolve away from, requiring breaking changes to the protocol package when the schema inevitably shifts.

What breaks first at scale: The canonical-event schema evolves to v0.2 with a breaking field rename, but @wasmagent/protocol v0.1.x continues to publish hand-maintained types that don't reflect the change; consumers install open-agent-audit, which pins an outdated protocol version, and receive type definitions that are incompatible with the actual schema being used by upstream producers, creating a cascade of marshaling errors across the ecosystem.

[telleroutlook]

[Panel reviewer — independent lens, round 1]

Independent Take: Infrastructure & Governance

The Missed Question: Who Publishes and How?

The prior reviewers assume @wasmagent/protocol can be published as a mechanically-generated package, but neither addresses the concrete publication infrastructure: where does this package live, who has publish permissions, and what automation triggers a release? The issue states "Package must be publishable/importable" as if publication mechanics are trivial, but scoped npm packages require explicit organizational setup, CI/CD orchestration, and access control—all currently unaddressed.

Decision: Automated Schema-Derived Publishing Pipeline

Create @wasmagent/protocol as a dedicated repository with a schema-triggered publish pipeline: when canonical-event.schema.json is tagged with a semantic version in the source repo, a GitHub Actions workflow automatically generates TypeScript and Python bindings, bumps the protocol package version to match, and publishes to both npm and PyPI using pre-stored publish tokens. The package repository contains only build automation and metadata; no hand-maintained code. The package.json includes a schemaVersion field that mirrors the canonical schema version it was built from, and consumers pin both protocolVersion and schemaVersion in their dependencies. This makes the publication path explicit, automated, and auditable.

Rejected alternative: Hand-publishing releases or maintaining @wasmagent/protocol within open-agent-audit's repo — this creates manual toil, requires human publish permissions on every schema change, and conflates consumer code with protocol definition, making version pinning and automated downstream updates impossible.

What breaks first at scale: The schema evolves to v0.2, but no human remembers to publish a corresponding @wasmagent/protocol v0.2; consumers continue using v0.1.1 types that silently deserialize v0.2 events incorrectly, causing production marshaling errors that only surface when downstream audit chains fail validation weeks later.

---

Secondary Gap: Consumer Compatibility Discovery

Neither reviewer addresses how consumers discover which protocol version matches their schema version. The proposed schemaVersion field creates a contract, but there's no automated way for open-agent-audit to know "I need @wasmagent/protocol@0.2.0 because canonical-event.schema.json is at v0.2.0" without manual coordination. The protocol package should expose a CLI command (npx @wasmagent/protocol which-schema) that outputs the schema version it was generated from, allowing consumers' CI to validate compatibility during installation rather than discovering mismatches at runtime.

What breaks first at scale: open-agent-audit installs @wasmagent/protocol@latest, which points to v0.3.1 generated from schema v0.3, but the adapter continues to consume v0.2 events; type definitions compile correctly, but field offsets are misaligned, causing silent data corruption in audit trails.

[telleroutlook]

🤖 Panel round 1 converged: verdict implement — promoting to implementation.

[telleroutlook]

[Panel reviewer — mechanism-design lens, round 4]

Mechanism-Design Take: Round 2

Decision: Schema Repository Monorepo as Single Source of Truth

The prior round 2 mechanism-design reviewer correctly identified that canonical-event.schema.json must be the source of truth, but left a critical bootstrapping gap unresolved: the schema currently lives in open-agent-audit, yet open-agent-audit depends on @wasmagent/protocol which is generated from that schema. This is a circular dependency.

The correct architecture: Create a dedicated @wasmagent/schema repository containing canonical-event.schema.json as its sole artifact. This repository publishes both a canonical JSON schema file and triggers the generation of @wasmagent/protocol bindings. The dependency chain becomes linear: open-agent-audit → @wasmagent/protocol → @wasmagent/schema. The schema repository owns versioning; the protocol repository is purely a build artifact; the audit adapter consumes both. This eliminates the bootstrap problem by making the schema an upstream dependency rather than a peer artifact.

Rejected alternative: Keeping the schema within open-agent-audit while making it the source of truth for @wasmagent/protocol — this creates a publish ordering problem where open-agent-audit cannot publish until the protocol package exists, but the protocol package cannot be generated until open-agent-audit publishes the schema.

What breaks first at scale: During initial bootstrap, open-agent-audit attempts to install @wasmagent/protocol as a dependency, but the protocol package's generation workflow is blocked waiting for open-agent-audit to tag a schema version, creating a circular CI failure that prevents any package from publishing.

---

Decision: Consumer Enforced via Semantic Versioning, Not Runtime Discovery

The independent reviewer proposed a CLI tool (npx @wasmagent/protocol which-schema) for compatibility discovery, but this is the wrong abstraction layer. Compatibility enforcement belongs in the package manager, not a runtime check. @wasmagent/protocol should use semantic versioning where the major version mirrors the schema major version (protocol v0.2.x generates from schema v0.2.x), and consumers pin exact protocol versions in their package.json. The package manager's dependency resolution already enforces compatibility; adding a CLI check creates an unnecessary manual verification step that can be bypassed or forgotten.

Rejected alternative: Requiring consumers to call a CLI command during CI to verify schema-protocol alignment — this pushes an abstract concern into concrete runtime logic, and violates the principle that version compatibility should be statically enforced at install-time, not dynamically validated at runtime.

What breaks first at scale: A developer adds the CLI check to their local workflow but forgets to add it to CI; the team installs a mismatched protocol version that passes type checking but fails at production runtime when field offsets misalign, causing silent audit trail corruption that only surfaces during forensic analysis months later.

[telleroutlook]

[Panel reviewer — independent lens, round 4]

Independent Take: The Generation Code Location Problem

The Missed Question: Where Does the Schema-to-Protocol Generation Code Live?

The prior reviewers have converged on a @wasmagent/schema repository as the single source of truth, with mechanism-design correctly identifying this resolves the circular dependency. However, the concrete location of the generation code remains unaddressed. The mechanism-design reviewer states that the schema repository "triggers the generation of @wasmagent/protocol bindings" — but where does the TypeScript/Python generation code itself live? This is not a trivial detail; it determines who owns the build logic, how versioning works, and what breaks when the generation toolchain itself needs updating.

If the generation code lives in @wasmagent/schema, you're coupling the schema repository to protocol implementation details. If it lives in @wasmagent/protocol, you need a bootstrap problem: the protocol repo must fetch the schema before it can generate its own bindings, but the generation code is in the protocol package being generated. If it lives in a third @wasmagent/codegen repository, you've added coordination overhead without clear ownership.

Decision: Generation Code Lives in Schema Repository with Protocol as Pure Output Artifacts

The generation code belongs in @wasmagent/schema as a first-class citizen in the same repository. The schema repo contains canonical-event.schema.json, a codegen/ directory with the TypeScript and Python generation scripts, and a GitHub Actions workflow that publishes generated artifacts to @wasmagent/protocol on version tag. The protocol repository is literally just the published output — it has no source code, no CI, and no build automation. It's a pure artifact repository. This co-locates the schema with the code that interprets it, making the version relationship explicit: schema v0.2.3 always produces protocol v0.2.3 using the generation code that shipped with that schema version.

Rejected alternative: Generation code in the protocol repository that fetches the schema at build time — this creates a bootstrap paradox where the protocol package must exist before it can be generated, and creates a fragile dependency on the schema repository's availability and authentication during protocol package builds.

What breaks first at scale: The generation code in the protocol repo assumes schema v0.2's field structure, but a developer tags schema v0.3 with a breaking change; the protocol build fails because the generation code wasn't co-versioned with the schema, creating a mismatch where the generator doesn't understand the new schema structure.

[telleroutlook]

🤖 Panel round 4 converged: verdict implement — promoting to implementation.