@discretion/core 0.1.0

package/src/fuse/resolve.ts

@@ -0,0 +1,237 @@
+/**
+ * Stage 4 — OVERLAP RESOLUTION.
+ *
+ * SPEC.md: "Resolve overlapping candidates: prefer the more specific type,
+ * then higher calibrated confidence, then longer span. Never emit overlapping
+ * entities."
+ *
+ * THE SAFETY PROPERTY THAT GOVERNS THIS FILE. Resolution DROPS candidates, so
+ * D18 applies to it exactly as it applies to a suppression rule — but it has a
+ * failure mode a suppression rule does not. Dropping a WIDE candidate in
+ * favour of a narrow one it contains does not merely relabel a span: the
+ * characters outside the narrow span stop being masked. A rule that naively
+ * "prefers the more specific type" would take CONNECTION_STRING over the
+ * credentialled URL containing it and leave the scheme, host and port of a
+ * live database URI in the outgoing text.
+ *
+ * So the ordering here is deliberately NOT SPEC's literal order. It is:
+ *
+ *   1. WIDEST SPAN first — never reduce masked coverage.
+ *   2. then the more specific TYPE, for spans of equal extent.
+ *   3. then higher confidence.
+ *
+ * Coverage is promoted above specificity because coverage is the property
+ * that cannot be recovered downstream: a mislabelled span is a cosmetic
+ * defect in the review UI, an unmasked one is a leak. Where spans are equal
+ * the two orderings agree, which is the case SPEC's wording is really about.
+ * `resolveOverlaps` asserts the coverage property on its own output.
+ *
+ * THE SPECIFICITY ORDER IS MEASURED, NOT ASSUMED. A census over the 2,600
+ * document corpus found 66.8% of Stage 1 candidates in at least one cross-type
+ * overlap, and for each pair recorded which type ground truth actually agreed
+ * with. Every rank below cites that measurement.
+ */
+
+import type { EntityType } from '../types.js';
+import type { PipelineCandidate } from '../context/types.js';
+
+/**
+ * Type specificity: LOWER wins a tie between spans of equal extent.
+ *
+ * Derived from the overlap census — the "which type did ground truth agree
+ * with" column — not from intuition about which type sounds more precise.
+ */
+const SPECIFICITY: Readonly<Partial<Record<EntityType, number>>> = {
+  // Self-verifying structure. A valid MRZ or PEM block is what it says it is.
+  PASSPORT_MRZ: 0,
+  PRIVATE_KEY: 0,
+  JWT: 0,
+
+  // A connection string and a credentialled URL claim IDENTICAL spans 140
+  // times in the corpus, and ground truth agreed with CONNECTION_STRING in
+  // 140 of 140. The DB/queue scheme is the more specific reading of the same
+  // characters, exactly as the M7 taxonomy predicted.
+  CONNECTION_STRING: 1,
+  URL_WITH_CREDENTIALS: 2,
+
+  // Checksum-validated identifiers.
+  IBAN: 3,
+  CREDIT_CARD: 3,
+  CRYPTO_WALLET: 3,
+  API_KEY: 3,
+  VAT_NUMBER: 3,
+  US_NPI: 3,
+  VIN: 3,
+  SWIFT_BIC: 3,
+  US_ROUTING_NUMBER: 3,
+  UK_SORT_CODE: 3,
+  CA_TRANSIT_NUMBER: 3,
+  AU_BSB: 3,
+  IN_IFSC: 3,
+  BR_AGENCIA: 3,
+
+  // Structured but not self-verifying.
+  EMAIL: 4,
+  PHONE: 4,
+  IP_ADDRESS: 4,
+  MAC_ADDRESS: 4,
+  COORDINATES: 4,
+  STREET_ADDRESS: 4,
+  HEALTH_DATA: 5,
+
+  // National and tax identifiers. Deliberately EQUAL: the census found
+  // TAX_ID-over-NATIONAL_ID and NATIONAL_ID-over-TAX_ID both occurring on
+  // equal spans with ground truth split roughly evenly between them (28/10/10
+  // and 19/11/11). No static ordering is honest about that — it is a genuine
+  // cross-scheme ambiguity that calibrated confidence has to settle, so they
+  // tie here and fall through to the confidence comparison.
+  NATIONAL_ID: 6,
+  TAX_ID: 6,
+
+  // Named entities: statistical proposals, not validated claims.
+  PERSON: 7,
+  ORG: 7,
+  LOCATION: 7,
+
+  // Shape-only, no validator behind it.
+  POSTAL_CODE: 8,
+  DRIVERS_LICENSE: 8,
+  DATE_OF_BIRTH: 8,
+
+  // Entropy alone. The census is unambiguous: a specific type covering the
+  // same characters was right in 2,047 of 2,053 measured overlaps.
+  GENERIC_SECRET: 9,
+};
+
+/** Types absent from the table sort between shape-only and generic. */
+const DEFAULT_SPECIFICITY = 8;
+
+function specificityOf(type: EntityType): number {
+  return SPECIFICITY[type] ?? DEFAULT_SPECIFICITY;
+}
+
+/** A candidate with the confidence Stage 3 gave it. */
+export interface ScoredForResolution {
+  readonly candidate: PipelineCandidate;
+  readonly confidence: number;
+}
+
+export interface ResolutionResult {
+  /** Non-overlapping survivors, in document order. */
+  readonly emitted: readonly ScoredForResolution[];
+  /** Candidates yielded to a winner, retained so the choice is explainable. */
+  readonly dropped: readonly { readonly item: ScoredForResolution; readonly toType: EntityType }[];
+}
+
+function overlaps(a: PipelineCandidate, b: PipelineCandidate): boolean {
+  return a.start < b.end && b.start < a.end;
+}
+
+function width(item: ScoredForResolution): number {
+  return item.candidate.end - item.candidate.start;
+}
+
+/**
+ * Resolve a candidate set into a non-overlapping one.
+ *
+ * Greedy by the ordering above. Because the widest span is always taken
+ * first, any candidate it contains is dropped only after its characters are
+ * already covered — which is what makes the coverage property hold rather
+ * than merely being hoped for.
+ *
+ * Non-sensitive candidates (known test values) never displace a sensitive
+ * one: they are detected so the eval can assert they were seen, and letting
+ * one win an overlap would unmask the value it covers.
+ */
+export function resolveOverlaps(items: readonly ScoredForResolution[]): ResolutionResult {
+  const ordered = [...items].sort((a, b) => {
+    // Sensitive first: a non-sensitive candidate must never displace one that
+    // would otherwise be masked.
+    if (a.candidate.sensitive !== b.candidate.sensitive) return a.candidate.sensitive ? -1 : 1;
+    const byWidth = width(b) - width(a);
+    if (byWidth !== 0) return byWidth;
+    const bySpecificity = specificityOf(a.candidate.type) - specificityOf(b.candidate.type);
+    if (bySpecificity !== 0) return bySpecificity;
+    const byConfidence = b.confidence - a.confidence;
+    if (byConfidence !== 0) return byConfidence;
+    // Total order, so the result cannot depend on input order.
+    return a.candidate.start - b.candidate.start || a.candidate.detectorId.localeCompare(b.candidate.detectorId);
+  });
+
+  const emitted: ScoredForResolution[] = [];
+  const dropped: { item: ScoredForResolution; toType: EntityType }[] = [];
+
+  for (const item of ordered) {
+    const at = emitted.findIndex((kept) => overlaps(kept.candidate, item.candidate));
+    if (at === -1) {
+      emitted.push(item);
+      continue;
+    }
+
+    const winner = emitted[at]!;
+    const contained =
+      winner.candidate.start <= item.candidate.start && item.candidate.end <= winner.candidate.end;
+
+    // CONTAINED: the winner already covers every character, so dropping the
+    // loser costs nothing but a label.
+    if (contained || !item.candidate.sensitive) {
+      dropped.push({ item, toType: winner.candidate.type });
+      continue;
+    }
+
+    // PARTIAL: the loser extends beyond the winner, so dropping it would
+    // leave the overhang unmasked. Measured on the corpus, this is rare (8
+    // spans in 2,600 documents, every one a Korean street address abutting
+    // another entity) but it is a leak, not a mislabelling. The winner
+    // absorbs the union instead.
+    //
+    // Widening in BOTH coordinate spaces is sound without re-consulting the
+    // offset map: the map is monotonic, so the union of two mapped spans
+    // contains the mapping of the union, and erring wider only ever masks
+    // more.
+    emitted[at] = {
+      ...winner,
+      candidate: {
+        ...winner.candidate,
+        start: Math.min(winner.candidate.start, item.candidate.start),
+        end: Math.max(winner.candidate.end, item.candidate.end),
+        originalStart: Math.min(winner.candidate.originalStart, item.candidate.originalStart),
+        originalEnd: Math.max(winner.candidate.originalEnd, item.candidate.originalEnd),
+      },
+    };
+    dropped.push({ item, toType: winner.candidate.type });
+  }
+
+  emitted.sort((a, b) => a.candidate.start - b.candidate.start);
+  return { emitted, dropped };
+}
+
+/**
+ * Every character a sensitive candidate covered is still covered.
+ *
+ * The invariant resolution exists to preserve, exposed so callers and tests
+ * can assert it directly rather than trusting the ordering to imply it.
+ */
+export function coverageHoles(
+  before: readonly ScoredForResolution[],
+  after: readonly ScoredForResolution[],
+): { readonly start: number; readonly end: number }[] {
+  const covered = after
+    .filter((i) => i.candidate.sensitive)
+    .map((i) => ({ start: i.candidate.start, end: i.candidate.end }))
+    .sort((a, b) => a.start - b.start);
+
+  const holes: { start: number; end: number }[] = [];
+  for (const item of before) {
+    if (!item.candidate.sensitive) continue;
+    let cursor = item.candidate.start;
+    for (const span of covered) {
+      if (span.end <= cursor) continue;
+      if (span.start > cursor) break;
+      cursor = Math.max(cursor, span.end);
+      if (cursor >= item.candidate.end) break;
+    }
+    if (cursor < item.candidate.end) holes.push({ start: cursor, end: item.candidate.end });
+  }
+  return holes;
+}

