@appinternalleads/ui 0.2.0 → 0.4.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;
+}

package/src/agent/search/types.ts

@@ -0,0 +1,68 @@
+/**
+ * **Component search — its internal types.** None of this is part of the agent contract: the agent
+ * calls `searchComponents(query)` and gets cards. How candidates are found — lexical, semantic,
+ * in memory or not — can change without it knowing.
+ */
+
+/** Turns text into vectors. Swap it for a hosted model without touching the search. */
+export interface EmbeddingProvider {
+  /** Changes whenever the vectors would: part of the index version. */
+  readonly id: string;
+  embed(texts: readonly string[]): Float32Array[];
+}
+
+/** The same, for a provider that has to wait (a hosted embedding API). */
+export interface AsyncEmbeddingProvider {
+  readonly id: string;
+  embed(texts: readonly string[]): Promise<Float32Array[]>;
+}
+
+/** What each piece of a component's search document says about it. */
+export type FieldType = 'name' | 'purpose' | 'signal' | 'useWhen' | 'scenario' | 'action' | 'state' | 'event' | 'data';
+
+/** A component, as search sees it: what problem it solves (positive) and what it is not for (negative). Built from its capability — nothing is written for search alone. */
+export type SearchDocument = {
+  component: string;
+  /** Catalogue order: the stable tie-break. */
+  order: number;
+  positive: { type: FieldType; text: string }[];
+  negative: { text: string }[];
+};
+
+export type SearchWeights = {
+  /** How much each kind of field counts when it is the closest to the query (0 leaves it out). */
+  fields: Record<FieldType, number>;
+  /** The semantic score is the mean of the best `topK` field similarities. */
+  topK: number;
+  /** How hard a query nearer to what a component is *not* for pushes it down. */
+  negative: number;
+  /** Before comparing: subtract the catalogue's mean vector (`mean`), and also its first principal component (`pc`) — what every document shares. */
+  centre: 'none' | 'mean' | 'pc';
+  semantic: number;
+  lexical: number;
+  /** The lexical score saturates: `s / (s + lexicalHalf)`. */
+  lexicalHalf: number;
+  /** Below this final score a component is not a candidate. */
+  minScore: number;
+  /** …nor if it scores below this share of the best one. */
+  relative: number;
+};
+
+export type ScoreBreakdown = {
+  component: string;
+  semantic: number | null;
+  negative: number | null;
+  lexical: number;
+  /** 1 when the component passes the request's filters (kinds), else 0. */
+  metadata: number;
+  /** 1 when the host may use it, else 0. */
+  availability: number;
+  final: number;
+};
+
+export type SearchOptions = {
+  /** Host policy: only these components may be offered. Absent → every approved component. */
+  available?: readonly string[];
+  /** Only components of these kinds. */
+  kinds?: readonly string[];
+};

package/src/agent/search/weights.ts

@@ -0,0 +1,32 @@
+import type { SearchWeights } from './types';
+
+/**
+ * **The ranking weights — measured, not guessed.** Chosen on the dev half of the evaluation set
+ * (`tests/agent/search-eval.ts`) with `tools/search/tune.ts` and a threshold sweep; the test half is
+ * reported, never tuned on. The record of why is in docs/DECISIONS.md §19.
+ *
+ * - Every document field counts; the ones about what a person does with the component (actions,
+ *   states, events, data) a little less than what it is for.
+ * - The semantic score is the mean of the three closest fields, after removing the catalogue mean.
+ * - A query closer to a component's `avoidWhen` than to anything it is for is pushed down by half
+ *   the difference.
+ * - Lexical matching adds up to 0.3 — a confident phrase or name match keeps its place; a shared
+ *   word alone cannot outvote meaning.
+ * - A candidate needs 0.3, and 60% of the best — so an ambiguous request keeps its alternatives and
+ *   a clear one does not trail five weak ones. (Off-topic and on-topic scores overlap; 0.3 rejects
+ *   about half the off-topic requests without losing on-topic ones.)
+ *
+ * Measured and not adopted: word-level alignment, reciprocal rank fusion, hubness (CSLS) correction
+ * and principal-component removal — none beat this on the development data.
+ */
+export const DEFAULT_WEIGHTS: SearchWeights = {
+  fields: { name: 1, purpose: 1, signal: 1, useWhen: 1, scenario: 1, action: 0.8, state: 0.8, event: 0.8, data: 0.8 },
+  topK: 3,
+  negative: 0.5,
+  centre: 'mean',
+  semantic: 1,
+  lexical: 0.3,
+  lexicalHalf: 6,
+  minScore: 0.3,
+  relative: 0.6,
+};