@adia-ai/a2ui-retrieval 0.6.4 → 0.6.6

package/embedding/chunk-embedding-retriever.js

@@ -1,55 +1,44 @@
-/**
- * Chunk embedding retriever — loads the build-time chunk embedding index
- * and scores a query against every chunk via cosine similarity.
- *
- * Sibling to `embedding-retriever.js` (pattern embeddings); same provider
- * conventions, same graceful-degradation contract.
- *
- * Index: packages/a2ui/corpus/chunk-embeddings.json (built by
- * scripts/build/embeddings-chunks.mjs). When missing or empty, the
- * retriever is effectively a no-op — callers see an empty score map and
- * should fall back to keyword-only ranking.
- *
- * Used by chunk-library.searchChunks() to blend semantic + keyword scores.
- */
-
-import { detectProvider, cosine, voyage, openai } from './embedding-provider.js';
-
-const IS_NODE = typeof process !== 'undefined' && !!process.versions?.node;
-
+import { detectProvider, cosine, voyage, openai } from "./embedding-provider.js";
+const IS_NODE = typeof process !== "undefined" && !!process.versions?.node;
 let _index = null;
-let _indexByName = null; // Map<chunk-name, Float32Array>
+let _indexByName = null;
 let _loadPromise = null;
 let _embedFn = null;
 let _available = null;
