@slicedearth/whoisleuth-cli 2.4.0 → 2.5.1

package/packages/cases/case-evidence-links.mjs

@@ -0,0 +1,135 @@
+import { array, enumeration, exact, exactOptional, iso, text } from "../evidence/artifact-structure.mjs";
+import { assertWorkspaceInputGraph } from "../workspace/hostile-input.mjs";
+import { MAX_CASE_EVIDENCE_PINS, MAX_RESPONSE_RATIONALE_LENGTH } from "../contracts/case-portability.mjs";
+import { SAFE_ID_RE, freshId } from "./case-response-values.mjs";
+export const CASE_EVIDENCE_LINK_KINDS = ['derived_from', 'shared_source'];
+/** Enough for both directed relationships between every admitted pin pair. */
+export const MAX_CASE_EVIDENCE_LINKS = MAX_CASE_EVIDENCE_PINS * (MAX_CASE_EVIDENCE_PINS - 1) * CASE_EVIDENCE_LINK_KINDS.length;
+function identifier(value) {
+    const id = text(value, 'Evidence link identity', 64);
+    if (!SAFE_ID_RE.test(id))
+        throw new TypeError('Evidence link identity is invalid.');
+    return id;
+}
+function explanation(value) {
+    const result = text(value, 'Evidence relationship basis', MAX_RESPONSE_RATIONALE_LENGTH).trim();
+    if (!result)
+        throw new TypeError('Explain the evidence relationship.');
+    return result;
+}
+export function readCaseEvidenceLinks(value) {
+    if (value === undefined)
+        return undefined;
+    assertWorkspaceInputGraph(value, 'Evidence relationships');
+    const links = array(value, 'Evidence relationships', MAX_CASE_EVIDENCE_LINKS).map(raw => {
+        const row = exactOptional(raw, ['id', 'fromPinId', 'toPinId', 'kind', 'basis', 'createdAt'], ['withdrawal'], 'Evidence relationship');
+        const fromPinId = identifier(row.fromPinId), toPinId = identifier(row.toPinId);
+        if (fromPinId === toPinId)
+            throw new TypeError('An evidence pin cannot derive from or share a source with itself.');
+        iso(row.createdAt, 'Relationship recording time');
+        let withdrawal;
+        if (row.withdrawal !== undefined) {
+            const item = exact(row.withdrawal, ['at', 'reason'], 'Relationship withdrawal');
+            iso(item.at, 'Withdrawal time');
+            if (Date.parse(item.at) < Date.parse(row.createdAt))
+                throw new TypeError('Withdrawal precedes the relationship.');
+            withdrawal = { at: item.at, reason: explanation(item.reason) };
+        }
+        return { id: identifier(row.id), fromPinId, toPinId,
+            kind: enumeration(row.kind, CASE_EVIDENCE_LINK_KINDS, 'Evidence relationship kind'),
+            basis: explanation(row.basis), createdAt: row.createdAt, ...(withdrawal ? { withdrawal } : {}) };
+    });
+    if (new Set(links.map(link => link.id)).size !== links.length)
+        throw new TypeError('Evidence relationship identities must be unique.');
+    return links;
+}
+function derivationGraph(links) {
+    const graph = new Map();
+    for (const link of links)
+        if (!link.withdrawal && link.kind === 'derived_from') {
+            const neighbours = graph.get(link.fromPinId) ?? [];
+            neighbours.push(link.toPinId);
+            graph.set(link.fromPinId, neighbours);
+        }
+    return graph;
+}
+function reaches(graph, from, to) {
+    const pending = [from], visited = new Set();
+    while (pending.length) {
+        const id = pending.pop();
+        if (id === to)
+            return true;
+        if (visited.has(id))
+            continue;
+        visited.add(id);
+        pending.push(...(graph.get(id) ?? []));
+    }
+    return false;
+}
+export function appendCaseEvidenceLink(current, input, pins, now) {
+    const row = exact(input, ['fromPinId', 'toPinId', 'kind', 'basis'], 'New evidence relationship');
+    const link = readCaseEvidenceLinks([{ ...row, id: freshId('evidence-link'), createdAt: now }])[0];
+    const ids = new Set(pins.map(pin => pin.id));
+    if (!ids.has(link.fromPinId) || !ids.has(link.toPinId))
+        throw new TypeError('Select two retained evidence pins.');
+    if (current.some(item => !item.withdrawal && item.kind === link.kind
+        && ((item.fromPinId === link.fromPinId && item.toPinId === link.toPinId)
+            || (link.kind === 'shared_source' && item.fromPinId === link.toPinId && item.toPinId === link.fromPinId)))) {
+        throw new TypeError('This evidence relationship is already recorded. Withdraw it before recording a replacement.');
+    }
+    if (link.kind === 'derived_from' && reaches(derivationGraph(current), link.toPinId, link.fromPinId))
+        throw new TypeError('This derivation would create a cycle. Review the existing links first.');
+    return readCaseEvidenceLinks([...current, link]);
+}
+export function withdrawCaseEvidenceLink(current, input, now) {
+    const row = exact(input, ['id', 'reason'], 'Evidence relationship withdrawal');
+    const id = identifier(row.id), existing = current.find(link => link.id === id);
+    if (!existing || existing.withdrawal)
+        throw new TypeError('This relationship is missing or already withdrawn. Refresh before reviewing it.');
+    return readCaseEvidenceLinks(current.map(link => link.id === id ? { ...link, withdrawal: { at: now, reason: explanation(row.reason) } } : link));
+}
+/** Keep unresolved references; an imported pin can have been omitted by its source. */
+export function mergeCaseEvidenceLinks(local, incoming) {
+    if (local === undefined && incoming === undefined)
+        return undefined;
+    const merged = new Map((readCaseEvidenceLinks(local) ?? []).map(link => [link.id, link]));
+    for (const link of readCaseEvidenceLinks(incoming) ?? []) {
+        const existing = merged.get(link.id);
+        if (!existing) {
+            merged.set(link.id, link);
+            continue;
+        }
+        const { withdrawal: left, ...a } = existing, { withdrawal: right, ...b } = link;
+        if (JSON.stringify(a) !== JSON.stringify(b) || (left && right && JSON.stringify(left) !== JSON.stringify(right))) {
+            throw new TypeError('An imported evidence relationship conflicts with retained provenance. No relationship was overwritten.');
+        }
+        merged.set(link.id, { ...a, ...((left ?? right) ? { withdrawal: left ?? right } : {}) });
+    }
+    return readCaseEvidenceLinks([...merged.values()].sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+}
+export function caseEvidenceLinkIssues(links, pins) {
+    const ids = new Set(pins.map(pin => pin.id));
+    const graph = derivationGraph(links);
+    return links.map(link => ({ link,
+        missingPinIds: [link.fromPinId, link.toPinId].filter(id => !ids.has(id)),
+        cyclic: !link.withdrawal && link.kind === 'derived_from' && reaches(graph, link.toPinId, link.fromPinId),
+    }));
+}
+/** Matching context is disclosed, never counted as independent corroboration. */
+export function caseEvidenceSharedContext(pins) {
+    const groups = new Map();
+    function add(kind, identity, label, id) {
+        if (!identity?.trim())
+            return;
+        const key = JSON.stringify([kind, identity]);
+        const group = groups.get(key) ?? { kind, label, pinIds: [] };
+        group.pinIds.push(id);
+        groups.set(key, group);
+    }
+    for (const pin of pins) {
+        add('checkpoint', pin.checkpointId, 'Same collection checkpoint', pin.id);
+        add('import', pin.importContentSha256, 'Same imported content', pin.id);
+        add('source', pin.source, `Same declared source: ${pin.source}`, pin.id);
+    }
+    return [...groups.values()].filter(group => group.pinIds.length > 1);
+}

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

@@ -1,12 +1,13 @@
 // Pure, framework-neutral analyst-case records, evidence histories, bounded
 // record normalization, and analyst updates.
-import { normalizeHttpSummary } from "./http-summary.mjs";
-import { normalizeOpportunityModelVersion } from "../../lib/opportunity-scoring.mjs";
-import { normalizeRiskModelVersion } from "../../lib/risk-scoring.mjs";
+import { httpSummaryFieldIsObserved, normalizeHttpSummary } from "./http-summary.mjs";
+import { normalizeOpportunityModelVersion } from "../analysis/opportunity-scoring.mjs";
+import { normalizeRiskModelVersion } from "../analysis/risk-scoring.mjs";
 import { latestObservationCohort } from "../evidence/latest-observations.mjs";
 import { normalizeExplicitIsoTimestamp } from "../evidence/observation.mjs";
-import { PUBLISHED_V2_3_CASE_SCHEMA_VERSION } from "../contracts/case-portability.mjs";
+import { EVIDENCE_FOLLOW_UP_CASE_SCHEMA_VERSION, PUBLISHED_V2_3_CASE_SCHEMA_VERSION } from "../contracts/case-portability.mjs";
 import { validWebObservationMode } from "../evidence/lookup-target.mjs";
+import { normalizeWebCollectionQuality, webCollectionAllowsComparison } from "../evidence/collection-quality.mjs";
 import { 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, } from "./case-record-contracts.mjs";
 import { CONCLUSIVE_AVAILABILITY, DEFAULT_EVIDENCE_SOURCE, EVIDENCE_SOURCE_RANK, EVIDENCE_SOURCE_SET, REGISTERED_LIKE, caseTimestampOrNull, hashString, isoOrNull, normalizeEvidenceHostnameForCase, objectRecord, safeId, } from "./case-record-core.mjs";
 function evidenceString(value, max = MAX_EVIDENCE_STRING_LENGTH) {
@@ -122,6 +123,7 @@ const MATERIAL_FIELD_ORDER = [
     'observationHostname',
     'webObservationMode',
     'scanDepth',
+    'webCollectionQuality',
     'availability', 'confidence', 'riskModelVersion', 'riskScore', 'opportunityModelVersion', 'opportunityScore',
     'riskFactors', 'opportunityFactors',
     'registrar', 'createdDate', 'expiryDate', 'nameservers',
@@ -174,7 +176,7 @@ function isEmptyMaterial(value) {
 }
 // Fields that describe the capture rather than assert evidence, so they never
 // on their own keep an otherwise-empty snapshot alive.
-const NON_EVIDENCE_MATERIAL = new Set(['inputHostname', 'observationHostname', 'webObservationMode', 'scanDepth', 'confidence']);
+const NON_EVIDENCE_MATERIAL = new Set(['inputHostname', 'observationHostname', 'webObservationMode', 'scanDepth', 'webCollectionQuality', 'confidence']);
 // A snapshot with no material evidence (only timestamps/source/depth, or only a
 // bare confidence/unknown-availability) is dropped rather than added to a
 // timeline.
@@ -194,7 +196,7 @@ function canonicalMaterialString(snapshot, legacyOrder = false) {
         const value = materialValue(field, snapshot, legacyOrder);
         // Optional collection context does not alter historical fingerprints when
         // absent; recorded context separates otherwise-identical captures.
-        if ((field === 'inputHostname' || field === 'observationHostname' || field === 'webObservationMode') && value === null)
+        if ((field === 'inputHostname' || field === 'observationHostname' || field === 'webObservationMode' || field === 'webCollectionQuality') && value === null)
             continue;
         canonical[field] = value;
     }
@@ -231,6 +233,10 @@ function buildSnapshot(raw, options) {
     const legacyOrder = historicalSchema || (record.factorOrder === undefined && typeof record.fingerprint === 'string');
     const scanDepth = normalizeScanDepth(record.scanDepth);
     const httpSummary = normalizeHttpSummary(record);
+    const webCollectionQuality = normalizeWebCollectionQuality(record.webCollectionQuality, scanDepth);
+    if (webCollectionQuality && options.sourceVersion != null && options.sourceVersion < EVIDENCE_FOLLOW_UP_CASE_SCHEMA_VERSION) {
+        throw new TypeError('Web collection quality requires Case schema 17 or later; historical evidence was not reinterpreted.');
+    }
     const acceptsProfileContext = options.sourceVersion === undefined || Number(options.sourceVersion) >= 12;
     const acceptsInputHostname = options.sourceVersion === undefined || Number(options.sourceVersion) >= 13;
     const acceptsObservationHostname = options.sourceVersion === undefined || Number(options.sourceVersion) > PUBLISHED_V2_3_CASE_SCHEMA_VERSION;
@@ -248,6 +254,7 @@ function buildSnapshot(raw, options) {
         ...(observationHostname ? { observationHostname } : {}),
         ...(acceptsObservationHostname && scanDepth !== 'fast' && record.webObservationMode === 'selected_url' ? { webObservationMode: record.webObservationMode } : {}),
         scanDepth,
+        ...(webCollectionQuality ? { webCollectionQuality } : {}),
         availability: evidenceString(record.availability),
         confidence: evidenceString(record.confidence),
         riskModelVersion: normalizeRiskModelVersion(record.riskModelVersion),
@@ -300,6 +307,12 @@ function buildSnapshot(raw, options) {
         fields.riskModelVersion = null;
     if (fields.opportunityScore === null && fields.opportunityFactors.length === 0)
         fields.opportunityModelVersion = null;
+    if (webCollectionQuality) {
+        for (const field of ['hasPasswordField', 'hasExternalFormAction', 'pageBaselineMatch', 'faviconMatch', 'faviconNearMatch', 'reusesOfficialAssets']) {
+            if (fields[field] === false && !webCollectionAllowsComparison(field, webCollectionQuality, scanDepth))
+                fields[field] = null;
+        }
+    }
     // A fast capture never evaluates the deep signals, so any value supplied for
     // them (e.g. a profile's default `false`) is discarded as unevaluated.
     if (scanDepth === 'fast') {
@@ -404,6 +417,11 @@ function compareSnapshotChrono(a, b) {
  * @returns {CaseEvidenceSnapshot[]}
  */
 export function normalizeEvidenceHistory(rawList, options = {}) {
+    const ordered = [...evidenceByMaterial(rawList, options).values()].sort(compareSnapshotChrono);
+    const kept = ordered.slice(Math.max(0, ordered.length - MAX_EVIDENCE_SNAPSHOTS_PER_CASE));
+    return assignUniqueSnapshotIds(kept);
+}
+function evidenceByMaterial(rawList, options) {
     const list = Array.isArray(rawList) ? rawList : [];
     const byMaterial = new Map();
     for (const raw of list) {
@@ -415,9 +433,24 @@ export function normalizeEvidenceHistory(rawList, options = {}) {
         // collision can never merge two genuinely different snapshots.
         byMaterial.set(built.material, existing ? mergeDuplicateSnapshots(existing, built.snapshot) : built.snapshot);
     }
-    const ordered = [...byMaterial.values()].sort(compareSnapshotChrono);
-    const kept = ordered.slice(Math.max(0, ordered.length - MAX_EVIDENCE_SNAPSHOTS_PER_CASE));
-    return assignUniqueSnapshotIds(kept);
+    return byMaterial;
+}
+/** Imports add observations without evicting existing local material. Ordinary
+ * collection still uses the newest-history policy in normalizeEvidenceHistory. */
+export function mergeImportedEvidenceHistory(local, imported, caseDomain) {
+    const options = { source: 'import', fallback: null, caseDomain };
+    const retained = evidenceByMaterial(normalizeEvidenceHistory(local, options), options);
+    let omitted = 0;
+    for (const [material, incoming] of evidenceByMaterial(imported, options)) {
+        const existing = retained.get(material);
+        if (existing)
+            retained.set(material, mergeDuplicateSnapshots(existing, incoming));
+        else if (retained.size < MAX_EVIDENCE_SNAPSHOTS_PER_CASE)
+            retained.set(material, incoming);
+        else
+            omitted += 1;
+    }
+    return { records: assignUniqueSnapshotIds([...retained.values()].sort(compareSnapshotChrono)), omitted };
 }
 function assignUniqueSnapshotIds(snapshots) {
     const used = new Set();
@@ -455,6 +488,13 @@ export function latestCaseEvidence(record) {
 }
 /** Chronological presentation and comparison admission shared by the browser and Case report. */
 export function caseEvidenceTimeline(history) {
+    return buildEvidenceTimeline(history, true);
+}
+/** Reproduce published report fields only; not current analyst comparisons. */
+export function publishedCaseEvidenceTimelineForVerification(history) {
+    return buildEvidenceTimeline(history, false);
+}
+function buildEvidenceTimeline(history, enforceCollectionQuality) {
     const dated = (history ?? []).map((snapshot) => ({
         snapshot,
         at: normalizeExplicitIsoTimestamp(snapshot.capturedAt),
@@ -475,10 +515,10 @@ export function caseEvidenceTimeline(history) {
                 ? 'Equal-time snapshots have no unique before-and-after order; no temporal change is inferred.'
                 : null;
         const comparable = previous && !orderingLimitation;
-        const changes = comparable ? compareCaseEvidence(previous.snapshot, snapshot) : [];
+        const changes = comparable ? compareEvidence(previous.snapshot, snapshot, enforceCollectionQuality) : [];
         const incomparableReasons = orderingLimitation
             ? ['other']
-            : comparable ? caseEvidenceIncomparableReasons(previous.snapshot, snapshot) : [];
+            : comparable ? incomparableReasonsForEvidence(previous.snapshot, snapshot, enforceCollectionQuality) : [];
         if (comparable && !changes.length && !incomparableReasons.length
             && canonicalMaterialString(previous.snapshot) !== canonicalMaterialString(snapshot))
             incomparableReasons.push('other');
@@ -562,6 +602,13 @@ function opportunityModelComparable(previous, current) {
 function valuesMateriallyEqual(field, previous, current) {
     return JSON.stringify(materialValue(field, previous)) === JSON.stringify(materialValue(field, current));
 }
+function collectionFieldComparable(field, snapshot) {
+    if (field === 'registrar' || field === 'createdDate' || field === 'expiryDate')
+        return isPresent(snapshot[field]);
+    return field.startsWith('http')
+        ? httpSummaryFieldIsObserved(field, snapshot)
+        : webCollectionAllowsComparison(field, snapshot.webCollectionQuality, snapshot.scanDepth);
+}
 /**
  * Explains material fields that comparison gates deliberately suppress. The
  * reasons are stable machine values for UI/report wording; they are not risk
@@ -569,14 +616,27 @@ function valuesMateriallyEqual(field, previous, current) {
  * in the same observation produced an ordinary material change.
  * @param {CaseEvidenceSnapshot | null | undefined} previous
  * @param {CaseEvidenceSnapshot | null | undefined} current
- * @returns {Array<'observation-context' | 'opportunity-model' | 'scan-depth' | 'risk-model'>}
+ * @returns {Array<'observation-context' | 'opportunity-model' | 'scan-depth' | 'risk-model' | 'collection-quality'>}
  */
 export function caseEvidenceIncomparableReasons(previous, current) {
+    return incomparableReasonsForEvidence(previous, current, true);
+}
+function incomparableReasonsForEvidence(previous, current, enforceCollectionQuality) {
     if (!previous || !current || previous.fingerprint === current.fingerprint)
         return [];
     const reasons = [];
     if (!sameObservationContext(previous, current))
         reasons.push('observation-context');
+    const missingRegistrationValue = ['registrar', 'createdDate', 'expiryDate'].some(field => !valuesMateriallyEqual(field, previous, current) && (!isPresent(previous[field]) || !isPresent(current[field])));
+    const incompleteWebFields = previous.scanDepth === 'deep' && current.scanDepth === 'deep'
+        && (JSON.stringify(previous.webCollectionQuality) !== JSON.stringify(current.webCollectionQuality)
+            || COMPARE_FIELDS.some(spec => (spec.modelGate !== 'risk' || riskModelComparable(previous, current))
+                && (spec.modelGate !== 'opportunity' || opportunityModelComparable(previous, current))
+                && !valuesMateriallyEqual(spec.field, previous, current)
+                && (!collectionFieldComparable(spec.field, previous)
+                    || !collectionFieldComparable(spec.field, current))));
+    if (enforceCollectionQuality && (missingRegistrationValue || incompleteWebFields))
+        reasons.push('collection-quality');
     const hasRiskEvidence = previous.riskScore !== null || current.riskScore !== null
         || previous.riskFactors.length > 0 || current.riskFactors.length > 0;
     if (hasRiskEvidence && !riskModelComparable(previous, current))
@@ -763,6 +823,9 @@ function compareField(spec, before, after) {
  * @returns {Array<{ field: string, label: string, before: unknown, after: unknown, tone: string }>}
  */
 export function compareCaseEvidence(previous, current) {
+    return compareEvidence(previous, current, true);
+}
+function compareEvidence(previous, current, enforceCollectionQuality) {
     if (!previous || !current)
         return [];
     const bothDeep = previous.scanDepth === 'deep' && current.scanDepth === 'deep';
@@ -785,6 +848,9 @@ export function compareCaseEvidence(previous, current) {
             continue;
         if (spec.modelGate === 'opportunity' && !comparableOpportunityModel)
             continue;
+        if (enforceCollectionQuality && (!collectionFieldComparable(spec.field, previous)
+            || !collectionFieldComparable(spec.field, current)))
+            continue;
         const result = compareField(spec, previous[spec.field], current[spec.field]);
         if (result) {
             changes.push({ field: spec.field, label: spec.label, before: result.before, after: result.after, tone: result.tone });

package/packages/cases/case-evidence-quality.mjs

@@ -0,0 +1,5 @@
+/** Collection completeness does not establish a usable date, comparison or conclusion. */
+export function casePinHasCompleteObservation(pin) {
+    return pin.completeness === 'complete' && !pin.truncated
+        && ['complete', 'success', 'reviewed', 'not_found'].includes(pin.sourceState ?? '');
+}

package/packages/cases/case-export-input.mjs

@@ -1,14 +1,16 @@
-import { boundedJsonLimitsForBytes, parseBoundedJsonObject } from "../../lib/bounded-json.mjs";
+import { boundedJsonLimitsForBytes, parseBoundedJsonObject } from "../analysis/bounded-json.mjs";
 import { canonicalArtifactJsonV2 } from "../evidence/artifact-integrity.mjs";
 import { normalizeExplicitIsoTimestamp } from "../evidence/observation.mjs";
-import { CASE_SCHEMA_VERSION, CLI_CASE_PACK_INPUT_CASE_VERSIONS, MAX_CASE_STORE_BYTES, MAX_EDITABLE_CASE_INPUT_BYTES, PUBLISHED_V2_3_CASE_SCHEMA_VERSION } from "../contracts/case-portability.mjs";
+import { CASE_SCHEMA_VERSION, CLI_CASE_PACK_INPUT_CASE_VERSIONS, MAX_CASE_STORE_BYTES, MAX_EDITABLE_CASE_INPUT_BYTES, PUBLISHED_V2_3_CASE_SCHEMA_VERSION, EVIDENCE_FOLLOW_UP_CASE_SCHEMA_VERSION } from "../contracts/case-portability.mjs";
 import { normalizeCaseStore } from "./case-migration-model.mjs";
 import { serializeCaseStore } from "./case-storage-model.mjs";
 /** Historical wire shape remains independent of current in-memory defaults. */
 export function canonicalCaseExportProjection(cases, caseVersion) {
-    if (caseVersion !== PUBLISHED_V2_3_CASE_SCHEMA_VERSION)
-        return [...cases];
-    return cases.map((value) => {
+    return cases.map((record) => {
+        const { workflowMetadata: _workflow, ...historical } = record;
+        const value = caseVersion < EVIDENCE_FOLLOW_UP_CASE_SCHEMA_VERSION ? historical : record;
+        if (caseVersion !== PUBLISHED_V2_3_CASE_SCHEMA_VERSION)
+            return value;
         if ([...value.evidencePins, ...value.sightings].some((item) => item.observedAt === null)) {
             throw new TypeError('The published Case 15 format requires a known observation time on each retained pin and sighting.');
         }

package/packages/cases/case-incident-context.mjs

@@ -0,0 +1,52 @@
+// Pure incident context parsing and retention projection; no storage or Case mutation.
+import { canonicalRegistrableDomain } from "../analysis/registrable-domain.mjs";
+import { MAX_CASE_OBJECTIVE_LENGTH } from "../contracts/case-portability.mjs";
+import { parseCredentialFreeHttpUrl } from "../evidence/lookup-target.mjs";
+export const MAX_CASE_INCIDENT_URL_LENGTH = 1_850;
+function boundedContextText(value, maximum) {
+    return typeof value === 'string'
+        ? value.replace(/[\u0000-\u001f\u007f]/gu, ' ').replace(/\s+/gu, ' ').trim().slice(0, maximum)
+        : '';
+}
+export function normalizeCaseObjective(value) {
+    return boundedContextText(value, MAX_CASE_OBJECTIVE_LENGTH);
+}
+export function parseIncidentUrlContext(value) {
+    const parsed = parseCredentialFreeHttpUrl(value, MAX_CASE_INCIDENT_URL_LENGTH);
+    if (!parsed)
+        return null;
+    const hostname = parsed.hostname.toLowerCase().replace(/\.$/u, '');
+    const registrableDomain = canonicalRegistrableDomain(hostname);
+    if (!registrableDomain)
+        return null;
+    const exactUrl = parsed.toString();
+    if (exactUrl.length > MAX_CASE_INCIDENT_URL_LENGTH)
+        return null;
+    return Object.freeze({
+        exactUrl,
+        hostname,
+        registrableDomain,
+        originUrl: parsed.origin,
+        hasPath: parsed.pathname !== '/',
+        hasQuery: Boolean(parsed.search),
+        hasFragment: Boolean(parsed.hash),
+    });
+}
+export function caseInvestigationContext(record) {
+    return record?.workflowMetadata?.investigationContext ?? null;
+}
+export function prepareCaseInvestigationContext(input) {
+    const objective = normalizeCaseObjective(input.objective);
+    if (!objective)
+        throw new Error('Enter the investigation objective before retaining Incident context.');
+    const parsed = parseIncidentUrlContext(input.incidentUrl);
+    if (!parsed)
+        throw new Error(`Enter one absolute HTTP(S) Incident URL of at most ${MAX_CASE_INCIDENT_URL_LENGTH} characters without credentials.`);
+    const retention = input.retainExactUrl ? 'exact' : 'origin_only';
+    const retainedUrl = input.retainExactUrl ? parsed.exactUrl : parsed.originUrl;
+    return Object.freeze({
+        objective,
+        incidentUrl: retainedUrl,
+        urlRetention: retention,
+    });
+}

package/packages/cases/case-markdown.mjs

@@ -0,0 +1,11 @@
+/** Keep untrusted Case prose literal, including block syntax and GFM autolinks. */
+export function escapeCaseMarkdownInline(text) {
+    return String(text)
+        .replace(/[\r\n\u2028\u2029]+/g, ' ')
+        .replace(/([\\`*_{}\[\]<>()#+!|~])/g, '\\$1')
+        .replace(/^(\s*)([-=]+)(?=\s|$)/u, '$1\\$2')
+        .replace(/^(\s*\d+)\.(?=\s)/u, '$1\\.')
+        // Break automatic links without altering the underlying evidence value.
+        .replace(/\b([a-z][a-z0-9+.-]{1,31}):(?=\/\/)/gi, '$1\\:')
+        .replace(/\bwww\.(?=\S)/gi, 'www\\.');
+}

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

@@ -1,11 +1,22 @@
-import { CASE_IMPORT_VERSIONS, CASE_SCHEMA_VERSION, DEFAULT_DISPOSITION, DEFAULT_SOURCE, DEFAULT_STATUS, MAX_CASES, MAX_NOTES_PER_CASE, deterministicId, caseTimestampOrNull, normalizeCase, normalizeDomain, normalizeCaseObjective, normalizeEvidenceHistory, normalizeNotes, normalizeReviewReasonCode, normalizeTags, objectRecord, safeId, isValidDisposition, isValidSource, isValidStatus, } from "./case-record-model.mjs";
+import { CASE_IMPORT_VERSIONS, CASE_SCHEMA_VERSION, MAX_CASES, MAX_NOTES_PER_CASE, } from "../contracts/case-portability.mjs";
+import { DEFAULT_DISPOSITION, DEFAULT_STATUS, isValidDisposition, isValidStatus } from "./case-record-decisions.mjs";
+import { DEFAULT_SOURCE } from "./case-record-contracts.mjs";
+import { deterministicId, caseTimestampOrNull, normalizeNotes, normalizeReviewReasonCode, normalizeTags, objectRecord, safeId, isValidSource, } from "./case-record-core.mjs";
+import { normalizeCase } from "./case-record-operations.mjs";
+import { normalizeCaseObjective } from "./case-incident-context.mjs";
+import { normalizeDomain } from "../evidence/domain-name.mjs";
+import { mergeImportedEvidenceHistory, normalizeEvidenceHistory } from "./case-evidence-model.mjs";
 import { CASE_REPORT_SCHEMA, PUBLIC_CASE_SCHEMA_VERSION, PUBLISHED_V2_3_CASE_SCHEMA_VERSION, INCIDENT_CASE_SCHEMA_VERSION, 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 { readCaseAttachments, mergeCaseAttachments } from "./case-attachment-model.mjs";
-import { assertBoundedJsonStructure } from "../../lib/bounded-json.mjs";
+import { readCaseEvidenceLinks, mergeCaseEvidenceLinks } from "./case-evidence-links.mjs";
+import { EVIDENCE_FOLLOW_UP_CASE_SCHEMA_VERSION } from "../contracts/case-portability.mjs";
+import { assertBoundedJsonStructure } from "../analysis/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, mergeCaseClosureHistories, mergeCaseObservedEffectHistories, MAX_CASE_ASSERTIONS, MAX_CASE_DECISIONS, MAX_CASE_EVIDENCE_PINS, MAX_CASE_MANUAL_TRAIL_EVENTS, MAX_CASE_SIGHTINGS, normalizeCaseActions, normalizeCaseAssertions, normalizeCaseClosureHistory, normalizeCaseDecisions, normalizeCaseEvidencePins, normalizeCaseManualTrail, normalizeCaseObservedEffectHistory, normalizeCaseSightings, } from "./case-response-model.mjs";
+import { readCaseWorkflowFields } from "./case-workflow-migration.mjs";
+import { emptyCaseWorkflowMetadata, mergeCaseWorkflowMetadata } from "./case-workflow-metadata.mjs";
 export const MAX_CASE_INPUT_RECORDS = 2_000;
 function compareCodeUnits(left, right) {
     return left < right ? -1 : left > right ? 1 : 0;
@@ -81,6 +92,8 @@ export function normalizeCaseStore(raw) {
 function assertModernCaseShape(raw, sourceVersion) {
     for (const item of boundedCaseList(raw).items) {
         const itemRecord = objectRecord(item);
+        if (sourceVersion < EVIDENCE_FOLLOW_UP_CASE_SCHEMA_VERSION && Object.hasOwn(itemRecord, 'evidenceLinks'))
+            throw new TypeError('Evidence relationships require the current Case schema.');
         if (sourceVersion < INCIDENT_CASE_SCHEMA_VERSION && Object.hasOwn(itemRecord, 'attachments')) {
             throw new TypeError('Retained file references require the current Case schema; no data was changed.');
         }
@@ -168,6 +181,8 @@ function boundedCaseList(raw) {
  */
 function extractImportPatch(raw, importedVersion) {
     const record = objectRecord(raw);
+    if (record.evidenceLinks !== undefined && importedVersion < EVIDENCE_FOLLOW_UP_CASE_SCHEMA_VERSION)
+        throw new TypeError('Evidence relationships require the current Case schema.');
     const domain = normalizeDomain(record.domain);
     if (!domain)
         return null;
@@ -204,6 +219,9 @@ function extractImportPatch(raw, importedVersion) {
         [record.sightings, sightings],
     ].reduce((total, [candidates, retained]) => total
         + Math.max(0, (Array.isArray(candidates) ? candidates.length : 0) - retained.length), 0);
+    const workflow = readCaseWorkflowFields(record, domain, assertions, importedVersion);
+    const hasWorkflow = record.workflowMetadata !== undefined || workflow.workflowMetadata.types.length > 0
+        || workflow.workflowMetadata.incidentTargets.length > 0 || workflow.workflowMetadata.investigationContext !== null;
     return {
         domain,
         rawId: typeof record.id === 'string' ? record.id : null,
@@ -235,7 +253,9 @@ function extractImportPatch(raw, importedVersion) {
             ? normalizeCaseInvestigationBranches(record.branches, normalizedFallback, branchReferences, timestampOptions)
             : [],
         attachments: importedVersion >= INCIDENT_CASE_SCHEMA_VERSION ? readCaseAttachments(record.attachments) : undefined,
-        tags: normalizeTags(record.tags),
+        evidenceLinks: readCaseEvidenceLinks(record.evidenceLinks),
+        tags: workflow.tags,
+        workflowMetadata: hasWorkflow ? workflow.workflowMetadata : undefined,
         // 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
@@ -245,16 +265,6 @@ function extractImportPatch(raw, 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));
-}
 function retainLocalAuthoredRecords(local, imported, maximum) {
     const records = [...local];
     const retainedIds = new Set(records.map((item) => item.id));
@@ -271,13 +281,6 @@ function retainLocalAuthoredRecords(local, imported, maximum) {
     }
     return { records, omitted };
 }
-// 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 {
@@ -289,6 +292,7 @@ function caseFromPatch(patch, now) {
         reviewReasonCode: patch.reviewReasonCode ?? null,
         brandProfileIds: patch.brandProfileIds,
         tags: patch.tags,
+        workflowMetadata: patch.workflowMetadata ?? emptyCaseWorkflowMetadata(),
         notes: patch.notes,
         source: patch.source ?? DEFAULT_SOURCE,
         evidenceHistory: patch.evidenceHistory,
@@ -302,6 +306,7 @@ function caseFromPatch(patch, now) {
         closures: patch.closures,
         branches: patch.branches,
         ...(patch.attachments === undefined ? {} : { attachments: patch.attachments }),
+        ...(patch.evidenceLinks === undefined ? {} : { evidenceLinks: patch.evidenceLinks }),
         createdAt: patch.createdAt || patch.updatedAt || now,
         updatedAt: patch.updatedAt || patch.createdAt || now,
     };
@@ -318,6 +323,8 @@ function caseFromPatch(patch, now) {
 function applyImportPatch(local, patch) {
     const importNewer = patch.updatedAt !== null && Date.parse(patch.updatedAt) > Date.parse(local.updatedAt);
     const fallback = patch.updatedAt || local.updatedAt;
+    const noteSelection = retainLocalAuthoredRecords(local.notes, patch.notes, MAX_NOTES_PER_CASE);
+    const historySelection = mergeImportedEvidenceHistory(local.evidenceHistory, patch.evidenceHistory, local.domain);
     const pinSelection = retainLocalAuthoredRecords(local.evidencePins, patch.evidencePins, MAX_CASE_EVIDENCE_PINS);
     const evidencePins = normalizeCaseEvidencePins(pinSelection.records, fallback);
     const pinIds = new Set(evidencePins.map((item) => item.id));
@@ -336,7 +343,9 @@ function applyImportPatch(local, patch) {
     const trailSelection = retainLocalAuthoredRecords(local.manualTrail, patch.manualTrail, MAX_CASE_MANUAL_TRAIL_EVENTS);
     const manualTrail = normalizeCaseManualTrail(trailSelection.records, fallback);
     const attachments = mergeCaseAttachments(local.attachments, patch.attachments);
+    const evidenceLinks = mergeCaseEvidenceLinks(local.evidenceLinks, patch.evidenceLinks);
     const authoredHistoryOmitted = patch.authoredHistoryOmitted
+        + noteSelection.omitted
         + pinSelection.omitted
         + decisionSelection.omitted
         + assertionSelection.omitted
@@ -350,7 +359,7 @@ function applyImportPatch(local, patch) {
             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),
+            evidenceHistory: historySelection.records,
             evidencePins,
             decisions,
             actions,
@@ -361,11 +370,15 @@ function applyImportPatch(local, patch) {
             closures,
             branches: mergeCaseInvestigationBranches(local.branches ?? [], patch.branches, fallback, branchReferences),
             ...(attachments === undefined ? {} : { attachments }),
+            ...(evidenceLinks === undefined ? {} : { evidenceLinks }),
             tags: normalizeTags([...local.tags, ...patch.tags]),
-            notes: unionNotes(local.notes, patch.notes),
+            workflowMetadata: patch.workflowMetadata === undefined
+                ? local.workflowMetadata ?? emptyCaseWorkflowMetadata()
+                : mergeCaseWorkflowMetadata(local.workflowMetadata ?? emptyCaseWorkflowMetadata(), patch.workflowMetadata, importNewer, local.domain),
+            notes: normalizeNotes(noteSelection.records, fallback),
             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, authoredHistoryOmitted };
+        }, brandProfileReferencesOmitted: brandProfileReferences.omitted, authoredHistoryOmitted, evidenceHistoryOmitted: historySelection.omitted };
 }
 function pickFreeId(preferred, domain, used) {
     const wanted = safeId(preferred);
@@ -478,7 +491,7 @@ function caseCollectionImportEnvelope(importedRaw) {
  * reinterpreted.
  * @param {CaseRecord[]} localCases
  * @param {unknown} importedRaw
- * @returns {{ cases: CaseRecord[], added: number, updated: number, skipped: number, brandProfileReferencesOmitted: number, authoredHistoryOmitted: number }}
+ * @returns {{ cases: CaseRecord[], added: number, updated: number, skipped: number, brandProfileReferencesOmitted: number, authoredHistoryOmitted: number, evidenceHistoryOmitted: number }}
  */
 export function mergeCases(localCases, importedRaw) {
     assertBoundedJsonStructure(importedRaw, 'Case import', CASE_INPUT_JSON_LIMITS);
@@ -507,6 +520,7 @@ export function mergeCases(localCases, importedRaw) {
     let skipped = imported.omitted;
     let brandProfileReferencesOmitted = 0;
     let authoredHistoryOmitted = 0;
+    let evidenceHistoryOmitted = 0;
     const fallback = new Date(0).toISOString();
     const importedIds = new Set();
     for (const item of imported.items) {
@@ -539,6 +553,7 @@ export function mergeCases(localCases, importedRaw) {
             byId.set(existing.id, merged.record);
             brandProfileReferencesOmitted += patch.brandProfileReferencesOmitted + merged.brandProfileReferencesOmitted;
             authoredHistoryOmitted += merged.authoredHistoryOmitted;
+            evidenceHistoryOmitted += merged.evidenceHistoryOmitted;
             updated += 1;
         }
         else if (byId.size < MAX_CASES) {
@@ -561,5 +576,6 @@ export function mergeCases(localCases, importedRaw) {
         skipped,
         brandProfileReferencesOmitted,
         authoredHistoryOmitted,
+        evidenceHistoryOmitted,
     };
 }