@appinternalleads/ui 0.3.0 → 0.4.0

package/dist/esm/index.js

@@ -16,6 +16,6 @@ export * from './widgets';
    nothing is implemented. See docs/architecture/COMPONENT-FAMILIES.md. */
 export * from './components';
 export * from './sheets';
-/* The agent component contract: search, describe, render/1, validation, result/1. */
+/* The agent component contract for the renderer: AgentComponent, describe, render/1 validation, result/1. Search is in `@appinternalleads/ui/agent`. */
 export * from './agent';
 //# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC;AACzB,cAAc,MAAM,CAAC;AACrB,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AACnE,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B;0EAC0E;AAC1E,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,qFAAqF;AACrF,cAAc,SAAS,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC;AACzB,cAAc,MAAM,CAAC;AACrB,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AACnE,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B;0EAC0E;AAC1E,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,wJAAwJ;AACxJ,cAAc,SAAS,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appinternalleads/ui",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "React + React Native component library. Components are generated from JSON; see SPEC.md.",
   "workspaces": [
     "site"
@@ -140,6 +140,7 @@
     "spec",
     "!src/**/*.test.*",
     "!src/**/*.stories.*",
+    "!src/agent/search/wordvectors.json",
     "tools/ask/mcp.mjs",
     "tools/ask/serve.mjs",
     "tools/ask/stale.mjs",

package/src/agent/base.ts

@@ -0,0 +1,17 @@
+/**
+ * **The agent contract without search** — describe, `render/1` validation, `result/1`, the types.
+ * Small and React-free. Both entry points carry it: `@appinternalleads/ui/agent` (`./core`) adds
+ * `searchComponents`; the main entry adds `AgentComponent`. Search is not here on purpose — its
+ * word-vector table is 2.8 MB, and an app that renders components must not bundle it.
+ */
+export {
+  AGENT_COMPONENTS, agentAvailability, describeComponent, isAgentComponent, listAgentComponents,
+} from './catalog';
+export { validateRenderRequest } from './validate';
+export { RESULT_EVENTS, makeResult } from './result';
+export {
+  CAPABILITY_SCHEMA, RENDER_SCHEMA, RESULT_SCHEMA,
+  type AgentButtonAction, type AgentCapability, type CapabilityAction, type CapabilityCard, type CapabilityEvent, type CapabilityKind,
+  type CopySpec as AgentCopySpec, type DataOrigin, type FieldSpec as AgentFieldSpec, type IssueCode, type IssueLayer, type Owner as AgentOwner,
+  type RenderCheck, type RenderIssue, type RenderPreview, type RenderRequest, type RenderResult, type Section as AgentSection,
+} from './types';

package/src/agent/catalog.ts

@@ -98,35 +98,3 @@ export function agentAvailability(id: string): { component: string; agentEditabl
   }
   return { component: id, agentEditable: false, reason: 'No such component.' };
 }
-
-/* ── Search ────────────────────────────────────────────────────────────────────────────────── */
-
-const STOP = new Set('a an the of for to and or in on at by with my me i we our you your it is are be this that these those can could would should please make create show give get want need some any what how which who when from as into about'.split(' '));
-const stem = (w: string) => w.replace(/(ies)$/, 'y').replace(/(ing|ed|es|s)$/, '');
-const words = (s: string) => s.toLowerCase().replace(/[^\p{L}\p{N}\s'-]/gu, ' ').split(/[\s'-]+/).filter(w => w.length > 1 && !STOP.has(w)).map(stem);
-
-/**
- * **Intent → candidates.** A short list of cards, best first. Scored on the component's own
- * selection signals (a whole phrase in the request counts most), then its name and purpose, then
- * when to use it. Deterministic: the same words give the same order.
- */
-export function searchComponents(query: string, limit = 5): (CapabilityCard & { score: number })[] {
-  const q = ` ${query.toLowerCase().replace(/[^\p{L}\p{N}\s]/gu, ' ').replace(/\s+/g, ' ')} `;
-  const qw = new Set(words(query));
-  const scored = [...CAPABILITIES.values()].map((c, order) => {
-    let score = 0;
-    for (const s of c.signals) {
-      const phrase = ` ${s.toLowerCase().replace(/[^\p{L}\p{N}\s]/gu, ' ').replace(/\s+/g, ' ')} `;
-      if (q.includes(phrase)) score += 6 + 2 * (phrase.trim().split(' ').length - 1);
-      else score += words(s).filter(w => qw.has(w)).length * 2;
-    }
-    score += words(`${c.name} ${c.purpose}`).filter(w => qw.has(w)).length;
-    score += new Set(words(c.useWhen.join(' ')).filter(w => qw.has(w))).size * 0.5;
-    return { card: cardOf(c), score, order };
-  });
-  return scored
-    .filter(s => s.score > 0)
-    .sort((a, b) => b.score - a.score || a.order - b.order)
-    .slice(0, limit)
-    .map(s => ({ ...s.card, score: s.score }));
-}

