@dszp/csl-screen 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+All notable changes to `@dszp/csl-screen` are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres
+to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] — 2026-10-17
+
+First release.
+
+### Added
+
+- `loadSnapshot` parses the Consolidated Screening List bulk JSON file into a compact snapshot. The
+  snapshot records the list's identity: search time, per-list update times, entry count, per-list
+  entry counts, and a SHA-256 of the downloaded bytes. Loading fails with a typed
+  `CslSnapshotError` when the file is truncated, empty, malformed, shorter than its own `total`, or
+  has lost entries since a previous load (`previousEntryCount`, `previousEntriesBySource`).
+- `screen` matches parties against every listed name and alias with four rules: exact (also
+  ignoring spaces), contains, within, and similar (Jaro-Winkler capped by token coverage). The
+  threshold, stop words and index token length are options. Contains also joins two or three
+  adjacent party tokens, so a separator typed inside a listed word does not hide it. A one-word
+  listed entity name matches in any position of the party name, except the words in
+  `genericTokens` (default `DEFAULT_GENERIC_TOKENS`), which match only as the first token.
+- `makeDecision`, `applyDecisions` and `parseDecisions` record a reviewer's ruling on a flag. A
+  clearance holds only while the party's normalised name and a fingerprint of the whole list entry
+  are unchanged.
+- `toCsv` and `toMarkdown` render evidence. The CSV guards against spreadsheet formula injection,
+  and the Markdown escapes names.
+- `@dszp/csl-screen/autotask` and `@dszp/csl-screen/onebill` map source records to parties.
+- `SnapshotIdentity.contentSha256` and `contentHashOf`: a hash of the entries alone, unchanged by
+  `search_performed_at` or a list's `last_imported`, so it changes only when the list's content does.
+
+- Names are folded to ASCII for Latin letters that have no accent decomposition (`ß`, `æ`, `œ`, `ø`,
+  `ł`, `đ`, `ð`, `þ`, `ı`), and every combining mark and format character (zero-width space, soft
+  hyphen, bidi mark, variation selector) is deleted, so an invisible character inside a word does
+  not split it. A party name that still has a letter outside the Latin alphabet, or a control,
+  private-use or unassigned character, is reported as unscreenable
+  (`reason: 'unreadable-characters'`, exported check `hasUnreadableCharacters`), because such a
+  character would otherwise split a word and hide a listed match.
+
+### Known limitations
+
+- A misspelling inside a word (for example a dropped letter) is not caught.
+- A listed one-word name in `genericTokens` matches only as the party's first token. The list is
+  an option.
+- A listed word split into four or more pieces inside a longer party name is not caught.
+- Only organisation names are screened, and only against the US list. Names with letters outside the
+  Latin alphabet are reported as unscreenable.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Szpunar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,126 @@
+# @dszp/csl-screen
+
+Screen organisation names against the US Consolidated Screening List (CSL). The library normalises names, matches them against every listed name and alias, and records a reviewer's ruling on each flag so the same flag does not come back until something changes. It has no runtime dependencies and runs in Node 20.19+ and Cloudflare Workers. It is an ES module; `require()` loads it on Node versions with `require(esm)` support (20.19+, 22.12+).
+
+This is a screening aid, not legal advice. A clear result does not prove that a party is permitted, and a flag does not prove a violation. A person must review flags.
+
+Scope: it screens organisations against the US CSL only. It does not screen against other countries' lists, and it does not transliterate non-Latin names (a name with letters outside the Latin alphabet, or with unreadable characters, cannot be matched safely and is reported as unscreenable).
+
+## Install
+
+```sh
+npm install @dszp/csl-screen
+```
+
+## Example
+
+The library does no I/O. You fetch the CSL JSON file and your party records, and pass them in.
+
+```ts
+import { loadSnapshot, screen, applyDecisions, partyOutcome, toCsv } from '@dszp/csl-screen';
+import { fromAutotaskCompanies } from '@dszp/csl-screen/autotask';
+
+// 1. Fetch the CSL bulk JSON file. Use GET: a HEAD request returns 404.
+const res = await fetch('https://data.trade.gov/downloadable_consolidated_screening_list/v1/consolidated.json');
+if (!res.ok) throw new Error(`CSL download failed: HTTP ${res.status}`);
+const bytes = new Uint8Array(await res.arrayBuffer());
+
+// 2. Validate it and build the snapshot. Pass last run's counts to refuse a truncated file
+//    or one that has lost a list.
+const snapshot = await loadSnapshot(bytes, {
+  previousEntryCount: last?.entryCount,
+  previousEntriesBySource: last?.entriesBySource,
+});
+
+// 3. Turn your records into parties. `include` is required: you choose who is in scope.
+const parties = fromAutotaskCompanies(companies, { include: (c) => c.id !== 0 });
+
+// 4. Screen, then apply the rulings reviewers have already made.
+const result = applyDecisions(screen(parties, snapshot), savedDecisions);
+
+// 5. Write the evidence.
+const csv = toCsv(result, { runDate: '2026-01-31' });
+// Store result.snapshot (the snapshot identity) as `last` for the next run.
+
+// 6. Branch on the outcome.
+console.log(result.counts); // { parties, screened, unscreenable, clear, flagged }
+for (const r of result.parties) {
+  if (partyOutcome(r) === 'flagged-new') console.log(r.party.name, r.status === 'flagged' && r.matches);
+}
+```
+
+`loadSnapshot` throws a `CslSnapshotError` whose `kind` says why: `parse` (not JSON), `shape` (missing `results` or `search_performed_at`, a malformed entry, or `alt_names` or `programs` that is not an array of strings), `total-mismatch`, `sharp-drop` (the entry count fell more than `maxDropRatio`, default 0.1, below `previousEntryCount`) or `source-drop` (a list in `previousEntriesBySource` is missing, or has fewer than half its previous entries). The snapshot identity carries `entriesBySource`, the entry count per list, to pass as `previousEntriesBySource` next time.
+
+`partyOutcome` returns `clear`, `unscreenable`, `flagged-new`, `flagged-escalated` or `flagged-cleared`; a party is `flagged-new` while any of its matches still needs review. `toMarkdown(result, { runDate, title, expected })` writes a report. Pass `expected` (the number of parties you meant to screen) and the report starts with an `INCOMPLETE` line if the run has a different count. Pass `sourceRecords` (the number of records you were given before choosing who is in scope) and the header prints `Source records` and, when some were left out, `Excluded by scope`. Pass `preamble` (an array of strings) to print your own lines, such as where the parties and the list came from, as list items under the title. They are escaped like names.
+
+To record a ruling on a flag, call `makeDecision(result, { partyId, entryKey, decision, reason, reviewer, decidedAt, runId })`. `decision` is `'cleared'` or `'escalated'`; `reason` and `reviewer` must not be blank. `runId` is optional: pass your identifier for the run whose result the reviewer read, and it is copied into the ruling. Store the returned object and pass it to `applyDecisions` on later runs. When you read stored rulings back from a file or database, run them through `parseDecisions(value)` first: it throws a `TypeError` naming the index and field of the first malformed record. `applyDecisions` also ignores any record whose `decision` is not `cleared` or `escalated`, or whose `reason` is blank, or whose `check` is not `'csl'`.
+
+## Adapters
+
+Each adapter is a separate entry point and returns `Party[]` (`{ id, name, source, country? }`). You can also build parties by hand.
+
+- `@dszp/csl-screen/autotask`: `fromAutotaskCompanies(records, { include, source?, country? })`. The `source` defaults to `'autotask'`.
+- `@dszp/csl-screen/onebill`: `fromOneBillSubscribers(records, { source?, country? })`. The `source` defaults to `'onebill'`. The name is `companyName`, or `accountName` if that is empty. The country is the first address country that is a two-letter code; any other value (such as `United States`) is dropped.
+
+A party's `country` only annotates a match, and flags a mismatch with the entry's countries. It never removes a match.
+
+## How matching works
+
+Names are lowercased, stripped of diacritics (letters with no decomposition fold to ASCII: `ß` is `ss`, `æ` is `ae`, `ø` is `o`, `ł` is `l`), split on anything that is not a letter or digit, and stripped of legal-form words such as `llc`, `inc` and `gmbh` (configurable with `stopWords`). Runs of single-letter tokens join, so `L.L.C.` is `llc` and `D. K. Smith` is `dk smith`. The party is then compared with every listed name and alias that shares a token of at least three characters (`minTokenLength`). A match carries the first rule below that applies:
+
+1. **exact**: the normalised names are equal, ignoring spaces ("Rosoboron Export" matches "Rosoboronexport").
+2. **contains**: every token of the listed name appears in the party's name ("Hikvision USA" matches "Hikvision"). Runs of two or three adjacent party tokens also count joined without spaces, so a separator typed inside a listed word does not hide it ("Ros-neft Trading" matches "Rosneft", with reason `contains listed name ignoring spaces`). A listed name of one token counts only when the entry is not an Individual, Vessel or Aircraft, which keeps ship names and personal nicknames from flagging unrelated companies. It counts in any position ("Global Rosneft Services" matches "Rosneft"), except a word in `genericTokens` (default `DEFAULT_GENERIC_TOKENS`: `center`, `focus`, `technology`, `united`), which counts only as the party's first token. Those words are listed one-word names that, measured on real customer names, flagged only unrelated organisations using them as ordinary words. Pass your own `genericTokens` to replace the list; every word on it is a listed name that can be hidden behind another word.
+3. **within**: every token of the party's name appears in the listed name, and the party has a token of four or more characters ("Huawei" matches "Huawei Technologies Co., Ltd.").
+4. **similar**: Jaro-Winkler similarity of the normalised names, capped by how many tokens they share, at or above `threshold` (default 0.9).
+
+Combining marks and invisible format characters (zero-width spaces, soft hyphens, bidi marks, variation selectors) are deleted before splitting, so one typed inside a word leaves the word whole.
+
+A party name is reported unscreenable (`reason: 'unreadable-characters'`), for a person to screen, when after that fold it still has a letter outside the Latin alphabet, or a control character (other than tab and line breaks), a private-use character or an unassigned code point. Otherwise a look-alike letter from another script, such as a Cyrillic `о` in "Rоsneft", or an unreadable character would split the word and hide a listed match. `hasUnreadableCharacters(name)` runs the same check.
+
+A name with no token of three or more characters (for example `Xu Li` or `D Company`) can only match by the exact rule. Such a party is still screened. The `within` rule needs a party token of at least four characters, or `minTokenLength` if that is larger.
+
+Known gaps:
+
+- A misspelling inside a single token ("Rosoboronexpot") shares no token with the listed name, so it is not found. Finding it needs a character n-gram index, which this library does not have.
+- A listed one-word name in `genericTokens` is found only as the party's first token, so "Acme Center" does not match a listed "Center". Pass a shorter `genericTokens` list (or `[]`) to trade more flags for that coverage.
+- A listed word split into four or more pieces by separators ("Ro s-ne ft Trading") is not joined back, unless the whole party name is that word.
+
+## Decisions
+
+A ruling is keyed by the party id and the entry key, `source|id`. The CSL `id` alone is not unique, because an entry that sits on two lists shares it.
+
+A `cleared` or `escalated` ruling applies only while both of these are unchanged since the reviewer made it:
+
+- the party's normalised name, and
+- the fingerprint of the whole CSL entry (a hash of every field of the raw entry).
+
+If the party is renamed, or the entry changes in any field, the match returns to `new` and needs a fresh review. The latest ruling for a party and entry wins, comparing the `decidedAt` instants. If two rulings have the same instant, `escalated` wins.
+
+Persist rulings yourself (a file, a database, a Worker's storage). The library only creates and applies them. Rulings contain your party names and reviewers, so keep them out of version control for a public repository.
+
+## Outputs
+
+`toCsv` writes one row per match, and one row for each clear or unscreenable party, with CRLF line endings. A cell that starts with `=`, `+`, `-`, `@`, a tab or a line break gets a leading apostrophe so a spreadsheet does not run it as a formula. `toMarkdown` escapes names before it prints them.
+
+The report header lists the parties in the run, how many were screened, and how many were clear, flagged and unscreenable, plus the CSL snapshot (time, entry count, SHA-256) and the matcher version, so a result can be tied to the exact list it was checked against.
+
+## Identifying a list version
+
+A snapshot carries two hashes. `sha256` covers the downloaded bytes, so it changes whenever the file is republished, including when only `search_performed_at` or a list's `last_imported` moved. `contentSha256` covers the entries alone: it hashes each entry's `key` and `fingerprint`, sorted by key, so it changes only when an entry is added, removed or edited. Compare `contentSha256` to decide whether the list changed. `contentHashOf(entries)` computes the same value from any array of `{ key, fingerprint }`.
+
+## Development
+
+```sh
+pnpm install
+pnpm test
+pnpm typecheck
+pnpm build
+```
+
+## Changes
+
+See [CHANGELOG.md](CHANGELOG.md).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/dist/adapters/autotask.d.ts

@@ -0,0 +1,16 @@
+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 declare function fromAutotaskCompanies<T extends AutotaskCompanyLike>(records: readonly T[], opts: {
+    include: (r: T) => boolean;
+    source?: string;
+    country?: (r: T) => string | undefined;
+}): Party[];

package/dist/adapters/autotask.js

@@ -0,0 +1,11 @@
+/**
+ * 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(records, opts) {
+    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 } : {}) };
+    });
+}

package/dist/adapters/onebill.d.ts

@@ -0,0 +1,17 @@
+import type { Party } from '../model.js';
+/** The fields of a OneBill subscriber record the adapter reads. */
+export interface OneBillSubscriberLike {
+    accountNumber: string;
+    companyName?: string;
+    accountName?: string;
+    address?: {
+        country?: string;
+    }[] | {
+        country?: string;
+    };
+}
+/** Maps OneBill subscribers to screening parties. Only a two-letter country code is kept; other values are dropped. */
+export declare function fromOneBillSubscribers<T extends OneBillSubscriberLike>(records: readonly T[], opts?: {
+    source?: string;
+    country?: (r: T) => string | undefined;
+}): Party[];

package/dist/adapters/onebill.js

@@ -0,0 +1,14 @@
+const ISO2 = /^[A-Za-z]{2}$/;
+function defaultCountry(r) {
+    const addrs = Array.isArray(r.address) ? r.address : r.address ? [r.address] : [];
+    const hit = addrs.find((a) => typeof a?.country === 'string' && ISO2.test(a.country));
+    return hit?.country?.toUpperCase();
+}
+/** Maps OneBill subscribers to screening parties. Only a two-letter country code is kept; other values are dropped. */
+export function fromOneBillSubscribers(records, opts = {}) {
+    const source = opts.source ?? 'onebill';
+    return records.map((r) => {
+        const country = opts.country ? opts.country(r) : defaultCountry(r);
+        return { id: r.accountNumber, name: r.companyName?.trim() || r.accountName || '', source, ...(country ? { country } : {}) };
+    });
+}

package/dist/canonical.d.ts

@@ -0,0 +1,3 @@
+/** JSON.stringify with object keys sorted recursively; arrays keep their order. */
+export declare function canonicalJson(value: unknown): string;
+export declare function sha256Hex(data: Uint8Array | string): Promise<string>;

package/dist/canonical.js

@@ -0,0 +1,22 @@
+/** JSON.stringify with object keys sorted recursively; arrays keep their order. */
+export function canonicalJson(value) {
+    return JSON.stringify(sortKeys(value));
+}
+function sortKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (value !== null && typeof value === 'object') {
+        const src = value;
+        // Null prototype: a field named "__proto__" stays an own key instead of setting the prototype and vanishing.
+        const out = Object.create(null);
+        for (const k of Object.keys(src).sort())
+            out[k] = sortKeys(src[k]);
+        return out;
+    }
+    return value;
+}
+export async function sha256Hex(data) {
+    const bytes = typeof data === 'string' ? new TextEncoder().encode(data) : data;
+    const digest = await crypto.subtle.digest('SHA-256', bytes);
+    return Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, '0')).join('');
+}

