@adia-ai/a2ui-compose 0.0.1 → 0.1.0

package/CHANGELOG.md

@@ -10,7 +10,92 @@ generator graph.
 
 ## [Unreleased]
 
-_Nothing yet._
+---
+
+## [0.1.0] - 2026-04-28
+
+**Multi-turn refinement engine (Phase A).** Adds three new modules to the
+zettel engine that turn `compose_from_chunks` from single-shot into a
+multi-turn surface, plus a first-class telemetry surface that auto-fires
+issue tickets on engine failure paths.
+
+Spec: [`docs/specs/genui-multiturn-architecture.md`](../../../docs/specs/genui-multiturn-architecture.md) (Active v0.1.0).
+Plan: [`docs/plans/genui-multiturn-rollout-2026-04-28.md`](../../../docs/plans/genui-multiturn-rollout-2026-04-28.md) (Phase A scoped).
+ADR: [`0008-multiturn-genui-architecture.md`](../../../.brain/adrs/0008-multiturn-genui-architecture.md).
+
+### Added (engine modules)
+
+- **`engines/zettel/state-cache.js`** — bounded LRU cache for multi-turn
+  compositions (default 64 entries; configurable via
+  `A2UI_STATE_CACHE_SIZE`). API: `set / get / peek / has / evict / list /
+  size / clear`. State-id minting helpers `mintStateId(intent, version)`
+  and `mintNextStateId(parent, version)` produce stems of the form
+  `<intent-prefix>-<rand4>-v<N>-<unix-min>` so refinement chains keep a
+  visible lineage. Module-level singleton via `getStateCache() /
+  resetStateCache()`. Pure data structure; no I/O, no async.
+- **`engines/zettel/issue-reporter.js`** — first-class telemetry surface.
+  `reportIssue(input, ctx)` writes immutable JSON to
+  `.brain/audit-history/issues/<issue_id>.json` (matches the existing
+  audit-ledger convention). `autoReport(reason, autoCtx, ctx)` looks up
+  a 6-row policy table for engine-side auto-fires (`synthesizer-exhausted`,
+  `validator-exhausted`, `locator-empty-targets`,
+  `retrieval-zero-then-synthesis-fail`, `cache-miss-on-known-state`,
+  `ops-failed-after-apply`) and threads severity / type / suggested-owner
+  defaults. `attachTrace(state_id, depth, cache)` pulls from the
+  state-cache via `peek` (no recency disturbance). Sidecar trace files
+  for traces > 200 KB. Three reporter kinds: `auto | user | llm`.
+  `evalMode: true` in ctx suppresses auto-fire (manual `reportIssue`
+  calls still write). Per-tool-call `IssueAccumulator` coalesces
+  multiple auto-fires into a single issue with the highest-severity
+  policy as primary; reasons listed in body + tags.
+- **`engines/zettel/chunk-refiner.js`** — sibling to `chunk-synthesizer.js`.
+  Two-pass synthesis (locator → modifier) for refinement intents.
+  `refineFromIntent({ priorState, intent, llmAdapter, maxAttempts,
+  issueAccumulator, catalog })` runs a locator pass to identify which
+  slots to modify, then a modifier pass to emit chunk-plan ops on the
+  targeted slice. Validator-driven retry loop with feedback-on-error
+  (default `maxAttempts: 2`, mirrors `chunk-synthesizer`). `validateOps`
+  checks op shape, slot references, chunk references, page-kind
+  contracts. `applyOps({ priorState, ops })` mutates a deep-cloned
+  plan and re-materializes HTML via `composeFromPlan`. `opsToA2UI(ops,
+  newState)` translates chunk-plan ops to wire-format `updateComponents`
+  A2UI messages (Phase A simplification: `components[].html` carries
+  the materialized payload; Phase B will upgrade to component-tree shape).
+
+### Phase A op format
+
+Internal: `rebindSlot | appendToSlot | removeFromSlot | replacePage`.
+Wire: standard `updateComponents` messages targeting `slot-<name>` ids
+(or `main` for `replacePage`). Documented as a Phase A simplification —
+the chunk pipeline emits HTML, so the wire-format wrapper is intentionally
+thin until Phase B introduces typed component-tree refinements.
+
+### Smoke + eval
+
+- `npm run smoke:state-cache` — 34/34 (LRU recency, peek, env-driven sizing,
+  state-id minting + chain).
+- `npm run smoke:issues` — 62/62 (write, validation, trace attach, sidecar
+  spill, auto-fire policy lookup, evalMode suppression, coalescing).
+- `npm run smoke:refine` — 51/51 (validateOps, applyOps × 4 op types,
+  opsToA2UI, two-pass with stub LLM, retries, exhaustion auto-fire,
+  end-to-end refine → apply → wire).
+- **`npm run eval:refine-synthesis`** — **15/15 PASS** real-LLM eval.
+  Ops rate 100%, validate rate 100%, 0 auto-fires, 67 s. All 15
+  refinements completed on the first attempt.
+
+### Out of scope (Phase B / C)
+
+- Persistent state across server restarts (SQLite-backed cache).
+- Branching / version trees.
+- LLM-streamed op emission.
+- Multi-user concurrent refinement (CRDT / OT).
+- A2UI `updateDataModel` + `wireComponents` synthesis (current scope is
+  `updateComponents` + `deleteSurface` only).
+
+### Migration
+
+Additive surface; no breaking changes. Existing consumers calling
+`composeFromIntent` continue to work unchanged.
 
 ---
 

