@cyanheads/sanctions-screening-mcp-server 0.1.0

package/dist/services/screening/types.d.ts

@@ -0,0 +1,154 @@
+/**
+ * @fileoverview Common normalized schema for sanctions designations and GLEIF
+ * legal-entity records, plus the matching-engine vocabulary. Every upstream
+ * source (OFAC, EU, UK, UN, GLEIF) collapses onto these shapes so the matching
+ * engine and tools never see a source-specific structure.
+ * @module services/screening/types
+ */
+/** Source list codes — the value stored in `designation.source`. */
+export type SourceCode = 'ofac_sdn' | 'ofac_consolidated' | 'eu' | 'uk' | 'un';
+/** All sanctions source codes, in display order. */
+export declare const SOURCE_CODES: readonly SourceCode[];
+/** Human-facing label per source, used in provenance and `sanctions_list_sources`. */
+export declare const SOURCE_LABELS: Record<SourceCode, string>;
+/** Coarse entity classification shared across all sources. */
+export type EntityType = 'person' | 'organization' | 'vessel' | 'aircraft' | 'unknown';
+/** Name-record provenance within a designation. */
+export type NameType = 'primary' | 'aka' | 'fka' | 'low-quality-aka';
+/** One name or alias attached to a designation. */
+export interface NameRecord {
+    /** The name as published. */
+    name: string;
+    /** Provenance of this name. */
+    nameType: NameType;
+}
+/** A structured identifier (passport, national ID, tax ID, registration number, …). */
+export interface IdentifierRecord {
+    /** Issuing country/authority, when published. */
+    country?: string;
+    /** Identifier category as published (e.g. "Passport", "National ID"). */
+    type: string;
+    /** The identifier value. */
+    value: string;
+}
+/** A published address (free-form components — sources vary widely). */
+export interface AddressRecord {
+    /** ISO country or country name, when published. */
+    country?: string;
+    /** Single-line rendering of the address, joined from whatever components were published. */
+    full: string;
+}
+/** Date + place of birth (persons only). */
+export interface DobRecord {
+    /** Date string as published (ISO 8601 where the source provides a clean date). */
+    date?: string;
+    /** Place of birth, when published. */
+    place?: string;
+}
+/**
+ * The full normalized record for one designation, stored as JSON in
+ * `designation.payload` and surfaced by `sanctions_get_designation`.
+ */
+export interface DesignationPayload {
+    addresses: AddressRecord[];
+    aliases: NameRecord[];
+    datesOfBirth: DobRecord[];
+    identifiers: IdentifierRecord[];
+    nationalities: string[];
+    /** Free-form remarks/title published by the source, when present. */
+    remarks?: string;
+}
+/**
+ * One normalized designation — the unit an ingester yields and the row stored
+ * in the primary `designation` table (with `payload` JSON-stringified).
+ */
+export interface NormalizedDesignation {
+    /** Designation date, ISO 8601 where available. */
+    designationDate?: string;
+    entityType: EntityType;
+    /** `{source}:{sourceEntryId}` composite primary key. */
+    id: string;
+    /** Statutory / regulatory basis, when published. */
+    legalBasis?: string;
+    /** Full normalized detail. */
+    payload: DesignationPayload;
+    /** Primary name as published. */
+    primaryName: string;
+    /** Sanctioning program / regime, when published. */
+    program?: string;
+    source: SourceCode;
+    /** The list's own entry ID (for `get_designation`). */
+    sourceEntryId: string;
+}
+/** A GLEIF Level 1 entity record (who-is-who). */
+export interface NormalizedLeiEntity {
+    /** Single-line headquarters address. */
+    headquartersAddress?: string;
+    /** ISO 3166-1 alpha-2 jurisdiction, when published. */
+    jurisdiction?: string;
+    /** ISO 8601 last-update timestamp from the LEI record. */
+    lastUpdate?: string;
+    /** Single-line legal address. */
+    legalAddress?: string;
+    legalName: string;
+    lei: string;
+    /** Trading / other names published in the LEI record. */
+    otherNames: string[];
+    /** The entity's ID at its registration authority. */
+    registrationAuthorityEntityId?: string;
+    /** Registration authority identifier (RA code). */
+    registrationAuthorityId?: string;
+    /** Registration status (e.g. ISSUED, LAPSED). */
+    status?: string;
+}
+/** A GLEIF Level 2 relationship record (who-owns-whom). */
+export interface NormalizedLeiRelationship {
+    childLei: string;
+    parentLei: string;
+    /** Relationship period summary, when published. */
+    relationshipPeriod?: string;
+    /** Accounting/relationship status (e.g. ACTIVE, INACTIVE). */
+    relationshipStatus?: string;
+    /** e.g. IS_DIRECTLY_CONSOLIDATED_BY, IS_ULTIMATELY_CONSOLIDATED_BY. */
+    relationshipType: string;
+}
+/** Match classification, in descending confidence. */
+export type MatchType = 'exact' | 'strong' | 'approximate';
+/** The two screening match modes. */
+export type MatchMode = 'strict' | 'fuzzy';
+/** A scored screening hit returned by the matching engine. */
+export interface ScreeningHit {
+    designationDate?: string;
+    /** `{source}:{sourceEntryId}` of the matched designation. */
+    designationId: string;
+    entityType: EntityType;
+    /** The specific name/alias string that matched the query. */
+    matchedName: string;
+    /** Provenance of the matched name (primary / aka / fka / low-quality-aka). */
+    matchedNameType: NameType;
+    matchType: MatchType;
+    /** Primary published name of the matched designation. */
+    primaryName: string;
+    program?: string;
+    /**
+     * Raw Jaro-Winkler similarity (0–1) for `approximate` hits — a real
+     * measurement, never a fabricated composite. Omitted for exact/strong hits,
+     * which are deterministic and not scored.
+     */
+    score?: number;
+    source: SourceCode;
+    sourceEntryId: string;
+}
+/** A scored LEI resolution candidate. */
+export interface LeiMatch {
+    jurisdiction?: string;
+    legalName: string;
+    lei: string;
+    /** The name (legal or other) that matched the query. */
+    matchedName: string;
+    matchType: MatchType;
+    /** Raw Jaro-Winkler similarity for `approximate` hits only. */
+    score?: number;
+    status?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/services/screening/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/services/screening/types.ts"],"names":[],"mappings":"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"}

package/dist/services/screening/types.js

@@ -0,0 +1,24 @@
+/**
+ * @fileoverview Common normalized schema for sanctions designations and GLEIF
+ * legal-entity records, plus the matching-engine vocabulary. Every upstream
+ * source (OFAC, EU, UK, UN, GLEIF) collapses onto these shapes so the matching
+ * engine and tools never see a source-specific structure.
+ * @module services/screening/types
+ */
+/** All sanctions source codes, in display order. */
+export const SOURCE_CODES = [
+    'ofac_sdn',
+    'ofac_consolidated',
+    'eu',
+    'uk',
+    'un',
+];
+/** Human-facing label per source, used in provenance and `sanctions_list_sources`. */
+export const SOURCE_LABELS = {
+    ofac_sdn: 'OFAC Specially Designated Nationals (SDN) List',
+    ofac_consolidated: 'OFAC Consolidated Sanctions List',
+    eu: 'EU Consolidated Financial Sanctions List',
+    uk: 'UK Sanctions List (FCDO)',
+    un: 'UN Security Council Consolidated List',
+};
+//# sourceMappingURL=types.js.map

package/dist/services/screening/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/services/screening/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,oDAAoD;AACpD,MAAM,CAAC,MAAM,YAAY,GAA0B;IACjD,UAAU;IACV,mBAAmB;IACnB,IAAI;IACJ,IAAI;IACJ,IAAI;CACI,CAAC;AAEX,sFAAsF;AACtF,MAAM,CAAC,MAAM,aAAa,GAA+B;IACvD,QAAQ,EAAE,gDAAgD;IAC1D,iBAAiB,EAAE,kCAAkC;IACrD,EAAE,EAAE,0CAA0C;IAC9C,EAAE,EAAE,0BAA0B;IAC9B,EAAE,EAAE,uCAAuC;CAC5C,CAAC"}

package/dist/services/screening/xml.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @fileoverview Server-local XML parser for the attribute-bearing sanctions and
+ * GLEIF data feeds. The framework's shared `xmlParser`
+ * (`@cyanheads/mcp-ts-core/utils`) is tuned for LLM structured output and
+ * constructs `fast-xml-parser` with its default `ignoreAttributes: true` — every
+ * XML attribute is dropped. That is fatal here: the OFAC advanced schema, the EU
+ * `xmlFullSanctionsList_1_1`, and parts of the GLEIF golden copy carry their
+ * load-bearing data (stable entry IDs, name strings, type codes, programmes,
+ * publication dates) in XML *attributes*, not element text. With attributes
+ * ignored the EU list parses to zero designations and OFAC loses its entry IDs,
+ * entity types, programmes, and dates.
+ *
+ * This parser turns attributes on with the `@_` prefix the ingesters read
+ * (`@_FixedRef`, `@_wholeName`, `@_code`, `@_publicationDate`, …) and is the only
+ * XML entry point the screening ingesters use. `processEntities: false` matches
+ * the framework's safe default (no entity expansion on untrusted bulk input).
+ * @module services/screening/xml
+ */
+/**
+ * Parse an XML document string into a plain object, preserving attributes under
+ * the `@_` prefix. Synchronous — `fast-xml-parser` is a direct dependency, so
+ * there is no lazy-load step.
+ *
+ * @template T Expected shape of the parsed document.
+ * @param xml Raw XML string.
+ * @returns The parsed document.
+ */
+export declare function parseXml<T = Record<string, unknown>>(xml: string): T;
+//# sourceMappingURL=xml.d.ts.map

package/dist/services/screening/xml.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xml.d.ts","sourceRoot":"","sources":["../../../src/services/screening/xml.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAmBH;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,CAEpE"}

package/dist/services/screening/xml.js

@@ -0,0 +1,46 @@
+/**
+ * @fileoverview Server-local XML parser for the attribute-bearing sanctions and
+ * GLEIF data feeds. The framework's shared `xmlParser`
+ * (`@cyanheads/mcp-ts-core/utils`) is tuned for LLM structured output and
+ * constructs `fast-xml-parser` with its default `ignoreAttributes: true` — every
+ * XML attribute is dropped. That is fatal here: the OFAC advanced schema, the EU
+ * `xmlFullSanctionsList_1_1`, and parts of the GLEIF golden copy carry their
+ * load-bearing data (stable entry IDs, name strings, type codes, programmes,
+ * publication dates) in XML *attributes*, not element text. With attributes
+ * ignored the EU list parses to zero designations and OFAC loses its entry IDs,
+ * entity types, programmes, and dates.
+ *
+ * This parser turns attributes on with the `@_` prefix the ingesters read
+ * (`@_FixedRef`, `@_wholeName`, `@_code`, `@_publicationDate`, …) and is the only
+ * XML entry point the screening ingesters use. `processEntities: false` matches
+ * the framework's safe default (no entity expansion on untrusted bulk input).
+ * @module services/screening/xml
+ */
+import { XMLParser } from 'fast-xml-parser';
+/**
+ * Shared parser instance. `fast-xml-parser` is stateless across `parse` calls,
+ * so one instance is reused for every source.
+ */
+const parser = new XMLParser({
+    ignoreAttributes: false,
+    attributeNamePrefix: '@_',
+    processEntities: false,
+    // Keep numeric-looking ids (LEIs, entry ids) as strings — they are opaque
+    // identifiers, not numbers, and downstream code treats them as text.
+    parseAttributeValue: false,
+    parseTagValue: false,
+    trimValues: true,
+});
+/**
+ * Parse an XML document string into a plain object, preserving attributes under
+ * the `@_` prefix. Synchronous — `fast-xml-parser` is a direct dependency, so
+ * there is no lazy-load step.
+ *
+ * @template T Expected shape of the parsed document.
+ * @param xml Raw XML string.
+ * @returns The parsed document.
+ */
+export function parseXml(xml) {
+    return parser.parse(xml);
+}
+//# sourceMappingURL=xml.js.map

package/dist/services/screening/xml.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"xml.js","sourceRoot":"","sources":["../../../src/services/screening/xml.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C;;;GAGG;AACH,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;IAC3B,gBAAgB,EAAE,KAAK;IACvB,mBAAmB,EAAE,IAAI;IACzB,eAAe,EAAE,KAAK;IACtB,0EAA0E;IAC1E,qEAAqE;IACrE,mBAAmB,EAAE,KAAK;IAC1B,aAAa,EAAE,KAAK;IACpB,UAAU,EAAE,IAAI;CACjB,CAAC,CAAC;AAEH;;;;;;;;GAQG;AACH,MAAM,UAAU,QAAQ,CAA8B,GAAW;IAC/D,OAAO,MAAM,CAAC,KAAK,CAAC,GAAG,CAAM,CAAC;AAChC,CAAC"}

package/package.json

@@ -0,0 +1,119 @@
+{
+  "name": "@cyanheads/sanctions-screening-mcp-server",
+  "version": "0.1.0",
+  "mcpName": "io.github.cyanheads/sanctions-screening-mcp-server",
+  "description": "Screen names against the consolidated OFAC, EU, UK, and UN sanctions lists and resolve legal entities against GLEIF, fuzzy-matched offline over a local SQLite + FTS5 mirror. A screening aid, not a compliance determination.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "sanctions-screening-mcp-server": "dist/index.js"
+  },
+  "files": [
+    "changelog/",
+    "dist/",
+    "scripts/_mirror-context.ts",
+    "scripts/mirror-init.ts",
+    "scripts/mirror-refresh.ts",
+    "scripts/mirror-verify.ts",
+    "scripts/mirror-seed.ts",
+    "README.md",
+    "LICENSE",
+    "CLAUDE.md",
+    "AGENTS.md",
+    "Dockerfile",
+    "server.json"
+  ],
+  "scripts": {
+    "build": "bun run scripts/build.ts",
+    "rebuild": "bun run scripts/clean.ts && bun run scripts/build.ts",
+    "clean": "bun run scripts/clean.ts",
+    "devcheck": "bun run scripts/devcheck.ts",
+    "audit:refresh": "rm -f bun.lock && bun install && bun audit",
+    "tree": "bun run scripts/tree.ts",
+    "list-skills": "bun run scripts/list-skills.ts",
+    "format": "biome check --write .",
+    "format:unsafe": "biome check --write --unsafe .",
+    "lint:mcp": "bun run scripts/lint-mcp.ts",
+    "lint:packaging": "bun run scripts/lint-packaging.ts",
+    "bundle": "bun run build && npx -y @anthropic-ai/mcpb pack . dist/sanctions-screening-mcp-server.mcpb && bun run scripts/clean-mcpb.ts dist/sanctions-screening-mcp-server.mcpb",
+    "changelog:build": "bun run scripts/build-changelog.ts",
+    "changelog:check": "bun run scripts/build-changelog.ts --check",
+    "release:github": "bun run scripts/release-github.ts",
+    "publish-mcp": "mcp-publisher login github -token \"$(security find-generic-password -a \"$USER\" -s mcp-publisher-github-pat -w)\" && mcp-publisher publish",
+    "test": "vitest run",
+    "start": "node dist/index.js",
+    "start:stdio": "MCP_TRANSPORT_TYPE=stdio node dist/index.js",
+    "start:http": "MCP_TRANSPORT_TYPE=http node dist/index.js",
+    "mirror:init": "bun run scripts/mirror-init.ts",
+    "mirror:refresh": "bun run scripts/mirror-refresh.ts",
+    "mirror:verify": "bun run scripts/mirror-verify.ts",
+    "mirror:seed": "bun run scripts/mirror-seed.ts"
+  },
+  "keywords": [
+    "sanctions",
+    "sanctions-screening",
+    "ofac",
+    "ofac-sdn",
+    "aml",
+    "kyc",
+    "compliance",
+    "watchlist",
+    "gleif",
+    "lei",
+    "beneficial-ownership",
+    "due-diligence",
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "typescript",
+    "bun",
+    "stdio",
+    "streamable-http",
+    "ai-agent"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cyanheads/sanctions-screening-mcp-server.git"
+  },
+  "bugs": {
+    "url": "https://github.com/cyanheads/sanctions-screening-mcp-server/issues"
+  },
+  "homepage": "https://github.com/cyanheads/sanctions-screening-mcp-server#readme",
+  "author": "cyanheads <casey@caseyjhand.com> (https://github.com/cyanheads)",
+  "funding": [
+    {
+      "type": "github",
+      "url": "https://github.com/sponsors/cyanheads"
+    },
+    {
+      "type": "buy_me_a_coffee",
+      "url": "https://www.buymeacoffee.com/cyanheads"
+    }
+  ],
+  "license": "Apache-2.0",
+  "packageManager": "bun@1.3.11",
+  "engines": {
+    "bun": ">=1.3.0",
+    "node": ">=24.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@cyanheads/mcp-ts-core": "^0.10.6",
+    "better-sqlite3": "^12.4.1",
+    "fast-xml-parser": "^5.8.0",
+    "pino-pretty": "^13.1.3",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.0",
+    "@types/node": "25.9.3",
+    "depcheck": "^1.4.7",
+    "ignore": "^7.0.5",
+    "tsc-alias": "^1.8.17",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
+  }
+}