package/dist/decisions.d.ts

@@ -0,0 +1,28 @@
+import type { Decision, PartyResult, ScreenResult } from './model.js';
+/** Unambiguous: both parts are JSON-encoded, so no separator inside an id can shift the boundary. */
+export declare function decisionKey(partyId: string, entryKey: string): string;
+export interface DecisionInput {
+    partyId: string;
+    entryKey: string;
+    decision: 'cleared' | 'escalated';
+    reason: string;
+    reviewer: string;
+    decidedAt: string;
+    /** Identifies the run whose result the reviewer read; copied into the Decision. */
+    runId?: string;
+}
+/** Records a ruling bound to the party name and CSL entry content the reviewer actually saw. */
+export declare function makeDecision(result: ScreenResult, input: DecisionInput): Decision;
+/**
+ * Returns a new result with each match's `state` and `decision` set from the latest decision for its
+ * (party, entry) key. A decision applies only if the party name and CSL entry are unchanged since it was
+ * made; otherwise the match is `new` again. Only the latest decision is considered, so a stale one is not
+ * bypassed by an older valid one. "Latest" compares parsed instants, so offsets and precision do not matter;
+ * a decision whose `decidedAt` does not parse is never latest and never applies. On an exact tie,
+ * `escalated` wins over `cleared`, whatever the array order.
+ */
+export declare function applyDecisions(result: ScreenResult, decisions: readonly Decision[]): ScreenResult;
+/** Validates persisted decisions (for example a decisions file read from disk). Throws a TypeError naming the index and field. */
+export declare function parseDecisions(value: unknown): Decision[];
+export type PartyOutcome = 'clear' | 'unscreenable' | 'flagged-new' | 'flagged-escalated' | 'flagged-cleared';
+export declare function partyOutcome(r: PartyResult): PartyOutcome;

