Weekly A2UI Compliance Report (2026-08-18)

## Summary

This comprehensive weekly compliance audit evaluates the synchronization, architectural integrity, documentation parity, and test quality across the entire A2UI repository. The audit scope encompasses all 8 production codebases: the Python Agent SDK (`agent_sdks/python/a2ui_agent`), Python Core SDK (`agent_sdks/python/a2ui_core`), Web Core runtime (`renderers/web_core`), Apple Swift Core runtime (`swift/core`), and framework renderers across Angular (`renderers/angular`), React (`renderers/react`), Lit (`renderers/lit`), and Flutter (`renderers/flutter`). In addition, documentation hierarchies under `docs/` and `specification/`, as well as test suites across Python, TypeScript, and Swift, were analyzed.

The audit identified three primary categories of discrepancies. First, in **Blueprint Compliance**, all 8 production codebase blueprints remain unpinned (`module_blueprint_commit: null`) and lack populated `implemented_features` declarations despite extensive concrete feature implementations across multiple inference formats, reactive signal models, and multi-version protocol branching. Second, in **Documentation & Code Synchronization**, several high-impact documentation drifts were uncovered, including obsolete scaffolding CLI commands (`npx create-ag-ui-app@latest` in `docs/public/guides/a2ui-with-any-agent-framework.md`), invalid package management commands (`yarn install @a2ui/web_core` in `renderers/web_core/README.md`), injection token typos (`A2UI_RENDER_CONFIG` vs `A2UI_RENDERER_CONFIG` in `renderers/angular/README.md`), and lingering references to the deprecated `callableFrom` property rather than the standardized `allowedCallers` spec enum. Third, in **Test Quality & Assertions**, test suites in Python, React, Lit, and Swift heavily rely on weak existence assertions (such as `assert is not None`, `expect().toBeDefined()`, and `#expect(... != nil)`) rather than validating payload schemas, boundary values, or recursive tree topology.

Addressing these findings will solidify specification conformance across all client rendering adapters and server-side agent SDKs, eliminate onboarding friction caused by outdated setup commands, and prevent silent regressions in core protocol message processing.

## Recommendations

1. **P0**: Baseline and pin all 8 codebase blueprints (`blueprints/codebases/**/codebase.blueprint.md`) to the latest module blueprint commit hashes (`920b9f764fc8cc25e25e1ec1b050795189665f90` for `a2ui_agent`, `1510d5c42c4d8a365209ef27c6643a15b18c58bf` for `a2ui_core`, and `a2b4c90622fee9ad1f07ee1e4c3c73d905c36381` for `a2ui_framework_adapter`) and populate their `implemented_features` lists.
2. **P1**: Correct documentation drift in `docs/public/guides/a2ui-with-any-agent-framework.md:L57-L65` (replacing legacy `create-ag-ui-app` with current scaffolding commands) and update `specification/proposals/user_initiated_functions.md:L117` to use `allowedCallers` instead of `callableFrom`.
3. **P1**: Fix README command inaccuracies across renderers, specifically fixing `yarn install @a2ui/web_core` to `yarn add @a2ui/web_core` in `renderers/web_core/README.md:L12`, correcting `A2UI_RENDER_CONFIG` to `A2UI_RENDERER_CONFIG` in `renderers/angular/README.md:L31`, and fixing shell code block formatting in `agent_sdks/python/a2ui_core/README.md:L25-L65`.
4. **P2**: Reconcile docstring parameter mismatches in `agent_sdks/python/a2ui_agent/src/a2ui/parser/parser.py:L27-L90` and its concrete format parser subclasses (`atom/parser.py:L57`, `elemental/parser.py:L44`, `express/parser.py:L49`) where `complete` and `is_final` arguments diverged from method signatures.
5. **P2**: Strengthen weak assertions across test suites by replacing superficial existence checks (`assert is not None`, `expect().toBeDefined()`, `#expect(... != nil)`) in `agent_sdks/python/a2ui_core/tests/test_processing.py`, `agent_sdks/python/a2ui_agent/tests/test_specification_roundtrip.py`, `renderers/react/tests/v0_9/catalog-components.test.tsx`, and `swift/core/Tests/A2UICoreTests/MessageProcessorTests.swift` with deep schema and state mutation assertions.
6. **P3**: Add dedicated edge case tests for malformed streaming chunk boundaries, recursive JSON pointer resolution errors, and component unmount race conditions across Python, React, and Swift runtimes.

