@adia-ai/gen-ui 0.8.37

package/validate/catalog-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 {};

package/validate/catalog-validator.js

@@ -0,0 +1,327 @@
+/**
+ * Catalog-backed structural validator — checks that every emitted A2UI
+ * component conforms to its catalog schema (allOf: ComponentCommon +
+ * CatalogComponentCommon + component-specific props, with
+ * unevaluatedProperties: false so unknown props are rejected).
+ *
+ * The catalog at gen-ui/corpus/catalog-a2ui_0_9.json is a freestanding
+ * JSON Schema draft-2020-12 document produced by scripts/build-components.mjs.
+ * At first use we compile one validator per component type and cache them,
+ * then dispatch per-component by the `component` discriminator.
+ *
+ * Load order (gh#748): the `@adia-ai/gen-ui/corpus` bare specifier first — that
+ * package IS the catalog and is a declared dependency, so it resolves for a
+ * plain npm consumer — then the in-repo/browser fallbacks (fetch, JSON import
+ * attributes, node fs) against the workspace-relative path.
+ *
+ * When the catalog genuinely can't load we degrade LOUDLY — one console.warn
+ * per session naming the lost coverage — and expose the state via
+ * `getCatalogStatus()` (also mirrored on
+ * `globalThis.__a2uiValidatorCatalogStatus` so a host/dev console can read it).
+ * Per-component calls still return { valid: true, skipped: true } so the
+ * scoring validator keeps running.
+ */
+
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+
+const IS_NODE = typeof process !== 'undefined' && !!process.versions?.node;
+const CATALOG_FILE = '../corpus/catalog-a2ui_0_9.json';
+// `@adia-ai/gen-ui/corpus`'s "." export IS the catalog JSON, and this package
+// depends on it — so the bare specifier is the ONLY path that resolves for a
+// published-tarball consumer (gh#748); the relative paths below only work in
+// this repo, where workspace symlinks put corpus/ next to validator/. Held in
+// a const so bundlers see a dynamic specifier and leave resolution to runtime.
+const CORPUS_PACKAGE = '@adia-ai/gen-ui/corpus';
+
+let _catalog = null;
+let _ajv = null;
+let _validators = null;           // Map<componentName, compiledValidator>
+let _loadPromise = null;
+let _status = { loaded: false, degraded: false, source: null, reason: null };
+let _warned = false;
+
+function _publishStatus(next) {
+  _status = { ..._status, ...next };
+  try { globalThis.__a2uiValidatorCatalogStatus = _status; } catch { /* frozen global */ }
+  return _status;
+}
+
+function _warnDegraded(reason) {
+  _publishStatus({ loaded: false, degraded: true, source: null, reason });
+  if (_warned) return;
+  _warned = true;
+  console.warn(
+    '[catalog-validator] component catalog could not be loaded — ' +
+    'catalog-backed STRUCTURAL VALIDATION IS OFF for every turn in this session ' +
+    '(unknown props, wrong enums and bad component names will NOT be caught). ' +
+    `Reason: ${reason}. Read globalThis.__a2uiValidatorCatalogStatus for details.`
+  );
+}
+
+function _looksLikeCatalog(json) {
+  return !!json && typeof json === 'object' && !!json.components;
+}
+
+/**
+ * Package catalog load — the published-consumer path (gh#748).
+ *
+ * `@adia-ai/gen-ui/corpus` is a real dependency of this package and its "."
+ * export resolves straight to catalog-a2ui_0_9.json, so this works from a
+ * plain `npm i @adia-ai/a2ui-validator` install with no repo layout, no
+ * static asset server and no bundler config. Tried FIRST; the relative-path
+ * chain below stays as the in-repo / browser fallback.
+ *
+ * @param {string[]} reasons — accumulator, so a total failure reports every try
+ * @returns {Promise<{ json: object, source: 'package'|'package-fs' }|null>}
+ */
+async function _loadPackageCatalog(reasons) {
+  try {
+    const mod = await import(/* @vite-ignore */ CORPUS_PACKAGE, { with: { type: 'json' } });
+    const json = mod?.default ?? mod;
+    if (_looksLikeCatalog(json)) return { json, source: 'package' };
+    reasons.push(`${CORPUS_PACKAGE} import produced no catalog object`);
+  } catch (e) {
+    reasons.push(`${CORPUS_PACKAGE} import failed: ${e?.message || e}`);
+  }
+
+  if (!IS_NODE) return null;
+
+  // Node runtimes that reject JSON import attributes still resolve the
+  // package specifier — resolve it to a path and read the file.
+  try {
+    const { createRequire } = await import(/* @vite-ignore */ 'node:module');
+    const fs = await import(/* @vite-ignore */ 'node:fs/promises');
+    const resolved = createRequire(import.meta.url).resolve(CORPUS_PACKAGE);
+    const json = JSON.parse(await fs.readFile(resolved, 'utf8'));
+    if (_looksLikeCatalog(json)) return { json, source: 'package-fs' };
+    reasons.push(`${CORPUS_PACKAGE} resolved file is not a catalog`);
+  } catch (e) {
+    reasons.push(`${CORPUS_PACKAGE} resolve+read failed: ${e?.message || e}`);
+  }
+  return null;
+}
+
+async function _loadNodeCatalog() {
+  const fs = await import(/* @vite-ignore */ 'node:fs/promises');
+  const path = await import(/* @vite-ignore */ 'node:path');
+  const url = await import(/* @vite-ignore */ 'node:url');
+  const here = path.dirname(url.fileURLToPath(import.meta.url));
+  // gen-ui/validate → gen-ui/corpus/catalog-a2ui_0_9.json
+  const raw = await fs.readFile(path.resolve(here, CATALOG_FILE), 'utf8');
+  return JSON.parse(raw);
+}
+
+/**
+ * Browser catalog load.
+ *
+ * `import(json, { with: { type: 'json' } })` is the spec-correct form but
+ * Vite's dev server transforms JSON into a JS module served as
+ * `text/javascript`, which the browser's strict MIME check rejects — so under
+ * `npm run dev` that import ALWAYS throws. The estate's browser-JSON idiom is
+ * a plain fetch of the module-relative URL (retrieval/catalog.js,
+ * retrieval/component-catalog.js, compose/strategies/monolithic/_shared.js all
+ * do exactly this); a fetch is untouched by Vite's JSON transform and works on
+ * the static deploy too. The import-attributes path stays as a second try for
+ * bundlers that inline the JSON and serve no static asset.
+ */
+async function _loadBrowserCatalog(reasons) {
+  try {
+    const res = await fetch(new URL(CATALOG_FILE, import.meta.url));
+    if (res.ok) {
+      const json = await res.json();
+      if (json && typeof json === 'object') {
+        _publishStatus({ loaded: true, degraded: false, source: 'fetch', reason: null });
+        return json;
+      }
+      reasons.push('fetch returned non-object JSON');
+    } else {
+      reasons.push(`fetch HTTP ${res.status}`);
+    }
+  } catch (e) {
+    reasons.push(`fetch failed: ${e?.message || e}`);
+  }
+
+  try {
+    const mod = await import(/* @vite-ignore */ CATALOG_FILE, { with: { type: 'json' } });
+    const json = mod?.default ?? null;
+    if (json && typeof json === 'object') {
+      _publishStatus({ loaded: true, degraded: false, source: 'import-attributes', reason: null });
+      return json;
+    }
+    reasons.push('json import produced no default export');
+  } catch (e) {
+    reasons.push(`json import failed: ${e?.message || e}`);
+  }
+
+  _warnDegraded(reasons.join('; '));
+  return null;
+}
+
+async function _loadCatalog() {
+  if (_catalog) return _catalog;
+  if (_loadPromise) return _loadPromise;
+  _loadPromise = (async () => {
+    const reasons = [];
+    const fromPackage = await _loadPackageCatalog(reasons);
+    if (fromPackage) {
+      _catalog = fromPackage.json;
+      _publishStatus({ loaded: true, degraded: false, source: fromPackage.source, reason: null });
+      return _catalog;
+    }
+    try {
+      if (IS_NODE) {
+        _catalog = await _loadNodeCatalog();
+        _publishStatus({ loaded: true, degraded: false, source: 'node-fs', reason: null });
+      } else {
+        _catalog = await _loadBrowserCatalog(reasons);
+      }
+    } catch (e) {
+      _catalog = null;
+      reasons.push(`${IS_NODE ? 'node read' : 'browser load'} failed: ${e?.message || e}`);
+      _warnDegraded(reasons.join('; '));
+    }
+    return _catalog;
+  })();
+  return _loadPromise;
+}
+
+function _getAjv() {
+  if (_ajv) return _ajv;
+  _ajv = new Ajv2020({
+    strict: false,          // our schemas are authored, not hardened; silence warnings
+    allErrors: true,         // return every violation, not just the first
+    verbose: false,
+    allowUnionTypes: true,
+    validateFormats: false,  // formats cost compilation time and aren't strictly needed
+  });
+  addFormats(_ajv);
+  return _ajv;
+}
+
+async function _getValidatorFor(componentName) {
+  if (_validators && _validators.has(componentName)) return _validators.get(componentName);
+  const catalog = await _loadCatalog();
+  if (!catalog) return null;
+
+  if (!_validators) {
+    _validators = new Map();
+    const ajv = _getAjv();
+    // Register the catalog as a single addressable document; sub-schemas are
+    // retrieved by JSON Pointer via getSchema(). Intra-catalog `$ref`s (#/$defs/X)
+    // resolve naturally because the catalog IS the root.
+    const catalogId = catalog.$id || 'adiaui-catalog';
+    try {
+      ajv.addSchema(catalog, catalogId);
+    } catch (e) {
+      _warnDegraded(`catalog registration failed: ${e.message}`);
+      return null;
+    }
+
+    for (const name of Object.keys(catalog.components || {})) {
+      try {
+        // Get a compiled validator for the sub-schema at #/components/<name>.
+        // AJV resolves it against the already-registered catalog.
+        const validate = ajv.getSchema(`${catalogId}#/components/${name}`);
+        if (validate) _validators.set(name, validate);
+      } catch (e) {
+        console.warn(`[catalog-validator] skip ${name}: ${e.message}`);
+      }
+    }
+  }
+  return _validators.get(componentName) || null;
+}
+
+/**
+ * Validate one A2UI component object against its catalog schema.
+ *
+ * @param {object} component — A2UI component ({ id, component, ...props })
+ * @returns {Promise<{ valid: boolean, errors?: string[], skipped?: boolean }>}
+ */
+export async function validateComponent(component) {
+  if (!component || typeof component !== 'object') {
+    return { valid: false, errors: ['not an object'] };
+  }
+  const typeName = component.component;
+  if (!typeName) return { valid: false, errors: ['missing `component` discriminator'] };
+
+  const validate = await _getValidatorFor(typeName);
+  if (!validate) {
+    // Catalog missing OR component type not in catalog → structural-only fallback.
+    return { valid: true, skipped: true };
+  }
+
+  const ok = validate(component);
+  if (ok) return { valid: true };
+
+  const errors = (validate.errors || []).map(e => {
+    const path = e.instancePath || '/';
+    return `${path} ${e.message}${e.params && Object.keys(e.params).length ? ` (${JSON.stringify(e.params)})` : ''}`;
+  });
+  return { valid: false, errors };
+}
+
+/**
+ * Validate an array of A2UI messages ({ type: 'updateComponents', components: [...] }).
+ * Flattens all updateComponents.components[] across messages and runs per-component validation.
+ *
+ * `catalogDegraded: true` means the catalog never loaded and NOTHING was
+ * structurally checked — a green `valid` there is absence of evidence, not
+ * evidence of absence.
+ *
+ * @returns {Promise<{ valid: boolean, totalChecked: number, failures: Array<{ id, component, errors }>, catalogDegraded: boolean }>}
+ */
+export async function validateMessages(messages) {
+  const failures = [];
+  let totalChecked = 0;
+  await _loadCatalog();
+
+  for (const msg of messages || []) {
+    if (msg?.type !== 'updateComponents') continue;
+    for (const comp of msg.components || []) {
+      totalChecked++;
+      const { valid, errors, skipped } = await validateComponent(comp);
+      if (skipped) continue;
+      if (!valid) {
+        failures.push({
+          id: comp.id || '(no id)',
+          component: comp.component || '(no component)',
+          errors: errors || ['unknown validation failure'],
+        });
+      }
+    }
+  }
+
+  return {
+    valid: failures.length === 0,
+    totalChecked,
+    failures,
+    catalogDegraded: _status.degraded,
+  };
+}
+
+/** Diagnostics: has the catalog loaded successfully? */
+export async function isCatalogLoaded() {
+  await _loadCatalog();
+  return _catalog !== null;
+}
+
+/**
+ * Queryable load state — hosts (dev overlays, QA probes) read this to tell
+ * "validated clean" apart from "validated nothing".
+ *
+ * @returns {{ loaded: boolean, degraded: boolean, source: 'package'|'package-fs'|'node-fs'|'fetch'|'import-attributes'|null, reason: string|null }}
+ */
+export function getCatalogStatus() {
+  return { ..._status };
+}
+
+/** Test-only: drop caches so a fresh load path can be exercised. */
+export function __resetCatalogForTests() {
+  _catalog = null;
+  _ajv = null;
+  _validators = null;
+  _loadPromise = null;
+  _warned = false;
+  _publishStatus({ loaded: false, degraded: false, source: null, reason: null });
+}

