@capsiynau/intelligence 0.3.0 → 0.4.0

package/src/speakers/index.js

@@ -0,0 +1,204 @@
+/**
+ * @capsiynau/intelligence/speakers
+ *
+ * Base-level speaker-handling primitives, shared by every app that consumes
+ * diarisation (Capsiynau engine, Nodiadau, future apps). Pure + dependency-
+ * free; runs in Node or the browser.
+ *
+ * This first export is the DIARISATION QUALITY GATE. Acoustic diarisation
+ * (AssemblyAI) is language-agnostic but not always reliable - especially on
+ * Welsh audio (unofficial support), short memos, or heavy cross-talk. The
+ * gate decides whether a diarisation result is trustworthy enough to SHOW
+ * speaker labels, or whether the consumer should suppress them. Showing
+ * "Speaker 1" on everything when four people spoke is worse than showing
+ * nothing - so when in doubt, suppress.
+ *
+ * Thresholds are documented constants, deliberately conservative. Tune them
+ * once real Welsh-meeting telemetry exists (schedule phase C2). The function
+ * never throws and never mutates its inputs.
+ */
+
+export const DIARISATION_GATE_DEFAULTS = {
+  // A multi-minute recording that diarisation collapses to ONE speaker is the
+  // classic false-negative (it failed to separate voices). Below this span a
+  // genuine solo memo is plausible, so a sole speaker is allowed; above it a
+  // sole speaker is suspicious and we suppress.
+  soleSpeakerSuspectAboveMs: 90_000, // 90 seconds
+  // Fraction of the transcript span that labelled utterances must cover.
+  // Sparse coverage means the speaker timeline barely overlaps the words, so
+  // per-segment assignment would be mostly guesswork.
+  minCoverage: 0.6,
+  // This many distinct speakers (with adequate coverage) is trusted as a
+  // clear multi-party separation.
+  trustAtSpeakers: 2,
+}
+
+/**
+ * Total milliseconds the utterances cover WITHIN the transcript span
+ * `[spanStart, spanEnd]`, counted as a UNION so overlapping utterances don't
+ * double-count. Each utterance is first clipped to the span (speech entirely
+ * outside the transcript window contributes 0), then the clipped intervals are
+ * merged and their lengths summed. This is what makes coverage measure the
+ * fraction of the transcript actually overlapped by the speaker timeline,
+ * rather than total diarisation duration (which can sit outside the window
+ * when diarisation ran over the full audio but the transcript is a clip).
+ *
+ * @param {Array<{start?:number,end?:number}>} utts
+ * @param {number} spanStart inclusive lower bound (ms)
+ * @param {number} spanEnd   inclusive upper bound (ms)
+ * @returns {number} unioned, clipped duration in ms (>= 0)
+ */
+export function clampedUnionMs(utts, spanStart, spanEnd) {
+  const clipped = []
+  for (const u of utts) {
+    const start = Math.max(u.start ?? 0, spanStart)
+    const end = Math.min(u.end ?? 0, spanEnd)
+    if (end > start) clipped.push([start, end])
+  }
+  if (clipped.length === 0) return 0
+
+  clipped.sort((a, b) => a[0] - b[0])
+  let total = 0
+  let [curStart, curEnd] = clipped[0]
+  for (let i = 1; i < clipped.length; i++) {
+    const [s, e] = clipped[i]
+    if (s <= curEnd) {
+      // Overlapping or contiguous - extend the current merged interval.
+      if (e > curEnd) curEnd = e
+    } else {
+      total += curEnd - curStart
+      curStart = s
+      curEnd = e
+    }
+  }
+  total += curEnd - curStart
+  return total
+}
+
+/**
+ * Judge whether a diarisation timeline is reliable enough to label segments.
+ *
+ * @param {Array<{start:number,end:number,speaker:string}>} utterances
+ *        diarisation timeline in milliseconds (AssemblyAI `utterances` shape).
+ * @param {Array<{start_ms:number,end_ms:number}>} segments
+ *        transcript segments in milliseconds (used to measure coverage).
+ * @param {Partial<typeof DIARISATION_GATE_DEFAULTS>} [opts] threshold overrides.
+ * @returns {{ reliable: boolean, speakerCount: number, coverage: number,
+ *             durationMs: number, reason: string }}
+ */
+export function assessDiarisation(utterances, segments, opts = {}) {
+  const t = { ...DIARISATION_GATE_DEFAULTS, ...opts }
+  const utts = Array.isArray(utterances)
+    ? utterances.filter((u) => u && typeof u.speaker === 'string' && u.speaker)
+    : []
+
+  if (utts.length === 0) {
+    return { reliable: false, speakerCount: 0, coverage: 0, durationMs: 0, reason: 'no_utterances' }
+  }
+
+  const speakerCount = new Set(utts.map((u) => u.speaker)).size
+
+  // Total span: prefer the transcript's extent; fall back to the utterances'.
+  const segs = Array.isArray(segments) ? segments.filter(Boolean) : []
+  const starts = segs.length ? segs.map((s) => s.start_ms ?? 0) : utts.map((u) => u.start)
+  const ends = segs.length ? segs.map((s) => s.end_ms ?? 0) : utts.map((u) => u.end)
+  const spanStart = Math.min(...starts)
+  const spanEnd = Math.max(...ends)
+  const durationMs = Math.max(0, spanEnd - spanStart)
+  const totalSpan = Math.max(1, durationMs)
+
+  // Coverage = fraction of the transcript span actually overlapped by the
+  // speaker timeline. Clip each utterance to [spanStart, spanEnd] and union the
+  // clipped intervals: speech outside the transcript window (diarisation ran
+  // over full audio, transcript is a clip) must NOT inflate coverage, and
+  // overlapping utterances must NOT double-count past the real covered fraction.
+  const labelledMs = clampedUnionMs(utts, spanStart, spanEnd)
+  const coverage = Math.min(1, labelledMs / totalSpan)
+
+  if (coverage < t.minCoverage) {
+    return { reliable: false, speakerCount, coverage, durationMs, reason: 'low_coverage' }
+  }
+
+  // Single speaker: trust only on short audio (a real solo memo); on long
+  // audio a lone speaker almost always means diarisation failed to separate.
+  if (speakerCount < t.trustAtSpeakers) {
+    if (durationMs > t.soleSpeakerSuspectAboveMs) {
+      return { reliable: false, speakerCount, coverage, durationMs, reason: 'sole_speaker_long_audio' }
+    }
+    return { reliable: true, speakerCount, coverage, durationMs, reason: 'sole_speaker_short_audio' }
+  }
+
+  return { reliable: true, speakerCount, coverage, durationMs, reason: 'ok' }
+}
+
+export const SPEAKER_MAP_DEFAULTS = {
+  // The winning name must cover at least this fraction of the acoustic
+  // speaker's total speaking time. Below it the overlap is too weak to trust.
+  minOverlapFraction: 0.5,
+  // The winning name's overlap must beat the runner-up by at least this ratio,
+  // else the acoustic speaker straddles two names too ambiguously to name.
+  dominanceRatio: 1.5,
+}
+
+/**
+ * Map acoustic diarisation speakers ("Speaker 1/2/3") to REAL names from a
+ * labelled reference timeline (platform transcript / roster), by greatest
+ * total time-overlap. Upgrades anonymous acoustic labels to real names when a
+ * labelled source exists (speaker-ID ladder rung A over C). Pure.
+ *
+ * Only confident matches are returned: the winning name must cover
+ * >= minOverlapFraction of the acoustic speaker's speaking time AND beat the
+ * runner-up by >= dominanceRatio. Ambiguous / unmatched acoustic speakers are
+ * listed in `unmapped`, so the caller keeps their anonymous label.
+ *
+ * Note: two acoustic speakers can map to the same real name (acoustic over-
+ * split one person). That is acceptable - downstream can merge. 1:1 dedup is a
+ * future refinement.
+ *
+ * @param {Array<{start:number,end:number,speaker:string}>} acoustic  utterances (ms)
+ * @param {Array<{start:number,end:number,name:string}>} labelled  real-name turns (ms)
+ * @param {Partial<typeof SPEAKER_MAP_DEFAULTS>} [opts]
+ * @returns {{ map: Record<string,string>, unmapped: string[] }}
+ */
+export function mapSpeakersToNames(acoustic, labelled, opts = {}) {
+  const t = { ...SPEAKER_MAP_DEFAULTS, ...opts }
+  const utts = Array.isArray(acoustic) ? acoustic.filter((u) => u && u.speaker) : []
+  const refs = Array.isArray(labelled) ? labelled.filter((r) => r && r.name) : []
+
+  const speakers = [...new Set(utts.map((u) => u.speaker))]
+  const map = {}
+  const unmapped = []
+  if (speakers.length === 0) return { map, unmapped }
+  if (refs.length === 0) return { map, unmapped: speakers }
+
+  const overlapMs = (a, b) => Math.max(0, Math.min(a.end, b.end) - Math.max(a.start, b.start))
+
+  for (const spk of speakers) {
+    const spkUtts = utts.filter((u) => u.speaker === spk)
+    const spkTotal = spkUtts.reduce((s, u) => s + Math.max(0, u.end - u.start), 0)
+
+    const byName = {}
+    for (const u of spkUtts) {
+      for (const r of refs) {
+        const ov = overlapMs(u, r)
+        if (ov > 0) byName[r.name] = (byName[r.name] || 0) + ov
+      }
+    }
+    const ranked = Object.entries(byName).sort((a, b) => b[1] - a[1])
+    if (ranked.length === 0) {
+      unmapped.push(spk)
+      continue
+    }
+    const [bestName, bestOv] = ranked[0]
+    const secondOv = ranked[1] ? ranked[1][1] : 0
+    const fraction = spkTotal > 0 ? bestOv / spkTotal : 0
+    const dominant = secondOv === 0 || bestOv >= secondOv * t.dominanceRatio
+
+    if (fraction >= t.minOverlapFraction && dominant) {
+      map[spk] = bestName
+    } else {
+      unmapped.push(spk)
+    }
+  }
+  return { map, unmapped }
+}

