Weekly A2UI Compliance Report (2026-09-08)

## Summary

This report presents the findings of a comprehensive compliance verification audit across the entire A2UI repository. The audit evaluated specification adherence, documentation synchronization, and test assertion rigor across all 9 discovered codebase implementations: the Python Agent SDK (`agent_sdks/python/a2ui_agent`), Python Core SDK (`agent_sdks/python/a2ui_core`), Web Core layer (`renderers/web_core`), React renderer (`renderers/react`), Angular renderer (`renderers/angular`), Lit renderer (`renderers/lit`), Flutter renderer placeholder (`renderers/flutter`), Swift Core runtime (`swift/core`), and SwiftUI framework adapter (`swift/swiftui`).

The blueprint compliance audit revealed that all 9 codebase blueprints are currently unbaselined (`module_blueprint_commit: null`) and lack declared feature lists (`implemented_features: []`), placing all implementations in an "Out of Date" status relative to language-agnostic module blueprints. Python and Swift core codebases trail the latest module blueprint updates by 3 commits (notably missing pre-send surface state cycle checking introduced in commit `80a45c1e`), while native UI framework adapters trail by 1 commit. The Flutter renderer remains in a planned state with no codebase implementation files in the repository.

The documentation synchronization audit identified actionable drift, including invalid package manager instructions (e.g. `yarn install @a2ui/web_core` in `renderers/web_core/README.md`), invalid directory paths for workspace root tooling in Python SDK READMEs, and injection token typographical discrepancies in Angular documentation. The test quality audit detected 130 weak assertions relying on truthiness or non-null checks across core and renderer test suites (e.g. `agent_sdks/python/a2ui_core/tests/test_processing.py` and `renderers/react/tests/`), requiring strengthening with structural payload and state assertions.

## Recommendations

1. **P0**: **Baseline Codebase Blueprints and Pin Specification Commits**
- Update frontmatter in all 9 `codebase.blueprint.md` files under `blueprints/codebases/` to populate `module_blueprint_commit` with the latest commit hashes (`80a45c1eb828848a89bb59f61f781a767569892d` for `a2ui_agent` and `a2ui_core`; `a2b4c90622fee9ad1f07ee1e4c3c73d905c36381` for `a2ui_framework_adapter`). Populate the empty `implemented_features` lists with verified feature sets (e.g., Express format, Elemental format, Direct JSON, Signals reactivity, DataContext binding).
Copy this prompt to implement this recommendation:
````markdown
Read the A2UI issue at https://github.com/a2ui-project/a2ui/issues/2556 and use the `a2ui-remediate-problem` skill to implement recommendation 1 described in the issue's Recommendation section.
````

2. **P0**: **Integrate Surface State Cross-Payload Cycle Checking in Python Agent SDK**
- Implement the surface state validation specification introduced in commit `80a45c1e` (`blueprints/modules/a2ui_agent.blueprint.md:L338-L345`) in `agent_sdks/python/a2ui_agent/src/a2ui/schema/validator.py` and `agent_sdks/python/a2ui_agent/src/a2ui/parser/streaming.py`. Allow outbound messages to be evaluated across cumulative surface states via `MessageProcessor` to reject cyclic references across multiple incremental payloads prior to transport dispatch.
Copy this prompt to implement this recommendation:
````markdown
Read the A2UI issue at https://github.com/a2ui-project/a2ui/issues/2556 and use the `a2ui-remediate-problem` skill to implement recommendation 2 described in the issue's Recommendation section.
````

3. **P1**: **Remediate Installation and Tooling Discrepancies in Readmes**
- In `renderers/web_core/README.md:L34`, replace invalid `yarn install @a2ui/web_core` with `yarn add @a2ui/web_core`. In `agent_sdks/python/a2ui_agent/README.md:L58` and `agent_sdks/python/a2ui_core/README.md:L82`, update commands to execute from repository root where workspace `pyproject.toml` resides rather than non-existent `agent_sdks/python/` workspace configs. In `renderers/angular/README.md:L42`, correct typo `A2UI_RENDER_CONFIG` to match `A2UI_RENDERER_CONFIG`.
Copy this prompt to implement this recommendation:
````markdown
Read the A2UI issue at https://github.com/a2ui-project/a2ui/issues/2556 and use the `a2ui-remediate-problem` skill to implement recommendation 3 described in the issue's Recommendation section.
````

