Weekly A2UI Compliance Report (2026-09-01)

## Summary

This report delivers the comprehensive weekly compliance audit across the A2UI repository, evaluating specification adherence, codebase blueprint synchronization, documentation accuracy, and test assertion rigor. The audit encompasses all platform implementations across Python SDKs (`a2ui_agent`, `a2ui_core`), web renderers (`renderers/web_core`, `renderers/react`, `renderers/angular`, `renderers/lit`, `renderers/flutter`), and native Apple SDKs (`swift/core`, `swift/swiftui`).

Across all 9 codebase blueprints, every implementation is currently unpinned (`module_blueprint_commit: null`) and lists an empty feature catalog (`implemented_features: []`), indicating that codebase-to-specification baselines must be established and tracked. Furthermore, documentation drift was identified in package installation commands, missing component property documentation, and stubbed directories.

Test suite analysis identified significant reliance on weak assertions—specifically `assert x is not None`, `expect(x).toBeTruthy()`, and `#expect(x != nil)`—which verify memory allocation or object existence rather than functional correctness, state mutation schemas, or payload integrity. Addressing these prioritized recommendations will establish robust baseline traceability and prevent regression across the multi-platform ecosystem.

## Recommendations

1. **P0**: **Pin Module Blueprint Commits and Populate Implemented Features across All Codebases**
- Update frontmatter metadata across all codebase blueprints in `blueprints/codebases/` (`agent_sdks/python/a2ui_agent`, `agent_sdks/python/a2ui_core`, `renderers/angular`, `renderers/flutter`, `renderers/lit`, `renderers/react`, `renderers/web_core`, `swift/core`, and `swift/swiftui`). Pin each `module_blueprint_commit` to the latest commit hash and enumerate all currently implemented features in `implemented_features` to restore automated compliance tracking.
Copy this prompt to implement this recommendation:
````markdown
Read the A2UI issue at https://github.com/a2ui-project/a2ui/issues/2470 and use the `a2ui-remediate-problem` skill to implement recommendation 1 described in the issue's Recommendation section.
````

2. **P1**: **Fix Invalid Setup and Installation Commands in `renderers/web_core/README.md`**
- Correct the package installation command in `renderers/web_core/README.md` from `yarn install @a2ui/web_core` to `yarn add @a2ui/web_core`. Ensure all package references and CLI invocation instructions accurately reflect the workspace Yarn Berry configuration.
Copy this prompt to implement this recommendation:
````markdown
Read the A2UI issue at https://github.com/a2ui-project/a2ui/issues/2470 and use the `a2ui-remediate-problem` skill to implement recommendation 2 described in the issue's Recommendation section.
````

3. **P1**: **Strengthen Weak Assertions in `agent_sdks/python/a2ui_core` Processing Tests**
- Refactor unit tests in `agent_sdks/python/a2ui_core/tests/test_processing.py` (lines 79, 102, 115, 140, 157, 386, 388, 466, 468, 514, 516, 578, 580, 660, 662) and `test_components.py:L193`. Replace generic `assert surface is not None` and `assert comp is not None` checks with deep assertions verifying component models, property keys, data bindings, and mutated state values.
Copy this prompt to implement this recommendation:
````markdown
Read the A2UI issue at https://github.com/a2ui-project/a2ui/issues/2470 and use the `a2ui-remediate-problem` skill to implement recommendation 3 described in the issue's Recommendation section.
````

4. **P1**: **Upgrade Swift Test Suites from Existence Checks to Structural Property Validations**
- Modernize test assertions across `swift/core/Tests/A2UICoreTests/` (`CatalogTests.swift:L170-L229`, `MessageProcessorTests.swift:L585-L622`, `SurfaceViewModelTests.swift:L197-L902`) and `swift/swiftui/Tests/A2UISwiftUITests/` (`A2UIAudioPlayerTests.swift:L77`, `A2UIChoicePickerTests.swift:L108`, `A2UIListTests.swift:L79`, `A2UIVideoTests.swift:L64`). Replace `#expect(... != nil)` with validations inspecting schema definitions, child node counts, and resolved view attributes.
Copy this prompt to implement this recommendation:
````markdown
Read the A2UI issue at https://github.com/a2ui-project/a2ui/issues/2470 and use the `a2ui-remediate-problem` skill to implement recommendation 4 described in the issue's Recommendation section.
````

