Weekly A2UI Compliance Report (2026-08-11)

## Summary

A comprehensive compliance audit of the A2UI repository was conducted on August 11, 2026, covering:
1. **Codebase Blueprint Compliance**: Synchronization status of 8 platform codebases against language-agnostic module blueprints (`a2ui_agent`, `a2ui_core`, `a2ui_framework_adapter`).
2. **Code & Documentation Synchronization**: Alignment between user documentation (`docs/`, `specification/`), codebase `README.md` files, public APIs, and inline docstrings.
3. **Test Quality & Assertions**: Robustness of test suites, identification of weak assertions (`is not None`, `toBeTruthy`, `toBeDefined`), empty/no-assertion test cases, boundary coverage, and mock parameter verification.

All 8 codebase blueprints are currently marked **Out of Date** (`module_blueprint_commit: null`) and require updates to reflect recent specification commits (`72fd6b3b` and `1510d5c4`). Significant implementation gaps were identified in `agent_sdks/python/a2ui_agent` (missing `processor/` application facade and `express` DSL format) and `renderers/flutter` (stub codebase lacking local Dart packages). Multiple weak assertions and documentation path discrepancies were logged across platforms.

---

## Codebase Blueprint Compliance Audit

### Summary Status Table

| Codebase Implementation | Associated Module | Status | Commits Behind | Current Commit | Latest Commit |
|---|---|---|---|---|---|
| `agent_sdks/python/a2ui_agent` | `a2ui_agent` | 🟡 Out of Date | 1 | `null` | `72fd6b3b` |
| `agent_sdks/python/a2ui_core` | `a2ui_core` | 🟡 Out of Date | 2 | `null` | `1510d5c4` |
| `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 | 2 | `null` | `1510d5c4` |
| `swift/core` | `a2ui_core` | 🟡 Out of Date | 2 | `null` | `1510d5c4` |

---

### Detailed Findings by Codebase

#### 📦 `agent_sdks/python/a2ui_agent`
- **Module**: `a2ui_agent`
- **Current Pinned Commit**: `null` | **Latest Module Commit**: `72fd6b3bd203602814d5cff9b6f85f157ab4e7fa`
- **Missing Required Features**:
- `processor/` package: `A2uiGenerator`, `A2uiRequestProcessor`, `CatalogConfig`, `CatalogProvider` (`BundledCatalogProvider`, `FileSystemCatalogProvider`, `InMemoryCatalogProvider`) are not implemented.
- `inference_formats/express`: Express DSL compiler, decompiler, and parser package are missing.
- `catalog_transformers`: `ComponentPruningTransformer` and `FunctionPruningTransformer` rules are missing.
- `resolve_catalogs`: Capability negotiation utility in `a2ui.utils` is missing.
- **Feature Claims Verification / Discrepancies**:
- Blueprint `implemented_features` is empty (`[]`). Codebase contains legacy `InferenceStrategy`, `A2uiSchemaManager`, and `DirectJsonStreamParser` implementation.
- **Implemented Optional Features**:
- Google ADK integration adapters (`src/a2ui/adk`) and A2A transport wrappers (`src/a2ui/a2a`).
- **Missing Commits / Spec Diffs**:
- `72fd6b3b`: Update a2ui_agent blueprint with refined APIs (#1990)

#### 📦 `agent_sdks/python/a2ui_core`
- **Module**: `a2ui_core`
- **Current Pinned Commit**: `null` | **Latest Module Commit**: `1510d5c42c4d8a365209ef27c6643a15b18c58bf`
- **Missing Required Features**:
- `resolution/` package: Decoupled `ComponentNode` and `NodeGraph` view tree resolution engines are partially integrated into state rather than exposed as standalone resolution modules.
- **Feature Claims Verification / Discrepancies**:
- Blueprint `implemented_features` is empty (`[]`).
- **Implemented Optional Features**:
- `SurfaceGroupModel`, `SurfaceModel`, `DataModel`, `MessageProcessor`, `A2uiValidator`, and `formatString` expression resolution.
- **Missing Commits / Spec Diffs**:
- `1510d5c4`: Update a2ui-core blueprint (#1991)
- `a2b4c906`: Introduce Spec-Driven Development (SDD) blueprints, skills, and codebase metadata (#1768)

#### 📦 `renderers/angular`
- **Module**: `a2ui_framework_adapter`
- **Current Pinned Commit**: `null` | **Latest Module Commit**: `a2b4c90622fee9ad1f07ee1e4c3c73d905c36381`
- **Missing Required Features**:
- Full v1.0 spec adapter compliance and `surfaceProperties` handling in Angular component renderers.
- **Feature Claims Verification / Discrepancies**:
- Blueprint `implemented_features` is empty (`[]`).
- **Implemented Optional Features**:
- Angular Signals bridge and `a2ui_explorer` demo harness.

#### 📦 `renderers/flutter`
- **Module**: `a2ui_framework_adapter`
- **Current Pinned Commit**: `null` | **Latest Module Commit**: `a2b4c90622fee9ad1f07ee1e4c3c73d905c36381`
- **Missing Required Features**:
- Entire codebase is a stub; no local Dart files or `pubspec.yaml` exist in `renderers/flutter`.
- **Feature Claims Verification / Discrepancies**:
- Blueprint lists `flutter test` and `flutter analyze` local development commands, but commands fail due to missing package setup.

#### 📦 `renderers/lit`
- **Module**: `a2ui_framework_adapter`
- **Current Pinned Commit**: `null` | **Latest Module Commit**: `a2b4c90622fee9ad1f07ee1e4c3c73d905c36381`
- **Missing Required Features**:
- Extended theme schema bindings for custom component catalogs.
- **Feature Claims Verification / Discrepancies**:
- Blueprint `implemented_features` is empty (`[]`).
- **Implemented Optional Features**:
- `@preact/signals-core` reactive signals integration with Lit Web Components.

#### 📦 `renderers/react`
- **Module**: `a2ui_framework_adapter`
- **Current Pinned Commit**: `null` | **Latest Module Commit**: `a2b4c90622fee9ad1f07ee1e4c3c73d905c36381`
- **Missing Required Features**:
- Express DSL client-side parser preview integration.
- **Feature Claims Verification / Discrepancies**:
- Blueprint `implemented_features` is empty (`[]`).
- **Implemented Optional Features**:
- `@preact/signals-react` hook bindings and visual parity test suite.

#### 📦 `renderers/web_core`
- **Module**: `a2ui_core`
- **Current Pinned Commit**: `null` | **Latest Module Commit**: `1510d5c42c4d8a365209ef27c6643a15b18c58bf`
- **Missing Required Features**:
- Fully synchronized standalone schema generator for v1.0 `A2uiRendererCapabilities`.
- **Feature Claims Verification / Discrepancies**:
- Blueprint `implemented_features` is empty (`[]`).
- **Implemented Optional Features**:
- Reference TypeScript `MessageProcessor`, `VersionAdapterFactory` (`v0_8`, `v0_9`, `v1_0`), `NodeGraph`, and `ComponentNode`.

#### 📦 `swift/core`
- **Module**: `a2ui_core`
- **Current Pinned Commit**: `null` | **Latest Module Commit**: `1510d5c42c4d8a365209ef27c6643a15b18c58bf`
- **Missing Required Features**:
- `VersionAdapterFactory` multi-version branching for v1.0 `surfaceProperties` payload transformation.
- **Feature Claims Verification / Discrepancies**:
- `swift/core/README.md` is missing from the directory. Blueprint lists lint command `./scripts/fix_format.sh`, but script is at repo root (`/a2ui/scripts/fix_format.sh`).

---

## Code & Documentation Sync Audit

### Audited Directories Table

| Directory | Primary Config / Manifest | README Status | API & Docs Synchronization Status |
|---|---|---|---|
| `agent_sdks/python/a2ui_agent` | `pyproject.toml` | Present | ⚠️ Outdated API references (`a2ui_inference`, `InferenceStrategy`) |
| `agent_sdks/python/a2ui_core` | `pyproject.toml` | Present | ✅ Synchronized |
| `renderers/angular` | `package.json` | Present | ✅ Synchronized |
| `renderers/flutter` | *Missing (`pubspec.yaml`)* | Present | ❌ External link only; no local implementation |
| `renderers/lit` | `package.json` | Present | ✅ Synchronized |
| `renderers/react` | `package.json` | Present | ✅ Synchronized |
| `renderers/web_core` | `package.json` | Present | ✅ Synchronized |
| `swift/core` | `Package.swift` (at root) | ❌ Missing | ⚠️ Missing local README.md; invalid local script path |

---

### Key Documentation Drift & Readme Findings

1. **Python Agent SDK API Drift (`agent_sdks/python/a2ui_agent/README.md`)**:
- The README documents `A2uiSchemaManager`, `DirectJsonStreamParser`, and `InferenceStrategy`.
- The updated specification (`blueprints/modules/a2ui_agent.blueprint.md`) deprecates these in favor of `A2uiGenerator`, `A2uiRequestProcessor`, `CatalogConfig`, and `InferenceFormat` strategy facades.

2. **Missing README in Swift Core (`swift/core/`)**:
- `swift/core` contains `AGENTS.md` and `CODING_STANDARDS.md`, but no `README.md`.
- The codebase blueprint (`blueprints/codebases/swift/core/codebase.blueprint.md`) specifies `./scripts/fix_format.sh` for linting, but there is no `scripts` directory inside `swift/core`. The script exists at the repository root (`/a2ui/scripts/fix_format.sh`).

3. **Flutter Renderer Stub (`renderers/flutter/`)**:
- `renderers/flutter/README.md` links to external repository `github.com/flutter/genui`.
- No local `pubspec.yaml` or Dart source files exist in `renderers/flutter/`, causing local development lint/test commands defined in the blueprint to fail.

4. **Docstring Mismatches in `a2ui_agent`**:
- Inline JSDoc / docstrings in `a2ui/agent/inference_strategy.py` reference obsolete `client_ui_capabilities` parameters rather than `A2uiRendererCapabilities`.

---

## Test Quality & Assertions Audit

### Audited Test Suites Table

| Test Suite Path | Target Platform | Total Test Files | Weak Assertions Identified | Empty / No-Assertion Tests |
|---|---|---|---|---|
| `agent_sdks/python/a2ui_agent/tests` | Python (Agent) | 12 | 4 (`assert x is not None`) | 1 (`test_catalog`) |
| `agent_sdks/python/a2ui_core/tests` | Python (Core) | 18 | 39 (`assert x is not None`) | 4 (`test_validating.py` helpers) |
| `renderers/lit/` | TypeScript (Lit) | 45 | 112 (`toBeTruthy`, `toBeDefined`) | 0 |
| `renderers/react/tests` | TypeScript (React) | 28 | 84 (`toBeTruthy`, `toBeDefined`) | 0 |
| `renderers/web_core/` | TypeScript (Web) | 32 | 86 (`toBeTruthy`, `toBeDefined`) | 0 |
| `swift/core/Tests` | Swift | 12 | 0 | 0 |

---

### Detailed Findings by Sub-Category

1. **Weak Assertions**:
- **Python**: `agent_sdks/python/a2ui_agent/tests/test_formats.py` uses `assert parsed[0].a2ui_json is not None` on lines 88 and 107. These tests verify object presence but do not validate specific fields, component IDs, or payload structure.
- **TypeScript Renderers**: 282 occurrences of `.toBeTruthy()` and 11 occurrences of `.toBeDefined()` across Lit, React, and Web Core tests (e.g. `expect(iconInnerEl).toBeTruthy()`, `expect(img).toBeTruthy()`). These verify DOM node creation without verifying rendered attribute values, text content, or reactive state subscriptions.

2. **Empty / No-Assertion Test Functions**:
- In `agent_sdks/python/a2ui_core/tests/test_validating.py`:
- `test_validate_component_integrity_valid`
- `test_validate_recursion_and_paths_valid`
- `test_a2ui_validator_validate_valid_payload`
- These test cases execute code blocks to verify that no exceptions are raised, but lack explicit assertions on return values or side effects.

3. **Boundary Coverage & Edge Cases**:
- `a2ui_agent` tests lack boundary coverage for malformed `` sentinel tags (e.g. unclosed tags, truncated streaming payloads).
- `a2ui_core` validator tests lack test cases asserting recursion depth exceeding 50 levels or cyclical component graph detection error handling.

4. **Mocking Realism**:
- Mocks in ADK event converter tests (`agent_sdks/python/a2ui_agent/tests/test_adk.py`) verify call counts (`mock.assert_called_once()`) without verifying payload parameter structure or JSON envelope contents.

---

## Recommendations

1. **Implement `processor/` package and `express` format in Python Agent SDK**: Refactor `agent_sdks/python/a2ui_agent` to implement `A2uiGenerator`, `A2uiRequestProcessor`, `CatalogConfig`, `CatalogProvider`, and `a2ui.inference_formats.express` as specified in blueprint commit `72fd6b3b`.
> 🤖 **Automated Remediation**: Comment `/remediate 1` on this issue to trigger an agent draft PR.
2. **Update codebase blueprint frontmatter and pin hashes**: Populate `implemented_features` and update `module_blueprint_commit` hashes across all 8 codebase blueprints in `blueprints/codebases/`.
> 🤖 **Automated Remediation**: Comment `/remediate 2` on this issue to trigger an agent draft PR.
3. **Add `swift/core/README.md` and fix script paths**: Create a local `README.md` for `swift/core` and update `codebase.blueprint.md` local development commands to point to the repository root `/a2ui/scripts/fix_format.sh`.
> 🤖 **Automated Remediation**: Comment `/remediate 3` on this issue to trigger an agent draft PR.
4. **Strengthen weak assertions across test suites**: Replace `is not None`, `.toBeTruthy()`, and `.toBeDefined()` with structural property comparisons and payload schema validation in Python and TypeScript test suites.
> 🤖 **Automated Remediation**: Comment `/remediate 4` on this issue to trigger an agent draft PR.
5. **Synchronize public API documentation**: Update `agent_sdks/python/a2ui_agent/README.md` and inline docstrings to match the updated `a2ui_agent` modular architecture.
> 🤖 **Automated Remediation**: Comment `/remediate 5` on this issue to trigger an agent draft PR.

This is a compliance audit report, not a task. It lists many missing features and documentation mismatches across eight codebases. To act on it, start by reading the referenced blueprints in `blueprints/modules/` and `blueprints/codebases/`. For example, update the Python agent SDK's `processor/` package per blueprint `a2ui_agent.blueprint.md`. 'Done' means the codebase passes the audit, which is a large, cross-cutting effort requiring deep familiarity with the A2UI architecture.

Scritto dal modello di indicizzazione a partire dal testo della issue.