@slicedearth/whoisleuth-cli 1.36.1 → 1.39.1

package/cli/completion.mjs

@@ -2,7 +2,7 @@ import { CLI_COMMANDS } from "./arguments.mjs";
 import { INVESTIGATION_PLAN_RECIPES } from "./investigation-plan.mjs";
 const COMMON_OPTIONS = Object.freeze(['--help', '--output', '--force']);
 const OPTIONS_BY_COMMAND = Object.freeze({
-    lookup: ['--json', '--markdown', '--html', '--fast', '--deep', '--plan', '--summary', '--verbose', '--strict-exit', '--events', '--quiet', '--no-color'],
+    lookup: ['--json', '--markdown', '--html', '--fast', '--deep', '--observer', '--vantage', '--plan', '--summary', '--verbose', '--strict-exit', '--events', '--quiet', '--no-color'],
     bulk: ['--json', '--jsonl', '--csv', '--domains', '--queries', '--registered-only', '--inconclusive-only', '--errors-only', '--fast', '--deep', '--concurrency', '--checkpoint', '--resume', '--events', '--quiet', '--no-color'],
     'ct-search': ['--json', '--quiet', '--no-color'],
     discover: ['--tlds', '--preset', '--families', '--keyboard', '--dictionary', '--snapshot', '--json', '--jsonl', '--domains', '--quiet', '--no-color'],
@@ -11,7 +11,9 @@ const OPTIONS_BY_COMMAND = Object.freeze({
     http: ['--json', '--quiet', '--no-color'],
     tls: ['--json', '--quiet', '--no-color'],
     'registry-support': ['--json', '--quiet', '--no-color'],
+    'registry-doctor': ['--json', '--quiet', '--no-color'],
     'risk-calibrate': ['--json', '--quiet', '--no-color'],
+    'lookalike-calibrate': ['--json', '--quiet', '--no-color'],
     'verify-artifact': ['--passphrase-file', '--json', '--quiet', '--no-color'],
     'inspect-archive': ['--passphrase-file', '--search', '--require-match', '--reveal', '--json', '--quiet', '--no-color'],
     'sign-artifact': ['--private-key-file'],
@@ -20,10 +22,13 @@ const OPTIONS_BY_COMMAND = Object.freeze({
     compare: ['--json', '--quiet', '--no-color'],
     'page-compare': ['--json', '--quiet', '--no-color'],
     'mail-review': ['--json', '--quiet', '--no-color'],
-    'review-evidence': ['--json', '--quiet', '--no-color'],
+    'review-evidence': ['--mmdb', '--json', '--quiet', '--no-color'],
     'domain-control': ['--json', '--quiet', '--no-color'],
+    assurance: ['--json', '--quiet', '--no-color'],
+    'sharing-review': ['--marking', '--recipient-scope', '--purpose', '--human-reviewed', '--personal-data-reviewed', '--redactions-confirmed', '--json', '--quiet', '--no-color'],
     'workflow-plan': ['--json', '--quiet', '--no-color'],
     diff: ['--json', '--quiet', '--no-color'],
+    reconcile: ['--json', '--quiet', '--no-color'],
     timeline: ['--json', '--quiet', '--no-color'],
     export: ['--markdown', '--html', '--compact'],
     completion: [],
@@ -41,10 +46,12 @@ const COMMAND_DESCRIPTIONS = Object.freeze({
     http: 'Inspect one homepage request',
     tls: 'Inspect one TLS connection',
     'registry-support': 'Explain local registry coverage',
+    'registry-doctor': 'Diagnose saved registry collection',
     'risk-calibrate': 'Replay reviewed Risk labels offline',
+    'lookalike-calibrate': 'Summarise reviewed lookalike yield offline',
     'verify-artifact': 'Validate saved evidence offline',
     'inspect-archive': 'Inspect an archive locally',
-    'sign-artifact': 'Sign a reviewed artifact locally',
+    'sign-artifact': 'Sign a reviewed artefact locally',
     'verify-signature': 'Verify a signed evidence package',
     'source-report': 'Build a target-free source report',
     compare: 'Compare registry publications in one lookup',
@@ -52,8 +59,11 @@ const COMMAND_DESCRIPTIONS = Object.freeze({
     'mail-review': 'Review saved passive mail evidence',
     'review-evidence': 'Review supplied evidence offline',
     'domain-control': 'Build or review a domain control manifest',
+    assurance: 'Review domain change, recovery, or retirement plans',
+    'sharing-review': 'Lint an artefact before deliberate sharing',
     'workflow-plan': 'Plan a fixed investigation recipe',
     diff: 'Compare two saved domain lookups',
+    reconcile: 'Reconcile independently labelled observations',
     timeline: 'Build same-domain history from saved lookups',
     export: 'Convert a lookup to an evidence report',
     completion: 'Print shell completion',
@@ -65,6 +75,8 @@ const VALUE_OPTIONS = Object.freeze({
     '--preset': ['common', 'impersonation', 'all'],
     '--keyboard': ['qwerty', 'azerty', 'qwertz', 'all'],
     '--mail-profile': ['standard', 'defensive-no-mail', 'parked'],
+    '--marking': ['clear', 'green', 'amber', 'amber-strict', 'red'],
+    '--recipient-scope': ['public', 'community', 'organization', 'named-recipients'],
     '--concurrency': ['1', '2', '3', '4', '5', '6', '7', '8'],
 });
 const FILE_OPTIONS = Object.freeze([
@@ -81,10 +93,13 @@ const FILE_OPTIONS = Object.freeze([
 const TEXT_OPTIONS = Object.freeze([
     '--families',
     '--resolver',
+    '--purpose',
+    '--observer',
     '--retired-selectors',
     '--search',
     '--selectors',
     '--tlds',
+    '--vantage',
 ]);
 function commandOptions(command) {
     return [...COMMON_OPTIONS, ...(OPTIONS_BY_COMMAND[command] || [])].join(' ');

package/cli/doctor.mjs

@@ -1,6 +1,4 @@
-import { resolvePublicAddresses, safeFetch } from "../lib/safe-fetch.mjs";
 import { withTimeout } from "../lib/abort.mjs";
-import { whoisQuery } from "../lib/whois-transport.mjs";
 const DOCTOR_SCHEMA = 'whoisleuth.cli.doctor';
 const DOCTOR_VERSION = 1;
 const MINIMUM_NODE_MAJOR = 24;
@@ -62,9 +60,17 @@ async function buildDoctorReport(options) {
         }));
     }
     else {
-        const resolve = options.resolveAddresses || resolvePublicAddresses;
-        const fetchHttps = options.fetchHttps || safeFetch;
-        const query = options.queryWhois || whoisQuery;
+        const safeFetchModule = options.resolveAddresses && options.fetchHttps
+            ? null
+            : await import("../lib/safe-fetch.mjs");
+        const whoisModule = options.queryWhois
+            ? null
+            : await import("../lib/whois-transport.mjs");
+        const resolve = options.resolveAddresses || safeFetchModule?.resolvePublicAddresses;
+        const fetchHttps = options.fetchHttps || safeFetchModule?.safeFetch;
+        const query = options.queryWhois || whoisModule?.whoisQuery;
+        if (!resolve || !fetchHttps || !query)
+            throw new TypeError('Network diagnostic dependencies are unavailable.');
         const networkTimeoutMs = Number.isSafeInteger(options.networkTimeoutMs)
             && Number(options.networkTimeoutMs) >= 1
             && Number(options.networkTimeoutMs) <= NETWORK_TIMEOUT_MS

package/cli/evidence-command-arguments.mjs

@@ -92,7 +92,7 @@ export function parseSignArtifactArguments(argv) {
         else if (source === null)
             source = argument;
         else
-            throw new CliUsageError('sign-artifact accepts one optional JSON file. Otherwise pipe one artifact on stdin.');
+            throw new CliUsageError('sign-artifact accepts one optional JSON file. Otherwise pipe one artefact on stdin.');
     }
     if (!privateKeySource)
         throw new CliUsageError('sign-artifact requires --private-key-file.');

package/cli/evidence-command-runner.mjs

@@ -80,9 +80,9 @@ export async function runEvidenceCommand(args, dependencies) {
         return EXIT_CODES.SUCCESS;
     }
     if (args.action === 'sign-artifact') {
-        const input = await readArtifact(args.source, 'Evidence artifact input', dependencies);
+        const input = await readArtifact(args.source, 'Evidence artefact input', dependencies);
         if (!input.trim()) {
-            throw new CliUsageError('sign-artifact requires one reviewed artifact file or an artifact on stdin.');
+            throw new CliUsageError('sign-artifact requires one reviewed artefact file or an artefact on stdin.');
         }
         const privateKey = await readKey(args.privateKeySource, 'Private key file', dependencies.readPrivateKeyFile);
         const signed = await signEvidencePackage(input, privateKey, dependencies.now ? dependencies.now() : new Date().toISOString());

package/cli/evidence-signing.mjs

@@ -100,10 +100,10 @@ function payloadBytes(payload) {
     return Buffer.from(canonicalArtifactJson(payload), 'utf8');
 }
 async function signableArtifact(raw) {
-    const artifact = parseObject(raw, 'Evidence artifact');
+    const artifact = parseObject(raw, 'Evidence artefact');
     const verification = await verifyOfflineArtifact(raw);
-    if (!['case_response_packet', 'signed_review_artifact'].includes(verification.artifact.kind)) {
-        throw new TypeError('Only reviewed response packets and supported review manifests can be signed.');
+    if (!['case_response_packet', 'investigation_capsule', 'signed_review_artifact'].includes(verification.artifact.kind)) {
+        throw new TypeError('Only reviewed response packets, investigation capsules, and supported review manifests can be signed.');
     }
     return { artifact, verification };
 }
@@ -193,7 +193,7 @@ export async function verifyEvidencePackageSignature(raw, trustedPublicKeyPem) {
             trustedPublicKeyPem
                 ? 'The signature and supplied public key match; recipient trust still depends on obtaining that public key through an authenticated channel.'
                 : 'The signature is internally valid for the embedded public key, but signer identity was not authenticated because no trusted public key was supplied.',
-            'The signature authenticates the canonical sorted-JSON content, not the original whitespace, indentation, or object-key order of the serialized file.',
+            'The signature authenticates the canonical sorted-JSON content, not the original whitespace, indentation, or object-key order of the serialised file.',
             'A valid signature proves the canonical package content has not changed since signing; it does not establish that the retained observations or analyst statements are accurate.',
             'WHOISleuth does not generate, store, recover, rotate, or publish signing keys.',
         ]),

package/cli/formatters/html.mjs

@@ -12,7 +12,7 @@ function renderGroups(groups) {
 }
 function renderComparison(comparison) {
     if (!comparison.fields.length)
-        return '<p class="empty">No comparable normalized fields were published.</p>';
+        return '<p class="empty">No comparable normalised fields were published.</p>';
     const rows = comparison.fields.map((field) => `<tr><th scope="row">${escapeHtml(field.label)}</th><td><span class="status">${escapeHtml(field.status)}</span></td><td>${escapeHtml(field.rdap)}</td><td>${escapeHtml(field.whois)}</td></tr>`).join('');
     const omitted = comparison.omitted
         ? `<p class="omission">${escapeHtml(comparison.omitted)} additional comparison fields omitted.</p>`

package/cli/formatters/json.mjs

@@ -17,7 +17,13 @@ const CLI_POSTURE_SCHEMA_VERSION = 1;
 const CLI_HTTP_SCHEMA_VERSION = 1;
 const CLI_TLS_SCHEMA_VERSION = 1;
 const CLI_COMPARE_SCHEMA_VERSION = 3;
-function buildCliLookupDocument(query, classified, result, generatedAt = new Date().toISOString(), mode = 'fast') {
+function buildCliLookupDocument(query, classified, result, generatedAt = new Date().toISOString(), mode = 'fast', collectionContext = {}) {
+    const observerLabel = typeof collectionContext.observerLabel === 'string'
+        ? collectionContext.observerLabel
+        : null;
+    const vantageLabel = typeof collectionContext.vantageLabel === 'string'
+        ? collectionContext.vantageLabel
+        : null;
     return {
         schema: CLI_LOOKUP_SCHEMA,
         version: CLI_LOOKUP_SCHEMA_VERSION,
@@ -28,6 +34,12 @@ function buildCliLookupDocument(query, classified, result, generatedAt = new Dat
         inputHostname: classified.inputHostname,
         registrableDomain: classified.registrableDomain,
         isSubdomain: classified.isSubdomain,
+        ...((observerLabel || vantageLabel) ? {
+            collectionContext: {
+                ...(observerLabel ? { observerLabel } : {}),
+                ...(vantageLabel ? { vantageLabel } : {}),
+            },
+        } : {}),
         ...result,
     };
 }

package/cli/formatters/terminal.mjs

@@ -593,7 +593,7 @@ function formatTerminalCompare(document) {
     }
     lines.push('');
     if (!fields.length) {
-        lines.push('Neither source published a comparable normalized field.');
+        lines.push('Neither source published a comparable normalised field.');
     }
     else {
         for (const value of fields) {
@@ -613,7 +613,7 @@ function formatTerminalCompare(document) {
         const publicationDifferences = publicationFields.length - (Number(publicationCounts.equivalent) || 0);
         lines.push('', 'Registry / registrar RDAP publication', `Registry RDAP  ${comparisonStatusLabel(registryHealth.status)}`, `Registrar RDAP ${comparisonStatusLabel(registrarHealth.status)}`, `Compared       ${safeTerminalValue(publicationFields.length, '0')} field${publicationFields.length === 1 ? '' : 's'}`, `Equivalent     ${safeTerminalValue(publicationCounts.equivalent, '0')}`, `Differences    ${safeTerminalValue(publicationDifferences, '0')}`, '');
         if (!publicationFields.length) {
-            lines.push('Neither RDAP publication exposed a comparable normalized field.');
+            lines.push('Neither RDAP publication exposed a comparable normalised field.');
         }
         else {
             for (const value of publicationFields) {
@@ -635,6 +635,7 @@ function formatTerminalRiskCalibration(document) {
     const bands = terminalRecord(summary.scoreBands);
     const thresholds = Array.isArray(document.thresholds) ? document.thresholds : [];
     const records = Array.isArray(document.records) ? document.records : [];
+    const comparison = terminalRecord(document.modelComparison);
     const visible = records.slice(0, MAX_RISK_CALIBRATION_TERMINAL_RECORDS);
     const lines = [
         `Risk model     v${safeTerminalValue(document.riskModelVersion)}`,
@@ -648,7 +649,10 @@ function formatTerminalRiskCalibration(document) {
     ];
     for (const value of thresholds) {
         const threshold = terminalRecord(value);
-        lines.push(`${String(safeTerminalValue(threshold.threshold)).padStart(3)}+  TP ${safeTerminalValue(threshold.truePositive, '0')}  FP ${safeTerminalValue(threshold.falsePositive, '0')}  TN ${safeTerminalValue(threshold.trueNegative, '0')}  FN ${safeTerminalValue(threshold.falseNegative, '0')}  precision ${safeTerminalValue(threshold.precision)}  recall ${safeTerminalValue(threshold.recall)}`);
+        lines.push(`${String(safeTerminalValue(threshold.threshold)).padStart(3)}+  TP ${safeTerminalValue(threshold.truePositive, '0')}  FP ${safeTerminalValue(threshold.falsePositive, '0')}  TN ${safeTerminalValue(threshold.trueNegative, '0')}  FN ${safeTerminalValue(threshold.falseNegative, '0')}  precision ${safeTerminalValue(threshold.precision)}  recall ${safeTerminalValue(threshold.recall)}  F1 ${safeTerminalValue(threshold.f1)}`);
+    }
+    if (comparison.available === true) {
+        lines.push('', `Model comparison  v${safeTerminalValue(comparison.previousModelVersion)} → v${safeTerminalValue(comparison.currentModelVersion)} · ${safeTerminalValue(comparison.scoresChanged, '0')} score changes · ${safeTerminalValue(comparison.thresholdClassificationsChanged, '0')} review-band changes`);
     }
     lines.push('', 'Records');
     for (const value of visible) {

package/cli/investigation-plan.mjs

@@ -15,7 +15,7 @@ const RECIPES = Object.freeze({
         steps: (domain) => Object.freeze([
             step('collect', 'Collect a Deep lookup', 'lookup', [domain, '--deep', '--json'], 'network', 'network_disclosure', 'whoisleuth.cli.lookup', 'Review source health and limitations before using missing fields.'),
             step('export', 'Create a portable evidence report', 'export', ['<saved-lookup.json>'], 'offline', 'analyst_selection', 'whoisleuth.lookup-evidence', 'Select the reviewed lookup file; the plan never guesses a path.'),
-            step('verify', 'Verify the exported artifact', 'verify-artifact', ['<evidence.json>', '--json'], 'offline', 'analyst_selection', 'whoisleuth.offline-artifact-verification', 'Keep verification distinct from a claim that the observations are correct or current.'),
+            step('verify', 'Verify the exported artefact', 'verify-artifact', ['<evidence.json>', '--json'], 'offline', 'analyst_selection', 'whoisleuth.offline-artifact-verification', 'Keep verification distinct from a claim that the observations are correct or current.'),
         ]),
     }),
     'lookalike-review': Object.freeze({
@@ -89,7 +89,7 @@ export function buildInvestigationPlan(recipeId, subjectValue, generatedAtValue
         limitations: Object.freeze([
             'This document is a fixed plan. It does not execute commands, expand placeholders, make requests, read files, change cases, or submit reports.',
             'Network steps require deliberate execution and disclose the selected target to the sources described by that command.',
-            'Analyst-selection steps require reviewed local artifacts; placeholders are never interpreted as file paths by this planner.',
+            'Analyst-selection steps require reviewed local artefacts; placeholders are never interpreted as file paths by this planner.',
         ]),
     });
 }

package/cli/local-mmdb-review.mjs

@@ -0,0 +1,76 @@
+import { stat } from 'node:fs/promises';
+import { isIP } from 'node:net';
+import { open } from 'maxmind';
+import { formatIpPrefix, parseIpPrefix } from "../lib/ip-prefix.mjs";
+import { CliUsageError } from "./errors.mjs";
+export const LOCAL_MMDB_QUERY_SCHEMA = 'whoisleuth.local-mmdb-query';
+export const MAX_LOCAL_MMDB_BYTES = 512 * 1024 * 1024;
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+function boundedText(value, maximum) {
+    return typeof value === 'string' && value.length <= maximum && !/[\u0000-\u001f\u007f]/u.test(value)
+        ? value.replace(/\s+/gu, ' ').trim() || null
+        : null;
+}
+function names(value) {
+    const source = record(value);
+    return boundedText(source.en, 120);
+}
+export async function reviewLocalMmdb(input, databasePath) {
+    const address = boundedText(input.address, 64)?.toLowerCase() ?? '';
+    const sourceLabel = boundedText(input.sourceLabel, 120);
+    const databaseVersion = boundedText(input.databaseVersion, 80);
+    const license = boundedText(input.license, 240);
+    if (!isIP(address))
+        throw new CliUsageError('Local MMDB review requires one valid IP address.');
+    if (!sourceLabel || !databaseVersion || !license) {
+        throw new CliUsageError('Local MMDB review requires bounded sourceLabel, databaseVersion, and licence metadata.');
+    }
+    let info;
+    try {
+        info = await stat(databasePath);
+    }
+    catch {
+        throw new CliUsageError('The supplied MMDB file could not be read.');
+    }
+    if (!info.isFile() || info.size <= 0 || info.size > MAX_LOCAL_MMDB_BYTES) {
+        throw new CliUsageError(`The supplied MMDB must be a file no larger than ${MAX_LOCAL_MMDB_BYTES} bytes.`);
+    }
+    let reader;
+    try {
+        reader = await open(databasePath, { cache: { max: 1_000 } });
+    }
+    catch {
+        throw new CliUsageError('The supplied file is not a readable MaxMind DB database.');
+    }
+    const [rawMatch, prefixLength] = reader.getWithPrefixLength(address);
+    const match = record(rawMatch);
+    const traits = record(match.traits);
+    const country = record(match.country);
+    const registeredCountry = record(match.registered_country);
+    const subdivisions = Array.isArray(match.subdivisions) ? match.subdivisions : [];
+    const subdivision = record(subdivisions[0]);
+    const city = record(match.city);
+    const asnValue = match.autonomous_system_number ?? traits.autonomous_system_number;
+    const asn = typeof asnValue === 'number' && Number.isSafeInteger(asnValue) && asnValue >= 0 ? asnValue : null;
+    const prefix = parseIpPrefix(`${address}/${prefixLength}`);
+    return Object.freeze({
+        state: rawMatch ? 'matched' : 'not_found',
+        address,
+        match: rawMatch ? Object.freeze({
+            network: prefix ? formatIpPrefix(prefix) : null,
+            countryCode: boundedText(country.iso_code ?? registeredCountry.iso_code, 2)?.toUpperCase() ?? null,
+            region: names(subdivision.names) ?? boundedText(subdivision.iso_code, 120),
+            city: names(city.names),
+            asn,
+            asName: boundedText(match.autonomous_system_organization ?? traits.autonomous_system_organization, 240),
+        }) : null,
+        source: Object.freeze({ label: sourceLabel, version: databaseVersion, license }),
+        limitations: Object.freeze([
+            'This CLI-only result comes from an analyst-supplied local MMDB file. WHOISleuth does not bundle, download, update, license, or transmit the database.',
+            'Geolocation and network attribution are provider estimates and may be stale, coarse, shared, or incorrect.',
+            'A location or ASN association does not establish the operator, owner, user, intent, safety, or maliciousness of an address.',
+        ]),
+    });
+}

package/cli/lookalike-calibration.mjs

@@ -0,0 +1,121 @@
+import { Buffer } from 'node:buffer';
+const LOOKALIKE_CALIBRATION_INPUT_SCHEMA = 'whoisleuth.lookalike-calibration-input';
+const LOOKALIKE_CALIBRATION_SCHEMA = 'whoisleuth.lookalike-calibration';
+const LOOKALIKE_CALIBRATION_VERSION = 1;
+const MAX_LOOKALIKE_CALIBRATION_BYTES = 2 * 1024 * 1024;
+const MAX_LOOKALIKE_CALIBRATION_RECORDS = 5_000;
+const MIN_LOOKALIKE_CALIBRATION_SAMPLE = 20;
+const DISPOSITIONS = ['suspicious', 'confirmed_abuse', 'false_positive', 'expected', 'closed_no_action'];
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+function token(value, field) {
+    if (typeof value !== 'string')
+        throw new TypeError(`${field} must be text.`);
+    const normalized = value.trim().toLowerCase();
+    if (!/^[a-z0-9][a-z0-9_-]{0,79}$/u.test(normalized))
+        throw new TypeError(`${field} must be a bounded identifier.`);
+    return normalized;
+}
+function ratio(value, total) {
+    return total ? Number((value / total).toFixed(4)) : 0;
+}
+function emptyCounts() {
+    return { suspicious: 0, confirmed_abuse: 0, false_positive: 0, expected: 0, closed_no_action: 0 };
+}
+function buildLookalikeCalibration(raw, generatedAt = new Date().toISOString()) {
+    if (Buffer.byteLength(raw, 'utf8') > MAX_LOOKALIKE_CALIBRATION_BYTES) {
+        throw new TypeError(`Lookalike calibration input is limited to ${MAX_LOOKALIKE_CALIBRATION_BYTES} bytes.`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new TypeError('Lookalike calibration input must be valid JSON.');
+    }
+    const input = record(parsed);
+    if (input.schema !== LOOKALIKE_CALIBRATION_INPUT_SCHEMA || input.version !== LOOKALIKE_CALIBRATION_VERSION) {
+        throw new TypeError(`Lookalike calibration input must use ${LOOKALIKE_CALIBRATION_INPUT_SCHEMA} version ${LOOKALIKE_CALIBRATION_VERSION}.`);
+    }
+    if (!Array.isArray(input.records) || input.records.length < 1 || input.records.length > MAX_LOOKALIKE_CALIBRATION_RECORDS) {
+        throw new TypeError(`Lookalike calibration input must contain from 1 to ${MAX_LOOKALIKE_CALIBRATION_RECORDS} reviewed records.`);
+    }
+    const ids = new Set();
+    const familyCounts = new Map();
+    const totalCounts = emptyCounts();
+    for (let index = 0; index < input.records.length; index++) {
+        const item = record(input.records[index]);
+        const id = token(item.id, `records[${index}].id`);
+        if (ids.has(id))
+            throw new TypeError(`Lookalike calibration record id "${id}" is duplicated.`);
+        ids.add(id);
+        if (typeof item.disposition !== 'string' || !DISPOSITIONS.includes(item.disposition)) {
+            throw new TypeError(`records[${index}].disposition is not a supported reviewed disposition.`);
+        }
+        const disposition = item.disposition;
+        if (!Array.isArray(item.mutationFamilies) || item.mutationFamilies.length < 1 || item.mutationFamilies.length > 12) {
+            throw new TypeError(`records[${index}].mutationFamilies must contain from 1 to 12 identifiers.`);
+        }
+        const families = [...new Set(item.mutationFamilies.map((value) => token(value, `records[${index}].mutationFamilies`)))];
+        totalCounts[disposition] += 1;
+        for (const family of families) {
+            const counts = familyCounts.get(family) || emptyCounts();
+            counts[disposition] += 1;
+            familyCounts.set(family, counts);
+        }
+    }
+    const families = [...familyCounts.entries()].map(([id, dispositions]) => {
+        const reviewedCandidates = Object.values(dispositions).reduce((sum, count) => sum + count, 0);
+        return {
+            id,
+            reviewedCandidates,
+            sampleState: reviewedCandidates >= MIN_LOOKALIKE_CALIBRATION_SAMPLE ? 'reviewed' : 'insufficient',
+            dispositions,
+            reviewLeadRate: ratio(dispositions.suspicious + dispositions.confirmed_abuse, reviewedCandidates),
+            falsePositiveRate: ratio(dispositions.false_positive, reviewedCandidates),
+        };
+    }).sort((left, right) => right.reviewedCandidates - left.reviewedCandidates || left.id.localeCompare(right.id));
+    const reviewedCandidates = input.records.length;
+    return {
+        schema: LOOKALIKE_CALIBRATION_SCHEMA,
+        version: LOOKALIKE_CALIBRATION_VERSION,
+        generatedAt,
+        summary: {
+            reviewedCandidates,
+            mutationFamilies: families.length,
+            sampleState: reviewedCandidates >= MIN_LOOKALIKE_CALIBRATION_SAMPLE ? 'reviewed' : 'insufficient',
+            reviewLeadRate: ratio(totalCounts.suspicious + totalCounts.confirmed_abuse, reviewedCandidates),
+            falsePositiveRate: ratio(totalCounts.false_positive, reviewedCandidates),
+            expectedRate: ratio(totalCounts.expected, reviewedCandidates),
+        },
+        families,
+        privacy: { candidateIdsRetained: 0, domainsRetained: 0, notesRetained: 0 },
+        limitations: [
+            'This offline report summarises analyst dispositions for the supplied reviewed sample and never changes mutation generation, ordering, Risk, or filtering automatically.',
+            'Suspicious and confirmed-abuse dispositions are counted as review leads, not proof of maliciousness; expected and false-positive dispositions are not proof of safety.',
+            `A family remains an insufficient sample below ${MIN_LOOKALIKE_CALIBRATION_SAMPLE} reviewed candidates, and even larger local samples may not generalize across brands, languages, registries, or time.`,
+            'Candidate identifiers, domains, notes, and evidence are intentionally omitted from output. Retain the reviewed source dataset under an appropriate local privacy policy.',
+        ],
+    };
+}
+function formatLookalikeCalibration(report) {
+    const output = [
+        'Lookalike review-yield calibration',
+        `Reviewed candidates ${report.summary.reviewedCandidates}`,
+        `Mutation families   ${report.summary.mutationFamilies}`,
+        `Sample state        ${report.summary.sampleState}`,
+        `Review-lead rate    ${(report.summary.reviewLeadRate * 100).toFixed(1)}%`,
+        `False-positive rate ${(report.summary.falsePositiveRate * 100).toFixed(1)}%`,
+        '',
+    ];
+    for (const family of report.families) {
+        output.push(`${family.id} [${family.sampleState}]`);
+        output.push(`  ${family.reviewedCandidates} reviewed · ${(family.reviewLeadRate * 100).toFixed(1)}% review leads · ${(family.falsePositiveRate * 100).toFixed(1)}% false positives`);
+    }
+    output.push('', 'Limitations:');
+    for (const limitation of report.limitations)
+        output.push(`  - ${limitation}`);
+    return `${output.join('\n')}\n`;
+}
+export { LOOKALIKE_CALIBRATION_INPUT_SCHEMA, LOOKALIKE_CALIBRATION_SCHEMA, LOOKALIKE_CALIBRATION_VERSION, MAX_LOOKALIKE_CALIBRATION_BYTES, MAX_LOOKALIKE_CALIBRATION_RECORDS, MIN_LOOKALIKE_CALIBRATION_SAMPLE, buildLookalikeCalibration, formatLookalikeCalibration, };

package/cli/lookup-command-runner.mjs

@@ -68,7 +68,10 @@ async function runLookupCommand(args, dependencies, context) {
         context.endProgress();
     }
     const now = context.now();
-    const document = buildCliLookupDocument(query, classified, result, now, args.deep ? 'deep' : 'fast');
+    const document = buildCliLookupDocument(query, classified, result, now, args.deep ? 'deep' : 'fast', {
+        ...(args.observerLabel ? { observerLabel: args.observerLabel } : {}),
+        ...(args.vantageLabel ? { vantageLabel: args.vantageLabel } : {}),
+    });
     if (!args.quiet) {
         if (args.output === 'json')
             context.writeStdout(formatJsonDocument(document));

package/cli/lookup-plan.mjs

@@ -3,13 +3,13 @@ export const CLI_LOOKUP_PLAN_VERSION = 1;
 const RDAP = Object.freeze({
     source: 'rdap',
     purpose: 'Collect authoritative registration or allocation evidence where supported.',
-    disclosure: 'The normalized target is sent to the applicable RDAP bootstrap and service endpoints.',
+    disclosure: 'The normalised target is sent to the applicable RDAP bootstrap and service endpoints.',
     conditional: false,
 });
 const WHOIS = Object.freeze({
     source: 'whois',
     purpose: 'Collect separately attributed registry and referral publications.',
-    disclosure: 'The normalized target is sent over bounded TCP connections to applicable WHOIS services.',
+    disclosure: 'The normalised target is sent over bounded TCP connections to applicable WHOIS services.',
     conditional: false,
 });
 const FAST_DOMAIN_EVIDENCE = Object.freeze({
@@ -39,7 +39,7 @@ const NETWORK_CONTEXT = Object.freeze({
 const REVERSE_DNS = Object.freeze({
     source: 'reverse_dns',
     purpose: 'Collect operator-published reverse-DNS context for a public IP address.',
-    disclosure: 'A DNS resolver receives the reverse lookup for the normalized IP address.',
+    disclosure: 'A DNS resolver receives the reverse lookup for the normalised IP address.',
     conditional: false,
 });
 function plannedSources(classified, deep) {

package/cli/lookup-reconcile.mjs

@@ -0,0 +1,141 @@
+import { CliUsageError } from "./errors.mjs";
+import { buildCliLookupDiff } from "./lookup-diff.mjs";
+import { parseSavedLookupDocument } from "./saved-lookup.mjs";
+const CLI_LOOKUP_RECONCILIATION_SCHEMA = 'whoisleuth.cli.lookup-reconciliation';
+const CLI_LOOKUP_RECONCILIATION_VERSION = 1;
+const MAX_LOOKUP_RECONCILIATION_INPUT_BYTES = 32 * 1024 * 1024;
+function object(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+function label(value) {
+    if (typeof value !== 'string')
+        return null;
+    const normalized = value.replace(/[\u0000-\u001f\u007f]+/gu, ' ').replace(/\s+/gu, ' ').trim().slice(0, 80);
+    return normalized || null;
+}
+function observationContext(document) {
+    const context = object(document.collectionContext);
+    return {
+        generatedAt: document.generatedAt,
+        mode: document.mode,
+        observerLabel: label(context.observerLabel),
+        vantageLabel: label(context.vantageLabel),
+    };
+}
+function comparable(value, sourceState) {
+    if (['error', 'not_recorded', 'partial', 'skipped', 'unavailable', 'unsupported'].includes(sourceState))
+        return false;
+    return value !== 'Not observed' && value !== 'Not recorded in compact Bulk evidence';
+}
+function normalizedValue(value) {
+    return value.replace(/\s+/gu, ' ').trim().toLocaleLowerCase('en-US');
+}
+function buildCliLookupReconciliation(inputs, generatedAt = new Date().toISOString()) {
+    if (inputs.length < 2 || inputs.length > 5)
+        throw new CliUsageError('Lookup reconciliation requires from 2 to 5 observations.');
+    const documents = inputs.map((input, index) => parseSavedLookupDocument(input, {
+        label: `Lookup reconciliation observation ${index + 1}`,
+    }));
+    const domain = documents[0]?.registrableDomain;
+    if (!domain || documents.some((document) => document.registrableDomain !== domain)) {
+        throw new CliUsageError('Lookup reconciliation requires observations for one domain.');
+    }
+    const comparisons = documents.slice(1).map((document, index) => buildCliLookupDiff(inputs[0], inputs[index + 1], generatedAt, { domainMode: 'same' }));
+    const firstRows = comparisons[0]?.comparison.rows || [];
+    const fields = firstRows.map((firstRow) => {
+        const values = [{
+                observation: 0,
+                value: firstRow.left,
+                sourceState: firstRow.leftSourceState,
+                comparable: comparable(firstRow.left, firstRow.leftSourceState),
+            }];
+        for (let index = 0; index < comparisons.length; index++) {
+            const row = comparisons[index].comparison.rows.find((candidate) => candidate.id === firstRow.id);
+            if (!row)
+                continue;
+            values.push({
+                observation: index + 1,
+                value: row.right,
+                sourceState: row.rightSourceState,
+                comparable: comparable(row.right, row.rightSourceState),
+            });
+        }
+        const comparableValues = values.filter((value) => value.comparable);
+        const distinctValues = new Set(comparableValues.map((value) => normalizedValue(value.value)));
+        const state = comparableValues.length < 2
+            ? 'non_comparable'
+            : distinctValues.size === 1
+                ? 'agreement'
+                : 'disagreement';
+        return {
+            id: firstRow.id,
+            category: firstRow.category,
+            label: firstRow.label,
+            source: firstRow.source,
+            state,
+            method: firstRow.method,
+            values,
+            limitations: firstRow.limitations,
+        };
+    });
+    const observations = documents.map(observationContext);
+    const identities = observations.map((observation) => (observation.observerLabel && observation.vantageLabel
+        ? `${observation.observerLabel}\u0000${observation.vantageLabel}`
+        : null));
+    const labelsComplete = identities.every((identity) => identity !== null);
+    const labelsDistinct = labelsComplete && new Set(identities).size === identities.length;
+    const independence = labelsDistinct
+        ? {
+            state: 'verified_distinct_labels',
+            reason: 'Every observation carries a different analyst-supplied observer and vantage label.',
+        }
+        : {
+            state: 'unverified',
+            reason: 'Observer and vantage labels are missing or repeated; independent collection cannot be inferred.',
+        };
+    return {
+        schema: CLI_LOOKUP_RECONCILIATION_SCHEMA,
+        version: CLI_LOOKUP_RECONCILIATION_VERSION,
+        generatedAt,
+        domain,
+        independence,
+        observations,
+        fields,
+        summary: {
+            observationCount: observations.length,
+            agreement: fields.filter((field) => field.state === 'agreement').length,
+            disagreement: fields.filter((field) => field.state === 'disagreement').length,
+            nonComparable: fields.filter((field) => field.state === 'non_comparable').length,
+        },
+        privacy: { filenamesRetained: 0, rawRegistryPayloadsCopied: 0 },
+        limitations: [
+            'This report reconciles only bounded normalised values already present in saved Lookup documents and makes no network request.',
+            'Observer and vantage labels are analyst-supplied metadata. Distinct labels do not prove independent resolvers, networks, providers, caches, or collection paths.',
+            'Agreement can reflect shared upstream data or collection conditions. Disagreement can reflect collection timing, propagation, source health, or a real domain change.',
+            'Non-comparable evidence remains separate from agreement and is never interpreted as absence, safety, or a negative finding.',
+        ],
+    };
+}
+function formatCliLookupReconciliation(document) {
+    const output = [
+        'Lookup observation reconciliation',
+        `Domain             ${document.domain}`,
+        `Observations       ${document.summary.observationCount}`,
+        `Independence       ${document.independence.state.replaceAll('_', ' ')}`,
+        `Agreement          ${document.summary.agreement}`,
+        `Disagreement       ${document.summary.disagreement}`,
+        `Non-comparable     ${document.summary.nonComparable}`,
+        '',
+    ];
+    for (const field of document.fields.filter((candidate) => candidate.state !== 'agreement')) {
+        output.push(`${field.label} [${field.state.replaceAll('_', ' ')}]`);
+        for (const value of field.values) {
+            output.push(`  Observation ${value.observation + 1}: ${value.value} (${value.sourceState.replaceAll('_', ' ')})`);
+        }
+    }
+    output.push('', 'Limitations:');
+    for (const limitation of document.limitations)
+        output.push(`  - ${limitation}`);
+    return `${output.join('\n')}\n`;
+}
+export { CLI_LOOKUP_RECONCILIATION_SCHEMA, CLI_LOOKUP_RECONCILIATION_VERSION, MAX_LOOKUP_RECONCILIATION_INPUT_BYTES, buildCliLookupReconciliation, formatCliLookupReconciliation, };