@capsiynau/intelligence 0.4.0 → 0.5.1

package/CHANGELOG.md

@@ -6,6 +6,81 @@ All notable changes to `@capsiynau/intelligence` go here. Format follows
 
 ## [Unreleased]
 
+## [0.5.1] - 2026-07-25
+
+**Welsh review of the 0.5.0 seed lexicon. Four of the twelve entries were
+wrong, two of them badly enough to emit ungrammatical Welsh.** Patch rather
+than minor because no consumer resolves 0.5.x yet (`notes-app` and `postio`
+are both on `^0.4.0`, and caret on a 0.x range permits patch only), so this
+corrects a defect nobody has installed.
+
+### Fixed
+
+- **`efo`/`gyda` and `isio`/`moyn` are now detect-only.** Both are genuine
+  regional pairs, but substituting them changes the grammar of the words
+  around them, and this module is mutation-blind and syntax-blind by design.
+  `gyda` takes the aspirate mutation and `efo` takes none, so the bare swap
+  gave `gyda cath` where the correct form is `gyda chath`. `moyn` takes a
+  linking `yn` and `isio` does not, so the bare swap gave `Dw i moyn`, which
+  is not grammatical. `checkDialect` still reports both; `applyDialect` now
+  skips them. Emitting broken Welsh is worse than leaving a term alone and
+  telling a human.
+- **Removed `pres`/`arian` (money) and `dŵad`/`dod` (to come).** These are not
+  regional pairs. `arian` and `dod` are the universal standard forms, used in
+  the north as readily as the south; `pres` and `dŵad` are northern
+  colloquialisms. Filing them as regional meant telling a northern writer that
+  their standard Welsh was southern. Register belongs to the prompt fragment,
+  not this table. The reason is recorded in `EXCLUDED_TERMS` so the next person
+  does not re-add them.
+
+### Added
+
+- `applySafe` on every `checkDialect` finding and every `listDialectTerms`
+  row, plus `applyNote` on detect-only entries. A caller can now tell the
+  difference between "this was corrected" and "this needs a human", rather
+  than assuming a clean `applyDialect` pass resolved everything.
+
+### Note
+
+The lexicon has now had a machine-assisted review against house style and
+known Welsh error patterns. That is **not** a native sign-off.
+`DIALECT_TERMS_STATUS.reviewed` stays `false`.
+
+## [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.1",
   "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,299 @@
+/**
+ * @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.
+ *   - Rewrite a term whose swap would change the grammar around it. Those
+ *     entries carry `applySafe: false`: checkDialect REPORTS them, applyDialect
+ *     SKIPS them. "efo" -> "gyda" is the clear case, since gyda takes the
+ *     aspirate mutation and efo takes none, so the bare swap is ungrammatical.
+ *   - Carry colloquial-versus-standard pairs. "arian" and "dod" are standard
+ *     everywhere; "pres" and "dŵad" are northern colloquialisms, not southern
+ *     opposites. That is register, and register belongs to the prompt fragment.
+ *   - 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: 'milk',        north: 'llefrith', south: 'llaeth',  neutral: 'llaeth',  gloss: 'milk' },
+  { id: 'out',         north: 'allan',   south: 'mas',      neutral: 'allan',   gloss: 'out' },
+  { 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' },
+
+  // ── Detect-only: real regional pairs, but SUBSTITUTING them changes the
+  // grammar of the surrounding words, and this module is mutation-blind and
+  // syntax-blind by design. checkDialect reports them (always safe, and it is
+  // exactly what a reviewer wants to see); applyDialect refuses to rewrite
+  // them, because a swap that produces ungrammatical Welsh is worse than no
+  // swap at all.
+  {
+    id: 'with', north: 'efo', south: 'gyda', neutral: 'gyda', gloss: 'with',
+    applySafe: false,
+    applyNote:
+      '"gyda" triggers the aspirate mutation and "efo" triggers none, so a ' +
+      'bare swap yields "gyda cath" where the correct form is "gyda chath". ' +
+      'Fixing it needs the mutation machinery this module does not have.',
+  },
+  {
+    id: 'want', north: 'isio', south: 'moyn', neutral: 'eisiau', gloss: 'to want',
+    applySafe: false,
+    applyNote:
+      'The three forms take different syntax: "Dw i isio" and "Dw i eisiau" ' +
+      'take no linking "yn", but "moyn" does ("Dw i\'n moyn"). A bare swap ' +
+      'yields "Dw i moyn", which is not grammatical.',
+  },
+]
+
+/**
+ * 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: 'colloquial-not-regional',
+    reason:
+      'Pairs like "pres"/"arian" (money) and "dŵad"/"dod" (to come) look ' +
+      'regional but are not: "arian" and "dod" are the universal standard ' +
+      'forms, used in the north as readily as the south, and "pres"/"dŵad" ' +
+      'are northern COLLOQUIAL forms. That is a register distinction, and ' +
+      'register is the prompt fragment\'s job, not this table\'s. Filing them ' +
+      'here would have told a northern writer their standard Welsh was ' +
+      'southern. Removed 25.07.2026 after review.',
+  },
+  {
+    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, applySafe: entry.applySafe !== false })
+    }
+  }
+  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, applySafe }) => ({
+    id: entry.id,
+    gloss: entry.gloss,
+    preferred,
+    alternatives,
+    applySafe,
+    // Present only on detect-only entries, so a UI can explain to the user
+    // why this one is flagged but never auto-corrected.
+    ...(entry.applyNote ? { applyNote: entry.applyNote } : {}),
+  }))
+}
+
+/**
+ * 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, applySafe } 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,
+          // false means applyDialect will NOT fix this one: the caller must
+          // hand it to a human rather than assume a rewrite resolved it.
+          applySafe,
+        })
+      }
+    }
+  }
+  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.
+ *
+ * Entries marked `applySafe: false` are SKIPPED here and reported by
+ * `checkDialect` instead. Those are pairs whose substitution would change the
+ * grammar of neighbouring words (mutation or linking "yn"), which this module
+ * has no machinery to get right. Emitting ungrammatical Welsh is worse than
+ * leaving the term alone and telling a human about it.
+ *
+ * @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, applySafe } of activeEntries(region)) {
+    if (!applySafe) continue
+    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,85 @@
+/**
+ * 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.
+ *
+ * Entries marked `applySafe: false` are SKIPPED here and reported by
+ * `checkDialect` instead. Those are pairs whose substitution would change the
+ * grammar of neighbouring words (mutation or linking "yn"), which this module
+ * has no machinery to get right. Emitting ungrammatical Welsh is worse than
+ * leaving the term alone and telling a human about it.
+ *
+ * @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;
+    applySafe?: undefined;
+    applyNote?: undefined;
+} | {
+    id: string;
+    north: string;
+    south: string;
+    neutral: string;
+    gloss: string;
+    applySafe: boolean;
+    applyNote: 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;
+}[];