4. **P1**: **Harden Weak Assertions in Core and Renderer Test Suites**
- Refactor shallow assertions (`assert surface is not None`, `expect(surface).toBeDefined()`, `assert comp is not None`) in `agent_sdks/python/a2ui_core/tests/test_processing.py:L79-L115`, `agent_sdks/python/a2ui_agent/tests/express/test_integration.py:L192-L220`, and `renderers/react/tests/v0_9/basic-catalog-examples.test.tsx:L63-L108`. Assert explicit component hierarchies, component property types, and specific error payloads.
Copy this prompt to implement this recommendation:
````markdown
Read the A2UI issue at https://github.com/a2ui-project/a2ui/issues/2556 and use the `a2ui-remediate-problem` skill to implement recommendation 4 described in the issue's Recommendation section.
````

5. **P2**: **Resolve Planned Status of Flutter Renderer Implementation**
- Clarify the architectural status of `renderers/flutter` in `blueprints/codebases/renderers/flutter/codebase.blueprint.md` and repository catalog documentation. Either establish an in-tree adapter bridge or document `renderers/flutter` explicitly as an external integration tracking `github.com/flutter/genui`.
Copy this prompt to implement this recommendation:
````markdown
Read the A2UI issue at https://github.com/a2ui-project/a2ui/issues/2556 and use the `a2ui-remediate-problem` skill to implement recommendation 5 described in the issue's Recommendation section.
````

6. **P2**: **Expand Boundary and Error Propagation Test Coverage**
- Introduce dedicated negative tests in `renderers/web_core/src/v0_9/processing/message-processor.test.ts` and `agent_sdks/python/a2ui_core/tests/test_processing.py` to assert graceful recovery, specific error types, and state consistency upon encountering malformed envelope messages, unmapped version strings, and deeply nested cycles (>100 depth).
Copy this prompt to implement this recommendation:
````markdown
Read the A2UI issue at https://github.com/a2ui-project/a2ui/issues/2556 and use the `a2ui-remediate-problem` skill to implement recommendation 6 described in the issue's Recommendation section.
````

## Codebase Blueprint Compliance Audit

| Codebase Implementation | Associated Module | Status | Commits Behind | Current Commit | Latest Commit |
|---|---|---|---|---|---|
| `agent_sdks/python/a2ui_agent` | `a2ui_agent` | 🟡 Out of Date | 3 | `null` | `80a45c1e` |
| `agent_sdks/python/a2ui_core` | `a2ui_core` | 🟡 Out of Date | 3 | `null` | `80a45c1e` |
| `renderers/angular` | `a2ui_framework_adapter` | 🟡 Out of Date | 1 | `null` | `a2b4c906` |
| `renderers/flutter` | `a2ui_framework_adapter` | 🟡 Out of Date | 1 | `null` | `a2b4c906` |
| `renderers/lit` | `a2ui_framework_adapter` | 🟡 Out of Date | 1 | `null` | `a2b4c906` |
| `renderers/react` | `a2ui_framework_adapter` | 🟡 Out of Date | 1 | `null` | `a2b4c906` |
| `renderers/web_core` | `a2ui_core` | 🟡 Out of Date | 3 | `null` | `80a45c1e` |
| `swift/core` | `a2ui_core` | 🟡 Out of Date | 3 | `null` | `80a45c1e` |
| `swift/swiftui` | `a2ui_framework_adapter` | 🟡 Out of Date | 1 | `null` | `a2b4c906` |

### Detailed Findings & Discrepancies

