@slicedearth/whoisleuth-cli 1.47.4 → 2.0.0

package/packages/cases/case-migration-model.mjs

@@ -0,0 +1,476 @@
+import { CASE_DISPOSITIONS, CASE_IMPORT_VERSIONS, CASE_SCHEMA_VERSION, CASE_SOURCES, CASE_STATUSES, DEFAULT_DISPOSITION, DEFAULT_SOURCE, DEFAULT_STATUS, MAX_CASES, MAX_NOTES_PER_CASE, deterministicId, caseTimestampOrNull, normalizeCase, normalizeDomain, normalizeEvidenceHistory, normalizeNotes, normalizeReviewReasonCode, normalizeTags, objectRecord, safeId, } from "./case-record-model.mjs";
+import { CASE_REPORT_SCHEMA, caseReportVersionMatchesCase, CLI_CASE_PACK_CURRENT_REDACTION_KEYS, CLI_CASE_PACK_INTEGRITY_KEYS, CLI_CASE_PACK_LIMITATIONS, CLI_CASE_PACK_PACKET_KEYS, CLI_CASE_PACK_PUBLIC_REPORT_KEYS, CLI_CASE_PACK_REPORT_KEYS, CLI_CASE_PACK_ROOT_KEYS, CLI_CASE_PACK_SCHEMA, CLI_CASE_PACK_VERSION, } from "../contracts/case-portability.mjs";
+import { canonicalArtifactJsonV2 } from "../evidence/artifact-integrity.mjs";
+import { assertBoundedJsonStructure } from "../../lib/bounded-json.mjs";
+import { inspectCaseBrandProfileIds, unionCaseBrandProfileIds, } from "./case-brand-profile-references.mjs";
+import { caseInvestigationBranchReferences, mergeCaseInvestigationBranches, normalizeCaseInvestigationBranches, } from "./case-investigation-branch-model.mjs";
+import { buildCaseClosureLinkContext, mergeCaseActions, mergeCaseAssertions, mergeCaseClosureHistories, mergeCaseDecisions, mergeCaseEvidencePins, mergeCaseManualTrail, mergeCaseObservedEffectHistories, mergeCaseSightings, normalizeCaseActions, normalizeCaseAssertions, normalizeCaseClosureHistory, normalizeCaseDecisions, normalizeCaseEvidencePins, normalizeCaseManualTrail, normalizeCaseObservedEffectHistory, normalizeCaseSightings, } from "./case-response-model.mjs";
+const STATUS_VALUES = new Set(CASE_STATUSES.map((item) => item.value));
+const DISPOSITION_VALUES = new Set(CASE_DISPOSITIONS.map((item) => item.value));
+const SOURCE_VALUES = new Set(CASE_SOURCES.map((item) => item.value));
+export const MAX_CASE_INPUT_RECORDS = 2_000;
+function compareCodeUnits(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+const CASE_INPUT_JSON_LIMITS = Object.freeze({
+    maximumDepth: 48,
+    maximumKeys: 500_000,
+    maximumValues: 1_000_000,
+    maximumContainerItems: 10_000,
+});
+function assignUniqueIds(cases) {
+    const used = new Set();
+    for (const record of [...cases].sort((a, b) => compareCodeUnits(a.domain, b.domain))) {
+        let id = safeId(record.id) || deterministicId(record.domain);
+        if (used.has(id)) {
+            const base = deterministicId(record.domain);
+            id = base;
+            let suffix = 2;
+            while (used.has(id))
+                id = `${base}-${suffix++}`;
+        }
+        used.add(id);
+        record.id = id;
+    }
+}
+/**
+ * Recovers a clean, bounded store from the current versioned envelope or an
+ * internal bare array, drops malformed records, keeps a single
+ * case per domain (most recently updated wins), caps to MAX_CASES by recency,
+ * and guarantees globally unique safe ids. Retired, future, accessor-bearing,
+ * sparse, or otherwise non-JSON envelopes fail before normalisation.
+ * @param {unknown} raw
+ * @returns {CaseStore}
+ */
+export function normalizeCaseStore(raw) {
+    assertBoundedJsonStructure(raw, 'Case store', CASE_INPUT_JSON_LIMITS);
+    const fallback = new Date(0).toISOString();
+    const sourceVersion = parseStoreVersion(raw);
+    if (!Array.isArray(raw)) {
+        if (sourceVersion === null) {
+            throw new TypeError(`Unversioned Case stores are retired. Export or reset them explicitly before using Case schema ${CASE_SCHEMA_VERSION}; no data was changed.`);
+        }
+        if (!CASE_IMPORT_VERSIONS.includes(sourceVersion) && sourceVersion < CASE_SCHEMA_VERSION) {
+            throw new TypeError(`Case schema ${sourceVersion} is not part of the public compatibility boundary. Only public schema 12 migrates to schema ${CASE_SCHEMA_VERSION}; no data was changed.`);
+        }
+        if (sourceVersion > CASE_SCHEMA_VERSION) {
+            throw new TypeError(`Case schema ${sourceVersion} is newer than the supported schema ${CASE_SCHEMA_VERSION}; no data was changed.`);
+        }
+        if (sourceVersion === CASE_SCHEMA_VERSION) {
+            assertCurrentEvidenceHostnameShape(raw);
+        }
+    }
+    const byDomain = new Map();
+    for (const item of boundedCaseList(raw).items) {
+        const normalized = normalizeCase(item, undefined, fallback, sourceVersion ?? CASE_SCHEMA_VERSION);
+        if (!normalized)
+            continue;
+        const existing = byDomain.get(normalized.domain);
+        if (!existing || Date.parse(normalized.updatedAt) >= Date.parse(existing.updatedAt)) {
+            byDomain.set(normalized.domain, normalized);
+        }
+    }
+    const cases = [...byDomain.values()]
+        .sort((a, b) => Date.parse(b.updatedAt) - Date.parse(a.updatedAt))
+        .slice(0, MAX_CASES);
+    assignUniqueIds(cases);
+    return { version: CASE_SCHEMA_VERSION, cases };
+}
+function assertCurrentEvidenceHostnameShape(raw) {
+    for (const item of boundedCaseList(raw).items) {
+        const evidenceHistory = objectRecord(item).evidenceHistory;
+        if (!Array.isArray(evidenceHistory))
+            continue;
+        for (const snapshot of evidenceHistory) {
+            const record = objectRecord(snapshot);
+            if (Object.keys(record).length > 0 && !Object.hasOwn(record, 'inputHostname')) {
+                throw new TypeError(`Case schema ${CASE_SCHEMA_VERSION} evidence snapshots must declare their exact submitted hostname, including null; unreleased local Case checkpoints are not interpreted as the v2 format and no data was changed.`);
+            }
+        }
+    }
+}
+/**
+ * The schema version declared by a stored/parsed value, or null. The storage
+ * wrapper uses this to refuse overwriting data written by a newer, unsupported
+ * version instead of silently downgrading it.
+ * @param {unknown} raw
+ * @returns {number | null}
+ */
+export function parseStoreVersion(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return null;
+    let descriptor;
+    try {
+        descriptor = Object.getOwnPropertyDescriptor(raw, 'version');
+    }
+    catch {
+        throw new TypeError('The Case store version could not be inspected safely.');
+    }
+    if (!descriptor)
+        return null;
+    if (!Object.hasOwn(descriptor, 'value')) {
+        throw new TypeError('The Case store version must not be an accessor.');
+    }
+    return typeof descriptor.value === 'number' ? descriptor.value : null;
+}
+/** @param {unknown} raw @returns {unknown[]} */
+function asCaseList(raw) {
+    if (Array.isArray(raw))
+        return raw;
+    const cases = objectRecord(raw).cases;
+    if (Array.isArray(cases))
+        return cases;
+    return [];
+}
+function boundedCaseList(raw) {
+    const source = asCaseList(raw);
+    return {
+        items: source.slice(0, MAX_CASE_INPUT_RECORDS),
+        omitted: Math.max(0, source.length - MAX_CASE_INPUT_RECORDS),
+    };
+}
+/**
+ * @param {{ domain: unknown, status?: unknown, disposition?: unknown, source?: unknown, tags?: unknown, evidence?: unknown, note?: unknown }} input
+ * @param {string} [nowIso]
+ * @returns {CaseRecord}
+ */
+function importScalar(value, valid) {
+    return typeof value === 'string' && valid.has(value) ? value : undefined;
+}
+/**
+ * Validates one imported record into a patch. Unlike normalizeCase, absent or
+ * invalid scalar fields stay `undefined` (never defaulted) and a missing/invalid
+ * updatedAt stays `null` (treated as older than any real local timestamp), so an
+ * incomplete import can never win a merge over valid local data. Imported
+ * evidence is normalized additively; a snapshot with no captured time falls back
+ * only to the imported record's own (older) timestamps, never to "now".
+ * @param {unknown} raw
+ * @returns {ImportPatch | null}
+ */
+function extractImportPatch(raw, importedVersion) {
+    const record = objectRecord(raw);
+    const domain = normalizeDomain(record.domain);
+    if (!domain)
+        return null;
+    const importFallback = caseTimestampOrNull(record.updatedAt, importedVersion)
+        || caseTimestampOrNull(record.createdAt, importedVersion)
+        || null;
+    const normalizedFallback = importFallback || '1970-01-01T00:00:00.000Z';
+    const timestampOptions = {
+        legacyTimestamps: importedVersion < CASE_SCHEMA_VERSION,
+        sourceVersion: importedVersion,
+    };
+    const rawEvidence = Array.isArray(record.evidenceHistory) ? record.evidenceHistory : [];
+    const evidencePins = normalizeCaseEvidencePins(record.evidencePins, normalizedFallback, {
+        allowCertificateObservation: importedVersion >= 11,
+        ...timestampOptions,
+    });
+    const pinIds = new Set(evidencePins.map((item) => item.id));
+    const actions = normalizeCaseActions(record.actions, normalizedFallback, { ...timestampOptions, validEvidencePinIds: pinIds });
+    const assertions = normalizeCaseAssertions(record.assertions, normalizedFallback, pinIds, timestampOptions);
+    const sightings = normalizeCaseSightings(record.sightings, normalizedFallback, pinIds, timestampOptions);
+    const observedEffects = normalizeCaseObservedEffectHistory(importedVersion >= 13 ? record.observedEffects : undefined, normalizedFallback, pinIds, new Set(sightings.map((item) => item.id)), timestampOptions);
+    const closures = normalizeCaseClosureHistory(importedVersion >= 13 ? record.closures : undefined, normalizedFallback, new Set(observedEffects.reviews.map((item) => item.id)), new Set(actions.map((item) => item.id)), timestampOptions, buildCaseClosureLinkContext(observedEffects, actions));
+    const branchReferences = caseInvestigationBranchReferences({ evidencePins, actions, assertions });
+    const brandProfileReferences = importedVersion >= 12
+        ? inspectCaseBrandProfileIds(record.brandProfileIds)
+        : { ids: [], omitted: 0 };
+    return {
+        domain,
+        rawId: typeof record.id === 'string' ? record.id : null,
+        status: importScalar(record.status, STATUS_VALUES),
+        disposition: importScalar(record.disposition, DISPOSITION_VALUES),
+        reviewReasonCode: Object.hasOwn(record, 'reviewReasonCode')
+            ? normalizeReviewReasonCode(record.reviewReasonCode)
+            : undefined,
+        brandProfileIds: brandProfileReferences.ids,
+        brandProfileReferencesOmitted: brandProfileReferences.omitted,
+        source: importScalar(record.source, SOURCE_VALUES),
+        evidenceHistory: normalizeEvidenceHistory(rawEvidence, {
+            source: 'import',
+            fallback: importFallback,
+            sourceVersion: importedVersion,
+            caseDomain: domain,
+        }),
+        evidencePins,
+        decisions: normalizeCaseDecisions(record.decisions, normalizedFallback, pinIds, timestampOptions),
+        actions,
+        assertions,
+        manualTrail: normalizeCaseManualTrail(record.manualTrail, normalizedFallback, timestampOptions),
+        sightings,
+        observedEffects,
+        closures,
+        branches: importedVersion >= 11
+            ? normalizeCaseInvestigationBranches(record.branches, normalizedFallback, branchReferences, timestampOptions)
+            : [],
+        tags: normalizeTags(record.tags),
+        // Imported notes fall back only to the imported record's own timestamps
+        // (never "now"), so a timestamp-less note gets a stable, deterministic time
+        // and id, and re-importing the same file cannot manufacture a duplicate or a
+        // spuriously-newer note.
+        notes: normalizeNotes(record.notes, importFallback, importedVersion),
+        createdAt: caseTimestampOrNull(record.createdAt, importedVersion),
+        updatedAt: caseTimestampOrNull(record.updatedAt, importedVersion),
+    };
+}
+/** @param {CaseNote[]} a @param {CaseNote[]} b @returns {CaseNote[]} */
+function unionNotes(a, b) {
+    const byId = new Map();
+    for (const note of [...a, ...b]) {
+        if (!byId.has(note.id))
+            byId.set(note.id, note);
+    }
+    const notes = [...byId.values()].sort((left, right) => Date.parse(left.createdAt) - Date.parse(right.createdAt));
+    return notes.slice(Math.max(0, notes.length - MAX_NOTES_PER_CASE));
+}
+// Additive, deduplicated union of two evidence histories. Identical material
+// collapses (earliest firstCapturedAt, latest capturedAt), distinct snapshots
+// are retained subject to the per-case bound, and an older import can never
+// move an existing observation backwards.
+function mergeEvidenceHistories(local, imported, caseDomain) {
+    return normalizeEvidenceHistory([...local, ...imported], { source: 'import', fallback: null, caseDomain });
+}
+/** @param {ImportPatch} patch @param {string} now @returns {CaseRecord} */
+function caseFromPatch(patch, now) {
+    return {
+        id: '', // assigned by mergeCases so it can guarantee uniqueness against locals
+        domain: patch.domain,
+        status: patch.status ?? DEFAULT_STATUS,
+        disposition: patch.disposition ?? DEFAULT_DISPOSITION,
+        reviewReasonCode: patch.reviewReasonCode ?? null,
+        brandProfileIds: patch.brandProfileIds,
+        tags: patch.tags,
+        notes: patch.notes,
+        source: patch.source ?? DEFAULT_SOURCE,
+        evidenceHistory: patch.evidenceHistory,
+        evidencePins: patch.evidencePins,
+        decisions: patch.decisions,
+        actions: patch.actions,
+        assertions: patch.assertions,
+        manualTrail: patch.manualTrail,
+        sightings: patch.sightings,
+        observedEffects: patch.observedEffects,
+        closures: patch.closures,
+        branches: patch.branches,
+        createdAt: patch.createdAt || patch.updatedAt || now,
+        updatedAt: patch.updatedAt || patch.createdAt || now,
+    };
+}
+/**
+ * Merges an imported patch into an existing local case. Notes, tags, and
+ * evidence history are merged additively (never destructive); a scalar field is
+ * only overwritten when the import provided a valid value AND is strictly newer
+ * than the local record. A patch with no/invalid updatedAt is never newer.
+ * @param {CaseRecord} local
+ * @param {ImportPatch} patch
+ * @returns {CaseRecord}
+ */
+function applyImportPatch(local, patch) {
+    const importNewer = patch.updatedAt !== null && Date.parse(patch.updatedAt) > Date.parse(local.updatedAt);
+    const fallback = patch.updatedAt || local.updatedAt;
+    const evidencePins = mergeCaseEvidencePins(local.evidencePins, patch.evidencePins, fallback);
+    const pinIds = new Set(evidencePins.map((item) => item.id));
+    const actions = mergeCaseActions(local.actions, patch.actions, fallback, pinIds);
+    const assertions = mergeCaseAssertions(local.assertions, patch.assertions, fallback, pinIds);
+    const branchReferences = caseInvestigationBranchReferences({ evidencePins, actions, assertions });
+    const sightings = mergeCaseSightings(local.sightings, patch.sightings, fallback, pinIds);
+    const sightingIds = new Set(sightings.map((item) => item.id));
+    const observedEffects = mergeCaseObservedEffectHistories(local.observedEffects, patch.observedEffects, fallback, pinIds, sightingIds);
+    const closures = mergeCaseClosureHistories(local.closures, patch.closures, fallback, new Set(observedEffects.reviews.map((item) => item.id)), new Set(actions.map((item) => item.id)), buildCaseClosureLinkContext(observedEffects, actions));
+    const brandProfileReferences = unionCaseBrandProfileIds(local.brandProfileIds, patch.brandProfileIds);
+    return { record: {
+            ...local,
+            status: patch.status !== undefined && importNewer ? patch.status : local.status,
+            disposition: patch.disposition !== undefined && importNewer ? patch.disposition : local.disposition,
+            reviewReasonCode: patch.reviewReasonCode !== undefined && importNewer ? patch.reviewReasonCode : local.reviewReasonCode ?? null,
+            brandProfileIds: brandProfileReferences.ids,
+            source: patch.source !== undefined && importNewer ? patch.source : local.source,
+            evidenceHistory: mergeEvidenceHistories(local.evidenceHistory, patch.evidenceHistory, local.domain),
+            evidencePins,
+            decisions: mergeCaseDecisions(local.decisions, patch.decisions, fallback, pinIds),
+            actions,
+            assertions,
+            manualTrail: mergeCaseManualTrail(local.manualTrail, patch.manualTrail, fallback),
+            sightings,
+            observedEffects,
+            closures,
+            branches: mergeCaseInvestigationBranches(local.branches ?? [], patch.branches, fallback, branchReferences),
+            tags: normalizeTags([...local.tags, ...patch.tags]),
+            notes: unionNotes(local.notes, patch.notes),
+            createdAt: patch.createdAt && Date.parse(patch.createdAt) < Date.parse(local.createdAt) ? patch.createdAt : local.createdAt,
+            updatedAt: importNewer ? (patch.updatedAt ?? local.updatedAt) : local.updatedAt,
+        }, brandProfileReferencesOmitted: brandProfileReferences.omitted };
+}
+function pickFreeId(preferred, domain, used) {
+    const wanted = safeId(preferred);
+    let id = wanted && !used.has(wanted) ? wanted : deterministicId(domain);
+    const base = deterministicId(domain);
+    let suffix = 2;
+    while (used.has(id))
+        id = `${base}-${suffix++}`;
+    return id;
+}
+const CASE_EXPORT_ROOT_KEYS = Object.freeze(['version', 'exportedAt', 'cases']);
+function assertOnlyEnvelopeKeys(value, allowed, label) {
+    const allowedKeys = new Set(allowed);
+    if (Object.keys(value).some((key) => !allowedKeys.has(key))) {
+        throw new Error(`The WHOISleuth ${label} contains undeclared envelope fields.`);
+    }
+}
+function exactStringList(value, expected) {
+    return Array.isArray(value)
+        && value.length === expected.length
+        && value.every((item, index) => item === expected[index]);
+}
+/**
+ * A CLI Case-pack remains browser-importable through its exact top-level Case
+ * collection. This projection closes the known pack envelopes before dropping
+ * pack-only review and integrity metadata; it does not make an integrity claim.
+ * The statically bound CLI verifier remains the exact structure-and-digest
+ * verifier for the durable Case-pack version.
+ */
+function caseCollectionImportEnvelope(importedRaw) {
+    const root = objectRecord(importedRaw);
+    const hasPackField = Object.hasOwn(root, 'packet') || Object.hasOwn(root, 'integrity');
+    if (!hasPackField) {
+        assertOnlyEnvelopeKeys(root, CASE_EXPORT_ROOT_KEYS, 'case export');
+        return root;
+    }
+    assertOnlyEnvelopeKeys(root, CLI_CASE_PACK_ROOT_KEYS, 'CLI Case-pack');
+    if (CLI_CASE_PACK_ROOT_KEYS.some((key) => !Object.hasOwn(root, key))) {
+        throw new Error('The WHOISleuth CLI Case-pack is missing a required envelope field.');
+    }
+    const packet = objectRecord(root.packet);
+    const integrity = objectRecord(root.integrity);
+    const redactionManifest = objectRecord(packet.redactionManifest);
+    assertOnlyEnvelopeKeys(packet, CLI_CASE_PACK_PACKET_KEYS, 'CLI Case-pack packet');
+    assertOnlyEnvelopeKeys(integrity, CLI_CASE_PACK_INTEGRITY_KEYS, 'CLI Case-pack integrity');
+    const rootVersion = root.version;
+    const packVersion = packet.version;
+    if (Number.isSafeInteger(packVersion) && packVersion < CLI_CASE_PACK_VERSION) {
+        throw new Error(`WHOISleuth CLI Case-pack version ${String(packVersion)} is retired. Re-export it as version ${CLI_CASE_PACK_VERSION}; no data was changed.`);
+    }
+    if (Number.isSafeInteger(packVersion) && packVersion > CLI_CASE_PACK_VERSION) {
+        throw new Error(`WHOISleuth CLI Case-pack version ${String(packVersion)} is newer than the supported version ${CLI_CASE_PACK_VERSION}; no data was changed.`);
+    }
+    if (Number.isSafeInteger(rootVersion) && rootVersion < CASE_SCHEMA_VERSION
+        && !CASE_IMPORT_VERSIONS.includes(rootVersion)) {
+        throw new Error(`Case schema ${String(rootVersion)} in this CLI Case-pack is not part of the public compatibility boundary; no data was changed.`);
+    }
+    if (Number.isSafeInteger(rootVersion) && rootVersion > CASE_SCHEMA_VERSION) {
+        throw new Error(`Case schema ${String(rootVersion)} in this CLI Case-pack is newer than the supported schema ${CASE_SCHEMA_VERSION}; no data was changed.`);
+    }
+    assertOnlyEnvelopeKeys(redactionManifest, CLI_CASE_PACK_CURRENT_REDACTION_KEYS, 'CLI Case-pack redaction manifest');
+    const reports = packet.reports;
+    const cases = root.cases;
+    const audience = packet.audience;
+    if (packet.schema !== CLI_CASE_PACK_SCHEMA
+        || packVersion !== CLI_CASE_PACK_VERSION
+        || typeof rootVersion !== 'number'
+        || !CASE_IMPORT_VERSIONS.includes(rootVersion)
+        || packet.reviewed !== true
+        || (audience !== 'internal' && audience !== 'public' && audience !== 'trusted')
+        || !Array.isArray(cases)
+        || !Array.isArray(reports)
+        || reports.length !== cases.length
+        || !exactStringList(packet.limitations, CLI_CASE_PACK_LIMITATIONS)
+        || !Number.isSafeInteger(redactionManifest.sourceCaseCount)
+        || redactionManifest.sourceCaseCount !== cases.length
+        || !Number.isSafeInteger(redactionManifest.brandProfileReferencesOmitted)
+        || redactionManifest.brandProfileReferencesOmitted < 0
+        || integrity.algorithm !== 'SHA-256'
+        || integrity.canonicalization !== 'sorted-json-v2'
+        || typeof integrity.digestSha256 !== 'string'
+        || !/^sha256:[a-f0-9]{64}$/u.test(integrity.digestSha256)
+        || typeof root.exportedAt !== 'string'
+        || caseTimestampOrNull(root.exportedAt) !== root.exportedAt) {
+        throw new Error('The WHOISleuth CLI Case-pack envelope is invalid.');
+    }
+    for (const reportValue of reports) {
+        const report = objectRecord(reportValue);
+        assertOnlyEnvelopeKeys(report, rootVersion === CASE_SCHEMA_VERSION ? CLI_CASE_PACK_REPORT_KEYS : CLI_CASE_PACK_PUBLIC_REPORT_KEYS, 'CLI Case-pack report');
+        if (report.schema !== CASE_REPORT_SCHEMA
+            || !caseReportVersionMatchesCase(rootVersion, report.schemaVersion)
+            || report.generatedAt !== root.exportedAt) {
+            throw new Error('The WHOISleuth CLI Case-pack report epoch is invalid.');
+        }
+    }
+    const normalised = normalizeCaseStore(root).cases;
+    if (normalised.length !== cases.length
+        || (rootVersion === CASE_SCHEMA_VERSION
+            && canonicalArtifactJsonV2(cases) !== canonicalArtifactJsonV2(normalised))) {
+        throw new Error(`The WHOISleuth CLI Case-pack contains a non-canonical schema ${rootVersion} Case collection.`);
+    }
+    return { version: rootVersion, exportedAt: root.exportedAt, cases };
+}
+/**
+ * Merges an imported (already parsed) value into the local cases. Predictable
+ * and idempotent: unknown records are skipped, existing domains merge without
+ * losing newer local decisions, and new ones are added until the store bound is
+ * reached. An imported envelope that declares a schema version newer than we
+ * support is rejected up front (before any local data is touched) rather than
+ * reinterpreted.
+ * @param {CaseRecord[]} localCases
+ * @param {unknown} importedRaw
+ * @returns {{ cases: CaseRecord[], added: number, updated: number, skipped: number, brandProfileReferencesOmitted: number }}
+ */
+export function mergeCases(localCases, importedRaw) {
+    assertBoundedJsonStructure(importedRaw, 'Case import', CASE_INPUT_JSON_LIMITS);
+    const importedEnvelope = caseCollectionImportEnvelope(importedRaw);
+    const importedVersion = parseStoreVersion(importedEnvelope);
+    if (importedVersion !== null && Number.isSafeInteger(importedVersion) && importedVersion < CASE_SCHEMA_VERSION
+        && !CASE_IMPORT_VERSIONS.includes(importedVersion)) {
+        throw new Error(`Case schema ${importedVersion} is not part of the public compatibility boundary. Only public schema 12 migrates to schema ${CASE_SCHEMA_VERSION}; no data was changed.`);
+    }
+    if (importedVersion !== null && Number.isSafeInteger(importedVersion) && importedVersion > CASE_SCHEMA_VERSION) {
+        throw new Error(`Case schema ${importedVersion} is newer than the supported schema ${CASE_SCHEMA_VERSION}; no data was changed.`);
+    }
+    if (!CASE_IMPORT_VERSIONS.includes(importedVersion)
+        || !Array.isArray(importedEnvelope.cases)) {
+        throw new Error(`Expected a well-formed WHOISleuth Case export using schema ${CASE_SCHEMA_VERSION}; no data was changed.`);
+    }
+    if (importedVersion === CASE_SCHEMA_VERSION)
+        assertCurrentEvidenceHostnameShape(importedEnvelope);
+    const local = normalizeCaseStore(localCases).cases;
+    const supportedImportedVersion = importedVersion ?? 0;
+    const byDomain = new Map(local.map((item) => [item.domain, item]));
+    const usedIds = new Set(local.map((item) => item.id));
+    let added = 0;
+    let updated = 0;
+    const imported = boundedCaseList(importedEnvelope);
+    let skipped = imported.omitted;
+    let brandProfileReferencesOmitted = 0;
+    const fallback = new Date(0).toISOString();
+    for (const item of imported.items) {
+        const patch = extractImportPatch(item, supportedImportedVersion);
+        if (!patch) {
+            skipped += 1;
+            continue;
+        }
+        const existing = byDomain.get(patch.domain);
+        if (existing) {
+            const merged = applyImportPatch(existing, patch);
+            byDomain.set(patch.domain, merged.record);
+            brandProfileReferencesOmitted += patch.brandProfileReferencesOmitted + merged.brandProfileReferencesOmitted;
+            updated += 1;
+        }
+        else if (byDomain.size < MAX_CASES) {
+            const record = caseFromPatch(patch, fallback);
+            record.id = pickFreeId(patch.rawId, patch.domain, usedIds);
+            usedIds.add(record.id);
+            byDomain.set(patch.domain, record);
+            brandProfileReferencesOmitted += patch.brandProfileReferencesOmitted;
+            added += 1;
+        }
+        else {
+            skipped += 1;
+        }
+    }
+    return {
+        cases: normalizeCaseStore([...byDomain.values()]).cases,
+        added,
+        updated,
+        skipped,
+        brandProfileReferencesOmitted,
+    };
+}

package/{frontend/src/lib/analysis/case-model.js → packages/cases/case-model.mjs}

@@ -1,5 +1,5 @@
 // Stable case-domain facade. Records, migrations, and storage concerns remain
 // separate internally while callers retain one public contract.
-export * from "./case-record-model.js";
-export * from "./case-migration-model.js";
-export * from "./case-storage-model.js";
+export * from "./case-record-model.mjs";
+export * from "./case-migration-model.mjs";
+export * from "./case-storage-model.mjs";

package/{frontend/src/lib/analysis/case-record-contracts.js → packages/cases/case-record-contracts.mjs}

@@ -1,24 +1,6 @@
-import { ANALYST_REVIEW_REASONS } from "../../../../lib/analyst-taxonomy.mjs";
-export const CASE_SCHEMA_VERSION = 12;
-export const CASE_IMPORT_VERSIONS = [2, 3, 4, 5, 6, 7, 8, 9, 10, 11, CASE_SCHEMA_VERSION];
-export const MAX_CASES = 500;
-export const MAX_NOTES_PER_CASE = 50;
-export const MAX_NOTE_LENGTH = 2000;
-export const MAX_TAGS_PER_CASE = 20;
-export const MAX_TAG_LENGTH = 40;
-export const MAX_DOMAIN_LENGTH = 253;
-export const MAX_CASE_IMPORT_BYTES = 2 * 1024 * 1024;
-export const MAX_EVIDENCE_SNAPSHOTS_PER_CASE = 25;
-export const MAX_EVIDENCE_FACTORS = 20;
-export const MAX_EVIDENCE_NAMESERVERS = 12;
-export const MAX_EVIDENCE_MUTATIONS = 20;
-export const MAX_EVIDENCE_STRING_LENGTH = 200;
-export const MAX_EVIDENCE_TITLE_LENGTH = 200;
-export const MAX_EVIDENCE_DETAIL_LENGTH = 200;
-export const MAX_EVIDENCE_CHANGES = 40;
-export const MAX_CASE_STORE_BYTES = 4 * 1024 * 1024;
-export const MAX_CASE_BRAND_PROFILE_IDS = 8;
-export const MAX_CASE_BRAND_PROFILE_ID_CANDIDATES = 32;
+import { ANALYST_REVIEW_REASONS } from "../../lib/analyst-taxonomy.mjs";
+import { CASE_IMPORT_VERSIONS, CASE_SCHEMA_VERSION, PUBLIC_CASE_SCHEMA_VERSION, MAX_CASE_BRAND_PROFILE_ID_CANDIDATES, MAX_CASE_BRAND_PROFILE_IDS, MAX_CASE_IMPORT_BYTES, MAX_CASE_STORE_BYTES, MAX_CASES, MAX_DOMAIN_LENGTH, MAX_EVIDENCE_CHANGES, MAX_EVIDENCE_DETAIL_LENGTH, MAX_EVIDENCE_FACTORS, MAX_EVIDENCE_MUTATIONS, MAX_EVIDENCE_NAMESERVERS, MAX_EVIDENCE_SNAPSHOTS_PER_CASE, MAX_EVIDENCE_STRING_LENGTH, MAX_EVIDENCE_TITLE_LENGTH, MAX_NOTE_LENGTH, MAX_NOTES_PER_CASE, MAX_TAG_LENGTH, MAX_TAGS_PER_CASE, } from "../contracts/case-portability.mjs";
+export { CASE_IMPORT_VERSIONS, CASE_SCHEMA_VERSION, PUBLIC_CASE_SCHEMA_VERSION, MAX_CASE_BRAND_PROFILE_ID_CANDIDATES, MAX_CASE_BRAND_PROFILE_IDS, MAX_CASE_IMPORT_BYTES, MAX_CASE_STORE_BYTES, MAX_CASES, MAX_DOMAIN_LENGTH, MAX_EVIDENCE_CHANGES, MAX_EVIDENCE_DETAIL_LENGTH, MAX_EVIDENCE_FACTORS, MAX_EVIDENCE_MUTATIONS, MAX_EVIDENCE_NAMESERVERS, MAX_EVIDENCE_SNAPSHOTS_PER_CASE, MAX_EVIDENCE_STRING_LENGTH, MAX_EVIDENCE_TITLE_LENGTH, MAX_NOTE_LENGTH, MAX_NOTES_PER_CASE, MAX_TAG_LENGTH, MAX_TAGS_PER_CASE, };
 export const CASE_STATUSES = [
     { value: 'new', label: 'New' },
     { value: 'reviewing', label: 'Reviewing' },