package/README.md

@@ -5,15 +5,14 @@ an A2UI component catalog and produces a tree of A2UI protocol messages
 ready for a renderer.
 
 > This package is pipeline runtime only. UI components live in
-> [`@adia-ai/web-components`](../web-components); the A2UI runtime (renderer,
-> registry, streams, wiring) in [`@adia-ai/a2ui-utils`](../a2ui/utils);
+> [`@adia-ai/web-components`](../../web-components); the A2UI runtime (renderer,
+> registry, streams, wiring) in [`@adia-ai/a2ui-utils`](../utils);
 > the pattern corpus in [`@adia-ai/a2ui-corpus`](../corpus);
 > the MCP server in [`@adia-ai/a2ui-mcp`](../mcp).
 >
-> Note: this package still lives under the legacy `@adiahealth` scope in its
-> own `package.json` name. The `@adia-ai` scope is the public npm scope
-> (only `@adia-ai/web-components` and `@adia-ai/a2ui-utils` are currently
-> published).
+> Published to the public `@adia-ai` scope on 2026-04-24 alongside
+> `a2ui-corpus`, `a2ui-mcp`, `a2ui-retrieval`, and `a2ui-validator`.
+> Install with `npm i @adia-ai/a2ui-compose`.
 
 ## What it does
 

package/engines/zettel/chunk-composer.js

