@adia-ai/a2ui-compose 0.3.2 → 0.3.3

package/CHANGELOG.md

@@ -12,6 +12,78 @@ generator graph.
 
 _No pending changes._
 
+## [0.3.3] - 2026-05-07
+
+**Lockstep cut.** All 9 published `@adia-ai/*` packages now share version `0.3.3`, governed by [`docs/specs/package-architecture.md` § 15](../../../docs/specs/package-architecture.md#15-versioning-policy). Internal `@adia-ai/*` ranges stay at `^0.3.0` (patch-cut asymmetry — caret floats `0.3.x`).
+
+### Added
+
+- **`iteration-synthesis-failure` auto-fire policy reason** in
+  `strategies/zettel/issue-reporter.js`. Generator-adapter's
+  iteration synthesis failures now route through
+  `autoReport('iteration-synthesis-failure', ...)` instead of bare
+  `console.error`. Suppressed in eval mode; emits to
+  `.brain/audit-history/issues/` in production. (closes backlog #49)
+
+- **`ID_PREFIX_SEPARATOR` exported constant** in
+  `strategies/zettel/composer.js` — the magic string `'--'` used
+  when prefixing fragment internal node ids with composition node
+  id. Documented choice rationale (double-dash chosen because single
+  `-` collides with kebab-case ids in primitives). (closes backlog #50)
+
+- **`computeScopeDrift` + `SCOPE_DRIFT_RATIO` + `SCOPE_DRIFT_MIN_ACTUAL`
+  exports** in `strategies/zettel/chunk-synthesizer.js`. Internal
+  function + constants are now exported for testability. New
+  `chunk-synthesizer.test.js` (8/8 pass) covers no-drift,
+  ratio-below-gate, drift-fires, floor-prevents-false-positive,
+  malformed-corpus zero-expected guard, multi-chunk aggregation,
+  instances[]-shape support, exports. (closes backlog #52)
+
+- **`A2UI_COMPOSE_TRACE` env-var support** in `core/generator.js`.
+  When set to a directory path, writes a per-request JSON trace
+  (full `_debug` payload + result) per `generateUI()` call, named
+  `<ISO-timestamp>--<intent-slug>.json`. `dialog-recorder.isRecording()`
+  honors the trace var so `_debug` payload is populated. New
+  `npm run compose:trace` script. (closes backlog #89)
+
+### Changed
+
+- **Cache-invalidation contract** documented inline in
+  `strategies/zettel/generator-adapter.js`. `loadAll()` itself is
+  idempotent (`fragments.clear()` + `compositions.clear()` + re-walk
+  on every call). The CACHING happens at the call-site:
+  `ensureBooted()` sets a process-singleton flag and never reloads
+  for the lifetime of the process. Trade-offs: good for long-running
+  MCP, bad for tests/hot-reload. To force a reload, call `loadAll()`
+  directly. (closes backlog #100)
+
+## [0.3.2] - 2026-05-06
+
+**9-package lockstep patch cut to v0.3.2.** All lockstep members share
+one version per [`docs/specs/package-architecture.md` § 15](../../../docs/specs/package-architecture.md#15-versioning-policy).
+Internal `@adia-ai/*` dep ranges unchanged at `^0.3.0`.
+
+### Added
+
+- **`chunk-zettel` engine** — registered as 5th built-in engine in
+  `strategies/registry.js`. Chunk-aware composition from training-chunk
+  corpus (page shells + block chunks). Fast path: sync keyword search
+  over async embeddings to prevent ranking drift.
+
+### Fixed
+
+- **Keyword-first fast path** — `composeFromIntent` prefers sync
+  `searchChunks` over `searchChunksAsync` (embeddings) for retrieval.
+- **Whole-word keyword matching** — `keywordScore()` splits chunk names
+  on `[-_]` and uses `nameWords.includes(tok)`; prevents `"pane"` from
+  matching `"panel"`.
+- **Coverage scoring** — PascalCase → kebab-case regex fix for
+  multi-word components (`AgentTrace` → `agent-trace-ui`).
+
+### Changed
+
+- `version`: `0.3.1` → `0.3.2`.
+
 ## [0.3.1] - 2026-05-06
 
 **9-package lockstep patch cut.** All 9 published `@adia-ai/*` packages bump 0.3.0 → 0.3.1 per [`docs/specs/package-architecture.md` § 15](../../../docs/specs/package-architecture.md#15-versioning-policy). Internal `@adia-ai/*` dep ranges remain at `^0.3.0` (covers `0.3.1` under semver — patch-cut asymmetry).

package/core/generator.js

@@ -185,6 +185,37 @@ export async function generateUI({ intent, engine: engineName = 'monolithic', mo
   // Strip the _debug payload before returning — it's an internal collaboration
   // channel between engines and the recorder, not part of the public API.
   // Without this strip the proxy would echo a 12KB+ system prompt to clients.
+  //
+  // Compose-trace flag: A2UI_COMPOSE_TRACE=<dir> writes the full debug payload
+  // (system prompt, raw LLM response, retrieval log, strategy decisions) to
+  // a per-request JSON file BEFORE the strip. Useful for debugging
+  // strategy-label decisions or reproducing eval failures. Off by default;
+  // file writes happen synchronously and add ~1-5ms per request.
+  const traceDir = process.env.A2UI_COMPOSE_TRACE;
+  if (traceDir && result._debug) {
+    try {
+      const { writeFile, mkdir } = await import('node:fs/promises');
+      const { join: pathJoin } = await import('node:path');
+      await mkdir(traceDir, { recursive: true });
+      const ts = new Date().toISOString().replace(/[:.]/g, '-');
+      const safeIntent = String(intent || 'unknown').slice(0, 40).replace(/[^a-zA-Z0-9_-]/g, '_');
+      const tracePath = pathJoin(traceDir, `${ts}-${engineName}-${safeIntent}.json`);
+      await writeFile(tracePath, JSON.stringify({
+        timestamp: ts,
+        intent,
+        engine: engineName,
+        mode: effectiveMode,
+        executionId: result.executionId,
+        strategy: result.strategy || null,
+        validation: result.validation || null,
+        messageCount: result.messages?.length || 0,
+        debug: result._debug,
+      }, null, 2));
+    } catch (err) {
+      // Tracing is diagnostic — never let it break the request path.
+      console.error('[compose:trace] failed to write trace:', err.message);
+    }
+  }
   if (result._debug) delete result._debug;
   return result;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/a2ui-compose",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "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": {
@@ -39,4 +39,4 @@
     "@adia-ai/a2ui-validator": "^0.3.0",
     "@adia-ai/llm": "^0.3.0"
   }
-}
+}

package/strategies/zettel/chunk-synthesizer.js

@@ -35,8 +35,8 @@ const DEFAULT_MAX_ATTEMPTS = 2;
 // chunks' component counts. A multiplier > SCOPE_DRIFT_RATIO trips a warning
 // + auto-fires a `scope-drift` issue. Floor prevents false positives on
 // small UIs where slot-wrapper noise dominates.
-const SCOPE_DRIFT_RATIO = 1.5;
-const SCOPE_DRIFT_MIN_ACTUAL = 20;
+export const SCOPE_DRIFT_RATIO = 1.5;
+export const SCOPE_DRIFT_MIN_ACTUAL = 20;
 
 const SYSTEM_PROMPT = `You compose web-app pages by binding training chunks into named slots.
 
@@ -397,7 +397,7 @@ function countComponents(html) {
  * Returns { actual, expected, ratio, drift } where `drift` is true when
  * actual exceeds SCOPE_DRIFT_RATIO × expected AND actual ≥ SCOPE_DRIFT_MIN_ACTUAL.
  */
-function computeScopeDrift(html, boundChunks) {
+export function computeScopeDrift(html, boundChunks) {
   const actual = countComponents(html);
   let expected = 0;
   for (const c of boundChunks) {

package/strategies/zettel/chunk-synthesizer.test.js

@@ -0,0 +1,97 @@
+import { describe, it, expect } from 'vitest';
+import {
+  computeScopeDrift,
+  SCOPE_DRIFT_RATIO,
+  SCOPE_DRIFT_MIN_ACTUAL,
+} from './chunk-synthesizer.js';
+
+// countComponents() in chunk-synthesizer counts elements that look like A2UI
+// component instances. The exact regex matters for these tests; we synthesize
+// HTML that's representative of real composed output.
+function gridOfCards(n) {
+  const cards = Array.from({ length: n }, (_, i) =>
+    `<card-ui id="c${i}"><header-ui slot="heading">Card ${i}</header-ui><text-ui>body</text-ui></card-ui>`
+  ).join('');
+  return `<grid-ui columns="3">${cards}</grid-ui>`;
+}
+
+describe('SCOPE_DRIFT_RATIO + computeScopeDrift', () => {
+  it('exports the constants', () => {
+    expect(SCOPE_DRIFT_RATIO).toBe(1.5);
+    expect(SCOPE_DRIFT_MIN_ACTUAL).toBe(20);
+  });
+
+  it('reports no drift when actual ≤ expected', () => {
+    // 25 cards composed from a chunk with 25 cards
+    const html = gridOfCards(25);
+    const chunk = { html: gridOfCards(25) };
+    const drift = computeScopeDrift(html, [chunk]);
+    expect(drift.actual).toBeGreaterThanOrEqual(SCOPE_DRIFT_MIN_ACTUAL);
+    expect(drift.expected).toBeGreaterThanOrEqual(SCOPE_DRIFT_MIN_ACTUAL);
+    expect(drift.ratio).toBeLessThanOrEqual(1);
+    expect(drift.drift).toBe(false);
+  });
+
+  it('reports no drift when ratio is below the gate (1.0 < ratio ≤ 1.5)', () => {
+    // 30 cards composed from 25 — ratio 1.2× below the 1.5× gate
+    const html = gridOfCards(30);
+    const chunk = { html: gridOfCards(25) };
+    const drift = computeScopeDrift(html, [chunk]);
+    expect(drift.ratio).toBeGreaterThan(1.0);
+    expect(drift.ratio).toBeLessThanOrEqual(SCOPE_DRIFT_RATIO);
+    expect(drift.drift).toBe(false);
+  });
+
+  it('reports drift when ratio exceeds the gate (ratio > 1.5)', () => {
+    // 50 cards composed from 25 — ratio 2.0× exceeds the 1.5× gate
+    const html = gridOfCards(50);
+    const chunk = { html: gridOfCards(25) };
+    const drift = computeScopeDrift(html, [chunk]);
+    expect(drift.actual).toBeGreaterThanOrEqual(SCOPE_DRIFT_MIN_ACTUAL);
+    expect(drift.ratio).toBeGreaterThan(SCOPE_DRIFT_RATIO);
+    expect(drift.drift).toBe(true);
+  });
+
+  it('does not trip the drift floor on small UIs (actual < SCOPE_DRIFT_MIN_ACTUAL)', () => {
+    // Tiny html (5 tags) vs even-tinier chunk (1 tag) — ratio 5× far above
+    // gate, but actual=5 < 20 floor
+    const html = '<div><span></span><span></span><span></span><span></span></div>';
+    const chunk = { html: '<div></div>' };
+    const drift = computeScopeDrift(html, [chunk]);
+    expect(drift.actual).toBeLessThan(SCOPE_DRIFT_MIN_ACTUAL);
+    expect(drift.ratio).toBeGreaterThan(SCOPE_DRIFT_RATIO);
+    expect(drift.drift).toBe(false); // floor prevents false positive on tiny UIs
+  });
+
+  it('handles the malformed-corpus case (zero-expected, non-zero actual)', () => {
+    // Bound chunk has no html field at all
+    const html = gridOfCards(50);
+    const chunk = { /* no html */ };
+    const drift = computeScopeDrift(html, [chunk]);
+    expect(drift.expected).toBe(0);
+    expect(drift.ratio).toBe(null); // guard returns null instead of Infinity
+    expect(drift.drift).toBe(false); // gate is skipped, not failed
+  });
+
+  it('aggregates expected across multiple bound chunks', () => {
+    // 30 actual; bound chunks 10 + 12 = 22 expected; ratio 30/22 ≈ 1.36 < 1.5
+    const html = gridOfCards(30);
+    const chunks = [
+      { html: gridOfCards(10) },
+      { html: gridOfCards(12) },
+    ];
+    const drift = computeScopeDrift(html, chunks);
+    expect(drift.expected).toBeGreaterThanOrEqual(22);
+    expect(drift.ratio).toBeLessThanOrEqual(SCOPE_DRIFT_RATIO);
+    expect(drift.drift).toBe(false);
+  });
+
+  it('reads chunk html from instances[0] when top-level html is absent', () => {
+    // Multi-instance chunk format: { name, instances: [{ html, ... }, ...] }
+    const html = gridOfCards(25);
+    const chunk = { name: 'multi', instances: [{ html: gridOfCards(25) }] };
+    const drift = computeScopeDrift(html, [chunk]);
+    expect(drift.expected).toBeGreaterThanOrEqual(SCOPE_DRIFT_MIN_ACTUAL);
+    expect(drift.drift).toBe(false);
+  });
+});

package/strategies/zettel/composer.js

@@ -18,13 +18,30 @@
 
 import { getFragment } from './fragment-library.js';
 
+/**
+ * Separator used when prefixing a fragment's internal node ids with the
+ * composition node id. Format: `{compNode}{ID_PREFIX_SEPARATOR}{fragNode}`.
+ *
+ * Why double-dash: single `-` collides with kebab-case ids that primitives
+ * commonly emit (`auth-card-header`, `card-header-heading`); double-dash
+ * has no observed natural occurrence in either composition node ids or
+ * fragment node ids, so the parse is unambiguous if anyone ever needs to
+ * reverse the prefixing.
+ *
+ * EXTERNAL CONTRACT: the renderer treats node ids as opaque strings, so
+ * changing this separator does not break A2UI consumers. But anything
+ * upstream that splits on `--` (issue-reporter ticket rendering, eval
+ * trace inspection, debug logs) will need to be updated in lockstep.
+ */
+export const ID_PREFIX_SEPARATOR = '--';
+
 function cloneFragmentWithPrefix(fragment, prefix) {
   const idMap = new Map();
   const cloned = fragment.template.map((n) => ({ ...n }));
 
   // Generate new ids
   for (const node of cloned) {
-    const newId = `${prefix}--${node.id}`;
+    const newId = `${prefix}${ID_PREFIX_SEPARATOR}${node.id}`;
     idMap.set(node.id, newId);
   }
   // Rewrite ids and children refs

package/strategies/zettel/generator-adapter.js

@@ -30,6 +30,7 @@ import {
   getTurns,
   buildHistorySummary,
 } from './session-store.js';
+import { autoReport } from './issue-reporter.js';
 import { validateSchema } from '../../../validator/validator.js';
 
 let booted = false;
@@ -40,6 +41,18 @@ function ensureBooted() {
   }
 }
 
+// NOTE on cache invalidation: `loadAll()` itself reloads fragments + compositions
+// from disk every time it's called — `fragments.clear()` + `compositions.clear()`
+// at the top, then re-walk. The CACHING happens here at the call-site: we set
+// `booted = true` after the first load and never reload for the lifetime of
+// this process. Trade-offs:
+//   - GOOD for long-running MCP: zero corpus-load cost on subsequent requests.
+//   - BAD for tests / hot-reload: a fresh fragment file isn't visible until
+//     the process restarts.
+// To force a reload (e.g. in a test that just wrote a new fragment file),
+// call `loadAll()` directly — it's idempotent. The `booted` flag here is a
+// process-singleton optimization, not a correctness invariant.
+
 // Retrieval score threshold — above this we trust the match and emit verbatim;
 // below, fall through to LLM synthesis (creative composition from fragments).
 // Calibrated on the 100-intent held-out set:
@@ -105,8 +118,25 @@ export async function generateZettel({ intent, mode = 'instant', llmAdapter = nu
       };
     } catch (err) {
       // If iteration synthesis fails, fall through to the normal path. Record
-      // the failure so the next turn can see we tried.
+      // the failure so the next turn can see we tried, and auto-fire an issue
+      // ticket so synthesis-owners can investigate the failure post-hoc.
       console.error('[zettel] iteration synthesis failed:', err.message);
+      try {
+        await autoReport(
+          'iteration-synthesis-failure',
+          {
+            intent,
+            turn: priorTurns.length + 1,
+            state_id: sessionId,
+            body: `Auto-fired by generator-adapter. Iteration synthesis threw on turn ${priorTurns.length + 1}.\n\nError: \`${err.message}\``,
+            tags: ['generator-adapter', `turn-${priorTurns.length + 1}`],
+          },
+          { evalMode: mode === 'eval' }
+        );
+      } catch (reportErr) {
+        // Never let issue-reporting crash the request path.
+        console.error('[zettel] autoReport failed:', reportErr.message);
+      }
     }
   }
 

package/strategies/zettel/issue-reporter.js

@@ -85,6 +85,16 @@ export const AUTO_FIRE_POLICY = {
       return `Scope drift${ratio ? ' ' + ratio : ''}: composed HTML exceeds bound-chunk envelope${intent}`;
     },
   },
+  'iteration-synthesis-failure': {
+    type: 'bug',
+    severity: 'drift',
+    suggested_owner: 'synthesis',
+    titleFor: (ctx) => {
+      const turn = ctx?.turn != null ? ` on turn ${ctx.turn}` : '';
+      const intent = ctx?.intent ? ` for "${truncate(ctx.intent, 40)}"` : '';
+      return `Iteration synthesis failed${turn}${intent}`;
+    },
+  },
 };
 
 function truncate(s, n = 60) {