@discretion/core 0.1.0

package/src/mask/masker.ts

@@ -0,0 +1,276 @@
+/**
+ * masker.ts — replace detected sensitive spans with surrogates (or tokens),
+ * building the vault as it goes.
+ *
+ * Operates on Stage 1 candidates in ORIGINAL-text coordinates (the offsets
+ * the runner resolved through the Stage 0 map), so the edited text is the
+ * user's real text with exactly the sensitive spans replaced.
+ *
+ * FOUR GUARANTEES, each enforced here:
+ *  • CONSISTENT — the same original (by exact, canonical, or normalized key)
+ *    always maps to the same surrogate within a session; a repeat reuses the
+ *    vault entry rather than minting a new one.
+ *  • COLLISION-SAFE — before committing a surrogate, verify it appears
+ *    nowhere in the source text and nowhere in the vault; on collision, retry
+ *    with a fresh seed up to a bound. Exhausting the bound falls back to a
+ *    bracket token.
+ *  • REVERSIBLE — every substitution is a vault entry, so the restorer can
+ *    invert it.
+ *  • NON-OVERLAPPING — overlapping candidates would corrupt the edit. Stage 4
+ *    (M8) does calibrated overlap resolution; here a documented pre-fusion
+ *    stopgap picks a non-overlapping subset (higher confidence, then longer
+ *    span, then more-specific type) purely so masking is well-defined.
+ *
+ * Non-sensitive candidates (known test values) are NOT masked — they are
+ * detected precisely so they can be left alone.
+ */
+
+import { normalize } from '../normalization.js';
+import { runStage1 } from '../detect/runner.js';
+import type { Stage1Options } from '../detect/runner.js';
+import type { SubstitutionMode, VaultEntry } from '../types.js';
+import type { Stage1Candidate } from '../detect/types.js';
+import type { PipelineCandidate } from '../context/types.js';
+import type { Vault } from './vault.js';
+import { chooseSurrogate } from './surrogates.js';
+import { comparisonForm, separatorFree } from './egressGuard.js';
+
+const MAX_SURROGATE_ATTEMPTS = 24;
+
+export interface MaskOptions {
+  /** 'surrogate' (default) or 'token' — SPEC.md's user-selectable modes. */
+  readonly mode?: SubstitutionMode;
+  /** Base seed; a session should vary this so two sessions differ. */
+  readonly seed?: number;
+}
+
+export interface MaskedEntity {
+  readonly type: Stage1Candidate['type'];
+  readonly originalStart: number;
+  readonly originalEnd: number;
+  readonly original: string;
+  readonly replacement: string;
+  readonly vaultId: string;
+  readonly fallback: boolean;
+}
+
+export interface MaskResult {
+  readonly maskedText: string;
+  readonly entities: readonly MaskedEntity[];
+  readonly vaultEntries: readonly VaultEntry[];
+}
+
+/** A stable bracket token, used in token mode and as the surrogate fallback. */
+function bracketToken(type: string, ordinal: number): string {
+  return `[${type}_${ordinal}]`;
+}
+
+/**
+ * Pre-fusion overlap resolution: greedily keep non-overlapping candidates,
+ * preferring higher confidence, then longer span, then a stable detector id
+ * for determinism. A documented stopgap until Stage 4 fusion (M8) resolves
+ * overlaps against calibrated scores.
+ */
+export function resolveForMasking<C extends PipelineCandidate>(
+  candidates: readonly C[],
+): C[] {
+  const sensitive = candidates.filter((c) => c.sensitive);
+  const ranked = [...sensitive].sort((a, b) => {
+    if (b.rawConfidence !== a.rawConfidence) return b.rawConfidence - a.rawConfidence;
+    const lenA = a.originalEnd - a.originalStart;
+    const lenB = b.originalEnd - b.originalStart;
+    if (lenB !== lenA) return lenB - lenA;
+    return a.detectorId < b.detectorId ? -1 : 1;
+  });
+  const kept: C[] = [];
+  for (const c of ranked) {
+    if (!kept.some((k) => c.originalStart < k.originalEnd && k.originalStart < c.originalEnd)) {
+      kept.push(c);
+    }
+  }
+  return kept.sort((a, b) => a.originalStart - b.originalStart);
+}
+
+/**
+ * Mask the given ORIGINAL text using the candidates found in it.
+ * The candidates' `originalStart`/`originalEnd` must index into `original`.
+ *
+ * Takes `PipelineCandidate` rather than `Stage1Candidate` because Stage 2's
+ * PERSON/ORG/LOCATION entities must be masked too, and nothing in this file
+ * reads the `stage` discriminant — the two candidate shapes are otherwise
+ * identical. Typing it to Stage 1 alone was the narrower claim, not the safer
+ * one: it silently excluded the entities SPEC most wants surrogates for.
+ */
+export function maskOriginal(
+  original: string,
+  candidates: readonly PipelineCandidate[],
+  vault: Vault,
+  options: MaskOptions = {},
+): MaskResult {
+  const mode = options.mode ?? 'surrogate';
+  const baseSeed = options.seed ?? 0x5eed;
+  const resolved = resolveForMasking(candidates);
+
+  // The collision check must run in the EGRESS GUARD'S comparison space:
+  // the guard scans in normalized+case-folded form plus a separator-free
+  // canonical pass, so a surrogate is acceptable only if none of this
+  // document's sensitive values would be found inside it under those same
+  // comparisons. The bug this prevents was found by the integration
+  // property: a phone surrogate drawn from the same small pool was the SAME
+  // number as the original in different formatting — the literal string
+  // check passed, and the masked text then failed its own guard.
+  const forbiddenNeedles = resolved.map((c) => {
+    const value = original.slice(c.originalStart, c.originalEnd);
+    const form = comparisonForm(value);
+    const strip = separatorFree(separatorFreeCanonical(c, value));
+    return { form, strip };
+  });
+
+  const entities: MaskedEntity[] = [];
+  const vaultEntries: VaultEntry[] = [];
+  const tokenOrdinals = new Map<string, number>();
+
+  const out: string[] = [];
+  let cursor = 0;
+
+  for (const c of resolved) {
+    const value = original.slice(c.originalStart, c.originalEnd);
+    out.push(original.slice(cursor, c.originalStart));
+    cursor = c.originalEnd;
+
+    // Consistency: a value already masked this session reuses its surrogate.
+    const existing = vault.getByOriginal(value, c.canonical);
+    if (existing !== undefined) {
+      out.push(existing.replacement);
+      entities.push({
+        type: c.type, originalStart: c.originalStart, originalEnd: c.originalEnd,
+        original: value, replacement: existing.replacement, vaultId: existing.id,
+        fallback: existing.fallback ?? false,
+      });
+      continue;
+    }
+
+    const { replacement, fallback } = selectReplacement(
+      c, value, original, vault, mode, baseSeed, tokenOrdinals, forbiddenNeedles,
+    );
+    const entry = vault.register({
+      type: c.type,
+      original: value,
+      replacement,
+      ...(c.canonical !== undefined ? { canonical: c.canonical } : {}),
+      ...(fallback ? { fallback: true } : {}),
+    });
+    vaultEntries.push(entry);
+    out.push(replacement);
+    entities.push({
+      type: c.type, originalStart: c.originalStart, originalEnd: c.originalEnd,
+      original: value, replacement, vaultId: entry.id, fallback,
+    });
+  }
+  out.push(original.slice(cursor));
+
+  return { maskedText: out.join(''), entities, vaultEntries };
+}
+
+/**
+ * End-to-end: normalize, run Stage 1, and mask the original text. The
+ * convenience entry point for the playground (M5) and the tests; the
+ * extension (M9) wires the same pieces with its own detection options.
+ */
+export function mask(text: string, vault: Vault, options: MaskOptions & Stage1Options = {}): MaskResult {
+  const normalization = normalize(text);
+  const { mode, seed, ...stage1 } = options;
+  const candidates = runStage1(normalization, stage1);
+  return maskOriginal(
+    text,
+    candidates,
+    vault,
+    { ...(mode !== undefined ? { mode } : {}), ...(seed !== undefined ? { seed } : {}) },
+  );
+}
+
+interface ForbiddenNeedle {
+  readonly form: string;
+  readonly strip: string;
+}
+
+/** The candidate's canonical in comparison form (falls back to the value). */
+function separatorFreeCanonical(c: PipelineCandidate, value: string): string {
+  return comparisonForm(c.canonical ?? value);
+}
+
+/** Pick a collision-free, consistent replacement for one value. */
+function selectReplacement(
+  c: PipelineCandidate,
+  value: string,
+  sourceDoc: string,
+  vault: Vault,
+  mode: SubstitutionMode,
+  baseSeed: number,
+  tokenOrdinals: Map<string, number>,
+  forbiddenNeedles: readonly ForbiddenNeedle[],
+): { replacement: string; fallback: boolean } {
+  if (mode === 'token') {
+    return { replacement: nextToken(c.type, vault, sourceDoc, tokenOrdinals), fallback: false };
+  }
+
+  const seedBase = baseSeed ^ hashString(c.canonical ?? value);
+  for (let attempt = 0; attempt < MAX_SURROGATE_ATTEMPTS; attempt++) {
+    const surrogate = chooseSurrogate(
+      { type: c.type, text: value, ...(c.metadata !== undefined ? { metadata: c.metadata } : {}) },
+      (seedBase + attempt * 0x9e37) & 0x7fffffff,
+    );
+    if (surrogate === null) break; // no surrogate for this type → token
+    if (!collides(surrogate, sourceDoc, vault, forbiddenNeedles)) {
+      return { replacement: surrogate, fallback: false };
+    }
+  }
+  // Pool exhausted or no surrogate: fall back to a bracket token, recorded.
+  return { replacement: nextToken(c.type, vault, sourceDoc, tokenOrdinals), fallback: true };
+}
+
+/**
+ * A surrogate collides if it appears in the source text or the vault — or
+ * if any of this document's sensitive values would be FOUND WITHIN IT under
+ * the egress guard's comparisons (normalized case-folded substring, or the
+ * ≥6-char separator-free canonical pass). Masker and guard sharing one
+ * comparison space is what guarantees masked text passes its own guard.
+ */
+function collides(
+  surrogate: string,
+  sourceDoc: string,
+  vault: Vault,
+  forbiddenNeedles: readonly ForbiddenNeedle[],
+): boolean {
+  if (vault.wouldCollide(surrogate)) return true;
+  // Case-insensitive appearance in the source, so the restorer's fuzzy pass
+  // cannot later confuse the surrogate with pre-existing text.
+  if (sourceDoc.toLowerCase().includes(surrogate.toLowerCase())) return true;
+
+  const surrogateForm = comparisonForm(surrogate);
+  const surrogateStrip = separatorFree(surrogateForm);
+  for (const needle of forbiddenNeedles) {
+    if (needle.form.length > 0 && surrogateForm.includes(needle.form)) return true;
+    if (needle.strip.length >= 6 && surrogateStrip.includes(needle.strip)) return true;
+  }
+  return false;
+}
+
+/** The next unused bracket token for a type (unique in source and vault). */
+function nextToken(type: string, vault: Vault, sourceDoc: string, tokenOrdinals: Map<string, number>): string {
+  let ordinal = tokenOrdinals.get(type) ?? 1;
+  let token = bracketToken(type, ordinal);
+  while (vault.wouldCollide(token) || sourceDoc.includes(token)) {
+    ordinal += 1;
+    token = bracketToken(type, ordinal);
+  }
+  tokenOrdinals.set(type, ordinal + 1);
+  return token;
+}
+
+/** Deterministic 31-bit string hash so a value's seed is stable per session. */
+function hashString(s: string): number {
+  let h = 0;
+  for (let i = 0; i < s.length; i++) h = (Math.imul(h, 31) + s.charCodeAt(i)) | 0;
+  return h & 0x7fffffff;
+}

