@adia-ai/a2ui-mcp 0.0.5 → 0.1.1

package/scripts/smoke-refine.mjs

@@ -0,0 +1,374 @@
+#!/usr/bin/env node
+// Smoke test: chunk-refiner (validator + applier + 2-pass synthesis with stub LLM).
+// Spec: docs/specs/genui-multiturn-architecture.md §4.
+
+import {
+  refineFromIntent,
+  applyOps,
+  validateOps,
+  opsToA2UI,
+} from '../../compose/engines/zettel/chunk-refiner.js';
+import {
+  StateCache,
+  mintStateId,
+  mintNextStateId,
+} from '../../compose/engines/zettel/state-cache.js';
+import { createIssueAccumulator } from '../../compose/engines/zettel/issue-reporter.js';
+import {
+  getChunk,
+  listChunksByKind,
+} from '../../../a2ui/corpus/scripts/chunk-library.js';
+
+let pass = 0, fail = 0;
+const t = (label, ok, detail = '') => {
+  if (ok) { console.log(`  ✓ ${label}`); pass++; }
+  else    { console.log(`  ✗ ${label}  ${detail}`); fail++; }
+};
+
+// --- Discover real corpus chunks for happy-path tests ---
+const pageChunks = listChunksByKind('page');
+const panelChunks = listChunksByKind('panel');
+const blockChunks = listChunksByKind('block');
+
+if (pageChunks.length === 0 || blockChunks.length < 3) {
+  console.error(`Corpus missing required chunks (pages=${pageChunks.length}, blocks=${blockChunks.length}). Aborting.`);
+  process.exit(2);
+}
+
+// Pick a page chunk that actually has slots (not all do)
+const samplePage = pageChunks.find((p) => (p.slots || p.instances?.[0]?.slots || []).length >= 1)
+  || panelChunks.find((p) => (p.slots || p.instances?.[0]?.slots || []).length >= 1)
+  || pageChunks[0];
+const samplePageSlots = (samplePage.slots || samplePage.instances?.[0]?.slots || []).map((s) => s.name);
+
+if (samplePageSlots.length === 0) {
+  console.error('No page chunk with declared slots; skipping LLM-driven tests.');
+  process.exit(2);
+}
+
+const sampleBlocks = blockChunks.slice(0, 5).map((b) => b.name);
+const targetedSlot = samplePageSlots[0];
+
+console.log(`Using page: ${samplePage.name} (slots: ${samplePageSlots.join(', ')})`);
+console.log(`Sample blocks: ${sampleBlocks.slice(0, 3).join(', ')}\n`);
+
+const priorState = {
+  state_id: mintStateId('test-prior', 1),
+  intent: 'test prior composition',
+  plan: {
+    page: samplePage.name,
+    slot_bindings: {
+      [targetedSlot]: [sampleBlocks[0]],
+      ...(samplePageSlots[1] ? { [samplePageSlots[1]]: [sampleBlocks[1], sampleBlocks[2]] } : {}),
+    },
+  },
+  html: '<placeholder/>',
+};
+
+console.log('=== validateOps ===');
+
+t('rejects non-array ops',
+  validateOps('not-array', priorState).ok === false);
+t('rejects priorState without plan',
+  validateOps([], { state_id: 'x' }).ok === false);
+t('accepts empty ops list', validateOps([], priorState).ok === true);
+
+const okRebind = validateOps(
+  [{ type: 'rebindSlot', slot: targetedSlot, chunks: [sampleBlocks[3]] }],
+  priorState,
+);
+t('accepts rebindSlot with valid chunk', okRebind.ok === true);
+
+const okAppend = validateOps(
+  [{ type: 'appendToSlot', slot: targetedSlot, chunks: [sampleBlocks[3], sampleBlocks[4]] }],
+  priorState,
+);
+t('accepts appendToSlot with valid chunks', okAppend.ok === true);
+
+const okRemove = validateOps(
+  [{ type: 'removeFromSlot', slot: targetedSlot, indices: [0] }],
+  priorState,
+);
+t('accepts removeFromSlot with valid index', okRemove.ok === true);
+
+// Negative cases
+const badType = validateOps([{ type: 'frobnicate', slot: targetedSlot }], priorState);
+t('rejects unknown op type',
+  badType.ok === false && /unknown op type/.test(badType.errors[0]));
+
+const badSlot = validateOps(
+  [{ type: 'rebindSlot', slot: 'not-a-real-slot', chunks: [sampleBlocks[0]] }],
+  priorState,
+);
+t('rejects unknown slot',
+  badSlot.ok === false && badSlot.errors.some((e) => /not in prior plan/.test(e)));
+
+const badChunk = validateOps(
+  [{ type: 'rebindSlot', slot: targetedSlot, chunks: ['not-a-real-chunk-xyz'] }],
+  priorState,
+);
+t('rejects unknown chunk reference',
+  badChunk.ok === false && badChunk.errors.some((e) => /not found/.test(e)));
+
+const badIndex = validateOps(
+  [{ type: 'removeFromSlot', slot: targetedSlot, indices: [99] }],
+  priorState,
+);
+t('rejects out-of-range index',
+  badIndex.ok === false && badIndex.errors.some((e) => /out of range/.test(e)));
+
+const emptyChunks = validateOps(
+  [{ type: 'rebindSlot', slot: targetedSlot, chunks: [] }],
+  priorState,
+);
+t('rejects empty chunks array',
+  emptyChunks.ok === false && emptyChunks.errors.some((e) => /non-empty/.test(e)));
+
+const replacePageOk = validateOps(
+  [{ type: 'replacePage', page: samplePage.name, slot_bindings: {} }],
+  priorState,
+);
+t('accepts replacePage with valid page', replacePageOk.ok === true);
+
+const replacePageBad = validateOps(
+  [{ type: 'replacePage', page: 'no-such-page' }],
+  priorState,
+);
+t('rejects replacePage with unknown page',
+  replacePageBad.ok === false && replacePageBad.errors.some((e) => /not found/.test(e)));
+
+console.log('\n=== applyOps ===');
+
+const applyRebind = await applyOps({
+  priorState,
+  ops: [{ type: 'rebindSlot', slot: targetedSlot, chunks: [sampleBlocks[3]] }],
+});
+t('rebindSlot replaces slot bindings',
+  applyRebind.newState.plan.slot_bindings[targetedSlot].length === 1 &&
+  applyRebind.newState.plan.slot_bindings[targetedSlot][0] === sampleBlocks[3]);
+t('rebindSlot returns op in ops_applied', applyRebind.ops_applied.length === 1);
+t('rebindSlot returns empty ops_failed', applyRebind.ops_failed.length === 0);
+
+const applyAppend = await applyOps({
+  priorState,
+  ops: [{ type: 'appendToSlot', slot: targetedSlot, chunks: [sampleBlocks[3]] }],
+});
+t('appendToSlot adds to existing bindings',
+  applyAppend.newState.plan.slot_bindings[targetedSlot].length === 2 &&
+  applyAppend.newState.plan.slot_bindings[targetedSlot].at(-1) === sampleBlocks[3]);
+
+const applyRemove = await applyOps({
+  priorState,
+  ops: [{ type: 'removeFromSlot', slot: targetedSlot, indices: [0] }],
+});
+t('removeFromSlot drops indexed entry',
+  applyRemove.newState.plan.slot_bindings[targetedSlot].length === 0);
+
+const applyReplace = await applyOps({
+  priorState,
+  ops: [{
+    type: 'replacePage',
+    page: samplePage.name,
+    slot_bindings: { [targetedSlot]: [sampleBlocks[4]] },
+  }],
+});
+t('replacePage swaps page reference', applyReplace.newState.plan.page === samplePage.name);
+t('replacePage replaces slot_bindings entirely',
+  applyReplace.newState.plan.slot_bindings[targetedSlot].length === 1);
+
+const applyMixed = await applyOps({
+  priorState,
+  ops: [
+    { type: 'rebindSlot', slot: targetedSlot, chunks: [sampleBlocks[3]] },
+    { type: 'appendToSlot', slot: targetedSlot, chunks: [sampleBlocks[4]] },
+  ],
+});
+t('multiple ops apply in sequence',
+  applyMixed.newState.plan.slot_bindings[targetedSlot].length === 2 &&
+  applyMixed.newState.plan.slot_bindings[targetedSlot][0] === sampleBlocks[3] &&
+  applyMixed.newState.plan.slot_bindings[targetedSlot][1] === sampleBlocks[4]);
+
+const applyOriginalUntouched = priorState.plan.slot_bindings[targetedSlot];
+t('priorState plan not mutated by applyOps',
+  Array.isArray(applyOriginalUntouched) && applyOriginalUntouched[0] === sampleBlocks[0]);
+
+const applyMixedFail = await applyOps({
+  priorState,
+  ops: [
+    { type: 'rebindSlot', slot: targetedSlot, chunks: [sampleBlocks[3]] },
+    { type: 'frobnicate' },
+  ],
+});
+t('apply continues past failed ops',
+  applyMixedFail.ops_applied.length === 1 && applyMixedFail.ops_failed.length === 1);
+
+console.log('\n=== opsToA2UI ===');
+
+const wireMessages = opsToA2UI(
+  [{ type: 'rebindSlot', slot: targetedSlot, chunks: [sampleBlocks[3]] }],
+  applyRebind.newState,
+);
+t('opsToA2UI emits one updateComponents per op',
+  wireMessages.length === 1 && wireMessages[0].type === 'updateComponents');
+t('opsToA2UI components target slot id', wireMessages[0].components[0].id === `slot-${targetedSlot}`);
+t('opsToA2UI carries chunk_op echo', wireMessages[0].components[0].chunk_op?.type === 'rebindSlot');
+t('opsToA2UI sets surfaceId', wireMessages[0].surfaceId === 'main');
+
+const wireReplace = opsToA2UI(
+  [{ type: 'replacePage', page: samplePage.name, slot_bindings: {} }],
+  applyReplace.newState,
+);
+t('opsToA2UI replacePage targets surface id', wireReplace[0].components[0].id === 'main');
+
+console.log('\n=== refineFromIntent (stub LLM) ===');
+
+function makeStubLLM(queue) {
+  const responses = [...queue];
+  return {
+    complete: async () => {
+      if (responses.length === 0) throw new Error('stub LLM: queue empty');
+      const r = responses.shift();
+      return { content: typeof r === 'string' ? r : JSON.stringify(r) };
+    },
+    remaining: () => responses.length,
+  };
+}
+
+// Happy path — targeted refinement
+const stubHappy = makeStubLLM([
+  { targeted: true, target_slots: [targetedSlot] },
+  {
+    ops: [{ type: 'rebindSlot', slot: targetedSlot, chunks: [sampleBlocks[3]] }],
+    delta_summary: `replaced ${targetedSlot} binding`,
+  },
+]);
+const refineHappy = await refineFromIntent({
+  priorState,
+  intent: `change ${targetedSlot} to use ${sampleBlocks[3]}`,
+  llmAdapter: stubHappy,
+  catalog: [{ name: sampleBlocks[3], kind: 'block', primary: 'div', slots: [] }],
+});
+t('happy-path: returns ops', refineHappy.ops.length === 1);
+t('happy-path: synthesis.targeted=true', refineHappy.synthesis.targeted === true);
+t('happy-path: synthesis.locatedTargets matches', refineHappy.synthesis.locatedTargets[0] === targetedSlot);
+t('happy-path: synthesis.attempts=1', refineHappy.synthesis.attempts === 1);
+t('happy-path: delta_summary set', !!refineHappy.delta_summary);
+t('happy-path: empty warnings', refineHappy.warnings.length === 0);
+t('happy-path: stub LLM exhausted', stubHappy.remaining() === 0);
+
+// Validator-driven retry — first response invalid, second valid
+const stubRetry = makeStubLLM([
+  { targeted: true, target_slots: [targetedSlot] },
+  { ops: [{ type: 'rebindSlot', slot: 'not-real', chunks: [sampleBlocks[3]] }], delta_summary: 'bad' },
+  { ops: [{ type: 'rebindSlot', slot: targetedSlot, chunks: [sampleBlocks[3]] }], delta_summary: 'fixed' },
+]);
+const refineRetry = await refineFromIntent({
+  priorState,
+  intent: `change ${targetedSlot}`,
+  llmAdapter: stubRetry,
+  maxAttempts: 2,
+  catalog: [{ name: sampleBlocks[3], kind: 'block', primary: 'div', slots: [] }],
+});
+t('retry: succeeds on second attempt', refineRetry.ops.length === 1);
+t('retry: synthesis.attempts=2', refineRetry.synthesis.attempts === 2);
+t('retry: attemptsLog has both attempts', refineRetry.synthesis.attemptsLog.length === 2);
+
+// Validator-exhausted — both attempts invalid
+const accExhausted = createIssueAccumulator();
+const stubExhaust = makeStubLLM([
+  { targeted: true, target_slots: [targetedSlot] },
+  { ops: [{ type: 'rebindSlot', slot: 'not-real-1', chunks: [sampleBlocks[3]] }], delta_summary: 'bad1' },
+  { ops: [{ type: 'rebindSlot', slot: 'not-real-2', chunks: [sampleBlocks[3]] }], delta_summary: 'bad2' },
+]);
+const refineExhaust = await refineFromIntent({
+  priorState,
+  intent: `change ${targetedSlot}`,
+  llmAdapter: stubExhaust,
+  maxAttempts: 2,
+  issueAccumulator: accExhausted,
+  catalog: [{ name: sampleBlocks[3], kind: 'block', primary: 'div', slots: [] }],
+});
+t('exhausted: returns empty ops', refineExhaust.ops.length === 0);
+t('exhausted: warnings include "failed after 2 attempts"',
+  refineExhaust.warnings[0].includes('failed after 2 attempts'));
+t('exhausted: auto-fires "validator-exhausted"',
+  accExhausted.reasons().includes('validator-exhausted'));
+
+// locator-empty-targets: targeted=true but no slots returned
+const accEmpty = createIssueAccumulator();
+const stubEmpty = makeStubLLM([
+  { targeted: true, target_slots: [] },
+  { ops: [], delta_summary: 'no-op' },
+]);
+await refineFromIntent({
+  priorState,
+  intent: 'change something specific',
+  llmAdapter: stubEmpty,
+  issueAccumulator: accEmpty,
+  catalog: [],
+});
+t('locator-empty: auto-fires "locator-empty-targets"',
+  accEmpty.reasons().includes('locator-empty-targets'));
+
+// Untargeted intent — no auto-fire on locator-empty
+const accUntargeted = createIssueAccumulator();
+const stubUntargeted = makeStubLLM([
+  { targeted: false, target_slots: [] },
+  { ops: [], delta_summary: 'no-op' },
+]);
+await refineFromIntent({
+  priorState,
+  intent: 'preserve everything',
+  llmAdapter: stubUntargeted,
+  issueAccumulator: accUntargeted,
+  catalog: [],
+});
+t('untargeted: no auto-fire on locator-empty',
+  !accUntargeted.reasons().includes('locator-empty-targets'));
+
+// Missing llmAdapter — graceful fail
+const refineNoLLM = await refineFromIntent({
+  priorState,
+  intent: 'anything',
+  llmAdapter: null,
+});
+t('no llmAdapter: returns empty ops', refineNoLLM.ops.length === 0);
+t('no llmAdapter: warnings include "no llmAdapter"',
+  refineNoLLM.warnings[0].includes('no llmAdapter'));
+
+// Missing priorState plan — graceful fail
+const refineNoPlan = await refineFromIntent({
+  priorState: { state_id: 'x' },
+  intent: 'anything',
+  llmAdapter: makeStubLLM([{ targeted: false, target_slots: [] }]),
+});
+t('no priorState.plan: returns empty ops', refineNoPlan.ops.length === 0);
+t('no priorState.plan: warnings flag the issue',
+  refineNoPlan.warnings[0].includes('no plan'));
+
+console.log('\n=== integration: refine → apply → wire ===');
+
+const stubE2E = makeStubLLM([
+  { targeted: true, target_slots: [targetedSlot] },
+  {
+    ops: [{ type: 'appendToSlot', slot: targetedSlot, chunks: [sampleBlocks[3]] }],
+    delta_summary: `appended ${sampleBlocks[3]} to ${targetedSlot}`,
+  },
+]);
+const refineE2E = await refineFromIntent({
+  priorState,
+  intent: `add ${sampleBlocks[3]} to ${targetedSlot}`,
+  llmAdapter: stubE2E,
+  catalog: [{ name: sampleBlocks[3], kind: 'block', primary: 'div', slots: [] }],
+});
+const applied = await applyOps({ priorState, ops: refineE2E.ops });
+const a2uiMsgs = opsToA2UI(refineE2E.ops, applied.newState);
+
+t('e2e: refine produces 1 op', refineE2E.ops.length === 1);
+t('e2e: apply succeeds', applied.ops_applied.length === 1 && applied.ops_failed.length === 0);
+t('e2e: a2ui message has updateComponents type', a2uiMsgs[0].type === 'updateComponents');
+t('e2e: applied newState has materialized HTML',
+  applied.newState.html !== null && applied.newState.html.length > 0);
+
+console.log(`\n${pass} passed, ${fail} failed`);
+process.exit(fail ? 1 : 0);

