@dszp/csl-screen 0.1.0

package/dist/normalize.js

@@ -0,0 +1,66 @@
+/** Legal-form suffixes and filler words that carry no identity for name matching. */
+export const DEFAULT_STOP_WORDS = [
+    'llc', 'inc', 'incorporated', 'co', 'corp', 'corporation', 'company',
+    'ltd', 'limited', 'plc', 'pc', 'pllc', 'lp', 'llp', 'the', 'and', 'of',
+    'sa', 'ag', 'gmbh', 'srl', 'bv', 'nv', 'oao', 'ooo', 'zao', 'jsc', 'pjsc',
+];
+/** Latin letters with no NFKD decomposition, and their ASCII spelling. */
+const LATIN_FOLD = {
+    'ß': 'ss', 'ẞ': 'SS', 'æ': 'ae', 'Æ': 'AE', 'œ': 'oe', 'Œ': 'OE', 'ø': 'o', 'Ø': 'O',
+    'ł': 'l', 'Ł': 'L', 'đ': 'd', 'Đ': 'D', 'ð': 'd', 'Ð': 'D', 'þ': 'th', 'Þ': 'TH', 'ı': 'i',
+};
+const LATIN_FOLD_RE = new RegExp(`[${Object.keys(LATIN_FOLD).join('')}]`, 'g');
+/**
+ * NFKD, every combining mark (\p{M}) and format character (\p{Cf}) deleted, then the Latin fold:
+ * the form every name is compared in. Deleting rather than separating means an invisible character
+ * typed inside a word (a zero-width space, soft hyphen, bidi mark or variation selector in "Ros\u200Bneft")
+ * leaves the word whole instead of splitting it into fragments that match nothing.
+ */
+function foldLatin(name) {
+    return name
+        .normalize('NFKD')
+        .replace(/[\p{M}\p{Cf}]/gu, '')
+        .replace(LATIN_FOLD_RE, (c) => LATIN_FOLD[c]);
+}
+/**
+ * True when, after the fold, the name still has a letter outside A-Z/a-z, or a control (other than tab,
+ * LF and CR), private-use or unassigned character. Such a name cannot be tokenised safely: a look-alike
+ * letter from another script (Cyrillic о in "Rоsneft") or an unreadable character would split the word
+ * and hide a listed entity, so the caller must screen it by hand.
+ */
+export function hasUnreadableCharacters(name) {
+    return /[^\P{L}A-Za-z]|[^\P{Cc}\t\n\r]|[\p{Co}\p{Cn}]/u.test(foldLatin(name));
+}
+/**
+ * Lowercase ASCII tokens of a name: diacritics stripped, `&` read as "and",
+ * everything outside [a-z0-9] treated as a separator, runs of single-character
+ * tokens joined ("L.L.C." is `llc`, "D. K. Smith" is `dk smith`), stop words dropped.
+ * Letters outside the Latin alphabet and other unreadable characters act as separators; see `hasUnreadableCharacters`.
+ */
+export function nameTokens(name, stopWords) {
+    const raw = foldLatin(name)
+        .toLowerCase()
+        .replace(/&/g, ' and ')
+        .replace(/[^a-z0-9]+/g, ' ')
+        .split(' ')
+        .filter((t) => t !== '');
+    // Join before dropping stop words, so initials ("L.L.C.") become the word they spell.
+    const joined = [];
+    let run = '';
+    for (const t of raw) {
+        if (t.length === 1)
+            run += t;
+        else {
+            if (run)
+                joined.push(run);
+            run = '';
+            joined.push(t);
+        }
+    }
+    if (run)
+        joined.push(run);
+    return joined.filter((t) => !stopWords.has(t));
+}
+export function normalizeName(name, stopWords) {
+    return nameTokens(name, stopWords).join(' ');
+}

package/dist/render.d.ts

@@ -0,0 +1,12 @@
+import type { ScreenResult } from './model.js';
+export declare function toCsv(result: ScreenResult, opts: {
+    runDate: string;
+}): string;
+export declare function toMarkdown(result: ScreenResult, opts: {
+    runDate: string;
+    title?: string;
+    expected?: number;
+    sourceRecords?: number;
+    /** Caller lines (for example where the parties and the list came from), printed as list items under the title. */
+    preamble?: readonly string[];
+}): string;