- **`agent_sdks/python/a2ui_agent`**:
- **Status & Drift**: 🟡 Out of Date. `module_blueprint_commit` is `null`. The codebase is 3 commits behind the latest module blueprint `blueprints/modules/a2ui_agent.blueprint.md` (`80a45c1eb828848a89bb59f61f781a767569892d`).
- **Missing Required Features**: Missing integration of pre-send surface state cycle verification using `MessageProcessor` as defined in `blueprints/modules/a2ui_agent.blueprint.md:L338-L345` (introduced in commit `80a45c1e`). Current validation in `A2uiValidator` checks individual payloads in isolation without accumulating state across multi-turn messages.
- **Feature Claims Verification**: Frontmatter lists `implemented_features: []`. The codebase actually implements Express format, Elemental format, Direct JSON format, streaming JSON parsing, and ADK toolset extensions, none of which are recorded in the blueprint frontmatter.
- **Missing Commits**:
- `80a45c1e`: `[dart] Extend a2ui_core for agent SDKs, limited to protocol v0.9 (#2439)`
- `920b9f76`: `refactor: move conformance test suites to root and organize by domain (#2250)`
- `72fd6b3b`: `Update a2ui_agent blueprint with refined APIs (#1990)`

- **`agent_sdks/python/a2ui_core`**:
- **Status & Drift**: 🟡 Out of Date. `module_blueprint_commit` is `null`. The codebase is 3 commits behind `blueprints/modules/a2ui_core.blueprint.md` (`80a45c1eb828848a89bb59f61f781a767569892d`).
- **Missing Required Features**: Missing explicit cross-language glossary linking conformance specified in commit `80a45c1e`.
- **Feature Claims Verification**: Frontmatter lists `implemented_features: []`. The codebase implements `Signal` reactivity, `SurfaceGroupModel`, `SurfaceModel`, `ComponentNode`, JSON Pointer resolution, and `A2uiValidator`, all missing from the frontmatter claims.
- **Missing Commits**:
- `80a45c1e`: `[dart] Extend a2ui_core for agent SDKs, limited to protocol v0.9 (#2439)`
- `1510d5c4`: `Update a2ui-core blueprint (#1991)`
- `a2b4c906`: `feat: introduce Spec-Driven Development (SDD) blueprints, skills, and codebase metadata (#1768)`

- **`renderers/angular`**:
- **Status & Drift**: 🟡 Out of Date. `module_blueprint_commit` is `null`. 1 commit behind `blueprints/modules/a2ui_framework_adapter.blueprint.md` (`a2b4c90622fee9ad1f07ee1e4c3c73d905c36381`).
- **Missing Required Features**: Fully implements the v0.9 framework adapter architecture using Angular Signals, but lacks formal frontmatter synchronization with the SDD module blueprint.
- **Feature Claims Verification**: Frontmatter lists `implemented_features: []`. Implemented features (`SurfaceComponent`, `ComponentHostComponent`, `A2uiRendererService`, `BasicCatalog`) are unrecorded in frontmatter.
- **Missing Commits**:
- `a2b4c906`: `feat: introduce Spec-Driven Development (SDD) blueprints, skills, and codebase metadata (#1768)`

- **`renderers/flutter`**:
- **Status & Drift**: 🟡 Out of Date. `module_blueprint_commit` is `null`. 1 commit behind `blueprints/modules/a2ui_framework_adapter.blueprint.md` (`a2b4c90622fee9ad1f07ee1e4c3c73d905c36381`).
- **Missing Required Features**: The codebase has zero implementation files in the repository (only an informational `README.md` pointing to `https://github.com/flutter/genui`). All framework adapter interfaces defined in `a2ui_framework_adapter.blueprint.md` are unimplemented within the local repository.
- **Feature Claims Verification**: Frontmatter lists `implemented_features: []`, which accurately reflects the lack of local code, but blueprint title is marked `(Planned)`.
- **Missing Commits**:
- `a2b4c906`: `feat: introduce Spec-Driven Development (SDD) blueprints, skills, and codebase metadata (#1768)`