package/validate/semantic/cache.js

@@ -0,0 +1,54 @@
+/**
+ * Content-hash cache for semantic verdicts.
+ *
+ * Key: (rubricVersion, intent, a2ui-hash).
+ * Store: one JSON file per key under evals/mcp/runs/.semantic-cache/.
+ *
+ * Phase 1 scope: read/write; no eviction. Bump rubricVersion to invalidate.
+ */
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const repoRoot = join(__dirname, '..', '..', '..', '..');
+const DEFAULT_DIR = join(repoRoot, 'evals', 'mcp', 'runs', '.semantic-cache');
+
+export function hashA2UI(messages) {
+  const h = createHash('sha256');
+  h.update(JSON.stringify(messages ?? []));
+  return h.digest('hex').slice(0, 16);
+}
+
+export function cacheKey({ rubricVersion, intent, messages }) {
+  const h = createHash('sha256');
+  h.update(String(rubricVersion || 'v1'));
+  h.update('\x1f');
+  h.update(String(intent || ''));
+  h.update('\x1f');
+  h.update(hashA2UI(messages));
+  return h.digest('hex').slice(0, 32);
+}
+
+export function makeCache({ dir = DEFAULT_DIR } = {}) {
+  return {
+    dir,
+    async get(key) {
+      const p = join(dir, `${key}.json`);
+      if (!existsSync(p)) return null;
+      try {
+        const raw = await readFile(p, 'utf8');
+        return JSON.parse(raw);
+      } catch {
+        return null;
+      }
+    },
+    async set(key, verdict) {
+      await mkdir(dir, { recursive: true });
+      const p = join(dir, `${key}.json`);
+      await writeFile(p, JSON.stringify(verdict, null, 2));
+    },
+  };
+}