package/dist/decisions.js

@@ -0,0 +1,118 @@
+/** Unambiguous: both parts are JSON-encoded, so no separator inside an id can shift the boundary. */
+export function decisionKey(partyId, entryKey) {
+    return JSON.stringify([partyId, entryKey]);
+}
+const nonEmpty = (v) => typeof v === 'string' && v !== '';
+/** Records a ruling bound to the party name and CSL entry content the reviewer actually saw. */
+export function makeDecision(result, input) {
+    const reason = input.reason.trim();
+    const reviewer = input.reviewer.trim();
+    if (reason === '')
+        throw new Error('A decision needs a non-blank reason');
+    if (reviewer === '')
+        throw new Error('A decision needs a non-blank reviewer');
+    const decidedAtMs = Date.parse(input.decidedAt);
+    if (!Number.isFinite(decidedAtMs))
+        throw new Error(`decidedAt is not a valid timestamp: ${JSON.stringify(input.decidedAt)}`);
+    if (input.runId !== undefined && !nonEmpty(input.runId))
+        throw new Error('runId, when given, must be a non-empty string');
+    const party = result.parties.find((r) => r.party.id === input.partyId);
+    const match = party?.status === 'flagged' ? party.matches.find((m) => m.entryKey === input.entryKey) : undefined;
+    if (!party || !match)
+        throw new Error(`Party ${input.partyId} is not flagged against entry ${input.entryKey}`);
+    return {
+        check: 'csl',
+        partyId: input.partyId,
+        entryKey: input.entryKey,
+        partyNameKey: party.partyNameKey,
+        entryFingerprint: match.entryFingerprint,
+        decision: input.decision,
+        reason,
+        reviewer,
+        decidedAt: new Date(decidedAtMs).toISOString(),
+        ...(input.runId !== undefined ? { runId: input.runId } : {}),
+    };
+}
+/**
+ * Returns a new result with each match's `state` and `decision` set from the latest decision for its
+ * (party, entry) key. A decision applies only if the party name and CSL entry are unchanged since it was
+ * made; otherwise the match is `new` again. Only the latest decision is considered, so a stale one is not
+ * bypassed by an older valid one. "Latest" compares parsed instants, so offsets and precision do not matter;
+ * a decision whose `decidedAt` does not parse is never latest and never applies. On an exact tie,
+ * `escalated` wins over `cleared`, whatever the array order.
+ */
+export function applyDecisions(result, decisions) {
+    const latest = new Map();
+    for (const d of decisions) {
+        // Defensive: a record that is not a real ruling must never clear or escalate anything.
+        if (d.check !== 'csl')
+            continue;
+        if (d.decision !== 'cleared' && d.decision !== 'escalated')
+            continue;
+        if (typeof d.reason !== 'string' || d.reason.trim() === '')
+            continue;
+        const at = Date.parse(d.decidedAt);
+        if (!Number.isFinite(at))
+            continue;
+        const key = decisionKey(d.partyId, d.entryKey);
+        const cur = latest.get(key);
+        if (!cur || at > cur.at || (at === cur.at && d.decision === 'escalated'))
+            latest.set(key, { d, at });
+    }
+    return {
+        ...result,
+        parties: result.parties.map((r) => {
+            if (r.status !== 'flagged')
+                return r;
+            return {
+                ...r,
+                matches: r.matches.map((m) => {
+                    const { decision: _prior, ...rest } = m;
+                    const d = latest.get(decisionKey(r.party.id, m.entryKey))?.d;
+                    if (!d || d.partyNameKey !== r.partyNameKey || d.entryFingerprint !== m.entryFingerprint) {
+                        return { ...rest, state: 'new' };
+                    }
+                    return { ...rest, state: d.decision, decision: d };
+                }),
+            };
+        }),
+    };
+}
+const nonBlank = (v) => typeof v === 'string' && v.trim() !== '';
+/** Validates persisted decisions (for example a decisions file read from disk). Throws a TypeError naming the index and field. */
+export function parseDecisions(value) {
+    if (!Array.isArray(value))
+        throw new TypeError('decisions must be an array');
+    value.forEach((d, i) => {
+        if (d === null || typeof d !== 'object' || Array.isArray(d))
+            throw new TypeError(`decisions[${i}] is not an object`);
+        const r = d;
+        if (r.check !== 'csl')
+            throw new TypeError(`decisions[${i}].check must be "csl"`);
+        for (const f of ['partyId', 'entryKey', 'partyNameKey', 'entryFingerprint']) {
+            if (!nonEmpty(r[f]))
+                throw new TypeError(`decisions[${i}].${f} must be a non-empty string`);
+        }
+        if (r.decision !== 'cleared' && r.decision !== 'escalated')
+            throw new TypeError(`decisions[${i}].decision must be "cleared" or "escalated"`);
+        if (!nonBlank(r.reason))
+            throw new TypeError(`decisions[${i}].reason must not be blank`);
+        if (!nonBlank(r.reviewer))
+            throw new TypeError(`decisions[${i}].reviewer must not be blank`);
+        if (typeof r.decidedAt !== 'string' || !Number.isFinite(Date.parse(r.decidedAt))) {
+            throw new TypeError(`decisions[${i}].decidedAt must be a valid timestamp`);
+        }
+        if (r.runId !== undefined && !nonEmpty(r.runId))
+            throw new TypeError(`decisions[${i}].runId must be a non-empty string when present`);
+    });
+    return value;
+}
+export function partyOutcome(r) {
+    if (r.status !== 'flagged')
+        return r.status;
+    if (r.matches.some((m) => m.state === 'new'))
+        return 'flagged-new';
+    if (r.matches.some((m) => m.state === 'escalated'))
+        return 'flagged-escalated';
+    return 'flagged-cleared';
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { DEFAULT_STOP_WORDS, hasUnreadableCharacters, nameTokens, normalizeName } from './normalize.js';
+export { jaroWinkler } from './jaroWinkler.js';
+export { canonicalJson, sha256Hex } from './canonical.js';
+export { loadSnapshot, contentHashOf, CslSnapshotError } from './snapshot.js';
+export type { Snapshot, SlimEntry, SnapshotIdentity, LoadSnapshotOptions } from './snapshot.js';
+export { DEFAULT_GENERIC_TOKENS, screen } from './screen.js';
+export { MATCHER_VERSION } from './model.js';
+export type { Party, MatchState, Match, Decision, PartyResult, ScreenOptions, ScreenResult } from './model.js';
+export { decisionKey, makeDecision, applyDecisions, partyOutcome, parseDecisions } from './decisions.js';
+export type { DecisionInput, PartyOutcome } from './decisions.js';
+export { toCsv, toMarkdown } from './render.js';

package/dist/index.js

@@ -0,0 +1,8 @@
+export { DEFAULT_STOP_WORDS, hasUnreadableCharacters, nameTokens, normalizeName } from './normalize.js';
+export { jaroWinkler } from './jaroWinkler.js';
+export { canonicalJson, sha256Hex } from './canonical.js';
+export { loadSnapshot, contentHashOf, CslSnapshotError } from './snapshot.js';
+export { DEFAULT_GENERIC_TOKENS, screen } from './screen.js';
+export { MATCHER_VERSION } from './model.js';
+export { decisionKey, makeDecision, applyDecisions, partyOutcome, parseDecisions } from './decisions.js';
+export { toCsv, toMarkdown } from './render.js';

package/dist/jaroWinkler.d.ts

@@ -0,0 +1,2 @@
+/** Jaro-Winkler similarity in [0, 1]: match window floor(max/2) - 1, common prefix capped at 4, scale 0.1. */
+export declare function jaroWinkler(a: string, b: string): number;

package/dist/jaroWinkler.js

@@ -0,0 +1,41 @@
+/** Jaro-Winkler similarity in [0, 1]: match window floor(max/2) - 1, common prefix capped at 4, scale 0.1. */
+export function jaroWinkler(a, b) {
+    if (a === b)
+        return a.length === 0 ? 0 : 1;
+    if (a.length === 0 || b.length === 0)
+        return 0;
+    const window = Math.max(0, Math.floor(Math.max(a.length, b.length) / 2) - 1);
+    const aMatched = new Array(a.length).fill(false);
+    const bMatched = new Array(b.length).fill(false);
+    let matches = 0;
+    for (let i = 0; i < a.length; i++) {
+        const lo = Math.max(0, i - window);
+        const hi = Math.min(b.length - 1, i + window);
+        for (let j = lo; j <= hi; j++) {
+            if (!bMatched[j] && a[i] === b[j]) {
+                aMatched[i] = true;
+                bMatched[j] = true;
+                matches++;
+                break;
+            }
+        }
+    }
+    if (matches === 0)
+        return 0;
+    let transpositions = 0;
+    let k = 0;
+    for (let i = 0; i < a.length; i++) {
+        if (!aMatched[i])
+            continue;
+        while (!bMatched[k])
+            k++;
+        if (a[i] !== b[k])
+            transpositions++;
+        k++;
+    }
+    const jaro = (matches / a.length + matches / b.length + (matches - transpositions / 2) / matches) / 3;
+    let prefix = 0;
+    while (prefix < 4 && prefix < a.length && prefix < b.length && a[prefix] === b[prefix])
+        prefix++;
+    return jaro + prefix * 0.1 * (1 - jaro);
+}

package/dist/model.d.ts

@@ -0,0 +1,86 @@
+import type { SnapshotIdentity } from './snapshot.js';
+export interface Party {
+    id: string;
+    name: string;
+    /** ISO 3166-1 alpha-2 when known. Only annotates matches; never suppresses one. */
+    country?: string;
+    source: string;
+}
+export type MatchState = 'new' | 'cleared' | 'escalated';
+/** A reviewer's recorded ruling on one party/entry pair, bound to the name and entry content it was made against. */
+export interface Decision {
+    check: 'csl';
+    partyId: string;
+    entryKey: string;
+    partyNameKey: string;
+    entryFingerprint: string;
+    decision: 'cleared' | 'escalated';
+    reason: string;
+    reviewer: string;
+    decidedAt: string;
+    /** The screening run whose result the reviewer read when making this ruling. Optional; the caller names it. */
+    runId?: string;
+}
+export interface Match {
+    /** `${source}|${id}`; unique within a snapshot. */
+    entryKey: string;
+    /** The raw CSL id, which is not unique on its own. */
+    entryId: string;
+    entryFingerprint: string;
+    matchedName: string;
+    listSource: string;
+    programs: string[];
+    entryType: string | null;
+    entryCountries: string[];
+    countryMismatch: boolean;
+    rule: 'exact' | 'contains' | 'within' | 'similar';
+    score: number;
+    reason: string;
+    state: MatchState;
+    decision?: Decision;
+}
+export type PartyResult = {
+    party: Party;
+    partyNameKey: string;
+} & ({
+    status: 'clear';
+} | {
+    status: 'unscreenable';
+    reason: 'empty-name' | 'unreadable-characters';
+} | {
+    status: 'flagged';
+    matches: Match[];
+});
+export interface ScreenOptions {
+    /** Minimum similarity for the `similar` rule. Default 0.9. */
+    threshold?: number;
+    /** Replaces DEFAULT_STOP_WORDS. Entries are normalised like names, so 'Inc' or 'L.L.C.' work. */
+    stopWords?: readonly string[];
+    /** Shortest token that is indexed and used to find candidates. Default 3. */
+    minTokenLength?: number;
+    /**
+     * Replaces DEFAULT_GENERIC_TOKENS: one-word listed entity names that match a party only as its first
+     * token. Normalised like names.
+     */
+    genericTokens?: readonly string[];
+}
+export declare const MATCHER_VERSION = "2";
+export interface ScreenResult {
+    check: 'csl';
+    matcher: {
+        version: string;
+        threshold: number;
+        minTokenLength: number;
+        stopWords: string[];
+        genericTokens: string[];
+    };
+    snapshot: SnapshotIdentity;
+    counts: {
+        parties: number;
+        screened: number;
+        unscreenable: number;
+        clear: number;
+        flagged: number;
+    };
+    parties: PartyResult[];
+}

package/dist/model.js

@@ -0,0 +1 @@
+export const MATCHER_VERSION = '2';

package/dist/normalize.d.ts

@@ -0,0 +1,17 @@
+/** Legal-form suffixes and filler words that carry no identity for name matching. */
+export declare const DEFAULT_STOP_WORDS: readonly string[];
+/**
+ * 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 declare function hasUnreadableCharacters(name: string): boolean;
+/**
+ * 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 declare function nameTokens(name: string, stopWords: ReadonlySet<string>): string[];
+export declare function normalizeName(name: string, stopWords: ReadonlySet<string>): string;