package/scripts/smoke-state-cache.mjs

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+// Smoke test: state-cache (LRU + state-id minting).
+// Spec: docs/specs/genui-multiturn-architecture.md §2.2 + §4.4.
+import {
+  StateCache,
+  mintStateId,
+  mintNextStateId,
+  getStateCache,
+  resetStateCache,
+} from '../../compose/engines/zettel/state-cache.js';
+
+let pass = 0, fail = 0;
+const t = (label, ok, detail = '') => {
+  if (ok) { console.log(`  ✓ ${label}`); pass++; }
+  else    { console.log(`  ✗ ${label}  ${detail}`); fail++; }
+};
+
+console.log('=== State-cache LRU ===');
+
+const cache = new StateCache({ maxSize: 3 });
+t('empty cache size 0', cache.size() === 0);
+t('miss returns null', cache.get('nope') === null);
+t('has returns false on miss', cache.has('nope') === false);
+
+cache.set('a', { intent: 'a', html: '<a/>' });
+cache.set('b', { intent: 'b', html: '<b/>' });
+cache.set('c', { intent: 'c', html: '<c/>' });
+t('size at capacity', cache.size() === 3);
+t('list returns insertion order', JSON.stringify(cache.list()) === JSON.stringify(['a', 'b', 'c']));
+t('has returns true on hit', cache.has('a') && cache.has('b') && cache.has('c'));
+
+// Eviction: 4th set drops oldest
+cache.set('d', { intent: 'd', html: '<d/>' });
+t('LRU evicts oldest on overflow', cache.size() === 3 && !cache.has('a') && cache.has('d'));
+
+// Recency touch via get: bump 'b' to most-recent, then set 'e'.
+// Order before: [b, c, d]. After get('b'): [c, d, b]. After set('e'): evict c → [d, b, e].
+cache.get('b');
+cache.set('e', { intent: 'e', html: '<e/>' });
+t('get touches recency', cache.has('b') && cache.has('e') && !cache.has('c'));
+
+// peek does NOT touch recency.
+// Order: [d, b, e]. peek('b') → unchanged [d, b, e]. set('f') → evict d → [b, e, f].
+const peeked = cache.peek('b');
+t('peek returns entry', peeked?.intent === 'b');
+cache.set('f', { intent: 'f', html: '<f/>' });
+t('peek does not touch recency', cache.has('b') && cache.has('e') && cache.has('f') && !cache.has('d'));
+
+// Update existing key bumps recency.
+// Order before: [b, e, f]. set('b', ...) → delete-then-insert → [e, f, b].
+cache.set('b', { intent: 'b-updated', html: '<b2/>' });
+t('update existing key bumps recency', cache.get('b').intent === 'b-updated');
+t('update preserves cache size', cache.size() === 3);
+
+// Evict
+t('evict returns true on hit', cache.evict('e') === true);
+t('evict returns false on miss', cache.evict('e') === false);
+t('evict drops entry', !cache.has('e') && cache.size() === 2);
+
+// Clear
+cache.clear();
+t('clear empties cache', cache.size() === 0 && cache.list().length === 0);
+
+console.log('\n=== State-id minting ===');
+
+const id1 = mintStateId('admin dashboard with KPIs', 1);
+t('id format: prefix-rand4-vN-unixmin', /^admin-[a-f0-9]{4}-v1-\d+$/.test(id1));
+
+const id2 = mintStateId('build me a pricing page');
+t('id uses first word as prefix', id2.startsWith('build-'));
+
+t('id with empty intent uses fallback', /^state-[a-f0-9]{4}-v1-\d+$/.test(mintStateId('')));
+t('id with whitespace-only intent uses fallback', /^state-[a-f0-9]{4}-v1-\d+$/.test(mintStateId('   ')));
+t('id strips non-alphanumeric chars', /^foo-/.test(mintStateId('foo!@#$ bar')));
+
+// Different mints → different ids in the vast majority of cases.
+const ids = new Set();
+for (let i = 0; i < 50; i++) ids.add(mintStateId('dash', 1));
+t('50 mints produce mostly distinct rand4 values', ids.size >= 45);
+
+// Next-id chain
+const root = mintStateId('dash', 1);
+const child = mintNextStateId(root, 2);
+const [pref5, rand5] = root.split('-');
+const [pref6, rand6, v6] = child.split('-');
+t('next-id preserves prefix', pref5 === pref6);
+t('next-id preserves rand4', rand5 === rand6);
+t('next-id bumps version', v6 === 'v2');
+
+const fallback = mintNextStateId('not-a-valid-id', 2);
+t('next-id falls back on bad parent', /^[a-z]+-[a-f0-9]{4}-v2-\d+$/.test(fallback));
+
+const fallbackEmpty = mintNextStateId(undefined, 3);
+t('next-id falls back on undefined parent', /^state-[a-f0-9]{4}-v3-\d+$/.test(fallbackEmpty));
+
+console.log('\n=== Singleton ===');
+
+resetStateCache({ maxSize: 5 });
+const c1 = getStateCache();
+const c2 = getStateCache();
+t('singleton returns same instance', c1 === c2);
+c1.set('x', { intent: 'x' });
+t('singleton state shared', c2.has('x'));
+
+const c3 = resetStateCache();
+t('reset replaces singleton', c3 !== c1 && c3.size() === 0);
+
+console.log('\n=== Env-driven sizing ===');
+
+process.env.A2UI_STATE_CACHE_SIZE = '7';
+const sized = resetStateCache();
+t('env-driven maxSize', sized.maxSize === 7);
+
+delete process.env.A2UI_STATE_CACHE_SIZE;
+const defaulted = resetStateCache();
+t('default maxSize 64', defaulted.maxSize === 64);
+
+process.env.A2UI_STATE_CACHE_SIZE = 'not-a-number';
+const garbage = resetStateCache();
+t('garbage env value falls back to default', garbage.maxSize === 64);
+delete process.env.A2UI_STATE_CACHE_SIZE;
+
+// Constructor opts override env
+process.env.A2UI_STATE_CACHE_SIZE = '7';
+const explicit = resetStateCache({ maxSize: 12 });
+t('constructor maxSize wins over env', explicit.maxSize === 12);
+delete process.env.A2UI_STATE_CACHE_SIZE;
+
+console.log(`\n${pass} passed, ${fail} failed`);
+process.exit(fail ? 1 : 0);