package/src/mask/restorer.ts

@@ -0,0 +1,284 @@
+/**
+ * restorer.ts — the unmasker, correct against fragmented streaming text.
+ *
+ * The model's response arrives in chunks, and a surrogate may be split across
+ * a chunk boundary. The restorer therefore operates on ACCUMULATED text and
+ * emits only what is safe to finalize:
+ *
+ *  • HOLD ON PARTIAL MATCH. If a suffix of the accumulated buffer is a proper
+ *    prefix of any known surrogate, that suffix is held unrendered until more
+ *    text resolves it. This is the guarantee behind the key test: no partial
+ *    surrogate is ever wrongly replaced, however the stream is chunked.
+ *
+ *  • EXACT REPLACEMENT is longest-match, left to right — a surrogate that is a
+ *    prefix of a longer surrogate never steals the longer one's match.
+ *
+ *  • FUZZY FALLBACK is a controlled, per-token pass for a surrogate the model
+ *    transformed: case change, possessive ('s), or plural (s/es). It fires
+ *    ONLY when exactly one surrogate matches a settled token under those
+ *    relaxations; ANY ambiguity (two surrogates match, or none) leaves the
+ *    token untouched — SPEC.md's hard rule. Cross-script "translation" of a
+ *    surrogate is deliberately NOT attempted; such a surrogate stays visible
+ *    rather than being guessed at (ARCHITECTURE.md D13).
+ *
+ *  • IDEMPOTENT. Only newly-buffered text is ever processed; rendered text is
+ *    never revisited. Re-restoring already-restored text is a no-op because
+ *    originals are collision-guaranteed distinct from every surrogate, so
+ *    nothing in the output matches a surrogate to replace again.
+ */
+
+import type { RestoreResult } from '../types.js';
+import type { Vault } from './vault.js';
+
+/** ASCII/Unicode word character, for exact-match boundary checks. */
+const WORD_CHAR = /[\p{L}\p{N}_]/u;
+
+interface FuzzyEntry {
+  readonly surrogate: string;
+  readonly lower: string;
+  readonly original: string;
+}
+
+export interface RestorerOptions {
+  /** Enable the transformed-surrogate fuzzy fallback. Default true. */
+  readonly fuzzy?: boolean;
+}
+
+export class Restorer {
+  private buffer = '';
+  private out = '';
+  private restored = 0;
+  private done = false;
+
+  private readonly surrogatesByLength: readonly string[];
+  private readonly maxLen: number;
+  private readonly fuzzyByLower: ReadonlyMap<string, readonly FuzzyEntry[]>;
+  private readonly fuzzy: boolean;
+  private readonly vault: Vault;
+
+  constructor(vault: Vault, options: RestorerOptions = {}) {
+    this.vault = vault;
+    this.fuzzy = options.fuzzy ?? true;
+    const surrogates = vault.replacements();
+    this.surrogatesByLength = [...surrogates].sort((a, b) => b.length - a.length);
+    this.maxLen = surrogates.reduce((m, s) => Math.max(m, s.length), 0);
+
+    const fuzzyMap = new Map<string, FuzzyEntry[]>();
+    for (const surrogate of surrogates) {
+      const entry = vault.getBySurrogate(surrogate);
+      if (entry === undefined) continue;
+      const lower = surrogate.toLowerCase();
+      const list = fuzzyMap.get(lower) ?? [];
+      list.push({ surrogate, lower, original: entry.original });
+      fuzzyMap.set(lower, list);
+    }
+    this.fuzzyByLower = fuzzyMap;
+  }
+
+  /** Push the next stream chunk; returns the text newly rendered this call. */
+  push(chunk: string): string {
+    if (this.done) throw new Error('restorer: push after finish');
+    this.buffer += chunk;
+    return this.drain(false);
+  }
+
+  /** Flush the remainder; no more holding. Returns the final rendered text. */
+  finish(): string {
+    if (this.done) return '';
+    const tail = this.drain(true);
+    this.done = true;
+    return tail;
+  }
+
+  /** Everything rendered so far. */
+  get rendered(): string {
+    return this.out;
+  }
+
+  /** How many surrogate occurrences have been restored. */
+  get restoredCount(): number {
+    return this.restored;
+  }
+
+  /** Emit every settled portion of the buffer, holding what is still risky. */
+  private drain(final: boolean): string {
+    if (this.surrogatesByLength.length === 0) {
+      // Nothing to restore: pure passthrough, no holding.
+      const emit = this.buffer;
+      this.buffer = '';
+      this.out += emit;
+      return emit;
+    }
+
+    const holdFrom = final ? this.buffer.length : this.holdPoint();
+    const settled = this.buffer.slice(0, holdFrom);
+    this.buffer = this.buffer.slice(holdFrom);
+    const emitted = this.replaceSettled(settled);
+    this.out += emitted;
+    return emitted;
+  }
+
+  /**
+   * The earliest position from which the buffer must be held back:
+   *  • the start of any suffix that is a proper prefix of a surrogate, and
+   *  • (fuzzy on) the start of a trailing non-whitespace run, so the fuzzy
+   *    pass always sees whole tokens rather than a word still being typed.
+   */
+  private holdPoint(): number {
+    const n = this.buffer.length;
+    let hold = n;
+
+    // A prefix-to-end can only begin within maxLen characters of the end.
+    const scanStart = Math.max(0, n - this.maxLen);
+    for (let p = scanStart; p < n; p++) {
+      const tail = this.buffer.slice(p);
+      if (this.isProperPrefixOfSurrogate(tail)) {
+        hold = Math.min(hold, p);
+        break; // earliest such p found
+      }
+    }
+
+    if (this.fuzzy) {
+      // Trailing run of non-whitespace = a token that may still be growing.
+      let w = n;
+      while (w > 0 && !/\s/.test(this.buffer[w - 1]!)) w--;
+      if (w < n) hold = Math.min(hold, w);
+    }
+
+    return hold;
+  }
+
+  private isProperPrefixOfSurrogate(tail: string): boolean {
+    if (tail.length === 0) return false;
+    for (const s of this.surrogatesByLength) {
+      if (s.length > tail.length && s.startsWith(tail)) return true;
+    }
+    return false;
+  }
+
+  /** Exact longest-match replacement, then the controlled fuzzy pass. */
+  private replaceSettled(text: string): string {
+    if (text.length === 0) return '';
+
+    // Exact pass.
+    let exact = '';
+    let i = 0;
+    while (i < text.length) {
+      const match = this.longestSurrogateAt(text, i);
+      if (match !== null) {
+        exact += this.vault.getBySurrogate(match)!.original;
+        this.restored += 1;
+        i += match.length;
+      } else {
+        exact += text[i];
+        i += 1;
+      }
+    }
+
+    return this.fuzzy ? this.fuzzyPass(exact) : exact;
+  }
+
+  /**
+   * Longest surrogate matching at `pos` WITH word-boundary semantics: a
+   * surrogate whose first/last character is a word character must not be
+   * glued to another word character in the text. Without this, a short
+   * surrogate ('Cat') corrupts an ordinary word ('Catalog' -> 'Org Onealog').
+   * Structured surrogates (emails, IBANs, PEM blocks) are unaffected because
+   * their neighbours in real text are punctuation or whitespace, and a
+   * surrogate ending in punctuation imposes no trailing constraint at all.
+   * Model-added affixes ('Northwinds') are handled by the fuzzy pass, which
+   * re-attaches what it strips.
+   */
+  private longestSurrogateAt(text: string, pos: number): string | null {
+    for (const s of this.surrogatesByLength) {
+      if (pos + s.length > text.length || !text.startsWith(s, pos)) continue;
+      const end = pos + s.length;
+      const startsWord = WORD_CHAR.test(s[0]!);
+      const endsWord = WORD_CHAR.test(s[s.length - 1]!);
+      if (startsWord && pos > 0 && WORD_CHAR.test(text[pos - 1]!)) continue;
+      if (endsWord && end < text.length && WORD_CHAR.test(text[end]!)) continue;
+      return s;
+    }
+    return null;
+  }
+
+  /**
+   * Per-token fuzzy restoration of transformed surrogates. Splits on
+   * whitespace, keeps the separators, and rewrites only tokens that resolve
+   * to exactly one surrogate under case / possessive / plural relaxation.
+   */
+  private fuzzyPass(text: string): string {
+    const pieces = text.split(/(\s+)/); // keep whitespace as odd-indexed pieces
+    for (let k = 0; k < pieces.length; k += 2) {
+      const token = pieces[k];
+      if (token === undefined || token.length === 0) continue;
+      const rewritten = this.fuzzyToken(token);
+      if (rewritten !== null) {
+        pieces[k] = rewritten;
+        this.restored += 1;
+      }
+    }
+    return pieces.join('');
+  }
+
+  /** Try to restore one whitespace-free token; null = leave it alone. */
+  private fuzzyToken(token: string): string | null {
+    // Peel surrounding punctuation so "Nils," and "(Nils)" still resolve;
+    // the peeled affixes are re-attached around the restored original.
+    const m = /^(\p{P}*)(.*?)(\p{P}*)$/u.exec(token);
+    if (m === null) return null;
+    const [, lead, coreRaw, trail] = m as unknown as [string, string, string, string];
+    if (coreRaw.length === 0) return null;
+
+    const resolved = this.resolveFuzzyCore(coreRaw);
+    if (resolved === null) return null; // zero or ambiguous → leave alone
+    // The stripped affix is re-attached to the ORIGINAL, so a model plural
+    // survives restoration ('Northwinds' -> 'Acme Corps') — except when the
+    // original already ends with the same letters, where re-attaching would
+    // only stutter ('Acme Holdings' + 's'). Either way the restored VALUE is
+    // right; perfect cross-language morphology is out of scope here.
+    const suffix =
+      resolved.suffix.length > 0 && resolved.original.toLowerCase().endsWith(resolved.suffix.toLowerCase())
+        ? ''
+        : resolved.suffix;
+    return `${lead}${resolved.original}${suffix}${trail}`;
+  }
+
+  /**
+   * Resolve a core token to exactly one original, under case-fold plus
+   * possessive/plural stripping, carrying the affix that was stripped.
+   * Returns null when zero or MORE THAN ONE distinct original is reachable —
+   * SPEC.md's hard rule that ambiguous matches are left alone.
+   */
+  private resolveFuzzyCore(core: string): { original: string; suffix: string } | null {
+    const lower = core.toLowerCase();
+    const forms: readonly (readonly [string, string])[] = [
+      [lower, ''],
+      [lower.replace(/['’]s$|['’]$/u, ''), core.slice(lower.replace(/['’]s$|['’]$/u, '').length)],
+      ...(/es$/i.test(core) ? ([[lower.replace(/es$/i, ''), core.slice(core.length - 2)]] as const) : []),
+      ...(/s$/i.test(core) ? ([[lower.replace(/s$/i, ''), core.slice(core.length - 1)]] as const) : []),
+    ];
+
+    const byOriginal = new Map<string, string>();
+    for (const [form, suffix] of forms) {
+      if (form === '' || form === lower && suffix !== '') continue;
+      const entries = this.fuzzyByLower.get(form);
+      if (entries === undefined) continue;
+      for (const e of entries) {
+        if (!byOriginal.has(e.original)) byOriginal.set(e.original, suffix);
+      }
+    }
+
+    if (byOriginal.size !== 1) return null;
+    const [original, suffix] = [...byOriginal.entries()][0]!;
+    return { original, suffix };
+  }
+}
+
+/** One-shot restoration of a complete (non-streamed) response. */
+export function restore(text: string, vault: Vault, options: RestorerOptions = {}): RestoreResult {
+  const r = new Restorer(vault, options);
+  r.push(text);
+  r.finish();
+  return { restoredText: r.rendered, restoredCount: r.restoredCount, unmatchedReplacements: [] };
+}

