@adia-ai/a2ui-retrieval 0.3.1 → 0.3.3

package/CHANGELOG.md

@@ -7,6 +7,35 @@ Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
 
 _No pending changes._
 
+## [0.3.3] - 2026-05-07
+
+**Lockstep cut.** All 9 published `@adia-ai/*` packages now share version `0.3.3`, governed by [`docs/specs/package-architecture.md` § 15](../../../docs/specs/package-architecture.md#15-versioning-policy). Internal `@adia-ai/*` ranges stay at `^0.3.0` (patch-cut asymmetry — caret floats `0.3.x`).
+
+### Changed
+
+- **`feedback/dialog-recorder.isRecording()`** — extended to honor
+  the new `A2UI_COMPOSE_TRACE` env var (companion to the
+  `compose:trace` flag in `@adia-ai/a2ui-compose/core/generator.js`).
+  When tracing is on, `isRecording()` returns true so engines
+  populate `_debug` payloads (which the trace consumes); without
+  this, traces would be empty when feedback recording is off.
+  (closes backlog #89)
+
+## [0.3.2] - 2026-05-06
+
+**9-package lockstep patch cut to v0.3.2.** All lockstep members share
+one version per [`docs/specs/package-architecture.md` § 15](../../../docs/specs/package-architecture.md#15-versioning-policy).
+Internal `@adia-ai/*` dep ranges unchanged at `^0.3.0`.
+
+### No source changes
+
+This package's source is byte-identical to v0.3.1. The cut bumps
+version only.
+
+### Changed
+
+- `version`: `0.3.1` → `0.3.2`.
+
 ## [0.3.1] - 2026-05-06
 
 **9-package lockstep patch cut.** All 9 published `@adia-ai/*` packages bump 0.3.0 → 0.3.1 per [`docs/specs/package-architecture.md` § 15](../../../docs/specs/package-architecture.md#15-versioning-policy). Internal `@adia-ai/*` dep ranges remain at `^0.3.0` (covers `0.3.1` under semver — patch-cut asymmetry).

package/embedding/chunk-embedding-retriever.js

@@ -70,10 +70,36 @@ async function _loadIndex() {
 }
 
 function _resolveEmbed(providerName, model) {
-  if (providerName === 'voyage') return voyage({ model });
-  if (providerName === 'openai') return openai({ model });
-  const auto = detectProvider();
-  return auto?.embed || null;
+  // The index's recorded (provider, model) is the source of truth — query
+  // embeddings MUST be generated by the same model the corpus was indexed
+  // with. If they're different models (e.g. voyage-3-lite vs.
+  // text-embedding-3-small), the cosine similarity is meaningless, and even
+  // same-provider/different-model (e.g. text-embedding-3-small@1536 vs
+  // text-embedding-3-large@3072) will emit different dim vectors which
+  // cosine() short-circuits to 0 — silent retrieval failure.
+  //
+  // Fail loud: do NOT silently fall back to a different provider's auto-pick.
+  // Caller (available()) returns false → keyword-only retrieval, which is
+  // the right behavior, but with a console.warn so the cause is visible.
+  let fn = null;
+  if (providerName === 'voyage') fn = voyage({ model });
+  else if (providerName === 'openai') fn = openai({ model });
+  else {
+    // No provider recorded in index header (legacy index?). Fall back to
+    // auto-detect — this preserves the old behavior for indexes that pre-date
+    // the provider/model header convention.
+    const auto = detectProvider();
+    return auto?.embed || null;
+  }
+  if (!fn && typeof console !== 'undefined') {
+    console.warn(
+      `[chunk-embedding-retriever] index was built with provider=${providerName} model=${model}, ` +
+      `but the corresponding API key is not set. Embeddings will be unavailable; falling back to ` +
+      `keyword-only retrieval. Set the matching API key, or rebuild the index with the available ` +
+      `provider via \`npm run build:embeddings:chunks\`.`
+    );
+  }
+  return fn;
 }
 
 export async function available() {

package/embedding/embedding-retriever.js

@@ -71,11 +71,31 @@ async function _loadIndex() {
 
 /** Resolve the embed function matching the index's provider. */
 function _resolveEmbed(providerName, model) {
-  if (providerName === 'voyage') return voyage({ model });
-  if (providerName === 'openai') return openai({ model });
-  // Unknown or null — fall through to whatever's available.
-  const auto = detectProvider();
-  return auto?.embed || null;
+  // The index's recorded (provider, model) is the source of truth — query
+  // embeddings MUST be generated by the same model the corpus was indexed
+  // with. Cross-provider mixing produces meaningless cosine scores; even
+  // same-provider/different-model emits different-dim vectors which cosine()
+  // short-circuits to 0 — silent retrieval failure. Fail loud (warn + null)
+  // when the recorded provider's key is unset, instead of auto-picking a
+  // different provider that would silently corrupt similarity rankings.
+  // (See chunk-embedding-retriever.js for the parallel implementation.)
+  let fn = null;
+  if (providerName === 'voyage') fn = voyage({ model });
+  else if (providerName === 'openai') fn = openai({ model });
+  else {
+    // No provider recorded in index header (legacy index) — fall through.
+    const auto = detectProvider();
+    return auto?.embed || null;
+  }
+  if (!fn && typeof console !== 'undefined') {
+    console.warn(
+      `[embedding-retriever] index was built with provider=${providerName} model=${model}, ` +
+      `but the corresponding API key is not set. Embeddings will be unavailable; falling back ` +
+      `to keyword-only retrieval. Set the matching API key, or rebuild the index with the ` +
+      `available provider via \`npm run build:embeddings\`.`
+    );
+  }
+  return fn;
 }
 
 /**

package/feedback/dialog-recorder.js

@@ -173,7 +173,13 @@ export async function recordTurn(record) {
   }
 }
 
-/** True when logging is on. Useful for guarding expensive capture work. */
+/** True when logging is on. Useful for guarding expensive capture work.
+ *
+ * Also returns true when `A2UI_COMPOSE_TRACE` is set, since the compose-trace
+ * flag in `compose/core/generator.js` consumes the same `_debug` payload —
+ * if we don't force-enable here, traces would be empty when the dialog
+ * recorder is off (the common case).
+ */
 export function isRecording() {
-  return ENABLED;
+  return ENABLED || !!process.env.A2UI_COMPOSE_TRACE;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/a2ui-retrieval",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "AdiaUI A2UI retrieval layer \u2014 catalog lookup, intent classification, domain routing, pattern + anti-pattern matching, clarity + context assembly. Consumed by the compose engine and any A2UI-protocol tooling that needs to reason about user intent against the catalog.",
   "type": "module",
   "main": "./index.js",