@slicedearth/whoisleuth-cli 1.32.0

package/frontend/src/lib/analysis/case-migration-model.js

@@ -0,0 +1,248 @@
+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, isoOrNull, normalizeCase, normalizeDomain, normalizeEvidenceHistory, normalizeNotes, normalizeTags, objectRecord, safeId, } from "./case-record-model.js";
+import { mergeCaseActions, mergeCaseAssertions, mergeCaseDecisions, mergeCaseEvidencePins, mergeCaseManualTrail, mergeCaseSightings, normalizeCaseActions, normalizeCaseAssertions, normalizeCaseDecisions, normalizeCaseEvidencePins, normalizeCaseManualTrail, normalizeCaseSightings, } from "./case-response-model.js";
+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));
+function assignUniqueIds(cases) {
+    const used = new Set();
+    for (const record of [...cases].sort((a, b) => a.domain.localeCompare(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 an arbitrary parsed value. Accepts the
+ * versioned envelope or a 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. Never throws.
+ * @param {unknown} raw
+ * @returns {CaseStore}
+ */
+export function normalizeCaseStore(raw) {
+    const now = new Date().toISOString();
+    const byDomain = new Map();
+    for (const item of asCaseList(raw)) {
+        const normalized = normalizeCase(item, undefined, now);
+        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 };
+}
+/**
+ * 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) {
+    const value = objectRecord(raw).version;
+    return typeof value === 'number' ? 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 [];
+}
+/**
+ * @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) {
+    const record = objectRecord(raw);
+    const domain = normalizeDomain(record.domain);
+    if (!domain)
+        return null;
+    const importFallback = isoOrNull(record.updatedAt) || isoOrNull(record.createdAt) || null;
+    const normalizedFallback = importFallback || '1970-01-01T00:00:00.000Z';
+    const rawEvidence = Array.isArray(record.evidenceHistory) ? record.evidenceHistory : [];
+    const evidencePins = normalizeCaseEvidencePins(record.evidencePins, normalizedFallback);
+    const pinIds = new Set(evidencePins.map((item) => item.id));
+    return {
+        domain,
+        rawId: typeof record.id === 'string' ? record.id : null,
+        status: importScalar(record.status, STATUS_VALUES),
+        disposition: importScalar(record.disposition, DISPOSITION_VALUES),
+        source: importScalar(record.source, SOURCE_VALUES),
+        evidenceHistory: normalizeEvidenceHistory(rawEvidence, { source: 'import', fallback: importFallback }),
+        evidencePins,
+        decisions: normalizeCaseDecisions(record.decisions, normalizedFallback, pinIds),
+        actions: normalizeCaseActions(record.actions, normalizedFallback),
+        assertions: normalizeCaseAssertions(record.assertions, normalizedFallback, pinIds),
+        manualTrail: normalizeCaseManualTrail(record.manualTrail, normalizedFallback),
+        sightings: normalizeCaseSightings(record.sightings, normalizedFallback, pinIds),
+        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),
+        createdAt: isoOrNull(record.createdAt),
+        updatedAt: isoOrNull(record.updatedAt),
+    };
+}
+/** @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) {
+    return normalizeEvidenceHistory([...local, ...imported], { source: 'import', fallback: null });
+}
+/** @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,
+        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,
+        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));
+    return {
+        ...local,
+        status: patch.status !== undefined && importNewer ? patch.status : local.status,
+        disposition: patch.disposition !== undefined && importNewer ? patch.disposition : local.disposition,
+        source: patch.source !== undefined && importNewer ? patch.source : local.source,
+        evidenceHistory: mergeEvidenceHistories(local.evidenceHistory, patch.evidenceHistory),
+        evidencePins,
+        decisions: mergeCaseDecisions(local.decisions, patch.decisions, fallback, pinIds),
+        actions: mergeCaseActions(local.actions, patch.actions, fallback),
+        assertions: mergeCaseAssertions(local.assertions, patch.assertions, fallback, pinIds),
+        manualTrail: mergeCaseManualTrail(local.manualTrail, patch.manualTrail, fallback),
+        sightings: mergeCaseSightings(local.sightings, patch.sightings, fallback, pinIds),
+        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,
+    };
+}
+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;
+}
+/**
+ * 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 }}
+ */
+export function mergeCases(localCases, importedRaw) {
+    const importedVersion = parseStoreVersion(importedRaw);
+    if (importedVersion !== null && Number.isInteger(importedVersion) && importedVersion > CASE_SCHEMA_VERSION) {
+        throw new Error(`This case file was exported by a newer version of WHOISleuth (schema ${importedVersion}). Update the app before importing it.`);
+    }
+    if (!CASE_IMPORT_VERSIONS.includes(importedVersion)
+        || !importedRaw || typeof importedRaw !== 'object'
+        || !Array.isArray(objectRecord(importedRaw).cases)) {
+        throw new Error(`Expected a WHOISleuth case export using schema ${CASE_IMPORT_VERSIONS.join(' or ')}.`);
+    }
+    const local = normalizeCaseStore(localCases).cases;
+    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;
+    let skipped = 0;
+    const now = new Date().toISOString();
+    for (const item of asCaseList(importedRaw)) {
+        const patch = extractImportPatch(item);
+        if (!patch) {
+            skipped += 1;
+            continue;
+        }
+        const existing = byDomain.get(patch.domain);
+        if (existing) {
+            byDomain.set(patch.domain, applyImportPatch(existing, patch));
+            updated += 1;
+        }
+        else if (byDomain.size < MAX_CASES) {
+            const record = caseFromPatch(patch, now);
+            record.id = pickFreeId(patch.rawId, patch.domain, usedIds);
+            usedIds.add(record.id);
+            byDomain.set(patch.domain, record);
+            added += 1;
+        }
+        else {
+            skipped += 1;
+        }
+    }
+    return { cases: normalizeCaseStore([...byDomain.values()]).cases, added, updated, skipped };
+}

package/frontend/src/lib/analysis/case-model.js

@@ -0,0 +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";

package/frontend/src/lib/analysis/case-record-contracts.js

@@ -0,0 +1,44 @@
+export const CASE_SCHEMA_VERSION = 9;
+export const CASE_IMPORT_VERSIONS = [3, 4, 5, 6, 7, 8, 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 CASE_STATUSES = [
+    { value: 'new', label: 'New' },
+    { value: 'reviewing', label: 'Reviewing' },
+    { value: 'monitoring', label: 'Monitoring' },
+    { value: 'escalated', label: 'Escalated' },
+    { value: 'resolved', label: 'Resolved' },
+];
+export const CASE_DISPOSITIONS = [
+    { value: 'unreviewed', label: 'Unreviewed' },
+    { value: 'suspicious', label: 'Suspicious' },
+    { value: 'confirmed_abuse', label: 'Confirmed abuse' },
+    { value: 'false_positive', label: 'False positive' },
+    { value: 'expected', label: 'Expected' },
+    { value: 'closed_no_action', label: 'Closed without action' },
+];
+export const CASE_SOURCES = [
+    { value: 'lookup', label: 'Lookup' },
+    { value: 'bulk', label: 'Bulk' },
+    { value: 'monitor', label: 'Monitor' },
+    { value: 'manual', label: 'Manual' },
+    { value: 'unknown', label: 'Unknown' },
+];
+export const EVIDENCE_SOURCES = ['lookup', 'bulk', 'monitor', 'import', 'unknown'];
+export const DEFAULT_STATUS = 'new';
+export const DEFAULT_DISPOSITION = 'unreviewed';
+export const DEFAULT_SOURCE = 'unknown';

package/frontend/src/lib/analysis/case-record-core.js

@@ -0,0 +1,232 @@
+// Pure, framework-neutral analyst-case records, evidence histories, bounded
+// record normalization, and analyst updates.
+import { CASE_DISPOSITIONS, CASE_IMPORT_VERSIONS, CASE_SCHEMA_VERSION, CASE_SOURCES, CASE_STATUSES, DEFAULT_DISPOSITION, DEFAULT_SOURCE, DEFAULT_STATUS, EVIDENCE_SOURCES, MAX_CASES, MAX_CASE_IMPORT_BYTES, MAX_CASE_STORE_BYTES, 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_NOTES_PER_CASE, MAX_NOTE_LENGTH, MAX_TAGS_PER_CASE, MAX_TAG_LENGTH, } from "./case-record-contracts.js";
+// Forward-version policy (two distinct guarantees):
+//   - A locally-stored envelope that declares a version greater than this is
+//     still read best-effort on load (known fields kept, unknown dropped), but
+//     is never OVERWRITTEN or exported as a downgraded backup (the storage
+//     wrapper blocks the write/export). "Not overwritten", not "not read".
+//   - An IMPORT file that declares a greater version is never INTERPRETED at
+//     all: mergeCases rejects it up front so we don't merge data from a schema
+//     we don't understand.
+// The provenance recorded on an individual evidence snapshot. Distinct from a
+// case's `source`: a snapshot can be imported, and a case opened by hand
+// ('manual') has no snapshot provenance of its own.
+export const EVIDENCE_SOURCE_SET = new Set(EVIDENCE_SOURCES);
+export const DEFAULT_EVIDENCE_SOURCE = 'unknown';
+// Deterministic "more informative source wins" order used when a materially
+// identical capture is seen again from a different source. A direct scan beats
+// a monitor bookmark beats a second-hand import beats unknown.
+export const EVIDENCE_SOURCE_RANK = {
+    lookup: 4,
+    bulk: 4,
+    monitor: 2,
+    import: 1,
+    unknown: 0,
+};
+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));
+const STATUS_LABELS = Object.fromEntries(CASE_STATUSES.map((item) => [item.value, item.label]));
+const DISPOSITION_LABELS = Object.fromEntries(CASE_DISPOSITIONS.map((item) => [item.value, item.label]));
+const SOURCE_LABELS = Object.fromEntries(CASE_SOURCES.map((item) => [item.value, item.label]));
+// Availability tokens that actually assert something about the domain. Anything
+// else ('unknown', 'error', empty) is not, on its own, material evidence.
+export const CONCLUSIVE_AVAILABILITY = new Set([
+    'available',
+    'registered',
+    'for_sale',
+    'expiring',
+]);
+export const REGISTERED_LIKE = new Set([
+    'registered',
+    'for_sale',
+    'expiring',
+]);
+// URL/DOM/query-string-safe id shape. UUIDs satisfy this; anything else is
+// treated as untrusted and deterministically repaired.
+const SAFE_ID_RE = /^[A-Za-z0-9_-]{1,64}$/;
+export function objectRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+export function statusLabel(value) {
+    return (typeof value === 'string' ? STATUS_LABELS[value] : '') || String(value || '');
+}
+export function dispositionLabel(value) {
+    return (typeof value === 'string' ? DISPOSITION_LABELS[value] : '') || String(value || '');
+}
+export function sourceLabel(value) {
+    return (typeof value === 'string' ? SOURCE_LABELS[value] : '') || String(value || '');
+}
+export function isValidStatus(value) {
+    return typeof value === 'string' && STATUS_VALUES.has(value);
+}
+export function isValidDisposition(value) {
+    return typeof value === 'string' && DISPOSITION_VALUES.has(value);
+}
+/** Fresh, safe, effectively-unique id for a brand-new local record. */
+export function makeId() {
+    if (typeof globalThis.crypto?.randomUUID === 'function')
+        return globalThis.crypto.randomUUID();
+    return `case-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+export function safeId(value) {
+    return typeof value === 'string' && SAFE_ID_RE.test(value) ? value : null;
+}
+// Deterministic 32-bit FNV-1a hash -> base36, so a repaired id or evidence
+// fingerprint is a pure function of its input (stable across normalization).
+export function hashString(value) {
+    let hash = 2166136261 >>> 0;
+    for (let index = 0; index < value.length; index++) {
+        hash ^= value.charCodeAt(index);
+        hash = Math.imul(hash, 16777619) >>> 0;
+    }
+    return hash.toString(36);
+}
+export function deterministicId(domain) {
+    return `c-${hashString(domain)}`;
+}
+/**
+ * Strict, canonical domain normalization. Parses through the WHATWG URL host
+ * (which strips scheme/path/port/userinfo and applies IDNA/punycode so Unicode
+ * and its punycode form collapse to one value), lowercases, drops a single
+ * terminal root dot, and validates LDH hostname labels. Rejects IPs, ASNs,
+ * whitespace/control characters, underscores, empty/overlong/hyphen-edged
+ * labels, and undotted names. Returns '' for anything unusable.
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function normalizeDomain(value) {
+    const raw = String(value == null ? '' : value).trim();
+    if (!raw || /[\s\x00-\x1f\x7f]/.test(raw))
+        return '';
+    let hostname;
+    try {
+        const hasScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(raw);
+        hostname = new URL(hasScheme ? raw : `http://${raw}`).hostname;
+    }
+    catch {
+        return '';
+    }
+    hostname = hostname.toLowerCase().replace(/\.$/, '');
+    if (!hostname || hostname.length > MAX_DOMAIN_LENGTH)
+        return '';
+    // A leftover ':' or '[' means a port/IPv6 the host parser preserved.
+    if (hostname.includes(':') || hostname.startsWith('['))
+        return '';
+    const labels = hostname.split('.');
+    if (labels.length < 2)
+        return '';
+    const labelPattern = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+    for (const label of labels) {
+        if (!label || label.length > 63 || !labelPattern.test(label))
+            return '';
+    }
+    // An all-numeric final label is an IPv4 address, never a hostname TLD.
+    if (/^[0-9]+$/.test(labels.at(-1) ?? ''))
+        return '';
+    return hostname;
+}
+export function normalizeStatus(value) {
+    return typeof value === 'string' && STATUS_VALUES.has(value) ? value : DEFAULT_STATUS;
+}
+export function normalizeDisposition(value) {
+    return typeof value === 'string' && DISPOSITION_VALUES.has(value) ? value : DEFAULT_DISPOSITION;
+}
+export function normalizeSource(value) {
+    return typeof value === 'string' && SOURCE_VALUES.has(value) ? value : DEFAULT_SOURCE;
+}
+/** Parsed ISO string, or null when missing/invalid (used for import ordering). */
+export function isoOrNull(value) {
+    if (typeof value === 'string') {
+        const parsed = Date.parse(value);
+        if (!Number.isNaN(parsed))
+            return new Date(parsed).toISOString();
+    }
+    return null;
+}
+export function isoOrNow(value, fallback) {
+    return isoOrNull(value) || fallback;
+}
+/**
+ * @param {unknown} value
+ * @returns {string[]}
+ */
+export function normalizeTags(value) {
+    if (!Array.isArray(value))
+        return [];
+    const seen = new Set();
+    const tags = [];
+    for (const raw of value) {
+        const tag = String(raw == null ? '' : raw).trim().slice(0, MAX_TAG_LENGTH);
+        if (!tag)
+            continue;
+        const key = tag.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        tags.push(tag);
+        if (tags.length >= MAX_TAGS_PER_CASE)
+            break;
+    }
+    return tags;
+}
+/**
+ * @param {unknown} body
+ * @returns {string}
+ */
+export function normalizeNoteBody(body) {
+    return String(body == null ? '' : body).trim().slice(0, MAX_NOTE_LENGTH);
+}
+/**
+ * Normalizes one note deterministically. `createdAt` is the note's own valid
+ * timestamp, else the supplied `fallback`; a note with neither is skipped rather
+ * than stamped with an arbitrary time. Repaired ids are a pure function of the
+ * body plus the resolved timestamp, so re-importing the same note produces the
+ * same id (and therefore dedupes) instead of a fresh one.
+ * @param {unknown} raw
+ * @param {string | null} fallback
+ * @returns {CaseNote | null}
+ */
+function normalizeNote(raw, fallback) {
+    const record = objectRecord(raw);
+    const body = normalizeNoteBody(record.body);
+    if (!body)
+        return null;
+    const createdAt = isoOrNull(record.createdAt) || fallback;
+    if (!createdAt)
+        return null;
+    return {
+        id: safeId(record.id) || `n-${hashString(`${body}|${createdAt}`)}`,
+        body,
+        createdAt,
+    };
+}
+/**
+ * @param {unknown} value
+ * @param {string | null} fallback timestamp for notes lacking their own (the
+ *   genuine "now" for local recovery; only the imported record's own createdAt/
+ *   updatedAt for imports, never the current time)
+ * @returns {CaseNote[]}
+ */
+export function normalizeNotes(value, fallback) {
+    if (!Array.isArray(value))
+        return [];
+    const seen = new Set();
+    const notes = [];
+    for (const raw of value) {
+        const note = normalizeNote(raw, fallback);
+        if (!note || seen.has(note.id))
+            continue;
+        seen.add(note.id);
+        notes.push(note);
+    }
+    notes.sort((a, b) => Date.parse(a.createdAt) - Date.parse(b.createdAt));
+    // Keep the most recent notes when over the bound.
+    return notes.slice(Math.max(0, notes.length - MAX_NOTES_PER_CASE));
+}
+// ---------------------------------------------------------------------------
+// Evidence snapshot normalization
+// ---------------------------------------------------------------------------

package/frontend/src/lib/analysis/case-record-model.js

@@ -0,0 +1,7 @@
+// Stable case-record facade. Core validation, evidence history/comparison,
+// and analyst-record operations remain framework-neutral and independently
+// testable while existing consumers keep one compatibility import.
+export * from "./case-record-contracts.js";
+export * from "./case-record-core.js";
+export * from "./case-evidence-model.js";
+export * from "./case-record-operations.js";