package/src/mask/surrogatePools.ts

@@ -0,0 +1,96 @@
+/**
+ * Starter surrogate pools for the NER entity types (PERSON, ORG, LOCATION)
+ * and dates.
+ *
+ * These types are produced by Stage 2 (M6), which does not exist yet, so
+ * nothing in the M4 pipeline reaches them — but SPEC.md's substitution table
+ * requires them, and building the pools now lets the surrogate registry be
+ * complete and lets M6 plug in without touching this file's consumers.
+ *
+ * PERSON pools are grouped by SCRIPT and broad naming convention so that
+ * "Yuki Tanaka" is replaced by another East-Asian-convention name rather than
+ * "Bob Smith" (SPEC.md's explicit example). These are deliberately small,
+ * hand-picked, unmistakably-fictional pools; M7's gazetteers replace them
+ * with broad real-name coverage. Recorded in ARCHITECTURE.md D12.
+ */
+
+import type { ScriptName } from '../types.js';
+
+export interface PersonPool {
+  readonly script: ScriptName;
+  readonly given: readonly string[];
+  readonly surnames: readonly string[];
+  /** Order: given-first (Western) or family-first (East Asian). */
+  readonly order: 'given-first' | 'family-first';
+  /** Separator between the two parts. */
+  readonly sep: string;
+}
+
+export const PERSON_POOLS: readonly PersonPool[] = [
+  {
+    script: 'latin', order: 'given-first', sep: ' ',
+    given: ['Alex', 'Maria', 'Sofia', 'Lucas', 'Elena', 'Marco', 'Nadia', 'Oscar', 'Petra', 'Ravi'],
+    surnames: ['Fontaine', 'Delacroix', 'Marchetti', 'Ellison', 'Vandel', 'Rourke', 'Sandoval', 'Keller'],
+  },
+  {
+    script: 'cyrillic', order: 'given-first', sep: ' ',
+    given: ['Ирина', 'Дмитрий', 'Ольга', 'Сергей', 'Наталья', 'Павел'],
+    surnames: ['Соколова', 'Морозов', 'Волкова', 'Лебедев', 'Козлова', 'Новиков'],
+  },
+  {
+    script: 'greek', order: 'given-first', sep: ' ',
+    given: ['Γιώργος', 'Ελένη', 'Νίκος', 'Μαρία', 'Κώστας'],
+    surnames: ['Παπαδόπουλος', 'Νικολάου', 'Γεωργίου', 'Δημητρίου'],
+  },
+  {
+    script: 'arabic', order: 'given-first', sep: ' ',
+    given: ['ليلى', 'أحمد', 'فاطمة', 'يوسف', 'زينب'],
+    surnames: ['الحسن', 'المنصور', 'الصالح', 'الرشيد'],
+  },
+  {
+    script: 'hebrew', order: 'given-first', sep: ' ',
+    given: ['נועה', 'איתי', 'תמר', 'יונתן'],
+    surnames: ['לוי', 'כהן', 'פרץ', 'ביטון'],
+  },
+  {
+    script: 'devanagari', order: 'given-first', sep: ' ',
+    given: ['आरव', 'दिया', 'विवान', 'सान्या'],
+    surnames: ['शर्मा', 'वर्मा', 'गुप्ता', 'सिंह'],
+  },
+  {
+    script: 'han', order: 'family-first', sep: '',
+    given: ['伟', '芳', '娜', '强', '敏', '静'],
+    surnames: ['王', '李', '张', '刘', '陈'],
+  },
+  {
+    script: 'kana', order: 'family-first', sep: '',
+    given: ['ゆき', 'はると', 'さくら', 'れん'],
+    surnames: ['田中', '佐藤', '鈴木', '高橋'],
+  },
+  {
+    script: 'hangul', order: 'family-first', sep: '',
+    given: ['민준', '서연', '지호', '하은'],
+    surnames: ['김', '이', '박', '최'],
+  },
+  {
+    script: 'thai', order: 'given-first', sep: ' ',
+    given: ['สมชาย', 'สุดา', 'ประเสริฐ'],
+    surnames: ['แซ่ตั้ง', 'ศรีสุข', 'บุญมี'],
+  },
+];
+
+/** Fallback pool when a detected script has no dedicated one. */
+export const DEFAULT_PERSON_POOL = PERSON_POOLS[0]!;
+
+/** Plausible fictional organization names. */
+export const ORG_POOL: readonly string[] = [
+  'Northwind Systems', 'Brightpath Analytics', 'Cedar Grove Holdings', 'Meridian Labs',
+  'Quillfeather & Co.', 'Ashford Logistics', 'Blue Harbor Partners', 'Vireo Technologies',
+  'Sunspire Media', 'Gravel & Stone LLC',
+];
+
+/** Plausible fictional place names (cities). */
+export const LOCATION_POOL: readonly string[] = [
+  'Fairmont', 'Elderbrook', 'Port Haven', 'Westmere', 'Ashville Bay',
+  'Cranleigh', 'Thornbury', 'Riverton', 'Oakmoor', 'Silverdale',
+];