@adia-ai/a2ui-compose 0.5.2 → 0.5.3

package/CHANGELOG.md

@@ -12,6 +12,29 @@ 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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/a2ui-compose",
-  "version": "0.5.2",
+  "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/registry.js

@@ -191,6 +191,33 @@ async function generateFreeFormAdapter(ctx) {
     // 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,

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