5. **P2**: **Resolve Weak Truthy DOM Assertions in Angular and React Renderer Tests**
- Strengthen component tests in `renderers/angular/a2ui_explorer/src/app/tests/` (`00_simple-login-form.spec.ts:L52`, `00_interactive-button.spec.ts:L41`, `05_product-card.spec.ts:L45`, `02_email-compose.spec.ts:L55`) and React renderer test suites. Replace generic `expect(btn).toBeTruthy()` with assertions verifying DOM attributes (such as `disabled`, `aria-label`), text content, and event dispatch payloads upon user interaction.
Copy this prompt to implement this recommendation:
````markdown
Read the A2UI issue at https://github.com/a2ui-project/a2ui/issues/2470 and use the `a2ui-remediate-problem` skill to implement recommendation 5 described in the issue's Recommendation section.
````

6. **P2**: **Reconcile Flutter Renderer Placeholder Architecture with Active Dart Codebases**
- Align `renderers/flutter/README.md` and `blueprints/codebases/renderers/flutter/codebase.blueprint.md` with the active Dart implementations in `dart/a2ui_agent` and `dart/a2ui_core`, or clearly document the external delegation boundary to `github.com/flutter/genui` and define integration test recipes.
Copy this prompt to implement this recommendation:
````markdown
Read the A2UI issue at https://github.com/a2ui-project/a2ui/issues/2470 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 | 1 | `null` | `584204f2` |
| `agent_sdks/python/a2ui_core` | `a2ui_core` | 🟡 Out of Date | 1 | `null` | `584204f2` |
| `renderers/angular` | `a2ui_framework_adapter` | 🟡 Out of Date | 1 | `null` | `584204f2` |
| `renderers/flutter` | `a2ui_framework_adapter` | 🟡 Out of Date | 1 | `null` | `584204f2` |
| `renderers/lit` | `a2ui_framework_adapter` | 🟡 Out of Date | 1 | `null` | `584204f2` |
| `renderers/react` | `a2ui_framework_adapter` | 🟡 Out of Date | 1 | `null` | `584204f2` |
| `renderers/web_core` | `a2ui_core` | 🟡 Out of Date | 1 | `null` | `584204f2` |
| `swift/core` | `a2ui_core` | 🟡 Out of Date | 1 | `null` | `584204f2` |
| `swift/swiftui` | `a2ui_framework_adapter` | 🟡 Out of Date | 1 | `null` | `584204f2` |

### Detailed Findings & Discrepancies

- **`agent_sdks/python/a2ui_agent`**: Codebase blueprint has `module_blueprint_commit: null` and empty `implemented_features: []`. The codebase implements multi-catalog capability negotiation, inference format strategies (Direct JSON, Atom, Elemental, Express), and token stream parsers, but lacks specification commit pinning against `blueprints/modules/a2ui_agent.blueprint.md`.
- **`agent_sdks/python/a2ui_core`**: Codebase blueprint has `module_blueprint_commit: null` and `implemented_features: []`. Implements the core state machine, reactive signals, Pydantic message models, and JSON pointer auto-vivification, but is unpinned against `blueprints/modules/a2ui_core.blueprint.md`.
- **`renderers/angular`**: Codebase blueprint has `module_blueprint_commit: null` and `implemented_features: []`. Adapter provides Angular signal bindings and hierarchical DI context propagation for v0.8 and v0.9 specifications, but is unpinned against `blueprints/modules/a2ui_framework_adapter.blueprint.md`.
- **`renderers/flutter`**: Codebase blueprint has `module_blueprint_commit: null` and `implemented_features: []`. The directory is currently a placeholder pointing to external `github.com/flutter/genui`, leaving local development commands (`flutter test`, `flutter analyze`) non-executable in-tree.
- **`renderers/lit`**: Codebase blueprint has `module_blueprint_commit: null` and `implemented_features: []`. Implements Web Components adapters wrapping Preact signals with shadow DOM boundaries, but is unpinned against `blueprints/modules/a2ui_framework_adapter.blueprint.md`.
- **`renderers/react`**: Codebase blueprint has `module_blueprint_commit: null` and `implemented_features: []`. Reference React renderer with hook-based signal bridges and hierarchical context providers is unpinned against `blueprints/modules/a2ui_framework_adapter.blueprint.md`.
- **`renderers/web_core`**: Codebase blueprint has `module_blueprint_commit: null` and `implemented_features: []`. Reference TypeScript core layer with `@preact/signals-core` state machines and Zod schema validation is unpinned against `blueprints/modules/a2ui_core.blueprint.md`.
- **`swift/core`**: Codebase blueprint has `module_blueprint_commit: null` and `implemented_features: []`. Native Swift state engine and JSON Schema 2020-12 evaluator are unpinned against `blueprints/modules/a2ui_core.blueprint.md`.
- **`swift/swiftui`**: Codebase blueprint has `module_blueprint_commit: null` and `implemented_features: []`. SwiftUI declarative renderer for Basic Catalog components is unpinned against `blueprints/modules/a2ui_framework_adapter.blueprint.md`.

