@capsiynau/intelligence 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -6,6 +6,69 @@ All notable changes to `@capsiynau/intelligence` go here. Format follows
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-07-22
+
+First release to ship TypeScript declarations. Everything here is
+additive: no existing import path changes shape, so 0.3.x consumers can
+upgrade without touching their code.
+
+### Added
+
+- **`speakers` subpath.** `assessDiarisation(utterances, segments, opts)`
+  is a diarisation QUALITY GATE: it computes clipped-union coverage so
+  speech outside the transcript window cannot inflate the number,
+  suppresses labels below `minCoverage` (0.6), and suppresses a sole
+  speaker on audio longer than 90s (the classic diarisation false
+  negative, where it failed to separate voices rather than there being
+  one voice). `mapSpeakersToNames(acoustic, labelled, opts)` maps
+  anonymous "Speaker 1" labels onto real names by greatest time overlap,
+  requiring the winner to cover >= 50% of that speaker's talk time AND
+  beat the runner-up by 1.5x; ambiguous speakers stay unmapped so the
+  caller keeps the anonymous label. `clampedUnionMs` is exported for
+  callers that want the coverage primitive on its own. Pure and
+  dependency-free.
+- **`corrections/pure` subpath.** `extractProperNounCorrections(before,
+  after)` without any of Capsiynau's schema. See "Changed" below.
+- **TypeScript declarations for every subpath.** Generated from the
+  existing JSDoc into `types/` and shipped in the tarball, with per-subpath
+  `types` conditions in the `exports` map plus a top-level `types` field.
+  Consumers no longer need a hand-written ambient shim; Nodiadau's
+  `src/types/capsiynau-intelligence.d.ts` is redundant from this release
+  and can be deleted in the notes-app repo.
+  Regenerate with `npm run build:types` in `packages/intelligence`. The
+  output is committed so publishing needs no build step.
+- First unit tests for the corrections module
+  (`__tests__/corrections-pure.test.js`, 14 cases). The heuristic had
+  shipped since 0.1.0 covered only by a single smoke call in the publish
+  workflow.
+
+### Changed
+
+- **`corrections` is split into a portable half and a Capsiynau half.**
+  `extractProperNounCorrections` (a whitespace-token diff plus the
+  Title-Case proper-noun heuristic) moved to `src/corrections/pure.js`
+  and is importable as `@capsiynau/intelligence/corrections/pure`.
+  `captureCorrections` stays in `src/corrections/tracker.js`: it reads
+  `live_segments` and `live_sessions` and writes `word_boost_approved`
+  via the `bump_word_boost_approved` RPC, so it only works against
+  Capsiynau's database and is not a shared capability.
+
+  **Backwards-compatible.** `@capsiynau/intelligence/corrections` still
+  exports BOTH halves, so existing imports keep working unchanged. Only
+  a consumer importing `src/corrections/tracker.js` by deep path would
+  notice, and no published entry point allows that.
+
+  Why: an app on a different database (Postia is on a separate Supabase
+  project entirely) could not import the heuristic without inheriting
+  tables it does not have. This is the lib-versus-API rule applied:
+  pure functions of their inputs ship as library modules, anything
+  needing a database ships as an API endpoint.
+
+- JSDoc on `spellcheck/checkSentence` and `spellcheck/suggest` now
+  documents the option-bag members that were already accepted but
+  undocumented (`nspell`, `accept`, `welsh`). No behaviour change; it
+  makes the generated declarations accurate rather than `object`.
+
 ## [0.3.0] - 2026-05-19
 
 ### Fixed

package/README.md

