@adia-ai/a2ui-compose 0.3.1 → 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.1",
+  "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": {

package/strategies/registry.js

@@ -118,11 +118,39 @@ async function generateZettelAdapter(ctx) {
   };
 }
 
+async function generateChunkZettelAdapter(ctx) {
+  const { composeFromIntent } = await import('./zettel/chunk-synthesizer.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 }] }]
+    : [];
+
+  return {
+    executionId: ctx.executionId,
+    messages,
+    validation: { score: result.html ? 70 : 0 },
+    strategy: result.source === 'retrieval' ? 'chunk-retrieval' : 'chunk-synthesis',
+    engine: 'chunk-zettel',
+    _debug: {
+      plan: result.plan || null,
+      warnings: result.warnings || [],
+      scopeDrift: result.scopeDrift || null,
+    },
+  };
+}
+
 export const ENGINES = {
   'monolithic-instant':  generateInstantAdapter,
   'monolithic-pro':      generateProAdapter,
   'monolithic-thinking': generateThinkingAdapter,
   'zettel':              generateZettelAdapter,
+  'chunk-zettel':        generateChunkZettelAdapter,
 };
 
 /**
@@ -147,7 +175,7 @@ export const ENGINES = {
  *   });
  *   generateUI({ engine: 'my-hybrid', intent: '...' });
  */
-const RESERVED = new Set(['monolithic', 'monolithic-instant', 'monolithic-pro', 'monolithic-thinking', 'zettel']);
+const RESERVED = new Set(['monolithic', 'monolithic-instant', 'monolithic-pro', 'monolithic-thinking', 'zettel', 'chunk-zettel']);
 
 export function registerEngine(name, generateFn) {
   if (typeof name !== 'string' || !name.length) {

package/strategies/zettel/chunk-synthesizer.js

@@ -35,36 +35,61 @@ 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.
 
-You are given:
-  - A user intent (what they want to build).
-  - A catalog of available chunks. Each chunk is a discrete UI sample harvested
-    from a real page. Chunks have:
-      - name (stable ID)
-      - kind ("page", "panel", or "block")
-      - primary (the chunk's outermost element, e.g. "card-ui", "grid-ui")
-      - slots (only on page/panel chunks — named regions where blocks plug in)
-  - 1-3 example bindings as in-context anchors.
+## YOUR TASK
+
+Given a user intent and a catalog of chunks, return a JSON object that:
+1. SELECTS the most appropriate page-kind shell
+2. BINDS block/panel chunks into its slots
+
+## STEP 1 — SELECT A PAGE SHELL
+
+Page shells (kind=page or kind=panel) define the layout topology. Match the
+intent domain to the right shell — NEVER default to dashboard-admin-page for
+non-dashboard intents:
+
+| Shell | Domain | Slots |
+|-------|--------|-------|
+| dashboard-admin-page | Admin/analytics dashboards | page-header, page-content |
+| settings-page-shell | Settings, preferences, configuration | page-header, page-tabs, page-content |
+| form-page-shell | Auth forms, sign-in, sign-up, profile | page-header, form-content, page-footer |
+| marketing-page-shell | Landing pages, heroes, features, CTAs | hero, features, cta |
+| error-page-shell | Error states (404, 500, permission denied) | error-content, navigation |
+| editor-page-shell | Split-pane editors (code + preview) | editor-pane, preview-pane |
+| onb-step-shell | Onboarding wizards, multi-step flows | page-story, page-header, page-content, page-footer |
+| reg-step-shell | Registration flows, multi-step sign-up | page-story, page-header, page-content, page-footer |
+
+Selection rule: the shell whose DOMAIN matches the intent keywords wins.
+
+## STEP 2 — SELECT BLOCKS TO FILL SLOTS
+
+- Search the block catalog for chunks whose name contains intent keywords.
+- Prefer blocks whose primary tag matches the desired component (e.g.
+  "stat-ui" for stat cards, "chart-ui" for charts).
+- If a slot is optional and no matching block exists, OMIT it rather
+  than forcing a random block.
+- Never invent chunk names. Every bound name must appear in the catalog.
+
+## STEP 3 — RETURN JSON
 
 Return ONLY a JSON object shaped exactly like:
 {
-  "page": "<name of a page-kind chunk to use as the layout shell>",
+  "page": "<name of page-kind chunk>",
   "slot_bindings": {
-    "<slot-name>": "<bound chunk name>"        // single chunk
+    "<slot-name>": "<bound chunk name>"
     OR
-    "<slot-name>": ["<chunk1>", "<chunk2>"]    // ordered list of chunks
+    "<slot-name>": ["<chunk1>", "<chunk2>"]
   }
 }
 
 Rules:
 - The "page" must be a chunk with kind="page" or kind="panel".
-- Every slot you bind must be declared by the page chunk (do not invent slots).
-- Bound chunks should be kind="block" or kind="panel" — pages can't nest inside
-  pages.
+- Every slot key must be declared by the chosen page shell.
+- Every bound value must be a real chunk name from the catalog.
 - Return valid JSON. No prose, no comments, no markdown fences. Begin with "{".
 `;
 
@@ -78,8 +103,8 @@ function buildCatalogSummary(chunks) {
 }
 
 function buildExamples() {
-  // Hard-coded canonical example: "build me an admin dashboard". This anchors
-  // the LLM on the expected output shape.
+  // Four canonical examples spanning different domains. Diverse examples
+  // prevent the LLM from defaulting to dashboard-shaped output.
   return [
     {
       intent: 'admin dashboard with KPIs and a conversion funnel',
@@ -91,6 +116,38 @@ function buildExamples() {
         },
       },
     },
+    {
+      intent: 'sign-in form with email and password',
+      output: {
+        page: 'form-page-shell',
+        slot_bindings: {
+          'page-header': 'auth-signin-card-password',
+          'form-content': 'auth-email-entry',
+        },
+      },
+    },
+    {
+      intent: 'settings page with tabs for general and billing',
+      output: {
+        page: 'settings-page-shell',
+        slot_bindings: {
+          'page-header': 'settings-general-form',
+          'page-tabs': 'check-combinations-settings-group',
+          'page-content': 'settings-general-form',
+        },
+      },
+    },
+    {
+      intent: 'marketing landing hero with feature cards',
+      output: {
+        page: 'marketing-page-shell',
+        slot_bindings: {
+          hero: 'hero-cta-simple',
+          features: 'empty-state-action',
+          cta: 'button-primary',
+        },
+      },
+    },
   ];
 }
 
@@ -150,23 +207,31 @@ export async function composeFromIntent({ intent, llmAdapter, maxAttempts = DEFA
   //
   // Restricted to kind=block: page/panel chunks are SKELETONS that need
   // slot-binding composition (Tier 2 handles them). Returning a skeleton
-  // directly from Tier-1 would emit a near-empty page; we only want the
-  // fast-path for atomic block patterns.
-  const hits = await searchChunksAsync(intent, { kind: 'block', limit: 5 });
-  if (hits.length > 0 && hits[0].score >= STRONG_RETRIEVAL_SCORE) {
-    const top = getChunk(hits[0].name);
+  // Fast path — deterministic keyword-first; embeddings as tie-breaker only.
+  // Embeddings can drift (e.g. "pane" matching "panel" boosting unrelated
+  // chunks). Sync keyword search is stable and keyword-discoverability is
+  // the baseline guarantee. We run both and prefer the sync result when
+  // it meets the threshold; only use async when sync is weak but async
+  // is strong (e.g. semantic match on content not captured by keywords).
+  const syncHits = searchChunks(intent, { kind: 'block', limit: 5 });
+  const asyncHits = await searchChunksAsync(intent, { kind: 'block', limit: 5 });
+
+  const syncTop = syncHits[0];
+  const asyncTop = asyncHits[0];
+  const useSync = syncTop && syncTop.score >= STRONG_RETRIEVAL_SCORE;
+  const useAsync = !useSync && asyncTop && asyncTop.score >= STRONG_RETRIEVAL_SCORE;
+
+  if (useSync || useAsync) {
+    const hit = useSync ? syncTop : asyncTop;
+    const top = getChunk(hit.name);
     const html = top.html || top.instances?.[0]?.html || '';
-    // Tier-1 fast path: sole bound chunk is the retrieved block. The gate
-    // is mostly a no-op here (ratio ≈ 1) but stays for symmetry — and to
-    // catch a corner case where retrieval returns a block that, post-render,
-    // expands far beyond its source (shouldn't happen, but worth detecting).
     const scopeDrift = computeScopeDrift(html, [top]);
     return {
       html,
       plan: null,
       source: 'retrieval',
-      score: hits[0].score,
-      cosineScore: hits[0].cosineScore,
+      score: hit.score,
+      cosineScore: hit.cosineScore,
       warnings: scopeDrift.drift
         ? [`scope drift: ${scopeDrift.actual} components in HTML vs ${scopeDrift.expected} in bound chunk (ratio ${scopeDrift.ratio.toFixed(2)}×)`]
         : [],
@@ -211,15 +276,16 @@ export async function composeFromIntent({ intent, llmAdapter, maxAttempts = DEFA
   // Trace: snapshot of the retrieval log for the issue-reporter to surface
   // verbatim on bug tickets. Recorded once before the retry loop so it
   // describes what the LLM actually saw.
+  const tier1HitList = useSync ? syncHits : (useAsync ? asyncHits : []);
   const retrievalTrace = {
-    tier1Hits: hits.slice(0, 5).map((h) => ({
+    tier1Hits: tier1HitList.slice(0, 5).map((h) => ({
       name: h.name,
       score: Number(h.score.toFixed(3)),
       kind: h.kind,
       cosineScore: h.cosineScore != null ? Number(h.cosineScore.toFixed(3)) : null,
     })),
     tier1Threshold: STRONG_RETRIEVAL_SCORE,
-    tier1Pass: hits.length > 0 && hits[0].score >= STRONG_RETRIEVAL_SCORE,
+    tier1Pass: tier1HitList.length > 0 && tier1HitList[0].score >= STRONG_RETRIEVAL_SCORE,
     catalogSize: filtered.length,
     catalogPageNames: pageChunks.map((c) => c.name),
     catalogPanelNames: panelChunks.map((c) => c.name),
@@ -331,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) {