@adia-ai/a2ui-compose 0.5.1 → 0.5.3

package/CHANGELOG.md

@@ -12,6 +12,64 @@ generator graph.
 
 _No pending changes._
 
+## [0.5.3] - 2026-05-14
+
+### Fixed — Deterministic chunk-loading order in zettel composition library (§160, v0.5.3)
+
+`strategies/zettel/composition-library.js`: `walk()` now sorts `fs.readdirSync` output via `localeCompare` before recursing. Pre-§160 the directory walker relied on filesystem-defined entry order, which varies across processes on APFS/ext4. When two chunks tied on retrieval score for a given intent, the first-loaded won the tie-break — so the same intent could match chunk A in one process and chunk B in the next.
+
+Surfaced as ~40% flake rate on the `admin dashboard with kpi cards` retrieval probe post-§143 (the 8 new UI-primitive chunks compete with the original `dashboard-kpi-grid` template). Sorted walk pins load order; remaining flakiness is now constrained to a corpus-quality bug (Stat chunks strip `label`/`value`/`change` attrs in the `template` field) tracked as v0.5.4 F-S1a.
+
+No behavior change for callers that don't hit a tie-break — most intents have a clear retrieval winner.
+
+### Deprecated — `_debug.attempts` and `_debug.warnings` on free-form-composed results (§146, v0.5.3)
+
+Finalizes the v0.6.0 deprecation schedule for the last two `_debug.*` fields that consumers might still read on `generateFreeFormAdapter`'s result. Both fields are dialog-recorder-gated (silently `undefined` when not recording) — the same access pattern §109 (v0.5.1) + §107a (v0.5.2) removed for `usedIngredients` / `rationale` / `plan`.
+
+**v0.6.0 migration path** (folded into the inline `@deprecated` JSDoc on `strategies/registry.js`):
+
+- `result._debug?.attempts` → `result.attempts: number` (LLM round-trips: 1 normally; 2-3 with hallucination retry or paraphrase-retry)
+- `result._debug?.warnings` → `result.warnings: string[]` (non-fatal transpile findings: unknown substitution keys, layout-value fall-throughs, chunk-resolution warns)
+
+**Scheduled removal**: v0.6.0 drops the `_debug` block entirely from the free-form-composed result shape. The dialog-recorder will read first-class fields directly. v0.5.3 is the **migration window** — any external consumers reading `_debug.attempts` / `_debug.warnings` should switch to the first-class fields before v0.6.0 ships.
+
+**Internal verification**: zero live in-repo consumers (`grep -rn '_debug\?\.attempts\|_debug\.attempts\|_debug\?\.warnings\|_debug\.warnings' apps/ playgrounds/ catalog/ packages/` returns only the deprecation comment itself).
+
+## [0.5.2] - 2026-05-13
+
+### Changed — `plan` graduates from `_debug.*` to first-class on free-form-composed result (§107a infra, v0.5.2)
+
+
+`strategies/registry.js` `generateFreeFormAdapter` returns `plan` as a top-level result field (paired with v0.5.1's §109 graduation of `usedIngredients` + `rationale`). The `_debug.plan` field is no longer populated — consumers should read `result.plan` directly. Soft-API change (`_debug` was always documented as volatile).
+
+Enables substitution-coverage measurement at eval time without dialog-recorder coupling. Companion to `@adia-ai/a2ui-mcp` `--report-substitutions` flag.
+
+### Deprecated — individual `_debug.*` field reads on free-form-composed results (§131, v0.5.2)
+
+Documents the `_debug`-volatility contract that §109 (v0.5.1) + §107a (v0.5.2) established de-facto. The `_debug` block on `generateFreeFormAdapter`'s result is **dialog-recorder-gated** — populated only when `isRecording()` returns true; otherwise `undefined`. Individual field reads (`result._debug?.usedIngredients`, `result._debug?.rationale`, `result._debug?.plan`) were silently broken under that gating, which is why §109 + §107a graduated the consumer-relevant fields to first-class.
+
+**Migration:** any consumer reading `result._debug?.<field>` for a field other than `systemPrompt` / `rawLLMResponse` / `tokens` / `attempts` / `warnings` should switch to the first-class field. The currently-stable first-class set: `usedIngredients`, `rationale`, `plan`.
+
+**Scheduled removal:** v0.6.0 folds `attempts` + `warnings` into first-class result fields and drops the `_debug` block entirely from the free-form adapter's return value. The dialog-recorder will read first-class fields directly.
+
+No live in-repo consumers of the soft-API path remain (verified `grep -rn '_debug?\.\|_debug\.' apps/ playgrounds/ catalog/` → 0 hits). One dead fallback in `@adia-ai/a2ui-mcp`'s `eval-diff.mjs` (`result.plan || result._debug?.plan || null`) removed in the same cut.
+
+### Changed — Free-form system prompt: 5 per-shape substitution examples + self-check pattern (§126, v0.5.2)
+
+`strategies/free-form-composer/system-prompt.js` constraint 3 extends the v0.5.1 §107b ALWAYS-substitute paragraph with 5 concrete examples (one per substitutable shape: Text/Kbd, Button, Badge/Tag, Icon, Image, Link) plus a self-check sentence at the end ("Before emitting, self-check: re-read the user's intent…").
+
+Targets the v0.5.1 §107a finding that Haiku 4.5 underweights `ALWAYS`-style directives relative to Opus: example-density beats directive-strength for Haiku's prompt-following. Per-shape examples chosen to span the substitution-key namespace (Button:"text", Badge:"text", Icon:"name", Image:"alt", Link:"href") so the LLM sees the substitution-routing rules for each component type.
+
+Cost: ~120 additional prompt tokens per call (~0.5% of total). Acceptable.
+
+Expected impact: lifts substitution ratio 27.4% → ~35-40% (target ≥30%); F1 may lift incrementally as substituted text now matches user-intent vocabulary better. Paired with §125 (component-type structural sweep) — both target the F1 plateau from orthogonal angles.
+
+### Changed — `generateFreeFormAdapter` accepts `ctx.model` override + reads `FREE_FORM_MODEL_OVERRIDE` env var (§127 infra, v0.5.2)
+
+`strategies/registry.js` reads model priority chain at call-time (not module-load): `ctx.model` > `process.env.FREE_FORM_MODEL_OVERRIDE` > `FREE_FORM_MODEL_DEFAULT` (Haiku 4.5). Enables `eval-diff.mjs --model <id>` to run the Haiku-vs-Opus A/B for §127 without env-dance or static-import-ordering hazards. `FREE_FORM_MODEL` constant renamed to `FREE_FORM_MODEL_DEFAULT` to reflect the new priority chain.
+
+Default behavior unchanged when no override set — the v0.5.1 §108 Haiku pin holds for every consumer that doesn't explicitly override.
+
 ## [0.5.1] - 2026-05-13
 
 ### Added — Free-form composer INTENT-PARAPHRASE block + paraphrase-retry (§106, v0.5.1)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/a2ui-compose",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "AdiaUI A2UI compose engine — 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/free-form-composer/system-prompt.js

@@ -129,7 +129,18 @@ CONSTRAINTS:
 2. Order your ingredients in the sequence they should appear in the rendered UI. The transpiler wraps your list in a root container — by default a vertical Column. Override via the optional \`layout\` field (see below).
 3. Each ingredient may carry a \`substitutions\` object. KEYS are node IDs from the \`substitutables:\` line in the catalog above (e.g. \`"title"\`, \`"submit"\`, \`"logo"\`). VALUES are the new content strings. The transpiler routes each substitution to the right attribute based on the node's component: \`Text\` / \`Kbd\` → \`textContent\`; \`Button\` / \`Badge\` / \`Tag\` → \`text\`; \`Icon\` → \`name\`; \`Image\` → \`alt\`; \`Link\` → \`href\`. Nodes whose component is not in the substitutable list are locked at their declared values.
 
-   **ALWAYS substitute** any title, heading, button label, or badge label that the user's intent specifies. Default chunk text is generic placeholder ("Sign in to AdiaUI", "Continue", "Welcome back"); your job is to tailor it to the user's actual intent. Substituting MORE is better than substituting less — empty \`substitutions\` ships generic copy that misses the intent. Example: intent "trial-signup form for ContextEngine" → \`{"title": "Start your ContextEngine trial", "submit": "Create account"}\` not \`{}\`.
+   **ALWAYS substitute** any title, heading, button label, or badge label that the user's intent specifies. Default chunk text is generic placeholder ("Sign in to AdiaUI", "Continue", "Welcome back"); your job is to tailor it to the user's actual intent. Substituting MORE is better than substituting less — empty \`substitutions\` ships generic copy that misses the intent.
+
+   **Substitution examples per shape** (study these before emitting):
+
+   - **Text / Kbd (textContent)**: intent "trial-signup form for ContextEngine" → \`{"title": "Start your ContextEngine trial", "submit": "Create account"}\` not \`{}\`.
+   - **Button (text)**: intent "submit a support ticket" → \`{"submit-btn": "Open ticket"}\` not \`{"submit-btn": "Submit"}\`.
+   - **Badge / Tag (text)**: intent "show overdue invoices with status" → \`{"status-badge": "Overdue"}\` not \`{"status-badge": "Status"}\`.
+   - **Icon (name)**: intent "delete the project" → \`{"action-icon": "trash"}\` not omitting the icon substitution.
+   - **Image (alt)**: intent "team photo with three engineers" → \`{"hero-image": "Three engineers at a whiteboard"}\` not \`{}\`.
+   - **Link (href)**: intent "footer link to /docs/api" → \`{"docs-link": "/docs/api"}\` not \`{"docs-link": "#"}\`.
+
+   **Before emitting, self-check**: re-read the user's intent. Does it specify any content (text label, badge, icon, alt-text, URL)? If yes, every matching substitutable in your picked ingredients should appear in \`substitutions\`. If the intent is content-agnostic ("a sign-up form"), empty \`substitutions\` is correct.
 4. If you can't satisfy the intent with the available ingredients, return \`{ "ingredients": [] }\` and a rationale explaining what's missing.
 5. Output ONLY the JSON object below, no explanation outside the JSON.
 

package/strategies/registry.js

@@ -124,7 +124,15 @@ async function generateZettelAdapter(ctx) {
 // than Opus, freeing the Opus budget for monolithic-pro fall-throughs.
 // User-decided pre-A/B per v0.5.1 plan question 2: "Haiku is a good
 // default."
-const FREE_FORM_MODEL = 'claude-haiku-4-5-20251001';
+//
+// §127 (v0.5.2): env override for the A/B harness. Set
+// `FREE_FORM_MODEL_OVERRIDE` env var to e.g. `claude-opus-4-7` to run
+// the eval against Opus for the §127 Haiku-vs-Opus comparison.
+// Default behavior unchanged when env var unset — the Haiku-pin holds
+// for every consumer that doesn't explicitly override. Read at
+// call-time (not module-load) so eval harnesses can set the env after
+// static imports complete.
+const FREE_FORM_MODEL_DEFAULT = 'claude-haiku-4-5-20251001';
 
 async function generateFreeFormAdapter(ctx) {
   // Lazy-load: free-form-composer imports composition-library which
@@ -134,10 +142,17 @@ async function generateFreeFormAdapter(ctx) {
   // Pin Haiku for the picker task even when harness model is Opus.
   // Auto-engine + factory-chat may pass any-model llmAdapter; free-form
   // mints its own to keep the picker cost-bounded.
+  //
+  // §127 (v0.5.2): `ctx.model` overrides the FREE_FORM pin (highest
+  // priority). `FREE_FORM_MODEL_OVERRIDE` env var is the second-priority
+  // override (set by `eval-diff.mjs --model <id>`). Default Haiku-pin
+  // holds otherwise. Empirical result from §127 records the production
+  // default; if Opus wins, FREE_FORM_MODEL_DEFAULT flips.
+  const modelToUse = ctx.model || process.env.FREE_FORM_MODEL_OVERRIDE || FREE_FORM_MODEL_DEFAULT;
   let pickerAdapter = ctx.llmAdapter || null;
   try {
     const { createAdapter } = await import('../../../llm/llm-bridge.js');
-    pickerAdapter = await createAdapter({ model: FREE_FORM_MODEL });
+    pickerAdapter = await createAdapter({ model: modelToUse });
   } catch {
     // Adapter mint failed (proxy down, no key) — fall back to whatever
     // ctx provides. Strategy will emit `free-form-no-llm` if both fail.
@@ -162,11 +177,51 @@ async function generateFreeFormAdapter(ctx) {
     // copy quotes the LLM's one-line rationale when present.
     usedIngredients: result.usedIngredients || [],
     rationale: result.rationale || null,
+    // §107a (v0.5.1): plan graduates to first-class so eval-diff's
+    // `--report-substitutions` can read it without `_debug` gating.
+    // The plan carries the LLM's emitted substitutions per ingredient
+    // — the substitution-coverage measurement needs this surface even
+    // when dialog-recorder is off (production eval scenarios).
+    plan: result.plan || null,
+    // §131 (v0.5.2): `_debug` is **volatile** — dialog-recorder-gated,
+    // shape may change without semver coordination. Consumers MUST read
+    // first-class fields instead: `usedIngredients` (§109 v0.5.1),
+    // `rationale` (§109 v0.5.1), `plan` (§107a v0.5.2). The old soft-API
+    // paths (`_debug.usedIngredients`, `_debug.rationale`, `_debug.plan`)
+    // were removed by §109 / §107a; this block is now strictly debug-
+    // recorder fodder. Scheduled removal: v0.6.0 will fold `attempts` +
+    // `warnings` into first-class result fields and drop `_debug` here.
+    //
+    // §146 (v0.5.3): finalize the v0.6.0 deprecation schedule for the
+    // last two `_debug.*` fields that any consumer might still read.
+    //
+    // @deprecated `_debug.attempts` and `_debug.warnings` — both fields
+    //   are dialog-recorder-gated (silently `undefined` when not
+    //   recording), which is exactly the access pattern §109+§107a
+    //   removed for `usedIngredients`/`rationale`/`plan`. v0.6.0 folds
+    //   both into first-class result fields:
+    //
+    //     - `result.attempts: number` — number of LLM round-trips taken
+    //       to produce the final plan (1 normally; 2-3 with hallucination
+    //       retry or paraphrase-retry; same value as §106's loop counter)
+    //     - `result.warnings: string[]` — non-fatal transpile findings
+    //       (unknown substitution keys, layout-value fall-throughs,
+    //       chunk-resolution warns); same value as transpilePlan output
+    //
+    //   Consumers should switch reads from `result._debug?.attempts` →
+    //   `result.attempts` and `result._debug?.warnings` → `result.warnings`
+    //   before v0.6.0 ships. The `_debug` block itself disappears from
+    //   the free-form-composed result shape entirely in v0.6.0; the
+    //   dialog-recorder will read first-class fields directly.
+    //
+    //   No in-repo consumers currently read these fields (verified
+    //   `grep -rn '_debug\?.attempts\|_debug.attempts\|_debug\?.warnings\|_debug.warnings'
+    //   apps/ playgrounds/ catalog/ packages/` → 0 hits at v0.5.3 cut).
+    //   External consumers should treat v0.6.0 as the migration window.
     _debug: isRecording() ? {
       systemPrompt: null,
       rawLLMResponse: null,
       tokens: null,
-      plan: result.plan,
       attempts: result.attempts,
       warnings: result.warnings,
     } : undefined,

package/strategies/zettel/composition-library.js

@@ -101,7 +101,17 @@ async function _loadAllNode() {
 
   function walk(dir, cb) {
     if (!fs.existsSync(dir)) return;
-    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    // §160 (v0.5.3, F-S1 root cause): sort readdir output. fs.readdirSync
+    // returns entries in filesystem-defined order (variable across
+    // processes on APFS/ext4), which means chunk-loading order varied
+    // run-to-run. When two chunks tied on score for a given intent, the
+    // first-loaded won the tie-break — so the same intent could match
+    // chunk A in one process and chunk B in the next. Surfaced as
+    // ~40% probe-failure rate on admin-dashboard post-§143 (the new
+    // chunks compete with the original 4-row KPI composition).
+    const entries = fs.readdirSync(dir, { withFileTypes: true })
+      .sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
       const p = path.join(dir, entry.name);
       if (entry.isDirectory()) walk(p, cb);
       else if (entry.name.endsWith('.json') && !entry.name.startsWith('_')) cb(p);