package/scripts/_mirror-context.ts

@@ -0,0 +1,21 @@
+/**
+ * @fileoverview Shared bootstrap for the mirror lifecycle scripts
+ * (`mirror:init`, `mirror:refresh`, `mirror:verify`, `mirror:seed`). Builds a
+ * standalone ScreeningService outside the MCP request pipeline and exposes the
+ * framework logger. Imported by the three named scripts, so it must travel with
+ * them in the npm tarball / Docker image.
+ * @module scripts/_mirror-context
+ */
+
+import { logger } from '@cyanheads/mcp-ts-core/utils';
+import { buildScreeningService } from '@/services/screening/screening-service.js';
+
+/** Build a fresh, standalone screening service for a lifecycle script. */
+export function bootstrap() {
+  return { service: buildScreeningService(), log: logger };
+}
+
+/** A long, abortable signal for hours-long init runs (caps a runaway harvest). */
+export function longRunSignal(hours = 6): AbortSignal {
+  return AbortSignal.timeout(hours * 60 * 60 * 1000);
+}

package/scripts/mirror-init.ts

@@ -0,0 +1,66 @@
+/**
+ * @fileoverview `mirror:init` — full out-of-band initialization of the local
+ * mirror from the live upstream sources. Harvests all four sanctions lists in
+ * full (via the MirrorService `init` sync), rebuilds the per-alias name index,
+ * then streams the GLEIF golden copy (Level 1 entities + Level 2 relationships).
+ * Hours-long and resumable; never run on the request path. Set
+ * `SANCTIONS_INIT_SKIP_GLEIF=1` to load only the (small) sanctions lists.
+ *
+ * Usage: `bun run mirror:init`
+ * @module scripts/mirror-init
+ */
+
+import {
+  harvestLeiLevel1,
+  harvestLeiLevel2,
+  resolveGleifFileUrl,
+} from '@/services/screening/gleif-ingest.js';
+import { bootstrap, longRunSignal } from './_mirror-context.js';
+
+async function main(): Promise<void> {
+  const { service, log } = bootstrap();
+  const signal = longRunSignal(8);
+
+  log.info('mirror:init — harvesting sanctions lists (full)');
+  const sanctions = await service.designations.runSync({ mode: 'init', signal });
+  log.info('mirror:init — sanctions harvest complete', {
+    records: sanctions.recordsApplied,
+    total: sanctions.total,
+  });
+  await service.rebuildNameIndex();
+  log.info('mirror:init — name index rebuilt');
+
+  if (process.env.SANCTIONS_INIT_SKIP_GLEIF === '1') {
+    log.notice(
+      'mirror:init — SANCTIONS_INIT_SKIP_GLEIF set; skipping GLEIF (sanctions-only mirror)',
+    );
+    await service.close();
+    return;
+  }
+
+  log.info('mirror:init — resolving GLEIF golden-copy URLs');
+  const [l1Url, l2Url] = await Promise.all([
+    resolveGleifFileUrl('lei2-full', signal),
+    resolveGleifFileUrl('rr-full', signal),
+  ]);
+
+  log.info('mirror:init — streaming GLEIF Level 1 (who-is-who, ~3.3M records)');
+  const entities = await harvestLeiLevel1(l1Url, signal);
+  await service.ingestLeiEntities(entities);
+  log.info('mirror:init — GLEIF Level 1 loaded', { entities: entities.length });
+
+  log.info('mirror:init — streaming GLEIF Level 2 (who-owns-whom)');
+  const relationships = await harvestLeiLevel2(l2Url, signal);
+  await service.ingestLeiRelationships(relationships);
+  log.info('mirror:init — GLEIF Level 2 loaded', { relationships: relationships.length });
+
+  await service.markLeiReady(entities.length);
+  log.info('mirror:init — complete');
+  await service.close();
+}
+
+main().catch((err) => {
+  // eslint-disable-next-line no-console
+  console.error('mirror:init failed:', err);
+  process.exit(1);
+});

