@link-foundation/sensitive-data-sanitizer 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.15.0
+
+### Minor Changes
+
+- 7e977ac: Match known Russian names in all six cases and both word orders, with `ё`/`е` variants, initials and surname-plus-given forms. Give all case forms of one known person, organization, school or location one declined fake identity with natural names and an optional `pools` override. Keep `@handle/email` and `Name-99` organization spans whole so placeholders stay restorable and are never glued to digits. Detect employers in CV experience lines of the `documents` profile.
+
 ## 0.14.0
 
 ### Minor Changes

package/README.md

@@ -60,6 +60,10 @@ sensitive-data-sanitizer redact cv.txt --profile documents --placeholder --no-ma
 Placeholder results report `irreversibleRedactions`; a nonzero count means some
 replacements, such as credentials excluded from the map, cannot be restored.
 
+Known Russian names match in all six cases and in any word order, with `ё`/`е`
+spelling variants and initials (`с Петровым Данилом Сергеевичем`, `Петров Д. С.`).
+A part of a longer name is matched alone only when it is listed itself.
+
 For irreversible output, choose `transformation: { mode: 'placeholder', map:
 false }`: no restore map is returned or written. Detection limits still apply
 in either mode. See the [placeholder API](docs/API.md#reversible-placeholders),
@@ -144,7 +148,9 @@ See [the API](docs/API.md) and [all issue 13 requirements and research](docs/cas
 `transformation: {mode: 'fake', key}` generates deterministic names, valid
 dates/MRZs/checksummed IDs and reserved email/domain destinations. Credentials
 remain fully redacted by default. Keep the key private: this preserves relations
-and structure and is pseudonymisation. See [realistic fakes](examples/realistic-fakes.mjs)
+and structure and is pseudonymisation. Russian mentions of one known person or
+entity share one fake identity declined to match the source (`Петров … С Петровым`
+becomes `Баранов … С Барановым`), and `pools` overrides the entity names. See [realistic fakes](examples/realistic-fakes.mjs)
 and [the complete issue 24 requirements, research and solution plans](docs/case-studies/issue-24/REQUIREMENTS.md).
 
 Keep policies containing real private values outside Git. Built-in exact public knowledge and narrowly scoped role/domain heuristics are enabled offline. Explicit private literals override public exemptions. Keep custom public policies reviewed against evidence; `--verify-public` separately opts into Wikidata name lookup:

package/docs/API.md

@@ -104,6 +104,16 @@ in reverse order, and organization cores without legal forms/quotes. Inflected
 forms consume whole Unicode words; minimum stem lengths limit overmatching.
 This is conservative heuristic identity linking, not general coreference:
 ambiguous surnames/initials and unrelated people are not intentionally merged.
+
+A listed Russian PERSON value also matches all six grammatical cases, including
+the instrumental (`Петровым Данилом Сергеевичем`), every word order, `ё`/`е`
+spelling differences in either direction, upper case, and initials with or
+without spaces in both positions and all cases (`Петрову Д. С.`, `Д.С. Петрова`).
+The contiguous name parts of a listed three-part name match together
+(`Петров Данил`, `Данил Сергеевич`, `с Петровым Данилом`). A part on its own does
+not: a bare `Данил` or `Сергеевич` is too ambiguous to imply from a longer value,
+so list each part you want matched alone as its own `knownPersonal` entry. Listing
+parts next to the full name keeps one token and one fake identity.
 Every replaced occurrence retains its exact original surface privately. With
 one identical token, a derived answer cannot encode the original grammatical
 case; it receives the canonical spelling. Two distinct originals that produce
@@ -132,7 +142,7 @@ new document recognizers; `documentEntities: false` turns them off explicitly.
 | `profile`          | Off; `'publication'` sets a 0.3 threshold and identity masking; `'documents'` enables document entities                                                     |
 | `knownOnly`        | `false`; disable all automatic detection (including credentials, Secretlint and custom detectors); use only explicit known values and reused map identities |
 | `knownSecrets`     | `[]`; exact literal credential values, regardless of length or format                                                                                       |
-| `knownPersonal`    | `[]`; `{type, value}` values with whole-word Unicode case-insensitive matching and bounded Russian case forms                                               |
+| `knownPersonal`    | `[]`; `{type, value}` values with whole-word Unicode case-insensitive matching and bounded Russian forms; list parts to match them alone                    |
 | `publicEntities`   | `[]`; exact PERSON/ORGANIZATION/EDUCATION/LOCATION/EMAIL exception with HTTPS evidence and review date                                                      |
 | `findings`         | `[]`; validated detections for the original input, supplied by the caller                                                                                   |
 | `detectors`        | `[]`; additional required callbacks in the asynchronous engine                                                                                              |
@@ -205,6 +215,8 @@ All keyed modes require a key of at least 16 UTF-8 bytes. `format-preserving` is
 
 `{mode: 'fake', key}` infers name locale, script and gender from the supported gazetteer/datasets and recognizable surname/patronymic endings. Independent HMAC-seeded Faker instances make results independent of processing order. Russian Cyrillic/transliterated spelling, name order and filename separators share component identities. Ambiguous names can use a fallback locale; this is not universal name/gender inference. Dates use one keyed backward offset of 1–365 days and preserve ISO, slash and dot formats. Complete TD1/TD2/TD3 MRZs regenerate individual/composite checks and match separately faked name/date fields. Issuer/nationality remain original unless `mrzCountry: 'UTO'` is supplied. Unsupported/damaged formats fall back to full redaction.
 
+Russian mentions of one person, organization, school or location share one fake identity. The fake follows the source word order, initials, capitalization, grammatical case and, for people, sex: `Петров пришёл. Позвонили Петрову. С Петровым.` becomes `Баранов пришёл. Позвонили Баранову. С Барановым.`, and `ООО «Ромашка» … в Ромашке` becomes `ООО «Импульс» … в Импульсе`. Declension uses finite offline rules for the generated vocabulary. The grammatical case comes from the source surface and the preceding preposition, so a source preposition stays as written even where the fake would call for another spelling (`о Осипове`). Organizations, schools and locations draw from an authored Russian or Latin vocabulary according to the script of the original, skip any name that is itself private in the text, and take a numeric suffix (`Заря-2`) once the vocabulary is exhausted. Each transformation object remembers its entity names so that two entities never share one, which makes a name depend on first appearance when two entities start on the same vocabulary entry; reuse the transformation object across documents to keep names stable, and note that this memory is not shared across worker threads or processes. `pools: {ORGANIZATION: [...], LOCATION: [...], EDUCATION: [...]}` on the fake transformation replaces a vocabulary with caller-reviewed non-empty names. Autodetected mentions are linked as in placeholder mode: a mention that appears only in oblique forms can remain a separate entity unless the value is listed in `knownPersonal`.
+
 Implemented national checksums, IBANs and payment-card Luhn checks remain valid. Phones retain calling code, length and separators; NANP uses 555-0100–0199 and UK mobile uses 07700 900000–900999. Email/domain outputs use example.com/.test. Other national identities and phone numbers have no universal reserved range: generated arithmetic does not prove that a value is unassigned.
 
 Generated replacements carry `faked: true`. A private bounded registry recognizes values produced by the same transformation context as `kept: 'fake'` during later inspection/verification. Caller-supplied flags and arbitrary FAKE-looking strings grant no exemption. A fresh sanitizer does not inherit that registry; reviewed persisted fake identity values can be configured through `fakeValues`. Credentials remain fully redacted unless `credentials: true` requests provider-shaped values containing FAKE and punctuation that violates token grammar. Generated personal values cannot exempt credential spans.

package/docs/COVERAGE.md

@@ -43,7 +43,9 @@ probabilities. `minConfidence` still controls replacement. Findings retain
 their confidence even below threshold. `publicEntities` supports exact reviewed
 exceptions for all three types; `knownPersonal` always forces removal of a
 listed private value. All types support placeholder mode; fake mode uses stable,
-visibly synthetic organization/school/location labels.
+plausible organization/school/location names from an authored vocabulary or
+caller-supplied `pools`, declined to match Russian source mentions. These names
+are plausible and can coincide with real entities that the text does not mention.
 
 `src/document-vocabulary.js` is the complete authored vocabulary: English,
 Spanish, French, German, Portuguese, Russian, Japanese, Simplified/Traditional
@@ -54,6 +56,16 @@ case); they do not implement grammatical parsing. Other lowercase connectors,
 unusual typography, unsupported legal forms and unfamiliar institutions can be
 missed. Legal-form words and uncased scripts can also yield false positives.
 
+The `documents` profile also reads employers from CV experience lines anchored on
+a date range: `Title, Employer (2019-05 – 2021-03)`, `Title — Employer, 2019–2021`
+and `Title (Employer), 2019–2021`. Ranges use years, `YYYY-MM`, `MM.YYYY`, full
+dates or `month YYYY`, with `по настоящее время`, `н.в.`, `present` and similar
+open ends. Confidence is 0.60, and the employer then propagates through the
+document like other organizations. The default profile ignores these lines. Lines
+with more fields (`Title, Employer, City (dates)`) and titles containing a comma
+are not targeted and can leave the employer in place; date-anchored prose with
+the same shape can be flagged.
+
 The gazetteer has only the cities/regions explicitly listed in that module,
 including Springfield and Riverton. It is not a worldwide geocoder. Location
 labels can find unlisted proper names; unlabelled places outside the vocabulary

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-foundation/sensitive-data-sanitizer",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Offline sensitive-text sanitization with credential, multilingual personal-data and scanner union detection",
   "type": "module",
   "main": "src/index.js",

package/src/detection.js

@@ -240,11 +240,29 @@ function detectAuthorization(text, emit, credential) {
   }
 }
 
