@capsiynau/intelligence 0.2.0

package/src/welsh/digraphs.js

@@ -0,0 +1,184 @@
+/**
+ * @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 = Object.freeze([
+  'ch', 'dd', 'ff', 'ng', 'll', 'ph', 'rh', 'th',
+])
+
+/**
+ * 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 = Object.freeze(
+  Object.fromEntries(WELSH_DIGRAPHS.map((d, i) => [d, i]))
+)
+
+/**
+ * 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 = Object.freeze([
+  'a', 'b', 'c', 'ch', 'd', 'dd', 'e', 'f', 'ff', 'g', 'ng',
+  'h', 'i', 'j', 'l', 'll', 'm', 'n', 'o', 'p', 'ph', 'r', 'rh',
+  's', 't', 'th', 'u', 'w', 'y',
+])
+
+/**
+ * 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) {
+  if (typeof word !== 'string') return []
+  const out = []
+  for (let i = 0; i < word.length; i++) {
+    const two = word.slice(i, i + 2).toLowerCase()
+    if (DIGRAPH_INDEX[two] !== undefined) {
+      out.push(word.slice(i, i + 2))
+      i++
+    } else {
+      out.push(word[i])
+    }
+  }
+  return out
+}
+
+/**
+ * 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) {
+  return splitIntoLetters(word).length
+}
+
+/**
+ * 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) {
+  return splitIntoLetters(word).reverse().join('')
+}
+
+/**
+ * Welsh-collation compare function (sort comparator). Treats digraphs
+ * as their own collation slot, so 'cath' sorts before 'chwarae'
+ * (because `c` < `ch` < `d`).
+ *
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
+ */
+const POSITION_OF = Object.freeze(
+  Object.fromEntries(WELSH_ALPHABET_ORDER.map((l, i) => [l, i]))
+)
+
+/**
+ * Strip combining diacritics so 'â' collates as 'a', 'ŵ' as 'w', etc.
+ * Welsh dictionaries treat accented vowels as the same slot as their
+ * base letter — `âl` sorts among the `a...` entries, not after `z`.
+ * Codex P2 on PR #454: without this, every accented form fell through
+ * to charCodeAt+1000 and sorted after the full alphabet.
+ */
+function stripAccents(letter) {
+  return letter.normalize('NFD').replace(/[̀-ͯ]/g, '')
+}
+
+function positionFor(letter) {
+  const direct = POSITION_OF[letter]
+  if (direct !== undefined) return direct
+  const stripped = stripAccents(letter)
+  if (stripped !== letter) {
+    const viaBase = POSITION_OF[stripped] ?? POSITION_OF[stripped[0]]
+    if (viaBase !== undefined) return viaBase
+  }
+  const head = POSITION_OF[letter[0]]
+  if (head !== undefined) return head
+  return letter.charCodeAt(0) + 1000
+}
+
+export function welshCompare(a, b) {
+  const la = splitIntoLetters(String(a).toLowerCase())
+  const lb = splitIntoLetters(String(b).toLowerCase())
+  const n  = Math.min(la.length, lb.length)
+  for (let i = 0; i < n; i++) {
+    const pa = positionFor(la[i])
+    const pb = positionFor(lb[i])
+    if (pa !== pb) return pa - pb
+  }
+  return la.length - lb.length
+}
+
+/**
+ * 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, index) {
+  if (typeof word !== 'string' || index <= 0 || index >= word.length) return false
+  const pair = word.slice(index - 1, index + 1).toLowerCase()
+  return DIGRAPH_INDEX[pair] !== undefined
+}

package/src/welsh/index.js

@@ -0,0 +1,8 @@
+/**
+ * @capsiynau/intelligence/welsh
+ *
+ * Welsh-language intelligence utilities. Pure JS, no external deps.
+ */
+export * from './normaliser.js'
+export * from './digraphs.js'
+export * from './mutations.js'

package/src/welsh/mutations.js

