@slicedearth/whoisleuth-cli 2.4.0 → 2.5.1

package/packages/cases/case-response-packet-render.mjs

@@ -1,7 +1,5 @@
 import { RESPONSE_AUTHORISATION_CONFIRMATION_IDS, responseContactLabel as contactLabel } from "./case-response-packet-vocabulary.mjs";
-function escapeMarkdown(value) {
-    return value.replace(/([\\`*_[\]<>|])/gu, '\\$1').replace(/\r?\n/gu, ' ');
-}
+import { escapeCaseMarkdownInline as escapeMarkdown } from "./case-markdown.mjs";
 /** Render only the projected packet, never the source Case or private inputs. */
 export function renderCaseResponsePacket(packet) {
     const { profile, case: caseRecord, incident: { category, affectedParty, abusiveUrls, observedHarm, observedAt }, generatedAt: normalizedGeneratedAt, recipientRoute, escalationHistory, escalationHistoryOmitted, escalationHistoryLimitations, authorisation, readiness, selectedEvidence, artefactReferences, responseLifecycle, preflight, provenance: { limitations, evidencePinCount, decisionCount, assertionCount, observationAge: age }, integrity: { digestSha256 }, } = packet;
@@ -49,10 +47,16 @@ export function renderCaseResponsePacket(packet) {
                 ...(action.providerOutcome ? [`  - Typed provider outcome: ${escapeMarkdown(action.providerOutcome.replaceAll('_', ' '))}`] : []),
                 ...(action.outcomeDetail ? [`  - Outcome detail: ${escapeMarkdown(action.outcomeDetail)}`] : []),
                 ...(action.originActionId ? [`  - Originating action: ${escapeMarkdown(action.originActionId)}`] : []),
+                ...(action.amendment ? [`  - Amendment of submitted packet SHA-256: ${action.amendment.packetDigestSha256}`, `  - Prepared request events: ${action.amendment.requestEventIds.map(escapeMarkdown).join(', ')}`] : []),
                 ...action.transitions.flatMap((event) => [
                     `  - ${event.occurredAt}: ${escapeMarkdown(event.previousState ?? 'none')} → ${escapeMarkdown(event.nextState)} · ${escapeMarkdown(event.sourceClass)} · ${escapeMarkdown(event.provenance)}${event.providerOutcome ? ` · ${escapeMarkdown(event.providerOutcome.replaceAll('_', ' '))}` : ''}${event.applied ? '' : ' · retained conflict'}`,
                     ...(event.reference ? [`    - Reference: ${escapeMarkdown(event.reference)}`] : []),
                     ...(event.evidencePinId ? [`    - Evidence pin: ${escapeMarkdown(event.evidencePinId)}`] : []),
+                    ...(event.evidenceRequest ? [
+                        `    - Requested evidence (${event.evidenceRequest.state}): ${escapeMarkdown(event.evidenceRequest.summary)}`,
+                        `    - Original packet SHA-256: ${event.evidenceRequest.packetDigestSha256}; deadline: ${event.evidenceRequest.dueAt ?? 'not provided'}`,
+                        `    - Prepared pins: ${event.evidenceRequest.evidencePinIds.map(escapeMarkdown).join(', ') || 'none'}${event.evidenceRequest.rationale ? `; ${escapeMarkdown(event.evidenceRequest.rationale)}` : ''}`,
+                    ] : []),
                     ...(event.originActionId ? [`    - Originating action: ${escapeMarkdown(event.originActionId)}`] : []),
                     ...event.limitations.map((limitation) => `    - Limitation: ${escapeMarkdown(limitation)}`),
                 ]),
@@ -136,12 +140,12 @@ export function renderCaseResponsePacket(packet) {
         `Reviewed packet SHA-256: ${digestSha256}`,
         'Attach the reviewed packet (and any separately reviewed evidence files) through the recipient’s approved submission channel; this message does not embed or transmit attachments.',
         '',
-        responseLifecycle.latestProviderOutcome
-            ? `Provider outcome time: ${responseLifecycle.latestProviderOutcome.occurredAt} (${responseLifecycle.latestProviderOutcome.outcome.replaceAll('_', ' ')})`
-            : `Provider outcome time: Withheld because the typed event state is ${responseLifecycle.providerOutcomeState}.`,
-        responseLifecycle.latestObservedChangeAt
-            ? `Independently observed change time: ${responseLifecycle.latestObservedChangeAt}`
-            : `Independently observed change time: Withheld because the independent change state is ${responseLifecycle.observedChangeState}.`,
+        ...(responseLifecycle.latestProviderOutcome
+            ? [`Provider outcome time: ${responseLifecycle.latestProviderOutcome.occurredAt} (${responseLifecycle.latestProviderOutcome.outcome.replaceAll('_', ' ')})`]
+            : []),
+        ...(responseLifecycle.latestObservedChangeAt
+            ? [`Independently observed change time: ${responseLifecycle.latestObservedChangeAt}`]
+            : []),
         '',
         'Please review this report under the applicable abuse and acceptable-use policies.',
         '',

package/packages/cases/case-response-packet.mjs

@@ -2,21 +2,21 @@ import { renderCaseResponsePacket } from "./case-response-packet-render.mjs";
 import { responseContactLabel as contactLabel } from "./case-response-packet-vocabulary.mjs";
 // Pure abuse-evidence packet builder. It creates local review artifacts only:
 // no network requests, mailto links, submissions, or provider side effects.
-import { assertBoundedJsonStructure, } from "../../lib/bounded-json.mjs";
+import { assertPacketAmendmentSelection } from "./case-requested-evidence.mjs";
+import { assertBoundedJsonStructure, } from "../analysis/bounded-json.mjs";
 import { CASE_RESPONSE_PACKET_SCHEMA, CASE_RESPONSE_PACKET_VERSION, CASE_RESPONSE_REVIEW_INPUTS_SCHEMA, CASE_RESPONSE_REVIEW_INPUTS_VERSION, MAX_ABUSE_CATEGORY_LENGTH, MAX_ABUSIVE_URLS, MAX_AFFECTED_PARTY_LENGTH, MAX_EXACT_URL_LENGTH, MAX_RESPONSE_ACTION_HISTORY, MAX_RESPONSE_ARTEFACT_REFERENCES, MAX_RESPONSE_AUTHORISATION_CLOCK_SKEW_MS, MAX_RESPONSE_CONTRADICTIONS, MAX_RESPONSE_HARM_LENGTH, MAX_RESPONSE_SELECTED_EVIDENCE, SUPPORTED_CASE_RESPONSE_PACKET_VERSIONS, } from "../contracts/case-portability.mjs";
 import { SORTED_JSON_V2, canonicalArtifactJsonV2, } from "../evidence/artifact-integrity.mjs";
 import { normalizeExplicitIsoTimestamp, } from "../evidence/observation.mjs";
 import { latestCaseEvidence, } from "./case-evidence-model.mjs";
 import {} from "./case-model.mjs";
-import { caseDispositionSupportsDefensiveResponse, } from "./case-record-operations.mjs";
-import { buildCaseActionOutcomeSummary, buildCaseResponseLifecycleSummary, } from "./case-response-model.mjs";
+import { caseDispositionSupportsDefensiveResponse } from "./case-record-decisions.mjs";
+import { buildCaseActionOutcomeSummary, buildCaseResponseLifecycleSummary, caseActionCompletesResponseDecision, countEvidenceLinkedCaseDecisions, } from "./case-response-model.mjs";
 import { RESPONSE_AUTHORISATION_CONFIRMATION_IDS, RESPONSE_PACKET_PROFILE_IDS, RESPONSE_READINESS_STATES, } from "./case-response-packet-vocabulary.mjs";
 import { validateCaseResponseReviewInputs, } from "./case-response-review-inputs.mjs";
 import { responseRouteFreshness, } from "./response-route-freshness.mjs";
 export * from "./case-response-packet-vocabulary.mjs";
 export { validateCaseResponseReviewInputs, } from "./case-response-review-inputs.mjs";
-export { CASE_RESPONSE_PACKET_SCHEMA, CASE_RESPONSE_PACKET_VERSION, PUBLISHED_V2_2_CASE_RESPONSE_PACKET_VERSION, PUBLISHED_V2_3_CASE_RESPONSE_PACKET_VERSION, PUBLIC_CASE_RESPONSE_PACKET_VERSION, PUBLISHED_V2_CASE_RESPONSE_PACKET_VERSION, CASE_RESPONSE_REVIEW_INPUTS_SCHEMA, CASE_RESPONSE_REVIEW_INPUTS_VERSION, PUBLISHED_V2_2_CASE_RESPONSE_REVIEW_INPUTS_VERSION, PUBLISHED_V2_3_CASE_RESPONSE_REVIEW_INPUTS_VERSION, PUBLISHED_V2_CASE_RESPONSE_REVIEW_INPUTS_VERSION, MAX_ABUSE_CATEGORY_LENGTH, MAX_ABUSIVE_URLS, MAX_AFFECTED_PARTY_LENGTH, MAX_EXACT_URL_LENGTH, MAX_RESPONSE_ACTION_HISTORY, MAX_RESPONSE_ARTEFACT_REFERENCES, MAX_RESPONSE_AUTHORISATION_CLOCK_SKEW_MS, MAX_RESPONSE_CONTACTS, MAX_RESPONSE_CONTRADICTIONS, MAX_RESPONSE_HARM_LENGTH, MAX_RESPONSE_SELECTED_EVIDENCE, RESPONSE_ROUTE_STALE_AFTER_DAYS, SUPPORTED_CASE_RESPONSE_PACKET_VERSIONS, } from "../contracts/case-portability.mjs";
-export { LATEST_PUBLIC_CASE_RESPONSE_PACKET_VERSION, LATEST_PUBLIC_CASE_RESPONSE_REVIEW_INPUTS_VERSION, } from "../contracts/case-portability.mjs";
+export { CASE_RESPONSE_PACKET_SCHEMA, CASE_RESPONSE_PACKET_VERSION, PUBLISHED_V2_2_CASE_RESPONSE_PACKET_VERSION, PUBLISHED_V2_3_CASE_RESPONSE_PACKET_VERSION, PUBLIC_CASE_RESPONSE_PACKET_VERSION, PUBLISHED_V2_CASE_RESPONSE_PACKET_VERSION, CASE_RESPONSE_REVIEW_INPUTS_SCHEMA, CASE_RESPONSE_REVIEW_INPUTS_VERSION, PUBLISHED_V2_2_CASE_RESPONSE_REVIEW_INPUTS_VERSION, PUBLISHED_V2_3_CASE_RESPONSE_REVIEW_INPUTS_VERSION, LATEST_PUBLIC_CASE_RESPONSE_PACKET_VERSION, LATEST_PUBLIC_CASE_RESPONSE_REVIEW_INPUTS_VERSION, PUBLISHED_V2_CASE_RESPONSE_REVIEW_INPUTS_VERSION, MAX_ABUSE_CATEGORY_LENGTH, MAX_ABUSIVE_URLS, MAX_AFFECTED_PARTY_LENGTH, MAX_EXACT_URL_LENGTH, MAX_RESPONSE_ACTION_HISTORY, MAX_RESPONSE_ARTEFACT_REFERENCES, MAX_RESPONSE_AUTHORISATION_CLOCK_SKEW_MS, MAX_RESPONSE_CONTACTS, MAX_RESPONSE_CONTRADICTIONS, MAX_RESPONSE_HARM_LENGTH, MAX_RESPONSE_SELECTED_EVIDENCE, RESPONSE_ROUTE_STALE_AFTER_DAYS, SUPPORTED_CASE_RESPONSE_PACKET_VERSIONS, } from "../contracts/case-portability.mjs";
 export const CASE_RESPONSE_PREFLIGHT_EVIDENCE_SCOPE = Object.freeze({
     version: 1,
     owner: 'case',
@@ -218,6 +218,11 @@ function selectedPacketAction(caseRecord, input) {
         : null;
     return actionId ? caseRecord.actions.find((action) => action.id === actionId) ?? null : null;
 }
+function assertAmendmentEvidence(caseRecord, input) {
+    const action = selectedPacketAction(caseRecord, input);
+    const selected = new Set(Array.isArray(input.selectedEvidencePinIds) ? input.selectedEvidencePinIds : []);
+    assertPacketAmendmentSelection(caseRecord.actions, action?.id ?? null, new Set(caseRecord.evidencePins.filter(pin => selected.has(pin.id)).map(pin => pin.id)));
+}
 function packetActionLineage(caseRecord, input) {
     const selected = selectedPacketAction(caseRecord, input);
     if (!selected)
@@ -534,6 +539,13 @@ export function buildCaseResponsePreflight(caseRecord, input, generatedAt = new
     const observedAt = timestamp(input.observedAt);
     const normalizedGeneratedAt = timestamp(generatedAt) || new Date().toISOString();
     const binding = bindPacketRoute(caseRecord, input, normalizedGeneratedAt);
+    let amendmentError = null;
+    try {
+        assertAmendmentEvidence(caseRecord, input);
+    }
+    catch (error) {
+        amendmentError = error instanceof Error ? error.message : 'Review this amendment and its retained evidence.';
+    }
     const urls = normalizeUrls(input.abusiveUrls);
     const selectedEvidence = normalizeSelectedEvidence(caseRecord, input.selectedEvidencePinIds);
     const requiredComplete = Boolean(text(input.category, MAX_ABUSE_CATEGORY_LENGTH)
@@ -546,10 +558,9 @@ export function buildCaseResponsePreflight(caseRecord, input, generatedAt = new
         .filter((item) => item.kind === 'contradiction' && item.state === 'open')
         .length;
     const actionSummary = buildCaseActionOutcomeSummary(caseRecord.actions, normalizedGeneratedAt);
-    const retainedPinIds = new Set(caseRecord.evidencePins.map((pin) => pin.id));
-    const evidenceLinkedDecisionCount = caseRecord.decisions.filter((decision) => decision.evidencePinIds.some((evidencePinId) => retainedPinIds.has(evidencePinId))).length;
+    const evidenceLinkedDecisionCount = countEvidenceLinkedCaseDecisions(caseRecord.decisions, caseRecord.evidencePins);
     const responseDisposition = caseDispositionSupportsDefensiveResponse(caseRecord.disposition);
-    const reviewedActionCount = caseRecord.actions.filter((action) => ['reviewed', 'authorised', 'submitted', 'acknowledged', 'terminal'].includes(action.state)).length;
+    const reviewedActionCount = caseRecord.actions.filter((action) => caseActionCompletesResponseDecision(action.state)).length;
     const profile = responsePacketProfile(input.profile);
     const checks = [
         {
@@ -637,10 +648,10 @@ export function buildCaseResponsePreflight(caseRecord, input, generatedAt = new
         {
             id: 'packet_action',
             label: 'Packet action',
-            state: binding.actionBinding.state === 'selected' ? 'pass' : profile.id === 'internal_soc' ? 'caution' : 'block',
-            detail: binding.actionBinding.state === 'selected'
+            state: amendmentError ? 'block' : binding.actionBinding.state === 'selected' ? 'pass' : profile.id === 'internal_soc' ? 'caution' : 'block',
+            detail: amendmentError ?? (binding.actionBinding.state === 'selected'
                 ? `Action ${binding.actionBinding.selectedActionId} owns this packet and its retained origin lineage.`
-                : 'Select the retained Case action this packet prepares or documents.',
+                : 'Select the retained Case action this packet prepares or documents.'),
         },
         {
             id: 'action_tracking',
@@ -675,6 +686,7 @@ function normalizeActionHistory(caseRecord, input) {
             .map((action) => ({
             actionId: action.id,
             type: text(action.type, 80),
+            ...(action.amendment ? { amendment: structuredClone(action.amendment) } : {}),
             recipient: text(action.recipient, 320),
             contactSource: text(action.contactSource, 120),
             routeObservedAt: timestamp(action.routeObservedAt),
@@ -688,6 +700,7 @@ function normalizeActionHistory(caseRecord, input) {
             historyLimitations: normalizeLimitations(action.historyLimitations),
             transitions: action.history.map((event) => ({
                 id: event.id,
+                ...(event.evidenceRequest ? { evidenceRequest: structuredClone(event.evidenceRequest) } : {}),
                 previousState: event.previousState,
                 nextState: event.nextState,
                 occurredAt: event.occurredAt,
@@ -773,6 +786,7 @@ async function sha256(value) {
     return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, '0')).join('');
 }
 export function buildCaseResponseReviewInputs(caseRecord, input, generatedAt) {
+    assertAmendmentEvidence(caseRecord, input);
     const profile = buildResponsePacketProfilePreview(caseRecord, input);
     const category = text(input.category, MAX_ABUSE_CATEGORY_LENGTH);
     const selectedEvidence = normalizeSelectedEvidence(caseRecord, input.selectedEvidencePinIds);

package/packages/cases/case-response-records.mjs

@@ -1,4 +1,3 @@
-// Framework-neutral response record types and vocabulary.
 export const CASE_EVIDENCE_RELATION_STANCES = ['supports', 'contradicts', 'unresolved'];
 export const CASE_PIN_COMPLETENESS = ['complete', 'partial', 'inconclusive', 'unknown'];
 export const CASE_TRANSITION_EXPECTATIONS = ['preserve', 'change', 'review'];

package/packages/cases/case-response-review-inputs.mjs

@@ -1,8 +1,9 @@
 // Exact, bounded validation of current and published response-review inputs.
+import { readCaseEvidenceRequest, readCasePacketAmendment, assertEvidenceRequestEvent, assertEvidenceRequestHistory, assertPacketAmendmentSelection } from "./case-requested-evidence.mjs";
 import { CASE_RESPONSE_REVIEW_INPUTS_SCHEMA, MAX_ABUSE_CATEGORY_LENGTH, MAX_ABUSIVE_URLS, MAX_AFFECTED_PARTY_LENGTH, MAX_CASE_ACTIONS, MAX_CASE_ACTION_EVENTS_PER_ACTION, MAX_CASE_ACTION_EVENTS_PER_CASE, MAX_EXACT_URL_LENGTH, MAX_RESPONSE_ACTION_HISTORY, MAX_RESPONSE_ARTEFACT_REFERENCES, MAX_RESPONSE_CONTACTS, MAX_RESPONSE_CONTRADICTIONS, MAX_RESPONSE_HARM_LENGTH, MAX_RESPONSE_LIMITATIONS, MAX_RESPONSE_LIMITATION_LENGTH, MAX_RESPONSE_REFERENCE_LENGTH, MAX_RESPONSE_SELECTED_EVIDENCE, MAX_RESPONSE_VALUE_LENGTH, PUBLISHED_V2_2_CASE_RESPONSE_REVIEW_INPUTS_VERSION, PUBLISHED_V2_3_CASE_RESPONSE_REVIEW_INPUTS_VERSION, SUPPORTED_CASE_RESPONSE_REVIEW_INPUTS_VERSIONS, } from "../contracts/case-portability.mjs";
 import { CASE_ACTION_EVENT_SOURCE_CLASSES, CASE_ACTION_STATES, CASE_ACTION_TYPES, CASE_ASSERTION_STATES, CASE_CLOSURE_REASONS, CASE_OBSERVED_EFFECT_SOURCE_CLASSES, CASE_OBSERVED_EFFECT_STATES, CASE_PIN_COMPLETENESS, CASE_PROVIDER_OUTCOMES, } from "./case-response-records.mjs";
 import { RESPONSE_CONTACT_KINDS, RESPONSE_PACKET_PROFILE_IDS, RESPONSE_READINESS_ROW_IDS, RESPONSE_READINESS_STATES, } from "./case-response-packet-vocabulary.mjs";
-import { isValidAsciiHostname } from "../../lib/hostname.mjs";
+import { isValidAsciiHostname } from "../contracts/domain-name.mjs";
 const CONTACT_KINDS = new Set(RESPONSE_CONTACT_KINDS);
 const PRE_PLATFORM_CONTACT_KINDS = new Set(RESPONSE_CONTACT_KINDS.filter((kind) => kind !== 'application_platform'));
 const CONTROL_RE = /[\u0000-\u001f\u007f]/u;
@@ -318,7 +319,8 @@ export function validateCaseResponseReviewInputs(value) {
             ...(hasPlatformRoutes ? ['routeReviewAfter'] : []),
             'providerOutcome', 'outcomeDetail', 'originActionId', 'historyOmitted',
             'historyLimitations', 'transitions', 'createdAt', 'updatedAt',
-        ], 'Case-response escalation action');
+        ], 'Case-response escalation action', version >= 5 ? ['amendment'] : []);
+        readCasePacketAmendment(action.amendment);
         for (const key of ['actionId', 'recipient', 'contactSource', 'createdAt', 'updatedAt']) {
             reviewText(action[key], MAX_RESPONSE_VALUE_LENGTH, `Case-response action ${key}`);
         }
@@ -338,12 +340,16 @@ export function validateCaseResponseReviewInputs(value) {
         reviewNullableEnum(action.providerOutcome, CASE_PROVIDER_OUTCOMES, 'Case-response action provider outcome');
         reviewCount(action.historyOmitted, MAX_CASE_ACTION_EVENTS_PER_CASE, 'Case-response omitted transition count');
         reviewStrings(action.historyLimitations, MAX_RESPONSE_LIMITATIONS, MAX_RESPONSE_LIMITATION_LENGTH, 'Case-response action history limitations');
+        const requestEvents = [];
         for (const candidateTransition of boundedReviewArray(action.transitions, MAX_CASE_ACTION_EVENTS_PER_ACTION, 'Case-response transitions')) {
             const transition = exactReviewRecord(candidateTransition, [
                 'id', 'previousState', 'nextState', 'occurredAt', 'sourceClass', 'provenance',
                 'reference', 'evidencePinId', 'limitations', 'providerOutcome', 'outcomeDetail',
                 'originActionId', 'applied',
-            ], 'Case-response transition');
+            ], 'Case-response transition', version >= 5 ? ['evidenceRequest'] : []);
+            const evidenceRequest = readCaseEvidenceRequest(transition.evidenceRequest);
+            assertEvidenceRequestEvent(evidenceRequest, transition);
+            requestEvents.push({ id: transition.id, ...(evidenceRequest ? { evidenceRequest } : {}) });
             for (const key of ['id', 'occurredAt', 'provenance']) {
                 reviewText(transition[key], MAX_RESPONSE_VALUE_LENGTH, `Case-response transition ${key}`);
             }
@@ -358,6 +364,7 @@ export function validateCaseResponseReviewInputs(value) {
                 throw new TypeError('Case-response transition applied state is invalid.');
             reviewStrings(transition.limitations, MAX_RESPONSE_LIMITATIONS, MAX_RESPONSE_LIMITATION_LENGTH, 'Case-response transition limitations');
         }
+        assertEvidenceRequestHistory(requestEvents, Number(action.historyOmitted) > 0);
     }
     if (currentLineageActionIds
         && (currentLineageActionIds.length !== escalationActionIds.length
@@ -365,6 +372,10 @@ export function validateCaseResponseReviewInputs(value) {
         throw new TypeError('Case-response escalation history must match the selected action lineage in order.');
     }
     reviewCount(source.escalationHistoryOmitted, MAX_CASE_ACTIONS, 'Case-response omitted action count');
+    if (version >= 5)
+        assertPacketAmendmentSelection(source.escalationHistory.map(action => ({
+            id: action.actionId, history: action.transitions, originActionId: action.originActionId, amendment: action.amendment,
+        })), currentLineageActionIds?.[0] ?? null, new Set(source.selectedEvidence.map(pin => pin.id)));
     reviewStrings(source.escalationHistoryLimitations, MAX_RESPONSE_LIMITATIONS, MAX_RESPONSE_LIMITATION_LENGTH, 'Case-response escalation limitations');
     validateReviewLifecycle(source.responseLifecycle);
     return recursivelyFreezeReviewValue(structuredClone(source));

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

@@ -1,4 +1,4 @@
-import { CASE_SCHEMA_VERSION, MAX_CASE_STORE_BYTES, } from "./case-record-model.mjs";
+import { CASE_SCHEMA_VERSION, MAX_CASE_STORE_BYTES } from "../contracts/case-portability.mjs";
 import { normalizeCaseStore } from "./case-migration-model.mjs";
 import { projectCaseForDurableWrite } from "./case-record-projection.mjs";
 /** The exact versioned string persisted by the browser storage adapter. */

package/packages/cases/case-workflow-metadata.mjs

@@ -0,0 +1,225 @@
+// Typed analyst metadata; ordinary tags and assertions are always literal.
+import { MAX_CASE_ASSERTIONS, MAX_RESPONSE_RATIONALE_LENGTH, MAX_CASE_OBJECTIVE_LENGTH } from "../contracts/case-portability.mjs";
+import { caseInvestigationContext, prepareCaseInvestigationContext, parseIncidentUrlContext, normalizeCaseObjective } from "./case-incident-context.mjs";
+import { safeId, makeId } from "./case-record-core.mjs";
+import { array, enumeration, exact, iso, text } from "../evidence/artifact-structure.mjs";
+import { assertWorkspaceInputGraph } from "../workspace/hostile-input.mjs";
+// Preserve the maximum URL previously admitted inside a 21-character label.
+export const MAX_CASE_INCIDENT_TARGET_URL_LENGTH = MAX_RESPONSE_RATIONALE_LENGTH - 21;
+export const MAX_CASE_INCIDENT_TARGETS = 20;
+export const MAX_CASE_INCIDENT_TARGET_HISTORY = MAX_CASE_ASSERTIONS;
+export const CASE_TYPES = Object.freeze([
+    Object.freeze({ id: 'phishing', label: 'Phishing', description: 'Deceptive content or messages intended to obtain credentials or other sensitive information.' }),
+    Object.freeze({ id: 'impersonation', label: 'Impersonation', description: 'A domain, account or page presenting itself as another person or organisation.' }),
+    Object.freeze({ id: 'lookalike_cybersquatting', label: 'Lookalike or cybersquatting', description: 'A domain or account selected for review because it resembles or may exploit another name, brand or identifier.' }),
+    Object.freeze({ id: 'trademark_infringement', label: 'Trademark infringement', description: 'Potential unauthorised trademark use that may cause confusion about source or affiliation.' }),
+    Object.freeze({ id: 'copyright_infringement', label: 'Copyright infringement', description: 'Potential unauthorised copying or distribution of protected material.' }),
+    Object.freeze({ id: 'counterfeit_goods', label: 'Counterfeit goods', description: 'Promotion or sale of goods presented as genuine branded products.' }),
+    Object.freeze({ id: 'scam_fraud', label: 'Scam or fraud', description: 'Deceptive activity intended to obtain money, property or another benefit.' }),
+    Object.freeze({ id: 'malware_distribution', label: 'Malware distribution', description: 'Delivery, hosting or promotion of malicious software.' }),
+    Object.freeze({ id: 'credential_theft', label: 'Credential theft', description: 'Collection, sale or misuse of account credentials.' }),
+    Object.freeze({ id: 'spam_platform_abuse', label: 'Spam or platform abuse', description: 'Unsolicited or abusive platform activity that does not fit a narrower type.' }),
+    Object.freeze({ id: 'privacy_personal_data', label: 'Privacy or personal data', description: 'Potential exposure or misuse of personal information.' }),
+    Object.freeze({ id: 'account_compromise', label: 'Account compromise', description: 'Suspected unauthorised control or use of an account.' }),
+    Object.freeze({ id: 'other', label: 'Other', description: 'A reviewed type not covered by the current taxonomy.' }),
+]);
+const CASE_TYPE_IDS = new Set(CASE_TYPES.map((item) => item.id));
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
+const CASE_REFERENCE_ALPHABET = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+export function readCaseTypes(value) {
+    assertWorkspaceInputGraph(value, 'Case types');
+    const selected = array(value, 'Case types', CASE_TYPES.length).map(id => {
+        if (typeof id !== 'string' || !CASE_TYPE_IDS.has(id))
+            throw new TypeError('Unknown Case type.');
+        return id;
+    });
+    if (new Set(selected).size !== selected.length)
+        throw new TypeError('Case types must be unique.');
+    return CASE_TYPES.map(item => item.id).filter(id => selected.includes(id));
+}
+export function caseTypeIds(record) {
+    return [...(record.workflowMetadata?.types ?? [])];
+}
+export function caseTypeRecords(record) {
+    const selected = new Set(caseTypeIds(record));
+    return CASE_TYPES.filter((item) => selected.has(item.id));
+}
+export function caseTypeSummary(record) {
+    const labels = caseTypeRecords(record).map((item) => item.label);
+    if (!labels.length)
+        return '';
+    if (labels.length <= 2)
+        return labels.join(' and ');
+    return `${labels.slice(0, 2).join(', ')} and ${labels.length - 2} more`;
+}
+function encodeCaseReference(value, minimumLength) {
+    let remainder = value;
+    let encoded = '';
+    do {
+        encoded = CASE_REFERENCE_ALPHABET[Number(remainder % 32n)] + encoded;
+        remainder /= 32n;
+    } while (remainder > 0n);
+    return encoded.padStart(minimumLength, '0');
+}
+/**
+ * Returns an unambiguous reference derived injectively from the immutable Case
+ * id. UUIDs use their complete 128-bit value. Legacy ids use every UTF-8 byte,
+ * its encoded length and a distinct namespace, so no shared counter or server
+ * is needed and imports retain the same reference.
+ */
+export function caseNumber(caseId) {
+    const id = typeof caseId === 'string' && caseId ? caseId : 'unknown';
+    if (UUID_RE.test(id)) {
+        return `WS-${encodeCaseReference(BigInt(`0x${id.replaceAll('-', '')}`), 26)}`;
+    }
+    const bytes = new TextEncoder().encode(id);
+    let encoded = 0n;
+    for (const byte of bytes)
+        encoded = encoded * 256n + BigInt(byte);
+    return `WS-L${encodeCaseReference(BigInt(bytes.length), 2)}-${encodeCaseReference(encoded, Math.ceil(bytes.length * 8 / 5))}`;
+}
+export function formattedCaseNumber(caseId) {
+    const value = caseNumber(caseId);
+    if (value.startsWith('WS-L'))
+        return value;
+    const separator = value.indexOf('-');
+    const prefix = value.slice(0, separator + 1);
+    const body = value.slice(separator + 1);
+    return `${prefix}${body.match(/.{1,5}/gu)?.join('-') ?? body}`;
+}
+export function normalizeCaseIncidentTargetUrl(value) {
+    if (typeof value !== 'string' || value.length > MAX_CASE_INCIDENT_TARGET_URL_LENGTH || !value.trim())
+        return null;
+    let parsed;
+    try {
+        parsed = new URL(value.trim());
+    }
+    catch {
+        return null;
+    }
+    if (!['http:', 'https:'].includes(parsed.protocol) || !parsed.hostname || parsed.username || parsed.password)
+        return null;
+    const normalized = parsed.toString();
+    return normalized.length <= MAX_CASE_INCIDENT_TARGET_URL_LENGTH ? normalized : null;
+}
+/** Local review only: analyst link state is not independent observed coverage. */
+export function buildCaseIncidentCoverage(record) {
+    return caseIncidentTargets(record, { includeResolved: true }).map(target => ({
+        target,
+        hostname: new URL(target.url).hostname,
+        actionCoverage: 'unknown',
+        observationCoverage: 'unknown',
+    }));
+}
+export function emptyCaseWorkflowMetadata() {
+    return { types: [], incidentTargets: [], investigationContext: null };
+}
+function identifier(value) {
+    const id = safeId(value);
+    if (!id || id !== value)
+        throw new TypeError('Case metadata identity is invalid.');
+    return id;
+}
+/** Strict admission before persistence; no inferred defaults for typed fields. */
+export function readCaseWorkflowMetadata(value, domain) {
+    if (value === undefined)
+        return undefined;
+    assertWorkspaceInputGraph(value, 'Case workflow metadata');
+    const row = exact(value, ['types', 'incidentTargets', 'investigationContext'], 'Case workflow metadata');
+    const types = readCaseTypes(row.types);
+    const incidentTargets = array(row.incidentTargets, 'Incident target history', MAX_CASE_INCIDENT_TARGET_HISTORY).map(raw => {
+        const item = exact(raw, ['id', 'url', 'state', 'createdAt', 'updatedAt'], 'Incident target');
+        const url = normalizeCaseIncidentTargetUrl(item.url);
+        if (!url || url !== item.url)
+            throw new TypeError('Incident target URL is invalid.');
+        iso(item.createdAt, 'Incident target creation time');
+        iso(item.updatedAt, 'Incident target update time');
+        if (Date.parse(item.updatedAt) < Date.parse(item.createdAt))
+            throw new TypeError('Incident target update precedes creation.');
+        return { id: identifier(item.id), url, state: enumeration(item.state, ['open', 'resolved'], 'Incident target state'),
+            createdAt: item.createdAt, updatedAt: item.updatedAt };
+    });
+    if (new Set(incidentTargets.map(item => item.id)).size !== incidentTargets.length)
+        throw new TypeError('Incident target identities must be unique.');
+    let investigationContext = null;
+    if (row.investigationContext !== null) {
+        const item = exact(row.investigationContext, ['id', 'objective', 'incidentUrl', 'urlRetention', 'updatedAt'], 'Incident context');
+        const objective = text(item.objective, 'Investigation objective', MAX_CASE_OBJECTIVE_LENGTH);
+        if (!objective || normalizeCaseObjective(objective) !== objective)
+            throw new TypeError('Investigation objective is invalid.');
+        const parsed = parseIncidentUrlContext(item.incidentUrl);
+        const urlRetention = enumeration(item.urlRetention, ['exact', 'origin_only'], 'Incident URL retention');
+        if (!parsed || parsed.registrableDomain !== domain
+            || item.incidentUrl !== (urlRetention === 'exact' ? parsed.exactUrl : parsed.originUrl)) {
+            throw new TypeError('Incident context URL does not match its Case domain or retention choice.');
+        }
+        iso(item.updatedAt, 'Incident context update time');
+        investigationContext = { id: identifier(item.id), objective, incidentUrl: item.incidentUrl,
+            urlRetention, updatedAt: item.updatedAt };
+    }
+    return { types, incidentTargets, investigationContext };
+}
+/** Mutations use the existing Case save coordinator and compare-and-swap rules. */
+export function updateCaseWorkflowMetadata(current, patch, domain, now) {
+    const next = structuredClone(current);
+    if (patch.caseTypes !== undefined) {
+        if (patch.expectedCaseTypes !== undefined && JSON.stringify(readCaseTypes(patch.expectedCaseTypes)) !== JSON.stringify(current.types)) {
+            throw new Error('The Case types changed after this edit was started. Reopen the Case before saving; your draft was not applied.');
+        }
+        next.types = readCaseTypes(patch.caseTypes);
+    }
+    if (patch.incidentTarget !== undefined) {
+        const url = normalizeCaseIncidentTargetUrl(patch.incidentTarget);
+        if (!url)
+            throw new TypeError('Enter an exact HTTP(S) incident URL without embedded credentials.');
+        if (next.incidentTargets.some(target => target.state === 'open' && target.url === url))
+            throw new Error('That exact incident URL is already active in this Case.');
+        if (next.incidentTargets.filter(target => target.state === 'open').length >= MAX_CASE_INCIDENT_TARGETS)
+            throw new Error(`A Case can retain at most ${MAX_CASE_INCIDENT_TARGETS} active incident links. Resolve one before adding another.`);
+        if (next.incidentTargets.length >= MAX_CASE_INCIDENT_TARGET_HISTORY)
+            throw new Error(`The retained incident link history is full (${MAX_CASE_INCIDENT_TARGET_HISTORY}). Export this Case and open another; no history was removed.`);
+        next.incidentTargets.push({ id: makeId(), url, state: 'open', createdAt: now, updatedAt: now });
+    }
+    if (patch.incidentTargetResolution !== undefined) {
+        const id = identifier(patch.incidentTargetResolution);
+        const target = next.incidentTargets.find(item => item.id === id);
+        if (!target || target.state !== 'open')
+            throw new Error('That incident target is missing or already resolved. Refresh the Case before continuing.');
+        next.incidentTargets = next.incidentTargets.map(item => item.id === id ? { ...item, state: 'resolved', updatedAt: now } : item);
+    }
+    if (patch.investigationContext !== undefined) {
+        assertWorkspaceInputGraph(patch.investigationContext, 'New incident context');
+        const raw = exact(patch.investigationContext, ['objective', 'incidentUrl', 'retainExactUrl'], 'New incident context');
+        if (typeof raw.retainExactUrl !== 'boolean')
+            throw new TypeError('Choose whether to retain the exact incident URL.');
+        next.investigationContext = { ...prepareCaseInvestigationContext({ objective: raw.objective, incidentUrl: raw.incidentUrl, retainExactUrl: raw.retainExactUrl }),
+            id: current.investigationContext?.id ?? makeId(), updatedAt: now };
+    }
+    return readCaseWorkflowMetadata(next, domain);
+}
+/** Add missing targets, retaining the newer state for an existing identity. */
+export function mergeCaseWorkflowMetadata(local, incoming, importNewer, domain) {
+    const targets = new Map(local.incidentTargets.map(target => [target.id, target]));
+    for (const target of incoming.incidentTargets) {
+        const existing = targets.get(target.id);
+        if (existing && (existing.url !== target.url || existing.createdAt !== target.createdAt))
+            throw new TypeError('Imported incident target identity conflicts with retained history. No data was changed.');
+        if (!existing || Date.parse(target.updatedAt) > Date.parse(existing.updatedAt))
+            targets.set(target.id, target);
+    }
+    const left = local.investigationContext, right = incoming.investigationContext;
+    const investigationContext = right && (!left || Date.parse(right.updatedAt) > Date.parse(left.updatedAt)) ? right : left;
+    return readCaseWorkflowMetadata({ types: importNewer ? incoming.types : local.types,
+        incidentTargets: [...targets.values()], investigationContext }, domain);
+}
+export function caseIncidentTargets(record, options = {}) {
+    return (record.workflowMetadata?.incidentTargets ?? [])
+        .filter(target => options.includeResolved || target.state === 'open').map(target => ({ ...target }));
+}
+export function caseResponseIncidentUrls(record) {
+    const urls = new Set(caseIncidentTargets(record).map((target) => target.url));
+    const context = caseInvestigationContext(record);
+    if (context?.urlRetention === 'exact')
+        urls.add(context.incidentUrl);
+    return [...urls].slice(0, MAX_CASE_INCIDENT_TARGETS);
+}

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

@@ -0,0 +1,43 @@
+// Read legacy text conventions once at the versioned storage/import boundary.
+// Keep the original assertions for references and historical evidence.
+import { CASE_TYPES, normalizeCaseIncidentTargetUrl, readCaseWorkflowMetadata } from "./case-workflow-metadata.mjs";
+import { normalizeTags } from "./case-record-core.mjs";
+import { normalizeCaseObjective, parseIncidentUrlContext } from "./case-incident-context.mjs";
+import { EVIDENCE_FOLLOW_UP_CASE_SCHEMA_VERSION } from "../contracts/case-portability.mjs";
+const TYPE_PREFIX = 'case-type:';
+const TARGET_PREFIX = 'Incident target URL: ';
+const CONTEXT_PREFIX = 'Investigate incident URL: ';
+const OBJECTIVE_PREFIX = 'Objective: ';
+const RETENTION_SEPARATOR = ' | URL retained: ';
+export function readCaseWorkflowFields(raw, domain, assertions, sourceVersion) {
+    const tags = normalizeTags(raw.tags);
+    if (raw.workflowMetadata !== undefined) {
+        if (sourceVersion != null && sourceVersion < EVIDENCE_FOLLOW_UP_CASE_SCHEMA_VERSION)
+            throw new TypeError('Typed workflow metadata requires the current Case schema.');
+        return { tags, workflowMetadata: readCaseWorkflowMetadata(raw.workflowMetadata, domain) };
+    }
+    const types = CASE_TYPES.filter(type => tags.some(tag => tag.toLowerCase() === `${TYPE_PREFIX}${type.id}`)).map(type => type.id);
+    const workflowMetadata = { types, incidentTargets: [], investigationContext: null };
+    for (const assertion of assertions) {
+        if (assertion.statement.startsWith(TARGET_PREFIX)) {
+            const url = normalizeCaseIncidentTargetUrl(assertion.statement.slice(TARGET_PREFIX.length));
+            if (url)
+                workflowMetadata.incidentTargets.push({ id: assertion.id, url, state: assertion.state, createdAt: assertion.createdAt, updatedAt: assertion.updatedAt });
+        }
+        if (assertion.kind !== 'next_step' || assertion.state !== 'open' || !assertion.statement.startsWith(CONTEXT_PREFIX))
+            continue;
+        const parsed = parseIncidentUrlContext(assertion.statement.slice(CONTEXT_PREFIX.length));
+        const rationale = assertion.rationale ?? '';
+        const index = rationale.lastIndexOf(RETENTION_SEPARATOR);
+        const objective = rationale.startsWith(OBJECTIVE_PREFIX) && index > OBJECTIVE_PREFIX.length
+            ? normalizeCaseObjective(rationale.slice(OBJECTIVE_PREFIX.length, index)) : '';
+        const retention = index >= 0 ? rationale.slice(index + RETENTION_SEPARATOR.length) : '';
+        if (!parsed || parsed.registrableDomain !== domain || !objective || (retention !== 'exact' && retention !== 'origin_only'))
+            continue;
+        workflowMetadata.investigationContext = { id: assertion.id, objective, urlRetention: retention,
+            incidentUrl: retention === 'exact' ? parsed.exactUrl : parsed.originUrl, updatedAt: assertion.updatedAt };
+    }
+    // Preserve historical text byte-for-byte where already normalised. Typed
+    // metadata becomes authoritative; subsequent tag edits never change types.
+    return { tags, workflowMetadata: readCaseWorkflowMetadata(workflowMetadata, domain) };
+}

package/packages/cases/http-summary.mjs

@@ -3,7 +3,7 @@
 // connection attempts. Bulk/watchlist/case records deliberately keep only this
 // smaller derived shape: no paths, queries, header values, attempt errors, or
 // redirect inventories.
-import { MAX_HTTP_EVIDENCE_REDIRECTS } from "../../lib/http-evidence-bounds.mjs";
+import { MAX_HTTP_EVIDENCE_REDIRECTS } from "../analysis/http-evidence-bounds.mjs";
 export const HTTP_SUMMARY_VERSION = 1;
 export const MAX_HTTP_SUMMARY_ORIGIN_LENGTH = 300;
 export const MAX_HTTP_SUMMARY_CONTENT_TYPE_LENGTH = 100;
@@ -154,6 +154,11 @@ export function normalizeHttpSummary(value) {
         httpSecurityHeaders: securityHeaderTokens(record.httpSecurityHeaders),
     };
 }
+/** A partial body still permits comparison of observed response metadata. */
+export function httpSummaryFieldIsObserved(field, value) {
+    const summary = normalizeHttpSummary(value);
+    return summary !== null && Object.hasOwn(summary, field) && summary[field] !== null;
+}
 export function httpSecurityHeaderLabel(token) {
     const labels = {
         'content-security-policy': 'Content Security Policy',

package/packages/comparison/favicon-similarity.mjs

@@ -1,4 +1,4 @@
-import { hammingDistanceHex, isInformativePerceptualHash, isPerceptualHash, } from "../../lib/perceptual-hash-comparison.mjs";
+import { hammingDistanceHex, isInformativePerceptualHash, isPerceptualHash, } from "../analysis/perceptual-hash-comparison.mjs";
 function plainRecord(value) {
     return value && typeof value === 'object' && !Array.isArray(value)
         ? value

package/packages/comparison/page-similarity.mjs

@@ -3,7 +3,7 @@
 // produce an aggregate similarity score, risk factor, or maliciousness
 // verdict. Inputs pass through the strict baseline normalizer before use.
 import { normalizePageBaseline } from "../workspace/page-baseline.mjs";
-import { hammingDistanceHex } from "../../lib/perceptual-hash-comparison.mjs";
+import { hammingDistanceHex } from "../analysis/perceptual-hash-comparison.mjs";
 import { PAGE_COMPARISON_VERSION } from "../contracts/offline-comparison.mjs";
 export { PAGE_COMPARISON_VERSION };
 function component(id, label, method, status, outcome, detail, partial) {

package/packages/comparison/relationship-evidence.mjs

@@ -3,11 +3,12 @@
 // proof of common ownership, coordination, intent, or maliciousness. This
 // module deliberately produces no aggregate score and is never a persistence
 // boundary.
-import { normalizeDomain } from "../cases/case-model.mjs";
+import { normalizeDomain } from "../evidence/domain-name.mjs";
+import { canonicalPublicIpAddress } from "../evidence/public-address-policy.mjs";
 import { groupBySimilarFavicon } from "./favicon-similarity.mjs";
-import { qualifyRelationshipSources, relationshipSourceEvidence, normalizeRelationshipSourceProjection, unknownRelationshipSource, MAX_RELATIONSHIP_SOURCES_PER_DOMAIN, } from "./relationship-provenance.mjs";
-import { RELATIONSHIP_EVIDENCE_SCHEMA, RELATIONSHIP_EVIDENCE_VERSION, SUPPORTED_TLS_RELATIONSHIP_PROFILE_VERSIONS, TLS_RELATIONSHIP_PROFILE_VERSION, } from "../contracts/offline-comparison.mjs";
-export { RELATIONSHIP_EVIDENCE_SCHEMA, RELATIONSHIP_EVIDENCE_VERSION, SUPPORTED_TLS_RELATIONSHIP_PROFILE_VERSIONS, TLS_RELATIONSHIP_PROFILE_VERSION, };
+import { qualifyRelationshipSources, relationshipSourceEvidence, normalizeRelationshipSourceProjection, FAVICON_RELATIONSHIP_DESCRIPTION, unknownRelationshipSource, MAX_RELATIONSHIP_SOURCES_PER_DOMAIN, } from "./relationship-provenance.mjs";
+import { RELATIONSHIP_EVIDENCE_SCHEMA, RELATIONSHIP_EVIDENCE_VERSION, SUPPORTED_RELATIONSHIP_EVIDENCE_VERSIONS, RELATIONSHIP_SOURCE_PROVENANCE_VERSION, SUPPORTED_TLS_RELATIONSHIP_PROFILE_VERSIONS, TLS_RELATIONSHIP_PROFILE_VERSION, } from "../contracts/offline-comparison.mjs";
+export { RELATIONSHIP_EVIDENCE_SCHEMA, RELATIONSHIP_EVIDENCE_VERSION, SUPPORTED_RELATIONSHIP_EVIDENCE_VERSIONS, SUPPORTED_TLS_RELATIONSHIP_PROFILE_VERSIONS, TLS_RELATIONSHIP_PROFILE_VERSION, };
 export const MAX_RELATIONSHIP_ROWS = 2000;
 export const MAX_RELATIONSHIP_GROUPS = 100;
 export const MAX_RELATIONSHIP_DOMAINS = 50;
@@ -217,7 +218,7 @@ export function buildScanRelationships(rawRows) {
     for (const raw of input.slice(0, MAX_RELATIONSHIP_ROWS)) {
         const domain = normalizeDomain(raw?.domain);
         const observation = record(raw?.relationship);
-        if (!domain || raw?.trusted || !observation || ![2, RELATIONSHIP_EVIDENCE_VERSION].some((version) => version === observation.version))
+        if (!domain || raw?.trusted || !observation || !SUPPORTED_RELATIONSHIP_EVIDENCE_VERSIONS.some((version) => version === observation.version))
             continue;
         rows.push({ domain, observation });
         if (observation.truncated === true)
@@ -228,6 +229,7 @@ export function buildScanRelationships(rawRows) {
     const identifiers = new Map();
     const certificates = new Map();
     const officialAssets = new Map();
+    let excludedNonPublicAddresses = 0;
     for (const { domain, observation } of rows) {
         const nameserverSource = Array.isArray(observation.nameservers) ? observation.nameservers : [];
         const addressSource = Array.isArray(observation.ipAddresses) ? observation.ipAddresses : [];
@@ -239,8 +241,16 @@ export function buildScanRelationships(rawRows) {
         const nameservers = nameserverSource.slice(0, MAX_NAMESERVERS_PER_ROW).map(hostname).filter(Boolean);
         if (nameservers.length)
             addBucket(nameserverSets, [...new Set(nameservers)].sort().join(' · '), domain);
-        for (const value of addressSource.slice(0, MAX_IPS_PER_ROW))
-            addBucket(addresses, ipAddress(value), domain);
+        for (const value of addressSource.slice(0, MAX_IPS_PER_ROW)) {
+            const address = ipAddress(value);
+            if (!address)
+                continue;
+            const publicAddress = canonicalPublicIpAddress(address);
+            if (publicAddress)
+                addBucket(addresses, publicAddress, domain);
+            else
+                excludedNonPublicAddresses += 1;
+        }
         for (const value of identifierSource.slice(0, MAX_TRACKING_IDS_PER_ROW)) {
             if (typeof value === 'string' && /^[a-z-]{1,40}:[A-Z0-9-]{1,64}$/.test(value)) {
                 addBucket(identifiers, value, domain);
@@ -288,7 +298,7 @@ export function buildScanRelationships(rawRows) {
                     evidence?.faviconPHash ? `dhash:${evidence.faviconPHash}` : '',
                 ].filter(Boolean).join(',')}`;
             }).join('|');
-            output.push(group('favicon', 'Similar favicon', 'Exact SHA-256 or perceptual dHash distance ≤ 6', '', distinctDomains, 'These domains used an identical or perceptually similar favicon in this scan.', normalizedValue));
+            output.push(group('favicon', 'Connected favicon matches', 'Exact SHA-256 or perceptual dHash distance ≤ 6', '', distinctDomains, FAVICON_RELATIONSHIP_DESCRIPTION, normalizedValue));
         }
     }
     for (const [value, domains] of officialAssets)