package/dist/render.js

@@ -0,0 +1,93 @@
+import { partyOutcome } from './decisions.js';
+const COLUMNS = [
+    'party_id', 'party_name', 'source', 'result', 'matched_name', 'list', 'entry_key', 'rule', 'score',
+    'reason', 'entry_countries', 'party_country', 'decision', 'decided_by', 'decided_at', 'run_date',
+];
+/** A leading = + - @ (or tab/CR/LF) makes a spreadsheet read the cell as a formula; a leading apostrophe stops that. */
+function guardFormula(s) {
+    return /^[=+\-@\t\r\n]/.test(s) ? `'${s}` : s;
+}
+/** Guard first, then RFC 4180 quoting, so the apostrophe sits inside the quotes. */
+function csvCell(s) {
+    const g = guardFormula(s);
+    return /[",\r\n]/.test(g) ? `"${g.replace(/"/g, '""')}"` : g;
+}
+export function toCsv(result, opts) {
+    const lines = [COLUMNS.join(',')];
+    const row = (cells) => lines.push(cells.map(csvCell).join(','));
+    for (const r of result.parties) {
+        const outcome = partyOutcome(r);
+        const head = [r.party.id, r.party.name, r.party.source, outcome];
+        if (r.status !== 'flagged') {
+            row([...head, '', '', '', '', '', '', '', '', '', '', opts.runDate]);
+            continue;
+        }
+        for (const m of r.matches) {
+            row([
+                ...head, m.matchedName, m.listSource, m.entryKey, m.rule, m.score.toFixed(2), m.reason,
+                m.entryCountries.join(';'), r.party.country ?? '',
+                m.decision?.decision ?? '', m.decision?.reviewer ?? '', m.decision?.decidedAt ?? '', opts.runDate,
+            ]);
+        }
+    }
+    return lines.join('\r\n') + '\r\n';
+}
+/**
+ * Names come from client records and the public list, so they are untrusted. Line breaks become spaces
+ * (a table row or list item must stay on one line), then every character Markdown or inline HTML could
+ * act on is backslash-escaped. `&` is included so an entity such as `<` stays literal text.
+ */
+function md(s) {
+    return s
+        .replace(/\r\n|\r|\n/g, ' ')
+        .replace(/[\\|`*_~<>[\]&]/g, '\\$&')
+        .replace(/^(\s*)#/, '$1\\#');
+}
+const UNSCREENABLE_REASON = {
+    'empty-name': 'name is empty after normalisation',
+    'unreadable-characters': 'name contains non-Latin or unreadable characters; screen it by hand',
+};
+const list = (xs) => (xs.length ? md(xs.join(', ')) : 'none');
+function matchLine(r, m) {
+    const p = r.party;
+    const d = m.decision;
+    const decision = d ? `${d.decision} by ${md(d.reviewer)} at ${md(d.decidedAt)}: ${md(d.reason)}` : 'none';
+    const partyCountry = p.country ? md(p.country) : 'not provided';
+    const mismatch = m.countryMismatch ? ' (country mismatch)' : '';
+    return [
+        `- **${md(p.name)}** (id ${md(p.id)}, source ${md(p.source)}) matched **${md(m.matchedName)}**`,
+        `  - List: ${md(m.listSource)}; programs: ${list(m.programs)}; entry type: ${m.entryType ? md(m.entryType) : 'unknown'}`,
+        `  - Countries: entry ${list(m.entryCountries)}; party ${partyCountry}${mismatch}`,
+        `  - Rule: ${m.rule}, score ${m.score.toFixed(2)}; reason: ${md(m.reason)}`,
+        `  - Decision: ${decision}`,
+    ].join('\n');
+}
+export function toMarkdown(result, opts) {
+    const { counts, snapshot: s, matcher } = result;
+    const out = [];
+    if (opts.expected !== undefined && opts.expected !== counts.parties) {
+        out.push(`INCOMPLETE: ${counts.parties} parties in run of expected ${opts.expected}`, '');
+    }
+    out.push(`# ${md(opts.title || 'Restricted-party screening report')}`, '');
+    if (opts.preamble?.length)
+        out.push(...opts.preamble.map((l) => `- ${md(l)}`), '');
+    out.push(`Run date: ${md(opts.runDate)}`, '');
+    const excluded = opts.sourceRecords !== undefined ? opts.sourceRecords - counts.parties : 0;
+    out.push(...(opts.sourceRecords !== undefined ? [`- Source records: ${opts.sourceRecords}`] : []), opts.expected !== undefined
+        ? `- Parties in run: ${counts.parties} of ${opts.expected} expected`
+        : `- Parties in run: ${counts.parties}`, ...(excluded > 0 ? [`- Excluded by scope: ${excluded}`] : []), `- Screened: ${counts.screened}`, `- Clear: ${counts.clear}`, `- Flagged: ${counts.flagged}`, `- Unscreenable: ${counts.unscreenable}`, '', '## Consolidated Screening List snapshot', '', `- Search performed at: ${md(s.searchPerformedAt || 'unknown')}`, `- Entries: ${s.entryCount}`, `- SHA-256: ${s.sha256}`, '- Sources:', ...s.sources.map((x) => `  - ${md(x.source)}: last updated ${md(x.sourceLastUpdated ?? 'unknown')}`), '', '## Matcher', '', `- Version ${md(matcher.version)}`, `- Threshold: ${matcher.threshold}`, '');
+    const flagged = result.parties.filter((r) => r.status === 'flagged');
+    const section = (title, state) => {
+        const lines = flagged.flatMap((r) => r.matches.filter((m) => m.state === state).map((m) => matchLine(r, m)));
+        if (lines.length)
+            out.push(`## ${title}`, '', ...lines, '');
+    };
+    section('New flags', 'new');
+    section('Escalated (open)', 'escalated');
+    const unscreenable = result.parties.filter((r) => r.status === 'unscreenable');
+    if (unscreenable.length) {
+        out.push('## Unscreenable parties', '', ...unscreenable.map((r) => `- ${r.party.name.trim() ? md(r.party.name) : '(blank name)'} (id ${md(r.party.id)}, source ${md(r.party.source)}): ${UNSCREENABLE_REASON[r.reason]}`), '');
+    }
+    section('Cleared (still matching)', 'cleared');
+    return out.join('\n');
+}

package/dist/screen.d.ts

@@ -0,0 +1,11 @@
+import type { Party, ScreenOptions, ScreenResult } from './model.js';
+import type { Snapshot } from './snapshot.js';
+/**
+ * One-word listed entity names (after stop words are dropped) too generic to flag anywhere but a party
+ * name's first token. Each was measured on real customer names: as a later token it flagged only
+ * unrelated organisations using it as an ordinary word.
+ * A word joins this list only from such a measurement, because each one is a name that can be hidden
+ * behind another word.
+ */
+export declare const DEFAULT_GENERIC_TOKENS: readonly string[];
+export declare function screen(parties: Party[], snapshot: Snapshot, options?: ScreenOptions): ScreenResult;

package/dist/screen.js

@@ -0,0 +1,181 @@
+import { jaroWinkler } from './jaroWinkler.js';
+import { MATCHER_VERSION } from './model.js';
+import { DEFAULT_STOP_WORDS, hasUnreadableCharacters, nameTokens } from './normalize.js';
+const RULE_RANK = { exact: 3, contains: 2, within: 1, similar: 0 };
+/** A one-token listed name on these entry types is too generic (a ship, a nickname) to match inside a longer party name. */
+const NON_ENTITY_TYPES = new Set(['Individual', 'Vessel', 'Aircraft']);
+/**
+ * One-word listed entity names (after stop words are dropped) too generic to flag anywhere but a party
+ * name's first token. Each was measured on real customer names: as a later token it flagged only
+ * unrelated organisations using it as an ordinary word.
+ * A word joins this list only from such a measurement, because each one is a name that can be hidden
+ * behind another word.
+ */
+export const DEFAULT_GENERIC_TOKENS = ['center', 'focus', 'technology', 'united'];
+/** Longest run of adjacent party tokens joined when looking for a listed word split by separators. */
+const MAX_RUN = 3;
+const spaceless = (key) => key.replace(/ /g, '');
+const push = (m, k, v) => {
+    const bucket = m.get(k);
+    if (bucket)
+        bucket.push(v);
+    else
+        m.set(k, [v]);
+};
+export function screen(parties, snapshot, options = {}) {
+    const threshold = options.threshold ?? 0.9;
+    const minTokenLength = options.minTokenLength ?? 3;
+    if (!(typeof threshold === 'number' && threshold > 0 && threshold <= 1)) {
+        throw new TypeError(`threshold must be a number in (0, 1], got ${String(threshold)}`);
+    }
+    if (!Number.isInteger(minTokenLength) || minTokenLength < 1) {
+        throw new TypeError(`minTokenLength must be an integer >= 1, got ${String(minTokenLength)}`);
+    }
+    const withinMinLength = Math.max(4, minTokenLength);
+    // Caller stop words go through the same normalisation as names, so 'Inc' and 'L.L.C.' behave.
+    const noStops = new Set();
+    const stopWords = new Set((options.stopWords ?? DEFAULT_STOP_WORDS).flatMap((w) => nameTokens(w, noStops)));
+    const genericTokens = new Set((options.genericTokens ?? DEFAULT_GENERIC_TOKENS).flatMap((w) => nameTokens(w, noStops)));
+    const seenIds = new Set();
+    for (const party of parties) {
+        if (seenIds.has(party.id))
+            throw new Error(`Duplicate party id: ${party.id}`);
+        seenIds.add(party.id);
+    }
+    const index = new Map();
+    const bySpaceless = new Map();
+    let longestSpaceless = 0;
+    for (const entry of snapshot.entries) {
+        for (const name of [entry.name, ...entry.altNames]) {
+            const tokens = nameTokens(name, stopWords);
+            if (tokens.length === 0)
+                continue;
+            const indexed = { entry, name, key: tokens.join(' '), tokens: new Set(tokens), indexable: tokens.some((t) => t.length >= minTokenLength) };
+            push(bySpaceless, spaceless(indexed.key), indexed);
+            longestSpaceless = Math.max(longestSpaceless, spaceless(indexed.key).length);
+            for (const token of indexed.tokens)
+                if (token.length >= minTokenLength)
+                    push(index, token, indexed);
+        }
+    }
+    const results = parties.map((party) => {
+        const tokens = nameTokens(party.name, stopWords);
+        const partyNameKey = tokens.join(' ');
+        const ptoks = new Set(tokens);
+        // A non-Latin letter or unreadable character would split a word into fragments (or vanish), so a listed name could be missed.
+        if (hasUnreadableCharacters(party.name))
+            return { party, partyNameKey, status: 'unscreenable', reason: 'unreadable-characters' };
+        // An empty key cannot be screened; it must not read as clear.
+        if (partyNameKey === '')
+            return { party, partyNameKey, status: 'unscreenable', reason: 'empty-name' };
+        // `within` needs a party token long enough to be distinctive: at least 4, and never shorter than an indexed token.
+        const hasLongToken = tokens.some((t) => t.length >= withinMinLength);
+        // Each party token, and each run of two or three adjacent tokens joined without spaces, with the position
+        // it starts at. A run catches a separator inserted inside a listed word ("Ros-neft Trading" holds
+        // "rosneft"). At most MAX_RUN units per position keeps the work linear in the party name's length; a run
+        // longer than any listed name cannot match and is not looked up.
+        const units = new Map();
+        for (let i = 0; i < tokens.length; i++) {
+            let run = '';
+            for (let j = i; j < tokens.length && j - i < MAX_RUN; j++) {
+                run += tokens[j];
+                if (run.length > longestSpaceless && j > i)
+                    break;
+                if (!units.has(run))
+                    units.set(run, i);
+            }
+        }
+        const candidates = new Set();
+        for (const u of units.keys()) {
+            if (u.length >= minTokenLength)
+                for (const c of index.get(u) ?? [])
+                    candidates.add(c);
+            for (const c of bySpaceless.get(u) ?? [])
+                candidates.add(c);
+        }
+        for (const c of bySpaceless.get(spaceless(partyNameKey)) ?? [])
+            candidates.add(c);
+        const best = new Map();
+        for (const cand of candidates) {
+            let shared = 0;
+            for (const t of cand.tokens)
+                if (ptoks.has(t))
+                    shared++;
+            const cover = shared / Math.max(ptoks.size, cand.tokens.size);
+            const score = Math.min(jaroWinkler(partyNameKey, cand.key), 0.5 + cover / 2);
+            // Contained when every listed token is a party token, or a run of them, or the whole listed name is one run.
+            const candSpaceless = spaceless(cand.key);
+            const inUnits = [...cand.tokens].every((t) => units.has(t)) || units.has(candSpaceless);
+            // A one-token name on an entity counts in any position, except a generic word, which counts only first.
+            const at = units.get(candSpaceless);
+            const containedAlone = cand.tokens.size > 1 ||
+                (!NON_ENTITY_TYPES.has(cand.entry.type ?? '') && at !== undefined && (at === 0 || !genericTokens.has(candSpaceless)));
+            let rule = null;
+            let reason = null;
+            if (partyNameKey === cand.key)
+                rule = 'exact';
+            else if (spaceless(partyNameKey) === spaceless(cand.key)) {
+                rule = 'exact';
+                reason = 'exact ignoring spaces';
+            }
+            else if (!cand.indexable)
+                continue;
+            else if (shared === cand.tokens.size && containedAlone)
+                rule = 'contains';
+            else if (inUnits && containedAlone) {
+                rule = 'contains';
+                reason = 'contains listed name ignoring spaces';
+            }
+            else if (shared === ptoks.size && hasLongToken)
+                rule = 'within';
+            else if (score >= threshold)
+                rule = 'similar';
+            if (rule === null)
+                continue;
+            const cur = best.get(cand.entry.key);
+            if (!cur || RULE_RANK[rule] > RULE_RANK[cur.rule] || (rule === cur.rule && score > cur.score)) {
+                best.set(cand.entry.key, { rule, score, name: cand, reason });
+            }
+        }
+        if (best.size === 0)
+            return { party, partyNameKey, status: 'clear' };
+        const country = party.country?.toUpperCase();
+        const matches = [...best.values()].map(({ rule, score, name, reason }) => ({
+            entryKey: name.entry.key,
+            entryId: name.entry.id,
+            entryFingerprint: name.entry.fingerprint,
+            matchedName: name.name,
+            listSource: name.entry.source,
+            programs: name.entry.programs,
+            entryType: name.entry.type,
+            entryCountries: name.entry.countries,
+            countryMismatch: !!country && name.entry.countries.length > 0 && !name.entry.countries.includes(country),
+            rule,
+            // An exact rule is a full match whatever the token-cover heuristic says (spaceless matches cover fewer tokens).
+            score: rule === 'exact' ? 1 : score,
+            reason: reason ??
+                (rule === 'exact' ? 'exact after normalisation'
+                    : rule === 'contains' ? 'contains listed name'
+                        : rule === 'within' ? 'listed name contains party name'
+                            : `similar ${score.toFixed(2)}`),
+            state: 'new',
+        }));
+        matches.sort((a, b) => RULE_RANK[b.rule] - RULE_RANK[a.rule] || b.score - a.score || (a.entryKey < b.entryKey ? -1 : a.entryKey > b.entryKey ? 1 : 0));
+        return { party, partyNameKey, status: 'flagged', matches };
+    });
+    const count = (s) => results.filter((r) => r.status === s).length;
+    const unscreenable = count('unscreenable');
+    return {
+        check: 'csl',
+        matcher: { version: MATCHER_VERSION, threshold, minTokenLength, stopWords: [...stopWords].sort(), genericTokens: [...genericTokens].sort() },
+        snapshot: snapshot.identity,
+        counts: {
+            parties: results.length,
+            screened: results.length - unscreenable,
+            unscreenable,
+            clear: count('clear'),
+            flagged: count('flagged'),
+        },
+        parties: results,
+    };
+}

package/dist/snapshot.d.ts

@@ -0,0 +1,59 @@
+export interface SnapshotIdentity {
+    searchPerformedAt: string;
+    sources: {
+        source: string;
+        sourceLastUpdated: string | null;
+        lastImported: string | null;
+    }[];
+    entryCount: number;
+    /** Entries per CSL `source` (list name), keys sorted. Feeds the next run's `previousEntriesBySource`. */
+    entriesBySource: Record<string, number>;
+    /** SHA-256 of the downloaded bytes. Changes on every republish, even when no entry changed. */
+    sha256: string;
+    /** Hash of the entries alone (see `contentHashOf`). Unchanged by `search_performed_at` and per-list `last_imported`. */
+    contentSha256: string;
+}
+export interface SlimEntry {
+    /** `${source}|${id}`. The CSL `id` alone is not unique: an entry on two lists shares it. */
+    key: string;
+    id: string;
+    name: string;
+    altNames: string[];
+    source: string;
+    type: string | null;
+    countries: string[];
+    programs: string[];
+    sourceListUrl: string | null;
+    /** SHA-256 of the canonical JSON of the whole raw entry; changes when any field changes. */
+    fingerprint: string;
+}
+export interface Snapshot {
+    identity: SnapshotIdentity;
+    entries: SlimEntry[];
+}
+export declare class CslSnapshotError extends Error {
+    kind: 'parse' | 'shape' | 'total-mismatch' | 'sharp-drop' | 'source-drop';
+    constructor(kind: 'parse' | 'shape' | 'total-mismatch' | 'sharp-drop' | 'source-drop', message: string);
+}
+export interface LoadSnapshotOptions {
+    /** Entry count of the snapshot being replaced; enables the sharp-drop check. */
+    previousEntryCount?: number;
+    /** Largest tolerated fractional shrink against previousEntryCount. Default 0.1. */
+    maxDropRatio?: number;
+    /**
+     * `entriesBySource` of the snapshot being replaced; enables the source-drop check. A source in this map that is
+     * missing from the new file, or has fewer than half its previous entries, fails the load. Catches the loss of
+     * one small list, which the whole-file sharp-drop check cannot see.
+     */
+    previousEntriesBySource?: Record<string, number>;
+}
+/**
+ * SHA-256 hex over the lines `${key}\t${fingerprint}\n`, sorted by key in byte order (plain `<` on strings, not
+ * `localeCompare`, so the result does not depend on the runtime's locale), concatenated. Entry order in the file
+ * does not matter; any change to an entry's fingerprint, or to the set of keys, does.
+ */
+export declare function contentHashOf(entries: readonly {
+    key: string;
+    fingerprint: string;
+}[]): Promise<string>;
+export declare function loadSnapshot(input: Uint8Array | ArrayBuffer | string, opts?: LoadSnapshotOptions): Promise<Snapshot>;

package/dist/snapshot.js

@@ -0,0 +1,130 @@
+import { canonicalJson, sha256Hex } from './canonical.js';
+export class CslSnapshotError extends Error {
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.kind = kind;
+        this.name = 'CslSnapshotError';
+    }
+}
+const isObj = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const strOrNull = (v) => (typeof v === 'string' ? v : null);
+const MIN_SOURCE_RATIO = 0.5;
+/** Null or absent is an empty list; anything else must be an array of strings, so a format change fails loudly. */
+function strings(v, where) {
+    if (v === null || v === undefined)
+        return [];
+    if (!Array.isArray(v) || !v.every((x) => typeof x === 'string')) {
+        throw new CslSnapshotError('shape', `${where} must be an array of strings, null or absent`);
+    }
+    return v;
+}
+/**
+ * SHA-256 hex over the lines `${key}\t${fingerprint}\n`, sorted by key in byte order (plain `<` on strings, not
+ * `localeCompare`, so the result does not depend on the runtime's locale), concatenated. Entry order in the file
+ * does not matter; any change to an entry's fingerprint, or to the set of keys, does.
+ */
+export async function contentHashOf(entries) {
+    const sorted = [...entries].sort((x, y) => (x.key < y.key ? -1 : x.key > y.key ? 1 : 0));
+    return sha256Hex(sorted.map((e) => `${e.key}\t${e.fingerprint}\n`).join(''));
+}
+export async function loadSnapshot(input, opts = {}) {
+    const bytes = typeof input === 'string' ? new TextEncoder().encode(input)
+        : input instanceof Uint8Array ? input
+            : new Uint8Array(input);
+    const sha256 = await sha256Hex(bytes);
+    let doc;
+    try {
+        doc = JSON.parse(new TextDecoder().decode(bytes));
+    }
+    catch (e) {
+        throw new CslSnapshotError('parse', `CSL file is not valid JSON: ${e.message}`);
+    }
+    if (!isObj(doc) || !Array.isArray(doc.results)) {
+        throw new CslSnapshotError('shape', 'CSL file has no "results" array');
+    }
+    const raw = doc.results;
+    if (raw.length === 0) {
+        throw new CslSnapshotError('shape', 'CSL file has an empty "results" array');
+    }
+    if (typeof doc.search_performed_at !== 'string') {
+        throw new CslSnapshotError('shape', 'CSL file has no "search_performed_at" string');
+    }
+    const searchPerformedAt = doc.search_performed_at;
+    if (typeof doc.total !== 'number' || raw.length !== doc.total) {
+        throw new CslSnapshotError('total-mismatch', `results has ${raw.length} entries but total is ${String(doc.total)}`);
+    }
+    const previous = opts.previousEntryCount;
+    const maxDrop = opts.maxDropRatio ?? 0.1;
+    // NaN or a ratio of 1 or more would silently disable the check.
+    if (!(typeof maxDrop === 'number' && maxDrop >= 0 && maxDrop < 1)) {
+        throw new TypeError(`maxDropRatio must be a number in [0, 1), got ${String(maxDrop)}`);
+    }
+    if (previous !== undefined && previous > 0 && raw.length < previous * (1 - maxDrop)) {
+        throw new CslSnapshotError('sharp-drop', `entry count fell from ${previous} to ${raw.length}, beyond the ${maxDrop} allowed drop`);
+    }
+    const entries = [];
+    const seenKeys = new Set();
+    for (const [i, r] of raw.entries()) {
+        if (!isObj(r) || typeof r.id !== 'string' || typeof r.name !== 'string' || typeof r.source !== 'string') {
+            throw new CslSnapshotError('shape', `results[${i}] lacks a string id, name or source`);
+        }
+        const countries = new Set();
+        const addCountry = (c) => {
+            if (typeof c === 'string' && c)
+                countries.add(c.toUpperCase());
+        };
+        addCountry(r.country);
+        if (Array.isArray(r.addresses))
+            for (const a of r.addresses)
+                if (isObj(a))
+                    addCountry(a.country);
+        const key = `${r.source}|${r.id}`;
+        if (seenKeys.has(key)) {
+            throw new CslSnapshotError('shape', `duplicate entry key ${key} at results[${i}]`);
+        }
+        seenKeys.add(key);
+        entries.push({
+            key,
+            id: r.id,
+            name: r.name,
+            altNames: strings(r.alt_names, `results[${i}].alt_names`),
+            source: r.source,
+            type: strOrNull(r.type),
+            countries: [...countries],
+            programs: strings(r.programs, `results[${i}].programs`),
+            sourceListUrl: strOrNull(r.source_list_url),
+            fingerprint: await sha256Hex(canonicalJson(r)),
+        });
+    }
+    // Null-prototype maps: a source named "constructor" or "__proto__" is an ordinary key.
+    const counted = Object.create(null);
+    for (const e of entries)
+        counted[e.source] = (counted[e.source] ?? 0) + 1;
+    // The published identity is a plain object (callers may use its prototype methods); fromEntries still makes
+    // "__proto__" an own data property. Lookups below stay on the null-prototype map.
+    const entriesBySource = Object.fromEntries(Object.keys(counted).sort().map((k) => [k, counted[k]]));
+    for (const [source, before] of Object.entries(opts.previousEntriesBySource ?? {})) {
+        if (typeof before !== 'number' || !Number.isFinite(before) || before < 0) {
+            throw new TypeError(`previousEntriesBySource["${source}"] must be a non-negative number, got ${JSON.stringify(before)}`);
+        }
+        const now = counted[source] ?? 0;
+        if (now < before * MIN_SOURCE_RATIO) {
+            throw new CslSnapshotError('source-drop', `source "${source}" fell from ${before} to ${now} entries${now === 0 ? ' (missing from the file)' : ''}, below ${MIN_SOURCE_RATIO * 100}% of the previous count`);
+        }
+    }
+    const sourcesUsed = Array.isArray(doc.sources_used) ? doc.sources_used : [];
+    const identity = {
+        searchPerformedAt,
+        sources: sourcesUsed.filter(isObj).map((s) => ({
+            source: typeof s.source === 'string' ? s.source : '',
+            sourceLastUpdated: strOrNull(s.source_last_updated),
+            lastImported: strOrNull(s.last_imported),
+        })),
+        entryCount: entries.length,
+        entriesBySource,
+        sha256,
+        contentSha256: await contentHashOf(entries),
+    };
+    return { identity, entries };
+}

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@dszp/csl-screen",
+  "version": "0.1.0",
+  "description": "Restricted-party screening against the US Consolidated Screening List: name normalisation, fuzzy matching and reviewable decisions. Zero runtime dependencies; runs in Node and Cloudflare Workers.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dszp/csl-screen.git"
+  },
+  "homepage": "https://github.com/dszp/csl-screen#readme",
+  "bugs": {
+    "url": "https://github.com/dszp/csl-screen/issues"
+  },
+  "author": {
+    "name": "David Szpunar",
+    "url": "https://david.szpunar.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.19"
+  },
+  "keywords": [
+    "restricted-party-screening",
+    "consolidated-screening-list",
+    "export-compliance",
+    "cloudflare-workers"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./autotask": {
+      "types": "./dist/adapters/autotask.d.ts",
+      "import": "./dist/adapters/autotask.js",
+      "require": "./dist/adapters/autotask.js",
+      "default": "./dist/adapters/autotask.js"
+    },
+    "./onebill": {
+      "types": "./dist/adapters/onebill.d.ts",
+      "import": "./dist/adapters/onebill.js",
+      "require": "./dist/adapters/onebill.js",
+      "default": "./dist/adapters/onebill.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.ts",
+  "module": "./dist/index.js",
+  "main": "./dist/index.js",
+  "sideEffects": false,
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "dist/**/*.map",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/testkit.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "build:watch": "tsc -p tsconfig.json --watch",
+    "prepublishOnly": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json --sourceMap false --declarationMap false",
+    "typecheck": "tsc -p tsconfig.test.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "typescript": "^5",
+    "vitest": "^3"
+  },
+  "packageManager": "pnpm@11.11.0"
+}

package/src/adapters/autotask.ts

@@ -0,0 +1,23 @@
+import type { Party } from '../model.js';
+
+/** The fields of an Autotask Companies record the adapter reads; extra fields pass through untouched. */
+export interface AutotaskCompanyLike {
+  id: number | string;
+  companyName?: string | null;
+  [k: string]: unknown;
+}
+
+/**
+ * Maps Autotask companies to screening parties. `include` is required so the caller states which
+ * companies are in scope (for example active customers) instead of screening everything by default.
+ */
+export function fromAutotaskCompanies<T extends AutotaskCompanyLike>(
+  records: readonly T[],
+  opts: { include: (r: T) => boolean; source?: string; country?: (r: T) => string | undefined },
+): Party[] {
+  const source = opts.source ?? 'autotask';
+  return records.filter(opts.include).map((r) => {
+    const country = opts.country?.(r);
+    return { id: String(r.id), name: r.companyName ?? '', source, ...(country ? { country } : {}) };
+  });
+}