## Code & Documentation Sync Audit

| Directory | Status | Identified Issues |
|---|---|---|
| `agent_sdks/python/a2ui_agent` | 🟡 Needs Review | Missing docstring parameter and return type specifications in inference format parsers; unpinned spec references. |
| `agent_sdks/python/a2ui_core` | 🟡 Needs Review | Inline docstrings in `a2ui/core/processing` reference legacy message schemas without clarifying v0.8 vs v0.9 branching. |
| `renderers/angular` | 🟡 Needs Review | Component documentation in `renderers/angular/README.md` lacks guidance on standalone Angular signal integration. |
| `renderers/flutter` | 🔴 Incomplete | `renderers/flutter/README.md` is a 10-line stub pointing externally, while Dart SDK implementations reside in `dart/`. |
| `renderers/lit` | 🟡 Needs Review | JSDoc missing for reactive controller properties and shadow DOM encapsulation options. |
| `renderers/react` | 🟡 Needs Review | Custom hooks in `src/v0_9/` lack complete JSDoc parameter and return documentation; visual parity runner doc drift. |
| `renderers/web_core` | 🔴 Outdated Commands | `renderers/web_core/README.md:L16` contains invalid `yarn install @a2ui/web_core` instruction. |
| `swift/core` | 🟡 Needs Review | README test filter instructions omit individual schema validation suites (`A2UIJSONTests`). |
| `swift/swiftui` | 🟡 Needs Review | Component builder protocol docstrings missing in `A2UISwiftUI` source files; theme environment overrides undocumented. |

### Detailed Findings

- **README Mismatches**:
- `renderers/web_core/README.md:L16`: Uses invalid installation command `yarn install @a2ui/web_core`. In Yarn workspaces / Yarn Berry, adding a package must use `yarn add @a2ui/web_core`.
- `renderers/flutter/README.md`: Lists external packages (`genui`, `genui_a2a`) but provides no documentation or build recipes for the in-repository codebase or its relation to `dart/a2ui_core` and `dart/a2ui_agent`.
- `swift/core/README.md:L42`: Test command specifies `swift test --filter A2UICoreTests --filter A2UIJSONTests --filter BasicCatalogTests`, which omits recent schema regression suites.

- **Docstring / API Drift**:
- `agent_sdks/python/a2ui_agent/src/a2ui/agent/generator.py:L24-L58`: Method docstrings for `A2uiGenerator.generate_stream` omit description of `progressive_keys` auto-healing behavior and capability negotiation hash caching.
- `agent_sdks/python/a2ui_core/src/a2ui/core/processing/processor.py:L35-L70`: `MessageProcessor.process_message` docstring does not document the runtime behavior and exception types (`A2uiValidationError`) raised on malformed JSON Pointer paths during auto-vivification.
- `renderers/react/src/v0_9/hooks/useA2uiBinding.ts:L12-L30`: Hook docstring does not explain subscription cleanup lifecycle or default value fallback semantics for unbound pointer paths.

## Test Quality & Assertions Audit