@@ -0,0 +1,182 @@
+/**
+ * Chunk composer — materializes a chunk-binding plan into a single HTML
+ * document by walking a page chunk's HTML and substituting each slot
+ * region with the bound block-level chunks' HTML.
+ *
+ * Input plan shape:
+ *   {
+ *     page: "dashboard-admin-page",
+ *     slot_bindings: {
+ *       "page-header": "dashboard-page-header",
+ *       "page-content": ["dashboard-overview-panel", "dashboard-funnel"]
+ *     }
+ *   }
+ *
+ * Output:
+ *   {
+ *     html: "<article>...</article>",   // composed HTML
+ *     plan: { ... },                     // echoed back for traceability
+ *     warnings: ["..."]                  // non-fatal issues
+ *   }
+ *
+ * Plan: docs/plans/training-pipeline-chunk-harvest-2026-04-27.md (Phase C.2).
+ */
+
+import { getChunk } from '../../../corpus/scripts/chunk-library.js';
+
+/**
+ * Resolve a chunk record's authoritative HTML. For multi-instance reusable
+ * slot chunks (auth-card-header, reg-step-header), pick the first instance.
+ */
+function chunkHtml(rec) {
+  if (!rec) return null;
+  if (rec.html) return rec.html;
+  if (Array.isArray(rec.instances) && rec.instances[0]?.html) return rec.instances[0].html;
+  return null;
+}
+
+/**
+ * Find an element with `data-chunk-slot="<name>"` inside the page HTML.
+ * Returns { tagName, openEnd, innerStart, innerEnd, outerEnd } or null.
+ *
+ * Mirrors the harvester's findElementSpan logic — depth-tracked walk for
+ * the matching close tag.
+ */
+function findSlotInHtml(html, slotName) {
+  const re = new RegExp(`<([a-zA-Z][a-zA-Z0-9-]*)([^>]*?\\bdata-chunk-slot\\s*=\\s*"${slotName}"[^>]*?)>`, 'i');
+  const m = html.match(re);
+  if (!m) return null;
+  const idx = m.index;
+  const tagName = m[1];
+  const openEnd = html.indexOf('>', idx);
+  const lower = tagName.toLowerCase();
+  const openRe = new RegExp(`<${lower}\\b[^>]*?>`, 'gi');
+  const closeRe = new RegExp(`</${lower}\\s*>`, 'gi');
+  let depth = 1;
+  let cursor = openEnd + 1;
+  while (cursor < html.length && depth > 0) {
+    openRe.lastIndex = cursor;
+    closeRe.lastIndex = cursor;
+    const o = openRe.exec(html);
+    const c = closeRe.exec(html);
+    if (!c) return null;
+    if (o && o.index < c.index) {
+      if (!o[0].endsWith('/>')) depth++;
+      cursor = o.index + o[0].length;
+    } else {
+      depth--;
+      if (depth === 0) {
+        return {
+          tagName,
+          openTag: html.slice(idx, openEnd + 1),
+          outerStart: idx,
+          outerEnd: c.index + c[0].length,
+          innerStart: openEnd + 1,
+          innerEnd: c.index,
+        };
+      }
+      cursor = c.index + c[0].length;
+    }
+  }
+  return null;
+}
+
+/**
+ * Materialize a binding plan into composed HTML.
+ *
+ * @param {object} plan
+ * @param {string} plan.page — name of the page-kind chunk
+ * @param {Object<string, string|string[]>} plan.slot_bindings — slot name → bound chunk name(s)
+ * @returns {{ html: string|null, plan: object, warnings: string[] }}
+ */
+export function composeFromPlan(plan) {
+  const warnings = [];
+  if (!plan || typeof plan !== 'object') {
+    return { html: null, plan, warnings: ['plan must be an object with { page, slot_bindings }'] };
+  }
+  const pageRec = getChunk(plan.page);
+  if (!pageRec) {
+    return { html: null, plan, warnings: [`page chunk not found: ${plan.page}`] };
+  }
+  if (pageRec.kind !== 'page' && pageRec.kind !== 'panel') {
+    warnings.push(`page chunk "${plan.page}" has kind="${pageRec.kind}" — expected "page" or "panel"`);
+  }
+  let html = chunkHtml(pageRec);
+  if (!html) {
+    return { html: null, plan, warnings: [...warnings, `page chunk "${plan.page}" has no HTML`] };
+  }
+
+  const bindings = plan.slot_bindings || {};
+  for (const [slotName, bound] of Object.entries(bindings)) {
+    const slot = findSlotInHtml(html, slotName);
+    if (!slot) {
+      warnings.push(`slot "${slotName}" not found in page "${plan.page}"`);
+      continue;
+    }
+    const names = Array.isArray(bound) ? bound : [bound];
+    const parts = [];
+    for (const childName of names) {
+      const childRec = getChunk(childName);
+      if (!childRec) {
+        warnings.push(`bound chunk "${childName}" (slot "${slotName}") not found`);
+        continue;
+      }
+      const childHtml = chunkHtml(childRec);
+      if (!childHtml) {
+        warnings.push(`bound chunk "${childName}" has no HTML`);
+        continue;
+      }
+      parts.push(childHtml);
+    }
+    // Replace slot inner with bound children (preserves the slot's own outer
+    // wrapper so the page's grid/flex layout still applies).
+    const before = html.slice(0, slot.innerStart);
+    const after = html.slice(slot.innerEnd);
+    html = before + '\n' + parts.join('\n') + '\n' + after;
+  }
+
+  return { html, plan, warnings };
+}
+
+/**
+ * Validate a binding plan WITHOUT materializing — used by the synthesizer to
+ * give the LLM feedback before round-tripping HTML composition.
+ */
+export function validatePlan(plan) {
+  const errors = [];
+  if (!plan || typeof plan !== 'object') {
+    errors.push('plan must be an object');
+    return { ok: false, errors };
+  }
+  if (!plan.page || typeof plan.page !== 'string') {
+    errors.push('plan.page must be a chunk name string');
+  }
+  const pageRec = plan.page ? getChunk(plan.page) : null;
+  if (plan.page && !pageRec) errors.push(`plan.page chunk "${plan.page}" not found`);
+  if (pageRec && pageRec.kind !== 'page' && pageRec.kind !== 'panel') {
+    errors.push(`plan.page "${plan.page}" must be kind "page" or "panel"; got "${pageRec.kind}"`);
+  }
+  const bindings = plan.slot_bindings || {};
+  if (typeof bindings !== 'object') {
+    errors.push('plan.slot_bindings must be an object');
+    return { ok: errors.length === 0, errors };
+  }
+  // Validate slot names exist on the page
+  if (pageRec) {
+    const declaredSlots = new Set((pageRec.slots || []).map((s) => s.name));
+    for (const slotName of Object.keys(bindings)) {
+      if (!declaredSlots.has(slotName)) {
+        errors.push(`slot "${slotName}" not declared on page "${plan.page}"`);
+      }
+    }
+  }
+  // Validate bound chunk names exist
+  for (const [slot, bound] of Object.entries(bindings)) {
+    const names = Array.isArray(bound) ? bound : [bound];
+    for (const n of names) {
+      const rec = getChunk(n);
+      if (!rec) errors.push(`bound chunk "${n}" (slot "${slot}") not found`);
+    }
+  }
+  return { ok: errors.length === 0, errors };
+}