package/src/gazetteer/index.ts

@@ -0,0 +1,139 @@
+/**
+ * Stage 2b — GAZETTEER lookup.
+ *
+ * SPEC.md: "Bundled compressed lookup sets, checked in parallel with the
+ * model … Gazetteer hit alone is medium confidence; gazetteer plus model
+ * agreement is high."
+ *
+ * The bundled sets are Bloom filters (see `@discretion/data`'s
+ * gazetteers.ts for why). Two consequences shape this module:
+ *
+ *   • A filter can report a false POSITIVE and never a false negative. So a
+ *     hit is corroboration, never proof — which is exactly the weight SPEC.md
+ *     assigns it — while a miss is conclusive.
+ *   • The hash here must match the builder's byte for byte, so it is written
+ *     out explicitly rather than pulled from a library that might change.
+ */
+
+import { GAZETTEERS, type GazetteerFilter } from '@discretion/data';
+import type { EntityType } from '../types.js';
+
+/** Entity types a gazetteer can speak to. */
+export type GazetteerType = 'PERSON' | 'ORG' | 'LOCATION';
+
+const GAZETTEER_TYPES: readonly GazetteerType[] = ['PERSON', 'ORG', 'LOCATION'];
+
+export function isGazetteerType(type: EntityType): type is GazetteerType {
+  return (GAZETTEER_TYPES as readonly string[]).includes(type);
+}
+
+/**
+ * Fold a value for lookup: lowercase, then strip combining marks.
+ *
+ * Identical to the trigger matcher's folding, and to the builder's. Case fold
+ * precedes mark stripping so Turkish dotted capital I resolves correctly.
+ */
+function fold(value: string): string {
+  return value.toLowerCase().normalize('NFD').replace(/\p{M}+/gu, '').normalize('NFC').trim();
+}
+
+/** FNV-1a with two seeds, then double hashing. Must match the builder. */
+function hashPair(value: string): readonly [number, number] {
+  let a = 0x811c9dc5;
+  let b = 0x01000193;
+  for (let i = 0; i < value.length; i += 1) {
+    const c = value.charCodeAt(i);
+    a = Math.imul(a ^ c, 0x01000193) >>> 0;
+    b = Math.imul(b ^ (c + 0x9e3779b9), 0x85ebca6b) >>> 0;
+  }
+  return [a >>> 0, (b || 1) >>> 0];
+}
+
+function decode(base64: string): Uint8Array {
+  // atob is available in browsers and in Node 16+, and keeps core free of
+  // Node-only APIs (`Buffer`), which its eslint config bans.
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+
+class BloomSet {
+  private readonly bytes: Uint8Array;
+
+  constructor(private readonly filter: GazetteerFilter) {
+    this.bytes = decode(filter.base64);
+  }
+
+  has(folded: string): boolean {
+    const [h1, h2] = hashPair(folded);
+    for (let i = 0; i < this.filter.k; i += 1) {
+      const bit = ((h1 + Math.imul(i, h2)) >>> 0) % this.filter.bits;
+      if ((this.bytes[bit >>> 3]! & (1 << (bit & 7))) === 0) return false;
+    }
+    return true;
+  }
+}
+
+/**
+ * Filters are decoded on first use and cached.
+ *
+ * Decoding all three eagerly costs about 2 MB of base64 work at import time,
+ * which a consumer that never runs Stage 2b should not pay.
+ */
+const decoded = new Map<GazetteerType, BloomSet>();
+
+function setFor(type: GazetteerType): BloomSet {
+  const cached = decoded.get(type);
+  if (cached !== undefined) return cached;
+  const built = new BloomSet(GAZETTEERS[type]);
+  decoded.set(type, built);
+  return built;
+}
+
+/** How a value matched the gazetteer. */
+export interface GazetteerHit {
+  readonly type: GazetteerType;
+  /** True when the whole value matched, rather than one of its words. */
+  readonly whole: boolean;
+  /** Number of the value's words that matched, for multi-word names. */
+  readonly matchedWords: number;
+  readonly totalWords: number;
+}
+
+/** Longest multi-word span the gazetteer will consider as a single name. */
+const MAX_WORDS = 5;
+
+/**
+ * Look a value up as `type`.
+ *
+ * A person's full name is rarely a single gazetteer entry — the sets hold
+ * given names and family names separately — so a multi-word value is checked
+ * whole first, then word by word. `matchedWords` lets the caller weigh
+ * "every word is a known name" differently from "one word out of four is".
+ */
+export function lookupGazetteer(value: string, type: GazetteerType): GazetteerHit | undefined {
+  const folded = fold(value);
+  if (folded.length < 2) return undefined;
+
+  const set = setFor(type);
+  const words = folded.split(/\s+/).filter((w) => w.length >= 2);
+  if (words.length === 0 || words.length > MAX_WORDS) return undefined;
+
+  if (set.has(folded)) {
+    return { type, whole: true, matchedWords: words.length, totalWords: words.length };
+  }
+
+  const matchedWords = words.filter((w) => set.has(w)).length;
+  if (matchedWords === 0) return undefined;
+  return { type, whole: false, matchedWords, totalWords: words.length };
+}
+
+/** Entry counts per set, for reporting and for BENCHMARKS.md. */
+export function gazetteerSizes(): Readonly<Record<GazetteerType, number>> {
+  return {
+    PERSON: GAZETTEERS.PERSON.entries,
+    ORG: GAZETTEERS.ORG.entries,
+    LOCATION: GAZETTEERS.LOCATION.entries,
+  };
+}

package/src/generate/bankcodes.ts

@@ -0,0 +1,82 @@
+/**
+ * Valid-value generators for the national bank-code family.
+ *
+ * US routing numbers carry the ABA checksum, so their property test runs the
+ * full mutation half. The rest are structure-only formats (stated in each
+ * detector); their properties assert validation without mutation.
+ */
+
+import { abaCheckDigit } from '../checksums/index.js';
+import { mulberry32 } from './prng.js';
+
+function pick<T>(rng: () => number, items: readonly T[]): T {
+  return items[Math.floor(rng() * items.length)]!;
+}
+
+function int(rng: () => number, min: number, max: number): number {
+  return min + Math.floor(rng() * (max - min + 1));
+}
+
+function digits(rng: () => number, count: number): string {
+  let out = '';
+  for (let i = 0; i < count; i++) out += String(int(rng, 0, 9));
+  return out;
+}
+
+/** Valid Federal Reserve prefixes (mirrors the detector's rule). */
+const FRB_PREFIXES = [
+  ...Array.from({ length: 12 }, (_, i) => i + 1),
+  ...Array.from({ length: 12 }, (_, i) => i + 21),
+  ...Array.from({ length: 12 }, (_, i) => i + 61),
+  80,
+];
+
+/** An ABA-checksummed routing number with a valid FRB prefix. */
+export function generateValidRouting(seed: number): string {
+  const rng = mulberry32(seed);
+  const prefix = String(pick(rng, FRB_PREFIXES)).padStart(2, '0');
+  const payload = prefix + digits(rng, 6);
+  return `${payload}${abaCheckDigit(payload)!}`;
+}
+
+/** A UK sort code in 00-00-00 notation (no checksum exists). */
+export function generateValidSortCode(seed: number): string {
+  const rng = mulberry32(seed);
+  return `${digits(rng, 2)}-${digits(rng, 2)}-${digits(rng, 2)}`;
+}
+
+/** Institution numbers mirrored from the detector's Payments Canada table. */
+const CA_INSTITUTIONS = ['001', '002', '003', '004', '006', '010', '016', '030', '219', '614', '623', '809', '815', '837'];
+
+/** A Canadian transit number with a known institution. */
+export function generateValidTransit(seed: number): string {
+  const rng = mulberry32(seed);
+  return `${digits(rng, 5)}-${pick(rng, CA_INSTITUTIONS)}`;
+}
+
+/** An Australian BSB in XXX-XXX notation (no checksum exists). */
+export function generateValidBsb(seed: number): string {
+  const rng = mulberry32(seed);
+  return `${digits(rng, 3)}-${digits(rng, 3)}`;
+}
+
+const LETTERS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
+
+/** An IFSC with the mandatory zero and at least one digit in the branch. */
+export function generateValidIfsc(seed: number): string {
+  const rng = mulberry32(seed);
+  let bank = '';
+  for (let i = 0; i < 4; i++) bank += LETTERS[int(rng, 0, 25)]!;
+  // Branch: mostly numeric, as issued in practice; always ≥1 digit.
+  return `${bank}0${digits(rng, 6)}`;
+}
+
+const AGENCIA_LABELS = ['ag.', 'Ag.', 'agência', 'Agência', 'agencia', 'ag'];
+
+/** A labeled Brazilian agência, sometimes with its display check digit. */
+export function generateValidAgencia(seed: number): string {
+  const rng = mulberry32(seed);
+  const label = pick(rng, AGENCIA_LABELS);
+  const check = rng() < 0.4 ? `-${int(rng, 0, 9)}` : '';
+  return `${label} ${digits(rng, 4)}${check}`;
+}

package/src/generate/contact.ts

@@ -0,0 +1,147 @@
+/**
+ * Valid-value generators for the contact & network family.
+ *
+ * Deterministic by seed, never call the validators they feed (no
+ * circularity), and are reused by M3's corpus generator. None of these
+ * formats carries a checksum, so the paired property tests assert
+ * "generated value always validates" without the single-character-mutation
+ * half — a mutated email or IP is usually still a valid email or IP.
+ */
+
+import { mulberry32 } from './prng.js';
+
+function pick<T>(rng: () => number, items: readonly T[]): T {
+  return items[Math.floor(rng() * items.length)]!;
+}
+
+function int(rng: () => number, min: number, max: number): number {
+  return min + Math.floor(rng() * (max - min + 1));
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Email
+// ─────────────────────────────────────────────────────────────────────────────
+
+const LOCALS = [
+  'john.doe', 'jane_doe', 'a', 'user+tag', 'dev-ops', "o'brien", 'x.y.z',
+  'müller', 'björn.b', 'test123', 'first.middle.last', '_service',
+];
+const DOMAINS = [
+  'gmail.com', 'yandex.ru', 'firma.de', 'corp.co.uk', 'startup.io',
+  'münchen.de', 'xn--bcher-kva.de', 'sub.domain.net', 'a-b.org', 'q2.dev',
+];
+
+/** A structurally valid, non-reserved-domain email address. */
+export function generateValidEmail(seed: number): string {
+  const rng = mulberry32(seed);
+  return `${pick(rng, LOCALS)}@${pick(rng, DOMAINS)}`;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Phone
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Known-valid E.164 numbers across plans and regions. Sources: numbers in
+ * ranges reserved for fiction/drama (UK Ofcom 7946 09xx, US 555-01xx) and
+ * carrier example shapes that satisfy libphonenumber's full-metadata
+ * isValid(). The pool is itself pinned by a test, so a metadata update that
+ * invalidates an entry fails loudly there rather than silently in the
+ * property test.
+ */
+export const VALID_E164_POOL: readonly string[] = [
+  '+12125550123', // US, NANP fictional range
+  '+14155550198', // US
+  '+442079460958', // UK, Ofcom drama range (London)
+  '+447911123456', // UK mobile
+  '+905321234567', // TR mobile
+  '+4915123456789', // DE mobile
+  '+33612345678', // FR mobile
+  '+61412345678', // AU mobile
+  '+819012345678', // JP mobile
+  '+558121345678', // BR
+  '+8613912345678', // CN mobile
+  '+918527012345', // IN mobile
+];
+
+/** A valid phone number, formatted variably (E.164, spaced, punctuated). */
+export function generateValidPhone(seed: number): string {
+  const rng = mulberry32(seed);
+  const e164 = pick(rng, VALID_E164_POOL);
+  const style = int(rng, 0, 2);
+  if (style === 0) return e164;
+  const cc = e164.slice(0, e164.length - 10 >= 2 ? e164.length - 10 : 3);
+  const rest = e164.slice(cc.length);
+  if (style === 1) {
+    // Space-grouped: +90 532 123 45 67 style.
+    const parts: string[] = [];
+    for (let i = 0; i < rest.length; i += 3) parts.push(rest.slice(i, i + 3));
+    return `${cc} ${parts.join(' ')}`;
+  }
+  // Hyphen-grouped.
+  const mid = Math.floor(rest.length / 2);
+  return `${cc} ${rest.slice(0, mid)}-${rest.slice(mid)}`;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// IP addresses
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** A valid IPv4 address (octets 1–254 to stay clear of edge constants). */
+export function generateValidIpv4(seed: number): string {
+  const rng = mulberry32(seed);
+  return [int(rng, 1, 223), int(rng, 0, 254), int(rng, 0, 254), int(rng, 1, 254)].join('.');
+}
+
+/** A valid IPv6 address, sometimes zero-compressed, never unspecified. */
+export function generateValidIpv6(seed: number): string {
+  const rng = mulberry32(seed);
+  const groups: number[] = [];
+  for (let i = 0; i < 8; i++) groups.push(int(rng, 0, 0xffff));
+  if (groups[0] === 0) groups[0] = 0x2001; // never all-zero / leading-zero edge
+  // Half the time, zero a run and write it compressed.
+  if (rng() < 0.5) {
+    const start = int(rng, 2, 5);
+    const len = int(rng, 2, 3);
+    for (let i = start; i < Math.min(start + len, 8); i++) groups[i] = 0;
+    const hex = groups.map((g) => g.toString(16));
+    return `${hex.slice(0, start).join(':')}::${hex.slice(Math.min(start + len, 8)).join(':')}`;
+  }
+  return groups.map((g) => g.toString(16)).join(':');
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// MAC
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** A valid MAC in colon, hyphen, or Cisco notation. Never all-00/all-ff. */
+export function generateValidMac(seed: number): string {
+  const rng = mulberry32(seed);
+  const bytes: number[] = [];
+  for (let i = 0; i < 6; i++) bytes.push(int(rng, 0, 255));
+  bytes[2] = int(rng, 1, 254); // guarantees neither all-zero nor all-ff
+  const hex = bytes.map((b) => b.toString(16).padStart(2, '0'));
+  const style = int(rng, 0, 2);
+  if (style === 0) return hex.join(':');
+  if (style === 1) return hex.join('-').toUpperCase();
+  const h = hex.join('');
+  return `${h.slice(0, 4)}.${h.slice(4, 8)}.${h.slice(8, 12)}`;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// URL with credentials
+// ─────────────────────────────────────────────────────────────────────────────
+
+const CRED_USERS = ['admin', 'deploy', 'svc-backup', 'root', 'ci'];
+const CRED_PASSWORDS = ['hunter2secret', 'P4ssw0rd!x', 'tOk3n-v4lue-9', 's3cr3t_key_77'];
+const CRED_HOSTS = ['db.internal.corp', 'api.prod.net', 'cache.svc.local', 'build.ci.dev'];
+const CRED_PARAMS = ['token', 'api_key', 'access_token', 'client_secret'];
+
+/** A URL that genuinely carries a credential (userinfo or query form). */
+export function generateValidCredentialUrl(seed: number): string {
+  const rng = mulberry32(seed);
+  if (rng() < 0.5) {
+    return `https://${pick(rng, CRED_USERS)}:${pick(rng, CRED_PASSWORDS)}@${pick(rng, CRED_HOSTS)}/app`;
+  }
+  return `https://${pick(rng, CRED_HOSTS)}/v1/data?${pick(rng, CRED_PARAMS)}=Ab9${Math.floor(rng() * 1e12).toString(36)}xQ7tk`;
+}