package/src/agent/core.ts

@@ -1,16 +1,8 @@
 /**
- * **The agent component contract, without React** — `@appinternalleads/ui/agent`. Search, describe,
- * `render/1` validation and `result/1`: what a backend or an MCP server needs, and all of it runs in
- * plain Node. The renderer, `AgentComponent`, is in the main entry. `docs/AGENT-COMPONENT-CONTRACT.md`.
+ * **`@appinternalleads/ui/agent` — the agent contract, with search, without React.** Search,
+ * describe, `render/1` validation and `result/1`: what a backend or an MCP server needs, all of it in
+ * plain Node. `searchComponents` lives only here (and its word-vector table with it); the renderer,
+ * `AgentComponent`, is in the main entry. `docs/AGENT-COMPONENT-CONTRACT.md`.
  */
-export {
-  AGENT_COMPONENTS, agentAvailability, describeComponent, isAgentComponent, listAgentComponents, searchComponents,
-} from './catalog';
-export { validateRenderRequest } from './validate';
-export { RESULT_EVENTS, makeResult } from './result';
-export {
-  CAPABILITY_SCHEMA, RENDER_SCHEMA, RESULT_SCHEMA,
-  type AgentButtonAction, type AgentCapability, type CapabilityAction, type CapabilityCard, type CapabilityEvent, type CapabilityKind,
-  type CopySpec as AgentCopySpec, type DataOrigin, type FieldSpec as AgentFieldSpec, type IssueCode, type IssueLayer, type Owner as AgentOwner,
-  type RenderCheck, type RenderIssue, type RenderPreview, type RenderRequest, type RenderResult, type Section as AgentSection,
-} from './types';
+export * from './base';
+export { searchComponents } from './search';

package/src/agent/index.ts

@@ -1,9 +1,10 @@
 /**
- * **The agent component contract** — `docs/AGENT-COMPONENT-CONTRACT.md`.
+ * **The agent contract, as the main entry carries it** — for the app that renders: `AgentComponent`,
+ * `AGENT_RENDERABLE`, and the small React-free contract they use (describe, validate, results).
  *
- * search → describe → build a `render/1` → `validateRenderRequest` → `<AgentComponent>` → `result/1`.
- * Everything but `AgentComponent` is pure and serialisable, and is also its own entry point —
- * `@appinternalleads/ui/agent` (`./core`) — so a server or an MCP tool can use it without React.
+ * Not `searchComponents`: component search belongs to the agent, and its word-vector table must not
+ * reach an app's bundle. Import it from `@appinternalleads/ui/agent`. `tests/agent/boundary.test.ts`
+ * holds this line on the built package.
  */
-export * from './core';
+export * from './base';
 export { AgentComponent, AGENT_RENDERABLE, type AgentComponentProps } from './AgentComponent';

package/src/agent/search/document.ts