> 🤖 **Automated Remediation**: Comment `/fix ` (e.g., `/fix 1`) on this issue to have an agent create a draft PR for that recommendation.

## Codebase Blueprint Compliance Audit

| Codebase Implementation | Associated Module | Status | Commits Behind | Current Commit | Latest Commit |
| ----------------------- | ----------------- | ------ | -------------- | -------------- | ------------- |
| `agent_sdks/python/a2ui_agent` | `a2ui_agent` | 🔴 Not Baselined | 2 | `None` | `920b9f76` |
| `agent_sdks/python/a2ui_core` | `a2ui_core` | 🔴 Not Baselined | 2 | `None` | `1510d5c4` |
| `renderers/angular` | `a2ui_framework_adapter` | 🔴 Not Baselined | 1 | `None` | `a2b4c906` |
| `renderers/flutter` | `a2ui_framework_adapter` | 🔴 Not Baselined | 1 | `None` | `a2b4c906` |
| `renderers/lit` | `a2ui_framework_adapter` | 🔴 Not Baselined | 1 | `None` | `a2b4c906` |
| `renderers/react` | `a2ui_framework_adapter` | 🔴 Not Baselined | 1 | `None` | `a2b4c906` |
| `renderers/web_core` | `a2ui_core` | 🔴 Not Baselined | 2 | `None` | `1510d5c4` |
| `swift/core` | `a2ui_core` | 🔴 Not Baselined | 2 | `None` | `1510d5c4` |

### Detailed Findings & Discrepancies

- **`agent_sdks/python/a2ui_agent`**:
- Frontmatter `module_blueprint_commit` is set to `null`, causing the codebase to be unbaselined and 2 commits behind latest `blueprints/modules/a2ui_agent.blueprint.md` (`920b9f76` and `72fd6b3b`).
- `implemented_features` is declared as empty (`[]`), failing to document active implementations of DirectJson (`inference_formats/direct_json`), Express (`inference_formats/experimental/express`), Atom (`inference_formats/experimental/atom`), Elemental (`inference_formats/experimental/elemental`), ADK converters (`a2ui/adk`), and File Resolution extensions (`a2ui/extensions/file_resolve`).
- **`agent_sdks/python/a2ui_core`**:
- Frontmatter `module_blueprint_commit` is set to `null`, lagging 2 commits behind `blueprints/modules/a2ui_core.blueprint.md` (`1510d5c4` and `a2b4c906`).
- Module blueprint specifies validation namespace `a2ui.core.validation`, but codebase implements the module under `a2ui.core.validating` (`a2ui_core/src/a2ui/core/validating/`).
- `implemented_features` is empty (`[]`) despite full implementation of `MessageProcessor`, `SurfaceModel`, `DataModel`, `Signal`, and `BasicCatalog`.
- **`renderers/angular`**:
- Frontmatter `module_blueprint_commit` is set to `null`, lagging 1 commit behind `blueprints/modules/a2ui_framework_adapter.blueprint.md` (`a2b4c906`).
- `implemented_features` is empty (`[]`) despite production implementation of Angular v0.8 and v0.9 basic catalog components, `A2uiRendererService`, `ComponentHostComponent`, and `SurfaceComponent`.
- **`renderers/flutter`**:
- Frontmatter `module_blueprint_commit` is set to `null`, lagging 1 commit behind `blueprints/modules/a2ui_framework_adapter.blueprint.md` (`a2b4c906`).
- The codebase directory only contains a stub `README.md` referencing the external `genui` and `genui_a2a` packages on pub.dev. No in-repo rendering implementation or local development configuration exists.
- **`renderers/lit`**:
- Frontmatter `module_blueprint_commit` is set to `null`, lagging 1 commit behind `blueprints/modules/a2ui_framework_adapter.blueprint.md` (`a2b4c906`).
- `implemented_features` is empty (`[]`) despite full implementation of `A2uiLitElement`, v0.8/v0.9 component implementations, and the interactive `@a2ui/lit-explorer`.
- **`renderers/react`**:
- Frontmatter `module_blueprint_commit` is set to `null`, lagging 1 commit behind `blueprints/modules/a2ui_framework_adapter.blueprint.md` (`a2b4c906`).
- `implemented_features` is empty (`[]`) despite comprehensive implementations of the Generic Binder middleware (`createComponentImplementation`), v0.8/v0.9 catalog components, and the `@a2ui/react-explorer`.
- **`renderers/web_core`**:
- Frontmatter `module_blueprint_commit` is set to `null`, lagging 2 commits behind `blueprints/modules/a2ui_core.blueprint.md` (`1510d5c4` and `a2b4c906`).
- `implemented_features` is empty (`[]`) despite complete implementations of `MessageProcessor`, `SurfaceModel`, `DataModel`, `Signal`, schema validators, and multi-version protocol branching (v0.8, v0.9, v0.9.1, v1.0).
- **`swift/core`**:
- Frontmatter `module_blueprint_commit` is set to `null`, lagging 2 commits behind `blueprints/modules/a2ui_core.blueprint.md` (`1510d5c4` and `a2b4c906`).
- `swift/core` lacks a localized `README.md` and has unpopulated `implemented_features`, despite implementing `A2UICore`, `A2UIJSON`, and `BasicCatalog` (including `DataContext`, reactive graph, and standard function APIs).