-
 async function _loadIndex() {
   if (_index !== null) return _index;
   if (_loadPromise) return _loadPromise;
   _loadPromise = (async () => {
     try {
       if (IS_NODE) {
-        const fs = await import(/* @vite-ignore */ 'node:fs/promises');
-        const path = await import(/* @vite-ignore */ 'node:path');
-        const url = await import(/* @vite-ignore */ 'node:url');
-        // Try the package-import path first (works under node_modules
-        // install layout — `@adia-ai/a2ui-corpus` exports
-        // `./chunk-embeddings`). Fall back to the relative source-tree
-        // path so a source-checkout monorepo without symlinked deps
-        // still resolves.
+        const fs = await import(
+          /* @vite-ignore */
+          "node:fs/promises"
+        );
+        const path = await import(
+          /* @vite-ignore */
+          "node:path"
+        );
+        const url = await import(
+          /* @vite-ignore */
+          "node:url"
+        );
         let p = null;
         try {
-          const { createRequire } = await import(/* @vite-ignore */ 'node:module');
-          const require = createRequire(import.meta.url);
-          p = require.resolve('@adia-ai/a2ui-corpus/chunk-embeddings');
+          const { createRequire } = await import(
+            /* @vite-ignore */
+            "node:module"
+          );
+          const require2 = createRequire(import.meta.url);
+          p = require2.resolve("@adia-ai/a2ui-corpus/chunk-embeddings");
         } catch {
           const here = path.dirname(url.fileURLToPath(import.meta.url));
-          p = path.resolve(here, '../../corpus/chunk-embeddings.json');
+          p = path.resolve(here, "../../corpus/chunk-embeddings.json");
         }
-        const raw = await fs.readFile(p, 'utf8');
+        const raw = await fs.readFile(p, "utf8");
         _index = JSON.parse(raw);
       } else {
-        const url = new URL('../../corpus/chunk-embeddings.json', import.meta.url);
+        const url = new URL("../../corpus/chunk-embeddings.json", import.meta.url);
         const res = await fetch(url).catch(() => null);
         _index = res?.ok ? await res.json().catch(() => null) : null;
       }
@@ -57,7 +46,7 @@ async function _loadIndex() {
       _index = null;
     }
     if (_index?.chunks?.length) {
-      _indexByName = new Map();
+      _indexByName = /* @__PURE__ */ new Map();
       for (const c of _index.chunks) {
         if (c?.name && Array.isArray(c.vector)) {
           _indexByName.set(c.name, Float32Array.from(c.vector));
@@ -68,41 +57,22 @@ async function _loadIndex() {
   })();
   return _loadPromise;
 }
-
 function _resolveEmbed(providerName, model) {
-  // 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 });
+  if (providerName === "voyage") fn = voyage({ ...model !== void 0 ? { model } : {} });
+  else if (providerName === "openai") fn = openai({ ...model !== void 0 ? { 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;
+    return auto?.embed ?? null;
   }
-  if (!fn && typeof console !== 'undefined') {
+  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\`.`
+      `[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() {
+async function available() {
   if (_available !== null) return _available;
   const idx = await _loadIndex();
   if (!idx || !idx.chunks?.length) {
@@ -113,37 +83,35 @@ export async function available() {
   _available = !!_embedFn;
   return _available;
 }
-
-/**
- * Embed a query and return a Map<chunk-name → cosine-score>.
- * Returns an empty Map when unavailable (no index or no API key).
- */
-export async function scoreAll(query) {
-  if (!query || typeof query !== 'string') return new Map();
-  if (!(await available())) return new Map();
-
+async function scoreAll(query) {
+  if (!query || typeof query !== "string") return /* @__PURE__ */ new Map();
+  if (!await available()) return /* @__PURE__ */ new Map();
   let qVec;
   try {
     const [v] = await _embedFn([query]);
     qVec = v;
   } catch (e) {
-    if (typeof console !== 'undefined') console.warn('[chunk-embedding-retriever]', e.message);
-    return new Map();
+    if (typeof console !== "undefined") console.warn("[chunk-embedding-retriever]", e.message);
+    return /* @__PURE__ */ new Map();
   }
-
-  const out = new Map();
+  const out = /* @__PURE__ */ new Map();
+  if (!_indexByName) return out;
   for (const [name, vec] of _indexByName) {
     out.set(name, cosine(qVec, vec));
   }
   return out;
 }
-
-export async function size() {
+async function size() {
   const idx = await _loadIndex();
-  return idx?.chunks?.length || 0;
+  return idx?.chunks?.length ?? 0;
 }
-
-export async function providerInfo() {
+async function providerInfo() {
   const idx = await _loadIndex();
   return idx ? { provider: idx.provider, model: idx.model, dims: idx.dims } : null;
 }
+export {
+  available,
+  providerInfo,
+  scoreAll,
+  size
+};

package/embedding/chunk-embedding-retriever.ts

@@ -84,8 +84,8 @@ function _resolveEmbed(providerName: string | undefined, model: string | undefin
   // 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.
   let fn: EmbedFn | null = null;
-  if (providerName === 'voyage') fn = voyage({ model });
-  else if (providerName === 'openai') fn = openai({ model });
+  if (providerName === 'voyage') fn = voyage({ ...(model !== undefined ? { model } : {}) });
+  else if (providerName === 'openai') fn = openai({ ...(model !== undefined ? { model } : {}) });
   else {
     // No provider recorded in index header (legacy index?). Fall back to auto-detect.
     const auto = detectProvider();

package/embedding/embedding-provider.js

@@ -1,108 +1,72 @@
-/**
- * Pluggable embedding provider. Two implementations:
- *
- *   voyage() — Voyage AI, voyage-3-lite by default (1024 dims).
- *              Env: VOYAGE_API_KEY. Anthropic-recommended; generous free tier.
- *
- *   openai() — OpenAI text-embedding-3-small (1536 dims).
- *              Env: OPENAI_API_KEY. Cheap ($0.02/1M tokens).
- *
- * detectProvider() picks Voyage if available, else OpenAI, else null.
- * A null provider means "embeddings unavailable" — callers should fall back
- * to keyword retrieval cleanly.
- *
- * Both implementations batch inputs to minimize round-trips. Every provider
- * returns a Promise<Float32Array[]> of the same length as the input.
- */
-
-const VOYAGE_URL = 'https://api.voyageai.com/v1/embeddings';
-const OPENAI_URL = 'https://api.openai.com/v1/embeddings';
-
+const VOYAGE_URL = "https://api.voyageai.com/v1/embeddings";
+const OPENAI_URL = "https://api.openai.com/v1/embeddings";
 function getEnv(key) {
-  if (typeof process !== 'undefined' && process.env?.[key]) return process.env[key];
+  if (typeof process !== "undefined" && process.env?.[key]) return process.env[key];
   try {
     const env = import.meta.env;
     if (env?.[`VITE_${key}`]) return env[`VITE_${key}`];
     if (env?.[key]) return env[key];
-  } catch {}
-  return '';
+  } catch {
+  }
+  return "";
 }
-
-/**
- * Voyage AI embedding provider.
- *
- * @param {object} [opts]
- * @param {string} [opts.apiKey] — defaults to env VOYAGE_API_KEY
- * @param {string} [opts.model]  — voyage-3-lite | voyage-3 | voyage-code-3
- * @returns {(texts: string[]) => Promise<Float32Array[]>} embedder, or null if no key
- */
-export function voyage({ apiKey, model = 'voyage-3-lite' } = {}) {
-  const key = apiKey || getEnv('VOYAGE_API_KEY');
+function voyage({ apiKey, model = "voyage-3-lite" } = {}) {
+  const key = apiKey ?? getEnv("VOYAGE_API_KEY");
   if (!key) return null;
-
   return async function embed(texts) {
     if (!Array.isArray(texts) || texts.length === 0) return [];
     const res = await fetch(VOYAGE_URL, {
-      method: 'POST',
+      method: "POST",
       headers: {
-        'content-type': 'application/json',
-        'authorization': `Bearer ${key}`,
+        "content-type": "application/json",
+        "authorization": `Bearer ${key}`
       },
-      body: JSON.stringify({ input: texts, model, input_type: 'document' }),
+      body: JSON.stringify({ input: texts, model, input_type: "document" })
     });
     if (!res.ok) throw new Error(`Voyage ${res.status}: ${(await res.text()).slice(0, 200)}`);
     const data = await res.json();
-    return data.data.map(d => new Float32Array(d.embedding));
+    return data.data.map((d) => new Float32Array(d.embedding));
   };
 }
-
-/**
- * OpenAI text-embedding-3-small provider.
- *
- * @param {object} [opts]
- * @param {string} [opts.apiKey] — defaults to env OPENAI_API_KEY
- * @param {string} [opts.model]  — text-embedding-3-small | text-embedding-3-large
- * @returns {(texts: string[]) => Promise<Float32Array[]>} embedder, or null if no key
- */
-export function openai({ apiKey, model = 'text-embedding-3-small' } = {}) {
-  const key = apiKey || getEnv('OPENAI_API_KEY');
+function openai({ apiKey, model = "text-embedding-3-small" } = {}) {
+  const key = apiKey ?? getEnv("OPENAI_API_KEY");
   if (!key) return null;
-
   return async function embed(texts) {
     if (!Array.isArray(texts) || texts.length === 0) return [];
     const res = await fetch(OPENAI_URL, {
-      method: 'POST',
+      method: "POST",
       headers: {
-        'content-type': 'application/json',
-        'authorization': `Bearer ${key}`,
+        "content-type": "application/json",
+        "authorization": `Bearer ${key}`
       },
-      body: JSON.stringify({ input: texts, model }),
+      body: JSON.stringify({ input: texts, model })
     });
     if (!res.ok) throw new Error(`OpenAI ${res.status}: ${(await res.text()).slice(0, 200)}`);
     const data = await res.json();
-    return data.data.map(d => new Float32Array(d.embedding));
+    return data.data.map((d) => new Float32Array(d.embedding));
   };
 }
-
-/**
- * Auto-detect the best available provider. Voyage first (cheaper, dense vectors
- * at 1024 dims), then OpenAI, then null.
- */
-export function detectProvider() {
-  const v = voyage(); if (v) return { name: 'voyage',  model: 'voyage-3-lite',             embed: v };
-  const o = openai(); if (o) return { name: 'openai',  model: 'text-embedding-3-small',    embed: o };
+function detectProvider() {
+  const v = voyage();
+  if (v) return { name: "voyage", model: "voyage-3-lite", embed: v };
+  const o = openai();
+  if (o) return { name: "openai", model: "text-embedding-3-small", embed: o };
   return null;
 }
-
-/** Cosine similarity between two Float32Arrays of the same length. */
-export function cosine(a, b) {
+function cosine(a, b) {
   if (!a || !b || a.length !== b.length) return 0;
   let dot = 0, na = 0, nb = 0;
   for (let i = 0; i < a.length; i++) {
-    dot += a[i] * b[i];
-    na  += a[i] * a[i];
-    nb  += b[i] * b[i];
+    dot += (a[i] ?? 0) * (b[i] ?? 0);
+    na += (a[i] ?? 0) * (a[i] ?? 0);
+    nb += (b[i] ?? 0) * (b[i] ?? 0);
   }
   if (na === 0 || nb === 0) return 0;
   return dot / (Math.sqrt(na) * Math.sqrt(nb));
 }
+export {
+  cosine,
+  detectProvider,
+  openai,
+  voyage
+};

package/embedding/index.js

@@ -1,10 +1,2 @@
-/**
- * @adia-ai/a2ui-retrieval/embedding — embedding-provider + chunk retriever surface.
- *
- * Since §65 (v0.4.7), the legacy pattern-embedding retriever was retired
- * along with its only consumer (concept-mapper.js, dead post-§64). The
- * canonical retrieval surface post-§40 is chunk-embedding-retriever.
- */
-
-export * from './embedding-provider.js';
-export * from './chunk-embedding-retriever.js';
+export * from "./embedding-provider.js";
+export * from "./chunk-embedding-retriever.js";

package/feedback/dialog-recorder.js

@@ -1,191 +1,107 @@
-/**
- * Dialog Recorder — write every generation turn to disk for debugging,
- * regression analysis, and training-data bootstrapping.
- *
- * Output: logs/dialogs/<sessionId>/<NNN>-<turnId>.json
- *   - <sessionId>: storeId / executionId of the multi-turn session, or
- *                  'standalone-<isodate>' for one-shot generations.
- *   - <NNN>:        zero-padded turn index within the session (000, 001, …)
- *   - <turnId>:     short slug from the intent + a random suffix for uniqueness
- *
- * Each file contains a flat JSON object with everything the pipeline knew at
- * generation time: intent, mode, model, the analyzer's structured signals,
- * pattern matches, the FULL system prompt, the raw LLM response, parsed A2UI
- * messages, validation, drift, suggestions, and timing/token telemetry.
- *
- * Gated by ADIA_LOG_DIALOGS=1 — opt-in, zero overhead when disabled. Browser
- * environment is also a no-op (no fs); only Node-side generation paths log.
- *
- * Use cases:
- *   - replay a single bad turn locally without paying the LLM cost again
- *   - diff two turns visually after wiring the headless renderer
- *   - bootstrap an eval set from real dogfood — every turn becomes a labeled example
- *   - regression detection on prompt / corpus / catalog changes
- */
-
-const IS_NODE = typeof process !== 'undefined' && !!process.versions?.node;
-const ENABLED = IS_NODE && (process.env.ADIA_LOG_DIALOGS === '1' || process.env.ADIA_LOG_DIALOGS === 'true');
-
+const IS_NODE = typeof process !== "undefined" && !!process.versions?.node;
+const ENABLED = IS_NODE && (process?.env?.["ADIA_LOG_DIALOGS"] === "1" || process?.env?.["ADIA_LOG_DIALOGS"] === "true");
 let _fs = null;
 let _path = null;
 let _url = null;
 let _logsRoot = null;
-
 async function _ensureModules() {
   if (_fs) return;
-  _fs = await import(/* @vite-ignore */ 'node:fs/promises');
-  _path = await import(/* @vite-ignore */ 'node:path');
-  _url = await import(/* @vite-ignore */ 'node:url');
-  // logs/ lives at the repo root: packages/a2ui/retrieval/feedback → up 4 → repo root
+  _fs = await import(
+    /* @vite-ignore */
+    "node:fs/promises"
+  );
+  _path = await import(
+    /* @vite-ignore */
+    "node:path"
+  );
+  _url = await import(
+    /* @vite-ignore */
+    "node:url"
+  );
   const __dirname = _path.dirname(_url.fileURLToPath(import.meta.url));
-  _logsRoot = _path.resolve(__dirname, '..', '..', '..', '..', 'logs', 'dialogs');
+  _logsRoot = _path.resolve(__dirname, "..", "..", "..", "..", "logs", "dialogs");
 }
-
-// In-memory turn counter per session — keeps the on-disk turn ordering correct
-// even when timestamps collide (sub-millisecond turns from automated probes).
-const _turnCounter = new Map();
-// Tracks which sessions we've already written `_session.json` for. Per-process
-// memory; if the process restarts mid-session, the file is rewritten, which is
-// fine — content is idempotent.
-const _sessionMetaWritten = new Set();
-
-/**
- * Record one generation turn. Safe to call unconditionally — when the env var
- * is unset, this is a no-op that returns immediately.
- *
- * @param {object} record
- * @param {string} record.sessionId      — multi-turn session handle (storeId / executionId)
- * @param {string} record.intent         — user's prompt this turn
- * @param {string} [record.mode]         — instant | pro | thinking | stream
- * @param {string} [record.engine]       — monolithic | zettel | <custom>
- * @param {string} [record.model]        — LLM model id
- * @param {object} [record.analysis]     — output of analyzePrompt() (concepts, steelman, ...)
- * @param {object} [record.currentCanvas] — { components } or { messages } provided by caller
- * @param {object[]} [record.patterns]   — patterns retrieved by searchBlocks()
- * @param {string} [record.systemPrompt] — full system prompt sent to LLM
- * @param {string} [record.rawLLMResponse] — raw LLM text (pre-parse)
- * @param {object[]} [record.messages]   — parsed A2UI messages (the result)
- * @param {object} [record.validation]   — validateSchema() result
- * @param {object} [record.drift]        — getDriftMetrics() result
- * @param {string[]} [record.suggestions] — follow-up suggestions
- * @param {object} [record.timing]       — { totalMs, llmMs, ... }
- * @param {object} [record.tokens]       — { input, output }
- * @param {object} [record.engineDebug]  — engine-specific extras (strategy, composition, fragmentsUsed for zettel; raw stage reports, etc.)
- * @param {boolean} [record.isIteration] — derived from executionId / currentCanvas presence
- * @returns {Promise<string|null>} the path written, or null when logging is disabled
- */
-export async function recordTurn(record) {
+const _turnCounter = /* @__PURE__ */ new Map();
+const _sessionMetaWritten = /* @__PURE__ */ new Set();
+async function recordTurn(record) {
   if (!ENABLED) return null;
-
   try {
     await _ensureModules();
-
-    const sessionId = record.sessionId || `standalone-${new Date().toISOString().replace(/[:.]/g, '-')}`;
-    const turnIdx = (_turnCounter.get(sessionId) ?? 0);
+    const sessionId = record.sessionId ?? `standalone-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}`;
+    const turnIdx = _turnCounter.get(sessionId) ?? 0;
     _turnCounter.set(sessionId, turnIdx + 1);
-
-    const slug = String(record.intent || 'turn')
-      .toLowerCase()
-      .replace(/[^a-z0-9]+/g, '-')
-      .replace(/^-+|-+$/g, '')
-      .slice(0, 32) || 'turn';
+    const slug = String(record.intent ?? "turn").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 32) || "turn";
     const rand = Math.random().toString(36).slice(2, 6);
-    const fileName = `${String(turnIdx).padStart(3, '0')}-${slug}-${rand}.json`;
-
+    const fileName = `${String(turnIdx).padStart(3, "0")}-${slug}-${rand}.json`;
     const sessionDir = _path.join(_logsRoot, sessionId);
     await _fs.mkdir(sessionDir, { recursive: true });
-
-    // Write per-session header on the first turn so a directory listing is
-    // immediately legible — origin intent, model, mode, first-turn analysis,
-    // start time. Future headless renderer reads this for its session list UI.
     if (!_sessionMetaWritten.has(sessionId) && turnIdx === 0) {
       _sessionMetaWritten.add(sessionId);
       const sessionMeta = {
         sessionId,
-        startedAt: new Date().toISOString(),
-        originIntent: record.intent || null,
-        engine: record.engine || null,
-        mode: record.mode || null,
-        model: record.model || null,
-        // The analyzer's enriched brief + concept tags from turn 0 — these
-        // characterize the session's intent space, not just the latest turn.
+        startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        originIntent: record.intent ?? null,
+        engine: record.engine ?? null,
+        mode: record.mode ?? null,
+        model: record.model ?? null,
         originAnalysis: record.analysis ? {
-          steelman: record.analysis.steelman || null,
-          concepts: record.analysis.concepts || [],
-          impliedComponents: record.analysis.impliedComponents || [],
-          styleHints: record.analysis.styleHints || [],
-        } : null,
+          steelman: record.analysis.steelman ?? null,
+          concepts: record.analysis.concepts ?? [],
+          impliedComponents: record.analysis.impliedComponents ?? [],
+          styleHints: record.analysis.styleHints ?? []
+        } : null
       };
       await _fs.writeFile(
-        _path.join(sessionDir, '_session.json'),
-        JSON.stringify(sessionMeta, null, 2) + '\n',
+        _path.join(sessionDir, "_session.json"),
+        JSON.stringify(sessionMeta, null, 2) + "\n"
       );
     }
-
     const payload = {
       // ── Identity ────────────────────────────────────────────────
       sessionId,
       turnIndex: turnIdx,
-      timestamp: new Date().toISOString(),
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
       isIteration: !!record.isIteration,
-
       // ── Request ─────────────────────────────────────────────────
       intent: record.intent,
-      mode: record.mode || null,
-      engine: record.engine || null,
-      model: record.model || null,
-      currentCanvas: record.currentCanvas || null,
-
+      mode: record.mode ?? null,
+      engine: record.engine ?? null,
+      model: record.model ?? null,
+      currentCanvas: record.currentCanvas ?? null,
       // ── Pipeline-side reasoning ─────────────────────────────────
-      analysis: record.analysis || null,
-      patterns: (record.patterns || []).slice(0, 10).map(p => ({
+      analysis: record.analysis ?? null,
+      patterns: (record.patterns ?? []).slice(0, 10).map((p) => ({
         name: p.name,
         score: p.score ?? p.confidence ?? null,
-        keywords: p.keywords || null,
+        keywords: p.keywords ?? null
       })),
-
-      // ── LLM I/O (the largest fields — keep last for jq usability) ─
-      systemPrompt: record.systemPrompt || null,
-      rawLLMResponse: record.rawLLMResponse || null,
-
+      // ── LLM I/O ─────────────────────────────────────────────────
+      systemPrompt: record.systemPrompt ?? null,
+      rawLLMResponse: record.rawLLMResponse ?? null,
       // ── Result ──────────────────────────────────────────────────
-      messages: record.messages || [],
-      validation: record.validation || null,
-      drift: record.drift || null,
-      suggestions: record.suggestions || [],
-
+      messages: record.messages ?? [],
+      validation: record.validation ?? null,
+      drift: record.drift ?? null,
+      suggestions: record.suggestions ?? [],
       // ── Telemetry ───────────────────────────────────────────────
-      timing: record.timing || null,
-      tokens: record.tokens || null,
-      // Engine-specific extras (zettel: strategy/composition/fragmentsUsed,
-      // monolithic: nothing yet — but reserved). Whatever the engine put on
-      // result._debug above and beyond the standard fields lands here.
-      engineDebug: record.engineDebug || null,
+      timing: record.timing ?? null,
+      tokens: record.tokens ?? null,
+      engineDebug: record.engineDebug ?? null
     };
-
     const filePath = _path.join(sessionDir, fileName);
-    await _fs.writeFile(filePath, JSON.stringify(payload, null, 2) + '\n');
+    await _fs.writeFile(filePath, JSON.stringify(payload, null, 2) + "\n");
     return filePath;
   } catch (err) {
-    // Logging must NEVER break a generation. Swallow + warn once per turn.
-    console.warn('[dialog-recorder] failed to record turn:', err.message);
+    console.warn("[dialog-recorder] failed to record turn:", err.message);
     return null;
   }
 }
-
-/** 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() {
-  // ENABLED is already gated by IS_NODE at module init. The A2UI_COMPOSE_TRACE
-  // bypass must guard `process` again — without it, browser callers
-  // (compose/core/generator.js → generate-pro.js → isRecording()) throw
-  // `ReferenceError: process is not defined` after a successful LLM round-trip.
+function isRecording() {
   if (ENABLED) return true;
-  const IS_NODE = typeof process !== 'undefined' && process.versions?.node;
-  return IS_NODE ? !!process.env.A2UI_COMPOSE_TRACE : false;
+  const IS_NODE_RT = typeof process !== "undefined" && process.versions?.node;
+  return IS_NODE_RT ? !!process?.env?.["A2UI_COMPOSE_TRACE"] : false;
 }
+export {
+  isRecording,
+  recordTurn
+};

package/feedback/dialog-recorder.ts

@@ -19,19 +19,22 @@ const IS_NODE = typeof process !== 'undefined' && !!process.versions?.node;
 const ENABLED = IS_NODE && (process?.env?.['ADIA_LOG_DIALOGS'] === '1' || process?.env?.['ADIA_LOG_DIALOGS'] === 'true');
 
 // Lazy-loaded Node modules (only when ENABLED)
-let _fs: typeof import('node:fs/promises') | null = null;
-let _path: typeof import('node:path') | null = null;
-let _url: typeof import('node:url') | null = null;
+type _FsModule = { readFile(p: string, enc: string): Promise<string>; writeFile(p: string, d: string): Promise<void>; mkdir(p: string, opts?: { recursive?: boolean }): Promise<string | undefined> };
+type _PathModule = { dirname(p: string): string; resolve(...args: string[]): string; join(...args: string[]): string };
+type _UrlModule = { fileURLToPath(u: string): string };
+let _fs: _FsModule | null = null;
+let _path: _PathModule | null = null;
+let _url: _UrlModule | null = null;
 let _logsRoot: string | null = null;
 
 async function _ensureModules(): Promise<void> {
   if (_fs) return;
-  _fs = await import(/* @vite-ignore */ 'node:fs/promises');
-  _path = await import(/* @vite-ignore */ 'node:path');
-  _url = await import(/* @vite-ignore */ 'node:url');
+  _fs = await import(/* @vite-ignore */ 'node:fs/promises') as unknown as _FsModule;
+  _path = await import(/* @vite-ignore */ 'node:path') as unknown as _PathModule;
+  _url = await import(/* @vite-ignore */ 'node:url') as unknown as _UrlModule;
   // logs/ lives at the repo root: packages/a2ui/retrieval/feedback → up 4 → repo root
-  const __dirname = _path.dirname(_url.fileURLToPath(import.meta.url));
-  _logsRoot = _path.resolve(__dirname, '..', '..', '..', '..', 'logs', 'dialogs');
+  const __dirname = _path!.dirname(_url!.fileURLToPath(import.meta.url));
+  _logsRoot = _path!.resolve(__dirname, '..', '..', '..', '..', 'logs', 'dialogs');
 }
 
 // In-memory turn counter per session