package/scripts/test-a2ui.mjs

@@ -264,6 +264,109 @@ try {
   bad('Chunk corpus', e.message);
 }
 
+// ── Test 7: Multi-turn refinement modules (Phase A) ─────────────────
+// Spec: docs/specs/genui-multiturn-architecture.md.
+
+console.log('\n7. Multi-turn refinement (Phase A)');
+
+try {
+  const { StateCache, mintStateId, mintNextStateId } = await import('../../compose/engines/zettel/state-cache.js');
+  const { createIssueAccumulator } = await import('../../compose/engines/zettel/issue-reporter.js');
+  const { refineFromIntent, applyOps, opsToA2UI, validateOps } = await import('../../compose/engines/zettel/chunk-refiner.js');
+  const { listChunksByKind } = await import('../../corpus/scripts/chunk-library.js');
+
+  // 7a. State cache + state-id chain
+  const cache = new StateCache({ maxSize: 8 });
+  const root = mintStateId('admin dashboard', 1);
+  cache.set(root, { state_id: root, intent: 'admin dashboard', plan: { page: 'p', slot_bindings: {} }, ops_history: [], version: 1 });
+  const child = mintNextStateId(root, 2);
+  if (child.startsWith(root.split('-').slice(0, 2).join('-')) && child.includes('v2')) {
+    ok('State-id chain preserves stem + bumps version');
+  } else {
+    bad('State-id chain', `child=${child} root=${root}`);
+  }
+
+  // 7b. validateOps catches unknown chunks
+  const pages = listChunksByKind('page');
+  const blocks = listChunksByKind('block');
+  if (pages.length === 0 || blocks.length < 3) {
+    bad('Refiner test setup', 'corpus missing chunks');
+  } else {
+    const samplePage = pages.find((p) => (p.slots || p.instances?.[0]?.slots || []).length >= 1) || pages[0];
+    const samplePageSlots = (samplePage.slots || samplePage.instances?.[0]?.slots || []).map((s) => s.name);
+    const targetedSlot = samplePageSlots[0];
+    const priorState = {
+      state_id: root,
+      intent: 'admin dashboard',
+      plan: { page: samplePage.name, slot_bindings: { [targetedSlot]: [blocks[0].name] } },
+      html: '<placeholder/>',
+      version: 1,
+    };
+
+    const badOps = validateOps(
+      [{ type: 'rebindSlot', slot: targetedSlot, chunks: ['no-such-chunk-zzz'] }],
+      priorState,
+    );
+    if (!badOps.ok && badOps.errors.some((e) => /not found/.test(e))) {
+      ok('validateOps rejects unknown chunk');
+    } else {
+      bad('validateOps unknown chunk', JSON.stringify(badOps));
+    }
+
+    // 7c. applyOps produces materialized HTML
+    const applied = await applyOps({
+      priorState,
+      ops: [{ type: 'rebindSlot', slot: targetedSlot, chunks: [blocks[1].name] }],
+    });
+    if (applied.ops_applied.length === 1 && applied.newState.html) {
+      ok('applyOps materializes new HTML');
+    } else {
+      bad('applyOps materialize', `applied=${applied.ops_applied.length} html=${!!applied.newState.html}`);
+    }
+
+    // 7d. Two-pass refineFromIntent with stub LLM
+    const stubResponses = [
+      { targeted: true, target_slots: [targetedSlot] },
+      { ops: [{ type: 'rebindSlot', slot: targetedSlot, chunks: [blocks[1].name] }], delta_summary: 'test' },
+    ];
+    let qIdx = 0;
+    const stubLLM = {
+      complete: async () => ({ content: JSON.stringify(stubResponses[qIdx++]) }),
+    };
+    const refined = await refineFromIntent({
+      priorState,
+      intent: `change ${targetedSlot}`,
+      llmAdapter: stubLLM,
+      catalog: [{ name: blocks[1].name, kind: 'block', primary: 'div', slots: [] }],
+    });
+    if (refined.ops.length === 1 && refined.synthesis.targeted) {
+      ok('refineFromIntent two-pass synthesis');
+    } else {
+      bad('refineFromIntent', `ops=${refined.ops.length} targeted=${refined.synthesis.targeted}`);
+    }
+
+    // 7e. opsToA2UI emits updateComponents wire-format
+    const wire = opsToA2UI(refined.ops, applied.newState);
+    if (wire.length === 1 && wire[0].type === 'updateComponents' && wire[0].surfaceId === 'main') {
+      ok('opsToA2UI wraps as updateComponents');
+    } else {
+      bad('opsToA2UI', JSON.stringify(wire[0]));
+    }
+
+    // 7f. IssueAccumulator coalesces via reasons()
+    const acc = createIssueAccumulator();
+    acc.add('locator-empty-targets', { intent: 't' });
+    acc.add('validator-exhausted', { tool: 't' });
+    if (acc.size() === 2 && acc.reasons().length === 2) {
+      ok('IssueAccumulator collects multiple auto-fires');
+    } else {
+      bad('IssueAccumulator', `size=${acc.size()}`);
+    }
+  }
+} catch (e) {
+  bad('Multi-turn modules', e.message);
+}
+
 // ── Summary ─────────────────────────────────────────────────────────
 
 console.log(`\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);