package/scripts/mirror-refresh.ts

@@ -0,0 +1,56 @@
+/**
+ * @fileoverview `mirror:refresh` — incremental out-of-band refresh. Re-harvests
+ * the (small) sanctions lists in full and rebuilds the name index, then applies
+ * the GLEIF 8-hour deltas. The HTTP server runs the sanctions half of this on a
+ * cron automatically; stdio operators run this manually. Set
+ * `SANCTIONS_REFRESH_SKIP_GLEIF=1` to refresh only the sanctions lists.
+ *
+ * Usage: `bun run mirror:refresh`
+ * @module scripts/mirror-refresh
+ */
+
+import {
+  harvestLeiLevel1,
+  harvestLeiLevel2,
+  resolveGleifFileUrl,
+} from '@/services/screening/gleif-ingest.js';
+import { bootstrap, longRunSignal } from './_mirror-context.js';
+
+async function main(): Promise<void> {
+  const { service, log } = bootstrap();
+  const signal = longRunSignal(4);
+
+  log.info('mirror:refresh — re-harvesting sanctions lists');
+  const sanctions = await service.designations.runSync({ mode: 'refresh', signal });
+  await service.rebuildNameIndex();
+  log.info('mirror:refresh — sanctions refreshed', { records: sanctions.recordsApplied });
+
+  if (process.env.SANCTIONS_REFRESH_SKIP_GLEIF === '1') {
+    log.notice('mirror:refresh — SANCTIONS_REFRESH_SKIP_GLEIF set; skipping GLEIF deltas');
+    await service.close();
+    return;
+  }
+
+  log.info('mirror:refresh — applying GLEIF deltas (LastDay)');
+  const [l1Url, l2Url] = await Promise.all([
+    resolveGleifFileUrl('lei2-delta', signal, 'LastDay'),
+    resolveGleifFileUrl('rr-delta', signal, 'LastDay'),
+  ]);
+  const entities = await harvestLeiLevel1(l1Url, signal);
+  await service.ingestLeiEntities(entities);
+  const relationships = await harvestLeiLevel2(l2Url, signal);
+  await service.ingestLeiRelationships(relationships);
+  log.info('mirror:refresh — GLEIF deltas applied', {
+    entities: entities.length,
+    relationships: relationships.length,
+  });
+
+  log.info('mirror:refresh — complete');
+  await service.close();
+}
+
+main().catch((err) => {
+  // eslint-disable-next-line no-console
+  console.error('mirror:refresh failed:', err);
+  process.exit(1);
+});

