@adia-ai/a2ui-retrieval 0.4.5 → 0.4.7

package/CHANGELOG.md

@@ -7,6 +7,32 @@ Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
 
 _No pending changes._
 
+## [0.4.7] - 2026-05-12
+
+### Removed — `embedding/embedding-retriever.js` + `concept-mapper.js` retired (§72, the §65 carry-over)
+
+The pattern-embeddings retrieval surface — `embedding-retriever.js` and its sole consumer `concept-mapper.js` (dead since v0.4.6 §64 retired `pattern-library.js`) — has been deleted from `packages/a2ui/retrieval/`. Companion artifacts in `@adia-ai/a2ui-corpus` (`pattern-embeddings.json` data file + `./pattern-embeddings` subpath export) and repo-side (`scripts/build/embeddings.mjs` + `build:embeddings` / `build:embeddings:all` npm scripts) retired in the same arc.
+
+`embedding/index.js` no longer re-exports from `embedding-retriever.js`. The remaining surface: `embedding-provider.js` (provider abstraction over Voyage / OpenAI) + `chunk-embedding-retriever.js` (the canonical embedding-based retriever, scoped to chunks).
+
+### Changed — `intent/prompt-analyzer.js` `getVocab()` reads canonical catalog (§72)
+
+Migrated from `@adia-ai/a2ui-corpus/patterns/_components.json` (retired) to `@adia-ai/a2ui-corpus/catalog-a2ui_0_9.json` (the canonical v0.9 catalog). Vocabulary now built from `components[name].x-adiaui.synonyms.tags`. Same `displayList` + `allowedSet` output shape; no behavior change for downstream callers.
+
+## [0.4.6] - 2026-05-12
+
+### Changed — `pattern-library.js` retired, consumers migrate to `composition-library` (§64 multi-step, 2026-05-12)
+
+The legacy `pattern-library.js` retrieval surface is retired in v0.4.6. Compositions (`@adia-ai/a2ui-compose/strategies/zettel/composition-library.js`) are now the canonical retrieval source — the §41 unification of compositions + annotated chunks made `pattern-library.js` redundant. Six-step migration (commits `cd11939d` / `67d3075c` / `c2336895` / `7cd42ca4` / `9abcd8ce` / `a4814384`):
+
+- **`pattern-library.js` retired** (§64 step 6). `reference.js` now delegates to `composition-library` for all reads; the file remains as a thin shim that re-exports the new path while emitting a one-shot deprecation warn for direct importers.
+- **`component-catalog.js` carved out of `pattern-library`** (§64 step 1). Previously the catalog ride-along on the pattern surface; now lives at its own module path so consumers can drop `pattern-library` without losing the catalog. Re-exported from the package barrel.
+- **`context-assembler.js` + `intent/clarity.js` migrated to `composition-library`** (§64 step 4). Both modules previously asked `pattern-library.search(intent)`; now ask `compositionLibrary.search(intent)`. Behavior preserved — the new lookup returns the same shape post-§41 normalization.
+- **`authoring/index.js` + `authoring/pattern-promotion.js` + `authoring/synthetic-data.js` retired** (§64 step 2). All three were dead code by §63 (pattern-promotion fired on a surface that no consumer exercised; synthetic-data targeted the pattern shape). Files deleted; barrel re-exports cleaned.
+- **`index.js`** — barrel updated to reflect the carved-out + retired modules.
+
+See root [CHANGELOG.md `[Unreleased]`](../../../CHANGELOG.md) and `@adia-ai/a2ui-compose@[Unreleased]` for the cross-cutting arc narrative.
+
 ## [0.4.5] - 2026-05-12
 
 ### Ride-along (no source changes)

package/authoring/index.js

@@ -1,13 +1,9 @@
 /**
  * @adia-ai/a2ui-retrieval/authoring — corpus authoring helpers.
  *
- * Scripts and helpers that produce or extend retrieval inputs:
- * synthetic-data generation, web research, pattern promotion. These are
- * upstream of retrieval (they create what retrieval reads) — kept inside
- * the retrieval package because they share the catalog + pattern-library
- * surfaces, but logically a separate concern from lookup.
+ * Web-research helpers used by `compose/core/generator.js` to enrich
+ * intent before generation. Synthetic-data + pattern-promotion retired
+ * in §64 alongside `pattern-library.js`.
  */
 