package/src/spellcheck/core.js

@@ -20,7 +20,16 @@
  * and passed in. Caller manages caching.
  */
 
-import { possibleRoots } from '../welsh/mutations.js'
+import { possibleRoots, applyMutation, MUTATION } from '../welsh/mutations.js'
+
+// Edit-distance ceiling for the accept-list bias inside suggest().
+// Raised to 3 (was 2 pre-audit 2026-05-20) so proper-noun typos one
+// extra step beyond what nspell catches still surface the right
+// glossary hit. Eg 'Gyfyrddin' -> 'Gaerfyrddin' is distance 3.
+const ACCEPT_BIAS_MAX_DIST = 3
+
+// Welsh mutations to try when forward-mutating accept-list entries.
+const ACCEPT_MUTATION_KINDS = [MUTATION.soft, MUTATION.nasal, MUTATION.aspirate]
 
 /**
  * Check a single word against the supplied dictionary + accept-list.
@@ -41,6 +50,17 @@ export function checkWord(word, { nspell, accept, welsh }) {
   if (typeof word !== 'string' || word.length === 0) return true
   const cleaned = word.replace(/[^\p{L}\p{M}'’-]/gu, '')
   if (cleaned.length === 0) return true
+  // No letter characters at all (e.g. a bare hyphen) -- treat as OK.
+  if (!/\p{L}/u.test(cleaned)) return true
+  // Hyphenated compounds (e.g. 'cyd-destun', 'ar-ol', 'rhag-brawf'):
+  // Welsh dictionaries store roots, not every compound form. Split on
+  // hyphen and accept if every component passes individually.
+  if (cleaned.includes('-')) {
+    const parts = cleaned.split('-').filter(p => /\p{L}/u.test(p))
+    if (parts.length > 1) {
+      return parts.every(part => checkWord(part, { nspell, accept, welsh }))
+    }
+  }
   const lower = cleaned.toLowerCase()
   if (accept && accept.has(lower)) return true
   if (nspell.correct(cleaned)) return true
@@ -74,7 +94,12 @@ export function tokenise(text) {
   const re = /[\p{L}\p{M}'’-]+/gu
   let m
   while ((m = re.exec(text)) !== null) {
-    tokens.push({ word: m[0], start: m.index, end: m.index + m[0].length })
+    // Guard: skip tokens with no letter at all. A bare '-' or apostrophe-only
+    // run is punctuation, not a word. Without this, 'word - word' produces a
+    // standalone '-' token that nspell.correct() rejects -> false red squiggle.
+    if (/\p{L}/u.test(m[0])) {
+      tokens.push({ word: m[0], start: m.index, end: m.index + m[0].length })
+    }
   }
   return tokens
 }
@@ -85,6 +110,9 @@ export function tokenise(text) {
  *
  * @param {string} text
  * @param {object} opts - same shape as checkWord opts
+ * @param {object} opts.nspell - An nspell instance.
+ * @param {Set<string>} [opts.accept] - Terms that must never be flagged.
+ * @param {boolean} [opts.welsh] - Try mutation reversal before flagging.
  * @returns {{ word: string, start: number, end: number }[]}
  */
 export function checkSentence(text, opts) {
@@ -100,22 +128,45 @@ export function checkSentence(text, opts) {
  * @param {object} opts
  * @param {object} opts.nspell
  * @param {Set<string>} [opts.accept]
+ * @param {boolean} [opts.welsh] - Bias suggestions for Welsh mutation forms.
  * @param {number} [opts.max] - default 6
  * @returns {string[]}
  */
-export function suggest(word, { nspell, accept, max = 6 }) {
+export function suggest(word, { nspell, accept, welsh, max = 6 }) {
   if (typeof word !== 'string' || word.length === 0) return []
   const base = nspell.suggest(word) || []
   if (!accept || accept.size === 0) return base.slice(0, max)
-  const acceptHits = []
   const lower = word.toLowerCase()
+
+  // Build candidate surface forms from each accept-list entry.
+  // Welsh: try the bare term plus each mutation, and pick whichever form
+  // is closest to the misspelling - so 'Caerfyrddin' in the glossary
+  // surfaces as 'Gaerfyrddin' when the typo was 'Gyfyrddin', preserving
+  // the grammatically-correct mutated surface form.
+  // English (welsh falsy): just the bare term, no mutation table.
+  const acceptHits = []
+  const seenHit = new Set()
   for (const term of accept) {
     if (term === lower) continue
-    if (editDistance(lower, term, 2) <= 2) acceptHits.push(term)
+    const candidates = welsh ? mutatedCandidates(term) : [term]
+    let bestForm = null
+    let bestDist = ACCEPT_BIAS_MAX_DIST + 1
+    for (const cand of candidates) {
+      const d = editDistance(lower, cand.toLowerCase(), ACCEPT_BIAS_MAX_DIST)
+      if (d <= ACCEPT_BIAS_MAX_DIST && d < bestDist) {
+        bestDist = d
+        bestForm = cand
+      }
+    }
+    if (bestForm && !seenHit.has(bestForm.toLowerCase())) {
+      acceptHits.push(bestForm)
+      seenHit.add(bestForm.toLowerCase())
+    }
   }
+
   // De-dupe: glossary hits first, then nspell suggestions that aren't dupes.
-  const seen = new Set(acceptHits.map(t => t.toLowerCase()))
   const out = [...acceptHits]
+  const seen = new Set(acceptHits.map(t => t.toLowerCase()))
   for (const s of base) {
     if (out.length >= max) break
     if (!seen.has(s.toLowerCase())) {
@@ -123,6 +174,22 @@ export function suggest(word, { nspell, accept, max = 6 }) {
       seen.add(s.toLowerCase())
     }
   }
+  return out.slice(0, max)
+}
+
+// Expand a Welsh accept-list term to its surface forms: bare + every
+// mutation. applyMutation() returns the input unchanged when the initial
+// consonant isn't subject to that mutation, so dedupe before returning.
+function mutatedCandidates(term) {
+  const out = [term]
+  const seen = new Set([term.toLowerCase()])
+  for (const kind of ACCEPT_MUTATION_KINDS) {
+    const m = applyMutation(term, kind)
+    if (m && !seen.has(m.toLowerCase())) {
+      out.push(m)
+      seen.add(m.toLowerCase())
+    }
+  }
   return out
 }
 

package/src/welsh/normaliser.js

@@ -20,6 +20,17 @@ const ZERO_WIDTH          = /[\u200B\u200C\u200D\uFEFF]/g
 // Deterministic Welsh broken-contraction repairs (ASR artefacts)
 const CONTRACTION_REPAIRS = [
   [/\b(a|o|i|â) r\b/gi,                           "$1'r"],
+  // Verb + 'r: ASR drops the apostrophe before the definite article.
+  // e.g. "mae r athro" → "mae'r athro", "yw r plant" → "yw'r plant".
+  // Drift fix: these were absent from the drifted frontend copy (#449).
+  // VOWEL-ENDING verbs only ('r attaches after vowels).
+  [/\b(mae|yw|dyma|dyna) r\b/gi, "$1'r"],
+  // CONSONANT-ENDING verbs take the full article, not 'r: "oedd r ffordd"
+  // is the ASR mishearing "oedd y ffordd", and "oedd'r" is ungrammatical.
+  // Repair to yr before vowels/h, y otherwise (Codex on #1103; Aled's call
+  // 2026-06-12: restore the article rather than leave the artefact).
+  [/\b(oedd|fydd|bydd|sydd|roedd|caiff|gall) r (?=[aeiouwyhâêîôûŵŷáéíóúàèìòùäëïöü])/gi, '$1 yr '],
+  [/\b(oedd|fydd|bydd|sydd|roedd|caiff|gall) r\b/gi, '$1 y'],
   [/\bwedi (u|i|m|n|ch)\b/gi,                      "wedi'$1"],
   [/\bwedi eu\b/gi,                                 "wedi'u"],
   [/\bwedi ei\b/gi,                                 "wedi'i"],

package/types/corrections/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./pure.js";
+export * from "./tracker.js";

package/types/corrections/pure.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Compute the set of proper-noun corrections worth promoting.
+ *
+ * Diffs `before` against `after` on whitespace tokens and returns the
+ * corrected tokens that look like proper nouns. Structural edits (the
+ * token count changed) return `[]`: word-for-word swaps are the
+ * high-signal class and everything else is too noisy to learn from.
+ *
+ * In Capsiynau these terms become rows in `word_boost_approved` (per-org,
+ * tagged with the session's language) and the relay's loader treats those
+ * rows as language-agnostic on read - see the contract note on
+ * `looksLikeProperNoun` above for the full invariant and what must change
+ * if the heuristic ever expands beyond proper nouns. The function itself
+ * knows nothing about that table; a consumer on a different schema can
+ * do whatever it likes with the returned terms.
+ *
+ * @param {string} before Original text before the edit.
+ * @param {string} after  Text after the edit.
+ * @returns {string[]} Deduplicated corrected tokens worth biasing toward.
+ */
+export function extractProperNounCorrections(before: string, after: string): string[];

package/types/corrections/tracker.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Upsert proper-noun corrections into word_boost_approved for the session's
+ * org + source language. Returns the list of terms persisted (excludes
+ * duplicates already in the table - upsert is silent on conflict).
+ *
+ * Never throws - failures are logged and swallowed so a segment-edit save
+ * is never blocked by a vocabulary-learning hiccup.
+ *
+ * CAPSIYNAU-SPECIFIC. Requires `live_sessions`, `live_segments` and
+ * `word_boost_approved`. If you only want the heuristic, import
+ * `extractProperNounCorrections` from
+ * `@capsiynau/intelligence/corrections/pure`.
+ *
+ * @param {string} before  Original segment text before the edit.
+ * @param {string} after   Text after the edit.
+ * @param {object} opts
+ * @param {string} opts.sessionId  Live session UUID for org / fallback-lang lookup.
+ * @param {string} [opts.segmentId] Phase 1+ (notes-app#262): live_segments
+ *                                 UUID for the edited segment. When provided,
+ *                                 the segment's own `language` column is used
+ *                                 for the new word_boost_approved row (drops
+ *                                 silent rot in mixed-language sessions where
+ *                                 Phase 3's per-chunk detected_language differs
+ *                                 from session.source_language). Falls back to
+ *                                 session.source_language if absent or the
+ *                                 segment's language column is null.
+ * @param {object} opts.supabase   Caller-provided Supabase client (DI).
+ *                                 Must have `.from()` and `.rpc()` methods.
+ *                                 RLS scopes writes by org.
+ * @returns {Promise<string[]>} Terms persisted (empty on any failure).
+ */
+export function captureCorrections(before: string, after: string, { sessionId, segmentId, supabase }: {
+    sessionId: string;
+    segmentId?: string;
+    supabase: object;
+}): Promise<string[]>;

package/types/glossary/import.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Parse a CSV-ish string. Accepts (with or without header row):
+ *   term,definition
+ *   term,definition,category
+ *   term,category,definition
+ * Header row (detected by token match) maps columns by name and
+ * tolerates aliases (name, meaning, tag). RFC-4180-lite: quoted
+ * fields + escaped quotes on a single line. Multi-line quoted values
+ * are out of scope - report and skip.
+ */
+export function parseImportedCsv(raw: any): {
+    rows: {
+        source_term: string;
+        preferred_term: string;
+        definition: string;
+        category: any;
+    }[];
+    errors: {
+        line: number;
+        reason: string;
+    }[];
+};
+/**
+ * Parse plain text. One term per line. Separator tried in order: tab,
+ * `:` followed by space, ` - ` (hyphen with spaces). Three columns
+ * (term, definition, optional category) match our copy-as-text output
+ * so users can round-trip cleanly.
+ */
+export function parseImportedText(raw: any): {
+    rows: {
+        source_term: string;
+        preferred_term: string;
+        definition: string;
+        category: string;
+    }[];
+    errors: {
+        line: number;
+        reason: string;
+    }[];
+};
+/**
+ * Split incoming rows against the existing set. Matches case-insensitive
+ * on trimmed source_term. Returns {additions, conflicts} where conflicts
+ * is an array of {existing, incoming} pairs the UI surfaces for
+ * resolution. Dedup within the import itself happens against additions
+ * (the second occurrence of a duplicated import term becomes a conflict
+ * with the first occurrence).
+ */
+export function splitImportAgainstExisting(existing: any, incoming: any): {
+    additions: any[];
+    conflicts: {
+        existing: any;
+        incoming: any;
+    }[];
+};

package/types/glossary/index.d.ts

@@ -0,0 +1,6 @@
+export { WEB_SEARCH_TOOL } from "./tools.js";
+export { normaliseUrl, isHttpUrl } from "./url.js";
+export { extractText, parseTermsJson, normaliseTermRow, flagDiacriticStrip } from "./parse.js";
+export { RESEARCH_SYSTEM, buildGenerationSystemPrompt, buildExpandSystemPrompt } from "./prompts.js";
+export { parseImportedCsv, parseImportedText, splitImportAgainstExisting } from "./import.js";
+export { suggestGlossaryName, languagePairFor, expandRowsForDb, buildGlossaryRow, suggestVersionedName } from "./persist.js";

package/types/glossary/parse.d.ts

@@ -0,0 +1,63 @@
+export function extractText(message: any): any;
+/**
+ * Defensive JSON parse for the generation phase. The model is told to
+ * reply with raw JSON only, but markdown fences and conversational
+ * preamble do leak through. Strip what we can, then fall back to the
+ * first [...] match. Return null on total failure - never throw.
+ */
+export function parseTermsJson(raw: any): any[];
+/**
+ * Heuristic guard: any Welsh text longer than 25 chars with ZERO
+ * diacritics is suspicious - the model probably stripped them.
+ *
+ * Not a perfect check (some short Welsh text genuinely has none) but
+ * catches the common "model normalised everything to ASCII" failure
+ * mode. Substitution detection (ŵ → w, ŷ → y in specific positions)
+ * requires a dictionary and is deferred to a future Tier-3 spellcheck
+ * integration; not in scope for the wizard.
+ */
+export function flagDiacriticStrip(text: any): boolean;
+/**
+ * Normalise one row from the model's JSON output.
+ *
+ * In 'en' mode: tolerate naming wobbles ({term} vs {source_term}; etc).
+ * In 'cy' mode: same shape, but route Welsh text through normaliseWelsh().
+ * In 'bilingual' mode: expect {term_en, term_cy, definition_en,
+ *   definition_cy, category}; route the *_cy fields through normaliseWelsh().
+ *
+ * Returns null for entries missing the required fields so the caller
+ * can `.map(normaliseTermRow).filter(Boolean)`. Adds a transient
+ * `_diacritic_warning` flag the handler can aggregate; it does NOT
+ * persist to the DB.
+ */
+export function normaliseTermRow(t: any, opts?: {}): {
+    source_term: any;
+    preferred_term: any;
+    definition: any;
+    term_en: any;
+    term_cy: any;
+    definition_en: any;
+    definition_cy: any;
+    category: string;
+    _diacritic_warning: boolean;
+} | {
+    source_term: any;
+    preferred_term: any;
+    definition: any;
+    category: string;
+    _diacritic_warning: boolean;
+    term_en?: undefined;
+    term_cy?: undefined;
+    definition_en?: undefined;
+    definition_cy?: undefined;
+} | {
+    source_term: string;
+    preferred_term: string;
+    definition: string;
+    category: string;
+    term_en?: undefined;
+    term_cy?: undefined;
+    definition_en?: undefined;
+    definition_cy?: undefined;
+    _diacritic_warning?: undefined;
+};

package/types/glossary/persist.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Pure helpers for converting Glossary Builder wizard rows into the
+ * shapes the `glossaries` + `terms` Supabase tables expect.
+ *
+ * No Supabase calls here - those live in the view layer
+ * (src/components/glossaryBuilder/savePersist.js) so this module
+ * stays unit-testable and side-effect-free, mirroring how
+ * @capsiynau/intelligence/welsh/normaliser splits pure logic from
+ * the API handler.
+ */
+/**
+ * Suggest a glossary name based on the source URL. Strips
+ * protocol + leading `www.` so the result reads naturally
+ * ("Site terms - example.com").
+ */
+export function suggestGlossaryName(url: any): string;
+/**
+ * Map wizard languageMode to glossaries.language_pair. Single-language
+ * modes get 'en-GB' or 'cy-GB'; bilingual is 'en-GB,cy-GB' (the
+ * existing convention in the schema for multi-language glossaries).
+ */
+export function languagePairFor(languageMode: any): "cy-GB" | "en-GB,cy-GB" | "en-GB";
+/**
+ * Expand wizard rows into terms-table inserts.
+ *
+ * Single-language modes produce one row per wizard row.
+ * Bilingual produces TWO rows per pair (EN + CY), linked by sharing
+ * glossary_id and category, with source_language differing. This uses
+ * the schema as designed and keeps the live-relay engine able to
+ * query by language without a JOIN.
+ *
+ * Drops rows missing term or definition silently (the wizard
+ * shouldn't let them through, but defence in depth at persistence
+ * time means a partial bilingual row contributes only its complete
+ * leg rather than aborting the whole save).
+ */
+export function expandRowsForDb(wizardRows: any, opts?: {}): any[];
+/**
+ * Build the glossaries-table insert payload for a wizard save.
+ * Defaults to visibility='shared' (org-wide, not just creator) - the
+ * wizard is collaborative tooling, not personal scratch space.
+ */
+export function buildGlossaryRow({ name, url, languageMode, organisationId, createdBy, visibility, }: {
+    name: any;
+    url: any;
+    languageMode: any;
+    organisationId: any;
+    createdBy: any;
+    visibility?: string;
+}): {
+    name: any;
+    description: string;
+    organisation_id: any;
+    created_by: any;
+    visibility: string;
+    language_pair: string;
+    source_url: any;
+    is_default: boolean;
+    is_system: boolean;
+};
+/**
+ * Suggest a versioned name when "Create new version" is chosen on
+ * conflict. Bumps an existing (vN) suffix or appends (v2) to a name
+ * that lacks one.
+ */
+export function suggestVersionedName(existingName: any): string;

package/types/glossary/prompts.d.ts

@@ -0,0 +1,10 @@
+export function buildGenerationSystemPrompt({ audience, topics, languageMode, dialect, }?: {
+    languageMode?: string;
+    dialect?: string;
+}): string;
+export function buildExpandSystemPrompt({ audience, topics, languageMode, dialect, existingTerms, }?: {
+    languageMode?: string;
+    dialect?: string;
+    existingTerms?: any[];
+}): string;
+export const RESEARCH_SYSTEM: "You are helping a SaaS user build a starter glossary for their organisation. You have a web_search tool - use it to look up the URL the user provides and identify the industry, the products / services they offer, and the likely audience. Reply conversationally in 2-3 sentences confirming what you found, then ask who the glossary is for (e.g. \"clients\", \"internal team\", \"general public\", \"broadcasters\"). Keep the tone warm and direct. Do NOT produce a glossary yet - that comes in a follow-up step.";

package/types/glossary/tools.d.ts

@@ -0,0 +1,4 @@
+export namespace WEB_SEARCH_TOOL {
+    let type: string;
+    let name: string;
+}

package/types/glossary/url.d.ts

@@ -0,0 +1,9 @@
+/**
+ * URL helpers for the Glossary Builder engine.
+ *
+ * Anthropic's web_search expects a full URL; a bare 'example.com'
+ * returns "no relevant pages" and the whole flow degrades silently.
+ * normaliseUrl prepends https:// when the caller forgot a scheme.
+ */
+export function normaliseUrl(raw: any): string;
+export function isHttpUrl(url: any): boolean;

package/types/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./corrections/index.js";
+export * from "./welsh/index.js";