@discretion/core 0.1.0

package/src/context/triggers.ts

@@ -0,0 +1,266 @@
+/**
+ * Stage 3, TRIGGER PROXIMITY.
+ *
+ * SPEC.md: "TRIGGER PROXIMITY — labels near the candidate, across many
+ * languages ('SSN', 'passport no', 'diagnosis', 'my name is', 'IBAN',
+ * 'kimlik', 'Personalausweis', '护照', 'паспорт', 'पासपोर्ट', and so on).
+ * Maintain the trigger lexicon as per-language data files, not inline code,
+ * so contributors can extend it. Cover at minimum the twenty most-spoken
+ * languages."
+ *
+ * This module is the MATCHER; the lexicons themselves live in
+ * `@discretion/data` as required. Two matching strategies run together
+ * because one alone cannot cover the world's scripts:
+ *
+ *   • Space-delimited scripts tokenize, then look up 1..4-word n-grams in a
+ *     hash map. Exact, and O(window) rather than O(window × terms).
+ *   • Scripts that do not space their words (Han, Kana, Hangul-adjacent
+ *     compounds, Thai, Khmer, Lao) cannot be tokenized that way, so their
+ *     terms are substring-searched instead. Keeping them in a separate,
+ *     much smaller list is what makes the substring pass affordable.
+ *
+ * Matching is case- and diacritic-insensitive: a form label reading "TCKN",
+ * "tckn" or "Tckn" is the same signal, and a user typing "numero" instead of
+ * "número" should not lose protection.
+ */
+
+import type { EntityType } from '../types.js';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Lexicon shape
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** One language's triggers, keyed by the entity type each vouches for. */
+export interface LanguageTriggers {
+  /** BCP-47 primary subtag, e.g. 'tr', 'zh', 'he'. */
+  readonly code: string;
+  readonly triggers: Readonly<Partial<Record<EntityType, readonly string[]>>>;
+}
+
+/** A trigger found near a candidate. */
+export interface TriggerMatch {
+  /** The lexicon term that matched, in its lexicon (folded) form. */
+  readonly term: string;
+  /** Entity types this term vouches for. */
+  readonly types: readonly EntityType[];
+  /** Characters between the trigger and the candidate. 0 when adjacent. */
+  readonly distance: number;
+  /** Language codes that contributed this term. */
+  readonly languages: readonly string[];
+}
+
+export interface TriggerIndex {
+  /** Number of distinct terms indexed, for reporting. */
+  readonly termCount: number;
+  /**
+   * Triggers found within `window` characters of the span, nearest first.
+   * Searching both sides matters: most languages label before the value
+   * ("SSN: …") but several place it after ("… کد ملی").
+   */
+  near(text: string, start: number, end: number, window?: number): readonly TriggerMatch[];
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Folding
+// ─────────────────────────────────────────────────────────────────────────────
+
+const COMBINING_MARKS = /\p{M}+/gu;
+
+/**
+ * Fold a string for comparison: lowercase, then strip combining marks via NFD.
+ *
+ * Order matters. Turkish 'İ' lowercases to 'i' + U+0307 COMBINING DOT ABOVE,
+ * so the mark strip has to come after the case fold to remove it.
+ */
+export function foldForMatch(value: string): string {
+  return value.toLowerCase().normalize('NFD').replace(COMBINING_MARKS, '').normalize('NFC');
+}
+
+/** Scripts whose text is not space-delimited, so n-gram lookup cannot see it. */
+const UNSPACED_SCRIPT = /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Thai}\p{Script=Khmer}\p{Script=Lao}\p{Script=Myanmar}]/u;
+
+/** Longest trigger, in words, that n-gram lookup will assemble. */
+const MAX_NGRAM_WORDS = 4;
+
+/** How far from the candidate a trigger still counts, in characters. */
+const DEFAULT_WINDOW = 64;
+
+/** Word characters for tokenizing space-delimited scripts. */
+const WORD_TOKEN = /[\p{L}\p{M}\p{N}_]+/gu;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Index construction
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface TermEntry {
+  readonly term: string;
+  readonly types: EntityType[];
+  readonly languages: string[];
+}
+
+interface Token {
+  readonly text: string;
+  readonly start: number;
+  readonly end: number;
+}
+
+/**
+ * Compile per-language lexicons into one index.
+ *
+ * All languages are matched at once rather than gated on a detected document
+ * language. That is deliberate: real messages mix languages (an English
+ * sentence quoting a German form label), language detection on a short chat
+ * message is unreliable, and a missed trigger costs recall on a privacy tool.
+ * The cost is that a term which is a common word in another language can
+ * mis-fire, which is why `near` reports what matched — Stage 3 weighs it,
+ * and the explanation records it.
+ */
+export function buildTriggerIndex(lexicons: readonly LanguageTriggers[]): TriggerIndex {
+  const spaced = new Map<string, TermEntry>();
+  const unspaced: TermEntry[] = [];
+
+  for (const lexicon of lexicons) {
+    for (const [type, terms] of Object.entries(lexicon.triggers)) {
+      for (const raw of terms ?? []) {
+        const term = foldForMatch(raw.trim());
+        if (term.length === 0) continue;
+        addTerm(term, type as EntityType, lexicon.code, spaced, unspaced);
+      }
+    }
+  }
+
+  // Longest first, so "kimlik no" wins over "kimlik" on the same text.
+  unspaced.sort((a, b) => b.term.length - a.term.length);
+
+  return {
+    termCount: spaced.size + unspaced.length,
+    near(text, start, end, window = DEFAULT_WINDOW) {
+      return findNear(text, start, end, window, spaced, unspaced);
+    },
+  };
+}
+
+function addTerm(
+  term: string,
+  type: EntityType,
+  language: string,
+  spaced: Map<string, TermEntry>,
+  unspaced: TermEntry[],
+): void {
+  if (UNSPACED_SCRIPT.test(term)) {
+    const existing = unspaced.find((e) => e.term === term);
+    mergeInto(existing ?? pushNew(unspaced, term), type, language);
+    return;
+  }
+  const existing = spaced.get(term);
+  if (existing === undefined) {
+    spaced.set(term, { term, types: [type], languages: [language] });
+    return;
+  }
+  mergeInto(existing, type, language);
+}
+
+function pushNew(list: TermEntry[], term: string): TermEntry {
+  const entry: TermEntry = { term, types: [], languages: [] };
+  list.push(entry);
+  return entry;
+}
+
+function mergeInto(entry: TermEntry, type: EntityType, language: string): void {
+  if (!entry.types.includes(type)) entry.types.push(type);
+  if (!entry.languages.includes(language)) entry.languages.push(language);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Lookup
+// ─────────────────────────────────────────────────────────────────────────────
+
+function findNear(
+  text: string,
+  start: number,
+  end: number,
+  window: number,
+  spaced: ReadonlyMap<string, TermEntry>,
+  unspaced: readonly TermEntry[],
+): TriggerMatch[] {
+  const from = Math.max(0, start - window);
+  const to = Math.min(text.length, end + window);
+  const before = foldForMatch(text.slice(from, start));
+  const after = foldForMatch(text.slice(end, to));
+
+  const matches: TriggerMatch[] = [];
+  collectSpaced(before, spaced, (entry, tokenEnd) =>
+    matches.push(toMatch(entry, before.length - tokenEnd)),
+  );
+  collectSpaced(after, spaced, (entry, _tokenEnd, tokenStart) =>
+    matches.push(toMatch(entry, tokenStart)),
+  );
+  collectUnspaced(before, unspaced, (entry, index) =>
+    matches.push(toMatch(entry, before.length - (index + entry.term.length))),
+  );
+  collectUnspaced(after, unspaced, (entry, index) => matches.push(toMatch(entry, index)));
+
+  matches.sort((a, b) => a.distance - b.distance);
+  return dedupe(matches);
+}
+
+function toMatch(entry: TermEntry, distance: number): TriggerMatch {
+  return {
+    term: entry.term,
+    types: entry.types,
+    languages: entry.languages,
+    distance: Math.max(0, distance),
+  };
+}
+
+/** Tokenize and probe every 1..MAX_NGRAM_WORDS window against the map. */
+function collectSpaced(
+  text: string,
+  spaced: ReadonlyMap<string, TermEntry>,
+  emit: (entry: TermEntry, tokenEnd: number, tokenStart: number) => void,
+): void {
+  const tokens = tokenize(text);
+  for (let i = 0; i < tokens.length; i += 1) {
+    for (let n = 1; n <= MAX_NGRAM_WORDS && i + n <= tokens.length; n += 1) {
+      const slice = tokens.slice(i, i + n);
+      const first = slice[0];
+      const last = slice[n - 1];
+      if (first === undefined || last === undefined) continue;
+      const entry = spaced.get(slice.map((t) => t.text).join(' '));
+      if (entry !== undefined) emit(entry, last.end, first.start);
+    }
+  }
+}
+
+function tokenize(text: string): Token[] {
+  const tokens: Token[] = [];
+  const pattern = new RegExp(WORD_TOKEN.source, WORD_TOKEN.flags);
+  let match: RegExpExecArray | null;
+  while ((match = pattern.exec(text)) !== null) {
+    tokens.push({ text: match[0], start: match.index, end: match.index + match[0].length });
+  }
+  return tokens;
+}
+
+function collectUnspaced(
+  text: string,
+  unspaced: readonly TermEntry[],
+  emit: (entry: TermEntry, index: number) => void,
+): void {
+  for (const entry of unspaced) {
+    const index = text.indexOf(entry.term);
+    if (index !== -1) emit(entry, index);
+  }
+}
+
+/** Keep the nearest occurrence of each distinct term. */
+function dedupe(matches: readonly TriggerMatch[]): TriggerMatch[] {
+  const seen = new Set<string>();
+  const out: TriggerMatch[] = [];
+  for (const match of matches) {
+    if (seen.has(match.term)) continue;
+    seen.add(match.term);
+    out.push(match);
+  }
+  return out;
+}

package/src/context/types.ts

@@ -0,0 +1,150 @@
+/**
+ * Stage 3 types.
+ *
+ * SPEC.md, Stage 3: "This is where false positives die, and the most
+ * important stage for real-world quality. Each candidate's confidence is
+ * adjusted by evidence from its surroundings."
+ *
+ * Two properties are load-bearing in the shapes below.
+ *
+ * EXPLAINABILITY. Every adjustment is a NAMED, SIGNED contribution rather
+ * than an opaque delta, so the adjusted score always decomposes into the
+ * reasons that produced it. Stage 4 (M8) calibrates these into probabilities
+ * and SPEC.md requires the review UI to show why an entity was reported; a
+ * score that cannot show its work would make both impossible.
+ *
+ * NO PLAINTEXT IN EXPLANATIONS. A contribution's `detail` may name the
+ * LEXICON TERM that matched ("iban", "kimlik no") but never the candidate's
+ * own text and never a raw document key, because explanations flow into
+ * reports and UI surfaces that must stay free of sensitive values — SPEC.md's
+ * third non-negotiable. `structure:*` contributions therefore report the key
+ * only when it matched a known lexicon term, and otherwise report the slot
+ * kind alone.
+ */
+
+import type { EntityType } from '../types.js';
+import type { Stage1Candidate } from '../detect/types.js';
+import type { Stage2Candidate } from '../ner/types.js';
+
+/** Any candidate entering Stage 3, from Stage 1 or Stage 2. */
+export type PipelineCandidate = Stage1Candidate | Stage2Candidate;
+
+/**
+ * The FORMAT of a document — how it is written, not what it is about.
+ *
+ * SPEC.md: "detect whether input is prose, source code (and which language),
+ * JSON, YAML, CSV, a log dump, a markdown table, or an email thread. Each
+ * mode shifts weights."
+ */
+export type DocumentFormat =
+  | 'prose'
+  | 'code'
+  | 'json'
+  | 'yaml'
+  | 'csv'
+  | 'log'
+  | 'markdown-table'
+  | 'email'
+  | 'unknown';
+
+/**
+ * The SUBJECT DOMAIN of a document, detected from terminology.
+ *
+ * Kept as a second, independent axis rather than folded into the format
+ * union: a medical record can arrive as prose, as CSV, or as a JSON payload,
+ * and collapsing the two would force a false choice. SPEC.md lists "medical,
+ * legal, and financial terminology used for context scoring" under the
+ * gazetteers, which is what feeds this.
+ */
+export type DocumentDomain = 'medical' | 'legal' | 'financial' | 'general';
+
+/** One named, signed reason the confidence moved. */
+export interface ContextContribution {
+  /** Stable signal name, e.g. `trigger:NATIONAL_ID`, `negative:uri-authority`. */
+  readonly signal: string;
+  /** Signed adjustment applied to the raw confidence. */
+  readonly delta: number;
+  /** Safe supporting detail — a lexicon term or rule name, never a value. */
+  readonly detail?: string;
+}
+
+/** A candidate after Stage 3, carrying its adjustment and its reasons. */
+export interface ContextScoredCandidate {
+  readonly candidate: PipelineCandidate;
+  /** Confidence after applying every contribution, clamped to [0, 1]. */
+  readonly contextConfidence: number;
+  readonly contributions: readonly ContextContribution[];
+  /**
+   * Stage 3 concluded this candidate should not be emitted at all.
+   *
+   * Suppression is reserved for evidence that the candidate is NOT sensitive
+   * (a documentation example, a value inside a URI's authority, a lab
+   * reference range) — never for mere weakness of evidence, which is what the
+   * confidence score is for.
+   */
+  readonly suppressed: boolean;
+  /** Rule id that suppressed it. Present exactly when `suppressed`. */
+  readonly suppressionReason?: string;
+}
+
+/** What Stage 3 learned about the document as a whole. */
+export interface DocumentProfile {
+  readonly format: DocumentFormat;
+  readonly domain: DocumentDomain;
+  /** Signals that decided the format, for reporting and debugging. */
+  readonly formatEvidence: readonly string[];
+  /** Domain terms that matched, for reporting. Lexicon terms only. */
+  readonly domainEvidence: readonly string[];
+}
+
+/**
+ * The evidence a rule sees about one candidate.
+ *
+ * Deliberately narrow: rules receive the document text and the candidate's
+ * span, not the other candidates. Reasoning about OTHER candidates' spans is
+ * overlap resolution, which SPEC.md assigns to Stage 4 — keeping it out of
+ * this interface is what stops Stage 3 quietly absorbing M8's job.
+ * Co-occurrence, the one signal that legitimately looks across candidates,
+ * runs as a separate pass with its own input.
+ */
+export interface RuleContext {
+  /** The full normalized document text. */
+  readonly text: string;
+  /** Candidate start offset in the normalized text (inclusive). */
+  readonly start: number;
+  /** Candidate end offset (exclusive). */
+  readonly end: number;
+  readonly type: EntityType;
+  readonly profile: DocumentProfile;
+  /** The line containing the candidate, and the candidate's offsets within it. */
+  readonly line: { readonly text: string; readonly start: number; readonly end: number };
+}
+
+/**
+ * A negative-context rule.
+ *
+ * SPEC.md: "NEGATIVE CONTEXT — signals that a candidate is NOT sensitive:
+ * inside a code comment describing a format, in a documentation example
+ * block, a known dummy value, lorem ipsum, a test fixture, a UUID in a log
+ * line, a git SHA. These must actively suppress."
+ *
+ * Each rule must state the real positive it risks suppressing, because in a
+ * privacy tool a wrong suppression is a leak, and an un-reviewed suppression
+ * rule is how leaks get shipped.
+ */
+export interface NegativeRule {
+  /** Stable id, surfaced as `negative:<id>` in contributions. */
+  readonly id: string;
+  /** Entity types this rule may act on, or `'all'`. */
+  readonly appliesTo: readonly EntityType[] | 'all';
+  /**
+   * `'suppress'` drops the candidate; a negative number reduces confidence.
+   * Prefer a penalty over suppression unless the evidence is conclusive.
+   */
+  readonly action: 'suppress' | number;
+  /** The general principle, quoted into ARCHITECTURE.md and reviewable. */
+  readonly principle: string;
+  /** What real positive this could wrongly suppress. Required, not optional. */
+  readonly risk: string;
+  test(ctx: RuleContext): boolean;
+}

package/src/crypto/keccak256.ts

@@ -0,0 +1,98 @@
+/**
+ * Keccak-256 — the ORIGINAL Keccak submission padding (0x01), NOT the
+ * standardized SHA3-256 (0x06). Ethereum's EIP-55 address checksum and
+ * Monero's address checksum both use original Keccak; using SHA3 here would
+ * silently break every EIP-55 verification while still "looking like a
+ * hash". The pinned vectors in test/crypto.test.ts are Keccak vectors
+ * specifically, so a padding mix-up cannot survive the tests.
+ *
+ * Lanes are BigInt: this is validation-only code on short inputs, and the
+ * BigInt formulation reads like the specification instead of like paired
+ * 32-bit register juggling.
+ */
+
+const MASK64 = (1n << 64n) - 1n;
+
+const ROUND_CONSTANTS: readonly bigint[] = [
+  0x0000000000000001n, 0x0000000000008082n, 0x800000000000808an, 0x8000000080008000n,
+  0x000000000000808bn, 0x0000000080000001n, 0x8000000080008081n, 0x8000000000008009n,
+  0x000000000000008an, 0x0000000000000088n, 0x0000000080008009n, 0x000000008000000an,
+  0x000000008000808bn, 0x800000000000008bn, 0x8000000000008089n, 0x8000000000008003n,
+  0x8000000000008002n, 0x8000000000000080n, 0x000000000000800an, 0x800000008000000an,
+  0x8000000080008081n, 0x8000000000008080n, 0x0000000080000001n, 0x8000000080008008n,
+];
+
+/** Rho rotation offsets, indexed x + 5y. */
+const RHO: readonly number[] = [
+  0, 1, 62, 28, 27,
+  36, 44, 6, 55, 20,
+  3, 10, 43, 25, 39,
+  41, 45, 15, 21, 8,
+  18, 2, 61, 56, 14,
+];
+
+const rotl = (a: bigint, n: number): bigint =>
+  ((a << BigInt(n)) | (a >> BigInt(64 - n))) & MASK64;
+
+function permute(state: bigint[]): void {
+  for (let round = 0; round < 24; round++) {
+    // θ
+    const c: bigint[] = [];
+    for (let x = 0; x < 5; x++) {
+      c.push(state[x]! ^ state[x + 5]! ^ state[x + 10]! ^ state[x + 15]! ^ state[x + 20]!);
+    }
+    for (let x = 0; x < 5; x++) {
+      const d = c[(x + 4) % 5]! ^ rotl(c[(x + 1) % 5]!, 1);
+      for (let y = 0; y < 25; y += 5) state[x + y] = state[x + y]! ^ d;
+    }
+    // ρ and π
+    const b: bigint[] = new Array<bigint>(25).fill(0n);
+    for (let x = 0; x < 5; x++) {
+      for (let y = 0; y < 5; y++) {
+        b[y + 5 * ((2 * x + 3 * y) % 5)] = rotl(state[x + 5 * y]!, RHO[x + 5 * y]!);
+      }
+    }
+    // χ
+    for (let x = 0; x < 5; x++) {
+      for (let y = 0; y < 25; y += 5) {
+        state[x + y] = b[x + y]! ^ (~b[((x + 1) % 5) + y]! & MASK64 & b[((x + 2) % 5) + y]!);
+      }
+    }
+    // ι
+    state[0] = state[0]! ^ ROUND_CONSTANTS[round]!;
+  }
+}
+
+const RATE = 136; // 1088-bit rate for 256-bit output
+
+/** Keccak-256 digest of `input`. */
+export function keccak256(input: Uint8Array): Uint8Array {
+  const state: bigint[] = new Array<bigint>(25).fill(0n);
+
+  // Multi-rate padding with the ORIGINAL 0x01 domain byte.
+  const padded = new Uint8Array(Math.ceil((input.length + 1) / RATE) * RATE);
+  padded.set(input);
+  padded[input.length] = 0x01;
+  padded[padded.length - 1] = padded[padded.length - 1]! | 0x80;
+
+  for (let off = 0; off < padded.length; off += RATE) {
+    for (let i = 0; i < RATE / 8; i++) {
+      let lane = 0n;
+      for (let b = 7; b >= 0; b--) {
+        lane = (lane << 8n) | BigInt(padded[off + i * 8 + b]!);
+      }
+      state[i] = state[i]! ^ lane;
+    }
+    permute(state);
+  }
+
+  const out = new Uint8Array(32);
+  for (let i = 0; i < 4; i++) {
+    let lane = state[i]!;
+    for (let b = 0; b < 8; b++) {
+      out[i * 8 + b] = Number(lane & 0xffn);
+      lane >>= 8n;
+    }
+  }
+  return out;
+}

package/src/crypto/sha256.ts

@@ -0,0 +1,76 @@
+/**
+ * SHA-256 (FIPS 180-4), pure TypeScript.
+ *
+ * Exists because base58check needs double-SHA-256 and `packages/core` is
+ * environment-agnostic: `node:crypto` is banned by the eslint fence and
+ * `crypto.subtle` is both a banned global and async. This implementation is
+ * VALIDATION-ONLY — it verifies checksums on candidate wallet addresses,
+ * never protects anything — so the correctness argument is the pinned NIST
+ * vectors in test/crypto.test.ts, not constant-time behaviour, which is
+ * irrelevant here.
+ */
+
+const K: readonly number[] = [
+  0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+  0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+  0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+  0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+  0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+  0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+  0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+  0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+];
+
+const rotr = (x: number, n: number): number => (x >>> n) | (x << (32 - n));
+
+/** SHA-256 digest of `input`. */
+export function sha256(input: Uint8Array): Uint8Array {
+  // Pad: append 0x80, zeros, then the 64-bit big-endian bit length.
+  const bitLen = input.length * 8;
+  const padded = new Uint8Array(((input.length + 8) >> 6 << 6) + 64);
+  padded.set(input);
+  padded[input.length] = 0x80;
+  const view = new DataView(padded.buffer);
+  view.setUint32(padded.length - 8, Math.floor(bitLen / 0x100000000), false);
+  view.setUint32(padded.length - 4, bitLen >>> 0, false);
+
+  let h0 = 0x6a09e667, h1 = 0xbb67ae85, h2 = 0x3c6ef372, h3 = 0xa54ff53a;
+  let h4 = 0x510e527f, h5 = 0x9b05688c, h6 = 0x1f83d9ab, h7 = 0x5be0cd19;
+
+  const w = new Int32Array(64);
+  for (let off = 0; off < padded.length; off += 64) {
+    for (let i = 0; i < 16; i++) w[i] = view.getUint32(off + i * 4, false);
+    for (let i = 16; i < 64; i++) {
+      const s0 = rotr(w[i - 15]!, 7) ^ rotr(w[i - 15]!, 18) ^ (w[i - 15]! >>> 3);
+      const s1 = rotr(w[i - 2]!, 17) ^ rotr(w[i - 2]!, 19) ^ (w[i - 2]! >>> 10);
+      w[i] = (w[i - 16]! + s0 + w[i - 7]! + s1) | 0;
+    }
+
+    let a = h0, b = h1, c = h2, d = h3, e = h4, f = h5, g = h6, h = h7;
+    for (let i = 0; i < 64; i++) {
+      const S1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+      const ch = (e & f) ^ (~e & g);
+      const t1 = (h + S1 + ch + K[i]! + w[i]!) | 0;
+      const S0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+      const maj = (a & b) ^ (a & c) ^ (b & c);
+      const t2 = (S0 + maj) | 0;
+      h = g; g = f; f = e; e = (d + t1) | 0;
+      d = c; c = b; b = a; a = (t1 + t2) | 0;
+    }
+
+    h0 = (h0 + a) | 0; h1 = (h1 + b) | 0; h2 = (h2 + c) | 0; h3 = (h3 + d) | 0;
+    h4 = (h4 + e) | 0; h5 = (h5 + f) | 0; h6 = (h6 + g) | 0; h7 = (h7 + h) | 0;
+  }
+
+  const out = new Uint8Array(32);
+  const outView = new DataView(out.buffer);
+  for (const [i, v] of [h0, h1, h2, h3, h4, h5, h6, h7].entries()) {
+    outView.setUint32(i * 4, v >>> 0, false);
+  }
+  return out;
+}
+
+/** Double SHA-256, the checksum base58check uses. */
+export function sha256d(input: Uint8Array): Uint8Array {
+  return sha256(sha256(input));
+}

package/src/detect/AUTHORING.md

@@ -0,0 +1,50 @@
+# Writing a Stage 1 detector
+
+Read this instead of re-reading SPEC.md. It is the whole contract.
+
+## One detector = one file
+
+`src/detect/detectors/<family>/<name>.ts` — exports nothing, self-registers:
+
+```ts
+registerDetector({
+  id: 'national-id-tr-tckn',       // kebab-case, unique, never churns
+  entityType: 'NATIONAL_ID',       // existing member — never add one
+  regions: ['TR'],                 // ISO alpha-2, or [GLOBAL_REGION]
+  pattern: /\b[1-9]\d{10}\b/g,     // MUST have /g. Over-generate.
+  baseConfidence: CONFIDENCE.HIGH, // reached only when validate() passes
+  description: 'One line.',
+  validate(ctx) {                  // ctx: text/start/end/match/defaultRegion
+    if (bad) return invalid('checksum failed'); // candidate DROPPED
+    return valid({ canonical, metadata: { scheme: 'tckn', country: 'TR' },
+                   validator: 'tckn-mod-10' });
+  },
+});
+```
+
+Imports: `registerDetector` from `../../registry.js`; `CONFIDENCE`,
+`GLOBAL_REGION`, `invalid`, `valid` from `../../types.js`. Then add one line
+to the family barrel: `import './tckn.js';`
+
+## Rules
+
+- Reuse `src/checksums/`. Missing algorithm → add it there with tests.
+- Wrong checksum = `invalid()`, not low confidence. No-checksum formats cap
+  at LOW/MEDIUM; context-dependent ones set `requiresContext: true`.
+- Known test/doc values: `valid({ sensitive: false })`.
+- No stubs, no truncated tables. Never put a matched value in a reason.
+- Strict TS; no DOM/Node globals in core; `.js` on relative imports.
+
+## Tests (`test/detectors-<family>.test.ts`) — per detector
+
+1. ≥3 valid vectors (published specimens preferred).
+2. Invalid vectors OUTNUMBERING valid: wrong check digit, transposition,
+   wrong length (short+long), wrong charset/prefix, cross-scheme near-miss.
+3. Property test: paired generator in `test/generators/<family>.ts` —
+   `generateValidX(seed): string`, deterministic, must NOT call the
+   validator. Generated always validates; single-char mutation fails (skip
+   mutation only for checksum-less formats — say so in a comment).
+4. Offset test: `runStage1(normalize(...))` with the value mid-sentence;
+   original span re-normalizes to exactly the value.
+
+Generators are reused by M3's corpus builder — export them cleanly.

package/src/detect/detectors/bankcodes/auBsb.ts

@@ -0,0 +1,36 @@
+/**
+ * AU_BSB — Australian Bank-State-Branch codes, XXX-XXX.
+ *
+ * There is NO checksum, and the folk "third digit is the state" rule has
+ * real exceptions (640-xxx and 80x-xxx exist), so encoding it would reject
+ * genuine BSBs. What remains trustworthy is the notation itself: the
+ * hyphenated 3-3 grouping is banking convention and little else. MEDIUM,
+ * structure-only, stated plainly — Stage 3 triggers ("BSB") do the rest.
+ */
+
+import { registerDetector } from '../../registry.js';
+import { CONFIDENCE, invalid, valid } from '../../types.js';
+import type { ValidationContext, ValidationResult } from '../../types.js';
+
+function validateBsb(ctx: ValidationContext): ValidationResult {
+  const before = ctx.start > 0 ? ctx.text[ctx.start - 1] : '';
+  if (/[\d-]/.test(before ?? '')) return invalid('fragment of a longer sequence');
+  const after = ctx.text.slice(ctx.end, ctx.end + 2);
+  if (/^\d/.test(after) || /^-\d/.test(after)) return invalid('fragment of a longer sequence');
+
+  const digits = ctx.match[0].replace(/-/g, '');
+  return valid({
+    canonical: digits,
+    validator: 'bsb-structural',
+  });
+}
+
+registerDetector({
+  id: 'au-bsb',
+  entityType: 'AU_BSB',
+  regions: ['AU'],
+  pattern: /\b\d{3}-\d{3}\b/g,
+  baseConfidence: CONFIDENCE.MEDIUM,
+  description: 'Australian BSB codes in XXX-XXX notation. No checksum exists; capped at MEDIUM.',
+  validate: validateBsb,
+});