feat: industry-standard conformance — AG-UI transport + schema-verified A2UI (phase 1)

[adamstankiewicz]

What & why

Makes the standards story checkable instead of aspirational, and hardens the a2learn layer into code. Phase 1 of an incremental, verifiable migration — each phase lands only with fixtures proving it.

• Spec truth from the official package: the A2UI v1.0 schemas come from @a2ui/web_core (the A2UI project's own publication — google/A2UI now redirects to a2ui-project/a2ui), exact-pinned as a devDependency with the lockfile integrity hash as the checksum. Nothing of the upstream spec is committed; a spec bump is an ordinary dependency bump the conformance gate passes judgment on. Our surfaces target the released revision, because interop is with shipped renderers, not the spec repo's HEAD — concretely, the emitted action event carries the intersection every revision accepts (name + context).
• The a2learn layer as code (src/lib/a2learn/): a versioned ActivityManifest builder and the A2UI boundary mapper. Three kinds map today (markdown-card, flashcard, step-reveal); fidelity limits are stated, not papered over — the flashcard reveal survives as Tabs and its deck as a horizontal List (renderer-local interactions the catalog does provide), while flip animation and per-card progress stay renderer-side.
• Real AG-UI transport (/api/pathway/agui): the pathway build as a typed @ag-ui/core run — protocol drift fails tsc.
• pnpm conformance, folded into ci.yml's verify job: zod-validated fixtures → upstream-schema validation → structural invariants (including Tabs' nested child refs) → golden diffs — with negative controls at every layer, so a vacuously-green validator can't hide: the schema validator must reject an empty message and a malformed component, the structural checker must report duplicate ids, dangling refs (tab refs included), and a missing root, and the zod gate must refuse an unknown kind. A2UI_SUPPORTED_KINDS derives from the dispatch table and must be fixture-covered — support is proven, never asserted.
• The mapping is functional, not just proven: /api/widget accepts format: "a2ui" and returns the built widget's surface alongside the spec, refusing an unmappable kind with the mapped-kinds list before spending a model call.

Reviewer notes on history: a three-tier demo page (/demo/a2ui) was built mid-review to exercise the mapper visually and retired within this PR once it had served its purpose — it nets out of the squash and never reaches main. Its surface renderer moved up the stack to #101, where its consumer (the composed widget kind) lives. An interim fetch-and-pin scheme for the schemas likewise lived and died inside this PR once the official package proved viable.

Migration phases: 2 = manifest served by find_activity/build_pathway, more kinds one fixture-proven PR each; 3 = interactive kinds via the a2learn catalog (#98/#100 — the composed kind in #101 is the first fruit); 4 = the app renders from its own surfaces (dogfood).

Type of change

• New/changed seam implementation (a standards-conformant transport + the a2learn boundary layer)

Breaking or contract changes

Additive: a new route, a new library layer, and an additive format option on /api/widget; the app's existing wire format is untouched. The spec schemas update only by bumping the pinned @a2ui/web_core version.

How it was verified

• pnpm lint and rm -rf .next && npx tsc --noEmit
• pnpm conformance — all four layers green against the package's schemas; negative controls verified at every layer
• pnpm test (40 on this branch), pnpm build
• Live: /api/widget a2ui format returns a 41-component surface for a generated flashcard and refuses drag-sort honestly; the retired demo verified rendering end to end (Playwright) before retiring
• Review-pass findings fixed and dispositioned (see comment): derived support list, no false correct claims, image sides mapped, protocol-legal 400s, quiet cancel teardown

Authorship

• I understand every line of this diff
• Agent-assisted or agent-authored: authored by Claude working interactively with @adamstankiewicz; multi-agent review pass findings + dispositions in the PR comment
• package.json/pnpm-lock.yaml changes are the feature's own dependencies (@ag-ui/core, ajv, ajv-formats, @a2ui/web_core exact-pinned)

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
interactive-learning-experiences	Ready	Preview	Aug 31, 2026 12:05am

[adamstankiewicz]

Pre-merge review pass (multi-agent finders + verification) — findings and dispositions:

Fixed in ba8137b:

• The dispatch table now is the support list — A2UI_SUPPORTED_KINDS derives from the MAPPERS record (typed on WidgetKind), so claiming a kind without mapping it, or vice versa, is impossible by construction.
• Flashcard sides render text/markdown/images as separate components — an image-only side is legal per the schema and no longer degrades to a dash; successMessage is carried; no emphasis-wrapping (bold can't span joined lines, and model text may already contain Markdown).
• completedAction no longer asserts correct: true — both mapped kinds are assesses: false, and the mapper must never report mastery nothing measured. Assessing kinds gain verdicts from real checking when they arrive, gated on the registry flag.
• Conformance gained a first layer: fixtures must parse against the app's real zod widgetSpec, so goldens prove the mapper against specs the pipeline can produce (this immediately caught the flashcard fixture missing its required successMessage). Also: explicit catalogId assertion (the ajv alias made validation catalog-blind), template-form children resolution, one fail() helper, data-URL import instead of writing into node_modules.
• AG-UI route: doc comment states the real scope (no profile/persistence yet); 400s emit RUN_STARTED before RUN_ERROR so standard client middleware sees a legal sequence; cancelled consumers get a quiet teardown; dead error branch removed; the a2learn. namespace is owned by the a2learn layer, not the transport.
• Workflow: permissions, concurrency, timeout-minutes, .nvmrc; package.json em-dash churn reverted.

Deferred, deliberately:

• Persistence + profile parity for the AG-UI transport: phase 2, converging on runPathway (feat: build_pathway over MCP, and a richer widget-to-agent channel #76) after both merge.
• Shared parse/encode/collect helpers across the three streaming routes: same phase-2 convergence.
• The mapper's durable home is an optional field on WidgetCatalogEntry (registry-owned-semantics refactor) — the MAPPERS record is the interim that can't drift.
• manifest.ts has no producer yet, stated in its doc comment; it gains one when find_activity (feat: find_activity — the registry half of find → invoke #75) converges on it.
• Folding this workflow into ci.yml once the OSS hardening 1/4: community health files #69–OSS hardening 4/4: CI rebuilds the widget shell and fails on drift #73 stack lands.

🤖 Generated with Claude Code