@adia-ai/a2ui-compose 0.7.26 → 0.7.28

package/CHANGELOG.md

@@ -1,4 +1,93 @@
 # Changelog — @adia-ai/a2ui-compose
+## [0.7.28] — 2026-07-14
+
+A2UI pipeline overhaul (comparing gen-ui-kit's system against a sibling
+project's from-scratch A2UI implementation surfaced a concrete gap: only
+one of six generation strategies ran a genuine closed-loop validate→retry
+before returning; the rest either skipped it, did a single repair shot,
+or validated a narrower plan/grounding contract).
+
+### Added
+
+- **`packages/a2ui/compose/shared/validate-and-repair.js`** — a shared
+  closed-loop validate→repair helper, extracted from `generate-thinking`'s
+  original inline loop (schema + Ajv catalog + anti-pattern conformance,
+  bounded LLM-fed repair attempts). Every LLM-calling engine can now share
+  one implementation instead of hand-rolling its own; escalation policy
+  (retry vs. give up vs. escalate to a bigger tier) stays entirely with
+  the caller — the module only reports `{valid, exhausted, attempts,
+  failures}`.
+
+### Fixed
+
+- **`generate-pro` — replaces its single hardcoded repair shot with the
+  shared closed loop** (`maxAttempts: 2`, reflecting pro's cheaper cost
+  tier vs. thinking's 3) and adds Ajv catalog-schema coverage it never had
+  before.
+- **`free-form-composer` — now runs a real schema/catalog/anti-pattern
+  check (validate-only) on its transpiled output**, which it previously
+  never did at all (a hardcoded `score: 85` regardless of actual
+  validity). This surfaced a real, previously-invisible defect: the
+  synthesized root component used `id: 'free-form-root'` instead of the
+  `'root'` convention every other engine's root uses, which
+  `validator.js`'s `checkHasRootComponent` hard-fails on — fixed at the
+  source (`transpile.js`). `score` stays 85 on the success path
+  (unchanged), so the tuned `eval:diff` floors don't shift as a side
+  effect of adding a measurement; new `schemaValid`/`schemaValidation`
+  fields are additive.
+- **`monolithic-instant` no longer silently returns a hard-fail's broken
+  output.** The dispatcher (`strategies/registry.js`'s
+  `generateInstantAdapter`) now escalates a hard-fail to `generate-pro`
+  exactly once, only when an `llmAdapter` is available — capped at one
+  hop by construction (a pro-mode failure returns straight to the
+  original caller, never chains to thinking). A counter +
+  `console.warn` ship from day one, since this silently converts a
+  0-cost request into a billed LLM call.
+- **`chunk-zettel` now emits a real component graph and qualifies for
+  the shared closed loop (TKT-0009).** `composeFromIntent`
+  (`chunk-synthesizer.js`) previously returned only a raw HTML string,
+  which both callers wrapped into a single node with an unregistered
+  `component: 'article'` type — full schema validation could only ever
+  report `invalid`. Ratified direction: reuse `transpileHTML()` (the
+  same converter `harvest-chunks.mjs` already runs at corpus-admission
+  time) to produce a real `template` component array on every path (a
+  chunk's own precomputed template when available, else transpiled on
+  demand). Both callers (`registry.js`'s `generateChunkZettelAdapter`,
+  `generator-adapter.js`'s `bridgeToChunkSynthesis`) now prefer
+  `result.template` and route the final messages through
+  `validate-and-repair.js` (validate-only). Verified live: Tier-1
+  retrieval and Tier-2 synthesis intents both produce `valid:true`
+  component graphs (score 90/92); zero regression confirmed via a
+  stash-based before/after comparison of `eval:compose-from-chunks`
+  (the eval calls `composeFromIntent` directly and never touches the
+  caller code this change modified).
+- **`transpiler/transpiler-maps.js` — dynamic array props (`Chart.data`,
+  `Table.data`) are now actually parsed, not copied through as raw
+  strings (TKT-0010).** Compiled dynamic props are a bare `$ref`
+  (`DynamicString`/`DynamicObjectList`/etc.) with no inline `type`, so
+  `CATALOG_PROPS`'s `pdef.type || 'string'` silently defaulted every
+  dynamic array prop to string extraction — a declarative
+  `data='[{...}]'` attribute's JSON text was copied through unparsed,
+  never `JSON.parse`d, so it could never satisfy the catalog's
+  array-shaped schema. Fixed by resolving `$ref` names to their
+  primitive kind (new `REF_TYPE_MAP`) and adding a `JSON.parse`-ing
+  array extraction branch (skipping silently on parse failure or a
+  non-array result, matching `chart.yaml`'s own documented "non-array
+  renders empty" contract). Root-caused via the corpus admission
+  validator surfacing the same `Chart`/`Table`.`data` `oneOf` failure
+  across 8+ unrelated chunks — a schema-generation/transpiler bug, not
+  independent content authoring mistakes. See `@adia-ai/a2ui-corpus`'s
+  CHANGELOG for the companion schema-side fix (`DynamicObjectList`).
+
+## [0.7.27] — 2026-07-12
+
+### Fixed
+- **Transpiler — `[span]` is now universally preserved (TKT-0002).** `extractProps()` had a universal preserve for `[slot]` but not `[span]` — the same class of cross-cutting, layout-bearing attribute, consumed purely via `grid.css`'s `& > [span="N"]` child selectors and never declared in any component's own yaml `props:`. Every transpiled asymmetric grid collapsed to equal columns (the admin-dashboard's 3:2 Overview/Recent-Sales split was the operator-reported case). Regression tests cover `span="3"`, `span="full"`, and the absent case.
+- **Transpiler — `Tag` is a leaf type; labels ride the `text` prop (TKT-0004 A).** `Tag` was missing from `LEAF_TYPES`, so `<tag-ui size="sm">label</tag-ui>` transpiled to `Tag > Text variant=body` — a full body-size paragraph inside the pill, inflating every converted chip (581 instances across 233 docs pages measured). Labels now ride tag.yaml's documented `attr(text)` contract, in both the pure-text and element-children extraction paths.
+- **`strategies/zettel/issue-reporter.js` — issue storage repointed to `qa/findings/issues/`.** The previous path would have silently recreated the retired `.brain/` tree at runtime on the first `report_issue` call.
+
+### Maintenance
+- Transpiler test suite: `extract-props.test.js` 19 → 24 cases (span preservation ×3, Tag text contract ×2).
 
 ## [0.7.26] — 2026-07-04
 
@@ -916,7 +1005,7 @@ See root [CHANGELOG.md `[Unreleased]`](../../../CHANGELOG.md) for the v0.4.5 ove
 - **`compose/strategies/monolithic/generate-pro.js` + companion `_shared/fragment-expander.js` — fragment machinery removed (§37).** Fragments retired; 85 compositions inlined with previously-referenced fragment content. Expander deleted; its caller's try/catch in `generator-adapter.js` handles the absence gracefully.
 - **MCP server `mcp/server.js` (§37).** Removed `get_fragment` tool, simplified `zettel_stats`, updated imports + boot logs + engine description to reflect the post-fragment world.
 
-See root [CHANGELOG.md `[Unreleased]`](../../../CHANGELOG.md) for the cross-cutting arc narrative + [.claude/docs/journal/2026/05/2026-05-12.md](../../../.claude/docs/journal/2026/05/2026-05-12.md) §§ 37 / 38 / 41 / 47 for per-§ details.
+See root [CHANGELOG.md `[Unreleased]`](../../../CHANGELOG.md) for the cross-cutting arc narrative + `.claude/docs/journal/2026/05/2026-05-12.md` §§ 37 / 38 / 41 / 47 for per-§ details.
 ## [0.4.3] - 2026-05-11
 
 ### Fixed
@@ -1200,7 +1289,7 @@ packages now share one version, governed by
 [`.claude/docs/specs/package-architecture.md` § 15 (Versioning Policy)](../../../.claude/docs/specs/package-architecture.md#15-versioning-policy).
 This release also lands the `engine/` ↔ `engines/` collision fix from
 T3 of the
-[`.claude/docs/plans/packages-architecture-fixes-2026-05-02.md`](../../../.brain/archive/2026-Q2/PLAN-packages-architecture-fixes-2026-05-02.md)
+`.claude/docs/plans/packages-architecture-fixes-2026-05-02.md`
 plan.
 
 ### Changed
@@ -1255,8 +1344,8 @@ multi-turn surface, plus a first-class telemetry surface that auto-fires
 issue tickets on engine failure paths.
 
 Spec: [`.claude/docs/specs/genui-multiturn-architecture.md`](../../../.claude/docs/specs/genui-multiturn-architecture.md) (Active v0.1.0).
-Plan: [`.claude/docs/plans/genui-multiturn-rollout-2026-04-28.md`](../../../.claude/docs/plans/genui-multiturn-rollout-2026-04-28.md) (Phase A scoped).
-ADR: [`0008-multiturn-genui-architecture.md`](../../../.brain/adrs/0008-multiturn-genui-architecture.md).
+Plan: `.claude/docs/plans/genui-multiturn-rollout-2026-04-28.md` (Phase A scoped).
+ADR: `0008-multiturn-genui-architecture.md`.
 
 ### Added (engine modules)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/a2ui-compose",
-  "version": "0.7.26",
+  "version": "0.7.28",
   "description": "AdiaUI A2UI compose engine \u2014 framework-agnostic. Takes natural-language intents + a catalog and produces A2UI protocol messages. Pairs with `@adia-ai/a2ui-retrieval` (intent classification, catalog lookup) and `@adia-ai/a2ui-validator` (schema + semantic checks).",
   "type": "module",
   "exports": {

package/strategies/free-form-composer/free-form-composer.test.js

@@ -293,7 +293,7 @@ describe('transpilePlan — root container (§103 auto-grouping)', () => {
     }, lookup);
     const root = result.messages[0].components[0];
     expect(root.component).toBe('Column');
-    expect(root.id).toBe('free-form-root');
+    expect(root.id).toBe('root');
     expect(root.wrap).toBeUndefined();
     expect(root.columns).toBeUndefined();
   });
@@ -490,3 +490,25 @@ describe('transpilePlan — multi-attribute substitutions (§105 v0.5.0)', () =>
     expect(node.text).toBe('42');
   });
 });
+
+// A2UI overhaul (Phase 3): full schema/anti-pattern/catalog check now runs
+// on the transpiled result — previously this engine reported a hardcoded
+// score=85 with NO real validation behind it at all.
+describe('free-form-composer — schema validation (Phase 3 addition)', () => {
+  it('a validly-transpiled composition reports schemaValid: true, score stays 85 (unchanged eval-floor contract)', async () => {
+    const fakeLLM = {
+      complete: async () => ({
+        content: JSON.stringify({ ingredients: [{ name: 'demo-login' }], rationale: 'ok' }),
+      }),
+    };
+    const result = await generateFreeForm({
+      intent: 'sign me in',
+      llmAdapter: fakeLLM,
+      compositions: FIXTURE_VOCAB,
+    });
+    expect(result.strategy).toBe('free-form-composed');
+    expect(result.validation.score).toBe(85);
+    expect(result.schemaValid).toBe(true);
+    expect(result.schemaValidation).toBeTruthy();
+  });
+});

package/strategies/free-form-composer/index.js

@@ -33,6 +33,7 @@ import {
   buildFreeFormParaphraseRetry,
 } from './system-prompt.js';
 import { transpilePlan, parsePlan } from './transpile.js';
+import { validateAndRepair } from '../../shared/validate-and-repair.js';
 
 const MAX_ATTEMPTS = 2;
 
@@ -209,9 +210,27 @@ Note: your previous response wasn't valid JSON. Output ONLY the JSON object —
     };
   }
 
