@nanobpm/urban 0.66.1 → 0.67.0

package/src/context/pii/classifier.test.ts

@@ -0,0 +1,183 @@
+// Unit tests for the PII classifier (slice S6 core). Run via
+// `npm run test --workspace @nanobpm/urban` (node --test, src/**/*.test.ts).
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { classifyPii, isPiiClean, type PiiCandidate, type PiiKind } from "./classifier.ts";
+import { MEMORY_RECORD_SCHEMA_VERSION, type MemoryRecord } from "../schema/index.ts";
+
+function record(overrides: Partial<MemoryRecord> = {}): MemoryRecord {
+  const full: MemoryRecord = {
+    schemaVersion: MEMORY_RECORD_SCHEMA_VERSION,
+    id: "rec-1",
+    scope: "repo",
+    mode: "empirical",
+    provenance: "human",
+    authority: "authoritative",
+    statement: "the build is green after fixing the test failure",
+    createdAt: "2026-08-19T14:00:00.000Z",
+  };
+  return { ...full, ...overrides };
+}
+
+function kinds(input: PiiCandidate): PiiKind[] {
+  const r = classifyPii(input);
+  return r.clean ? [] : r.findings.map((f) => f.kind);
+}
+
+test("clean record classifies clean", () => {
+  const result = classifyPii(record());
+  assert.equal(result.clean, true);
+  assert.deepEqual(result.findings, []);
+  assert.equal(isPiiClean(record()), true);
+});
+
+test("numeric and timestamp fields never false-positive", () => {
+  // schemaVersion (number) and createdAt (ISO 4-2-2) must not trip phone/ssn/date detectors.
+  const result = classifyPii(record({ statement: "shipped at 2026-08-19T14:00:00.000Z, v1.2.3" }));
+  assert.equal(result.clean, true);
+});
+
+test("detects a plain email", () => {
+  assert.ok(kinds("contact alice@example.com for details").includes("email"));
+});
+
+test("detects obfuscated emails", () => {
+  assert.ok(kinds("reach alice (at) example dot com").includes("email"));
+  assert.ok(kinds("reach alice[at]example[dot]com").includes("email"));
+  assert.ok(kinds("reach alice AT example DOT com").includes("email"));
+});
+
+test("reports BOTH plain and obfuscated emails in the same field", () => {
+  // A plain email must not suppress obfuscated hits elsewhere in the same field:
+  // the dedupe is per-location, not a field-wide "already saw an email" flag.
+  const result = classifyPii("alice@example.com and reach bob (at) example dot com");
+  assert.equal(result.clean, false);
+  if (!result.clean) {
+    const emails = result.findings.filter((f) => f.kind === "email");
+    assert.equal(emails.length, 2);
+    assert.ok(emails.some((f) => f.reason === "email address"));
+    assert.ok(emails.some((f) => f.reason === "obfuscated email address"));
+  }
+});
+
+test("detects US SSN", () => {
+  assert.ok(kinds("ssn 123-45-6789 on file").includes("ssn"));
+});
+
+test("detects phone numbers but not ISO timestamps", () => {
+  assert.ok(kinds("call +1 (415) 555-0132 tomorrow").includes("phone"));
+  assert.ok(kinds("call 415-555-0132").includes("phone"));
+  assert.equal(kinds("2026-08-19T14:00:00").includes("phone"), false);
+});
+
+test("detects Luhn-valid credit-card numbers, ignores random digit runs", () => {
+  // 4242 4242 4242 4242 is a Luhn-valid test card.
+  assert.ok(kinds("card 4242 4242 4242 4242 expires soon").includes("credit-card"));
+  // A 16-digit non-Luhn run must NOT be flagged as a card.
+  assert.equal(kinds("ticket 1234123412341234 in tracker").includes("credit-card"), false);
+});
+
+test("detects IPv4 addresses with valid octets only", () => {
+  assert.ok(kinds("connect to 192.168.1.10").includes("ip-address"));
+  // 999 is out of range — not a valid octet.
+  assert.equal(kinds("version 999.1.1.1").includes("ip-address"), false);
+});
+
+test("detects secrets: AWS key id, private key, JWT", () => {
+  assert.ok(kinds("AKIAIOSFODNN7EXAMPLE").includes("aws-access-key-id"));
+  assert.ok(kinds("-----BEGIN RSA PRIVATE KEY-----\nMIIE...").includes("private-key"));
+  // Build the JWT from real base64url-encoded JSON segments at runtime. A literal
+  // eyJ...eyJ... token is rewritten to `******` by secret-masking in diffs/tooling,
+  // which hid from reviewers that this test exercises the detector at all. Deriving
+  // it keeps the source diff reviewable while still matching the JWT pattern.
+  const seg = (o: unknown): string => Buffer.from(JSON.stringify(o)).toString("base64url");
+  const jwt = [seg({ alg: "HS256", typ: "JWT" }), seg({ sub: "test-subject" }), "c2lnbmF0dXJlXY"].join(".");
+  assert.ok(kinds(`token ${jwt}`).includes("jwt"));
+});
+
+test("scans every string field of a record and reports its path", () => {
+  const result = classifyPii(
+    record({ statement: "no pii here", subject: "email bob@corp.example.org" }),
+  );
+  assert.equal(result.clean, false);
+  if (!result.clean) {
+    const emailFinding = result.findings.find((f) => f.kind === "email");
+    assert.ok(emailFinding);
+    assert.equal(emailFinding?.path, "subject");
+  }
+});
+
+test("scans string-array fields (evidence[]) with an indexed path", () => {
+  const result = classifyPii(record({ evidence: ["ok", "ssn 123-45-6789"] }));
+  assert.equal(result.clean, false);
+  if (!result.clean) {
+    const finding = result.findings.find((f) => f.kind === "ssn");
+    assert.equal(finding?.path, "evidence.1");
+  }
+});
+
+test("walks nested objects (no shallow false-negative through the guard)", () => {
+  const result = classifyPii({ meta: { contact: { email: "alice@example.com" } } });
+  assert.equal(result.clean, false);
+  if (!result.clean) {
+    const finding = result.findings.find((f) => f.kind === "email");
+    assert.equal(finding?.path, "meta.contact.email");
+  }
+});
+
+test("walks arrays of nested objects with a fully indexed path", () => {
+  const result = classifyPii({ items: [{ note: "ok" }, { note: "ssn 123-45-6789" }] });
+  assert.equal(result.clean, false);
+  if (!result.clean) {
+    const finding = result.findings.find((f) => f.kind === "ssn");
+    assert.equal(finding?.path, "items.1.note");
+  }
+});
+
+test("obfuscated-email finding index maps back to the original text offset", () => {
+  const text = "reach alice (at) example dot com now";
+  const result = classifyPii(text);
+  assert.equal(result.clean, false);
+  if (!result.clean) {
+    const finding = result.findings.find((f) => f.reason === "obfuscated email address");
+    assert.ok(finding);
+    // Must locate the value in the ORIGINAL text, not the shorter normalised copy.
+    assert.equal(finding?.index, text.indexOf("alice"));
+  }
+});
+
+test("findings are located and redacted, never re-leaking the value", () => {
+  const value = "alice@example.com";
+  const result = classifyPii(`email ${value}`);
+  assert.equal(result.clean, false);
+  if (!result.clean) {
+    const f = result.findings[0];
+    assert.equal(typeof f.index, "number");
+    assert.ok(f.index >= 0);
+    assert.equal(f.excerpt.includes(value), false);
+    // Defect class: the excerpt must not leak ANY 2-char run of the value — not
+    // just the whole string. A first/last-character redaction would slip through
+    // an `includes(value)` check while still surfacing part of the secret.
+    for (let i = 0; i + 2 <= value.length; i++) {
+      assert.equal(
+        f.excerpt.includes(value.slice(i, i + 2)),
+        false,
+        `excerpt leaked substring "${value.slice(i, i + 2)}"`,
+      );
+    }
+  }
+});
+
+test("reports multiple occurrences", () => {
+  const result = classifyPii("a@x.com and b@y.com");
+  assert.equal(result.clean, false);
+  if (!result.clean) {
+    assert.ok(result.findings.filter((f) => f.kind === "email").length >= 2);
+  }
+});
+
+test("is pure — repeated calls on the same input are identical", () => {
+  const input = record({ statement: "phone 415-555-0132" });
+  assert.deepEqual(classifyPii(input), classifyPii(input));
+});

