feat(web_core): v1.0 Zod schemas, version adapters, and composition constraints (Firing-TS)

[gspencergoog]

Summary

This pull request implements Stage 2 (Firing-TS) of the A2UI v1.0 specification upgrade for typescript/web_core. It introduces automated spec-driven Zod schema generation for v1.0 protocol messages and capabilities payloads (RendererCapabilities), a multi-version adapter infrastructure (VersionAdapterFactory) supporting strictly isolated protocol versions (v0.8, v0.9, v0.9.1, v1.0), specification-to-code function parity verification, Closure Compiler externs for Angular framework integration, and encapsulated surface state management.

---

Stack Context

• 🥞 PR 1 (This PR - Base of Stack): #2257 (v1_0_firing_ts) — Core v1.0 Zod schemas, strict version adapters, system function scoping, spec-driven RendererCapabilitiesSchema, and conformance test runner enhancements.
• 🥞 PR 2 (Stacked on top): #2264 (v1_0_sauce_ts) — Bidirectional RPC execution (callRendererFunction, callAgentFunction), dynamic ValidationResult handling, multi-catalog resolution engine, and @index loop function.

---

Changes

1. Spec-Driven Zod Schemas & Code Generation (typescript/web_core/src/v1_0/schema/)

• Created scripts/generate-zod-schemas.mjs to parse JSON specification blueprints into strongly typed TypeScript Zod schemas.
• Generated agent-to-renderer.ts, renderer-to-agent.ts, common-types.ts, and renderer-capabilities.ts.
• Auto-generated V10RendererCapabilitiesSchema and RendererCapabilitiesSchema directly from specification/v1_0/json/renderer_capabilities.json.
• Added comprehensive schema verification unit tests in src/v1_0/schema/verify-schema.test.ts.

2. Strict Version Adapter Infrastructure & Dependency Injection (typescript/web_core/src/processing/)

• Created ProtocolVersion open union ('v0.8' | 'v0.9' | 'v0.9.1' | 'v1.0' | (string & {})) in src/processing/adapters/base.ts to support version discovery and custom versions.
• Implemented V0_8VersionAdapter, V0_9VersionAdapter, and V1_0VersionAdapter to transform incoming wire payloads into native InternalOperation primitives.
• Restricted V0_8VersionAdapter strictly to native v0.8 message action names (beginRendering, surfaceUpdate, dataModelUpdate, deleteSurface).
• Omitting legacy top-level theme property extraction in V1_0VersionAdapter to match spec v1.0 changes.
• Enhanced VersionAdapterFactory with registerAdapter() for dynamic adapter registration, and added adapterRegistry?: VersionAdapterResolver to MessageProcessorOptions for dependency injection.

3. System Functions Scoping & Specification Parity (typescript/web_core/src/)

• Relocated @index (IndexApi) out of src/v0_9/basic_catalog and created src/v1_0/functions/system_functions.ts re-exported from src/v1_0/index.ts.
• Exported V09_SPEC_FUNCTION_APIS and added a spec parity unit test in basic_functions.test.ts to ensure exported v0.9 basic catalog functions match specification/v0_9/catalogs/basic/catalog.json.

4. Closure Compiler Externs & Build Integration

• Added Angular framework property retention externs (angular_framework.externs.js) to protect inputs object keys in Closure Compiler release builds.
• Added Web Core externs (a2ui_web_core_v0_9.externs.js) and explorer externs.

5. Conformance Harness & Test Vectors (typescript/web_core/tests/conformance/)

• Updated conformance_test.mjs to actively execute process_messages test cases via validateProcessMessagesTestCase() with dynamic catalog loading and protocol version header propagation.
• Enforced strict action handler coverage in conformance_test.mjs to throw on unhandled action types.
• Added cross-version negative boundary test vectors in conformance/core/message_processor.yaml.

---

Impact & Risks

• Impact: Enables typescript/web_core to validate and process v1.0 protocol messages alongside legacy v0.8 and v0.9 payloads while providing clean, encapsulated state accessors and customizable version adapter dependency injection. Serves as the base PR for stacked PR #2264.
• Risks: Low. All changes preserve existing v0.8 and v0.9 processing behavior without breaking changes.

---

Testing

• Unit Tests: Executed yarn test in typescript/web_core — 291/291 passing tests (100%).
• Conformance Suite: Executed node tests/conformance/conformance_test.mjs — 205/205 passing test vectors (100%).
• Static Analysis & Formatting: Verified clean formatting via ./scripts/fix_format.sh and zero build/extern errors.

[gspencergoog]

Okay, PTAL: I think I fixed the issues, and I added some more conformance and unit tests to catch these things.

[nan-yu]

Should we verify if the payload conforms to the v0_8 A2uiMessageSchema, A2uiMessageSchema.safeParse(payload);?

[gspencergoog]

No, because if it fails later, it will have more specific error information that the LLM can use to fix things. If it fails here, it would just be a generic "parse failure" with no detailed information. But it will fail later, because later we do parse it, so there's no chance that something will slip through.

[nan-yu]

because later we do parse it,

We only parse components and functions later. If a v1.0 payload has a theme property, it will get passed to the processor without any issues. But if we do AgentToRendererMessage.safeParse(payload) in the v1.0 adapter, it will recognize theme as an invalid property. With the formatZodIssue, it should have the issue details for LLM.

[gspencergoog]

Ahh, good point. Okay, added safeParse to the adapters and refactored them to put the initial parsing into a base class for adapters.

[nan-yu]

v1.0 changes the returnType of required, regex, length, numeric, email from "boolean" to "validationResult". We need to maintain a copy of these functions in v1.0 for these changes.

[gspencergoog]

Thanks! Okay, I separated out the required API for 1.0, and had it generate the Zod types for the ValidationResult type from the catalog_definition.json file.