-  // Score reflects "we successfully composed N ingredients without
-  // hallucination". Validator-level scoring is upstream's responsibility.
-  // 85 chosen to match zettel's `composition-match` avgScore baseline.
+  // Full schema/catalog/anti-pattern conformance — the same final pass
+  // every other LLM-calling engine runs (see validate-and-repair.js) —
+  // ADDED here, not previously run at all; this engine used to report a
+  // hardcoded score=85 with no real validation behind it whatsoever.
+  // Validate-ONLY (no llmAdapter passed): a repair attempt here would mean
+  // re-authoring the ingredient PLAN, not the transpiled A2UI JSON
+  // directly — this engine's whole paradigm is ingredient selection +
+  // deterministic transpilation, not direct JSON authoring, so a schema-
+  // failure repair prompt has no natural target to hand back to the LLM.
+  // The existing hallucination-guard retry loop above (ingredient-name
+  // grounding) is this engine's own repair mechanism.
+  //
+  // score stays 85 on the success path — unchanged from before — so the
+  // eval:diff floors (cov/avg/F1) tuned against that number don't shift as
+  // a side effect of adding a measurement; schemaValid/schemaScore/
+  // antiPatternFailures are new, additive fields a future increment (or
+  // the eval baseline itself, deliberately) can act on.
+  const schemaCheck = await validateAndRepair({ messages });
+  if (!schemaCheck.valid) {
+    warnings = warnings.concat([`schema/anti-pattern check failed (score ${schemaCheck.validation.score}): ${schemaCheck.validation.checks?.filter(c => !c.passed).map(c => c.name).join(', ') || 'see schemaValidation'}`]);
+  }
   const score = 85;
 
   return {
@@ -224,5 +243,7 @@ Note: your previous response wasn't valid JSON. Output ONLY the JSON object —
     warnings,
     rationale: plan.rationale || null,
     emptyPlanRetryUsed,
+    schemaValid: schemaCheck.valid,
+    schemaValidation: schemaCheck.validation,
   };
 }