package/scripts/mirror-seed.ts

@@ -0,0 +1,36 @@
+/**
+ * @fileoverview `mirror:seed` — load the small synthetic fixture into the local
+ * mirror and mark it ready, for a quick local smoke run without downloading the
+ * real corpus. The fixture names are invented, NOT real sanctions designations.
+ * For production data use `mirror:init`.
+ *
+ * Usage: `bun run mirror:seed`
+ * @module scripts/mirror-seed
+ */
+
+import {
+  FIXTURE_DESIGNATIONS,
+  FIXTURE_LEI_ENTITIES,
+  FIXTURE_LEI_RELATIONSHIPS,
+} from '@/services/screening/fixtures.js';
+import { bootstrap } from './_mirror-context.js';
+
+async function main(): Promise<void> {
+  const { service, log } = bootstrap();
+  await service.seedFixtures({
+    designations: FIXTURE_DESIGNATIONS,
+    leiEntities: FIXTURE_LEI_ENTITIES,
+    leiRelationships: FIXTURE_LEI_RELATIONSHIPS,
+  });
+  log.notice('mirror:seed — synthetic fixture loaded (NOT real sanctions data)', {
+    designations: FIXTURE_DESIGNATIONS.length,
+    leiEntities: FIXTURE_LEI_ENTITIES.length,
+  });
+  await service.close();
+}
+
+main().catch((err) => {
+  // eslint-disable-next-line no-console
+  console.error('mirror:seed failed:', err);
+  process.exit(1);
+});