package/validate/semantic/classify-intent.js

@@ -0,0 +1,128 @@
+/**
+ * Intent classifier — Phase 3 kickoff (semantic-validator)
+ *
+ * Spec: .claude/docs/specs/semantic-validator.md § Phase 3
+ *
+ * Two-stage classification:
+ *
+ *   1. Find the best-matching IntentSpec from the registry via regex
+ *   2. Score the emitted A2UI tree against the spec deterministically
+ *
+ * High-confidence matches (intent.confidence ≥ 0.9 AND verdict.certainty ≥ 0.9)
+ * can short-circuit the LLM judge per § 3c (hybrid).
+ *
+ * Status: kickoff — not yet wired into validateSemantics(). Use for
+ * shadow-compare runs (the test harness in classify-intent.test.js).
+ */
+
+import { findIntentSpec } from './intent-specs.js';
+
+/**
+ * Classify an intent prompt against the IntentSpec registry.
+ *
+ * @param {string} intent — natural-language prompt
+ * @returns {{ spec: IntentSpec | null, confidence: number }}
+ */
+export function classifyIntent(intent) {
+  return findIntentSpec(intent);
+}
+
+/**
+ * Score an A2UI tree against an IntentSpec deterministically.
+ *
+ * Returns a SemanticVerdict-shaped object with rule-based certainty.
+ * The caller decides whether to skip the LLM judge based on `certainty`.
+ *
+ * @param {object} a2ui — emitted A2UI tree (root object with `nodes` or
+ *                        equivalent traversable shape)
+ * @param {IntentSpec} spec — the classified IntentSpec
+ * @returns {RuleVerdict}
+ */
+export function scoreAgainstSpec(a2ui, spec) {
+  const { distinct, instances } = collectComponentTypes(a2ui);
+
+  const requiredMissing = spec.required.filter((t) => !distinct.includes(t));
+  const forbiddenPresent = spec.forbidden.filter((t) => distinct.includes(t));
+  const componentCount = instances;  // total instance count (matches existing validator semantics)
+
+  // Clean pass: all required present, no forbidden, meets minComponents
+  const cleanPass =
+    requiredMissing.length === 0 &&
+    forbiddenPresent.length === 0 &&
+    componentCount >= spec.minComponents;
+
+  // Clean fail: 2+ required missing (per spec § 3c "cleanly fails")
+  const cleanFail = requiredMissing.length >= 2;
+
+  // Certainty: 1.0 on clean pass/fail; 0.5 on partial (ambiguous)
+  let certainty = 0.5;
+  let verdict = 'partial';
+  if (cleanPass) {
+    certainty = 1.0;
+    verdict = 'pass';
+  } else if (cleanFail) {
+    certainty = 1.0;
+    verdict = 'fail';
+  }
+
+  // Build a structured findings payload — useful as hints to the LLM
+  // judge on fall-through
+  return {
+    verdict,
+    certainty,
+    score: cleanPass ? 100 : cleanFail ? 0 : 50,
+    spec: spec.id,
+    findings: {
+      required_missing: requiredMissing,
+      forbidden_present: forbiddenPresent,
+      component_count: componentCount,
+      min_components: spec.minComponents,
+    },
+  };
+}
+
+/**
+ * Walk an A2UI tree and collect (a) the set of distinct component types
+ * and (b) the total instance count. The A2UI tree shape varies — sometimes
+ * flat arrays, sometimes nested under `nodes` / `children` / `body`. This
+ * walker handles both.
+ *
+ * @param {*} node — root or nested A2UI shape
+ * @returns {{ distinct: string[], instances: number }}
+ */
+function collectComponentTypes(node) {
+  const distinct = new Set();
+  const counter = { n: 0 };
+  walk(node, distinct, counter);
+  return { distinct: Array.from(distinct), instances: counter.n };
+}
+
+function walk(node, distinct, counter) {
+  if (!node) return;
+  if (Array.isArray(node)) {
+    for (const item of node) walk(item, distinct, counter);
+    return;
+  }
+  if (typeof node !== 'object') return;
+  // Count instances + collect distinct
+  if (typeof node.component === 'string') {
+    distinct.add(node.component);
+    counter.n += 1;
+  } else if (typeof node.type === 'string') {
+    distinct.add(node.type);
+    counter.n += 1;
+  }
+  // Recurse children
+  if (node.children) walk(node.children, distinct, counter);
+  if (node.nodes) walk(node.nodes, distinct, counter);
+  if (node.body) walk(node.body, distinct, counter);
+}
+
+/**
+ * @typedef {object} RuleVerdict
+ * @property {'pass' | 'fail' | 'partial'} verdict
+ * @property {number} certainty — 0..1; ≥ 0.9 allows LLM-skip per § 3c
+ * @property {number} score — 0..100; aligned with LLM judge scale
+ * @property {string} spec — IntentSpec.id that produced this verdict
+ * @property {object} findings — required_missing / forbidden_present / counts
+ */