## Code & Documentation Sync Audit

| Directory | Status | Identified Issues |
| --------- | ------ | ----------------- |
| `agent_sdks/python/a2ui_agent` | 🟡 Drift Detected | Docstring parameter mismatches across parser methods |
| `agent_sdks/python/a2ui_core` | 🟡 Drift Detected | Shell formatting in README and obsolete catalog class names |
| `renderers/angular` | 🟡 Drift Detected | Injection token mismatch (`A2UI_RENDER_CONFIG` vs `A2UI_RENDERER_CONFIG`) |
| `renderers/flutter` | 🟡 Drift Detected | External SDK pointer with missing in-repo implementation details |
| `renderers/lit` | 🟢 In Sync | README and API exports align with `@a2ui/lit` v0.9 |
| `renderers/react` | 🟢 In Sync | README accurately details v0.8 to v0.9 migration and Generic Binder |
| `renderers/web_core` | 🟡 Drift Detected | Invalid package installation command in README |
| `swift/core` | 🟡 Drift Detected | Missing localized `README.md` in `swift/core` directory |
| `docs/public` | 🟡 Drift Detected | Obsolete CLI scaffolding commands (`create-ag-ui-app`) |
| `specification` | 🟡 Drift Detected | Lingering `callableFrom` reference in proposal docs |

### Detailed Findings