-export * from './synthetic-data.js';
 export * from './web-research.js';
-export * from './pattern-promotion.js';

package/component-catalog.js

@@ -0,0 +1,111 @@
+/**
+ * Component Catalog — Loads `.a2ui.json` sidecars from web-components/.
+ *
+ * The `.a2ui.json` sidecars are hand-authored component contracts that
+ * live alongside their components in `packages/web-components/components/`.
+ * They are part of the component library — NOT the training corpus — and
+ * are the canonical source of truth for component shape (v0.9 JSON Schema
+ * with `x-adiaui` extension for retrieval signals).
+ *
+ * §66 wired these into `buildSystemPrompt` as the authoritative component
+ * descriptor. §64 split this loader out of the now-retired
+ * `pattern-library.js` so it survives the patterns corpus deletion.
+ *
+ * Works in both Node.js (readdir/readFile) and the browser (Vite glob).
+ */
+
+const IS_NODE =
+  typeof process !== 'undefined' &&
+  typeof process.versions?.node === 'string';
+
+/** @type {Map<string, object>} */
+const _componentData = new Map();
+
+let _loaded = false;
+let _loadPromise = null;
+
+// Vite resolves this at build time; at runtime in Node the variable is unused.
+let _globA2UIModules = null;
+if (!IS_NODE) {
+  try {
+    _globA2UIModules = import.meta.glob('../../web-components/components/**/*.a2ui.json', {
+      query: '?raw',
+      import: 'default',
+    });
+  } catch {
+    // Not in a Vite context — no component data
+  }
+}
+
+async function _loadNode() {
+  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');
+
+  const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
+  const componentsDir = path.resolve(__dirname, '..', '..', 'web-components', 'components');
+
+  let compEntries;
+  try {
+    compEntries = await fs.readdir(componentsDir, { withFileTypes: true });
+  } catch {
+    return; // components dir doesn't exist — skip
+  }
+
+  for (const compEntry of compEntries) {
+    if (!compEntry.isDirectory()) continue;
+    const a2uiPath = path.join(componentsDir, compEntry.name, `${compEntry.name}.a2ui.json`);
+    try {
+      const raw = await fs.readFile(a2uiPath, 'utf8');
+      const data = JSON.parse(raw);
+      if (data?.title) _componentData.set(data.title, data);
+    } catch {
+      // No .a2ui.json for this component — skip
+    }
+  }
+}
+
+async function _loadBrowser() {
+  if (!_globA2UIModules) return;
+
+  for (const [, loader] of Object.entries(_globA2UIModules)) {
+    try {
+      const raw = await loader();
+      const data = JSON.parse(raw);
+      if (data?.title) _componentData.set(data.title, data);
+    } catch {
+      // skip malformed .a2ui.json
+    }
+  }
+}
+
+export async function loadCatalog() {
+  if (_loaded) return;
+  if (_loadPromise) return _loadPromise;
+  _loadPromise = (async () => {
+    if (IS_NODE) await _loadNode();
+    else await _loadBrowser();
+  })();
+  await _loadPromise;
+  _loaded = true;
+}
+
+// Eager load on module import so the synchronous getters below are safe.
+await loadCatalog();
+
+/**
+ * Get `.a2ui.json` data for a named component.
+ * @param {string} name — PascalCase component name (e.g., "Swiper")
+ * @returns {object|null} raw .a2ui.json document, or null
+ */
+export function getComponentData(name) {
+  return _componentData.get(name) || null;
+}
+
+/**
+ * Get all loaded `.a2ui.json` component data.
+ * @returns {Object.<string, object>} component name → .a2ui.json data
+ */
+export function getAllComponentData() {
+  return Object.fromEntries(_componentData);
+}

package/context-assembler.js