- **`renderers/lit`**:
- **Status & Drift**: 🟡 Out of Date. `module_blueprint_commit` is `null`. 1 commit behind `blueprints/modules/a2ui_framework_adapter.blueprint.md` (`a2b4c90622fee9ad1f07ee1e4c3c73d905c36381`).
- **Missing Required Features**: Implements Lit Web Component adapter layer with Preact signal binding. Missing frontmatter tracking.
- **Feature Claims Verification**: Frontmatter lists `implemented_features: []`. Implemented features (`A2uiSurface`, `A2uiLitElement`, `basicCatalog`, custom component controller binding) are unrecorded in frontmatter.
- **Missing Commits**:
- `a2b4c906`: `feat: introduce Spec-Driven Development (SDD) blueprints, skills, and codebase metadata (#1768)`

- **`renderers/react`**:
- **Status & Drift**: 🟡 Out of Date. `module_blueprint_commit` is `null`. 1 commit behind `blueprints/modules/a2ui_framework_adapter.blueprint.md` (`a2b4c90622fee9ad1f07ee1e4c3c73d905c36381`).
- **Missing Required Features**: Implements React renderer hooks and Generic Binder middleware. Missing frontmatter tracking.
- **Feature Claims Verification**: Frontmatter lists `implemented_features: []`. Implemented features (`A2uiSurface`, `createComponentImplementation`, `createBinderlessComponentImplementation`, two-way binding setters) are unrecorded.
- **Missing Commits**:
- `a2b4c906`: `feat: introduce Spec-Driven Development (SDD) blueprints, skills, and codebase metadata (#1768)`

- **`renderers/web_core`**:
- **Status & Drift**: 🟡 Out of Date. `module_blueprint_commit` is `null`. 3 commits behind `blueprints/modules/a2ui_core.blueprint.md` (`80a45c1eb828848a89bb59f61f781a767569892d`).
- **Missing Required Features**: The reference TypeScript core implementation implements `SurfaceGroupModel`, `MessageProcessor`, `GenericBinder`, and `@preact/signals-core` state models, but has not pinned its blueprint commit.
- **Feature Claims Verification**: Frontmatter lists `implemented_features: []`. Implemented capabilities (Signals reactivity, JSON pointer resolution, universal web components catalog, Zod schema validation) are unrecorded.
- **Missing Commits**:
- `80a45c1e`: `[dart] Extend a2ui_core for agent SDKs, limited to protocol v0.9 (#2439)`
- `1510d5c4`: `Update a2ui-core blueprint (#1991)`
- `a2b4c906`: `feat: introduce Spec-Driven Development (SDD) blueprints, skills, and codebase metadata (#1768)`

- **`swift/core`**:
- **Status & Drift**: 🟡 Out of Date. `module_blueprint_commit` is `null`. 3 commits behind `blueprints/modules/a2ui_core.blueprint.md` (`80a45c1eb828848a89bb59f61f781a767569892d`).
- **Missing Required Features**: Implements `A2UICore`, `A2UIJSON` (Draft 2020-12), and `BasicCatalog`. Needs formal pin to core blueprint commit `80a45c1e`.
- **Feature Claims Verification**: Frontmatter lists `implemented_features: []`. Native Swift state models, pointer auto-vivification, and schema resolution are implemented but omitted from frontmatter.
- **Missing Commits**:
- `80a45c1e`: `[dart] Extend a2ui_core for agent SDKs, limited to protocol v0.9 (#2439)`
- `1510d5c4`: `Update a2ui-core blueprint (#1991)`
- `a2b4c906`: `feat: introduce Spec-Driven Development (SDD) blueprints, skills, and codebase metadata (#1768)`