- **README Mismatches**:
- `renderers/web_core/README.md:L12`: README instructs running `yarn install @a2ui/web_core`. In Yarn, `yarn install` does not take package arguments; the command should be `yarn add @a2ui/web_core` or bare `yarn install`.
- `renderers/angular/README.md:L31`: Setup guide instructs configuring `app.config.ts` using `A2UI_RENDER_CONFIG`, but line 35 and the source code export `A2UI_RENDERER_CONFIG` (`renderers/angular/src/v0_9/core/a2ui-renderer.service.ts:L54`).
- `agent_sdks/python/a2ui_core/README.md:L25-L65`: Feature architecture list is erroneously enclosed in bash code blocks (```` ```bash - **Signal**: ... ````) and references deprecated `JsonCatalog` and `ModelCatalog` classes rather than the consolidated `Catalog` API.
- `swift/core`: No `README.md` exists within `swift/core/`; documentation is located exclusively at the top-level `swift/README.md`.
- `docs/public/guides/a2ui-with-any-agent-framework.md:L57-L65`: Documents `npx create-ag-ui-app@latest` instead of the updated package branding.
- **Docstring / API Drift**:
- `agent_sdks/python/a2ui_agent/src/a2ui/parser/parser.py:L27-L35`: Docstring for `Parser.has_format_content` documents `complete: If True...` parameter, but base method signature in abstract class was defined as `def has_format_content(self, content: str, *, complete: bool = False) -> bool:`, causing parameter documentation drift with older implementations.
- `agent_sdks/python/a2ui_agent/src/a2ui/parser/parser.py:L81-L90`: Docstring for `Parser.compile` documents parameter `is_final`, but docstring text does not match all subclass invocations in `experimental/express/parser.py:L49`.
- `specification/proposals/user_initiated_functions.md:L117`: Proposal document references `callableFrom: "rendererOrAgent"`, which was renamed in the v1.0 specification (commit `29b715fa`) to `allowedCallers`.

## Test Quality & Assertions Audit

| Suite / Module | Status | Observations |
| -------------- | ------ | ------------ |
| `agent_sdks/python/a2ui_agent/tests` | 🟡 Needs Improvement | Roundtrip and streaming tests rely on truthiness and non-empty length checks |
| `agent_sdks/python/a2ui_core/tests` | 🟡 Needs Improvement | Core processing and node graph tests rely heavily on `assert ... is not None` |
| `renderers/angular/src/v0_9` | 🟢 Good | Comprehensive component and service unit tests with DOM query assertions |
| `renderers/lit` | 🟢 Good | Comprehensive visual and behavioral test coverage across components |
| `renderers/react/tests` | 🟡 Needs Improvement | Integration scenarios rely on `toBeDefined()` and non-null query checks |
| `renderers/web_core/test` | 🟢 Good | Robust schema validation and message processor assertion checks |
| `swift/core/Tests` | 🟡 Needs Improvement | Message processor and catalog test suites rely on `#expect(... != nil)` |

### Detailed Findings

- **Weak Assertions**:
- `agent_sdks/python/a2ui_agent/tests/test_specification_roundtrip.py:L123, L133, L143`: Uses `assert recompiled is not None` following decompile/compile cycles without asserting equality of message opcodes or payload contents.
- `agent_sdks/python/a2ui_agent/tests/test_prompt_examples.py:L134`: Uses `assert parsed is not None` on Atom example outputs without verifying the structure of compiled component nodes.
- `agent_sdks/python/a2ui_agent/tests/parser/test_streaming_v08.py:L302` & `test_streaming_v09.py:L417`: Uses `assert len(messages) > 0` rather than asserting the exact expected message sequence and envelope properties.
- `agent_sdks/python/a2ui_core/tests/test_processing.py:L79, L102, L115, L140, L157, L386, L466, L514, L578, L660`: Excessive reliance on `assert surface is not None` and `assert comp is not None` without checking component property maps, bound models, or catalog schemas.
- `agent_sdks/python/a2ui_core/tests/test_node_graph.py:L75, L129, L155, L180, L221, L270, L321, L360, L383, L428, L581, L616`: Contains 12 separate instances of `assert root_node is not None` and `assert node_graph.rootNode.value is not None` without validating the topology or children IDs of the resulting graph.
- `renderers/react/tests/v0_9/catalog-components.test.tsx:L70, L110`: `expect(h1).not.toBeNull()` and `expect(view.container.querySelector(...)).not.toBeNull()` check element presence without asserting text content or styling classes.
- `renderers/react/tests/v0_9/integration-scenarios.test.tsx:L33, L49, L66, L75`: Uses `expect(surface).toBeDefined()` and `expect(emailInput).toBeDefined()` without asserting rendered form inputs or event listeners.
- `renderers/react/tests/v0_8/integration/actions.test.tsx:L59, L100, L102, L156, L162, L216`: Uses `expect(event.userAction).toBeDefined()` without asserting action name, context payload, or target component ID.
- `renderers/lit/a2ui_explorer/tests/smoke-test.spec.ts:L36-L37`: `expect(mod.LocalGallery).toBeDefined()` and `expect(customElements.get('local-gallery')).toBeDefined()` are basic registration checks without asserting component rendering.
- `swift/core/Tests/A2UICoreTests/CatalogTests.swift:L170, L172, L199, L210, L229`: Uses `#expect(catalog.components["Button"] != nil)` and `#expect(result != nil)` without checking component metadata or function evaluation outputs.
- `swift/core/Tests/A2UICoreTests/MessageProcessorTests.swift:L127, L163, L164, L199, L326, L327, L351`: Uses `#expect(surface != nil)` and `#expect(processor.surfaceGroupModel.surfacesMap["s1"] != nil)` without validating child node counts or surface theme configurations.
- `swift/core/Tests/A2UICoreTests/SurfaceViewModelTests.swift:L125, L427, L428, L441, L462, L463, L511, L675`: Multiple instances of `#expect(surface.componentsModel.get(...) != nil)` without checking component properties.
- **Missing Edge Case Tests**:
- `agent_sdks/python/a2ui_agent/src/a2ui/parser/lexer.py`: Missing tests for corrupted or truncated `` boundary tags during high-latency streaming splits.
- `agent_sdks/python/a2ui_core/src/a2ui/core/state/data_model.py`: Missing unit tests for invalid relative JSON pointer navigation (e.g., navigating above root with `/../../property`).
- `agent_sdks/python/a2ui_core/src/a2ui/core/state/node_graph.py`: Missing tests for handling circular parent-child references in dynamic component updates.
- `renderers/react/src/v0_9/core/ComponentHost.tsx`: Missing test cases for concurrent unmounting during active generic binder state subscription updates.
- `swift/core/Sources/A2UICore/Rendering/DataContext.swift`: Missing test coverage for invalid arithmetic/logical types passed to dynamic function expressions.