package/strategies/free-form-composer/transpile.js

@@ -220,7 +220,12 @@ function buildRoot(plan, rootChildren, warnings) {
   }
 
   const base = {
-    id: 'free-form-root',
+    // 'root' — not 'free-form-root' — matches the convention every other
+    // engine's root component uses (validator.js's checkHasRootComponent
+    // hard-fails without it: "at least one component with id: 'root'").
+    // This engine never ran real schema validation before Phase 3 of the
+    // A2UI overhaul plan, so the mismatch went unnoticed until then.
+    id: 'root',
     gap: '6',
     children: rootChildren,
   };

package/strategies/monolithic/generate-pro.js

@@ -6,7 +6,7 @@
  * in strategies/monolithic/_shared.js.
  */
 
-import { validateSchema } from '../../../validator/validator.js';
+import { validateAndRepair } from '../../shared/validate-and-repair.js';
 import { getContext, searchBlocks, lookupDomain } from '../../core/reference.js';
 import { decomposeIntent } from '../../../retrieval/intent/decomposer.js';
 import { assessClarity } from '../../../retrieval/intent/clarity.js';
@@ -403,18 +403,26 @@ ${buildCanvasDiffPrompt(intent, priorComponents, { originalIntent })}`;
   });
 
   // ── Stage 5: Validate + repair ──
-  let validation = foldInAntiPatterns(messages, validateSchema(messages, { intent, context }));
-  if (!validation.valid) {
-    try {
-      const failedChecks = validation.checks.filter(c => !c.passed);
-      const repairResponse = await llmAdapter.complete({
-        messages: [{ role: 'user', content: buildRepairPrompt(failedChecks, messages) }],
-        systemPrompt,
-      });
-      messages = parseA2UIResponse(repairResponse.content, { executionId: execId, intent, mode: 'pro', stopReason: repairResponse.stopReason });
-      validation = foldInAntiPatterns(messages, validateSchema(messages, { intent, context }));
-    } catch { /* keep original */ }
-  }
+  // Shared with every other LLM-calling engine — see validate-and-repair.js.
+  // maxAttempts: 2 (vs. thinking's 3) reflects pro's cheaper cost tier.
+  // runCatalogCheck adds Ajv catalog-schema coverage pro never had before —
+  // buildRepairPrompt's catalogFailures param already defaults to [] so
+  // this is additive, not a signature break.
+  const repairResult = await validateAndRepair({
+    messages,
+    llmAdapter,
+    buildRepairPrompt,
+    parseResponse: (repairResponse) => parseA2UIResponse(
+      repairResponse.content,
+      { executionId: execId, intent, mode: 'pro', stopReason: repairResponse.stopReason },
+    ),
+    systemPrompt,
+    validateContext: { intent, context },
+    foldInAntiPatterns,
+    maxAttempts: 2,
+  });
+  messages = repairResult.messages;
+  const validation = repairResult.validation;
   engine.submitStage(execId, 'validate', { ...validation, confidence: validation.score / 100 });
 
   // ── Stage 6: Store ──

package/strategies/monolithic/generate-thinking.js

@@ -6,8 +6,7 @@
  * in strategies/monolithic/_shared.js.
  */
 
-import { validateSchema } from '../../../validator/validator.js';
-import { validateMessages as validateCatalog } from '../../../validator/catalog-validator.js';
+import { validateAndRepair } from '../../shared/validate-and-repair.js';
 import { getContext, searchBlocksSemantic, lookupDomain } from '../../core/reference.js';
 import { assessClarity } from '../../../retrieval/intent/clarity.js';
 import { feedbackStore } from '../../../retrieval/feedback/feedback-store.js';
@@ -122,35 +121,32 @@ export async function generateThinking({ intent, executionId, storeId, llmAdapte
   });
 
   // ── Stage 5: Validate + repair loop ──
-  // Two orthogonal validators run in parallel:
-  //   - scored: weighted heuristic checks (intent alignment, card model, etc.)
-  //   - catalog: AJV against v0.9 catalog schema (strict structural correctness)
-  // Either failing triggers a repair attempt. Catalog failures are typically
-  // small (unknown prop, wrong enum, missing required id) and fix cleanly in
-  // one repair round. Three-attempt cap preserved from the original loop.
-  let validation = foldInAntiPatterns(messages, validateSchema(messages, { intent, context }));
-  let catalogValidation = await validateCatalog(messages);
-  let attempts = 0;
-
-  while ((!validation.valid || !catalogValidation.valid) && attempts < 3) {
-    attempts++;
-    const failedChecks = validation.checks.filter(c => !c.passed);
-    const catalogFailures = catalogValidation.failures || [];
-    const repairPrompt = buildRepairPrompt(failedChecks, messages, catalogFailures);
-
-    try {
-      const repairResponse = await llmAdapter.complete({
-        messages: [{ role: 'user', content: repairPrompt }],
-        systemPrompt,
-      });
-      messages = parseA2UIResponse(repairResponse.content, { executionId: execId, mode: 'thinking', intent, stopReason: repairResponse.stopReason });
+  // Two orthogonal validators run: scored (weighted heuristic checks —
+  // intent alignment, card model, etc.) and catalog (AJV against v0.9
+  // catalog schema — strict structural correctness). Either failing
+  // triggers a repair attempt. Catalog failures are typically small
+  // (unknown prop, wrong enum, missing required id) and fix cleanly in one
+  // repair round. Three-attempt cap preserved from the original loop.
+  // Shared with every other LLM-calling engine — see validate-and-repair.js.
+  const repairResult = await validateAndRepair({
+    messages,
+    llmAdapter,
+    buildRepairPrompt,
+    parseResponse: (repairResponse) => parseA2UIResponse(
+      repairResponse.content,
+      { executionId: execId, mode: 'thinking', intent, stopReason: repairResponse.stopReason },
+    ),
+    systemPrompt,
+    validateContext: { intent, context },
+    foldInAntiPatterns,
+    maxAttempts: 3,
+    onAttempt: (repairResponse) => {
       if (isRecording()) { lastRawResponse = repairResponse.content; lastTokens = repairResponse.usage || lastTokens; }
-      validation = foldInAntiPatterns(messages, validateSchema(messages, { intent, context }));
-      catalogValidation = await validateCatalog(messages);
-    } catch {
-      break; // stop repair loop on adapter error
-    }
-  }
+    },
+  });
+  messages = repairResult.messages;
+  const validation = repairResult.validation;
+  const attempts = repairResult.attempts;
 
   engine.submitStage(execId, 'validate', {
     ...validation,

package/strategies/registry.js

@@ -52,11 +52,42 @@ export function registerMonolithicEngines({ instant, pro, thinking }) {
   _monolithicThinking = thinking;
 }
 
+// A2UI overhaul plan, Phase 4: instant mode never repairs (it makes no LLM
+// calls at all — that's its whole cost/latency identity) and previously
+// returned a hard-fail's broken output silently. Escalation to pro lives
+// HERE, at the dispatcher, not inside generate-instant.js itself — it's the
+// caller's policy decision, matching validate-and-repair.js's "escalation
+// stays with the caller" contract, and this is the one place that already
+// holds both `ctx.llmAdapter` and `_monolithicPro` in scope.
+//
+// Capped at exactly one hop by construction: generateProAdapter has no
+// escalation logic of its own, so a pro-mode failure after an instant
+// escalation returns straight to the original caller — it can never chain
+// into thinking. Only escalates when an llmAdapter is actually available;
+// many instant-mode callers pass none (that's the 0-cost tier's point), and
+// validate-and-repair.js's own contract for that case is "report the
+// failure, don't invent a repair path" — same discipline here.
+//
+// This silently converts a 0-cost request into a billed LLM call, which is
+// a product/cost-visibility concern, not just an engineering one — hence
+// the counter + the warn log, from day one, not added later once someone
+// asks "why did our LLM spend spike".
+let _instantEscalationCount = 0;
+export function getInstantEscalationCount() {
+  return _instantEscalationCount;
+}
+
 // Engine adapters — uniform call signature `(ctx) => Promise<result>` where
 // ctx is prepared by the public generateUI() orchestrator.
 async function generateInstantAdapter(ctx) {
   if (!_monolithicInstant) throw new Error('monolithic-instant engine not registered');
-  return _monolithicInstant(ctx);
+  const result = await _monolithicInstant(ctx);
+  if (!result.validation?.valid && ctx.llmAdapter && _monolithicPro) {
+    _instantEscalationCount++;
+    console.warn(`[a2ui] monolithic-instant hard-failed validation (score=${result.validation?.score}) for intent "${ctx.intent}" — escalating to monolithic-pro (escalation #${_instantEscalationCount})`);
+    return _monolithicPro(ctx);
+  }
+  return result;
 }
 async function generateProAdapter(ctx) {
   if (!_monolithicPro) throw new Error('monolithic-pro engine not registered');
@@ -230,27 +261,42 @@ async function generateFreeFormAdapter(ctx) {
 
 async function generateChunkZettelAdapter(ctx) {
   const { composeFromIntent } = await import('./zettel/chunk-synthesizer.js');
+  const { validateAndRepair } = await import('../shared/validate-and-repair.js');
   const result = await composeFromIntent({
     intent: ctx.intent,
     llmAdapter: ctx.llmAdapter || null,
     maxAttempts: 2,
   });
 
-  // Convert chunk-composition result to A2UI message shape.
-  const messages = result.html
-    ? [{ type: 'updateComponents', components: [{ id: 'chunk-root', component: 'article', html: result.html }] }]
-    : [];
+  // TKT-0009: composeFromIntent now returns a real component array
+  // (`result.template`) whenever it can, instead of only an HTML string —
+  // use it directly; the pre-fix fallback (a single node carrying an
+  // UNREGISTERED `component: 'article'` type) only fires if transpilation
+  // itself somehow produced nothing, which should not happen in practice.
+  const messages = result.template
+    ? [{ type: 'updateComponents', components: result.template }]
+    : result.html
+      ? [{ type: 'updateComponents', components: [{ id: 'chunk-root', component: 'article', html: result.html }] }]
+      : [];
+
+  // Full schema/catalog/anti-pattern conformance — the same final pass
+  // every other engine runs (see validate-and-repair.js). Validate-only:
+  // no natural repair target here (the LLM authored a slot-binding PLAN,
+  // not this A2UI JSON directly) — chunk-composer's own `validatePlan`
+  // is this engine's repair-relevant check and already ran upstream.
+  const schemaCheck = messages.length ? await validateAndRepair({ messages }) : { valid: false, validation: { score: 0 } };
 
   return {
     executionId: ctx.executionId,
     messages,
-    validation: { score: result.html ? 70 : 0 },
+    validation: schemaCheck.validation,
     strategy: result.source === 'retrieval' ? 'chunk-retrieval' : 'chunk-synthesis',
     engine: 'chunk-zettel',
     _debug: {
       plan: result.plan || null,
       warnings: result.warnings || [],
       scopeDrift: result.scopeDrift || null,
+      schemaValid: schemaCheck.valid,
     },
   };
 }

package/strategies/registry.test.js

@@ -0,0 +1,82 @@
+/**
+ * registry.js — instant→pro escalation (A2UI overhaul plan, Phase 4).
+ *
+ * Instant mode makes zero LLM calls and previously returned a hard-fail's
+ * broken output silently. The dispatcher now escalates to pro exactly once
+ * when an llmAdapter is available; escalation policy lives here, not inside
+ * generate-instant.js itself (see registry.js's comment above
+ * generateInstantAdapter).
+ */
+import { describe, it, expect, beforeEach } from 'vitest';
+import { registerMonolithicEngines, ENGINES, getInstantEscalationCount } from './registry.js';
+
+const HARD_FAIL_RESULT = { messages: [], validation: { valid: false, score: 0 }, strategy: 'fallback' };
+const VALID_RESULT = { messages: [{ type: 'updateComponents', components: [{ id: 'root', component: 'Card' }] }], validation: { valid: true, score: 90 }, strategy: 'pattern-match' };
+
+beforeEach(() => {
+  // Reset to known fakes before every case — registerMonolithicEngines is
+  // the same public injection API core/generator.js uses at boot.
+  registerMonolithicEngines({ instant: null, pro: null, thinking: null });
+});
+
+describe('generateInstantAdapter — escalation to pro on hard-fail', () => {
+  it('does NOT escalate when instant mode already returns a valid result', async () => {
+    let proCalls = 0;
+    registerMonolithicEngines({
+      instant: async () => VALID_RESULT,
+      pro: async () => { proCalls++; return VALID_RESULT; },
+      thinking: async () => VALID_RESULT,
+    });
+    const before = getInstantEscalationCount();
+    const result = await ENGINES['monolithic-instant']({ intent: 'x', llmAdapter: { complete: async () => ({}) } });
+    expect(result).toBe(VALID_RESULT);
+    expect(proCalls).toBe(0);
+    expect(getInstantEscalationCount()).toBe(before);
+  });
+
+  it('escalates to pro exactly once when instant hard-fails AND an llmAdapter is available', async () => {
+    let proCalls = 0;
+    registerMonolithicEngines({
+      instant: async () => HARD_FAIL_RESULT,
+      pro: async (ctx) => { proCalls++; return { ...VALID_RESULT, receivedCtx: ctx }; },
+      thinking: async () => VALID_RESULT,
+    });
+    const before = getInstantEscalationCount();
+    const fakeAdapter = { complete: async () => ({}) };
+    const result = await ENGINES['monolithic-instant']({ intent: 'x', executionId: 'exec-1', storeId: 'store-1', llmAdapter: fakeAdapter });
+    expect(proCalls).toBe(1);
+    expect(result.validation.valid).toBe(true);
+    expect(getInstantEscalationCount()).toBe(before + 1);
+    // Same ctx (storeId/executionId/llmAdapter) threaded through unmodified —
+    // no session/store desync risk from a reconstructed context.
+    expect(result.receivedCtx.executionId).toBe('exec-1');
+    expect(result.receivedCtx.storeId).toBe('store-1');
+    expect(result.receivedCtx.llmAdapter).toBe(fakeAdapter);
+  });
+
+  it('does NOT escalate when instant hard-fails but no llmAdapter is available — reports the failure as-is', async () => {
+    let proCalls = 0;
+    registerMonolithicEngines({
+      instant: async () => HARD_FAIL_RESULT,
+      pro: async () => { proCalls++; return VALID_RESULT; },
+      thinking: async () => VALID_RESULT,
+    });
+    const result = await ENGINES['monolithic-instant']({ intent: 'x', llmAdapter: null });
+    expect(proCalls).toBe(0);
+    expect(result).toBe(HARD_FAIL_RESULT);
+  });
+
+  it('caps escalation at exactly one hop — a pro-mode failure never chains to thinking', async () => {
+    let proCalls = 0;
+    let thinkingCalls = 0;
+    registerMonolithicEngines({
+      instant: async () => HARD_FAIL_RESULT,
+      pro: async () => { proCalls++; return HARD_FAIL_RESULT; }, // pro ALSO fails
+      thinking: async () => { thinkingCalls++; return VALID_RESULT; },
+    });
+    const result = await ENGINES['monolithic-instant']({ intent: 'x', llmAdapter: { complete: async () => ({}) } });
+    expect(proCalls).toBe(1);
+    expect(thinkingCalls).toBe(0); // never chains further — pro's own failure returns to the original caller
+    expect(result.validation.valid).toBe(false);
+  });
+});

package/strategies/zettel/chunk-synthesizer.js

@@ -27,6 +27,29 @@ import {
   getAllChunks,
 } from '../../../corpus/scripts/chunk-library.js';
 import { composeFromPlan, validatePlan } from './chunk-composer.js';
+import { transpileHTML } from '../../transpiler/transpiler.js';
+
+// TKT-0009: composeFromIntent used to return only a raw HTML string,
+// which every caller wrapped in a single node carrying an UNREGISTERED
+// A2UI type (`component: 'article'`) — meaning full schema/catalog
+// validation against it always reported invalid, regardless of the
+// composed content's actual quality (registry.has('article') is false).
+// Ratified direction: reuse the SAME transpileHTML() infrastructure the
+// docs-transpiler and harvest-chunks.mjs already run at scale, rather
+// than inventing a new passthrough construct — this makes every
+// composeFromIntent() result a REAL component graph, so it qualifies for
+// the shared validate-and-repair loop like every other engine. A chunk's
+// own precomputed `.template` (from harvest-chunks.mjs) is used directly
+// when available (accurate, no re-transpile cost); multi-instance chunk
+// records don't carry one per-instance, so this falls back to
+// transpiling the HTML on demand either way — every return path leaves
+// with a real template, never just a string.
+async function ensureTemplate(html, precomputedTemplate) {
+  if (Array.isArray(precomputedTemplate) && precomputedTemplate.length) return precomputedTemplate;
+  if (!html) return null;
+  const { messages } = await transpileHTML(html);
+  return messages?.[0]?.components ?? null;
+}
 
 const STRONG_RETRIEVAL_SCORE = 8;     // search-score threshold for fast path
 const PRE_SEARCH_LIMIT = 30;           // chunks shown to the LLM in the prompt
@@ -199,7 +222,11 @@ function extractJSON(raw) {
  * @param {string} opts.intent
  * @param {object} opts.llmAdapter — { complete: async ({ messages, systemPrompt }) => { content|text } }
  * @param {number} [opts.maxAttempts=2]
- * @returns {Promise<{ html: string, plan: object|null, source: 'retrieval'|'synthesis', score?: number, warnings: string[], synthesis?: object }>}
+ * @returns {Promise<{ html: string, template: object[]|null, plan: object|null, source: 'retrieval'|'synthesis', score?: number, warnings: string[], synthesis?: object }>}
+ *   `template` (TKT-0009) is a real A2UI component array — derived from the
+ *   chunk's own precomputed template when available, else transpiled from
+ *   `html` on demand — so callers get a validatable component graph, not
+ *   just an HTML string to wrap opaquely.
  */
 export async function composeFromIntent({ intent, llmAdapter, maxAttempts = DEFAULT_MAX_ATTEMPTS }) {
   // Tier 1 — retrieval. Try semantic-blended hit first; fall back to keyword
@@ -228,6 +255,7 @@ export async function composeFromIntent({ intent, llmAdapter, maxAttempts = DEFA
     const scopeDrift = computeScopeDrift(html, [top]);
     return {
       html,
+      template: await ensureTemplate(html, top.template),
       plan: null,
       source: 'retrieval',
       score: hit.score,
@@ -339,6 +367,7 @@ export async function composeFromIntent({ intent, llmAdapter, maxAttempts = DEFA
 
     return {
       html: composed.html,
+      template: await ensureTemplate(composed.html, null),
       plan,
       source: 'synthesis',
       warnings: [...composed.warnings, ...driftWarnings],

package/strategies/zettel/generator-adapter.js

@@ -47,11 +47,18 @@ import { validateSchema } from '../../../validator/validator.js';
 async function bridgeToChunkSynthesis({ intent, llmAdapter }) {
   const { composeFromIntent } = await import('./chunk-synthesizer.js');
   const result = await composeFromIntent({ intent, llmAdapter, maxAttempts: 2 });
-  // Shape-adapt chunk-synthesizer's `{ html, plan, source, ... }` to the
-  // synthesis-branch's prior `{ messages, template, synthesis }` contract.
-  const messages = result.html
-    ? [{ type: 'updateComponents', components: [{ id: 'chunk-root', component: 'article', html: result.html }] }]
-    : [];
+  // Shape-adapt chunk-synthesizer's `{ html, template, plan, source, ... }`
+  // to the synthesis-branch's prior `{ messages, template, synthesis }`
+  // contract. TKT-0009: prefer the real component array (`result.template`)
+  // over the pre-fix fallback of wrapping raw HTML in a single node with an
+  // UNREGISTERED `component: 'article'` type — that fallback made this
+  // caller's validate-and-repair pass below structurally unable to ever
+  // report a clean pass.
+  const messages = result.template
+    ? [{ type: 'updateComponents', components: result.template }]
+    : result.html
+      ? [{ type: 'updateComponents', components: [{ id: 'chunk-root', component: 'article', html: result.html }] }]
+      : [];
   return {
     messages,
     template: result.plan ? [{ $chunk: 'composeFromIntent', plan: result.plan }] : [],
@@ -172,7 +179,13 @@ export async function generateZettel({ intent, mode = 'instant', llmAdapter = nu
   if (llmAdapter && mode !== 'instant-only') {
     try {
       const synth = await bridgeToChunkSynthesis({ intent, llmAdapter });
-      const validation = validateSchema(synth.messages, { intent });
+      // Full schema/catalog/anti-pattern conformance (validate-only — see
+      // validate-and-repair.js; TKT-0009 made this meaningful for the first
+      // time by giving synth.messages a real component graph instead of an
+      // opaque HTML wrapper).
+      const { validateAndRepair } = await import('../../shared/validate-and-repair.js');
+      const schemaCheck = synth.messages.length ? await validateAndRepair({ messages: synth.messages }) : { valid: false, validation: { score: 0 } };
+      const validation = schemaCheck.validation;
       // Chunk-bridge produces an html-bearing single component, not
       // resolved fragment instances. `fragments_used` is empty by design;
       // consumers tracking fragment usage should switch to the

package/strategies/zettel/issue-reporter.js

@@ -7,7 +7,7 @@
  *   3. Engine auto-fire — internal failure paths trigger `autoReport(reason)`.
  *      ctx.reporter = 'auto'. Suppressed when ctx.evalMode is true.
  *
- * Every issue lands as immutable JSON under `.brain/audit-history/issues/`.
+ * Every issue lands as immutable JSON under `qa/findings/issues/`.
  * Traces > 200KB spill to a sidecar `.trace.json` next to the issue.
  *
  * Spec: .claude/docs/specs/genui-multiturn-architecture.md §3.5 + §4.6 + §11.
@@ -23,7 +23,7 @@ import { fileURLToPath } from 'node:url';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = resolve(__dirname, '../../../../..');
-const DEFAULT_STORAGE_ROOT = resolve(REPO_ROOT, '.brain/audit-history/issues');
+const DEFAULT_STORAGE_ROOT = resolve(REPO_ROOT, 'qa/findings/issues');
 const TRACE_INLINE_THRESHOLD_BYTES = 200 * 1024;
 
 const VALID_TYPES = new Set(['bug', 'training-gap', 'protocol-gap', 'ux-feedback']);

package/transpiler/extract-props.test.js

@@ -225,4 +225,39 @@ describe('§163 extractProps — catalog-driven prop fidelity', () => {
       expect(props.variant).toBe('outline');
     });
   });
+
+  describe('TKT-0004 — Tag label via text prop (attr(text) contract)', () => {
+    it('falls back to light-DOM textContent when no text= attribute', () => {
+      const el = elem({ size: 'sm', variant: 'success' }, { text: '~1 min · no tools' });
+      const props = extractProps(el, 'Tag');
+      expect(props.text).toBe('~1 min · no tools');
+      expect(props.size).toBe('sm');
+    });
+
+    it('an explicit text= attribute wins over textContent', () => {
+      const el = elem({ text: 'explicit' }, { text: 'ignored light-dom' });
+      const props = extractProps(el, 'Tag');
+      expect(props.text).toBe('explicit');
+    });
+  });
+
+  describe('TKT-0002 — [span] universal preservation', () => {
+    it('preserves span on a Card (grid-ui child), same as slot', () => {
+      const el = elem({ span: '3' });
+      const props = extractProps(el, 'Card');
+      expect(props.span).toBe('3');
+    });
+
+    it('preserves span="full" verbatim (not coerced to a number)', () => {
+      const el = elem({ span: 'full' });
+      const props = extractProps(el, 'Card');
+      expect(props.span).toBe('full');
+    });
+
+    it('omits span when absent — no stray empty prop', () => {
+      const el = elem({});
+      const props = extractProps(el, 'Card');
+      expect(props.span).toBeUndefined();
+    });
+  });
 });

package/transpiler/transpiler-maps.js

@@ -39,6 +39,21 @@ import { registry } from '@adia-ai/a2ui-runtime';
 // alias map below so `extractProps(el, 'CheckBox')` resolves to the
 // `Check` catalog entry.
 
+// TKT-0010: dynamic props are compiled to a bare `$ref` (DynamicString /
+// DynamicNumber / DynamicBoolean / DynamicStringList / DynamicObjectList),
+// which carries no inline `type` — so `pdef.type || 'string'` below silently
+// treated EVERY dynamic array prop (Chart.data, Table.data) as a string,
+// copying the raw `data='[...]'` attribute text through unparsed instead of
+// JSON-parsing it into a real array. Resolve the ref name to its primitive
+// kind first so extractCatalogProps' array branch actually fires.
+const REF_TYPE_MAP = {
+  DynamicString: 'string',
+  DynamicNumber: 'number',
+  DynamicBoolean: 'boolean',
+  DynamicStringList: 'array',
+  DynamicObjectList: 'array',
+};
+
 /** @type {Map<string, {props: Map<string, {type: string, enum?: string[]}>, canonical: string}>} */
 const CATALOG_PROPS = (() => {
   const map = new Map();
@@ -50,8 +65,13 @@ const CATALOG_PROPS = (() => {
       // Skip internal/computed props that aren't HTML attributes
       if (pname === 'component' || pname === 'textContent') continue;
       if (typeof pdef !== 'object' || !pdef) continue;
+      let type = pdef.type;
+      if (!type && typeof pdef.$ref === 'string') {
+        const refName = pdef.$ref.split('/').pop();
+        type = REF_TYPE_MAP[refName];
+      }
       propMap.set(pname, {
-        type: pdef.type || 'string',
+        type: type || 'string',
         enum: pdef.enum || null,
       });
     }
@@ -153,6 +173,18 @@ function extractCatalogProps(el, a2uiType) {
       if (raw === '') continue;
       const n = Number(raw);
       props[pname] = Number.isFinite(n) ? n : raw;
+    } else if (pdef.type === 'array') {
+      // TKT-0010: declarative JSON-array attribute (e.g. chart-ui/table-ui's
+      // data='[{...}]'), hydrated once at connect per those components' own
+      // yaml docs. Parse it — the raw string never satisfies the catalog's
+      // array schema, and per chart.yaml's own contract a non-array value
+      // is meant to render empty, so a parse failure/non-array is skipped,
+      // not passed through.
+      if (raw === '') continue;
+      try {
+        const parsed = JSON.parse(raw);
+        if (Array.isArray(parsed)) props[pname] = parsed;
+      } catch { /* not valid JSON — skip */ }
     } else {
       // string (incl. enum) — skip empty
       if (raw === '') continue;
@@ -317,6 +349,17 @@ export function extractProps(el, a2uiType) {
   const slotAttr = attr('slot');
   if (slotAttr) props.slot = slotAttr;
 
+  // Universal: preserve [span] for every element. Span is a layout-bearing
+  // attribute grid-ui's child reads via a pure CSS attribute selector
+  // (grid.css: `& > [span="3"] { grid-column: span 3; }`) — it belongs to
+  // "whatever this grid child happens to be," never to a specific
+  // component's own prop schema, so no .yaml declares it and the
+  // catalog-driven pass below silently drops it (TKT-0002: collapsed the
+  // admin-dashboard Overview/Recent Sales 3:2 split to two equal, unspanned
+  // columns).
+  const spanAttr = attr('span');
+  if (spanAttr) props.span = spanAttr;
+
   // §163 (v0.5.4) — Catalog-driven generic extraction FIRST. Fills in
   // every prop the v0.9 catalog declares for this type (label, icon,
   // variant=, etc.). Legacy per-type blocks below run AFTER and can
@@ -351,6 +394,15 @@ export function extractProps(el, a2uiType) {
     }
   }
 
+  // ── Tag ── (TKT-0004: tag-ui renders its label via CSS attr(text) —
+  // tag.yaml documents textContent as routing to the text attribute. The
+  // authored form is light-DOM content (<tag-ui size="sm">label</tag-ui>),
+  // so fall back to textContent when no text= attribute is set.)
+  if (a2uiType === 'Tag' && props.text === undefined) {
+    const text = (el.textContent || '').trim().replace(/\s+/g, ' ');
+    if (text) props.text = text;
+  }
+
   // ── Link ── (§47 — <a> tags map to Link, not Button; carries href, target, rel)
   if (a2uiType === 'Link') {
     const text = (el.textContent || '').trim().replace(/\s+/g, ' ');

package/transpiler/transpiler.js

@@ -201,9 +201,13 @@ function walkNode(el, context) {
     return id;
   }
 
-  // Leaf types: these render their own text, don't recurse into children
+  // Leaf types: these render their own text, don't recurse into children.
+  // Tag joined 2026-07-12 (TKT-0004): tag-ui renders its label via CSS
+  // attr(text) — as a container, its light-DOM label became a child Text
+  // at body size, inflating every converted chip site-wide (581 instances
+  // across 233 pages measured).
   const LEAF_TYPES = new Set([
-    'Text', 'Button', 'Kbd', 'Code', 'Badge', 'Image', 'Divider',
+    'Text', 'Button', 'Kbd', 'Code', 'Badge', 'Tag', 'Image', 'Divider',
     'TextField', 'CheckBox', 'Toggle', 'Radio', 'Slider', 'Search',
     'Upload', 'ColorPicker', 'DateTimeInput', 'TextArea', 'OtpInput',
   ]);
@@ -244,7 +248,7 @@ function walkNode(el, context) {
     if (directText) {
       // Preserve the direct text on whichever prop the type uses
       if (a2uiType === 'Text' || a2uiType === 'Kbd' || a2uiType === 'Code') containerProps.textContent = directText;
-      else if (a2uiType === 'Button' || a2uiType === 'Badge') {
+      else if (a2uiType === 'Button' || a2uiType === 'Badge' || a2uiType === 'Tag') {
         if (containerProps.text === undefined) containerProps.text = directText;
       }
     } else {