- **`swift/swiftui`**:
- **Status & Drift**: 🟡 Out of Date. `module_blueprint_commit` is `null`. 1 commit behind `blueprints/modules/a2ui_framework_adapter.blueprint.md` (`a2b4c90622fee9ad1f07ee1e4c3c73d905c36381`).
- **Missing Required Features**: Native SwiftUI view mapping (`Surface`, `ComponentNodeView`, `BasicCatalogSwiftUI`) implemented; frontmatter unpinned.
- **Feature Claims Verification**: Frontmatter lists `implemented_features: []`. Implemented native views for Basic Catalog components (`A2UIText`, `A2UIButton`, etc.) are unrecorded.
- **Missing Commits**:
- `a2b4c906`: `feat: introduce Spec-Driven Development (SDD) blueprints, skills, and codebase metadata (#1768)`

## Code & Documentation Sync Audit

| Directory | Status | Identified Issues |
|---|---|---|
| `renderers/web_core` | 🔴 Out of Sync | Invalid package manager command (`yarn install @a2ui/web_core`) in `README.md:L34`. |
| `agent_sdks/python/a2ui_agent` | 🟡 Out of Sync | Outdated relative execution directory for formatting commands in `README.md:L58`. |
| `agent_sdks/python/a2ui_core` | 🟡 Out of Sync | Non-existent workspace path specified for `uv sync` setup in `README.md:L82`. |
| `renderers/angular` | 🟡 Out of Sync | Typographical mismatch in config injection token name in `README.md:L42`. |
| `renderers/flutter` | 🟡 Out of Sync | Readme documents external SDK without clarifying absence of in-tree renderer code. |
| `renderers/react` | 🟢 In Sync | Comprehensive v0.8 vs v0.9 documentation, correct setup and Vitest test commands. |
| `renderers/lit` | 🟢 In Sync | Clear quickstart, migration guide, and valid NPM/Yarn setup commands. |
| `swift/core` | 🟢 In Sync | Accurate SPM targets, Package.swift alignment, and valid `swift test` commands. |
| `swift/swiftui` | 🟢 In Sync | Valid code examples and accurate test filters matching `Package.swift`. |

### Detailed Findings

- **README Mismatches**:
- `renderers/web_core/README.md:L34`: The installation snippet instructs `yarn install @a2ui/web_core`. In Yarn (v1 and modern Berry), `yarn install` does not take package arguments; the correct command is `yarn add @a2ui/web_core`.
- `agent_sdks/python/a2ui_agent/README.md:L58`: Instructs running `uv run pyink .` from `agent_sdks/python`. There is no `pyproject.toml` in `agent_sdks/python/`; the workspace configuration resides at the repository root `/pyproject.toml`.
- `agent_sdks/python/a2ui_core/README.md:L82`: Instructs running `uv sync` from `agent_sdks/python` to synchronize the virtual environment. Running from `agent_sdks/python` fails because the workspace root is at `/`.
- `renderers/angular/README.md:L42`: Documentation refers to `A2UI_RENDER_CONFIG` in text ("Configure the renderer in your `app.config.ts` using the `A2UI_RENDER_CONFIG` injection token"), whereas the code example and exported symbol in `src/v0_9/index.ts` is `A2UI_RENDERER_CONFIG`.
- `renderers/flutter/README.md:L1-L10`: Readme describes `genui` and `genui_a2a` as the official renderer, but does not clarify that no framework adapter implementation files exist in `renderers/flutter/` within the repository.

- **Docstring / API Drift**:
- `agent_sdks/python/a2ui_agent/src/a2ui/a2a/parts.py:L180-L192`: `stream_response_to_parts` docstring contains formatting drift where `Yields:` is misaligned relative to the standard Google docstring parser.
- `renderers/web_core/src/v0_9/catalog/types.ts:L45-L60`: Docstring refers to `catalogId` as an absolute URI in legacy commentary, whereas `a2ui_framework_adapter.blueprint.md` and `a2ui_core.blueprint.md` explicitly updated the specification contract to define `catalogId` as an arbitrary string identifier.

## Test Quality & Assertions Audit

