@cyanheads/sanctions-screening-mcp-server 0.1.0

package/dist/mcp-server/tools/definitions/trace-ownership.tool.d.ts

@@ -0,0 +1,74 @@
+/**
+ * @fileoverview `sanctions_trace_ownership` — the GLEIF Level 2 ownership graph
+ * for an LEI: direct and ultimate parents and children, with relationship type,
+ * traversed breadth-first to a bounded depth. Optionally screens every node
+ * against the watchlists — beneficial-ownership screening that single-list tools
+ * can't do, and the cross-source workflow that justifies one server over two.
+ * @module mcp-server/tools/definitions/trace-ownership.tool
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const traceOwnershipTool: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    lei: z.ZodString;
+    direction: z.ZodDefault<z.ZodEnum<{
+        parents: "parents";
+        children: "children";
+        both: "both";
+    }>>;
+    depth: z.ZodDefault<z.ZodNumber>;
+    screenNodes: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>, z.ZodObject<{
+    rootLei: z.ZodString;
+    nodes: z.ZodArray<z.ZodObject<{
+        lei: z.ZodString;
+        legalName: z.ZodString;
+        jurisdiction: z.ZodOptional<z.ZodString>;
+        status: z.ZodOptional<z.ZodString>;
+        depth: z.ZodNumber;
+        role: z.ZodEnum<{
+            root: "root";
+            parent: "parent";
+            child: "child";
+        }>;
+        sanctionsHits: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            source: z.ZodEnum<{
+                ofac_sdn: "ofac_sdn";
+                ofac_consolidated: "ofac_consolidated";
+                eu: "eu";
+                uk: "uk";
+                un: "un";
+            }>;
+            sourceLabel: z.ZodString;
+            sourceEntryId: z.ZodString;
+            primaryName: z.ZodString;
+            matchedName: z.ZodString;
+            matchType: z.ZodEnum<{
+                exact: "exact";
+                strong: "strong";
+                approximate: "approximate";
+            }>;
+            score: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+    edges: z.ZodArray<z.ZodObject<{
+        childLei: z.ZodString;
+        parentLei: z.ZodString;
+        relationshipType: z.ZodString;
+        relationshipStatus: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    screenedNodeCount: z.ZodNumber;
+    flaggedNodeCount: z.ZodNumber;
+    caveat: z.ZodString;
+}, z.core.$strip>, readonly [{
+    readonly reason: "lei_not_found";
+    readonly code: JsonRpcErrorCode.NotFound;
+    readonly when: "No GLEIF entity exists for the root LEI in the mirror.";
+    readonly recovery: "Resolve the entity name with sanctions_resolve_entity to obtain a valid root LEI first.";
+}, {
+    readonly reason: "mirror_not_ready";
+    readonly code: JsonRpcErrorCode.ServiceUnavailable;
+    readonly when: "The GLEIF (LEI) mirror has never completed an initial sync.";
+    readonly retryable: true;
+    readonly recovery: "Run the mirror:init lifecycle script to load the GLEIF golden copy + relationships, then retry.";
+}], undefined>;
+//# sourceMappingURL=trace-ownership.tool.d.ts.map

package/dist/mcp-server/tools/definitions/trace-ownership.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-ownership.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/trace-ownership.tool.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAyEjE,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAoP7B,CAAC"}

package/dist/mcp-server/tools/definitions/trace-ownership.tool.js

@@ -0,0 +1,273 @@
+/**
+ * @fileoverview `sanctions_trace_ownership` — the GLEIF Level 2 ownership graph
+ * for an LEI: direct and ultimate parents and children, with relationship type,
+ * traversed breadth-first to a bounded depth. Optionally screens every node
+ * against the watchlists — beneficial-ownership screening that single-list tools
+ * can't do, and the cross-source workflow that justifies one server over two.
+ * @module mcp-server/tools/definitions/trace-ownership.tool
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { getScreeningService } from '../../../services/screening/screening-service.js';
+import { SOURCE_CODES, SOURCE_LABELS } from '../../../services/screening/types.js';
+import { SCREENING_CAVEAT } from './_shared.js';
+const LEI_RE = /^[A-Z0-9]{18}[0-9]{2}$/;
+/**
+ * Breadth-first traversal over the relationship table to `depth`, in the
+ * requested direction(s). Returns nodes (deduped) and edges. The traversal is
+ * bounded by `depth` and by the relationship table itself (the mirror's corpus),
+ * so it terminates even on cyclic ownership structures via the visited set.
+ */
+async function traverse(svc, rootLei, direction, depth) {
+    const nodes = new Map();
+    const edges = [];
+    const seenEdges = new Set();
+    nodes.set(rootLei, { lei: rootLei, legalName: rootLei, depth: 0, role: 'root' });
+    let frontier = [rootLei];
+    for (let level = 0; level < depth && frontier.length > 0; level++) {
+        const next = [];
+        for (const lei of frontier) {
+            const rels = await svc.getRelationships(lei, direction);
+            for (const rel of rels) {
+                const edgeKey = `${rel.childLei}|${rel.parentLei}|${rel.relationshipType}`;
+                if (!seenEdges.has(edgeKey)) {
+                    seenEdges.add(edgeKey);
+                    edges.push({
+                        childLei: rel.childLei,
+                        parentLei: rel.parentLei,
+                        relationshipType: rel.relationshipType,
+                        ...(rel.relationshipStatus ? { relationshipStatus: rel.relationshipStatus } : {}),
+                    });
+                }
+                // The neighbor is whichever end of the edge isn't `lei`.
+                const neighbor = rel.childLei === lei ? rel.parentLei : rel.childLei;
+                const role = rel.childLei === lei ? 'parent' : 'child';
+                if (!nodes.has(neighbor)) {
+                    nodes.set(neighbor, { lei: neighbor, legalName: neighbor, depth: level + 1, role });
+                    next.push(neighbor);
+                }
+            }
+        }
+        frontier = next;
+    }
+    return { nodes, edges };
+}
+export const traceOwnershipTool = tool('sanctions_trace_ownership', {
+    title: 'sanctions-screening-mcp-server: trace ownership',
+    description: 'Trace the GLEIF Level 2 corporate-ownership graph for an LEI: direct and ultimate parents and/or children, traversed breadth-first to a bounded depth, with relationship type for each edge. Set screen_nodes to also screen every entity in the graph against all loaded watchlists — beneficial-ownership screening that resolves "is anyone in this ownership chain sanctioned." Each per-node screen is a screening AID: hits are candidates to verify, and an empty result for a node is not a clearance of that node. Requires a valid 20-character LEI (use sanctions_resolve_entity to obtain one).',
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    input: z.object({
+        lei: z
+            .string()
+            .regex(LEI_RE, 'LEI must be 20 chars: 18 alphanumerics + 2 check digits.')
+            .describe('The 20-character GLEIF LEI at the root of the ownership graph.'),
+        direction: z
+            .enum(['parents', 'children', 'both'])
+            .default('both')
+            .describe('Walk parents (who owns it), children (what it owns), or both (default).'),
+        depth: z
+            .number()
+            .int()
+            .min(1)
+            .max(5)
+            .default(3)
+            .describe('Maximum traversal depth from the root entity (1–5).'),
+        screenNodes: z
+            .boolean()
+            .default(false)
+            .describe("When true, screen every node's legal name against all watchlists for beneficial-ownership screening."),
+    }),
+    output: z.object({
+        rootLei: z.string().describe('The LEI the traversal started from.'),
+        nodes: z
+            .array(z
+            .object({
+            lei: z.string().describe("The node's LEI."),
+            legalName: z
+                .string()
+                .describe("The node's legal name (the LEI itself if not hydrated)."),
+            jurisdiction: z.string().optional().describe('Jurisdiction (ISO code), when known.'),
+            status: z.string().optional().describe('GLEIF registration status, when known.'),
+            depth: z.number().describe('Breadth-first depth from the root (root = 0).'),
+            role: z
+                .enum(['root', 'parent', 'child'])
+                .describe('Position relative to the traversal.'),
+            sanctionsHits: z
+                .array(z
+                .object({
+                source: z
+                    .enum(['ofac_sdn', 'ofac_consolidated', 'eu', 'uk', 'un'])
+                    .describe('Watchlist the candidate is on.'),
+                sourceLabel: z.string().describe('Human-readable source list name.'),
+                sourceEntryId: z
+                    .string()
+                    .describe('Source entry ID — pass to sanctions_get_designation.'),
+                primaryName: z.string().describe('Primary published name of the designation.'),
+                matchedName: z.string().describe('The name/alias that matched this node.'),
+                matchType: z
+                    .enum(['exact', 'strong', 'approximate'])
+                    .describe('Match classification.'),
+                score: z
+                    .number()
+                    .optional()
+                    .describe('Raw Jaro-Winkler similarity (0–1) for approximate hits only.'),
+            })
+                .describe('A potential watchlist match on this node — verify, do not assume.'))
+                .optional()
+                .describe('Per-node screening results, present only when screen_nodes is true.'),
+        })
+            .describe('One entity in the ownership graph.'))
+            .describe('All entities reached in the traversal, including the root.'),
+        edges: z
+            .array(z
+            .object({
+            childLei: z.string().describe('LEI of the owned (child) entity.'),
+            parentLei: z.string().describe('LEI of the owning (parent) entity.'),
+            relationshipType: z
+                .string()
+                .describe('GLEIF relationship type (e.g. IS_DIRECTLY_CONSOLIDATED_BY).'),
+            relationshipStatus: z
+                .string()
+                .optional()
+                .describe('Relationship status, when published.'),
+        })
+            .describe('One directed ownership edge (child is consolidated by parent).'))
+            .describe('Directed ownership edges between the nodes.'),
+        screenedNodeCount: z
+            .number()
+            .describe('How many nodes were screened (0 when screen_nodes is false).'),
+        flaggedNodeCount: z
+            .number()
+            .describe('How many screened nodes had at least one potential watchlist match.'),
+        caveat: z
+            .string()
+            .describe('Decision-support caveat — node screening is an aid, not a determination.'),
+    }),
+    errors: [
+        {
+            reason: 'lei_not_found',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'No GLEIF entity exists for the root LEI in the mirror.',
+            recovery: 'Resolve the entity name with sanctions_resolve_entity to obtain a valid root LEI first.',
+        },
+        {
+            reason: 'mirror_not_ready',
+            code: JsonRpcErrorCode.ServiceUnavailable,
+            when: 'The GLEIF (LEI) mirror has never completed an initial sync.',
+            retryable: true,
+            recovery: 'Run the mirror:init lifecycle script to load the GLEIF golden copy + relationships, then retry.',
+        },
+    ],
+    async handler(input, ctx) {
+        const svc = getScreeningService();
+        if (!(await svc.leiReady())) {
+            throw ctx.fail('mirror_not_ready', 'The local GLEIF (LEI) mirror is not yet populated.', {
+                ...ctx.recoveryFor('mirror_not_ready'),
+            });
+        }
+        const root = await svc.getLeiEntity(input.lei);
+        if (!root) {
+            throw ctx.fail('lei_not_found', `No GLEIF entity with LEI "${input.lei}".`, {
+                ...ctx.recoveryFor('lei_not_found'),
+            });
+        }
+        const { nodes, edges } = await traverse(svc, input.lei, input.direction, input.depth);
+        // Hydrate node names/jurisdictions in one batch.
+        const hydrated = await svc.getLeiEntitiesBatch([...nodes.keys()]);
+        const byLei = new Map(hydrated.map((e) => [e.lei, e]));
+        for (const node of nodes.values()) {
+            const e = byLei.get(node.lei);
+            if (e) {
+                node.legalName = e.legalName;
+                if (e.jurisdiction)
+                    node.jurisdiction = e.jurisdiction;
+                if (e.status)
+                    node.status = e.status;
+            }
+        }
+        const sanctionsReady = await svc.sanctionsReady();
+        let screenedNodeCount = 0;
+        let flaggedNodeCount = 0;
+        const screensByLei = new Map();
+        if (input.screenNodes && sanctionsReady) {
+            for (const node of nodes.values()) {
+                const screen = await svc.screenName({
+                    query: node.legalName,
+                    entityType: 'any',
+                    matchMode: 'strict',
+                    // Per-node cross-reference: strict only. Auto-fuzzy would flag nearly
+                    // every node on a single shared common token, defeating the signal.
+                    autoFallback: false,
+                    sources: [...SOURCE_CODES],
+                    limit: 10,
+                }, ctx);
+                screenedNodeCount++;
+                if (screen.hits.length > 0)
+                    flaggedNodeCount++;
+                screensByLei.set(node.lei, screen.hits);
+            }
+        }
+        const orderedNodes = [...nodes.values()].sort((a, b) => a.depth - b.depth);
+        return {
+            rootLei: input.lei,
+            nodes: orderedNodes.map((node) => {
+                const hits = screensByLei.get(node.lei);
+                return {
+                    lei: node.lei,
+                    legalName: node.legalName,
+                    ...(node.jurisdiction ? { jurisdiction: node.jurisdiction } : {}),
+                    ...(node.status ? { status: node.status } : {}),
+                    depth: node.depth,
+                    role: node.role,
+                    ...(input.screenNodes && sanctionsReady
+                        ? {
+                            sanctionsHits: (hits ?? []).map((h) => ({
+                                source: h.source,
+                                sourceLabel: SOURCE_LABELS[h.source],
+                                sourceEntryId: h.sourceEntryId,
+                                primaryName: h.primaryName,
+                                matchedName: h.matchedName,
+                                matchType: h.matchType,
+                                ...(h.score !== undefined ? { score: h.score } : {}),
+                            })),
+                        }
+                        : {}),
+                };
+            }),
+            edges,
+            screenedNodeCount,
+            flaggedNodeCount,
+            caveat: SCREENING_CAVEAT,
+        };
+    },
+    format: (r) => {
+        const lines = [`# Ownership graph for \`${r.rootLei}\``, ''];
+        lines.push(`**${r.nodes.length} node(s), ${r.edges.length} edge(s).**`);
+        if (r.screenedNodeCount > 0) {
+            lines.push(`**Screened ${r.screenedNodeCount} node(s); ${r.flaggedNodeCount} had potential matches.**`);
+        }
+        lines.push('\n## Entities');
+        for (const node of r.nodes) {
+            const meta = [node.jurisdiction, node.status].filter(Boolean).join(', ');
+            lines.push(`- **${node.legalName}** \`${node.lei}\` — ${node.role}, depth ${node.depth}${meta ? ` (${meta})` : ''}`);
+            if (node.sanctionsHits && node.sanctionsHits.length > 0) {
+                for (const h of node.sanctionsHits) {
+                    const scoreStr = h.score !== undefined ? ` · score ${h.score.toFixed(3)}` : '';
+                    lines.push(`  - ⚠ ${h.primaryName} — ${h.sourceLabel} (\`${h.source}\`, entry ${h.sourceEntryId}): matched "${h.matchedName}" — ${h.matchType}${scoreStr}`);
+                }
+            }
+            else if (node.sanctionsHits) {
+                lines.push('  - No potential matches (not a clearance).');
+            }
+        }
+        if (r.edges.length > 0) {
+            lines.push('\n## Ownership edges');
+            for (const e of r.edges) {
+                lines.push(`- \`${e.childLei}\` ${e.relationshipType} \`${e.parentLei}\`${e.relationshipStatus ? ` (${e.relationshipStatus})` : ''}`);
+            }
+        }
+        lines.push(`\n> ${r.caveat}`);
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=trace-ownership.tool.js.map

package/dist/mcp-server/tools/definitions/trace-ownership.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-ownership.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/trace-ownership.tool.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,17 @@
+/**
+ * @fileoverview Small synthetic fixture mirror — a handful of designations (one
+ * per source, with aliases and transliteration-class variants) plus a couple of
+ * GLEIF entities and an ownership relationship. Lets `bun run test` exercise the
+ * matching engine, the tools, and ownership tracing WITHOUT downloading the real
+ * multi-source corpus (which loads out-of-band via `mirror:init`). The names
+ * here are invented for testing — they are NOT real sanctions designations.
+ * @module services/screening/fixtures
+ */
+import type { NormalizedDesignation, NormalizedLeiEntity, NormalizedLeiRelationship } from '../../services/screening/types.js';
+/** Invented designations spanning all five sources, with aliases for fuzzy tests. */
+export declare const FIXTURE_DESIGNATIONS: NormalizedDesignation[];
+/** Two invented GLEIF entities — a parent and a subsidiary — for resolution + tracing. */
+export declare const FIXTURE_LEI_ENTITIES: NormalizedLeiEntity[];
+/** Testland Holdings PLC ultimately consolidates Fictional Trading Company LLC. */
+export declare const FIXTURE_LEI_RELATIONSHIPS: NormalizedLeiRelationship[];
+//# sourceMappingURL=fixtures.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fixtures.d.ts","sourceRoot":"","sources":["../../../src/services/screening/fixtures.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACV,qBAAqB,EACrB,mBAAmB,EACnB,yBAAyB,EAC1B,MAAM,+BAA+B,CAAC;AAEvC,qFAAqF;AACrF,eAAO,MAAM,oBAAoB,EAAE,qBAAqB,EAiHvD,CAAC;AAEF,0FAA0F;AAC1F,eAAO,MAAM,oBAAoB,EAAE,mBAAmB,EAyBrD,CAAC;AAEF,mFAAmF;AACnF,eAAO,MAAM,yBAAyB,EAAE,yBAAyB,EAQhE,CAAC"}

package/dist/services/screening/fixtures.js

@@ -0,0 +1,162 @@
+/**
+ * @fileoverview Small synthetic fixture mirror — a handful of designations (one
+ * per source, with aliases and transliteration-class variants) plus a couple of
+ * GLEIF entities and an ownership relationship. Lets `bun run test` exercise the
+ * matching engine, the tools, and ownership tracing WITHOUT downloading the real
+ * multi-source corpus (which loads out-of-band via `mirror:init`). The names
+ * here are invented for testing — they are NOT real sanctions designations.
+ * @module services/screening/fixtures
+ */
+/** Invented designations spanning all five sources, with aliases for fuzzy tests. */
+export const FIXTURE_DESIGNATIONS = [
+    {
+        id: 'ofac_sdn:FX-1001',
+        source: 'ofac_sdn',
+        sourceEntryId: 'FX-1001',
+        entityType: 'person',
+        primaryName: 'Ivan Testovich Volkov',
+        program: 'TEST-PROGRAM',
+        designationDate: '2021-03-15',
+        payload: {
+            // 'Volkov' / 'Wolkow' is a transliteration-class pair for the phonetic test.
+            aliases: [
+                { name: 'Ivan Wolkow', nameType: 'aka' },
+                { name: 'I. T. Volkov', nameType: 'aka' },
+                { name: 'Vanya Volkov', nameType: 'low-quality-aka' },
+            ],
+            identifiers: [{ type: 'Passport', value: 'X1234567', country: 'Testland' }],
+            addresses: [{ full: '1 Test Street, Testograd, Testland', country: 'Testland' }],
+            datesOfBirth: [{ date: '1970-01-01', place: 'Testograd' }],
+            nationalities: ['Testland'],
+            remarks: 'Synthetic test designation — not a real person.',
+        },
+    },
+    {
+        id: 'ofac_consolidated:FX-2002',
+        source: 'ofac_consolidated',
+        sourceEntryId: 'FX-2002',
+        entityType: 'organization',
+        primaryName: 'Fictional Trading Company LLC',
+        program: 'TEST-CONS',
+        designationDate: '2022-06-01',
+        payload: {
+            aliases: [
+                { name: 'Fictional Trading Co', nameType: 'aka' },
+                { name: 'FTC LLC', nameType: 'aka' },
+            ],
+            identifiers: [],
+            addresses: [{ full: '99 Commerce Way, Testopolis', country: 'Testland' }],
+            datesOfBirth: [],
+            nationalities: [],
+        },
+    },
+    {
+        id: 'eu:FX-3003',
+        source: 'eu',
+        sourceEntryId: 'FX-3003',
+        entityType: 'person',
+        primaryName: 'Katarina Beispiel',
+        program: 'EU-TEST-REGIME',
+        designationDate: '2023-02-20',
+        payload: {
+            aliases: [{ name: 'Katarina Example', nameType: 'aka' }],
+            identifiers: [],
+            addresses: [],
+            datesOfBirth: [{ date: '1985-05-05' }],
+            nationalities: ['Beispielland'],
+        },
+    },
+    {
+        id: 'uk:FX-4004',
+        source: 'uk',
+        sourceEntryId: 'FX-4004',
+        entityType: 'vessel',
+        primaryName: 'MV Phantom Voyager',
+        program: 'UK-TEST-SHIPPING',
+        designationDate: '2024-09-10',
+        payload: {
+            aliases: [{ name: 'Phantom Voyager', nameType: 'aka' }],
+            identifiers: [{ type: 'IMO', value: '1234567' }],
+            addresses: [],
+            datesOfBirth: [],
+            nationalities: [],
+        },
+    },
+    {
+        // Transliteration-class case: published as "Mohammed", queryable as
+        // "Muhammad" — the two share a Double-Metaphone key (MHMT), which is how the
+        // phonetic fallback catches a romanization the strict/JW paths would miss.
+        id: 'un:FX-6006',
+        source: 'un',
+        sourceEntryId: 'FX-6006',
+        entityType: 'person',
+        primaryName: 'Mohammed Al-Testi',
+        program: 'UN-TEST-1267',
+        designationDate: '2019-04-12',
+        payload: {
+            aliases: [{ name: 'Mohammed Testi', nameType: 'aka' }],
+            identifiers: [],
+            addresses: [],
+            datesOfBirth: [{ date: '1975-07-07' }],
+            nationalities: ['Testland'],
+        },
+    },
+    {
+        id: 'un:FX-5005',
+        source: 'un',
+        sourceEntryId: 'FX-5005',
+        entityType: 'organization',
+        primaryName: 'Imaginary Front Organisation',
+        program: 'UN-TEST-1267',
+        designationDate: '2020-11-30',
+        payload: {
+            aliases: [
+                { name: 'Imaginary Front Org', nameType: 'aka' },
+                { name: 'IFO', nameType: 'low-quality-aka' },
+            ],
+            identifiers: [],
+            addresses: [{ full: 'PO Box 1, Nowhere City' }],
+            datesOfBirth: [],
+            nationalities: [],
+            remarks: 'Synthetic UN test entry.',
+        },
+    },
+];
+/** Two invented GLEIF entities — a parent and a subsidiary — for resolution + tracing. */
+export const FIXTURE_LEI_ENTITIES = [
+    {
+        lei: '5493001KJTIIGC8Y1R12',
+        legalName: 'Fictional Trading Company LLC',
+        otherNames: ['Fictional Trading Co'],
+        jurisdiction: 'US',
+        status: 'ISSUED',
+        legalAddress: '99 Commerce Way, Testopolis, US',
+        headquartersAddress: '99 Commerce Way, Testopolis, US',
+        registrationAuthorityId: 'RA000665',
+        registrationAuthorityEntityId: 'TEST-REG-1',
+        lastUpdate: '2026-01-15T10:00:00Z',
+    },
+    {
+        lei: '529900T8BM49AURSDO55',
+        legalName: 'Testland Holdings PLC',
+        otherNames: ['Testland Holdings'],
+        jurisdiction: 'GB',
+        status: 'ISSUED',
+        legalAddress: '1 Holding Square, London, GB',
+        headquartersAddress: '1 Holding Square, London, GB',
+        registrationAuthorityId: 'RA000585',
+        registrationAuthorityEntityId: 'TEST-REG-2',
+        lastUpdate: '2026-01-10T10:00:00Z',
+    },
+];
+/** Testland Holdings PLC ultimately consolidates Fictional Trading Company LLC. */
+export const FIXTURE_LEI_RELATIONSHIPS = [
+    {
+        childLei: '5493001KJTIIGC8Y1R12',
+        parentLei: '529900T8BM49AURSDO55',
+        relationshipType: 'IS_ULTIMATELY_CONSOLIDATED_BY',
+        relationshipStatus: 'ACTIVE',
+        relationshipPeriod: '2020-01-01',
+    },
+];
+//# sourceMappingURL=fixtures.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fixtures.js","sourceRoot":"","sources":["../../../src/services/screening/fixtures.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAQH,qFAAqF;AACrF,MAAM,CAAC,MAAM,oBAAoB,GAA4B;IAC3D;QACE,EAAE,EAAE,kBAAkB;QACtB,MAAM,EAAE,UAAU;QAClB,aAAa,EAAE,SAAS;QACxB,UAAU,EAAE,QAAQ;QACpB,WAAW,EAAE,uBAAuB;QACpC,OAAO,EAAE,cAAc;QACvB,eAAe,EAAE,YAAY;QAC7B,OAAO,EAAE;YACP,6EAA6E;YAC7E,OAAO,EAAE;gBACP,EAAE,IAAI,EAAE,aAAa,EAAE,QAAQ,EAAE,KAAK,EAAE;gBACxC,EAAE,IAAI,EAAE,cAAc,EAAE,QAAQ,EAAE,KAAK,EAAE;gBACzC,EAAE,IAAI,EAAE,cAAc,EAAE,QAAQ,EAAE,iBAAiB,EAAE;aACtD;YACD,WAAW,EAAE,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC;YAC3E,SAAS,EAAE,CAAC,EAAE,IAAI,EAAE,oCAAoC,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC;YAChF,YAAY,EAAE,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC;YAC1D,aAAa,EAAE,CAAC,UAAU,CAAC;YAC3B,OAAO,EAAE,iDAAiD;SAC3D;KACF;IACD;QACE,EAAE,EAAE,2BAA2B;QAC/B,MAAM,EAAE,mBAAmB;QAC3B,aAAa,EAAE,SAAS;QACxB,UAAU,EAAE,cAAc;QAC1B,WAAW,EAAE,+BAA+B;QAC5C,OAAO,EAAE,WAAW;QACpB,eAAe,EAAE,YAAY;QAC7B,OAAO,EAAE;YACP,OAAO,EAAE;gBACP,EAAE,IAAI,EAAE,sBAAsB,EAAE,QAAQ,EAAE,KAAK,EAAE;gBACjD,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,KAAK,EAAE;aACrC;YACD,WAAW,EAAE,EAAE;YACf,SAAS,EAAE,CAAC,EAAE,IAAI,EAAE,6BAA6B,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC;YACzE,YAAY,EAAE,EAAE;YAChB,aAAa,EAAE,EAAE;SAClB;KACF;IACD;QACE,EAAE,EAAE,YAAY;QAChB,MAAM,EAAE,IAAI;QACZ,aAAa,EAAE,SAAS;QACxB,UAAU,EAAE,QAAQ;QACpB,WAAW,EAAE,mBAAmB;QAChC,OAAO,EAAE,gBAAgB;QACzB,eAAe,EAAE,YAAY;QAC7B,OAAO,EAAE;YACP,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,kBAAkB,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;YACxD,WAAW,EAAE,EAAE;YACf,SAAS,EAAE,EAAE;YACb,YAAY,EAAE,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC;YACtC,aAAa,EAAE,CAAC,cAAc,CAAC;SAChC;KACF;IACD;QACE,EAAE,EAAE,YAAY;QAChB,MAAM,EAAE,IAAI;QACZ,aAAa,EAAE,SAAS;QACxB,UAAU,EAAE,QAAQ;QACpB,WAAW,EAAE,oBAAoB;QACjC,OAAO,EAAE,kBAAkB;QAC3B,eAAe,EAAE,YAAY;QAC7B,OAAO,EAAE;YACP,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,iBAAiB,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;YACvD,WAAW,EAAE,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;YAChD,SAAS,EAAE,EAAE;YACb,YAAY,EAAE,EAAE;YAChB,aAAa,EAAE,EAAE;SAClB;KACF;IACD;QACE,oEAAoE;QACpE,6EAA6E;QAC7E,2EAA2E;QAC3E,EAAE,EAAE,YAAY;QAChB,MAAM,EAAE,IAAI;QACZ,aAAa,EAAE,SAAS;QACxB,UAAU,EAAE,QAAQ;QACpB,WAAW,EAAE,mBAAmB;QAChC,OAAO,EAAE,cAAc;QACvB,eAAe,EAAE,YAAY;QAC7B,OAAO,EAAE;YACP,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,gBAAgB,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;YACtD,WAAW,EAAE,EAAE;YACf,SAAS,EAAE,EAAE;YACb,YAAY,EAAE,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC;YACtC,aAAa,EAAE,CAAC,UAAU,CAAC;SAC5B;KACF;IACD;QACE,EAAE,EAAE,YAAY;QAChB,MAAM,EAAE,IAAI;QACZ,aAAa,EAAE,SAAS;QACxB,UAAU,EAAE,cAAc;QAC1B,WAAW,EAAE,8BAA8B;QAC3C,OAAO,EAAE,cAAc;QACvB,eAAe,EAAE,YAAY;QAC7B,OAAO,EAAE;YACP,OAAO,EAAE;gBACP,EAAE,IAAI,EAAE,qBAAqB,EAAE,QAAQ,EAAE,KAAK,EAAE;gBAChD,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,iBAAiB,EAAE;aAC7C;YACD,WAAW,EAAE,EAAE;YACf,SAAS,EAAE,CAAC,EAAE,IAAI,EAAE,wBAAwB,EAAE,CAAC;YAC/C,YAAY,EAAE,EAAE;YAChB,aAAa,EAAE,EAAE;YACjB,OAAO,EAAE,0BAA0B;SACpC;KACF;CACF,CAAC;AAEF,0FAA0F;AAC1F,MAAM,CAAC,MAAM,oBAAoB,GAA0B;IACzD;QACE,GAAG,EAAE,sBAAsB;QAC3B,SAAS,EAAE,+BAA+B;QAC1C,UAAU,EAAE,CAAC,sBAAsB,CAAC;QACpC,YAAY,EAAE,IAAI;QAClB,MAAM,EAAE,QAAQ;QAChB,YAAY,EAAE,iCAAiC;QAC/C,mBAAmB,EAAE,iCAAiC;QACtD,uBAAuB,EAAE,UAAU;QACnC,6BAA6B,EAAE,YAAY;QAC3C,UAAU,EAAE,sBAAsB;KACnC;IACD;QACE,GAAG,EAAE,sBAAsB;QAC3B,SAAS,EAAE,uBAAuB;QAClC,UAAU,EAAE,CAAC,mBAAmB,CAAC;QACjC,YAAY,EAAE,IAAI;QAClB,MAAM,EAAE,QAAQ;QAChB,YAAY,EAAE,8BAA8B;QAC5C,mBAAmB,EAAE,8BAA8B;QACnD,uBAAuB,EAAE,UAAU;QACnC,6BAA6B,EAAE,YAAY;QAC3C,UAAU,EAAE,sBAAsB;KACnC;CACF,CAAC;AAEF,mFAAmF;AACnF,MAAM,CAAC,MAAM,yBAAyB,GAAgC;IACpE;QACE,QAAQ,EAAE,sBAAsB;QAChC,SAAS,EAAE,sBAAsB;QACjC,gBAAgB,EAAE,+BAA+B;QACjD,kBAAkB,EAAE,QAAQ;QAC5B,kBAAkB,EAAE,YAAY;KACjC;CACF,CAAC"}

package/dist/services/screening/gleif-ingest.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @fileoverview GLEIF ingester — the heaviest leg. Resolves the latest
+ * golden-copy (full) or delta download URLs from the GLEIF Golden Copy API,
+ * streams the ZIP-compressed file, and normalizes LEI-CDF Level 1 (who-is-who)
+ * and RR-CDF Level 2 (who-owns-whom) records onto {@link NormalizedLeiEntity} /
+ * {@link NormalizedLeiRelationship}. Level 1 init is ~3.3M records / ~490 MB
+ * compressed (May 2026) — it runs out-of-band via `mirror:init`, never on the
+ * request path; refresh uses the 8-hour deltas keyed on a checkpoint.
+ *
+ * The normalization functions are the testable core (exercised by the synthetic
+ * fixture). The download/decompress wiring is documented and resilient; the real
+ * corpus loads out-of-band.
+ * @module services/screening/gleif-ingest
+ */
+import type { NormalizedLeiEntity, NormalizedLeiRelationship } from '../../services/screening/types.js';
+/** Which GLEIF dataset + window to fetch. */
+export type GleifFileKind = 'lei2-full' | 'lei2-delta' | 'rr-full' | 'rr-delta';
+/**
+ * Resolve the download URL for a GLEIF golden-copy or delta file. The Golden
+ * Copy API exposes a JSON index of the latest publications per file type and
+ * delta window; we read it and return the matching `.xml.gz` download link.
+ *
+ * @param kind Which dataset + window.
+ * @param delta Delta window when `kind` is a delta variant (e.g. `'LastDay'`, `'IntraDay'`).
+ */
+export declare function resolveGleifFileUrl(kind: GleifFileKind, signal: AbortSignal, delta?: 'IntraDay' | 'LastDay' | 'WeeklyFullFiles'): Promise<string>;
+/**
+ * Download a GLEIF golden-copy / delta file and return the decompressed XML.
+ * The golden-copy downloads are **ZIP** containers (`PK\x03\x04`) wrapping a
+ * single XML entry — not gzip; the delta `.gz` files are gzip. Detection is by
+ * magic bytes (the URL suffix is unreliable behind the storage redirect), with a
+ * plain-XML fallback.
+ *
+ * NOTE (memory): this buffers and decompresses the whole file in memory. The
+ * Level 1 golden copy is ~3.3M records / ~900 MB compressed; decompressing and
+ * DOM-parsing it whole needs multiple GB of heap. A production `mirror:init`
+ * against the full L1 file requires a streaming ZIP → SAX pipeline; until then,
+ * real L1 ingest is bounded by available memory. Deltas and L2 are far smaller
+ * and fit comfortably.
+ */
+export declare function downloadGleifXml(url: string, signal: AbortSignal): Promise<string>;
+/** Decompress a downloaded GLEIF buffer by detecting ZIP / gzip / plain by magic bytes. */
+export declare function decompressGleifBuffer(buf: Buffer): string;
+/**
+ * Extract the first file entry from a ZIP buffer (stored or deflate). GLEIF
+ * golden-copy ZIPs wrap exactly one XML file, so a single-entry reader is
+ * sufficient — it reads the local file header, then inflates the entry's raw
+ * deflate stream (or returns it verbatim when stored).
+ */
+export declare function extractFirstZipEntry(buf: Buffer): string;
+/**
+ * Parse an LEI-CDF Level 1 XML document into normalized entity records. The
+ * record root is `<LEIRecords><LEIRecord>`; each carries an `<LEI>`, an
+ * `<Entity>` (legal name, other names, addresses, jurisdiction, status), and a
+ * `<Registration>` (registration status, last-update, RA).
+ */
+export declare function parseLeiLevel1(doc: Record<string, unknown>): NormalizedLeiEntity[];
+/**
+ * Parse an RR-CDF Level 2 XML document into normalized relationship records.
+ * The record root is `<RelationshipRecords><RelationshipRecord>`; each carries a
+ * `<Relationship>` with a start node (child), end node (parent), and type.
+ */
+export declare function parseLeiLevel2(doc: Record<string, unknown>): NormalizedLeiRelationship[];
+/** Fetch + decompress + parse Level 1 from a resolved URL. */
+export declare function harvestLeiLevel1(url: string, signal: AbortSignal): Promise<NormalizedLeiEntity[]>;
+/** Fetch + decompress + parse Level 2 from a resolved URL. */
+export declare function harvestLeiLevel2(url: string, signal: AbortSignal): Promise<NormalizedLeiRelationship[]>;
+//# sourceMappingURL=gleif-ingest.d.ts.map

package/dist/services/screening/gleif-ingest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gleif-ingest.d.ts","sourceRoot":"","sources":["../../../src/services/screening/gleif-ingest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH,OAAO,KAAK,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,MAAM,+BAA+B,CAAC;AAKpG,6CAA6C;AAC7C,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,YAAY,GAAG,SAAS,GAAG,UAAU,CAAC;AA2BhF;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,aAAa,EACnB,MAAM,EAAE,WAAW,EACnB,KAAK,GAAE,UAAU,GAAG,SAAS,GAAG,iBAA6B,GAC5D,OAAO,CAAC,MAAM,CAAC,CAmCjB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAclF;AAED,2FAA2F;AAC3F,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAIzD;AAUD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAsBxD;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,mBAAmB,EAAE,CASlF;AAuDD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,yBAAyB,EAAE,CAgBxF;AA6BD,8DAA8D;AAC9D,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAIhC;AAED,8DAA8D;AAC9D,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,yBAAyB,EAAE,CAAC,CAItC"}