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

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.16.0
+
+### Minor Changes
+
+- 75fd2d9: Match a reused restore map PERSON entry like an explicit `knownPersonal` value, so a bare or lower-case part no longer merges people or fails with `ERR_RESIDUAL`, keep parts listed as their own values in an optional `standalone` entry field, cover the adjacent given name or patronymic when a bare part matches, and read labelled CV experience lines (`Опыт: Менеджер, Ромашка (2018 – 2020)`), titles of up to nine words and the `по н.в.` open range in the `documents` profile.
+
+## 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,34 @@ 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 PERSON entry of a reused map matches the same forms as an explicit
+`knownPersonal` value: the full value and its contiguous parts together, all
+cases, both orders and initials. A bare part does not match in the next document
+unless it is stored as its own value, so `Петров Данил` from one CV leaves
+`петров день` and `Петров пришёл.` in the next one untouched. A single stored word
+(`Мороз`) matches its capitalized and upper-case forms but not lower-case text
+(`сильный мороз`); a multi-word value also matches in lower case (`петров данил`).
+A part listed in `knownPersonal` is kept in the entry's `standalone` list once it
+has been replaced, and bare surfaces recorded by earlier versions are ignored on
+reuse. The evidence of the current document is separate: when its text names
+`Петров Данил`, a bare `Петров` or `петрову` in that document, including its stream
+batches and decoded values, links to that person exactly as with a fresh map.
+
+When a bare part matches, the span in placeholder mode takes the capitalized
+given name or patronymic next to it on the same line, so `Алина Мороз` becomes one
+new token instead of `Алина Person-1`. Given names come from a bounded list with
+Russian case endings, so an unlisted name can still stay beside the placeholder.
+
+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 +160,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 +233,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,22 @@ 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. Titles have one to nine words. A label of one or two words
+before the title (`Опыт: `, `Опыт работы - `, `Опыт — `) is read like a list marker,
+and a segment after `|` is read like a line start, so
+`Должность: Менеджер | Опыт: Аналитик, Ромашка (2018 – 2020)` also yields the
+employer. The date range stays the anchor and the employer must still start with a
+capital letter, a digit or a quote. 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.16.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,35 @@ 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}';
+// A segment starts a line or follows `|`. `Опыт:` or `Опыт -` before the title
+// reads like a list marker: the date range remains the anchor of the rule.
+const lineLabel = `\\p{L}[\\p{L}\\p{N}/+#.&-]{0,39}(?:[ \\t]+${titleWord})?(?:[ \\t]*:[ \\t]*|[ \\t]+[-–—][ \\t]+)`;
+const lineTitle = `(?:^|(?<=\\|))[ \\t]*(?:[-–—•*·][ \\t]+|\\d{1,2}[.)][ \\t]+)?(?:${lineLabel}){0,2}${titleWord}(?:[ \\t]+${titleWord}){0,8}`;
+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 +101,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 };
@@ -265,6 +269,8 @@ export interface RestoreMap {
     number: number;
     values: string[];
     aliases: string[];
+    /** PERSON parts listed by the caller, which also match alone on reuse. */
+    standalone?: string[];
   }>;
   documents: Array<{
     digest: string;

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('|');