@@ -0,0 +1,252 @@
+/**
+ * @capsiynau/intelligence/welsh/mutations
+ *
+ * Welsh initial consonant mutations (treigladau dechreuol).
+ *
+ * Three mutations exist:
+ *   - Soft   (meddal):  p->b, t->d, c->g, b->f, d->dd, g->(deleted), m->f, ll->l, rh->r
+ *   - Nasal  (trwynol): p->mh, t->nh, c->ngh, b->m, d->n, g->ng
+ *   - Aspirate (llaes): p->ph, t->th, c->ch
+ *
+ * What this module DOES:
+ *   - Forward mutation: apply a mutation to a root word (used when
+ *     generating correct grammatical forms after triggers)
+ *   - Reverse mutation: given an observed mutated word, list candidate
+ *     root forms (used by spellcheck / dictionary lookup)
+ *   - Mutation classification: identify which mutation a surface form
+ *     could be the result of
+ *
+ * What this module does NOT do:
+ *   - Decide WHETHER to mutate. That requires syntactic context (the
+ *     trigger word: 'i', 'a', 'yn', 'fy', possessive pronouns, feminine
+ *     singular nouns after 'y', etc.). Triggering rules belong in a
+ *     higher layer that has access to part-of-speech tags.
+ *   - Handle compound words or loanwords differently. Caller's
+ *     responsibility to pre-filter (e.g. 'pizza' should not be treated
+ *     as a Welsh root).
+ *
+ * Pure JS, no external deps. Case-preserving on the first letter of
+ * the result so 'Tad' -> soft -> 'Dad' (preserving the capital).
+ */
+
+const SOFT_FORWARD = {
+  p: 'b', t: 'd', c: 'g',
+  b: 'f', d: 'dd', g: '',
+  m: 'f', ll: 'l', rh: 'r',
+}
+
+const NASAL_FORWARD = {
+  p: 'mh', t: 'nh', c: 'ngh',
+  b: 'm',  d: 'n',  g: 'ng',
+}
+
+const ASPIRATE_FORWARD = {
+  p: 'ph', t: 'th', c: 'ch',
+}
+
+/**
+ * The three mutation kinds as a const enum-ish object.
+ * @type {Readonly<{soft:'soft', nasal:'nasal', aspirate:'aspirate'}>}
+ */
+export const MUTATION = Object.freeze({
+  soft:     'soft',
+  nasal:    'nasal',
+  aspirate: 'aspirate',
+})
+
+const FORWARD_TABLE = {
+  soft:     SOFT_FORWARD,
+  nasal:    NASAL_FORWARD,
+  aspirate: ASPIRATE_FORWARD,
+}
+
+// Reverse table: mutated-prefix -> [{ kind, root }, ...]
+// Built once at module load. Multiple-entry rows mean a surface form
+// is ambiguous (e.g. 'f' could be soft-mutated 'b' or soft-mutated 'm').
+const REVERSE_TABLE = buildReverseTable()
+function buildReverseTable() {
+  /** @type {Record<string, {kind:string,rootPrefix:string}[]>} */
+  const out = {}
+  for (const [kind, table] of Object.entries(FORWARD_TABLE)) {
+    for (const [root, mutated] of Object.entries(table)) {
+      if (mutated === '') continue // soft 'g' -> deletion handled specially
+      if (!out[mutated]) out[mutated] = []
+      out[mutated].push({ kind, rootPrefix: root })
+    }
+  }
+  return out
+}
+
+/**
+ * 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, kind) {
+  if (typeof word !== 'string' || word.length === 0) return word
+  const table = FORWARD_TABLE[kind]
+  if (!table) throw new Error(`Unknown mutation kind: ${kind}`)
+
+  const first = word[0]
+  const lower = word.toLowerCase()
+
+  // Check 2-letter digraphs first (ll, rh) so 'llaw' soft-mutates to
+  // 'law' not 'lll' or similar nonsense.
+  const two = lower.slice(0, 2)
+  if (table[two] !== undefined) {
+    const replacement = table[two]
+    if (replacement === '') return promoteCase(word.slice(2), first)
+    return matchCase(replacement, first) + word.slice(2)
+  }
+
+  const one = lower[0]
+  if (table[one] !== undefined) {
+    const replacement = table[one]
+    // Codex P2 on PR #455: when soft mutation deletes the leading letter
+    // (only g -> '' today), we must promote the NEXT letter to match the
+    // deleted letter's case. Otherwise 'Gardd' -> 'ardd' loses the
+    // sentence-initial capital.
+    if (replacement === '') return promoteCase(word.slice(1), first)
+    return matchCase(replacement, first) + word.slice(1)
+  }
+
+  return word
+}
+
+/**
+ * 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, kind) {
+  if (typeof word !== 'string' || word.length === 0) return []
+  const candidates = [{ root: word, kind: null }]
+  const lower = word.toLowerCase()
+  const first = word[0]
+
+  // Try 3-letter mutated prefixes (ngh, mh, nh, ng, ph, th, ch, dd)
+  // 2-letter mutated prefixes
+  // 1-letter mutated prefixes
+  for (const len of [3, 2, 1]) {
+    const prefix = lower.slice(0, len)
+    const matches = REVERSE_TABLE[prefix]
+    if (!matches) continue
+    for (const { kind: k, rootPrefix } of matches) {
+      if (kind && k !== kind) continue
+      candidates.push({
+        root: matchCase(rootPrefix, first) + word.slice(len),
+        kind: k,
+      })
+    }
+  }
+
+  // Soft 'g' -> deletion case: 'ardd' could be soft-mutated 'gardd'
+  // (only relevant when no kind filter, or kind === 'soft')
+  if ((!kind || kind === MUTATION.soft) && /^[aeiouwâêîôûŵŷ]/i.test(word)) {
+    candidates.push({
+      root: (isUpperFirst(word) ? 'G' : 'g') + word,
+      kind: MUTATION.soft,
+    })
+  }
+
+  return candidates
+}
+
+/**
+ * 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) {
+  if (typeof word !== 'string' || word.length === 0) return null
+  const lower = word.toLowerCase()
+  // Codex P2 on PR #454/#455: `ph/th/ch` are NOT aspirate-only — many
+  // native unmutated Welsh lemmas start with these digraphs (chwarae,
+  // theatr, pharmacydd, chwerthin, ...). Classifying them as aspirate
+  // produces systematic false positives. Returning null is the honest
+  // answer; callers that need disambiguation should use possibleRoots()
+  // with dictionary intersection.
+  // Nasal classifications are kept: `ngh/mh/nh` never start native
+  // unmutated Welsh words, so a match really does indicate a mutation.
+  if (/^(ngh|mh|nh)/.test(lower)) return MUTATION.nasal
+  // Soft-only diagnostics:
+  //   'dd' at start is soft of 'd'
+  //   'f' at start could be soft of 'b' or 'm' (ambiguous, but soft)
+  //   'l' (single, not ll) could be soft of 'll'
+  //   'r' (single, not rh) could be soft of 'rh'
+  // These overlap with native Welsh words starting with those letters
+  // (e.g. 'lle' is a native word, not soft of 'llle'). Returning null
+  // here keeps the function honest; use possibleRoots() instead.
+  return null
+}
+
+// ── helpers ─────────────────────────────────────────────────────────────────
+
+function isUpperFirst(s) {
+  return s[0] && s[0] === s[0].toUpperCase() && s[0] !== s[0].toLowerCase()
+}
+
+function matchCase(replacement, modelChar) {
+  if (!replacement) return replacement
+  if (modelChar && modelChar === modelChar.toUpperCase() && modelChar !== modelChar.toLowerCase()) {
+    return replacement[0].toUpperCase() + replacement.slice(1)
+  }
+  return replacement
+}
+
+// When a mutation deletes the leading letter (g -> ''), promote the
+// next character's case to match the deleted letter's case so
+// 'Gardd' -> 'Ardd' instead of 'ardd'.
+function promoteCase(rest, deletedChar) {
+  if (!rest) return rest
+  if (deletedChar && deletedChar === deletedChar.toUpperCase() && deletedChar !== deletedChar.toLowerCase()) {
+    return rest[0].toUpperCase() + rest.slice(1)
+  }
+  return rest
+}

package/src/welsh/normaliser.js

@@ -0,0 +1,93 @@
+/**
+ * @capsiynau/intelligence/welsh/normaliser
+ *
+ * Shared Welsh text normalisation. Pure JS, no external dependencies.
+ *
+ * Phase A canonicalisation (2026-05-15, PR #448):
+ * Merged successor to two drifted copies that lived at
+ * `src/lib/welshNormaliser.js` (frontend) and `api/_lib/welshNormaliser.js`
+ * (server). The api/_lib version was correct on every count - this file
+ * is a copy of it. The src/lib copy had silently regressed for ~6 weeks:
+ * dropped the `formal` dialect prompt, leaked an embedded dev comment
+ * into the north-dialect prompt ("...wait, reverse:..."), and missing
+ * several contraction rules. Both old paths now shim to here.
+ */
+
+const APOSTROPHE_VARIANTS = /[\u2018\u2019\u201A\u201B\u0060\u00B4]/g
+const QUOTE_VARIANTS      = /[\u201C\u201D\u201E\u201F\u00AB\u00BB]/g
+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"],
+  [/\bwedi (u|i|m|n|ch)\b/gi,                      "wedi'$1"],
+  [/\bwedi eu\b/gi,                                 "wedi'u"],
+  [/\bwedi ei\b/gi,                                 "wedi'i"],
+  [/\b(mae|dyma|dyna|dacw|lle|ble|sydd|oedd|fydd|bydd|roedd|cawn|gallai|allen|bydden) n\b/gi, "$1'n"],
+  [/\bdw i n\b/gi,                                   "dw i'n"],
+  [/\b(dwi|ti|chi|ni|nhw|fe|hi) n\b/gi,            "$1'n"],
+  [/\b(e|o|hi|fe|fo) n\b/gi,                       "$1'n"],
+  [/\bdo n\b/gi,                                    "do'n"],   // "do'n i ddim" — wasn't
+  [/\b(i|a|o) (w|i)\b/gi,                          "$1'$2"],
+  // Stray space before existing apostrophe
+  [/\b(\w+) '(\w)/g,                               "$1'$2"],
+]
+
+/**
+ * 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) {
+  if (!text) return ''
+  let t = text
+  t = t.replace(APOSTROPHE_VARIANTS, "'")
+  t = t.replace(QUOTE_VARIANTS, '"')
+  t = t.replace(ZERO_WIDTH, '')
+  t = t.replace(/ {2,}/g, ' ')
+  for (const [pattern, replacement] of CONTRACTION_REPAIRS) {
+    t = t.replace(pattern, replacement)
+  }
+  t = t.replace(/ {2,}/g, ' ')
+  return t.trim()
+}
+
+// ── Dialect-specific system prompts for AI calls ──────────────────────────────
+
+const DIALECT_PROMPTS = {
+  broadcast: `Use standard Welsh broadcast register (Cymraeg Byw / Living Welsh).
+Neutral between north and south — avoid strong regional markers.
+Prefer: "mae e/hi", "nawr", "hefyd", "eisiau".
+Avoid colloquialisms. Maintain formal third-person constructions.`,
+
+  north: `Use North Welsh (Gogledd Cymru) dialect conventions.
+Prefer: "mae o" (not "mae e"), "rŵan" (not "nawr"), "efo" (not "gyda"),
+"llefrith" (not "llaeth"), "fo" as pronoun, "isio" / "eisio" for "want",
+"'dan ni" for "we are", "gwatsiad" for "watching".
+Maintain natural conversational North Welsh.`,
+
+  south: `Use South Welsh (De Cymru) dialect conventions.
+Prefer: "mae e" (not "mae o"), "nawr" (not "rŵan"), "gyda" (not "efo"),
+"llaeth" (not "llefrith"), "fe" as pronoun, "moyn" for "want",
+"ni'n" for "we are", "'da ni" for "with us".
+Maintain natural conversational South Welsh.`,
+
+  formal: `Use formal written Welsh (Cymraeg ffurfiol).
+Apply correct mutations (treigladau) throughout. Use full verb forms rather than
+contractions — "rydw i" not "dwi", "dydw i ddim" not "dw i ddim".
+Avoid colloquialisms and regional markers. Use "gyda" (not "efo"), "nawr" (not "rŵan").
+Suitable for official documents, Senedd proceedings, and public sector publications.`,
+}
+
+/**
+ * Get a dialect-specific system prompt fragment for AI calls.
+ * @param {'broadcast'|'north'|'south'|'formal'} dialect
+ * @returns {string}
+ */
+export function getDialectSystemPrompt(dialect) {
+  return DIALECT_PROMPTS[dialect] || DIALECT_PROMPTS.broadcast
+}
+
+// CJS-compatible export for use in api/ (Node.js, no bundler)
+if (typeof module !== 'undefined') module.exports = { normaliseWelsh, getDialectSystemPrompt }