package/src/context/pii/classifier.ts

@@ -0,0 +1,321 @@
+// Slice S6 CORE (pii guard-core) — the PII *classifier*.
+//
+// A PURE, dependency-free function that inspects candidate memory-record content
+// and reports whether it carries personally-identifiable information (PII) or
+// PII-adjacent secrets. It is the analytical core the mandatory pre-commit guard
+// (`./guard.ts`) is built on: the guard decides *policy* (default-DENY), this
+// module decides *facts* (what looks like PII and where).
+//
+// Design goals:
+//  - PURE & deterministic: same input → same classification, no I/O, no state.
+//    Safe to call on a hot path (S3 runs it before every commit) and trivial to
+//    unit-test and reuse (the S6 CI slice reuses it to scan staged records).
+//  - By-construction MVP: the context substrate is *no-PII*, so the classifier
+//    is deliberately conservative-to-strict — it errs toward flagging obfuscated
+//    look-alikes (e.g. `name (at) host dot com`) because a false *positive* is a
+//    safe rejection while a false *negative* would launder PII into the record.
+//  - Located findings: every hit reports the field `path` and offset so callers
+//    (and humans) can see exactly what was flagged and why.
+
+import type { MemoryRecord } from "../schema/index.ts";
+
+/** The categories of PII / sensitive material the classifier recognises. */
+export type PiiKind =
+  | "email"
+  | "phone"
+  | "ssn"
+  | "credit-card"
+  | "ip-address"
+  | "aws-access-key-id"
+  | "private-key"
+  | "jwt";
+
+/** A single located detection. */
+export interface PiiFinding {
+  /** Which category matched. */
+  readonly kind: PiiKind;
+  /**
+   * Dotted path to the offending field within the candidate. Empty (`""`) when
+   * the candidate is a bare string. For array elements the index is appended,
+   * e.g. `evidence.0`.
+   */
+  readonly path: string;
+  /** Character offset of the match within that field's text. */
+  readonly index: number;
+  /**
+   * A length-only placeholder for the matched substring (e.g. `[redacted:17]`).
+   * Contains NO part of the value, so a finding can be logged/surfaced without
+   * re-leaking any character of the PII/secret it located.
+   */
+  readonly excerpt: string;
+  /** Human-readable explanation of why this was flagged. */
+  readonly reason: string;
+}
+
+/**
+ * The classification decision. `clean: true` means no PII was found; otherwise
+ * `findings` is a non-empty list of located detections.
+ */
+export type PiiClassification =
+  | { readonly clean: true; readonly findings: readonly [] }
+  | { readonly clean: false; readonly findings: readonly PiiFinding[] };
+
+/**
+ * Anything the classifier can inspect: a bare string, a {@link MemoryRecord}, or
+ * any plain object whose string / string-array properties should be scanned.
+ * Nested objects and arrays are walked recursively, so PII buried in a
+ * sub-object is still found; non-string leaf values (numbers, booleans, `null`)
+ * are ignored, so a record's numeric `schemaVersion` or an ISO `createdAt`
+ * timestamp never trips a false positive.
+ */
+export type PiiCandidate = string | MemoryRecord | Readonly<Record<string, unknown>>;
+
+// ---------------------------------------------------------------------------
+// Detectors
+// ---------------------------------------------------------------------------
+
+interface Detector {
+  readonly kind: PiiKind;
+  readonly reason: string;
+  readonly pattern: RegExp;
+  /** Optional extra guard to reject a syntactic match that is not real PII. */
+  readonly accept?: (match: string) => boolean;
+}
+
+function luhnValid(digits: string): boolean {
+  const only = digits.replace(/\D/g, "");
+  if (only.length < 13 || only.length > 19) return false;
+  let sum = 0;
+  let alternate = false;
+  for (let i = only.length - 1; i >= 0; i--) {
+    let n = only.charCodeAt(i) - 48;
+    if (alternate) {
+      n *= 2;
+      if (n > 9) n -= 9;
+    }
+    sum += n;
+    alternate = !alternate;
+  }
+  return sum % 10 === 0;
+}
+
+function validIpv4(match: string): boolean {
+  return match.split(".").every((octet) => {
+    const n = Number(octet);
+    return octet.length <= 3 && n >= 0 && n <= 255;
+  });
+}
+
+// Detectors run against the raw text. `pattern` MUST be global (`g`) so every
+// occurrence is reported, not just the first.
+const DETECTORS: readonly Detector[] = [
+  {
+    kind: "private-key",
+    reason: "PEM private-key block",
+    pattern: /-----BEGIN (?:RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----/g,
+  },
+  {
+    kind: "aws-access-key-id",
+    reason: "AWS access key id",
+    pattern: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g,
+  },
+  {
+    kind: "jwt",
+    reason: "JSON Web Token",
+    pattern: /\beyJ[A-Za-z0-9_-]{5,}\.eyJ[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}\b/g,
+  },
+  {
+    kind: "ssn",
+    reason: "US Social Security Number",
+    pattern: /\b\d{3}-\d{2}-\d{4}\b/g,
+  },
+  {
+    kind: "credit-card",
+    reason: "credit-card number (Luhn-valid)",
+    pattern: /\b(?:\d[ -]?){13,19}\b/g,
+    accept: luhnValid,
+  },
+  {
+    kind: "phone",
+    reason: "telephone number",
+    // Optional country code, then 3-3-4 grouping with separators — deliberately
+    // strict so ISO timestamps / ids (4-2-2, 3-1-1…) do not match.
+    pattern: /(?:\+?\d{1,3}[\s.-]?)?(?:\(\d{3}\)|\d{3})[\s.-]\d{3}[\s.-]\d{4}\b/g,
+  },
+  {
+    kind: "ip-address",
+    reason: "IPv4 address",
+    pattern: /\b(?:\d{1,3}\.){3}\d{1,3}\b/g,
+    accept: validIpv4,
+  },
+  {
+    kind: "email",
+    reason: "email address",
+    pattern: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g,
+  },
+];
+
+// Obfuscated-email detector. Real-world PII is often written to evade naive
+// scanners: `alice (at) example dot com`, `alice[at]example[dot]com`. We
+// normalise those spellings back to `@`/`.` on a COPY of the text and re-run the
+// plain email detector; a hit is reported at the original field. Because the
+// MVP is no-PII by construction we accept the (safe) risk of flagging a benign
+// "X at Y dot Z" phrase — a false positive is a rejected write, never a leak.
+//
+// The two obfuscation spellings are matched in ONE left-to-right pass (the `at`
+// alternation first, then `dot`) so a normalised offset can be mapped straight
+// back to the original text — a normalising `.replace()` chain would shift every
+// offset after a rewritten run and mis-locate the finding.
+const OBFUSCATION_TOKEN =
+  /(\s*[([{]?\s*(?:at|@)\s*[)\]}]?\s*)|(\s*[([{]?\s*(?:dot|\.)\s*[)\]}]?\s*)/gi;
+
+/**
+ * Normalise obfuscated `@`/`.` spellings back to their canonical characters.
+ * Returns the normalised text plus a `map` where `map[i]` is the index in the
+ * ORIGINAL text that normalised character `i` originated from, so a match found
+ * in the normalised copy can be reported at its true original offset.
+ */
+function deobfuscate(text: string): { text: string; map: number[] } {
+  let out = "";
+  const map: number[] = [];
+  let last = 0;
+  OBFUSCATION_TOKEN.lastIndex = 0;
+  let m: RegExpExecArray | null = OBFUSCATION_TOKEN.exec(text);
+  while (m !== null) {
+    for (let i = last; i < m.index; i++) {
+      out += text[i];
+      map.push(i);
+    }
+    out += m[1] !== undefined ? "@" : ".";
+    map.push(m.index);
+    last = m.index + m[0].length;
+    if (m.index === OBFUSCATION_TOKEN.lastIndex) OBFUSCATION_TOKEN.lastIndex++;
+    m = OBFUSCATION_TOKEN.exec(text);
+  }
+  for (let i = last; i < text.length; i++) {
+    out += text[i];
+    map.push(i);
+  }
+  return { text: out, map };
+}
+
+function redact(match: string): string {
+  // Findings are explicitly logged/surfaced, so the excerpt must never contain
+  // ANY part of the sensitive value — even the first/last characters would leak
+  // PII/secrets into logs. Emit a length-only placeholder: useful for
+  // debugging ("how long was it?") without re-leaking a single character.
+  return `[redacted:${match.trim().length}]`;
+}
+
+function scanText(path: string, text: string): PiiFinding[] {
+  const findings: PiiFinding[] = [];
+  for (const detector of DETECTORS) {
+    detector.pattern.lastIndex = 0;
+    let m: RegExpExecArray | null = detector.pattern.exec(text);
+    while (m !== null) {
+      const value = m[0];
+      if (!detector.accept || detector.accept(value)) {
+        findings.push({
+          kind: detector.kind,
+          path,
+          index: m.index,
+          excerpt: redact(value),
+          reason: detector.reason,
+        });
+      }
+      // Guard against zero-width matches looping forever.
+      if (m.index === detector.pattern.lastIndex) detector.pattern.lastIndex++;
+      m = detector.pattern.exec(text);
+    }
+  }
+
+  // Obfuscated email pass — only add hits the plain pass did not already report.
+  const { text: normalised, map } = deobfuscate(text);
+  if (normalised !== text) {
+    const emailDetector = DETECTORS.find((d) => d.kind === "email");
+    if (emailDetector) {
+      // Dedupe per LOCATION, not per field: a field-wide "already saw an email"
+      // flag would drop every obfuscated hit as soon as one plain email exists
+      // anywhere in the field (under-reporting a mixed plain+obfuscated field).
+      const plainEmailIndices = new Set(
+        findings.filter((f) => f.kind === "email").map((f) => f.index),
+      );
+      emailDetector.pattern.lastIndex = 0;
+      let em: RegExpExecArray | null = emailDetector.pattern.exec(normalised);
+      while (em !== null) {
+        // Map the offset in the normalised copy back to the original text so the
+        // finding is located where the obfuscated value actually is.
+        const originalIndex = map[em.index] ?? em.index;
+        if (!plainEmailIndices.has(originalIndex)) {
+          findings.push({
+            kind: "email",
+            path,
+            index: originalIndex,
+            excerpt: redact(em[0]),
+            reason: "obfuscated email address",
+          });
+        }
+        if (em.index === emailDetector.pattern.lastIndex) emailDetector.pattern.lastIndex++;
+        em = emailDetector.pattern.exec(normalised);
+      }
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * Flatten a candidate into the `(path, text)` fields the detectors scan. String
+ * leaves are scanned; every object / array is walked RECURSIVELY so PII nested
+ * inside sub-objects or arrays of objects cannot slip past the default-deny
+ * guard as a false negative. Non-string, non-container leaves (numbers,
+ * booleans, `null`) are ignored. A `WeakSet` breaks any accidental reference
+ * cycle so a self-referential candidate cannot loop forever.
+ */
+function collectFields(candidate: PiiCandidate): Array<{ path: string; text: string }> {
+  if (typeof candidate === "string") return [{ path: "", text: candidate }];
+  const fields: Array<{ path: string; text: string }> = [];
+  const seen = new WeakSet<object>();
+  const walk = (value: unknown, path: string): void => {
+    if (typeof value === "string") {
+      fields.push({ path, text: value });
+      return;
+    }
+    if (value === null || typeof value !== "object") return;
+    if (seen.has(value)) return;
+    seen.add(value);
+    if (Array.isArray(value)) {
+      value.forEach((entry, i) => walk(entry, path === "" ? `${i}` : `${path}.${i}`));
+      return;
+    }
+    for (const [key, v] of Object.entries(value)) {
+      walk(v, path === "" ? key : `${path}.${key}`);
+    }
+  };
+  for (const [key, value] of Object.entries(candidate)) {
+    walk(value, key);
+  }
+  return fields;
+}
+
+/**
+ * Classify a candidate for PII. PURE and deterministic — no I/O, no shared
+ * state. Returns `{ clean: true }` when nothing is found, otherwise
+ * `{ clean: false, findings }` with a located reason for every hit.
+ *
+ * Inspect a whole {@link MemoryRecord} (every string / string-array field is
+ * scanned), a single field's text, or any plain object.
+ */
+export function classifyPii(candidate: PiiCandidate): PiiClassification {
+  const findings: PiiFinding[] = [];
+  for (const { path, text } of collectFields(candidate)) {
+    findings.push(...scanText(path, text));
+  }
+  if (findings.length === 0) return { clean: true, findings: [] };
+  return { clean: false, findings };
+}
+
+/** Convenience predicate: `true` when the candidate carries no detected PII. */
+export function isPiiClean(candidate: PiiCandidate): boolean {
+  return classifyPii(candidate).clean;
+}

package/src/context/pii/guard.test.ts

@@ -0,0 +1,124 @@
+// Unit tests for the mandatory pre-commit PII guard (slice S6 core). Run via
+// `npm run test --workspace @nanobpm/urban` (node --test, src/**/*.test.ts).
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  preCommitPiiGuard,
+  createPiiGuard,
+  PiiGuardError,
+  type PiiGuard,
+} from "./guard.ts";
+import type { PiiFinding } from "./classifier.ts";
+import { MEMORY_RECORD_SCHEMA_VERSION, type MemoryRecord } from "../schema/index.ts";
+
+function record(overrides: Partial<MemoryRecord> = {}): MemoryRecord {
+  const full: MemoryRecord = {
+    schemaVersion: MEMORY_RECORD_SCHEMA_VERSION,
+    id: "rec-1",
+    scope: "repo",
+    mode: "empirical",
+    provenance: "human",
+    authority: "authoritative",
+    statement: "the release passed all gates",
+    createdAt: "2026-08-19T14:00:00.000Z",
+  };
+  return { ...full, ...overrides };
+}
+
+test("default guard passes clean content through (returns void)", () => {
+  assert.equal(preCommitPiiGuard.assert(record()), undefined);
+  assert.equal(preCommitPiiGuard.inspect(record()).clean, true);
+});
+
+test("default guard is default-DENY: rejects a PII-carrying record", () => {
+  assert.throws(
+    () => preCommitPiiGuard.assert(record({ statement: "owner alice@example.com approved" })),
+    PiiGuardError,
+  );
+});
+
+test("PiiGuardError carries the located findings", () => {
+  try {
+    preCommitPiiGuard.assert(record({ subject: "ssn 123-45-6789" }));
+    assert.fail("expected PiiGuardError");
+  } catch (err) {
+    assert.ok(err instanceof PiiGuardError);
+    assert.ok(err.findings.length >= 1);
+    assert.equal(err.findings[0].kind, "ssn");
+    assert.equal(err.findings[0].path, "subject");
+  }
+});
+
+test("guard rejects obfuscated PII too (evasion attempt)", () => {
+  assert.throws(
+    () => preCommitPiiGuard.assert("contact me: bob (at) corp dot com"),
+    PiiGuardError,
+  );
+});
+
+test("inspect is non-throwing and returns findings", () => {
+  const result = preCommitPiiGuard.inspect("card 4242 4242 4242 4242");
+  assert.equal(result.clean, false);
+  if (!result.clean) assert.equal(result.findings[0].kind, "credit-card");
+});
+
+test("createPiiGuard() with no options matches the default guard policy", () => {
+  const guard = createPiiGuard();
+  assert.equal(guard.name, "pre-commit-pii-guard");
+  assert.throws(() => guard.assert("email x@y.com"), PiiGuardError);
+  assert.doesNotThrow(() => guard.assert("nothing sensitive"));
+});
+
+test("guard name is overridable but policy stays default-DENY", () => {
+  const guard: PiiGuard = createPiiGuard({ name: "write-path-guard" });
+  assert.equal(guard.name, "write-path-guard");
+  assert.throws(() => guard.assert("ssn 123-45-6789"), PiiGuardError);
+});
+
+test("custom classifier override is still enforced as default-DENY", () => {
+  // A stricter policy that flags a banned word — proving the guard enforces
+  // whatever classifier it is given, and always denies on a non-clean result.
+  const guard = createPiiGuard({
+    classify: (c) =>
+      typeof c === "string" && c.includes("secret")
+        ? { clean: false, findings: [{ kind: "email", path: "", index: 0, excerpt: "***", reason: "banned" }] }
+        : { clean: true, findings: [] },
+  });
+  assert.throws(() => guard.assert("this is secret"), PiiGuardError);
+  assert.doesNotThrow(() => guard.assert("this is fine"));
+});
+
+test("classify override cannot disable the built-in default-DENY classifier", () => {
+  // An override that always reports clean must NOT be able to launder PII past
+  // the guard: the built-in classifier always runs and its findings are unioned.
+  const bypass = createPiiGuard({ classify: () => ({ clean: true, findings: [] }) });
+  assert.throws(() => bypass.assert("owner alice@example.com approved"), PiiGuardError);
+  const inspected = bypass.inspect("ssn 123-45-6789");
+  assert.equal(inspected.clean, false);
+});
+
+test("PiiGuardError defensively snapshots findings — caller mutation can't corrupt it", () => {
+  const findings: PiiFinding[] = [
+    { kind: "email", path: "", index: 0, excerpt: "***", reason: "x" },
+  ];
+  const err = new PiiGuardError(findings);
+  findings.pop();
+  findings.push({ kind: "ssn", path: "y", index: 1, excerpt: "###", reason: "z" });
+  assert.equal(err.findings.length, 1);
+  assert.equal(err.findings[0].kind, "email");
+});
+
+test("override reporting !clean with no findings throws a loud error, not an empty PiiGuardError", () => {
+  // Defect class: a buggy override that claims PII but locates nothing would
+  // otherwise make `assert` throw a PiiGuardError with an empty (contract says
+  // "never empty") findings array and a meaningless summary. The guard must
+  // surface that as a loud programming error instead — while never letting the
+  // write through (default-DENY is preserved).
+  const guard = createPiiGuard({ classify: () => ({ clean: false, findings: [] }) });
+  assert.throws(() => guard.assert("nothing sensitive"), (err: unknown) => {
+    assert.ok(err instanceof TypeError);
+    assert.ok(!(err instanceof PiiGuardError));
+    return true;
+  });
+});