@@ -11,7 +11,11 @@ import { getCatalog, getComponentsByCategory } from './catalog.js';
 import { serializeEntry } from './component-entry.js';
 import { classifyIntent, getDomain } from './domain-router.js';
 import { getAntiPatterns } from './anti-patterns.js';
-import { searchPatterns, getAllPatterns } from './pattern-library.js';
+import {
+  searchAll as searchCompositions,
+  getComposition,
+  getAllCompositions,
+} from '../compose/strategies/zettel/composition-library.js';
 
 /** Token budget per tier */
 const TIER_BUDGETS = {
@@ -125,28 +129,30 @@ export async function assembleContext({ intent = '', tier = 1, domain: overrideD
     }
   }
 
-  // ── Tier 3+: Add matching patterns ──
+  // ── Tier 3+: Add matching compositions ──
+  // §64 migrated from pattern-library to composition-library. Compositions
+  // are the canonical retrieval surface post-§65.
   if (tier >= 3) {
-    const matchedPatterns = intent
-      ? searchPatterns(intent)
-      : getAllPatterns().filter(p => p.domain === domainName);
+    const matchedCompositions = intent
+      ? searchCompositions(intent).map((hit) => getComposition(hit.name)).filter(Boolean)
+      : getAllCompositions().filter((c) => c.domain === domainName);
 
-    for (const pattern of matchedPatterns) {
-      const cost = estimateTokens(pattern);
+    for (const composition of matchedCompositions) {
+      const cost = estimateTokens(composition);
       if (usedTokens + cost > budget) break;
-      result.patterns.push(pattern);
+      result.patterns.push(composition);
       usedTokens += cost;
     }
   }
 
-  // ── Tier 4: Full exploration — add remaining patterns ──
+  // ── Tier 4: Full exploration — add remaining compositions ──
   if (tier >= 4) {
-    const addedPatterns = new Set(result.patterns.map(p => p.name));
-    for (const pattern of getAllPatterns()) {
-      if (addedPatterns.has(pattern.name)) continue;
-      const cost = estimateTokens(pattern);
+    const added = new Set(result.patterns.map((c) => c.name));
+    for (const composition of getAllCompositions()) {
+      if (added.has(composition.name)) continue;
+      const cost = estimateTokens(composition);
       if (usedTokens + cost > budget) break;
-      result.patterns.push(pattern);
+      result.patterns.push(composition);
       usedTokens += cost;
     }
   }

package/embedding/index.js

@@ -1,7 +1,10 @@
 /**
- * @adia-ai/a2ui-retrieval/embedding — embedding-provider + retrievers surface.
+ * @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 './embedding-retriever.js';
 export * from './chunk-embedding-retriever.js';

package/index.js

@@ -10,7 +10,7 @@ export { isConversational } from './intent/intent-gate.js';
 export { assessClarity } from './intent/clarity.js';
 export { detectReferences, researchIntent } from './authoring/web-research.js';
 export { assembleContext } from './context-assembler.js';
-export { getPattern, searchPatterns, semanticSearchPatterns, getAllPatterns, registerPattern } from './pattern-library.js';
+export { getComponentData, getAllComponentData } from './component-catalog.js';
 export { extractExpectations, verifyAlignment, checkIntentAlignment } from './intent/intent-alignment.js';
 export { decomposeIntent, composeSubtasks } from './intent/decomposer.js';
 export { getWiringCatalog, getControllerInfo, getHandlerInfo } from './wiring-catalog.js';

package/intent/clarity.js

@@ -13,7 +13,7 @@
  */
 
 import { classifyIntent } from '../domain-router.js';
-import { searchPatterns } from '../pattern-library.js';
+import { searchAll as searchCompositions } from '../../compose/strategies/zettel/composition-library.js';
 
 // ── Dimension detectors ──────────────────────────────────────────────────
 
@@ -81,7 +81,7 @@ export function assessClarity(intent, classification) {
   }
 
   const cls = classification || classifyIntent(text);
-  const patterns = searchPatterns(text);
+  const compositionMatches = searchCompositions(text);
   const lower = text.toLowerCase();
   const wordCount = text.split(/\s+/).length;
 
@@ -115,8 +115,8 @@ export function assessClarity(intent, classification) {
     actionScore * 0.15
   );
 
-  // ── Bonus: pattern match adds confidence ──
-  const patternBonus = patterns.length > 0 ? 0.15 : 0;
+  // ── Bonus: composition match adds confidence ──
+  const patternBonus = compositionMatches.length > 0 ? 0.15 : 0;
   // Bonus: long intents are usually more specific
   const lengthBonus = wordCount > 10 ? 0.1 : wordCount > 6 ? 0.05 : 0;
 

package/intent/prompt-analyzer.js

@@ -38,28 +38,36 @@
 let _vocab = null;
 async function getVocab() {
   if (_vocab) return _vocab;
-  let catalog = {};
+  let catalogJson = {};
   try {
     const IS_NODE = typeof process !== 'undefined' && process.versions?.node;
     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');
-      // packages/a2ui/retrieval/intent → up 2 → packages/a2ui → corpus/patterns/_components.json
+      // Since §65 (v0.4.7), reads from canonical v0.9 catalog at
+      // corpus/catalog-a2ui_0_9.json (assembled from yamls). Previously read
+      // the hand-maintained corpus/patterns/_components.json retired in §65.
+      // packages/a2ui/retrieval/intent → up 2 → packages/a2ui → corpus/catalog-a2ui_0_9.json
       const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
-      const raw = await fs.readFile(path.join(__dirname, '../../corpus/patterns/_components.json'), 'utf8');
-      catalog = JSON.parse(raw);
+      const raw = await fs.readFile(path.join(__dirname, '../../corpus/catalog-a2ui_0_9.json'), 'utf8');
+      catalogJson = JSON.parse(raw);
     } else {
-      const resp = await fetch(new URL('../../corpus/patterns/_components.json', import.meta.url));
-      if (resp.ok) catalog = await resp.json();
+      const resp = await fetch(new URL('../../corpus/catalog-a2ui_0_9.json', import.meta.url));
+      if (resp.ok) catalogJson = await resp.json();
     }
   } catch { /* empty vocab — analyzer will still work, just unconstrained */ }
 
+  // Adapt v0.9 catalog shape: `components: {Name: {x-adiaui: {synonyms: {tags: [...]}}}}`
+  // → legacy `{Name: {aliases}}` shape this vocab builder expects.
+  const comps = catalogJson?.components || {};
   const displayList = [];
   const allowedSet = new Set();
-  for (const [name, data] of Object.entries(catalog)) {
+  for (const [name, def] of Object.entries(comps)) {
     allowedSet.add(name);
-    const aliases = Array.isArray(data?.aliases) ? data.aliases : [];
+    const ext = def?.['x-adiaui'] || {};
+    const syns = (ext.synonyms && typeof ext.synonyms === 'object') ? ext.synonyms : null;
+    const aliases = Array.isArray(syns?.tags) ? syns.tags : [];
     for (const a of aliases) allowedSet.add(a);
     displayList.push(aliases.length ? `${name} (also: ${aliases.join(', ')})` : name);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/a2ui-retrieval",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "description": "AdiaUI A2UI retrieval layer — 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",

package/authoring/pattern-promotion.js

@@ -1,135 +0,0 @@
-/**
- * Pattern Promotion — Automatically identifies generations that should
- * become reusable patterns based on quality signals and user feedback.
- *
- * Promotion criteria (all must be met):
- *   - Generation score >= 95
- *   - Feedback rating >= 4 (if feedback exists)
- *   - Intent alignment score >= 0.8 (if checked)
- *   - User didn't heavily edit the output
- *   - Explicit shouldBePattern flag (from feedback) OR auto-detected
- *
- * Auto-detection: a generation is auto-promoted if it scores high on all
- * dimensions and uses a novel combination of components not already in
- * the pattern library.
- */
-
-import { getAllPatterns } from '../pattern-library.js';
-
-/**
- * Evaluate whether a generation should be promoted to a named pattern.
- *
- * @param {object} opts
- * @param {number} opts.score — Validation score (0-100)
- * @param {object} [opts.feedback] — User feedback { rating, userEdited }
- * @param {object} [opts.alignment] — Intent alignment { score }
- * @param {string[]} opts.componentTypes — Component types used in generation
- * @param {string} opts.intent — Original intent
- * @returns {{ shouldPromote: boolean, confidence: number, reason: string, suggestedName: string }}
- */
-export function evaluatePromotion({ score, feedback, alignment, componentTypes, intent }) {
-  let confidence = 0;
-  const reasons = [];
-
-  // ── Hard gates ──
-  if (score < 95) {
-    return { shouldPromote: false, confidence: 0, reason: `Score ${score} < 95`, suggestedName: '' };
-  }
-
-  // Score contribution (0.3 weight)
-  confidence += (score / 100) * 0.3;
-  reasons.push(`score: ${score}/100`);
-
-  // ── Feedback signals (0.3 weight) ──
-  if (feedback) {
-    if (feedback.rating >= 4) {
-      confidence += (feedback.rating / 5) * 0.2;
-      reasons.push(`rating: ${feedback.rating}/5`);
-    } else if (feedback.rating > 0) {
-      return { shouldPromote: false, confidence, reason: `Rating ${feedback.rating} < 4`, suggestedName: '' };
-    }
-
-    if (feedback.userEdited) {
-      confidence -= 0.15;
-      reasons.push('user edited (penalty)');
-    }
-
-    if (feedback.shouldBePattern) {
-      confidence += 0.15;
-      reasons.push('user flagged as pattern');
-    }
-  } else {
-    // No feedback — partial confidence from score alone
-    confidence += 0.1;
-  }
-
-  // ── Alignment signals (0.2 weight) ──
-  if (alignment) {
-    if (alignment.score >= 0.8) {
-      confidence += alignment.score * 0.2;
-      reasons.push(`alignment: ${Math.round(alignment.score * 100)}%`);
-    } else {
-      confidence -= 0.1;
-      reasons.push(`low alignment: ${Math.round(alignment.score * 100)}%`);
-    }
-  }
-
-  // ── Novelty bonus (0.2 weight) ──
-  const novelty = assessNovelty(componentTypes);
-  if (novelty > 0.5) {
-    confidence += novelty * 0.2;
-    reasons.push(`novelty: ${Math.round(novelty * 100)}%`);
-  }
-
-  // ── Decision ──
-  const shouldPromote = confidence >= 0.5;
-  const suggestedName = generatePatternName(intent);
-
-  return {
-    shouldPromote,
-    confidence: Math.round(confidence * 100) / 100,
-    reason: reasons.join(', '),
-    suggestedName,
-  };
-}
-
-/**
- * Assess how novel a component combination is compared to existing patterns.
- * Higher = more novel (not well-covered by existing patterns).
- *
- * @param {string[]} componentTypes
- * @returns {number} — 0 (duplicate) to 1 (completely novel)
- */
-function assessNovelty(componentTypes) {
-  const existing = getAllPatterns();
-  if (existing.length === 0) return 1;
-
-  const typeSet = new Set(componentTypes);
-  let bestOverlap = 0;
-
-  for (const pattern of existing) {
-    const patternTypes = new Set(pattern.components || []);
-    const intersection = [...typeSet].filter(t => patternTypes.has(t)).length;
-    const union = new Set([...typeSet, ...patternTypes]).size;
-    const jaccard = union > 0 ? intersection / union : 0;
-    bestOverlap = Math.max(bestOverlap, jaccard);
-  }
-
-  // Invert: high overlap = low novelty
-  return 1 - bestOverlap;
-}
-
-/**
- * Generate a suggested pattern name from an intent string.
- *
- * @param {string} intent
- * @returns {string}
- */
-function generatePatternName(intent) {
-  return (intent || 'unnamed')
-    .toLowerCase()
-    .replace(/\b(create|build|make|show|add|generate|a|an|the|with|and|for|of)\b/g, '')
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-|-$/g, '')
-    .slice(0, 40) || 'unnamed-pattern';
-}