@capsiynau/intelligence 0.3.0 → 0.5.0

package/types/dialect/index.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The lexicon as a reviewable list. This is what a "your preferred terms"
+ * management screen renders, and what a workspace exports for sign-off.
+ *
+ * @param {'north'|'south'|'neutral'|'broadcast'|'formal'} region
+ * @returns {Array<{id:string, gloss:string, preferred:string, alternatives:string[]}>}
+ */
+export function listDialectTerms(region: "north" | "south" | "neutral" | "broadcast" | "formal"): Array<{
+    id: string;
+    gloss: string;
+    preferred: string;
+    alternatives: string[];
+}>;
+/**
+ * Report off-region terms WITHOUT changing the text. This is the validator
+ * half: it produces evidence a reviewer can act on, which is what makes the
+ * lexical layer auditable rather than merely applied.
+ *
+ * @param {string} text
+ * @param {'north'|'south'|'neutral'|'broadcast'|'formal'} region
+ * @returns {Array<{id:string, found:string, expected:string, index:number}>}
+ *          Findings in document order. Empty array for empty input.
+ */
+export function checkDialect(text: string, region: "north" | "south" | "neutral" | "broadcast" | "formal"): Array<{
+    id: string;
+    found: string;
+    expected: string;
+    index: number;
+}>;
+/**
+ * Rewrite off-region terms to the target region's form. Deterministic and
+ * case-preserving; returns the input unchanged when there is nothing to do.
+ *
+ * Substitution is whole-term only and mutation-blind, so it is safe to run on
+ * mixed Welsh/English text: no entry in the table is an English word.
+ *
+ * @param {string} text
+ * @param {'north'|'south'|'neutral'|'broadcast'|'formal'} region
+ * @returns {string}
+ */
+export function applyDialect(text: string, region: "north" | "south" | "neutral" | "broadcast" | "formal"): string;
+export namespace DIALECT_TERMS_STATUS {
+    let reviewed: boolean;
+    let reviewedBy: any;
+    let seededOn: string;
+    let note: string;
+}
+/**
+ * Seed lexicon. `neutral` is the form a broadcast or formal register would
+ * use; `null` means BOTH forms are regionally marked and there is no neutral
+ * standard, so a neutral target leaves the text alone rather than inventing
+ * one. Saying "no neutral form exists" is more useful than picking a side.
+ */
+export const DIALECT_TERMS: {
+    id: string;
+    north: string;
+    south: string;
+    neutral: string;
+    gloss: string;
+}[];
+/**
+ * Deliberately NOT in the table, with the reason. Kept in code because the
+ * next person to extend this will reach for exactly these, and the reason
+ * they are absent is not self-evident.
+ */
+export const EXCLUDED_TERMS: {
+    id: string;
+    reason: 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";

package/types/speakers/index.d.ts

@@ -0,0 +1,85 @@
+/**
+ * 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: Array<{
+    start?: number;
+    end?: number;
+}>, spanStart: number, spanEnd: number): number;
+/**
+ * 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: Array<{
+    start: number;
+    end: number;
+    speaker: string;
+}>, segments: Array<{
+    start_ms: number;
+    end_ms: number;
+}>, opts?: Partial<typeof DIARISATION_GATE_DEFAULTS>): {
+    reliable: boolean;
+    speakerCount: number;
+    coverage: number;
+    durationMs: number;
+    reason: string;
+};
+/**
+ * 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: Array<{
+    start: number;
+    end: number;
+    speaker: string;
+}>, labelled: Array<{
+    start: number;
+    end: number;
+    name: string;
+}>, opts?: Partial<typeof SPEAKER_MAP_DEFAULTS>): {
+    map: Record<string, string>;
+    unmapped: string[];
+};
+export namespace DIARISATION_GATE_DEFAULTS {
+    let soleSpeakerSuspectAboveMs: number;
+    let minCoverage: number;
+    let trustAtSpeakers: number;
+}
+export namespace SPEAKER_MAP_DEFAULTS {
+    let minOverlapFraction: number;
+    let dominanceRatio: number;
+}

package/types/spellcheck/core.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Check a single word against the supplied dictionary + accept-list.
+ *
+ * @param {string} word - The word to check (no punctuation, single token).
+ * @param {object} opts
+ * @param {object} opts.nspell - An nspell instance (server side, built
+ *                               from dictionary-cy or dictionary-en-gb).
+ * @param {Set<string>} [opts.accept] - Lowercased proper nouns + glossary
+ *                                       + word_boost_approved terms that
+ *                                       must never be flagged.
+ * @param {boolean} [opts.welsh] - When true, additionally try mutation
+ *                                  reversal before declaring the word
+ *                                  misspelled. Pass false for English.
+ * @returns {boolean} true if the word is considered correctly spelled.
+ */
+export function checkWord(word: string, { nspell, accept, welsh }: {
+    nspell: object;
+    accept?: Set<string>;
+    welsh?: boolean;
+}): boolean;
+/**
+ * Tokenise a string into checkable words + their positions, so a UI
+ * can underline only the wrong tokens without re-tokenising itself.
+ *
+ * Position is the offset in the original string. Tokens are word-like
+ * runs of letters/marks/apostrophes/hyphens; punctuation is skipped.
+ *
+ * @param {string} text
+ * @returns {{ word: string, start: number, end: number }[]}
+ */
+export function tokenise(text: string): {
+    word: string;
+    start: number;
+    end: number;
+}[];
+/**
+ * Check an entire string and return the misspelled tokens (if any).
+ * Convenience wrapper around tokenise + checkWord.
+ *
+ * @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: string, opts: {
+    nspell: object;
+    accept?: Set<string>;
+    welsh?: boolean;
+}): {
+    word: string;
+    start: number;
+    end: number;
+}[];
+/**
+ * Generate up to N suggestions for a misspelled word. Wraps
+ * nspell.suggest() but biases toward `accept` (proper nouns are
+ * surfaced first when they're close in edit distance).
+ *
+ * @param {string} word
+ * @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: string, { nspell, accept, welsh, max }: {
+    nspell: object;
+    accept?: Set<string>;
+    welsh?: boolean;
+    max?: number;
+}): string[];

package/types/spellcheck/index.d.ts

@@ -0,0 +1 @@
+export { checkWord, checkSentence, tokenise, suggest } from "./core.js";

package/types/welsh/digraphs.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Split a Welsh word into its constituent letters, treating digraphs
+ * as single units. Case-preserving.
+ *
+ * @example
+ *   splitIntoLetters('llwybr')   // ['ll', 'w', 'y', 'b', 'r']
+ *   splitIntoLetters('CHWARAE')  // ['CH', 'W', 'A', 'R', 'A', 'E']
+ *   splitIntoLetters('rhag-')    // ['rh', 'a', 'g', '-']
+ *
+ * @param {string} word
+ * @returns {string[]}
+ */
+export function splitIntoLetters(word: string): string[];
+/**
+ * Welsh-aware character count: a digraph counts as ONE letter.
+ *
+ * @example
+ *   welshLength('llwybr')     // 5  (ll-w-y-b-r), NOT 6
+ *   welshLength('chwarae')    // 6  (ch-w-a-r-a-e)
+ *   welshLength('Eisteddfod') // 9  (e-i-s-t-e-dd-f-o-d), NOT 10
+ *
+ * @param {string} word
+ * @returns {number}
+ */
+export function welshLength(word: string): number;
+/**
+ * Reverse a Welsh word preserving digraphs (used by anagram /
+ * caption-style transforms that mirror text).
+ *
+ * @example
+ *   welshReverse('llwybr')  // 'rbywll'  (NOT 'rbywll' broken to 'rbyw ll')
+ *
+ * @param {string} word
+ * @returns {string}
+ */
+export function welshReverse(word: string): string;
+export function welshCompare(a: any, b: any): number;
+/**
+ * Check if a string position lies on a digraph boundary. Useful for
+ * cursor / selection logic: when the cursor sits after `l` in `llwybr`,
+ * a single backspace should remove BOTH letters of `ll`, not just one.
+ *
+ * Returns `true` if the character at `index` is the second half of a
+ * digraph (i.e. the digraph started at `index - 1`).
+ *
+ * @example
+ *   isDigraphContinuation('llwybr', 1) // true   ('l' completing 'll')
+ *   isDigraphContinuation('llwybr', 2) // false  ('w')
+ *   isDigraphContinuation('cath', 1)   // false  ('a')
+ *
+ * @param {string} word
+ * @param {number} index
+ * @returns {boolean}
+ */
+export function isDigraphContinuation(word: string, index: number): boolean;
+/**
+ * @capsiynau/intelligence/welsh/digraphs
+ *
+ * Welsh digraph handling. In the Welsh alphabet, these eight digraphs
+ * are SINGLE letters and must be treated as one unit for:
+ *   - character iteration
+ *   - cursor movement
+ *   - word length
+ *   - alphabetical sort
+ *   - reversal (for anagrams etc.)
+ *
+ * The eight digraphs (canonical order in the Welsh alphabet):
+ *   ch  dd  ff  ng  ll  ph  rh  th
+ *
+ * Note: `ng` is the most context-sensitive. In some words it represents
+ * a single sound (canu's "ng" is /ŋ/) but in compound words it can be
+ * `n` + `g` separately (e.g. "Bangor" is BAN+GOR phonetically but
+ * conventionally still written without splitting). For purely
+ * orthographic operations (length, indexing, anagrams), we treat every
+ * occurrence as a single digraph. Callers needing phonetic accuracy
+ * must layer their own lexicon lookup on top.
+ *
+ * Pure JS, no external deps.
+ */
+/**
+ * The eight Welsh digraphs in their canonical alphabetical order.
+ * @type {readonly string[]}
+ */
+export const WELSH_DIGRAPHS: readonly string[];
+/**
+ * Map of digraph -> alphabetical position (0-indexed within the digraph set).
+ * For full Welsh-alphabet collation, layer this on top of the single-letter
+ * position map in `WELSH_ALPHABET_ORDER` below.
+ */
+export const DIGRAPH_INDEX: Readonly<{
+    [k: string]: number;
+}>;
+/**
+ * The canonical Welsh alphabet in collation order. Note the digraphs
+ * follow their leading letter: `c` then `ch`, `d` then `dd`, etc.
+ * Letters not in Welsh (`k`, `q`, `v`, `x`, `z`) are omitted; loan words
+ * containing them are conventionally sorted as if they were English.
+ *
+ * Source: Geiriadur Prifysgol Cymru collation rules.
+ * @type {readonly string[]}
+ */
+export const WELSH_ALPHABET_ORDER: readonly string[];

package/types/welsh/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./normaliser.js";
+export * from "./digraphs.js";
+export * from "./mutations.js";

package/types/welsh/mutations.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Apply a mutation to a Welsh word. Returns the mutated form.
+ * Preserves the case of the first character.
+ *
+ * Soft mutation of `g` is DELETION — the word loses its initial `g`.
+ * e.g. 'gardd' -> soft -> 'ardd' (the garden, after 'yr' for feminine).
+ *
+ * If the word's initial consonant is not subject to the given mutation,
+ * returns the word unchanged.
+ *
+ * @param {string} word
+ * @param {'soft'|'nasal'|'aspirate'} kind
+ * @returns {string}
+ *
+ * @example
+ *   applyMutation('cath',  'soft')      // 'gath'
+ *   applyMutation('Tad',   'soft')      // 'Dad'    (case preserved)
+ *   applyMutation('ci',    'nasal')     // 'nghi'
+ *   applyMutation('Pen',   'aspirate')  // 'Phen'
+ *   applyMutation('gardd', 'soft')      // 'ardd'   (g-deletion)
+ *   applyMutation('llaw',  'soft')      // 'law'
+ *   applyMutation('siop',  'soft')      // 'siop'   (s not subject)
+ */
+export function applyMutation(word: string, kind: "soft" | "nasal" | "aspirate"): string;
+/**
+ * Reverse a mutation: given an observed (possibly mutated) word,
+ * return all candidate root forms. The caller can intersect this
+ * with a dictionary lookup to pick the real root.
+ *
+ * If `kind` is provided, only candidates from that mutation are
+ * returned. If omitted, candidates from all three mutations.
+ *
+ * The observed word itself is ALWAYS included as the first candidate
+ * (it might not actually be mutated).
+ *
+ * @param {string} word
+ * @param {'soft'|'nasal'|'aspirate'} [kind]
+ * @returns {{ root: string, kind: string | null }[]}
+ *
+ * @example
+ *   possibleRoots('gath')   // [
+ *                            //   { root: 'gath', kind: null },     // as-is
+ *                            //   { root: 'cath', kind: 'soft' },   // c -> g
+ *                            // ]
+ *   possibleRoots('phen', 'aspirate') // [
+ *                            //   { root: 'phen', kind: null },
+ *                            //   { root: 'pen',  kind: 'aspirate' },
+ *                            // ]
+ */
+export function possibleRoots(word: string, kind?: "soft" | "nasal" | "aspirate"): {
+    root: string;
+    kind: string | null;
+}[];
+/**
+ * Best-effort classification: does this word LOOK mutated?
+ *
+ * Returns the mutation kind if the word starts with a sequence
+ * characteristic of one specific mutation (e.g. 'ph' / 'th' / 'ch' are
+ * aspirate-only; 'mh' / 'nh' / 'ngh' are nasal-only). Returns null if
+ * the word either isn't mutated or its surface form is ambiguous.
+ *
+ * NOT a reliable mutation detector on its own. Use with caller context.
+ *
+ * @param {string} word
+ * @returns {'soft'|'nasal'|'aspirate'|null}
+ */
+export function classifyMutation(word: string): "soft" | "nasal" | "aspirate" | null;
+/**
+ * The three mutation kinds as a const enum-ish object.
+ * @type {Readonly<{soft:'soft', nasal:'nasal', aspirate:'aspirate'}>}
+ */
+export const MUTATION: Readonly<{
+    soft: "soft";
+    nasal: "nasal";
+    aspirate: "aspirate";
+}>;

package/types/welsh/normaliser.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Normalise raw Welsh/English transcript text.
+ * Repairs broken contractions, fixes encoding, removes zero-width chars.
+ * Safe to apply to English too — repairs are Welsh-specific patterns unlikely
+ * to match English text.
+ */
+export function normaliseWelsh(text: any): any;
+/**
+ * Get a dialect-specific system prompt fragment for AI calls.
+ * @param {'broadcast'|'north'|'south'|'formal'} dialect
+ * @returns {string}
+ */
+export function getDialectSystemPrompt(dialect: "broadcast" | "north" | "south" | "formal"): string;