package/validate/semantic/index.js

@@ -0,0 +1,163 @@
+/**
+ * Semantic validator — public API (Phase 1: LLM-only, shadow mode).
+ *
+ * See .claude/docs/specs/semantic-validator.md §5.2 for the SemanticVerdict shape.
+ * Phase 1: LLM-judge only. Hybrid rule path is Phase 3.
+ *
+ * Usage:
+ *   import { validateSemantics } from 'packages/gen-ui/validate/semantic/index.js';
+ *   const v = await validateSemantics({ intent, messages }, { cache: true });
+ */
+import { cacheKey, makeCache } from './cache.js';
+import { callJudge, getRubric, summarizeA2UI } from './judge.js';
+
+function clamp(n, lo = 0, hi = 100) {
+  const x = Number.isFinite(n) ? n : 0;
+  return Math.max(lo, Math.min(hi, Math.round(x)));
+}
+
+function shapeVerdict(parsed, { rubricVersion, cost }) {
+  const axes = parsed?.axes || {};
+  const dp = axes.dominantPattern || {};
+  const rc = axes.requiredCapabilities || {};
+  const fn = axes.forbiddenNoise || {};
+
+  const dpScore = clamp(dp.score);
+  const rcScore = clamp(rc.score);
+  const fnScore = clamp(fn.score);
+
+  // Trust the judge's score if sane; otherwise recompute from axes.
+  let score = parsed?.score;
+  if (!Number.isFinite(score) || score < 0 || score > 100) {
+    score = Math.round(0.5 * dpScore + 0.35 * rcScore + 0.15 * fnScore);
+  } else {
+    score = clamp(score);
+  }
+
+  const verdictIn = String(parsed?.verdict || '').toLowerCase();
+  const verdict = ['aligned', 'partial', 'misaligned', 'off-topic'].includes(verdictIn)
+    ? verdictIn
+    : (() => {
+        if (dpScore < 15) return 'off-topic';
+        if (dpScore < 40 || [dpScore, rcScore, fnScore].filter((s) => s < 60).length >= 2) return 'misaligned';
+        if (score >= 75 && dpScore >= 75 && rcScore >= 75 && fnScore >= 75) return 'aligned';
+        return 'partial';
+      })();
+
+  return {
+    score,
+    verdict,
+    path: 'llm-only',
+    axes: {
+      dominantPattern: {
+        expected: String(dp.expected || ''),
+        observed: String(dp.observed || ''),
+        score: dpScore,
+      },
+      requiredCapabilities: {
+        expected: Array.isArray(rc.expected) ? rc.expected.map(String) : [],
+        missing: Array.isArray(rc.missing) ? rc.missing.map(String) : [],
+        score: rcScore,
+      },
+      forbiddenNoise: {
+        observed: Array.isArray(fn.observed) ? fn.observed.map(String) : [],
+        score: fnScore,
+      },
+    },
+    rationale: String(parsed?.rationale || '').slice(0, 240),
+    evidence: Array.isArray(parsed?.evidence) ? parsed.evidence.map(String).slice(0, 10) : [],
+    cost,
+    rubricVersion,
+  };
+}
+
+/**
+ * validateSemantics — Phase 1 implementation (LLM-only + cache).
+ */
+export async function validateSemantics(input, opts = {}) {
+  const { intent, messages } = input || {};
+  const {
+    cache = true,
+    timeoutMs = 15000,
+    model,
+    rubricVersion = getRubric().version,
+  } = opts;
+
+  if (!intent || !Array.isArray(messages) || messages.length === 0) {
+    return {
+      score: 0,
+      verdict: 'off-topic',
+      path: 'llm-only',
+      axes: {
+        dominantPattern: { expected: '', observed: 'none', score: 0 },
+        requiredCapabilities: { expected: [], missing: [], score: 0 },
+        forbiddenNoise: { observed: [], score: 100 },
+      },
+      rationale: 'No messages emitted; nothing to score.',
+      evidence: [],
+      cost: { cached: false, latencyMs: 0 },
+      rubricVersion,
+      error: 'no-messages',
+    };
+  }
+
+  const key = cacheKey({ rubricVersion, intent, messages });
+  const store = cache ? makeCache() : null;
+
+  if (store) {
+    const hit = await store.get(key);
+    if (hit) {
+      return { ...hit, cost: { ...(hit.cost || {}), cached: true } };
+    }
+  }
+
+  const summary = summarizeA2UI(messages);
+  let judgeRes;
+  try {
+    judgeRes = await callJudge({
+      intent,
+      componentSummary: summary,
+      rubricVersion,
+      timeoutMs,
+      ...(model ? { model } : {}),
+    });
+  } catch (err) {
+    return {
+      score: 0,
+      verdict: 'partial',
+      path: 'llm-only',
+      axes: {
+        dominantPattern: { expected: '', observed: '', score: 0 },
+        requiredCapabilities: { expected: [], missing: [], score: 0 },
+        forbiddenNoise: { observed: [], score: 0 },
+      },
+      rationale: `Judge error: ${err.message || String(err)}`.slice(0, 240),
+      evidence: [],
+      cost: { cached: false, latencyMs: 0 },
+      rubricVersion,
+      error: 'judge-failed',
+    };
+  }
+
+  const cost = {
+    provider: judgeRes.provider,
+    model: judgeRes.model,
+    inputTokens: judgeRes.usage.inputTokens,
+    outputTokens: judgeRes.usage.outputTokens,
+    cached: false,
+    latencyMs: judgeRes.latencyMs,
+  };
+
+  const verdict = shapeVerdict(judgeRes.parsed, { rubricVersion, cost });
+
+  if (store) {
+    try {
+      await store.set(key, verdict);
+    } catch {
+      /* cache write failure is non-fatal */
+    }
+  }
+  return verdict;
+}
+
+export { getRubric, summarizeA2UI };