+// `/` and `|` are valid local-part characters, so `@handle/jane@example.com`
+// reads as one address that starts after `@`. A mention keeps its own finding;
+// any other leading `@` joins the address so that it cannot survive as a handle.
+function emailAfterMention(text, finding) {
+  if (
+    text[finding.start - 1] !== '@' ||
+    /[\p{L}\p{N}_.\]]/u.test(text[finding.start - 2] ?? '')
+  ) {
+    return finding;
+  }
+  const handle = /^[\p{L}\p{N}_]{2,32}[/|]/u.exec(
+    text.slice(finding.start, finding.end)
+  );
+  return handle
+    ? { ...finding, start: finding.start + handle[0].length }
+    : { ...finding, start: finding.start - 1 };
+}
+
 function detectPersonalFormats(text, options, emit) {
   collectMatches(
     text,
     /(?<![\p{L}\p{N}_.!#$%&'*+/?^`{|}~-])[\p{L}\p{N}_.!#$%&'*+/?^`{|}~-]+@[\p{L}\p{N}](?:[\p{L}\p{N}.-]{0,252})\.[\p{L}]{2,63}(?![\p{L}\p{N}_-])/gu,
-    emit,
+    (finding) => emit(emailAfterMention(text, finding)),
     { type: 'EMAIL', category: 'personal', rule: 'email' }
   );
   collectMatches(

package/src/document-entities.js

@@ -2,6 +2,7 @@ import { collectMatches, escapePattern } from './detection.js';
 import { firstNames } from './names.js';
 import { organizationCore, personalRegex } from './personal-variants.js';
 import { documentVocabulary } from './document-vocabulary.js';
+import { months } from './personal-context.js';
 
 const words = (column) =>
   [...new Set(documentVocabulary.flatMap((row) => row[column].split('|')))]
@@ -52,6 +53,32 @@ const groupOrganization = new RegExp(
   `(?<!${boundary})${latinName}[ \t]+(?:Групп|Group|Холдинг|Holding)(?!${boundary})`,
   'gu'
 );
+// CV experience lines: the date range anchors the employer slot, so prose with
+// a comma is untouched. Titles are not required to be lowercase because English
+// ones are often title case (`Senior QA Engineer`).
+const capitalized = (word) => word[0].toUpperCase() + word.slice(1);
+const month = [
+  ...new Set(months.split('|').flatMap((word) => [word, capitalized(word)])),
+].join('|');
+const rangeStart = `(?:(?:19|20)\\d{2}(?:-\\d{2}){0,2}|\\d{2}[./](?:\\d{2}\\.)?\\d{4}|(?:${month})\\.?[ \\t]+(?:19|20)\\d{2})`;
+const rangeOpen = ['по настоящее время', 'настоящее время', 'сейчас', 'н.в.']
+  .concat(['н/в', 'present', 'now', 'current'])
+  .flatMap((word) => [word, capitalized(word)])
+  .map(escapePattern)
+  .join('|');
+const range = `${rangeStart}(?:[ \\t]*[-–—][ \\t]*|[ \\t]+(?:по|to)[ \\t]+)(?:${rangeStart}|${rangeOpen})(?!${boundary})`;
+const titleWord = '[\\p{L}\\p{N}][\\p{L}\\p{N}/+#.&-]{0,39}';
+const lineTitle = `^[ \\t]*(?:[-–—•*·][ \\t]+|\\d{1,2}[.)][ \\t]+)?${titleWord}(?:[ \\t]+${titleWord}){0,5}`;
+const employerWord = "[\\p{L}\\p{M}\\p{N}&'’.+-]{1,40}";
+const employer = `«[^«»\\r\\n]{1,160}»|"[^"\\r\\n]{1,160}"|“[^“”\\r\\n]{1,160}”|(?:\\p{Lu}|\\d{1,4}-?\\p{L})${employerWord}?(?:[ \\t]+${employerWord}){0,5}`;
+const experienceLine = new RegExp(
+  `${lineTitle}(?:,[ \\t]+|[ \\t]+[-–—][ \\t]+)(${employer})(?:[ \\t]*\\(${range}\\)|[ \\t]*[,–—-][ \\t]*${range})`,
+  'gmu'
+);
+const experienceParenthesis = new RegExp(
+  `${lineTitle}[ \\t]*\\((${employer})\\)(?:,?[ \\t]*${range}|[ \\t]*\\(${range}\\))`,
+  'gmu'
+);
 
 export function detectDocumentEntities(text, emit, options) {
   if (!options.documentEntities) {
@@ -71,6 +98,8 @@ export function detectDocumentEntities(text, emit, options) {
     ['EDUCATION', 'education-type', schools, 0, 0.65],
     ['LOCATION', 'location-gazetteer', places, 0, 0.6],
     ['LOCATION', 'location-label', labelledPlace, 1, 0.75],
+    ['ORGANIZATION', 'organization-experience', experienceLine, 1, 0.6],
+    ['ORGANIZATION', 'organization-experience', experienceParenthesis, 1, 0.6],
   ]) {
     collectMatches(
       text,

package/src/fake-entities.js

@@ -0,0 +1,304 @@
+import { createHmac } from 'node:crypto';
+import { fakeName, fakeWord, wordProfile } from './fake-names.js';
+import { canonicalPerson } from './placeholders.js';
+import {
+  isGivenName,
+  isPatronymic,
+  russianNameRoles,
+} from './russian-names.js';
+import {
+  casesOf,
+  commonCase,
+  formOf,
+  governedCases,
+  russianNameForms,
+  russianNoun,
+} from './russian-declension.js';
+import {
+  organizationCore,
+  samePersonal,
+  wordPattern,
+} from './personal-variants.js';
+
+// Fictional but ordinary names. The lists are finite on purpose; callers can
+// replace them with `transformation.pools`.
+const vocabulary = {
+  ORGANIZATION: {
+    ru: 'Северный ветер|Альфа-Строй|Бета-Сервис|Гамма-Трейд|Меридиан|Горизонт|Гранит|Рассвет|Прогресс|Импульс|Орион|Азимут|Кристалл|Арсенал|Квант|Заря|Радуга|Волна|Орбита|Вершина|Искра|Тихая гавань|Новый горизонт|Белый парус|Золотой колос|Синяя птица',
+    latin:
+      'Northwind Trading|Bluebird Logistics|Silver Birch Partners|Harbor Lane Studio|Summit Ridge Supply|Clearwater Works|Redwood Systems|Maple Street Foods',
+  },
+  LOCATION: {
+    ru: 'Зареченск|Приморск|Светлогорск|Лесногорск|Березовка|Сосновка|Каменка|Покровка|Ольховка|Заречье|Краснополье',
+    latin: 'Riverton|Oakdale|Fairview|Lakewood|Brookfield|Greenville|Ashford',
+  },
+  EDUCATION: {
+    ru: 'Северный государственный университет|Приморский технический институт|Лесногорский гуманитарный университет|Зареченский экономический колледж|Светлогорская городская школа',
+    latin:
+      'Riverside University|Lakeview College|Oakdale Institute of Technology|Fairview State University',
+  },
+};
+const cyrillic = /\p{Script=Cyrillic}/u;
+const surfacesKey = Symbol('fakeSurfaces');
+const textKey = Symbol('fakeText');
+const surfaceLimit = 1000;
+
+// Lets each span see the other mentions of its document, as placeholders do.
+export function prepareFakeText(text, findings, options) {
+  const surfaces = new Map();
+  for (const finding of findings) {
+    if (
+      ['PERSON', 'ORGANIZATION', 'LOCATION', 'EDUCATION'].includes(finding.type)
+    ) {
+      const values = surfaces.get(finding.type) ?? new Set();
+      if (values.size < surfaceLimit) {
+        values.add(text.slice(finding.start, finding.end));
+      }
+      surfaces.set(finding.type, values);
+    }
+  }
+  return { ...options, [surfacesKey]: surfaces, [textKey]: text };
+}
+const wordCount = (value) => value.trim().split(/\s+/u).length;
+// The fullest form this mention belongs to, or the mention itself.
+function entityLemma(value, type, options) {
+  const known = [
+    ...(options.knownPersonal ?? []),
+    ...(options.confirmedPersonal ?? []),
+  ]
+    .filter((entry) => entry.type === type)
+    .map((entry) => entry.value);
+  const mentions = [...(options[surfacesKey]?.get(type) ?? [])];
+  for (const group of [known, mentions]) {
+    const matches = group.filter((other) => samePersonal(value, other, type));
+    const longest = Math.max(0, ...matches.map(wordCount));
+    const fullest = [
+      ...new Set(matches.filter((other) => wordCount(other) === longest)),
+    ];
+    // `Гранит` covers its own form `Граните`, so several forms share one lemma.
+    const lemma = fullest.filter((other) =>
+      fullest.every((form) => samePersonal(form, other, type))
+    );
+    if (lemma.length === 1) {
+      return lemma[0];
+    }
+  }
+  return type === 'PERSON' ? canonicalPerson(value, mentions) : value;
+}
+
+const applyStyle = (surface, output) =>
+  surface.length > 1 && surface === surface.toUpperCase()
+    ? output.toUpperCase()
+    : surface === surface.toLowerCase()
+      ? output.toLowerCase()
+      : output;
+const capitalize = (word) =>
+  word[0].toUpperCase() + word.slice(1).toLowerCase();
+function nameSlots(parts) {
+  const roles = russianNameRoles(parts);
+  if (roles) {
+    return parts.map((_part, i) =>
+      i === roles.surname
+        ? 'lastName'
+        : i === roles.patronymic
+          ? 'middleName'
+          : 'firstName'
+    );
+  }
+  if (parts.length === 1) {
+    return [wordProfile(parts[0]).role];
+  }
+  const given = parts.map((part) => isGivenName(part));
+  if (parts.length === 2 && given[0] !== given[1]) {
+    return given.map((isGiven) => (isGiven ? 'firstName' : 'lastName'));
+  }
+  return parts.map((_part, i) =>
+    i === 0 ? 'firstName' : i === parts.length - 1 ? 'lastName' : 'middleName'
+  );
+}
+function nameSex(parts, slots) {
+  const at = (slot) => parts[slots.indexOf(slot)];
+  const middle = at('middleName');
+  if (middle && (isPatronymic(middle) || /(?:вна|чна)$/iu.test(middle))) {
+    return /(?:вна|чна)$/iu.test(middle) ? 'female' : 'male';
+  }
+  const last = at('lastName');
+  if (last && /(?:ова|ева|ёва|ина|ына|ая|яя)$/iu.test(last)) {
+    return 'female';
+  }
+  if (last && /(?:ов|ев|ёв|ин|ын|ий|ой|ый)$/iu.test(last)) {
+    return 'male';
+  }
+  return wordProfile(at('firstName') ?? parts[0]).sex;
+}
+const letters = /[\p{L}\p{M}]+/gu;
+// One identity per lemma: each lemma word has one seeded fake, and the matched
+// surface only decides its case, its order and its letter case.
+function russianFakeName(surface, lemma, key, context) {
+  const parts = lemma.trim().split(/\s+/u);
+  const slots = nameSlots(parts);
+  const sex = nameSex(parts, slots);
+  const lemmaWords = parts.flatMap((part, i) =>
+    part.match(letters).map((word) => {
+      const slot = slots[i];
+      return {
+        slot,
+        lemmaForms: russianNameForms(word, slot, sex),
+        pattern: new RegExp(`^(?:${wordPattern(word, 'PERSON')})$`, 'iu'),
+        first: word[0].toLowerCase().replace('ё', 'е'),
+        fake: fakeWord(capitalize(word), key, slot, undefined, sex),
+      };
+    })
+  );
+  const matched = surface.match(letters).map((word) => {
+    const initial = word.length === 1;
+    const entry = lemmaWords.find(
+      (candidate) =>
+        !candidate.used &&
+        (initial
+          ? candidate.slot !== 'lastName' &&
+            candidate.first === word.toLowerCase().replace('ё', 'е')
+          : candidate.pattern.test(word))
+    );
+    if (entry) {
+      entry.used = true;
+    }
+    return { word, entry, initial };
+  });
+  const index = commonCase(
+    matched
+      .filter(({ entry, initial }) => entry && !initial)
+      .map(({ word, entry }) => casesOf(word, entry.lemmaForms)),
+    context
+  );
+  let position = 0;
+  return surface.replace(letters, () => {
+    const { word, entry, initial } = matched[position++];
+    if (!entry) {
+      return fakeWord(word, key);
+    }
+    if (initial) {
+      return entry.fake[0].toUpperCase();
+    }
+    const forms = russianNameForms(entry.fake, entry.slot, sex);
+    return applyStyle(word, capitalize(formOf(forms, index)));
+  });
+}
+const contextOf = (finding, options) =>
+  governedCases(options[textKey] ?? '', finding.start);
+export function fakePerson(value, finding, transform, options) {
+  const lemma = entityLemma(value, 'PERSON', options);
+  return cyrillic.test(lemma) &&
+    cyrillic.test(value) &&
+    !/\p{Script=Latin}/u.test(`${lemma}${value}`)
+    ? russianFakeName(value, lemma, transform.key, contextOf(finding, options))
+    : fakeName(value, transform.key);
+}
+
+const assigned = new WeakMap();
+const lemmaKey = (core) => core.toLowerCase().replaceAll('ё', 'е');
+const poolFor = (type, core, transform) =>
+  transform.pools?.[type] ??
+  vocabulary[type][cyrillic.test(core) ? 'ru' : 'latin'].split('|');
+function isReal(candidate, type, options) {
+  return [
+    ...(options.knownPersonal ?? []),
+    ...(options.confirmedPersonal ?? []),
+    ...[...(options[surfacesKey]?.get(type) ?? [])].map((value) => ({
+      type,
+      value,
+    })),
+  ].some(
+    (entry) => entry.type === type && samePersonal(candidate, entry.value, type)
+  );
+}
+// A deterministic start, then the next free name so that two entities of one
+// run never share a fake. An exhausted list continues with numbered names.
+function assignFake(core, type, transform, options) {
+  let state = assigned.get(transform);
+  if (!state) {
+    state = new Map();
+    assigned.set(transform, state);
+  }
+  const entityKey = `${type}\0${lemmaKey(core)}`;
+  if (state.has(entityKey)) {
+    return state.get(entityKey);
+  }
+  const taken = new Set(state.values());
+  const pool = poolFor(type, core, transform);
+  const start = createHmac('sha256', transform.key)
+    .update(`entity\0${entityKey}`)
+    .digest()
+    .readUInt32BE(0);
+  for (let attempt = 0; ; attempt++) {
+    const name = pool[(start + attempt) % pool.length];
+    const round = Math.floor(attempt / pool.length);
+    const candidate = round ? `${name}-${round + 1}` : name;
+    if (!taken.has(candidate) && !isReal(candidate, type, options)) {
+      state.set(entityKey, candidate);
+      return candidate;
+    }
+  }
+}
+const nounOptions = (word, phrase, position) => ({
+  animate: false,
+  sex: phrase.some((other) => /[ая]я$/u.test(other)) ? 'female' : undefined,
+  adjective:
+    !word.includes('-') &&
+    (/(?:ый|ая|яя)$/u.test(word) ||
+      (/(?:ий|ой|ое|ее)$/u.test(word) && position < phrase.length - 1)),
+});
+// Only the last part of a hyphenated name declines: в Альфа-Строе.
+const phraseForms = (phrase) => {
+  const words = phrase.toLowerCase().split(/\s+/u);
+  return words.map((word, position) => {
+    const head = word.slice(0, word.lastIndexOf('-') + 1);
+    const tail = word.slice(head.length);
+    return {
+      head,
+      forms: russianNoun(tail, nounOptions(word, words, position)),
+    };
+  });
+};
+function phraseCase(surface, lemma, context) {
+  const words = surface.split(/\s+/u);
+  const lemmaForms = phraseForms(lemma);
+  if (words.length !== lemmaForms.length) {
+    return 0;
+  }
+  return commonCase(
+    words.map((word, i) =>
+      casesOf(word.slice(word.lastIndexOf('-') + 1), lemmaForms[i].forms)
+    ),
+    context
+  );
+}
+function declinedPhrase(phrase, index) {
+  if (!cyrillic.test(phrase)) {
+    return phrase;
+  }
+  const original = phrase.split(/\s+/u);
+  return phraseForms(phrase)
+    .map(({ head, forms }, i) => {
+      const word = head + formOf(forms, index);
+      return original[i][0] === original[i][0].toUpperCase()
+        ? word.replace(
+            /(^|-)(\p{L})/gu,
+            (_m, gap, letter) => `${gap}${letter.toUpperCase()}`
+          )
+        : word;
+    })
+    .join(' ');
+}
+const decoration = /^((?:(?:ООО|АО|ПАО|ИП|ЗАО)[ \t]+)?[«“"]?)(.*?)([»”"]?)$/su;
+// `ООО «Ромашка»` keeps its legal form and quotes; only the name is replaced.
+export function fakeEntity(value, finding, transform, options) {
+  const { type } = finding;
+  const [, before, core, after] = decoration.exec(value);
+  const lemma = organizationCore(entityLemma(value, type, options));
+  const fake = assignFake(lemma, type, transform, options);
+  const output = cyrillic.test(core)
+    ? declinedPhrase(fake, phraseCase(core, lemma, contextOf(finding, options)))
+    : fake;
+  return `${before}${applyStyle(core, output)}${after}`;
+}

package/src/fake-names.js

@@ -213,7 +213,8 @@ export function fakeName(value, key) {
     return fakeWord(word, key, roles.get(word), undefined, nameSex);
   });
 }
-function wordProfile(word, forcedRole, forcedLocale) {
+export function wordProfile(word, forcedRole, forcedLocale) {
+  indexNames();
   const canonical = latinName(word);
   const patronymic = /(?:vich|vna|ichna|ogly|kyzy)$/.test(canonical);
   const slavic = /(?:ova|eva|ov|ev|in|ina|enko|sky|ski|skaya)$/.test(canonical);
@@ -240,7 +241,7 @@ function wordProfile(word, forcedRole, forcedLocale) {
         : 'lastName');
   return { canonical, locale, sex, role };
 }
-function fakeWord(word, key, forcedRole, forcedLocale, forcedSex) {
+export function fakeWord(word, key, forcedRole, forcedLocale, forcedSex) {
   const {
     canonical,
     locale,

package/src/fake.js

@@ -1,3 +1,4 @@
+import { fakeEntity, fakePerson } from './fake-entities.js';
 import { createHmac } from 'node:crypto';
 import { parsePhoneNumberFromString } from 'libphonenumber-js/max';
 import { mrzCheck } from './identity.js';
@@ -487,7 +488,7 @@ function fakeTd1(parts, transform) {
     .padEnd(30, '<');
   return parts.join('');
 }
-export function realisticFake(value, finding, transform) {
+export function realisticFake(value, finding, transform, options = {}) {
   let output;
   if (finding.category === 'credential') {
     if (!transform.credentials) {
@@ -500,14 +501,9 @@ export function realisticFake(value, finding, transform) {
       .toString('hex')
       .slice(0, 8)}!`;
   } else if (finding.type === 'PERSON') {
-    output = fakeName(value, transform.key);
+    output = fakePerson(value, finding, transform, options);
   } else if (['ORGANIZATION', 'EDUCATION', 'LOCATION'].includes(finding.type)) {
-    const label = {
-      ORGANIZATION: 'Organization',
-      EDUCATION: 'School',
-      LOCATION: 'Location',
-    }[finding.type];
-    output = `Example ${label} ${digest(value, transform.key, finding.type).readUInt32BE(0)}`;
+    output = fakeEntity(value, finding, transform, options);
   } else if (/DATE|BIRTH/.test(finding.type)) {
     output = fakeDate(value, transform.key);
   } else if (finding.type === 'PASSPORT_MRZ') {

package/src/index.d.ts

@@ -250,6 +250,10 @@ export type Transformation =
       credentials?: boolean;
       /** Keep original MRZ issuer/nationality unless Utopia is requested. */
       mrzCountry?: 'UTO';
+      /** Caller-reviewed names that replace the generated entity vocabulary. */
+      pools?: Partial<
+        Record<'ORGANIZATION' | 'LOCATION' | 'EDUCATION', string[]>
+      >;
     }
   | { mode: 'date-shift'; days: number }
   | { mode: 'bucket'; size: number };

package/src/personal-context.js

@@ -2,7 +2,7 @@ import { collectMatches } from './detection.js';
 
 const birth =
   /(?<![\p{L}\p{N}_])(?:born|birth[ _-]?date|date[ _-]of[ _-]birth|DOB|дата рождения|д\.р\.|родился|родилась|Geburtsdatum|fecha de nacimiento|date de naissance)(?![\p{L}\p{N}_])/giu;
-const months =
+export const months =
   'January February March April May June July August September October November December Jan Feb Mar Apr Jun Jul Aug Sep Sept Oct Nov Dec января февраля марта апреля мая июня июля августа сентября октября ноября декабря январь февраль март апрель май июнь июль август сентябрь октябрь ноябрь декабрь'
     .split(' ')
     .join('|');

package/src/personal-variants.js

@@ -1,4 +1,5 @@
 import { escapePattern, failure } from './detection.js';
+import { russianNameRoles } from './russian-names.js';
 
 const boundary = '[\\p{L}\\p{M}\\p{N}_]';
 export function organizationCore(value) {
@@ -7,9 +8,26 @@ export function organizationCore(value) {
     .replace(/^[«“"]|[»”"]$/gu, '')
     .trim();
 }
+// `Вектор-1` also identifies its base name and numbered siblings like `Вектор-2`.
+export function organizationFamily(core) {
+  const base = /^(.{3,})-\d{1,9}$/u.exec(core)?.[1];
+  return base
+    ? {
+        base,
+        pattern: new RegExp(
+          `(?<!${boundary})${escapePattern(base)}(?:-\\d{1,9})?(?!${boundary}|-\\d)`,
+          'giu'
+        ),
+      }
+    : undefined;
+}
+// ё and е are one letter in ordinary Russian writing; the i flag covers Ё and Е.
+const foldYo = (pattern) => pattern.replace(/[еёЕЁ]/gu, '[её]');
+const fleeting = { павел: 'Павл', лев: 'Льв' };
+const hardCases = '(?:а|у|ом|е)';
 // Only caller-confirmed Russian words receive finite case alternatives. A
 // minimum three-letter stem avoids turning short names into broad matches.
-function wordPattern(word) {
+function cyrillicPattern(word, type) {
   const endings = [
     [/(?:ова|ева|ина)$/u, 1, '(?:а|ой|ою|у|е|ы)'],
     [/(?:ая)$/u, 2, '(?:ая|ой|ою|ую)'],
@@ -18,24 +36,76 @@ function wordPattern(word) {
       2,
       '(?:ий|ый|ой|ого|его|ому|ему|им|ым|ом|ем|ия|ию|ием|ии)',
     ],
+    [/[аеуюя]й$/u, 1, '(?:й|я|ю|ем|е)'],
     [/(?:ов|ев|ин)$/u, 0, '(?:а|у|ым|ом|е|ой)?'],
+    [/[жчшщц]$/u, 0, '(?:а|у|ем|ом|е)?'],
+    [/[жчшщц]а$/u, 1, '(?:а|и|е|у|ей|ею|ой|ою)'],
     [/а$/u, 1, '(?:а|ы|и|е|у|ой|ою)'],
     [/я$/u, 1, '(?:я|и|е|ю|ей|ею)'],
-    [/ь$/u, 1, '(?:ь|я|ю|ем|и)'],
+    [/ь$/u, 1, '(?:ь|я|ю|ем|е|и|ью)'],
   ];
   const lower = word.toLowerCase();
-  if (/^[а-яё]+$/u.test(lower)) {
-    for (const [ending, remove, suffix] of endings) {
-      if (ending.test(lower) && word.length - remove >= 3) {
-        return escapePattern(remove ? word.slice(0, -remove) : word) + suffix;
-      }
+  if (fleeting[lower]) {
+    return `(?:${word}|${fleeting[lower]}${hardCases})`;
+  }
+  for (const [ending, remove, suffix] of endings) {
+    if (ending.test(lower) && word.length - remove >= 3) {
+      return escapePattern(remove ? word.slice(0, -remove) : word) + suffix;
     }
   }
-  if (/^[а-яё]{4,}[бвгджзклмнпрстфхцчшщ]$/u.test(lower)) {
-    return `${escapePattern(word)}(?:а|у|ом|е|ы|ов|ам|ами|ах)?`;
+  if (/^[а-яё]{3,}[бвгджзклмнпрстфхцчшщ]$/u.test(lower)) {
+    // Plural forms would turn a given name into a surname: Петр and Петров.
+    return `${escapePattern(word)}${type === 'PERSON' ? `${hardCases}?` : '(?:а|у|ом|е|ы|ов|ам|ами|ах)?'}`;
   }
   return escapePattern(word);
 }
+export function wordPattern(word, type) {
+  return foldYo(
+    word
+      .split('-')
+      .map((part) =>
+        /^[а-яё]+$/iu.test(part)
+          ? cyrillicPattern(part, type)
+          : escapePattern(part)
+      )
+      .join('-')
+  );
+}
+const initialGap = '[ \\t\\u00a0]*';
+const initialPattern = (word) => `${foldYo(escapePattern(word[0]))}\\.`;
+// Everyday orders, partial forms and initials of a Russian full name, longest
+// first so that alternation prefers the complete form at each position.
+function russianForms(words, roles, type) {
+  const name = Object.fromEntries(
+    Object.entries(roles).map(([role, i]) => [role, words[i]])
+  );
+  const gap = '[ \\t]+';
+  const full = (...parts) =>
+    parts.map((part) => wordPattern(part, type)).join(gap);
+  if (name.surname === undefined) {
+    return [];
+  }
+  const initial = initialPattern(name.given);
+  const last = wordPattern(name.surname, type);
+  const short = [
+    full(name.surname, name.given),
+    full(name.given, name.surname),
+    `${last}${gap}${initial}`,
+    `${initial}[ \\t\\u00a0]+${last}`,
+  ];
+  if (name.patronymic === undefined) {
+    return short;
+  }
+  const initials = `${initial}${initialGap}${initialPattern(name.patronymic)}`;
+  return [
+    full(name.surname, name.given, name.patronymic),
+    full(name.given, name.patronymic, name.surname),
+    `${last}[ \\t\\u00a0]+${initials}`,
+    `${initials}[ \\t\\u00a0]+${last}`,
+    ...short,
+    full(name.given, name.patronymic),
+  ];
+}
 export function personalPatterns(value, type) {
   if (value.length > 256) {
     // Large explicit values still support literal matching without expansion.
@@ -52,13 +122,22 @@ export function personalPatterns(value, type) {
   for (const surface of values) {
     const parts = surface.split(/([ \t]+)/u);
     const pattern = parts
-      .map((part, i) => (i % 2 ? '[ \\t]+' : wordPattern(part)))
+      .map((part, i) => (i % 2 ? '[ \\t]+' : wordPattern(part, type)))
       .join('');
     patterns.add(pattern);
-    if (type === 'PERSON' && parts.length === 3) {
-      patterns.add(
-        [wordPattern(parts[2]), wordPattern(parts[0])].join('[ \\t]+')
-      );
+    if (type === 'PERSON') {
+      const words = parts.filter((_part, i) => i % 2 === 0);
+      const roles = russianNameRoles(words);
+      for (const form of roles ? russianForms(words, roles, type) : []) {
+        patterns.add(form);
+      }
+      if (words.length === 2) {
+        patterns.add(
+          [wordPattern(words[1], type), wordPattern(words[0], type)].join(
+            '[ \\t]+'
+          )
+        );
+      }
     }
   }
   return [...patterns];
@@ -77,18 +156,29 @@ export function samePersonal(value, original, type) {
 export function detectKnownPersonal(text, entries, rule, emit, options) {
   let count = 0;
   for (const entry of entries ?? []) {
-    for (const match of text.matchAll(personalRegex(entry.value, entry.type))) {
-      if (++count > (options.maxFindings ?? 100000)) {
-        throw failure('ERR_LIMIT');
+    const family =
+      rule === 'confirmed-personal' &&
+      options.documentEntities &&
+      !options.knownOnly &&
+      entry.type === 'ORGANIZATION' &&
+      organizationFamily(organizationCore(entry.value));
+    for (const pattern of [
+      personalRegex(entry.value, entry.type),
+      ...(family ? [family.pattern] : []),
+    ]) {
+      for (const match of text.matchAll(pattern)) {
+        if (++count > (options.maxFindings ?? 100000)) {
+          throw failure('ERR_LIMIT');
+        }
+        emit({
+          start: match.index,
+          end: match.index + match[0].length,
+          type: entry.type,
+          category: 'personal',
+          rule,
+          confidence: rule === 'known-personal' ? 0.85 : 0.9,
+        });
       }
-      emit({
-        start: match.index,
-        end: match.index + match[0].length,
-        type: entry.type,
-        category: 'personal',
-        rule,
-        confidence: rule === 'known-personal' ? 0.85 : 0.9,
-      });
     }
   }
 }

package/src/personal.js

@@ -29,6 +29,9 @@ const ibanLengths = Object.fromEntries(
     .map((entry) => [entry.slice(0, 2), Number(entry.slice(2))])
 );
 
+// `@handle/jane@example.com` is a mention and an address, not a package path.
+const mentionedEmail =
+  /^\/[\p{L}\p{N}_.!#$%&'*+?^`{|}~-]+@[\p{L}\p{N}][\p{L}\p{N}.-]{0,252}\.\p{L}{2,63}(?![\p{L}\p{N}_-])/u;
 export function iban(value) {
   const compact = value.replace(/\s/g, '').toUpperCase();
   if (
@@ -207,10 +210,11 @@ export function detectPersonal(text, emit) {
   }
   collectMatches(
     text,
-    /(?:компании|организации|company|organization|société|empresa|Firma)[ \t]+([\p{Lu}][\p{L}\p{M}&'-]{1,80})/gu,
+    /(?:компании|организации|company|organization|société|empresa|Firma)[ \t]+([\p{Lu}][\p{L}\p{M}&']{0,80}(?:-[\p{L}\p{M}\p{N}&']{1,40}){0,4})/gu,
     emit,
     details('ORGANIZATION', 'organization-context', 0.7),
-    1
+    1,
+    (value) => value.length >= 2
   );
   collectMatches(
     text,
@@ -236,10 +240,12 @@ export function detectPersonal(text, emit) {
     emit,
     details('USERNAME', 'messenger-handle', 0.65),
     0,
-    (_value, match) =>
-      !/^\/[a-z0-9][a-z0-9_.-]*/i.test(
-        text.slice(match.index + match[0].length)
-      )
+    (_value, match) => {
+      const rest = text.slice(match.index + match[0].length);
+      return (
+        !/^\/[a-z0-9][a-z0-9_.-]*/i.test(rest) || mentionedEmail.test(rest)
+      );
+    }
   );
   collectMatches(
     text,

package/src/placeholders.js

@@ -107,6 +107,14 @@ function aliases(value, type) {
     ),
   ];
 }
+// A bare name is the same entity as its numbered form, including maps saved
+// when the span stopped at the hyphen of `Вектор-99`.
+function numberedOrganization(value, entry) {
+  return (entry.values ?? []).some((original) => {
+    const base = original.replace(/-\d*$/u, '');
+    return base !== original && samePersonal(value, base, entry.type);
+  });
+}
 function related(value, entry) {
   if (
     (entry.values ?? []).some((original) =>
@@ -119,6 +127,9 @@ function related(value, entry) {
   if (candidates.some((alias) => entry.aliases.includes(alias))) {
     return true;
   }
+  if (entry.type === 'ORGANIZATION') {
+    return numberedOrganization(value, entry);
+  }
   if (entry.type !== 'PERSON') {
     return false;
   }
@@ -257,7 +268,7 @@ function namespaceCollision(text, pattern) {
   return false;
 }
 
-function canonicalPerson(value, people) {
+export function canonicalPerson(value, people) {
   // Resolve components only when there is a unique compatible full name.
   const matches = people.filter((person) => {
     const words = person.match(/\p{L}+/gu) ?? [];
@@ -279,8 +290,11 @@ function canonicalKnown(value, type, options, state) {
   const known = (options.knownPersonal ?? []).filter(
     (e) => e.type === type && samePersonal(value, e.value, type)
   );
-  if (known.length === 1) {
-    return known[0].value;
+  // `Петров Данил` and `Петров Данил Сергеевич` are one person: the fullest wins.
+  const longest = Math.max(0, ...known.map((e) => e.value.length));
+  const fullest = known.filter((e) => e.value.length === longest);
+  if (fullest.length === 1) {
+    return fullest[0].value;
   }
   return type === 'PERSON' ? canonicalPerson(value, state.people ?? []) : value;
 }
@@ -303,7 +317,12 @@ export function placeholderReplacement(value, finding, transform, options) {
   const candidates = map.entries.filter(
     (entry) => entry.type === type && related(canonical, entry)
   );
-  let entry = candidates.length === 1 ? candidates[0] : undefined;
+  // Several related entities are ambiguous, unless one holds this exact value.
+  const exact = candidates.filter((entry) =>
+    entry.values.some((original) => samePersonal(canonical, original, type))
+  );
+  const matches = candidates.length === 1 ? candidates : exact;
+  let entry = matches.length === 1 ? matches[0] : undefined;
   if (!entry) {
     if (map.entries.length >= (options.maxFindings ?? 100000)) {
       throw failure('ERR_LIMIT');

package/src/propagation.js

@@ -1,6 +1,6 @@
 import { personalPattern, maxPropagationLength, failure } from './detection.js';
 import { actionable } from './confidence.js';
-import { organizationCore } from './personal-variants.js';
+import { organizationCore, organizationFamily } from './personal-variants.js';
 import { nameAliases } from './transliteration.js';
 
 function mrzSeeds(value, finding, seeds) {
@@ -50,12 +50,16 @@ function eligibleSeed(finding, options) {
       ].includes(finding.type))
   );
 }
-function organizationSeed(value, finding, seeds, options) {
+function organizationSeed(text, value, finding, seeds, options) {
   if (options.documentEntities && finding.type === 'ORGANIZATION') {
     const core = organizationCore(value);
     if (core.length >= 3) {
       seeds.set(core, finding);
     }
+    const family = organizationFamily(core);
+    for (const match of family ? text.matchAll(family.pattern) : []) {
+      seeds.set(match[0], finding);
+    }
   }
 }
 // Only confirmed values seed propagation. A low-score numeric coincidence
@@ -82,7 +86,7 @@ export function confirmedSeeds(text, findings, options) {
       mrzSeeds(value, finding, seeds);
     } else if (value.length >= 2) {
       seeds.set(value, finding);
-      organizationSeed(value, finding, seeds, options);
+      organizationSeed(text, value, finding, seeds, options);
       if (finding.type === 'PERSON') {
         for (const name of value.match(/\p{L}{2,}/gu) ?? []) {
           seeds.set(name, finding);

package/src/russian-declension.js

@@ -0,0 +1,167 @@
+// Finite Russian declension shared by fake names and fake entities. Case order:
+// nominative, genitive, dative, accusative, instrumental, prepositional.
+// `|` lists a rarer spelling, accepted when reading a form, never generated.
+const fleeting = { павел: 'павл', лев: 'льв', ветер: 'ветр' };
+const hush = /[жчшщц]$/u;
+const a = (stem) => [
+  'а',
+  /[гкхжчшщ]$/u.test(stem) ? 'и' : 'ы',
+  'е',
+  'у',
+  /[жчшщц]$/u.test(stem) ? 'ей|ею' : 'ой|ою',
+  'е',
+];
+const adjectives = [
+  [
+    /[ый]й$|ой$/u,
+    2,
+    (w) => [w.slice(-2), 'ого', 'ому', w.slice(-2), 'ым', 'ом'],
+  ],
+  [/[кгхжчшщ]ий$/u, 2, () => ['ий', 'ого', 'ому', 'ий', 'им', 'ом']],
+  [/ий$/u, 2, () => ['ий', 'его', 'ему', 'ий', 'им', 'ем']],
+  [/ая$/u, 2, () => ['ая', 'ой', 'ой', 'ую', 'ой|ою', 'ой']],
+  [/яя$/u, 2, () => ['яя', 'ей', 'ей', 'юю', 'ей|ею', 'ей']],
+  [/ое$/u, 2, () => ['ое', 'ого', 'ому', 'ое', 'ым', 'ом']],
+  [/ее$/u, 2, () => ['ее', 'его', 'ему', 'ее', 'им', 'ем']],
+];
+function noun(word, sex, animate) {
+  const accusative = (genitive, nominative = '') =>
+    animate ? genitive : nominative;
+  if (fleeting[word]) {
+    const hard = ['а', 'у', accusative('а'), 'ом', 'е'];
+    return [word, ...hard.map((ending) => fleeting[word] + ending)];
+  }
+  const table = [
+    [/ия$/u, 2, ['ия', 'ии', 'ии', 'ию', 'ией|иею', 'ии']],
+    [/ье$/u, 2, ['ье', 'ья', 'ью', 'ье', 'ьем', 'ье']],
+    [/ие$/u, 2, ['ие', 'ия', 'ию', 'ие', 'ием', 'ии']],
+    [/ий$/u, 2, ['ий', 'ия', 'ию', accusative('ия', 'ий'), 'ием', 'ии']],
+    [/й$/u, 1, ['й', 'я', 'ю', accusative('я', 'й'), 'ем', 'е']],
+    [/я$/u, 1, ['я', 'и', 'е', 'ю', 'ей|ею', 'е']],
+    [/а$/u, 1, a(word.slice(0, -1))],
+    [/о$/u, 1, ['о', 'а', 'у', 'о', 'ом', 'е']],
+  ];
+  for (const [ending, remove, cases] of table) {
+    if (ending.test(word)) {
+      return cases.map((suffix) => attach(word.slice(0, -remove), suffix));
+    }
+  }
+  if (word.endsWith('ь')) {
+    const stem = word.slice(0, -1);
+    const feminine = ['ь', 'и', 'и', 'ь', 'ью', 'и'];
+    const masculine = ['ь', 'я', 'ю', accusative('я', 'ь'), 'ем', 'е'];
+    const cases =
+      sex === 'female'
+        ? feminine
+        : sex === 'male'
+          ? masculine
+          : masculine.map((suffix, i) =>
+              suffix === feminine[i] ? suffix : `${suffix}|${feminine[i]}`
+            );
+    return cases.map((suffix) => attach(stem, suffix));
+  }
+  if (!/[бвгджзклмнпрстфхцчшщ]$/u.test(word)) {
+    return Array(6).fill(word); // Indeclinable: Шевченко, Сочи.
+  }
+  return [
+    '',
+    'а',
+    'у',
+    accusative('а'),
+    hush.test(word) ? 'ем' : 'ом',
+    'е',
+  ].map((suffix) => attach(word, suffix));
+}
+const attach = (stem, suffix) =>
+  suffix
+    .split('|')
+    .map((ending) => stem + ending)
+    .join('|');
+function adjective(word) {
+  for (const [ending, remove, cases] of adjectives) {
+    if (ending.test(word)) {
+      return cases(word).map((suffix) =>
+        attach(word.slice(0, -remove), suffix)
+      );
+    }
+  }
+  return undefined;
+}
+function surname(word, sex) {
+  if (/(?:ов|ев|ёв|ин|ын)$/u.test(word)) {
+    return ['', 'а', 'у', 'а', 'ым|ом', 'е'].map((s) => attach(word, s));
+  }
+  if (/(?:ова|ева|ёва|ина|ына)$/u.test(word)) {
+    const stem = word.slice(0, -1);
+    return ['а', 'ой', 'ой', 'у', 'ой|ою', 'ой'].map((s) => attach(stem, s));
+  }
+  const forms = adjective(word);
+  if (forms) {
+    return forms;
+  }
+  return sex === 'female' && !/[ая]$/u.test(word)
+    ? Array(6).fill(word)
+    : noun(word, sex, true);
+}
+export const russianNoun = (word, options) =>
+  options.adjective && adjective(word)
+    ? adjective(word)
+    : noun(word, options.sex, options.animate);
+// `kind` is the name slot: lastName, firstName or middleName.
+export function russianNameForms(word, kind, sex) {
+  const lower = word.toLowerCase();
+  if (kind === 'lastName') {
+    return surname(lower, sex);
+  }
+  if (kind === 'middleName' && /ич$/u.test(lower)) {
+    return ['', 'а', 'у', 'а', 'ем', 'е'].map((s) => attach(lower, s));
+  }
+  return noun(lower, sex, true);
+}
+const fold = (word) => word.toLowerCase().replaceAll('ё', 'е');
+// Every case a surface can stand for, in case order.
+export function casesOf(surface, forms) {
+  const wanted = fold(surface);
+  return forms.flatMap((form, index) =>
+    fold(form).split('|').includes(wanted) ? [index] : []
+  );
+}
+export const formOf = (forms, index) => forms[index].split('|')[0];
+// Cases governed by a preposition, in order of preference. Bare forms like
+// `Ромашке` (dative or prepositional) cannot be told apart without it.
+const governed = [
+  [/^(?:в|во|на|о|об|обо|при)$/u, [5, 3]],
+  [/^(?:к|ко|по)$/u, [2]],
+  [/^(?:с|со|над|под|перед|за)$/u, [4, 1, 3]],
+  [/^(?:у|от|до|из|без|для|около|после|кроме|вокруг|против)$/u, [1]],
+];
+const lastWord = /(?<![\p{L}\p{M}\p{N}_-])(\p{L}{1,7})[ \t\u00a0]+([«“"]?)$/u;
+// `в Лютике и Ромашке`: a conjunct takes the case of the word before it.
+const conjunct =
+  /[\p{L}\p{M}-]{1,32}[»”"]?(?:,|[ \t\u00a0]+(?:и|или))[ \t\u00a0]+[«“"]?$/u;
+export function governedCases(text, start) {
+  const before = text.slice(Math.max(0, start - 64), start);
+  const conjunction = conjunct.exec(before);
+  const source = conjunction ? before.slice(0, conjunction.index) : before;
+  const match = lastWord.exec(source.slice(-12));
+  if (!match) {
+    return { cases: [] };
+  }
+  const word = match[1].toLowerCase();
+  const rule = governed.find(([pattern]) => pattern.test(word));
+  return { cases: rule?.[1] ?? [], quoted: Boolean(match[2]) };
+}
+// Intersects the candidates of each word; a word that fits no case is ignored.
+// A quoted name in the nominative stays there: в «Вектор».
+export function commonCase(candidates, context = { cases: [] }) {
+  const present = candidates.filter((cases) => cases.length);
+  const common = [0, 1, 2, 3, 4, 5].filter((index) =>
+    present.every((cases) => cases.includes(index))
+  );
+  if (context.quoted && common.includes(0)) {
+    return 0;
+  }
+  return (
+    context.cases.find((index) => common.includes(index)) ?? common[0] ?? 0
+  );
+}

package/src/russian-names.js

@@ -0,0 +1,36 @@
+import { firstNames } from './names.js';
+
+// Finite Russian name grammar shared by known-value matching and fake mode.
+const patronymic = /(?:ич|овна|евна|ична|vich|ovna|evna)$/iu;
+const surname = /(?:ов|ев|ин|ын|ский|цкий|ова|ева|ина|ына|ская|цкая)$/iu;
+const fold = (word) => word.toLowerCase().replaceAll('ё', 'е');
+const givenNames = new Set(firstNames.ru.split(' ').map(fold));
+
+export const isPatronymic = (word) => patronymic.test(word);
+export const isGivenName = (word) => givenNames.has(fold(word));
+
+// Returns word indexes by role, or undefined when the roles are not evident.
+// `Имя Отчество Фамилия` is checked first so that surnames in -ич, as in
+// `Шостакович Дмитрий Дмитриевич`, are not mistaken for patronymics.
+export function russianNameRoles(words, known = isGivenName) {
+  if (words.length === 3) {
+    if (isPatronymic(words[1])) {
+      return { given: 0, patronymic: 1, surname: 2 };
+    }
+    return isPatronymic(words[2])
+      ? { surname: 0, given: 1, patronymic: 2 }
+      : undefined;
+  }
+  if (words.length !== 2) {
+    return undefined;
+  }
+  if (isPatronymic(words[1])) {
+    return { given: 0, patronymic: 1 };
+  }
+  const candidates = [0, 1].filter(
+    (i) => surname.test(words[i]) && !known(words[i])
+  );
+  return candidates.length === 1
+    ? { surname: candidates[0], given: 1 - candidates[0] }
+    : undefined;
+}

package/src/sanitizer.js

@@ -1,4 +1,5 @@
 import { generatedValues } from './fake.js';
+import { prepareFakeText } from './fake-entities.js';
 import { alignEscapes } from './escape-spans.js';
 import { actionable } from './confidence.js';
 import { propagate, confirmationOptions } from './propagation.js';
@@ -692,7 +693,7 @@ export function redactResult(
 ) {
   options = applyProfile(options);
   const spans = validatedSpans(text, findings, options);
-  options = initializePlaceholders(options);
+  options = prepareFakeText(text, findings, initializePlaceholders(options));
   preparePlaceholderText(text, findings, options);
   const parts = [];
   const faked = [];
@@ -719,6 +720,11 @@ export function redactResult(
     const transform =
       options.transformations?.[span.type] ?? options.transformation;
     if (retainedReplacement(transform, 'placeholder', span, replacement)) {
+      // `Organization-1` followed by `99` would read as a token that does not
+      // exist, so a span that ends there fails the run instead.
+      if (/\d$/.test(replacement) && /\d/.test(text[span.end] ?? '')) {
+        throw failure('ERR_RESIDUAL');
+      }
       occurrences.push({
         start: outputLength,
         end: outputLength + replacement.length,

package/src/transforms.js

@@ -41,6 +41,22 @@ export function validateTransforms(options) {
 function positiveInteger(value) {
   return Number.isSafeInteger(value) && value > 0;
 }
+const poolTypes = new Set(['ORGANIZATION', 'LOCATION', 'EDUCATION']);
+function validPools(pools) {
+  return (
+    pools === undefined ||
+    (Boolean(pools) &&
+      typeof pools === 'object' &&
+      !Array.isArray(pools) &&
+      Object.entries(pools).every(
+        ([type, names]) =>
+          poolTypes.has(type) &&
+          Array.isArray(names) &&
+          names.length > 0 &&
+          names.every((name) => typeof name === 'string' && name.trim())
+      ))
+  );
+}
 function validateTransform(transform) {
   if (!transform || !modes.has(transform.mode)) {
     throw failure('ERR_CONFIG');
@@ -54,7 +70,8 @@ function validateTransform(transform) {
       Buffer.byteLength(transform.key) >= 16 &&
       (transform.credentials === undefined ||
         typeof transform.credentials === 'boolean') &&
-      (transform.mrzCountry === undefined || transform.mrzCountry === 'UTO'),
+      (transform.mrzCountry === undefined || transform.mrzCountry === 'UTO') &&
+      validPools(transform.pools),
     pseudonym: () =>
       typeof transform.key === 'string' &&
       Buffer.byteLength(transform.key) >= 16,
@@ -130,7 +147,7 @@ function masked(value, finding, transform) {
     ? REDACTED
     : `${chars.slice(0, start).join('')}${transform.marker ?? '*'.repeat(chars.length - start - end)}${end ? chars.slice(-end).join('') : ''}`;
 }
-function transformed(value, finding, transform) {
+function transformed(value, finding, transform, options) {
   if (!transform || transform.mode === 'redact') {
     return REDACTED;
   }
@@ -141,7 +158,7 @@ function transformed(value, finding, transform) {
       : REDACTED;
   }
   if (transform.mode === 'fake') {
-    return realisticFake(value, finding, transform);
+    return realisticFake(value, finding, transform, options);
   }
   if (finding.category === 'credential') {
     return REDACTED;
@@ -198,6 +215,6 @@ function renderValue(text, finding, transform, options) {
   const result =
     transform?.mode === 'placeholder'
       ? placeholderReplacement(raw, finding, transform, options)
-      : transformed(raw, finding, transform);
+      : transformed(raw, finding, transform, options);
   return jsonQuoted ? JSON.stringify(result).slice(1, -1) : result;
 }