@@ -0,0 +1,46 @@
+import type { AgentCapability, FieldSpec } from '../types';
+import type { FieldType, SearchDocument } from './types';
+
+/**
+ * **A component's search document, derived from its capability.** It says what problem the
+ * component solves — purpose, when to use it, its selection signals, its case studies' scenarios,
+ * what a person can do with it, what it shows and what it reports — and, separately, what it is not
+ * for (`avoidWhen`). Nothing is written for search alone, so a new approved component is searchable
+ * the moment it has a capability. No source, no implementation, no runtime values.
+ */
+
+/** "…statement over time — use budget-tracker or a list." → "…statement over time": the pointer to another component is advice, not meaning. */
+function ownMeaning(text: string, ids: readonly string[]): string {
+  let t = text.replace(/\s[—–-]+\s*use\s.*$/i, '').replace(/:\s*use\s.*$/i, '');
+  for (const id of ids) t = t.split(id).join(' ');
+  return t.replace(/\s+/g, ' ').trim();
+}
+
+const describeData = (key: string, spec: FieldSpec): string => {
+  const words = key.replace(/([a-z])([A-Z])/g, '$1 $2').toLowerCase();
+  return `${words}: ${spec.description}`;
+};
+
+export function searchDocumentOf(c: AgentCapability, order: number, allIds: readonly string[]): SearchDocument {
+  const positive: { type: FieldType; text: string }[] = [];
+  const add = (type: FieldType, text: string | undefined) => { const t = text && ownMeaning(text, allIds); if (t) positive.push({ type, text: t }); };
+  add('name', c.name);
+  add('purpose', c.purpose);
+  c.signals.forEach(s => add('signal', s));
+  c.useWhen.forEach(s => add('useWhen', s));
+  c.presets.forEach(p => add('scenario', `${p.title}. ${p.scenario}`));
+  c.actions.forEach(a => add('action', a.description));
+  c.states.forEach(s => add('state', s.description));
+  c.events.forEach(e => add('event', e.description));
+  for (const [k, spec] of Object.entries(c.data)) add('data', describeData(k, spec));
+  const negative = c.avoidWhen.map(t => ownMeaning(t, allIds)).filter(Boolean).map(text => ({ text }));
+  return { component: c.component, order, positive, negative };
+}
+
+/** FNV-1a over the documents: the catalogue's search version. Any change to what search reads changes it. */
+export function versionOf(value: unknown): string {
+  const s = JSON.stringify(value);
+  let h = 0x811c9dc5;
+  for (let i = 0; i < s.length; i++) { h ^= s.charCodeAt(i); h = Math.imul(h, 0x01000193); }
+  return (h >>> 0).toString(16).padStart(8, '0');
+}

package/src/agent/search/embedding.ts