| Suite / Module | Status | Observations |
|---|---|---|
| `agent_sdks/python/a2ui_core/tests` | 🟡 Weak Assertions | 15 occurrences of shallow `assert ... is not None` on model structures. |
| `agent_sdks/python/a2ui_agent/tests` | 🟡 Weak Assertions | 16 occurrences of non-null checks in `express`, `elemental`, and `test_formats.py`. |
| `renderers/react/tests` | 🟡 Weak Assertions | 14 occurrences of `expect(...).toBeDefined()` or `toBeTruthy()` across test cases. |
| `renderers/lit/a2ui_explorer/tests` | 🟡 Weak Assertions | 11 occurrences of `.toBeTruthy()` on rendered DOM elements without attribute checks. |
| `renderers/web_core/src/v0_9/` | 🟢 Robust Assertions | Thorough assertions on signals, nodes, data context bindings, and expressions. |
| `swift/core/Tests` | 🟢 Robust Assertions | Precise `XCTAssertEqual` checks on schema validation errors and JSON pointers. |
| `swift/swiftui/Tests` | 🟢 Robust Assertions | Full component view hierarchy verification using SwiftUI test fixtures. |
| `conformance/tests` | 🟢 Robust Assertions | High-quality behavioral assertions validating cross-platform YAML test cases. |

### Detailed Findings

- **Weak Assertions**:
- `agent_sdks/python/a2ui_core/tests/test_processing.py:L79`: `assert surface is not None` — verifies surface existence after `CreateSurface` message without asserting that `surface.surface_id == "surface_1"` or checking associated `catalog_id`.
- `agent_sdks/python/a2ui_core/tests/test_processing.py:L102`: `assert surface is not None` — weak check following surface creation.
- `agent_sdks/python/a2ui_core/tests/test_processing.py:L115`: `assert comp is not None` — verifies component retrieval without validating component type, properties dictionary, or bound state.
- `agent_sdks/python/a2ui_agent/tests/express/test_integration.py:L192, L200, L220`: `self.assertIsNotNone(expected_msg)` — asserts that a compiled message object exists, but fails to check message envelope action names, parameters, or schema compliance.
- `agent_sdks/python/a2ui_agent/tests/elemental/test_integration.py:L70, L94, L110`: `self.assertIsNotNone(parts[0].a2ui_json)` — only validates that the output string is non-empty, bypassing validation against the A2UI message JSON schema.
- `agent_sdks/python/a2ui_agent/tests/test_formats.py:L88, L107`: `assert parsed[0].a2ui_json is not None` — weak truthiness check omitting AST schema validation.
- `renderers/react/tests/v0_8/integration/actions.test.tsx:L59, L100`: `expect(event.userAction).toBeDefined()` — passes on any defined object without asserting the specific action identifier or payload properties.
- `renderers/react/tests/v0_9/basic-catalog-examples.test.tsx:L63`: `expect(surface).toBeDefined()` and `L72: expect(container.firstChild).toBeTruthy()` — asserts element presence without verifying rendered component class or attributes.
- `renderers/lit/a2ui_explorer/tests/v0_9/29_movie-card.test.ts:L52, L71, L74`: `expect(img).toBeTruthy()`, `expect(modal).toBeTruthy()`, `expect(video).toBeTruthy()` — checks that elements exist in the DOM without checking source URLs, layout classes, or visibility state.

- **Missing Edge Case Tests**:
- `renderers/web_core/src/v0_9/processing/message-processor.ts`: Lacks dedicated unit tests verifying system behavior when duplicate `CreateSurface` messages with identical `surfaceId` are processed concurrently, or when messages arrive with unparseable version identifiers.
- `agent_sdks/python/a2ui_core/src/a2ui/core/validating/validator.py`: Lacks test cases covering recursion depth overflows exceeding 100 levels of nested component references.
- `agent_sdks/python/a2ui_agent/src/a2ui/parser/streaming.py`: Needs boundary tests for stream disconnections occurring in the middle of multi-byte UTF-8 sequences and unescaped quote literals inside JSON string values.