@@ -67,14 +67,27 @@ const errors = checkSentence('Mae cymareg yn iath pwysig', {
 const fixes = suggest('cymareg', { nspell: cy, max: 6 })
 // → ['Cymraeg']
 
-// Proper-noun extraction (correction-learning heuristic)
-import { extractProperNounCorrections } from '@capsiynau/intelligence/corrections'
+// Proper-noun extraction (correction-learning heuristic). Import from
+// /corrections/pure if you want the heuristic with no Capsiynau schema
+// attached; /corrections re-exports it too.
+import { extractProperNounCorrections } from '@capsiynau/intelligence/corrections/pure'
 
 const corrections = extractProperNounCorrections(
   'Allard Perry spoke at the event',
   'Aled Parry spoke at the event',
 )
-// → ['Aled Parry']
+// → ['Aled', 'Parry']   (corrected TOKENS, not the phrase)
+
+// Diarisation quality gate: decide whether speaker labels are trustworthy
+// enough to show at all.
+import { assessDiarisation } from '@capsiynau/intelligence/speakers'
+
+const verdict = assessDiarisation(utterances, segments)
+// e.g. for a 10-minute recording that diarisation collapsed to one speaker:
+// → { reliable: false, speakerCount: 1, coverage: 0.933…, durationMs: 600000,
+//     reason: 'sole_speaker_long_audio' }
+// Suppress the labels when reliable === false. "Speaker 1" on everything
+// when four people spoke is worse than showing nothing.
 
 // And to persist into word_boost_approved (caller provides the Supabase
 // client; the package itself has zero Supabase coupling):
@@ -91,9 +104,27 @@ const persisted = await captureCorrections(before, after, { sessionId, supabase
 |--------|----------|
 | `@capsiynau/intelligence/welsh` | `normaliseWelsh`, `possibleRoots` + mutation helpers, `splitIntoLetters` + digraph utilities |
 | `@capsiynau/intelligence/spellcheck` | `checkWord`, `checkSentence`, `tokenise`, `suggest` — mutation-aware, accepts caller's nspell instance |
-| `@capsiynau/intelligence/corrections` | `extractProperNounCorrections` (pure), `captureCorrections` (accepts caller-provided Supabase client) |
+| `@capsiynau/intelligence/corrections` | Both halves below, for backwards compatibility |
+| `@capsiynau/intelligence/corrections/pure` | `extractProperNounCorrections` - portable, no database |
+| `@capsiynau/intelligence/speakers` | `assessDiarisation` (diarisation quality gate), `mapSpeakersToNames`, `clampedUnionMs` |
 | `@capsiynau/intelligence/glossary` | Glossary Builder pipeline helpers: `parse`, `prompts`, `tools`, `url`, `import`, `persist` |
 
+Every subpath ships TypeScript declarations (`types/`, generated from the
+JSDoc), so no ambient shim is needed in a TS consumer.
+
+### Portability
+
+Two exports are **Capsiynau-specific** and will not work against another
+database. They stay in the package but are not shared capabilities:
+
+- `captureCorrections` (`/corrections`) reads `live_segments` and
+  `live_sessions`, writes `word_boost_approved` via the
+  `bump_word_boost_approved` RPC. Import `/corrections/pure` instead if you
+  only want the heuristic.
+- `glossary/persist` builds rows shaped to Capsiynau's `glossaries` table.
+
+Everything else is a pure function of its inputs.
+
 ## Design
 
 - **Caller-provided dictionaries.** The package doesn't bundle nspell or

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capsiynau/intelligence",
-  "version": "0.3.0",
+  "version": "0.4.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",
@@ -27,15 +27,40 @@
     "capsiynau"
   ],
   "main": "./src/index.js",
+  "types": "./types/index.d.ts",
   "exports": {
-    ".": "./src/index.js",
-    "./welsh": "./src/welsh/index.js",
-    "./corrections": "./src/corrections/index.js",
-    "./glossary": "./src/glossary/index.js",
-    "./spellcheck": "./src/spellcheck/index.js"
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./welsh": {
+      "types": "./types/welsh/index.d.ts",
+      "default": "./src/welsh/index.js"
+    },
+    "./corrections": {
+      "types": "./types/corrections/index.d.ts",
+      "default": "./src/corrections/index.js"
+    },
+    "./corrections/pure": {
+      "types": "./types/corrections/pure.d.ts",
+      "default": "./src/corrections/pure.js"
+    },
+    "./glossary": {
+      "types": "./types/glossary/index.d.ts",
+      "default": "./src/glossary/index.js"
+    },
+    "./spellcheck": {
+      "types": "./types/spellcheck/index.d.ts",
+      "default": "./src/spellcheck/index.js"
+    },
+    "./speakers": {
+      "types": "./types/speakers/index.d.ts",
+      "default": "./src/speakers/index.js"
+    }
   },
   "files": [
     "src",
+    "types",
     "README.md",
     "SCHEMA.md",
     "CHANGELOG.md",
@@ -58,7 +83,8 @@
     "access": "public"
   },
   "scripts": {
-    "test": "vitest run __tests__"
+    "test": "vitest run __tests__",
+    "build:types": "tsc -p tsconfig.json"
   },
   "sideEffects": false
 }

package/src/corrections/index.js

@@ -1,6 +1,16 @@
 /**
  * @capsiynau/intelligence/corrections
  *
- * Public surface for the correction-learning loop.
+ * Public surface for the correction-learning loop. Re-exports BOTH
+ * halves so this import path keeps its full 0.3.0 surface:
+ *
+ *   - `./pure.js`    portable. Diff + proper-noun heuristic. No database.
+ *   - `./tracker.js` Capsiynau-specific. Reads live_sessions /
+ *                    live_segments, writes word_boost_approved.
+ *
+ * A consumer on a different schema should import
+ * `@capsiynau/intelligence/corrections/pure` instead, and get the
+ * heuristic without the schema coupling.
  */
+export * from './pure.js'
 export * from './tracker.js'

package/src/corrections/pure.js

@@ -0,0 +1,133 @@
+/**
+ * @capsiynau/intelligence/corrections/pure
+ *
+ * The PORTABLE half of the correction-learning loop: a whitespace-token
+ * diff plus a Title-Case proper-noun heuristic. Pure functions of their
+ * inputs - no database, no API key, no spend, no per-tenant state - so
+ * per the lib-versus-API rule this half is a library capability that any
+ * consuming app can import.
+ *
+ * Split out of `./tracker.js` in 0.4.0. The other half,
+ * `captureCorrections()`, reads `live_segments` / `live_sessions` and
+ * writes `word_boost_approved` via the `bump_word_boost_approved` RPC:
+ * that is Capsiynau's schema, not a shared capability, and an app on a
+ * different database cannot use it. Importing from here gets you the
+ * heuristic without inheriting any of that.
+ *
+ * `./corrections` still re-exports both halves, so existing consumers
+ * (Nodiadau's src/lib/correctionTracker.ts) keep working unchanged.
+ *
+ * Ported verbatim (TS -> JS) from Nodiadau commit 5d75dde
+ * (aledprysparry/notes-app#239). Keep parity with the Nodiadau
+ * implementation - any heuristic change here must mirror in
+ * notes-app/src/lib/correctionTracker.ts (or vice versa) or the two
+ * apps' learning behaviour silently diverges.
+ */
+
+/**
+ * Words that are *not* worth promoting even if Title-Case. Keep narrow -
+ * this is a deny-list, not a dictionary.
+ */
+const PROPER_NOUN_STOPWORDS = new Set([
+  // English filler
+  'The', 'This', 'That', 'These', 'Those', 'There', 'Their', 'They',
+  'Then', 'When', 'Where', 'What', 'Which', 'While', 'Whose', 'Whom',
+  'With', 'Without', 'About', 'Above', 'After', 'Again', 'Against',
+  'Also', 'Some', 'Such', 'Same', 'Should', 'Would', 'Could', 'Might',
+  'Have', 'Been', 'Were', 'From', 'Into', 'Onto',
+  // Welsh filler (Title-Case start-of-sentence is common in Welsh too)
+  'Mae', "Mae'r", "Mae'n", 'Dyma', 'Dyna', 'Roedd', "Roedd'r",
+  'Rwy', 'Rwyt', 'Bydd', "Bydd'r", 'Bod', 'Cael',
+  'Wedi', 'Wedyn', 'Felly', 'Ond', 'Achos', 'Ar', "Ar y",
+  'Yn', 'Mewn', 'Heb', 'Drwy', 'Drwyddo', 'Drwyddi', 'Drwyddyn',
+])
+
+const MIN_PROPER_NOUN_LENGTH = 4
+const ALPHA_ONLY = /^[\p{L}\p{M}'-]+$/u
+
+/**
+ * Tokenise on whitespace AND strip trailing punctuation per word. Keeps
+ * in-word punctuation (apostrophes, hyphens) which Welsh names need
+ * ("ap Iolo", "Tŷ'r-pol", etc.).
+ *
+ * @param {string} text
+ * @returns {string[]}
+ */
+function tokenise(text) {
+  return text
+    .trim()
+    .split(/\s+/)
+    .map((tok) => tok.replace(/^[\p{P}\p{S}]+|[\p{P}\p{S}]+$/gu, ''))
+    .filter(Boolean)
+}
+
+/**
+ * Returns true if the token looks like a name/place/brand we want to bias
+ * toward. Heuristics, not a dictionary.
+ *
+ * --- PART OF THE LANGUAGE-AGNOSTIC CONTRACT --------------------------
+ * The relay's `word_boost_approved` loader (worker/live-relay.js) reads
+ * rows from this table language-agnostically, trusting that this
+ * heuristic only matches semantically language-invariant terms (Title-
+ * Case proper nouns: personal names, brand names, place names).
+ *
+ * If you ever loosen this heuristic to also match per-language vocabulary
+ * (hyphenated compounds, lowercase acronyms, dialect markers, domain
+ * lexicon, etc.), the loader has to follow. Either:
+ *   (a) re-introduce a per-language filter on the read side, OR
+ *   (b) add a row-level `word_boost_approved.cross_language` discriminator
+ *       so the loader can decide per row (Phase 1 of notes-app#262 queues
+ *       this micro-add).
+ *
+ * Change the heuristic, change the loader.
+ * ---------------------------------------------------------------------
+ *
+ * @param {string} token
+ * @returns {boolean}
+ */
+function looksLikeProperNoun(token) {
+  if (!token || token.length < MIN_PROPER_NOUN_LENGTH) return false
+  if (!ALPHA_ONLY.test(token)) return false
+  const first = token[0]
+  // Must start with an upper-case letter
+  if (first.toUpperCase() !== first || first.toLowerCase() === first) return false
+  if (PROPER_NOUN_STOPWORDS.has(token)) return false
+  // Avoid promoting ALL-CAPS strings (likely acronyms or shouting)
+  if (token.toUpperCase() === token && token.length > 4) return false
+  return true
+}
+
+/**
+ * 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, after) {
+  const a = tokenise(before)
+  const b = tokenise(after)
+  // Skip structural changes (token count differs) - same heuristic as the
+  // 2am vocabulary-learning cron. Word-for-word swaps are the high-signal class.
+  if (a.length !== b.length || a.length === 0) return []
+  const out = new Set()
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] === b[i]) continue
+    const corrected = b[i]
+    if (looksLikeProperNoun(corrected)) out.add(corrected)
+  }
+  return Array.from(out)
+}

package/src/corrections/tracker.js

@@ -1,74 +1,59 @@
 /**
  * @capsiynau/intelligence/corrections/tracker
  *
+ * The CAPSIYNAU-PERSISTENT half of the correction-learning loop. This
+ * module is NOT portable: it reads `live_segments` and `live_sessions`
+ * and writes `word_boost_approved` via the `bump_word_boost_approved`
+ * RPC. An app on a different database cannot use it. The Supabase client
+ * is dependency-injected (0.2.0), which removed the module-alias coupling
+ * but not the schema coupling.
+ *
+ * The portable half - the diff plus the proper-noun heuristic - lives in
+ * `./pure.js` and was split out here in 0.4.0 so a consumer can import
+ * `@capsiynau/intelligence/corrections/pure` without inheriting any of
+ * Capsiynau's schema. `./index.js` re-exports both halves, so importing
+ * `@capsiynau/intelligence/corrections` still gets you everything.
+ *
  * Moved here in Phase A (see docs/intelligence-layer-phase-a.md +
  * PR #448) so Nodiadau can git-subtree this package rather than
  * maintain a hand-mirrored copy. Original path: src/lib/correctionTracker.js.
  *
- * Ported verbatim (TS → JS) from Nodiadau commit 5d75dde
- * (aledprysparry/notes-app#239) so Capsiynau Live edits feed the same
- * closed-loop vocabulary learning channel.
- *
  * When a moderator fixes a Whisper mis-recognition in the live transcript
- * (e.g. "Allard Perry" → "Aled Parry"), we want the model to recognise the
+ * (e.g. "Allard Perry" -> "Aled Parry"), we want the model to recognise the
  * corrected term next time. The Capsiynau live-relay reads
  * `word_boost_approved` for the session's org + language and injects
  * matching terms into the Whisper `prompt` parameter (PR #421).
  *
  * Flow:
- *   1. Diff the segment text before/after the edit (whitespace-tokenised).
- *   2. Find equal-length word swaps — if the lengths differ, skip; structural
- *      changes are too noisy to feed back into vocabulary biasing.
- *   3. For each swap, decide whether the corrected token looks like a proper
- *      noun worth biasing (Title-Case, ≥4 chars, not a Welsh/English
- *      start-of-sentence stopword, alphabetic-only).
- *   4. Upsert into word_boost_approved with the session's organisation_id +
- *      source_language. RLS scopes by org via get_user_org_ids() so a term
- *      never leaks into another tenant's bias.
- *
- * Keep parity with the Nodiadau implementation — any heuristic change here
- * must mirror in notes-app/src/lib/correctionTracker.ts (or vice versa) or
- * the two apps' learning behaviour silently diverges.
+ *   1. Diff the segment text before/after the edit and pick out the
+ *      proper-noun swaps worth learning (`./pure.js`).
+ *   2. Upsert them into word_boost_approved with the session's
+ *      organisation_id + source_language. RLS scopes by org via
+ *      get_user_org_ids() so a term never leaks into another tenant's bias.
  */
 
 // Phase B (2026-05-17, PR #495): the Supabase client is passed in by
 // the caller rather than imported from a Capsiynau-specific path. This
 // removes the package's only coupling to the host app's module alias
 // (`@/api/supabaseClient`) and lets Nodiadau consume captureCorrections
-// without a re-export shim. Breaking API change vs 0.1.0 — bumped to
+// without a re-export shim. Breaking API change vs 0.1.0 - bumped to
 // 0.2.0. Callers now pass `supabase` in the options bag alongside
 // `sessionId`.
 
-/**
- * Words that are *not* worth promoting even if Title-Case. Keep narrow —
- * this is a deny-list, not a dictionary.
- */
-const PROPER_NOUN_STOPWORDS = new Set([
-  // English filler
-  'The', 'This', 'That', 'These', 'Those', 'There', 'Their', 'They',
-  'Then', 'When', 'Where', 'What', 'Which', 'While', 'Whose', 'Whom',
-  'With', 'Without', 'About', 'Above', 'After', 'Again', 'Against',
-  'Also', 'Some', 'Such', 'Same', 'Should', 'Would', 'Could', 'Might',
-  'Have', 'Been', 'Were', 'From', 'Into', 'Onto',
-  // Welsh filler (Title-Case start-of-sentence is common in Welsh too)
-  'Mae', "Mae'r", "Mae'n", 'Dyma', 'Dyna', 'Roedd', "Roedd'r",
-  'Rwy', 'Rwyt', 'Bydd', "Bydd'r", 'Bod', 'Cael',
-  'Wedi', 'Wedyn', 'Felly', 'Ond', 'Achos', 'Ar', "Ar y",
-  'Yn', 'Mewn', 'Heb', 'Drwy', 'Drwyddo', 'Drwyddi', 'Drwyddyn',
-])
-
-const MIN_PROPER_NOUN_LENGTH = 4
-const ALPHA_ONLY = /^[\p{L}\p{M}'-]+$/u
+import { extractProperNounCorrections } from './pure.js'
 
 /**
  * Collapse the session's source_language to the two-bucket convention used
  * everywhere else in this repo for STT bias loading: cy-GB (any Welsh
- * variant — broadcast, north, south, formal) or en-GB (everything else,
+ * variant - broadcast, north, south, formal) or en-GB (everything else,
  * including NULL).
  *
  * Pre-this fix, this module defaulted unknown / NULL to 'cy-GB', which
  * silently routed English users' legacy-session learned vocab into the
  * Welsh bias bucket. Mirrors notes-app/src/lib/correctionTracker.ts.
+ *
+ * @param {string|null|undefined} source
+ * @returns {'cy-GB'|'en-GB'}
  */
 function normaliseLanguageBucket(source) {
   // Case-insensitive: legacy / externally-written source_language values
@@ -79,85 +64,19 @@ function normaliseLanguageBucket(source) {
   return 'en-GB'
 }
 
-/**
- * Tokenise on whitespace AND strip trailing punctuation per word. Keeps
- * in-word punctuation (apostrophes, hyphens) which Welsh names need
- * ("ap Iolo", "Tŷ'r-pol", etc.).
- */
-function tokenise(text) {
-  return text
-    .trim()
-    .split(/\s+/)
-    .map((tok) => tok.replace(/^[\p{P}\p{S}]+|[\p{P}\p{S}]+$/gu, ''))
-    .filter(Boolean)
-}
-
-/**
- * Returns true if the token looks like a name/place/brand we want to bias
- * toward. Heuristics, not a dictionary.
- *
- * ─── PART OF THE LANGUAGE-AGNOSTIC CONTRACT ──────────────────────────
- * The relay's `word_boost_approved` loader (worker/live-relay.js) reads
- * rows from this table language-agnostically, trusting that this
- * heuristic only matches semantically language-invariant terms (Title-
- * Case proper nouns: personal names, brand names, place names).
- *
- * If you ever loosen this heuristic to also match per-language vocabulary
- * (hyphenated compounds, lowercase acronyms, dialect markers, domain
- * lexicon, etc.), the loader has to follow. Either:
- *   (a) re-introduce a per-language filter on the read side, OR
- *   (b) add a row-level `word_boost_approved.cross_language` discriminator
- *       so the loader can decide per row (Phase 1 of notes-app#262 queues
- *       this micro-add).
- *
- * Change the heuristic, change the loader.
- * ─────────────────────────────────────────────────────────────────────
- */
-function looksLikeProperNoun(token) {
-  if (!token || token.length < MIN_PROPER_NOUN_LENGTH) return false
-  if (!ALPHA_ONLY.test(token)) return false
-  const first = token[0]
-  // Must start with an upper-case letter
-  if (first.toUpperCase() !== first || first.toLowerCase() === first) return false
-  if (PROPER_NOUN_STOPWORDS.has(token)) return false
-  // Avoid promoting ALL-CAPS strings (likely acronyms or shouting)
-  if (token.toUpperCase() === token && token.length > 4) return false
-  return true
-}
-
-/**
- * Compute the set of proper-noun corrections worth promoting. Exported
- * for unit tests.
- *
- * Returned terms become rows in `word_boost_approved` (per-org, with the
- * session's source_language tag). 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.
- */
-export function extractProperNounCorrections(before, after) {
-  const a = tokenise(before)
-  const b = tokenise(after)
-  // Skip structural changes (token count differs) — same heuristic as the
-  // 2am vocabulary-learning cron. Word-for-word swaps are the high-signal class.
-  if (a.length !== b.length || a.length === 0) return []
-  const out = new Set()
-  for (let i = 0; i < a.length; i++) {
-    if (a[i] === b[i]) continue
-    const corrected = b[i]
-    if (looksLikeProperNoun(corrected)) out.add(corrected)
-  }
-  return Array.from(out)
-}
-
 /**
  * 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).
+ * duplicates already in the table - upsert is silent on conflict).
  *
- * Never throws — failures are logged and swallowed so a segment-edit save
+ * 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
@@ -174,6 +93,7 @@ export function extractProperNounCorrections(before, after) {
  * @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 async function captureCorrections(before, after, { sessionId, segmentId, supabase }) {
   if (!supabase) {
@@ -225,7 +145,7 @@ export async function captureCorrections(before, after, { sessionId, segmentId,
 
   const language = normaliseLanguageBucket(segmentLanguage || sess.source_language)
 
-  // Phase 4.2 — call the SECURITY DEFINER RPC for an atomic
+  // Phase 4.2 - call the SECURITY DEFINER RPC for an atomic
   // INSERT ... ON CONFLICT DO UPDATE SET confirmed_by_count =
   // confirmed_by_count + 1, last_confirmed_at = now(). This is what makes
   // repeat confirmations of the same proper noun count toward bias
@@ -246,12 +166,12 @@ export async function captureCorrections(before, after, { sessionId, segmentId,
       p_auto_approved:   true,
     })
     if (rpcErr) {
-      // RPC not deployed on this env → bail out and fall back to upsert.
+      // RPC not deployed on this env -> bail out and fall back to upsert.
       if (rpcErr.code === 'PGRST202' || /Could not find the function/i.test(rpcErr.message || '')) {
         rpcMissing = true
         break
       }
-      // Other errors (forbidden, network) — log and skip this term.
+      // Other errors (forbidden, network) - log and skip this term.
       console.warn('[correctionTracker] bump_word_boost_approved error:', rpcErr.message)
       continue
     }