| Suite / Module | Status | Observations |
|---|---|---|
| `agent_sdks/python/a2ui_agent` | 🟡 Needs Review | Weak assertions in ADK toolset tests (`test_send_a2ui_to_client_toolset.py`) and stream parser length assertions. |
| `agent_sdks/python/a2ui_core` | 🔴 Weak Assertions | Over 15 instances of generic `assert surface is not None` / `assert comp is not None` in `test_processing.py`. |
| `renderers/angular` | 🟡 Needs Review | Explorer E2E and unit specs rely on `expect(btn).toBeTruthy()` rather than verifying event emissions or rendered content. |
| `renderers/flutter` | 🔴 Missing Tests | No test suite implemented in `renderers/flutter`. |
| `renderers/lit` | 🟡 Needs Review | Component lifecycle tests verify element rendering without asserting dispatched custom event payloads. |
| `renderers/react` | 🟡 Needs Review | DOM component tests in `tests/v0_8/components/button.test.tsx` assert element presence without testing click handlers. |
| `renderers/web_core` | 🟡 Needs Review | Data binding test suites lack boundary test cases for circular JSON pointer references and invalid schema types. |
| `swift/core` | 🟡 Weak Assertions | Over 25 weak `#expect(... != nil)` assertions across `CatalogTests.swift` and `MessageProcessorTests.swift`. |
| `swift/swiftui` | 🟡 Weak Assertions | Component tests in `A2UISwiftUITests` assert view creation (`#expect(rendered != nil)`) without validating view hierarchy. |

### Detailed Findings

- **Weak Assertions**:
- `agent_sdks/python/a2ui_core/tests/test_processing.py:L79, L102, L115, L140, L157, L386, L466, L514, L578, L660`: Repeated use of `assert surface is not None` and `assert comp is not None` without checking specific component IDs, type discriminators, bound values, or child hierarchies.
- `agent_sdks/python/a2ui_core/tests/test_components.py:L193`: Uses `assert schema is not None` instead of validating schema structure, properties map, or required fields.
- `agent_sdks/python/a2ui_agent/tests/adk/test_send_a2ui_to_client_toolset.py:L131`: `assert declaration is not None` tests only toolset declaration existence without validating function parameter schemas or return bindings.
- `agent_sdks/python/a2ui_agent/tests/parser/test_streaming_v08.py:L302`: `assert len(messages) > 0` tests only non-empty output rather than asserting exact message types (`CreateSurface`, `UpdateComponents`) or payload structure.
- `renderers/angular/a2ui_explorer/src/app/tests/v0_8/00_simple-login-form.spec.ts:L52`: `expect(btn).toBeTruthy()` checks that a DOM node exists, but does not verify button label text, disabled state, or submit event trigger.
- `renderers/angular/a2ui_explorer/src/app/agent-stub.service.spec.ts:L58`: `expect(service).toBeTruthy()` is an empty smoke assertion testing service instantiation only.
- `swift/core/Tests/A2UICoreTests/CatalogTests.swift:L170, L172, L199, L210, L229`: Uses `#expect(catalog.components["Button"] != nil)` and `#expect(catalog.themeSchema != nil)` without asserting schema rules or component property contracts.
- `swift/core/Tests/A2UICoreTests/MessageProcessorTests.swift:L585, L622`: Uses `#expect(dataModel["s1"]?.objectValue != nil)` and `#expect(textComponent.objectValue != nil)` instead of validating the underlying dictionary keys and bound text values.
- `swift/swiftui/Tests/A2UISwiftUITests/A2UIAudioPlayerTests.swift:L77`: `#expect(rendered != nil)` only verifies view struct instantiation without verifying playback state binding or controls configuration.
- `swift/swiftui/Tests/A2UISwiftUITests/A2UIChoicePickerTests.swift:L108`: `#expect(rendered != nil)` checks view existence without asserting that choice options, selections, or filterable flags are properly reflected in the SwiftUI hierarchy.

- **Missing Edge Case Tests**:
- `agent_sdks/python/a2ui_core/tests/`: Missing boundary tests for deeply nested circular JSON pointer paths and malformed JSON patch operations in `MessageProcessor`.
- `renderers/web_core/tests/`: Missing test coverage for handling malformed or mismatched data types bound to typed component properties (e.g. string bound to boolean input).
- `swift/core/Tests/A2UICoreTests/`: Missing error propagation tests when message sequence contains invalid surface IDs or undefined component templates.