@adia-ai/a2ui-mcp 0.0.4 → 0.1.0

package/scripts/smoke-issues.mjs

@@ -0,0 +1,266 @@
+#!/usr/bin/env node
+// Smoke test: issue-reporter (write, trace attach, auto-fire, coalesce, evalMode).
+// Spec: docs/specs/genui-multiturn-architecture.md §3.5 + §4.6 + §6.4 + §11.
+
+import {
+  reportIssue,
+  autoReport,
+  attachTrace,
+  createIssueAccumulator,
+  AUTO_FIRE_POLICY,
+} from '../../compose/engines/zettel/issue-reporter.js';
+import { StateCache } from '../../compose/engines/zettel/state-cache.js';
+import { mkdtemp, readFile, rm, stat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+let pass = 0, fail = 0;
+const t = (label, ok, detail = '') => {
+  if (ok) { console.log(`  ✓ ${label}`); pass++; }
+  else    { console.log(`  ✗ ${label}  ${detail}`); fail++; }
+};
+
+const TMP = await mkdtemp(join(tmpdir(), 'a2ui-issues-'));
+const ctx = {
+  storageRoot: TMP,
+  versionInfo: { mcp: '0.1.0', corpus: '0.0.6', engine: 'zettel', llm_adapter: 'stub', model: 'test' },
+};
+
+console.log(`Storage root: ${TMP}`);
+console.log('\n=== reportIssue: basic write ===');
+
+const r1 = await reportIssue({
+  type: 'bug',
+  severity: 'drift',
+  title: 'Test issue with simple title',
+  body: 'Test body content.',
+}, { ...ctx, reporter: 'user' });
+
+t('returns issue_id', !!r1.issue_id);
+t('issue-id format YYYY-MM-DD-slug-rand4', /^\d{4}-\d{2}-\d{2}-[a-z0-9-]+-[a-f0-9]{4}$/.test(r1.issue_id));
+t('returns ack: logged', r1.ack === 'logged');
+t('returns absolute path', r1.path.startsWith(TMP));
+
+const file1 = JSON.parse(await readFile(r1.path, 'utf8'));
+t('written file has expected type', file1.type === 'bug');
+t('written file has expected severity', file1.severity === 'drift');
+t('written file has status open', file1.status === 'open');
+t('written file has reporter.kind', file1.reporter.kind === 'user');
+t('written file has environment', file1.environment?.mcp === '0.1.0');
+t('written file has linked_specs default', Array.isArray(file1.linked_specs) && file1.linked_specs.length > 0);
+t('related_issue_ids defaults to empty array', Array.isArray(file1.related_issue_ids) && file1.related_issue_ids.length === 0);
+t('tags defaults to empty array', Array.isArray(file1.tags));
+t('suggested_owner defaults to "unknown"', file1.suggested_owner === 'unknown');
+
+console.log('\n=== validation guards ===');
+
+let threw = false;
+try { await reportIssue({ type: 'invalid', severity: 'drift', title: 't', body: 'b' }, ctx); }
+catch (e) { threw = /type must be/.test(e.message); }
+t('rejects invalid type', threw);
+
+threw = false;
+try { await reportIssue({ type: 'bug', severity: 'oops', title: 't', body: 'b' }, ctx); }
+catch (e) { threw = /severity must be/.test(e.message); }
+t('rejects invalid severity', threw);
+
+threw = false;
+try { await reportIssue({ type: 'bug', severity: 'drift', title: 'x'.repeat(81), body: 'b' }, ctx); }
+catch (e) { threw = /≤ 80 chars/.test(e.message); }
+t('rejects title > 80 chars', threw);
+
+threw = false;
+try { await reportIssue({ type: 'bug', severity: 'drift', title: 't', body: 'b', trace: 'partial' }, ctx); }
+catch (e) { threw = /trace must be/.test(e.message); }
+t('rejects invalid trace depth', threw);
+
+threw = false;
+try { await reportIssue({ type: 'bug', severity: 'drift', title: 't', body: 'b', tags: 'not-an-array' }, ctx); }
+catch (e) { threw = /tags must be an array/.test(e.message); }
+t('rejects non-array tags', threw);
+
+console.log('\n=== state_id trace attachment ===');
+
+const cache = new StateCache({ maxSize: 10 });
+cache.set('dash-3f9a-v1-26042817', {
+  state_id: 'dash-3f9a-v1-26042817',
+  intent: 'admin dashboard',
+  tool: 'compose_from_chunks',
+  input: { intent: 'admin dashboard' },
+  output: { html: '<dashboard/>', plan: { page: 'dashboard-admin-page' } },
+  ops_history: [
+    { type: 'createSurface', surfaceId: 'main' },
+    { type: 'updateComponents', surfaceId: 'main', components: [] },
+  ],
+  delta_summary: 'Created admin dashboard',
+  warnings: [],
+  duration_ms: 1234,
+  internal: {
+    locator_prompt: 'PROMPT_LOCATOR_v1',
+    locator_response: 'RESPONSE_LOCATOR_v1',
+    modifier_prompt: 'PROMPT_MODIFIER_v1',
+    modifier_response: 'RESPONSE_MODIFIER_v1',
+    validator_results: [{ ok: true }],
+    retries: 0,
+  },
+});
+
+const traceSummary = await attachTrace('dash-3f9a-v1-26042817', 'summary', cache);
+t('summary trace populates state_id', traceSummary?.state_id === 'dash-3f9a-v1-26042817');
+t('summary trace populates input', traceSummary?.input?.intent === 'admin dashboard');
+t('summary trace populates output.ops', Array.isArray(traceSummary?.output?.ops));
+t('summary trace omits internal field', traceSummary?.internal === undefined);
+
+const traceFull = await attachTrace('dash-3f9a-v1-26042817', 'full', cache);
+t('full trace includes internal.locator_prompt', traceFull?.internal?.locator_prompt === 'PROMPT_LOCATOR_v1');
+t('full trace includes internal.modifier_response', traceFull?.internal?.modifier_response === 'RESPONSE_MODIFIER_v1');
+t('full trace includes validator_results', Array.isArray(traceFull?.internal?.validator_results));
+
+const traceMiss = await attachTrace('not-a-real-id', 'summary', cache);
+t('attachTrace returns null on cache miss', traceMiss === null);
+
+const traceNoCache = await attachTrace('dash-3f9a-v1-26042817', 'summary', null);
+t('attachTrace returns null when no cache', traceNoCache === null);
+
+// reportIssue with state_id integrates trace
+const r2 = await reportIssue({
+  type: 'bug',
+  severity: 'drift',
+  title: 'Issue tied to a state',
+  body: 'Reproducible on dashboard generation.',
+  state_id: 'dash-3f9a-v1-26042817',
+  trace: 'full',
+}, { ...ctx, cache });
+const file2 = JSON.parse(await readFile(r2.path, 'utf8'));
+t('reportIssue with state_id+full attaches trace.input', file2.trace?.input?.intent === 'admin dashboard');
+t('reportIssue with full trace attaches internal', file2.trace?.internal?.locator_prompt === 'PROMPT_LOCATOR_v1');
+
+// peek does not touch recency — verify the cache state didn't bump dash- to most-recent.
+// Insert a few more entries, ensure dash- stays the LRU candidate.
+// (This is exercised indirectly: state-cache smoke covers peek-recency directly.)
+
+console.log('\n=== oversized trace spills to sidecar ===');
+
+cache.set('big-state', {
+  state_id: 'big-state',
+  intent: 'big',
+  tool: 'compose',
+  input: {},
+  ops_history: [],
+  internal: { huge_dump: 'x'.repeat(300 * 1024) },
+});
+const r3 = await reportIssue({
+  type: 'bug',
+  severity: 'drift',
+  title: 'Big trace test',
+  body: 'Has an oversized trace.',
+  state_id: 'big-state',
+  trace: 'full',
+}, { ...ctx, cache });
+const file3 = JSON.parse(await readFile(r3.path, 'utf8'));
+t('oversized trace replaced by sidecar pointer', !!file3.trace?.sidecar);
+t('sidecar path has expected shape', /^traces\/.+\.trace\.json$/.test(file3.trace.sidecar));
+const sidecar = await stat(join(TMP, file3.trace.sidecar));
+t('sidecar file exists with non-zero size', sidecar.size > 0);
+
+console.log('\n=== autoReport: policy lookup ===');
+
+const a1 = await autoReport('validator-exhausted', { tool: 'refine_composition' }, ctx);
+const file_a1 = JSON.parse(await readFile(a1.path, 'utf8'));
+t('validator-exhausted: type=bug', file_a1.type === 'bug');
+t('validator-exhausted: severity=blocker', file_a1.severity === 'blocker');
+t('validator-exhausted: suggested_owner=validator', file_a1.suggested_owner === 'validator');
+t('validator-exhausted: reporter.kind=auto', file_a1.reporter.kind === 'auto');
+t('validator-exhausted: reporter.context=validator-exhausted', file_a1.reporter.context === 'validator-exhausted');
+t('validator-exhausted: tags include "auto-fire"', file_a1.tags.includes('auto-fire'));
+
+const a2 = await autoReport('retrieval-zero-then-synthesis-fail', { intent: 'pricing page' }, ctx);
+const file_a2 = JSON.parse(await readFile(a2.path, 'utf8'));
+t('retrieval-zero-then-synthesis-fail: type=training-gap', file_a2.type === 'training-gap');
+t('retrieval-zero-then-synthesis-fail: suggested_owner=chunk-corpus', file_a2.suggested_owner === 'chunk-corpus');
+t('retrieval-zero-then-synthesis-fail: title carries intent', /pricing page/.test(file_a2.title));
+
+const a3 = await autoReport('cache-miss-on-known-state', { state_id: 'gone-12ab-v1-0' }, ctx);
+const file_a3 = JSON.parse(await readFile(a3.path, 'utf8'));
+t('cache-miss-on-known-state: severity=nit', file_a3.severity === 'nit');
+
+threw = false;
+try { await autoReport('unknown-reason', {}, ctx); }
+catch (e) { threw = /unknown reason/.test(e.message); }
+t('autoReport rejects unknown reason', threw);
+
+console.log('\n=== evalMode suppresses auto-fire ===');
+
+const evalCtx = { ...ctx, evalMode: true };
+const aSuppressed = await autoReport('validator-exhausted', { tool: 'refine_composition' }, evalCtx);
+t('autoReport returns null when evalMode=true', aSuppressed === null);
+
+// Manual reportIssue still writes during evalMode (eval-suppression is auto-fire only)
+const aManual = await reportIssue({
+  type: 'bug',
+  severity: 'blocker',
+  title: 'Manual call during evalMode',
+  body: 'should still write',
+}, evalCtx);
+t('manual reportIssue ignores evalMode', !!aManual.issue_id);
+const file_manual = JSON.parse(await readFile(aManual.path, 'utf8'));
+t('manual call during evalMode writes file', file_manual.title === 'Manual call during evalMode');
+
+console.log('\n=== coalescing accumulator ===');
+
+const acc = createIssueAccumulator();
+t('empty accumulator size 0', acc.size() === 0);
+const flushEmpty = await acc.flush(ctx);
+t('empty accumulator flush returns null', flushEmpty === null);
+
+acc.add('locator-empty-targets', { intent: 'change title' });
+t('single-entry accumulator size 1', acc.size() === 1);
+const flushOne = await acc.flush(ctx);
+const file_flush_one = JSON.parse(await readFile(flushOne.path, 'utf8'));
+t('single-entry flush writes normal auto-issue', file_flush_one.reporter.kind === 'auto' && file_flush_one.reporter.context === 'locator-empty-targets');
+t('single-entry flush resets accumulator', acc.size() === 0);
+
+acc.add('locator-empty-targets', { intent: 'change title' });
+acc.add('validator-exhausted', { tool: 'refine_composition' });
+acc.add('ops-failed-after-apply', {});
+t('three-entry accumulator size 3', acc.size() === 3);
+const flushThree = await acc.flush(ctx);
+const file_flush_three = JSON.parse(await readFile(flushThree.path, 'utf8'));
+t('coalesced issue: severity=blocker (highest of three)', file_flush_three.severity === 'blocker');
+t('coalesced issue: type=bug', file_flush_three.type === 'bug');
+t('coalesced issue: reporter.context=coalesced', file_flush_three.reporter.context === 'coalesced');
+t('coalesced issue: tags include "coalesced"', file_flush_three.tags.includes('coalesced'));
+t('coalesced issue: tags include all reasons',
+  ['locator-empty-targets', 'validator-exhausted', 'ops-failed-after-apply'].every((r) => file_flush_three.tags.includes(r))
+);
+t('coalesced issue: body lists every reason',
+  file_flush_three.body.includes('locator-empty-targets') &&
+  file_flush_three.body.includes('validator-exhausted') &&
+  file_flush_three.body.includes('ops-failed-after-apply')
+);
+t('coalesced flush resets accumulator', acc.size() === 0);
+
+// evalMode + coalesce → no write
+const accEval = createIssueAccumulator();
+accEval.add('validator-exhausted', {});
+accEval.add('ops-failed-after-apply', {});
+const flushEval = await accEval.flush({ ...ctx, evalMode: true });
+t('coalesce flush returns null when evalMode=true', flushEval === null);
+
+threw = false;
+try { acc.add('not-a-real-reason'); }
+catch (e) { threw = /unknown reason/.test(e.message); }
+t('accumulator.add rejects unknown reason', threw);
+
+console.log('\n=== AUTO_FIRE_POLICY exported ===');
+
+t('AUTO_FIRE_POLICY exports expected reasons',
+  ['synthesizer-exhausted', 'validator-exhausted', 'locator-empty-targets',
+   'retrieval-zero-then-synthesis-fail', 'cache-miss-on-known-state',
+   'ops-failed-after-apply'].every((r) => AUTO_FIRE_POLICY[r])
+);
+
+await rm(TMP, { recursive: true, force: true });
+
+console.log(`\n${pass} passed, ${fail} failed`);
+process.exit(fail ? 1 : 0);

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);