@@ -317,7 +327,7 @@ export function buildScanRelationships(rawRows) {
                 const field = ARRAY_RELATIONSHIP_FIELDS[item.type];
                 if (field && Array.isArray(observation[field.field]) && observation[field.field].length > field.maximum)
                     groupTruncated = true;
-                const projection = observation.version === RELATIONSHIP_EVIDENCE_VERSION
+                const projection = Number(observation.version) >= RELATIONSHIP_SOURCE_PROVENANCE_VERSION
                     ? normalizeRelationshipSourceProjection(observation.sourceEvidence) : {};
                 for (const source of projection[item.type] ?? [unknownRelationshipSource()]) {
                     if (contributors.length >= MAX_RELATIONSHIP_DOMAINS * MAX_RELATIONSHIP_SOURCES_PER_DOMAIN)
@@ -331,8 +341,10 @@ export function buildScanRelationships(rawRows) {
     return {
         version: RELATIONSHIP_EVIDENCE_VERSION,
         groups,
+        excludedNonPublicAddresses,
         truncated,
         limitations: [
+            ...(excludedNonPublicAddresses ? [`${excludedNonPublicAddresses} non-public address observations were excluded from public-infrastructure grouping; their DNS answers remain in the scan evidence.`] : []),
             'Shared observations are investigation pivots, not proof of common ownership, coordination, intent, or maliciousness.',
             'Certificate relationships use exact native TLS leaf-certificate SHA-256 values only. Certificate Transparency counts and hostnames are never treated as certificate reuse.',
             'A shared certificate can reflect a multi-domain certificate, shared hosting, CDN, or managed platform and does not establish common control.',