@@ -0,0 +1,95 @@
+import type { EmbeddingProvider } from './types';
+
+/**
+ * **Embedding providers.** The search asks a provider for vectors and nothing else, so the one
+ * below — pretrained word vectors shipped in the package, no network — can be replaced by a hosted
+ * model without touching retrieval or ranking.
+ */
+
+/** `bits`: 8 — int8 per value; 4 — two values per byte, each stored as value + 8 (−7…7). */
+export type WordVectorTable = { dims: number; count: number; words: string; data: string; bits?: 4 | 8 };
+
+const bytesOf = (b64: string): Uint8Array => {
+  if (typeof Buffer !== 'undefined') { const b = Buffer.from(b64, 'base64'); return new Uint8Array(b.buffer, b.byteOffset, b.length); }
+  const bin = atob(b64); const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+};
+/* One signed value per entry, whatever the storage. Only directions matter (vectors are averaged and normalised), so no rescaling. */
+function decode(t: WordVectorTable): Int8Array {
+  const bytes = bytesOf(t.data);
+  if (t.bits !== 4) return new Int8Array(bytes.buffer, bytes.byteOffset, bytes.length);
+  const out = new Int8Array(t.count * t.dims);
+  for (let i = 0; i < out.length; i++) out[i] = ((bytes[i >> 1]! >> ((i & 1) * 4)) & 15) - 8;
+  return out;
+}
+
+const unit = (v: Float32Array): Float32Array => {
+  let n = 0; for (const x of v) n += x * x;
+  n = Math.sqrt(n);
+  if (n > 0) for (let i = 0; i < v.length; i++) v[i]! /= n;
+  return v;
+};
+
+/**
+ * **Word vectors, averaged — offline and deterministic.** A text's vector is the average of its
+ * words' vectors, each weighted by how rare the word is (Arora et al.'s smooth inverse frequency,
+ * with the table's frequency order standing in for counts), so "the" counts for almost nothing and
+ * "receipt" for a lot. A word the table lacks is tried without a plural or tense ending; failing
+ * that it is skipped (lexical matching still sees it).
+ */
+export function createWordVectorProvider(table: WordVectorTable, opts: { smoothing?: number } = {}): EmbeddingProvider {
+  let index: Map<string, number> | null = null;
+  let data: Int8Array | null = null;
+  const a = opts.smoothing ?? 1e-3;
+  /* Zipf: a word's share of text ∝ 1 / rank. H is the normaliser for the table's size. */
+  const H = Math.log(table.count) + 0.5772;
+  const load = () => {
+    if (index) return;
+    index = new Map(table.words.split(' ').map((w, i) => [w, i]));
+    data = decode(table);
+  };
+  const lookup = (w: string): number | undefined => {
+    const m = index!;
+    return m.get(w) ?? m.get(w.replace(/'s$/, '')) ?? m.get(w.replace(/ies$/, 'y')) ?? m.get(w.replace(/s$/, ''))
+      ?? m.get(w.replace(/ing$/, '')) ?? m.get(w.replace(/ing$/, 'e')) ?? m.get(w.replace(/ed$/, '')) ?? m.get(w.replace(/d$/, ''));
+  };
+  return {
+    id: `word-vectors:${table.dims}x${table.count}x${table.bits ?? 8}bit:sif-${a}`,
+    embed(texts) {
+      load();
+      return texts.map(text => {
+        const v = new Float32Array(table.dims);
+        for (const raw of text.toLowerCase().split(/[^\p{L}']+/u)) {
+          if (!raw) continue;
+          const r = lookup(raw);
+          if (r === undefined) continue;
+          const p = 1 / ((r + 1) * H);
+          const w = a / (a + p);
+          const off = r * table.dims;
+          for (let d = 0; d < table.dims; d++) v[d]! += w * data![off + d]!;
+        }
+        return unit(v);
+      });
+    },
+  };
+}
+
+/**
+ * **For tests: deterministic vectors, no model.** Each word hashes to a few dimensions, so equal words
+ * give equal vectors and different words mostly do not. It proves the machinery — indexing, ranking,
+ * filtering, fallback — not semantic quality.
+ */
+export function createFakeEmbeddingProvider(dims = 64): EmbeddingProvider {
+  const hash = (s: string, seed: number) => { let h = 0x811c9dc5 ^ seed; for (let i = 0; i < s.length; i++) { h ^= s.charCodeAt(i); h = Math.imul(h, 0x01000193); } return h >>> 0; };
+  return {
+    id: `fake:${dims}`,
+    embed(texts) {
+      return texts.map(t => {
+        const v = new Float32Array(dims);
+        for (const w of t.toLowerCase().split(/[^\p{L}\p{N}]+/u)) if (w) for (let s = 0; s < 3; s++) v[hash(w, s) % dims]! += (hash(w, s + 7) & 1) ? 1 : -1;
+        return unit(v);
+      });
+    },
+  };
+}

package/src/agent/search/index.ts

@@ -0,0 +1,20 @@
+import { createWordVectorProvider, type WordVectorTable } from './embedding';
+import { createComponentSearch, type SearchCard } from './search';
+import type { SearchOptions } from './types';
+import { DEFAULT_WEIGHTS } from './weights';
+import table from './wordvectors.json';
+
+/**
+ * **`searchComponents` — the package's one search.** The MCP tool and the site's API call this; the
+ * hybrid engine behind it (`search.ts`) uses the offline word-vector provider shipped with the
+ * package, so it needs no network and gives the same answer every time.
+ */
+const engine = createComponentSearch({ provider: createWordVectorProvider(table as WordVectorTable), weights: DEFAULT_WEIGHTS });
+
+/** Intent → candidate cards, best first. `options.available` is the host's policy: only those components may be offered. */
+export function searchComponents(query: string, limit = 5, options?: SearchOptions): SearchCard[] {
+  return engine.search(query, limit, options);
+}
+
+/** Development only: why each component scored what it did. Not part of the agent's result. */
+export const explainSearch = (query: string, options?: SearchOptions) => engine.explain(query, options);

package/src/agent/search/lexical.ts

@@ -0,0 +1,25 @@
+import type { AgentCapability } from '../types';
+
+/**
+ * **Lexical scoring — the search as it shipped in 0.3.0, unchanged.** Whole selection-signal phrases
+ * in the request count most, then shared words with the signals, the name and purpose, then when to
+ * use it. It is one input to the hybrid ranking, and on its own it is the fallback whenever semantic
+ * retrieval is unavailable.
+ */
+const STOP = new Set('a an the of for to and or in on at by with my me i we our you your it is are be this that these those can could would should please make create show give get want need some any what how which who when from as into about'.split(' '));
+const stem = (w: string) => w.replace(/(ies)$/, 'y').replace(/(ing|ed|es|s)$/, '');
+const words = (s: string) => s.toLowerCase().replace(/[^\p{L}\p{N}\s'-]/gu, ' ').split(/[\s'-]+/).filter(w => w.length > 1 && !STOP.has(w)).map(stem);
+
+export function lexicalScore(c: AgentCapability, query: string): number {
+  const q = ` ${query.toLowerCase().replace(/[^\p{L}\p{N}\s]/gu, ' ').replace(/\s+/g, ' ')} `;
+  const qw = new Set(words(query));
+  let score = 0;
+  for (const s of c.signals) {
+    const phrase = ` ${s.toLowerCase().replace(/[^\p{L}\p{N}\s]/gu, ' ').replace(/\s+/g, ' ')} `;
+    if (q.includes(phrase)) score += 6 + 2 * (phrase.trim().split(' ').length - 1);
+    else score += words(s).filter(w => qw.has(w)).length * 2;
+  }
+  score += words(`${c.name} ${c.purpose}`).filter(w => qw.has(w)).length;
+  score += new Set(words(c.useWhen.join(' ')).filter(w => qw.has(w))).size * 0.5;
+  return score;
+}

package/src/agent/search/normalize.ts

@@ -0,0 +1,17 @@
+/**
+ * **Query normalisation** — whitespace, case, obvious punctuation and repeated words. Nothing that
+ * changes meaning: no synonyms, no spelling rewrites. The original stays available for lexical
+ * phrase matching and for debugging.
+ */
+export type NormalizedQuery = { original: string; text: string; tokens: string[]; empty: boolean };
+
+export function normalizeQuery(query: unknown): NormalizedQuery {
+  const original = typeof query === 'string' ? query : '';
+  const text = original.toLowerCase().normalize('NFKC').replace(/[^\p{L}\p{N}\s'-]/gu, ' ').replace(/\s+/g, ' ').trim();
+  const tokens: string[] = [];
+  for (const t of text.split(/[\s-]+/)) {
+    const w = t.replace(/^'+|'+$/g, '');
+    if (w && tokens[tokens.length - 1] !== w) tokens.push(w);
+  }
+  return { original, text: tokens.join(' '), tokens, empty: tokens.length === 0 };
+}

package/src/agent/search/search.ts

@@ -0,0 +1,148 @@
+import { AGENT_COMPONENTS, describeComponent, isAgentComponent } from '../catalog';
+import type { AgentCapability, CapabilityCard } from '../types';
+import { searchDocumentOf } from './document';
+import { SearchIndex, cosine, indexVersion, type Centring, type IndexedDocument } from './searchIndex';
+import { lexicalScore } from './lexical';
+import { normalizeQuery, type NormalizedQuery } from './normalize';
+import type { EmbeddingProvider, ScoreBreakdown, SearchDocument, SearchOptions, SearchWeights } from './types';
+
+/**
+ * **Component search: intent → candidates.**
+ *
+ *   normalizeQuery → retrieveCandidates (semantic + lexical) → applyEligibility → rankCandidates → cards
+ *
+ * Semantic similarity comes from an `EmbeddingProvider` over each component's search document
+ * (`document.ts`, derived from its capability); lexical similarity is 0.3.0's scorer. If semantic
+ * retrieval is unavailable — no provider, an index that fails to build, a query with no known
+ * words — the ranking is exactly the lexical one. Eligibility (approved, and allowed by the host)
+ * is applied after retrieval and is authoritative: relevance never makes a component usable.
+ * Ties break on catalogue order, so the same query and catalogue give the same list.
+ */
+
+export type SearchCard = CapabilityCard & { score: number };
+
+export type ComponentSearch = {
+  search(query: string, limit?: number, options?: SearchOptions): SearchCard[];
+  /** Development: every component's scores, best first — never part of the agent's result. */
+  explain(query: string, options?: SearchOptions): ScoreBreakdown[] & { mode: 'hybrid' | 'lexical'; version: string };
+  /** The index in use (null when searching lexically). */
+  index(): SearchIndex | null;
+};
+
+const round = (x: number) => Math.round(x * 1000) / 1000;
+const cardOf = (c: AgentCapability): CapabilityCard => ({ component: c.component, name: c.name, kind: c.kind, purpose: c.purpose, signals: c.signals });
+
+/** The approved catalogue, in order, and its search documents — derived once per module. */
+let catalogCache: { caps: AgentCapability[]; docs: SearchDocument[] } | null = null;
+export function searchCatalog(): { caps: AgentCapability[]; docs: SearchDocument[] } {
+  if (!catalogCache) {
+    const caps = AGENT_COMPONENTS.map(id => describeComponent(id)!);
+    catalogCache = { caps, docs: caps.map((c, i) => searchDocumentOf(c, i, AGENT_COMPONENTS)) };
+  }
+  return catalogCache;
+}
+
+export function createComponentSearch(opts: {
+  provider?: EmbeddingProvider | null;
+  weights: SearchWeights;
+  /** Where the documents come from — the approved catalogue by default. */
+  catalog?: () => { caps: AgentCapability[]; docs: SearchDocument[] };
+}): ComponentSearch {
+  const catalog = opts.catalog ?? searchCatalog;
+  const w = opts.weights;
+  let built: SearchIndex | null = null;
+  let failed: string | null = null;
+
+  /* The index for the catalogue as it is now — rebuilt whenever its version (documents + provider) changes. */
+  const indexFor = (docs: readonly SearchDocument[]): SearchIndex | null => {
+    const provider = opts.provider;
+    if (!provider) return null;
+    const version = indexVersion(docs, provider);
+    if (built?.version === version) return built;
+    if (failed === version) return null;
+    try {
+      built = new SearchIndex(provider, version).build(docs);
+      return built;
+    } catch {
+      failed = version;
+      built = null;
+      return null;
+    }
+  };
+
+  const queryVector = (q: NormalizedQuery, index: SearchIndex): Float32Array | null => {
+    try {
+      const v = index.provider.embed([q.text])[0];
+      if (!v || v.length !== index.mean?.length || !v.some(x => x !== 0) || v.some(x => !Number.isFinite(x))) return null;
+      return v;
+    } catch { return null; }
+  };
+
+  function retrieveCandidates(q: NormalizedQuery) {
+    const { caps, docs } = catalog();
+    const index = q.empty ? null : indexFor(docs);
+    const qv = index ? queryVector(q, index) : null;
+    const centring = { mean: w.centre !== 'none' ? index?.mean ?? null : null, principal: w.centre === 'pc' ? index?.principal ?? null : null };
+    return {
+      mode: (qv ? 'hybrid' : 'lexical') as 'hybrid' | 'lexical',
+      version: index?.version ?? '',
+      candidates: caps.map((c, order) => {
+        const lexical = q.empty ? 0 : lexicalScore(c, q.original);
+        if (!qv || !index) return { cap: c, order, lexical, semantic: null as number | null, negative: null as number | null };
+        const e = index.entries.get(c.component);
+        if (!e) return { cap: c, order, lexical, semantic: null, negative: null };
+        const { pos, posMax } = fieldScore(qv, e, centring);
+        const neg = e.negative.length ? Math.max(...e.negative.map(n => cosine(qv, n, centring))) : 0;
+        return { cap: c, order, lexical, semantic: pos - w.negative * Math.max(0, neg - posMax), negative: neg };
+      }),
+    };
+  }
+
+  /* How close a query vector is to a component: the mean of its `topK` closest fields (weighted by kind), and the closest one. */
+  function fieldScore(qv: Float32Array, e: IndexedDocument, centring: Centring) {
+    const sims = e.positive.filter(p => w.fields[p.type] > 0).map(p => { const raw = cosine(qv, p.vector, centring); return { raw, weighted: w.fields[p.type] * raw }; });
+    const top = sims.map(x => x.weighted).sort((a, b) => b - a).slice(0, w.topK);
+    return { pos: top.length ? top.reduce((a, b) => a + b, 0) / top.length : 0, posMax: sims.length ? Math.max(...sims.map(x => x.raw)) : 0 };
+  }
+
+  const applyEligibility = <T extends { cap: AgentCapability }>(list: T[], options: SearchOptions = {}) => list.map(x => ({
+    ...x,
+    availability: isAgentComponent(x.cap.component) && (!options.available || options.available.includes(x.cap.component)) ? 1 : 0,
+    metadata: !options.kinds || options.kinds.includes(x.cap.kind) ? 1 : 0,
+  }));
+
+  function rankCandidates(query: string, options?: SearchOptions) {
+    const q = normalizeQuery(query);
+    const r = retrieveCandidates(q);
+    const scored = applyEligibility(r.candidates, options).map(x => ({
+      ...x,
+      final: r.mode === 'lexical' || x.semantic === null
+        ? x.lexical
+        : w.semantic * x.semantic + w.lexical * (x.lexical / (x.lexical + w.lexicalHalf)),
+    }));
+    scored.sort((a, b) => b.final - a.final || a.order - b.order);
+    return { ...r, scored };
+  }
+
+  return {
+    search(query, limit = 5, options) {
+      const r = rankCandidates(query, options);
+      const eligible = r.scored.filter(x => x.availability && x.metadata);
+      const kept = r.mode === 'lexical'
+        ? eligible.filter(x => x.final > 0)
+        : (() => { const best = eligible[0]?.final ?? 0; return eligible.filter(x => x.final >= w.minScore && (best <= 0 || x.final >= best * w.relative)); })();
+      return kept.slice(0, Math.max(0, limit)).map(x => ({ ...cardOf(x.cap), score: round(x.final) }));
+    },
+    explain(query, options) {
+      const r = rankCandidates(query, options);
+      const out = r.scored.map(x => ({
+        component: x.cap.component, semantic: x.semantic === null ? null : round(x.semantic), negative: x.negative === null ? null : round(x.negative),
+        lexical: round(x.lexical), metadata: x.metadata, availability: x.availability, final: round(x.final),
+      })) as ScoreBreakdown[] & { mode: 'hybrid' | 'lexical'; version: string };
+      out.mode = r.mode;
+      out.version = r.version;
+      return out;
+    },
+    index: () => indexFor(catalog().docs),
+  };
+}

package/src/agent/search/searchIndex.ts

@@ -0,0 +1,107 @@
+import { versionOf } from './document';
+import type { EmbeddingProvider, FieldType, SearchDocument } from './types';
+
+/**
+ * **The search index — derived, rebuildable, never the source of truth.** Each component's document
+ * fields as vectors, plus the catalogue mean (for centring). Its `version` is the documents' hash
+ * plus the provider's id: if the catalogue or the model changes, the version does, and a cached
+ * index for the old one is never served (`indexFor`).
+ */
+export type IndexedDocument = {
+  component: string;
+  order: number;
+  positive: { type: FieldType; vector: Float32Array }[];
+  negative: Float32Array[];
+};
+
+export class SearchIndex {
+  readonly entries = new Map<string, IndexedDocument>();
+  mean: Float32Array | null = null;
+  /** The first principal component of the (centred) document vectors — the direction every text shares most (SIF's common-component removal). */
+  principal: Float32Array | null = null;
+  constructor(readonly provider: EmbeddingProvider, public version: string) {}
+
+  /** Throw away everything and index these documents. */
+  build(docs: readonly SearchDocument[]): this {
+    this.entries.clear();
+    for (const d of docs) this.put(d);
+    this.version = indexVersion(docs, this.provider);
+    return this.recentre();
+  }
+
+
+  /** Add or replace one component. */
+  upsert(doc: SearchDocument, allDocs?: readonly SearchDocument[]): this {
+    this.put(doc);
+    if (allDocs) this.version = indexVersion(allDocs, this.provider);
+    return this.recentre();
+  }
+
+  remove(component: string, allDocs?: readonly SearchDocument[]): this {
+    this.entries.delete(component);
+    if (allDocs) this.version = indexVersion(allDocs, this.provider);
+    return this.recentre();
+  }
+
+  private put(d: SearchDocument) {
+    const vectors = this.provider.embed([...d.positive.map(p => p.text), ...d.negative.map(n => n.text)]);
+    if (vectors.length !== d.positive.length + d.negative.length) throw new Error(`${this.provider.id} returned ${vectors.length} vectors for ${d.component}`);
+    this.entries.set(d.component, {
+      component: d.component,
+      order: d.order,
+      positive: d.positive.map((p, i) => ({ type: p.type, vector: vectors[i]! })),
+      negative: vectors.slice(d.positive.length),
+    });
+  }
+
+  /** The mean of every positive field vector: what all documents share, subtracted before comparing when centring. */
+  private recentre(): this {
+    let sum: Float32Array | null = null; let n = 0;
+    for (const e of this.entries.values()) for (const p of e.positive) {
+      sum ??= new Float32Array(p.vector.length);
+      for (let i = 0; i < sum.length; i++) sum[i]! += p.vector[i]!;
+      n++;
+    }
+    if (sum && n) for (let i = 0; i < sum.length; i++) sum[i]! /= n;
+    this.mean = sum;
+    this.principal = sum ? firstComponent([...this.entries.values()].flatMap(e => e.positive.map(p => p.vector)), sum) : null;
+    return this;
+  }
+}
+
+export const indexVersion = (docs: readonly SearchDocument[], provider: EmbeddingProvider) => `${versionOf(docs)}:${provider.id}`;
+
+/** Power iteration — deterministic start, fixed iterations. */
+function firstComponent(vectors: Float32Array[], mean: Float32Array): Float32Array {
+  const d = mean.length;
+  let u = new Float32Array(d).fill(1 / Math.sqrt(d));
+  for (let it = 0; it < 30; it++) {
+    const next = new Float32Array(d);
+    for (const v of vectors) {
+      let dot = 0; for (let i = 0; i < d; i++) dot += (v[i]! - mean[i]!) * u[i]!;
+      for (let i = 0; i < d; i++) next[i]! += dot * (v[i]! - mean[i]!);
+    }
+    let n = 0; for (const x of next) n += x * x; n = Math.sqrt(n) || 1;
+    for (let i = 0; i < d; i++) next[i]! /= n;
+    u = next;
+  }
+  return u;
+}
+
+/** What is compared: the vector less the shared mean and, if given, less its projection on the shared direction. */
+export type Centring = { mean: Float32Array | null; principal: Float32Array | null };
+function centred(v: Float32Array, c: Centring): Float32Array {
+  if (!c.mean && !c.principal) return v;
+  const out = new Float32Array(v.length);
+  for (let i = 0; i < v.length; i++) out[i] = v[i]! - (c.mean ? c.mean[i]! : 0);
+  if (c.principal) { let dot = 0; for (let i = 0; i < v.length; i++) dot += out[i]! * c.principal[i]!; for (let i = 0; i < v.length; i++) out[i]! -= dot * c.principal[i]!; }
+  return out;
+}
+
+/** Cosine similarity after centring. */
+export function cosine(a: Float32Array, b: Float32Array, c: Centring = { mean: null, principal: null }): number {
+  const x = centred(a, c), y = centred(b, c);
+  let dot = 0, na = 0, nb = 0;
+  for (let i = 0; i < x.length; i++) { dot += x[i]! * y[i]!; na += x[i]! * x[i]!; nb += y[i]! * y[i]!; }
+  return na && nb ? dot / Math.sqrt(na * nb) : 0;
+}