@capsiynau/intelligence 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -6,6 +6,41 @@ All notable changes to `@capsiynau/intelligence` go here. Format follows
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-07-25
+
+Additive. No existing import path changes shape, so 0.4.x consumers can
+upgrade without touching their code.
+
+### Added
+
+- **`dialect` subpath.** The Welsh regional lexicon as data rather than as a
+  prompt. `applyDialect(text, region)` rewrites off-region word choices
+  deterministically and case-preservingly ("Rŵan" to "Nawr", "mas" to
+  "allan"); `checkDialect(text, region)` reports the same findings WITHOUT
+  changing the text, so a reviewer gets evidence rather than a silent
+  rewrite; `listDialectTerms(region)` exposes the table for a management
+  screen or a sign-off export. `region` accepts the same values as
+  `getDialectSystemPrompt`, with `broadcast` and `formal` both mapping onto
+  the neutral lexicon.
+
+  This does not replace `getDialectSystemPrompt`. Register ("avoid
+  colloquialisms") has no deterministic transform and stays a prompt
+  concern; word choice does have one and should not be left to a model that
+  applies it unevenly and unverifiably. The two compose.
+
+  Deliberate limits, all pinned by tests: mutated surface forms are not
+  matched (needs syntactic context, as in `welsh/mutations.js`), pronoun and
+  copula forms are excluded because "mae o'r ardal" would be corrupted, and
+  where both regional forms are marked with no neutral standard
+  (taid/tad-cu) a neutral target leaves the text alone rather than picking a
+  side. Word boundaries use lookarounds over a Welsh letter class, not `\b`,
+  which treats the diacritic in "rŵan" as a word boundary and matches inside
+  the word.
+
+  **The seed table is not natively reviewed.** `DIALECT_TERMS_STATUS`
+  reports `reviewed: false` in code, and consumers should treat output as a
+  draft until that changes.
+
 ## [0.4.0] - 2026-07-22
 
 First release to ship TypeScript declarations. Everything here is

package/package.json

@@ -1,23 +1,24 @@
 {
   "name": "@capsiynau/intelligence",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Bilingual (Welsh + English) intelligence layer: text normalisation, mutation handling, digraph splitting, spellcheck primitives, and glossary/correction utilities. Pure functions, runs in Node or browser.",
   "type": "module",
   "license": "MIT",
   "author": "Aled Parry <aled@aledparry.com>",
-  "homepage": "https://github.com/aledprysparry/Capsiynau_V2_ClaudeAI/tree/main/packages/intelligence",
+  "homepage": "https://github.com/aledprysparry/Capsiynau.com/tree/main/packages/intelligence",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/aledprysparry/Capsiynau_V2_ClaudeAI.git",
+    "url": "git+https://github.com/aledprysparry/Capsiynau.com.git",
     "directory": "packages/intelligence"
   },
   "bugs": {
-    "url": "https://github.com/aledprysparry/Capsiynau_V2_ClaudeAI/issues"
+    "url": "https://github.com/aledprysparry/Capsiynau.com/issues"
   },
   "keywords": [
     "welsh",
     "cymraeg",
     "bilingual",
+    "dialect",
     "spellcheck",
     "mutation",
     "digraph",
@@ -56,6 +57,10 @@
     "./speakers": {
       "types": "./types/speakers/index.d.ts",
       "default": "./src/speakers/index.js"
+    },
+    "./dialect": {
+      "types": "./types/dialect/index.d.ts",
+      "default": "./src/dialect/index.js"
     }
   },
   "files": [

package/src/dialect/index.js

@@ -0,0 +1,240 @@
+/**
+ * @capsiynau/intelligence/dialect
+ *
+ * The Welsh regional LEXICON as data, not as a prompt.
+ *
+ * `welsh/normaliser.js` already exposes `getDialectSystemPrompt()`, which
+ * returns a register instruction ("avoid colloquialisms", "maintain formal
+ * third-person constructions"). Register genuinely is a prompt concern -
+ * there is no deterministic transform for "sound less formal".
+ *
+ * Word choice is not. "rŵan" versus "nawr" is a dictionary lookup, and a
+ * dictionary applied in code is right every time, costs nothing, and can be
+ * shown to a reviewer. Asked of a model in a system prompt it is applied
+ * unevenly and cannot be verified afterwards. So this module owns the lexical
+ * half and the prompt fragment keeps the register half. They compose; neither
+ * replaces the other.
+ *
+ * What this module DOES:
+ *   - `checkDialect(text, region)`  - report off-region terms, mutating nothing
+ *   - `applyDialect(text, region)`  - deterministic case-preserving substitution
+ *   - `listDialectTerms(region)`    - expose the table for review UI and export
+ *
+ * What this module does NOT do:
+ *   - Decide register, tone or formality. That is the prompt fragment's job.
+ *   - Match MUTATED surface forms. "taid" after a possessive is "daid", and
+ *     recognising that needs syntactic context, exactly as documented in
+ *     `welsh/mutations.js`. Callers normalise first or accept the miss.
+ *   - Touch pronouns or copula forms. See EXCLUDED_TERMS below; the false
+ *     positives are worse than the misses.
+ *   - Infer a region from text. The caller declares it, per the house rule
+ *     that source language and variety are never auto-detected.
+ *
+ * Pure JS, no external deps, no I/O. Runs in Node or the browser.
+ */
+
+/**
+ * Provenance for the seed table, per the "evidence beats confidence" rule:
+ * state what this data IS rather than implying an authority it has not earned.
+ * These are widely attested north/south pairs, but they are a starting seed
+ * compiled alongside the existing dialect prompt fragments - NOT a reviewed
+ * lexicographic source. A native reviewer signs this off before any consumer
+ * treats `applyDialect` output as publishable without a human read.
+ */
+export const DIALECT_TERMS_STATUS = {
+  reviewed: false,
+  reviewedBy: null,
+  seededOn: '2026-07-25',
+  note: 'Seed table. Needs native review before authoritative use.',
+}
+
+// Welsh letters, including the diacritics JS `\w` and `\b` do not cover. `\b`
+// is unusable here: to `\b` the `ŵ` in `rŵan` is a NON-word character, so
+// /\brŵan\b/ finds a boundary in the middle of the word and matches inside
+// longer tokens. Lookarounds over this class are the fix.
+const WELSH_LETTERS = "A-Za-zÂÊÎÔÛŴŶâêîôûŵŷÁÉÍÓÚáéíóúÀÈÌÒÙàèìòùÄËÏÖÜäëïöü'"
+
+/**
+ * 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: 'now',         north: 'rŵan',    south: 'nawr',     neutral: 'nawr',    gloss: 'now' },
+  { id: 'with',        north: 'efo',     south: 'gyda',     neutral: 'gyda',    gloss: 'with' },
+  { id: 'milk',        north: 'llefrith', south: 'llaeth',  neutral: 'llaeth',  gloss: 'milk' },
+  { id: 'want',        north: 'isio',    south: 'moyn',     neutral: 'eisiau',  gloss: 'to want' },
+  { id: 'out',         north: 'allan',   south: 'mas',      neutral: 'allan',   gloss: 'out' },
+  { id: 'money',       north: 'pres',    south: 'arian',    neutral: 'arian',   gloss: 'money' },
+  { id: 'to-come',     north: 'dŵad',    south: 'dod',      neutral: 'dod',     gloss: 'to come' },
+  { id: 'boy',         north: 'hogyn',   south: 'crwt',     neutral: 'bachgen', gloss: 'boy' },
+  { id: 'girl',        north: 'hogan',   south: 'croten',   neutral: 'merch',   gloss: 'girl' },
+  { id: 'cuppa',       north: 'panad',   south: 'dishgled', neutral: 'paned',   gloss: 'a cuppa' },
+  // Both forms regionally marked, no neutral standard.
+  { id: 'grandfather', north: 'taid',    south: 'tad-cu',   neutral: null,      gloss: 'grandfather' },
+  { id: 'grandmother', north: 'nain',    south: 'mam-gu',   neutral: null,      gloss: 'grandmother' },
+]
+
+/**
+ * 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: 'pronoun-o-e',
+    reason:
+      'North "mae o" / south "mae e". The north form collides with the ' +
+      'preposition "o" (from): substituting in "mae o\'r ardal" (is from the ' +
+      'area) produces nonsense. Needs part-of-speech context.',
+  },
+  {
+    id: 'up-lan',
+    reason:
+      'South "lan" (up) collides with "glan" soft-mutated to "lan" (shore), ' +
+      'so "ar lan y môr" would be rewritten. Needs mutation awareness.',
+  },
+  {
+    id: 'watching-gwatsiad',
+    reason:
+      'Appears in the north prompt fragment but is an anglicism, not a ' +
+      'north/south pair. Codifying it as regional Welsh would be wrong.',
+  },
+]
+
+// `broadcast` and `formal` both want the unmarked standard form, so they map
+// onto the same lexical target. They still differ in REGISTER, which is the
+// prompt fragment's concern, not this module's.
+const REGION_ALIASES = {
+  north: 'north',
+  south: 'south',
+  neutral: 'neutral',
+  broadcast: 'neutral',
+  formal: 'neutral',
+}
+
+/** @param {string} region @returns {'north'|'south'|'neutral'} */
+function resolveRegion(region) {
+  return REGION_ALIASES[region] || 'neutral'
+}
+
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/**
+ * Whole-term matcher. Multi-word entries ("tad-cu", and any future entry with
+ * a space) tolerate variable internal whitespace.
+ */
+function matcherFor(term) {
+  const body = escapeRegExp(term).replace(/\s+/g, '\\s+')
+  return new RegExp(`(?<![${WELSH_LETTERS}])(${body})(?![${WELSH_LETTERS}])`, 'gi')
+}
+
+/**
+ * Carry the observed capitalisation onto the replacement, so "Rŵan" becomes
+ * "Nawr" and "RŴAN" becomes "NAWR". Mixed case falls through to the table's
+ * own casing rather than guessing.
+ */
+function matchCase(observed, replacement) {
+  if (observed === observed.toUpperCase() && observed !== observed.toLowerCase()) {
+    return replacement.toUpperCase()
+  }
+  if (observed[0] === observed[0].toUpperCase()) {
+    return replacement[0].toUpperCase() + replacement.slice(1)
+  }
+  return replacement
+}
+
+/**
+ * The entries that carry a usable target for `region`, each with the forms
+ * that should be replaced by it. Entries with no neutral form are skipped for
+ * a neutral target rather than forced onto one side.
+ */
+function activeEntries(region) {
+  const resolved = resolveRegion(region)
+  const out = []
+  for (const entry of DIALECT_TERMS) {
+    const preferred = entry[resolved]
+    if (!preferred) continue
+    // Dedupe by lowercase form. Two regions often share a form (south and
+    // neutral are both "gyda"), and without this the same occurrence is
+    // reported twice by checkDialect.
+    const seen = new Set()
+    const alternatives = []
+    for (const r of ['north', 'south', 'neutral']) {
+      const form = r === resolved ? null : entry[r]
+      if (!form) continue
+      const key = form.toLowerCase()
+      if (key === preferred.toLowerCase() || seen.has(key)) continue
+      seen.add(key)
+      alternatives.push(form)
+    }
+    if (alternatives.length) out.push({ entry, preferred, alternatives })
+  }
+  return out
+}
+
+/**
+ * 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) {
+  return activeEntries(region).map(({ entry, preferred, alternatives }) => ({
+    id: entry.id,
+    gloss: entry.gloss,
+    preferred,
+    alternatives,
+  }))
+}
+
+/**
+ * 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, region) {
+  if (!text) return []
+  const findings = []
+  for (const { entry, preferred, alternatives } of activeEntries(region)) {
+    for (const alternative of alternatives) {
+      const matcher = matcherFor(alternative)
+      let hit
+      while ((hit = matcher.exec(text)) !== null) {
+        findings.push({ id: entry.id, found: hit[1], expected: preferred, index: hit.index })
+      }
+    }
+  }
+  return findings.sort((a, b) => a.index - b.index)
+}
+
+/**
+ * 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, region) {
+  if (!text) return ''
+  let out = text
+  for (const { preferred, alternatives } of activeEntries(region)) {
+    for (const alternative of alternatives) {
+      out = out.replace(matcherFor(alternative), (m) => matchCase(m, preferred))
+    }
+  }
+  return out
+}

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;
+}[];