package/scripts/mirror-verify.ts

@@ -0,0 +1,44 @@
+/**
+ * @fileoverview `mirror:verify` — readiness + freshness report for both mirrors.
+ * Prints per-source record counts, the sanctions/GLEIF readiness flags, and the
+ * last-completed timestamps. Read-only; safe to run anytime.
+ *
+ * Usage: `bun run mirror:verify`
+ * @module scripts/mirror-verify
+ */
+
+import { bootstrap } from './_mirror-context.js';
+
+async function main(): Promise<void> {
+  const { service, log } = bootstrap();
+  const [counts, sanctions, lei] = await Promise.all([
+    service.sourceCounts(),
+    service.sanctionsReadiness(),
+    service.leiReadiness(),
+  ]);
+
+  log.info('mirror:verify — sanctions mirror', {
+    ready: sanctions.ready,
+    total: sanctions.total,
+    completedAt: sanctions.completedAt ?? 'never',
+    status: sanctions.status,
+  });
+  for (const s of counts) {
+    log.info(`  source ${s.code}`, { records: s.recordCount });
+  }
+  log.info('mirror:verify — GLEIF mirror', {
+    ready: lei.ready,
+    entities: lei.entityCount,
+    relationships: lei.relationshipCount,
+    completedAt: lei.completedAt ?? 'never',
+    status: lei.status,
+  });
+
+  await service.close();
+}
+
+main().catch((err) => {
+  // eslint-disable-next-line no-console
+  console.error('mirror:verify failed:', err);
+  process.exit(1);
+});