@adia-ai/a2ui 0.8.37

package/validate/README.md

@@ -0,0 +1,146 @@
+# `@adia-ai/a2ui/validate`
+
+> Formerly the `@adia-ai/a2ui-validator` package; renamed at ADR-0048 P3,
+> which moved the protocol-side half here as a subpath of `@adia-ai/a2ui`.
+> The catalog-aware validator and the LLM semantic judge moved the other way
+> in P1 — they are now `@adia-ai/gen-ui/validate/catalog` and
+> `@adia-ai/gen-ui/validate/semantic`. Sections below that describe those two
+> stages are history, kept for the record.
+
+JSON Schema structural validation for A2UI (Agent-to-UI) protocol messages —
+shape, types, required fields, and wiring/registry coherence. Its only import
+is this package's own registry, which is what lets `@adia-ai/a2ui` ship with
+zero dependencies. Originally extracted from
+[`@adia-ai/a2ui-compose`](../../gen-ui/compose/) so non-compose tooling
+(tests, MCP validator tools, CI gates) could depend on validation without
+pulling the full generator graph.
+
+## Install
+
+```bash
+npm install @adia-ai/a2ui-validator
+```
+
+## Usage
+
+```js
+import { validateSchema } from '@adia-ai/a2ui-validator';
+
+const messages = [/* A2UI protocol messages */];
+const result = validateSchema(messages);
+if (!result.valid) {
+  console.error(result.errors);
+}
+```
+
+Catalog-aware validation (component exists + props match YAML):
+
+```js
+import { validateAgainstCatalog } from '@adia-ai/a2ui-validator/catalog';
+
+const result = validateAgainstCatalog(messages, catalog);
+```
+
+## What's here
+
+- **Structural validator** — JSON Schema validation against the A2UI
+  protocol schema (message shape, required fields, enum constraints).
+- **Catalog validator** — semantic checks: does this component exist in
+  the catalog? Do its props match the YAML contract? Are references
+  resolvable?
+- **Semantic validator** (optional, shadow-mode) — LLM-judged output
+  quality against a rubric; cached on disk by content hash.
+
+## Catalog loading + degradation (gh#742, gh#748)
+
+The catalog validator needs the v0.9 component catalog. **First try is the bare
+specifier `@adia-ai/a2ui-corpus`** — that package's `.` export IS
+`catalog-a2ui_0_9.json`, and it is a declared dependency of this package, so a
+plain `npm i @adia-ai/a2ui-validator` install resolves it with no repo layout,
+no static asset server and no bundler config (gh#748: before this, every
+tarball consumer validated in degraded mode, because all three fallbacks below
+resolve `../corpus/...` relative to this module and only work through workspace
+symlinks). On Node, a `createRequire(...).resolve()` + `fs.readFile` retry
+covers runtimes that reject JSON import attributes (`source: 'package-fs'`).
+
+The relative-path chain stays as the in-repo / browser fallback. Node reads it
+from disk; the browser **fetches** it module-relative
+(`fetch(new URL('../corpus/catalog-a2ui_0_9.json', import.meta.url))`) — the
+same idiom as `retrieval/catalog.js` and `compose/strategies/monolithic/_shared.js`.
+A spec-correct `import(..., { with: { type: 'json' } })` cannot be the primary
+path: Vite's dev server serves JSON as `text/javascript` and the browser's
+strict MIME check rejects it, so under `npm run dev` that import always throws.
+It remains a second try for bundlers that inline the JSON.
+
+If every path fails, the validator degrades **loudly**: one `console.warn` per
+session naming the lost coverage, plus queryable state —
+
+```js
+import { getCatalogStatus } from '@adia-ai/a2ui-validator/catalog';
+
+getCatalogStatus();  // { loaded, degraded, source: 'package'|'package-fs'|'node-fs'|'fetch'|'import-attributes'|null, reason }
+globalThis.__a2uiValidatorCatalogStatus;  // same object, for a dev console / host overlay
+```
+
+`validateMessages()` also returns `catalogDegraded`. When it is `true`, a green
+`valid` means nothing was structurally checked — absence of evidence, not
+evidence of absence.
+
+## The 18 weighted checks
+
+`validator.js` runs 18 weighted checks that sum to 100. Default pass
+threshold is `valid: score ≥ 70`. The compose eval harness uses
+`combined: 0.6 × validation + 0.4 × semantic` at threshold 80, so a
+high structural score with low semantic still gets rejected at
+compose time.
+
+| Check | Weight | What it catches |
+|---|---:|---|
+| `intentAlignment` | 13 | Output addresses the intent (LLM-free heuristic) |
+| `allTypesRegistered` | 9 | Every `component` value exists in the runtime registry |
+| `noOrphanedChildren` | 9 | Every `children` ID resolves to a real node |
+| `validMessageFormat` | 8 | Top-level shape is valid A2UI |
+| `hasRootComponent` | 7 | Exactly one root |
+| `noBareDivs` | 7 | Use semantic primitives (`<card-ui>`, `<col-ui>`) not bare `<div>` |
+| `cardStructure` | 6 | Card pattern: header / body / footer hierarchy |
+| `flatAdjacency` | 5 | Component IDs are flat (no nested arrays) |
+| `noInlineLayout` | 5 | Use `<col-ui>` / `<row-ui>` / `<grid-ui>` not inline `style="display:flex"` |
+| `textContentSet` | 5 | Text components have actual content |
+| `idUniqueness` | 5 | No duplicate IDs |
+| `interactiveHasLabel` | 4 | Buttons / inputs have accessible labels |
+| `imagesHaveAlt` | 3 | `<img>` has `alt` attribute |
+| `headingHierarchy` | 3 | `h1` → `h2` → `h3` monotonic |
+| `gridVsColumn` | 3 | Right primitive for the layout |
+| `landmarkStructure` | 3 | Page-level `main` / `nav` / `footer` |
+| `noHardcodedColors` | 3 | Token contract — `--a-chrome-*` only |
+| `tabStructure` | 2 | `<tabs-ui>` has `<tab-ui>` children |
+| **Total** | **100** | |
+
+**Wiring checks** are tracked separately (don't roll into the component
+score) and sum to 13: `wiringControllersExist` (3), `wiringHostsExist`
+(3), `wiringHandlersExist` (3), `wiringSourcesExist` (2),
+`wiringDataPathsValid` (2).
+
+## Status
+
+- **Structural + catalog validation** — shipped, default-on. Single
+  source of truth for component-shape contracts in A2UI messages.
+- **Semantic validator (Phases 1 + 2)** — shipped. LLM-judge with
+  `dominantPattern` (0.5 weight) + `requiredCapabilities` (0.35) +
+  `forbiddenNoise` (0.15). Combined-gating opt-in via
+  `--gate-mode combined` to the eval harness.
+- **Phases 3–5** — planned per [`semantic-validator.md`](../../../.claude/docs/specs/semantic-validator.md):
+  rubric expansion, persisted per-intent thresholds, and judge
+  ensembling.
+
+## Runtime
+
+- `ajv` + `ajv-formats` for structural validation.
+- `@adia-ai/a2ui-runtime` for the registry shape.
+
+## Related
+
+- Spec: [`.claude/docs/specs/semantic-validator.md`](../../../.claude/docs/specs/semantic-validator.md) — canonical design narrative
+- Audit: `.claude/docs/reports/audit-validator-2026-05-06.md` — 226-line deep-dive with check-by-check rationale + recalibration notes
+- Repo: [`adiahealth/gen-ui-kit`](https://github.com/adiahealth/gen-ui-kit)
+- CHANGELOG: [`CHANGELOG.md`](./CHANGELOG.md)

package/validate/index.d.ts

@@ -0,0 +1,4 @@
+// v0.5.21 hotfix stub — TS-migration Phase 1 (568bb998d) declared this
+// types: export but Phase 2 hasn't generated real declarations yet.
+// Replace with real type declarations when Phase 2 lands.
+export {};

package/validate/index.js

@@ -0,0 +1,12 @@
+/**
+ * @adia-ai/a2ui/validate — barrel.
+ *
+ * Structural validation for A2UI protocol messages — `validateSchema`
+ * (shape, types, required fields, wiring/registry coherence).
+ *
+ * Catalog-aware validation (`validateMessages`) and the LLM semantic judge
+ * moved to @adia-ai/gen-ui in ADR-0048 P1: import them from
+ * `@adia-ai/gen-ui/validate/catalog` and `@adia-ai/gen-ui/validate/semantic`.
+ */
+
+export * from './validator.js';

package/validate/validator.d.ts

@@ -0,0 +1,4 @@
+// v0.5.21 hotfix stub — TS-migration Phase 1 (568bb998d) declared this
+// types: export but Phase 2 hasn't generated real declarations yet.
+// Replace with real type declarations when Phase 2 lands.
+export {};