@slicedearth/whoisleuth-cli 2.2.0 → 2.4.0

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

@@ -1,8 +1,12 @@
 import { CASE_SCHEMA_VERSION, MAX_CASE_STORE_BYTES, } from "./case-record-model.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. */
 export function serializeCaseStore(cases) {
-    return JSON.stringify({ version: CASE_SCHEMA_VERSION, cases });
+    return JSON.stringify({
+        version: CASE_SCHEMA_VERSION,
+        cases: cases.map(projectCaseForDurableWrite),
+    });
 }
 function byteLength(text) {
     if (typeof TextEncoder !== 'undefined') {
@@ -84,10 +88,35 @@ export function enforceStoreBudget(cases) {
     }
     return { cases: working, pruned };
 }
+/** A read-only, ephemeral preview of the exact existing byte-budget policy. */
+export function prepareCaseStoreSave(current, proposed) {
+    const result = enforceStoreBudget(proposed);
+    const retainedById = new Map(result.cases.map(record => [record.id, record]));
+    const removed = proposed.flatMap(record => {
+        const retained = retainedById.get(record.id);
+        const ids = new Set(retained?.evidenceHistory.map(snapshot => snapshot.id));
+        const snapshots = record.evidenceHistory.filter(snapshot => !ids.has(snapshot.id));
+        return snapshots.length ? [{
+                caseId: record.id, domain: record.domain,
+                snapshotIds: snapshots.map(snapshot => snapshot.id),
+                remainingSnapshots: retained?.evidenceHistory.length ?? 0,
+            }] : [];
+    });
+    return {
+        ...result,
+        current: normalizeCaseStore(current).cases,
+        removed,
+        removedBytes: Math.max(0, byteLength(serializeCaseStore(proposed)) - byteLength(serializeCaseStore(result.cases))),
+    };
+}
+/** Same-clock peer edits invalidate confirmation, including changes to other Cases. */
+export function caseStoreSavePreviewIsCurrent(current, preview) {
+    return serializeCaseStore(current) === serializeCaseStore(preview.current);
+}
 export function buildCaseExport(cases, nowIso) {
     return {
         version: CASE_SCHEMA_VERSION,
         exportedAt: nowIso || new Date().toISOString(),
-        cases: normalizeCaseStore(cases).cases,
+        cases: normalizeCaseStore(cases).cases.map(projectCaseForDurableWrite),
     };
 }

package/packages/cases/response-route-freshness.mjs

@@ -0,0 +1,16 @@
+import { normalizeExplicitIsoTimestamp } from "../evidence/observation.mjs";
+import { MAX_RESPONSE_AUTHORISATION_CLOCK_SKEW_MS, RESPONSE_ROUTE_STALE_AFTER_DAYS } from "../contracts/case-portability.mjs";
+/** Source freshness is independent of action deadlines and analyst follow-up. */
+export function responseRouteFreshness(observedAt, reviewAfter, evaluatedAt) {
+    const observation = normalizeExplicitIsoTimestamp(observedAt);
+    const evaluation = normalizeExplicitIsoTimestamp(evaluatedAt);
+    const deadline = normalizeExplicitIsoTimestamp(reviewAfter);
+    if (!observation || !evaluation || (reviewAfter !== null && !deadline))
+        return 'unknown';
+    const age = Date.parse(evaluation) - Date.parse(observation);
+    return age < -MAX_RESPONSE_AUTHORISATION_CLOCK_SKEW_MS
+        || (deadline !== null && Date.parse(evaluation) >= Date.parse(deadline))
+        || (deadline === null && age > RESPONSE_ROUTE_STALE_AFTER_DAYS * 86_400_000)
+        ? 'stale'
+        : 'current';
+}

package/packages/comparison/capture-context.mjs

@@ -0,0 +1,61 @@
+import { exact, text } from "../evidence/artifact-structure.mjs";
+import { normalizeExplicitIsoTimestamp } from "../evidence/observation.mjs";
+import { readEvidenceImageDimensions } from "../evidence/image-regions.mjs";
+/** Optional declarations remain unknown for existing manifests; no inference from image dimensions. */
+export function readCaptureConditions(raw) {
+    if (raw === undefined || raw === null)
+        return null;
+    const value = exact(raw, ['browser', 'browserVersion', 'viewport', 'deviceScaleFactor', 'locale', 'timezone', 'colourScheme'], 'Capture conditions');
+    const viewport = exact(value.viewport, ['width', 'height'], 'Capture viewport');
+    const dimensions = readEvidenceImageDimensions(viewport.width, viewport.height);
+    if (typeof value.deviceScaleFactor !== 'number' || !Number.isFinite(value.deviceScaleFactor)
+        || value.deviceScaleFactor < 0.25 || value.deviceScaleFactor > 8)
+        throw new TypeError('Capture scale must be between 0.25 and 8.');
+    if (value.colourScheme !== 'light' && value.colourScheme !== 'dark')
+        throw new TypeError('Capture colour scheme is unsupported.');
+    return Object.freeze({ browser: text(value.browser, 'Capture browser', 40), browserVersion: text(value.browserVersion, 'Capture browser version', 80),
+        viewport: dimensions, deviceScaleFactor: value.deviceScaleFactor,
+        locale: text(value.locale, 'Capture locale', 80), timezone: text(value.timezone, 'Capture timezone', 80), colourScheme: value.colourScheme });
+}
+export function readObservationLabel(raw) {
+    if (raw === undefined || raw === null || raw === '')
+        return null;
+    return text(raw, 'Observation label', 80);
+}
+export function compareObservationContexts(input) {
+    if (!Array.isArray(input) || input.length < 2 || input.length > 20)
+        throw new TypeError('Compare between 2 and 20 observation contexts.');
+    const observations = input.map(value => {
+        const observedAt = value.observedAt === null ? null : normalizeExplicitIsoTimestamp(value.observedAt);
+        if (value.observedAt !== null && !observedAt)
+            throw new TypeError('Observation time must include an explicit timezone.');
+        return { observedAt, observerLabel: readObservationLabel(value.observerLabel), vantageLabel: readObservationLabel(value.vantageLabel), conditions: readCaptureConditions(value.conditions) };
+    });
+    const timestamps = observations.map(value => value.observedAt === null ? null : Date.parse(value.observedAt));
+    const knownTimes = timestamps.filter((value) => value !== null);
+    const row = (id, label, values) => ({ id, label, values,
+        state: values.some(value => value === null) ? 'unknown' : new Set(values).size === 1 ? 'same' : 'different' });
+    const conditions = observations.map(value => value.conditions);
+    const rows = [
+        row('observer', 'Declared observer', observations.map(value => value.observerLabel)),
+        row('vantage', 'Declared vantage', observations.map(value => value.vantageLabel)),
+        row('browser', 'Declared browser', conditions.map(value => value ? `${value.browser} ${value.browserVersion}` : null)),
+        row('viewport', 'Declared viewport', conditions.map(value => value ? `${value.viewport.width} × ${value.viewport.height}` : null)),
+        row('scale', 'Declared scale', conditions.map(value => value ? String(value.deviceScaleFactor) : null)),
+        row('locale', 'Declared locale', conditions.map(value => value?.locale ?? null)),
+        row('timezone', 'Declared timezone', conditions.map(value => value?.timezone ?? null)),
+        row('colour', 'Declared colour scheme', conditions.map(value => value?.colourScheme ?? null)),
+    ];
+    const labelPairs = observations.map(value => value.observerLabel && value.vantageLabel ? JSON.stringify([value.observerLabel, value.vantageLabel]) : null);
+    return {
+        observations, rows, time: { state: knownTimes.length !== observations.length ? 'unknown' : new Set(knownTimes).size === 1 ? 'same_instant' : 'different_instants',
+            spanMilliseconds: knownTimes.length === observations.length ? Math.max(...knownTimes) - Math.min(...knownTimes) : null },
+        labels: labelPairs.some(value => value === null) ? 'incomplete' : new Set(labelPairs).size === labelPairs.length ? 'distinct' : 'repeated',
+        independence: 'not_verified',
+        limitations: [
+            'Observer, vantage and capture conditions are declarations, not verified network location or independent collection.',
+            'Different capture times, browser versions, viewports, scale, locale and shared upstream caches can explain differences. Equal declarations do not establish identical environments.',
+            'These selected observations do not establish worldwide availability, removal or takedown.',
+        ],
+    };
+}

package/packages/comparison/comparison-ledger-bulk.mjs

@@ -1,14 +1,8 @@
-import { MAX_BULK_SESSIONS, compareBulkSessions, normalizeBulkSession, } from "../workspace/bulk-session-model.mjs";
+import { MAX_BULK_SESSIONS, areBulkRiskScoresComparable, compareBulkSessions, normalizeBulkSession, } from "../workspace/bulk-session-model.mjs";
 import { MAX_COMPARISON_LEDGER_BULK_PAIRS, boundedComparisonLedgerId, comparisonLedgerCollector, comparisonLedgerInputArray, comparisonLedgerRecord, comparisonLedgerValuePresent, comparisonLedgerValueState, makeComparisonLedgerCandidate, stableComparisonLedgerId, } from "./comparison-ledger-contract.mjs";
-function bulkCompleteness(session) {
-    return session.state === 'complete' ? 'complete' : session.state === 'partial' ? 'partial' : 'unavailable';
-}
-function sourceMap(result) {
-    return new Map(result.sourceCoverage.map((item) => [item.source, item.state]));
-}
-function namedBulkSourceState(result, source) {
-    return result.sourceCoverage.find((item) => item.source === source)?.state ?? 'not_reported';
-}
+function bulkCompleteness(session) { return session.state === 'complete' ? 'complete' : session.state === 'partial' ? 'partial' : 'unavailable'; }
+function sourceMap(result) { return new Map(result.sourceCoverage.map((item) => [item.source, item.state])); }
+function namedBulkSourceState(result, source) { return result.sourceCoverage.find((item) => item.source === source)?.state ?? 'not_reported'; }
 function bulkFamilyState(result, family) {
     if (family === 'model')
         return 'derived';
@@ -47,6 +41,9 @@ function bulkFieldDecision(field, earlier, later, before, after) {
     if (field.kind === 'registrar')
         return { state: 'not_compared', completeness: 'not_reported', earlierState, laterState, limitation: 'The exact retained registrar texts are shown, but saved Bulk rows do not retain field-level registrar provenance; these values are not compared as a publication or target change.' };
     if (field.kind === 'model') {
+        if (field.field === 'Risk score' && !areBulkRiskScoresComparable(earlier, later)) {
+            return { state: 'not_compared', completeness: 'partial', earlierState, laterState, limitation: 'Risk scores require the same ready Brand Profile provenance, scan depth, and versioned Risk model before comparison.' };
+        }
         const comparable = comparisonLedgerValuePresent(before) && comparisonLedgerValuePresent(after);
         return { state: comparable ? 'different' : 'not_compared', completeness: comparable ? 'complete' : 'partial', earlierState, laterState, limitation: comparable ? null : 'A score absent from either retained row is not represented as an observed score change.' };
     }
@@ -69,6 +66,8 @@ function bulkPairCompleteness(earlier, later) {
         const right = after.get(domain);
         if (!right || left.scanDepth !== right.scanDepth)
             return 'partial';
+        if (!areBulkRiskScoresComparable(left, right))
+            return 'partial';
         if (left.riskModelVersion === null || right.riskModelVersion === null || left.riskModelVersion !== right.riskModelVersion
             || left.opportunityModelVersion === null || right.opportunityModelVersion === null || left.opportunityModelVersion !== right.opportunityModelVersion)
             return 'partial';
@@ -296,6 +295,10 @@ export function comparisonLedgerBulkPairIndexId(earlierSessionId, laterSessionId
     return stableComparisonLedgerId('ledger-bulk_session_pair', [String(earlierSessionId ?? ''), String(laterSessionId ?? '')]);
 }
 export function buildBulkComparisonCandidates(sessionsRaw, pairsRaw, counters) {
+    const pairs = comparisonLedgerInputArray(pairsRaw);
+    // Saved sessions are comparison inputs only after a pair is requested.
+    if (!pairs.length)
+        return [];
     const input = comparisonLedgerInputArray(sessionsRaw);
     counters.inputRecords += Math.max(0, input.length - MAX_BULK_SESSIONS);
     const sessions = new Map();
@@ -311,7 +314,6 @@ export function buildBulkComparisonCandidates(sessionsRaw, pairsRaw, counters) {
         }
         sessions.set(item.id, item);
     }
-    const pairs = comparisonLedgerInputArray(pairsRaw);
     counters.inputRecords += Math.max(0, pairs.length - MAX_COMPARISON_LEDGER_BULK_PAIRS);
     const candidates = [];
     const seen = new Set();

package/packages/comparison/page-similarity.mjs

@@ -141,6 +141,7 @@ export function comparePageBaselines(rawReference, rawObserved) {
     const observed = normalizePageBaseline(rawObserved);
     if (!reference || !observed)
         return null;
+    const sameFingerprintVersion = reference.fingerprintVersion === observed.fingerprintVersion;
     const components = [
         digestComponent('normalized_html', 'Normalised HTML', 'Normalized-HTML', reference.normalizedHtml, observed.normalizedHtml),
         visibleTextComponent(reference.visibleText, observed.visibleText),
@@ -149,7 +150,7 @@ export function comparePageBaselines(rawReference, rawObserved) {
         faviconComponent(reference, observed),
         setComponent('resource_hosts', 'External resource hosts', 'host', reference.resourceHosts, observed.resourceHosts, (value) => value),
         setComponent('tracking_identifiers', 'Tracking identifiers', 'identifier', reference.trackingIdentifiers, observed.trackingIdentifiers, (value) => `${value.type}:${value.value}`),
-    ];
+    ].map((item) => sameFingerprintVersion || item.id === 'favicon' ? item : component(item.id, item.label, item.method, 'unavailable', 'Different fingerprint versions', 'These captures use different HTML fingerprint algorithms. Retain the older baseline and capture a new baseline to compare current page evidence.', true));
     const counts = { same: 0, overlap: 0, different: 0, notObserved: 0, unavailable: 0 };
     for (const item of components) {
         if (item.status === 'not_observed')
@@ -173,7 +174,9 @@ export function comparePageBaselines(rawReference, rawObserved) {
             complete: observed.complete,
             truncated: observed.truncated,
         },
-        partial: reference.truncated || observed.truncated || components.some((item) => item.partial),
+        partial: !reference.complete || !observed.complete
+            || reference.truncated || observed.truncated
+            || components.some((item) => item.partial),
         components,
         counts,
     };

package/packages/comparison/relationship-evidence.mjs

@@ -5,6 +5,7 @@
 // boundary.
 import { normalizeDomain } from "../cases/case-model.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, };
 export const MAX_RELATIONSHIP_ROWS = 2000;
@@ -16,6 +17,12 @@ export const MAX_TRACKING_IDS_PER_ROW = 30;
 export const MAX_OFFICIAL_ASSET_HOSTS_PER_ROW = 30;
 export const MAX_OFFICIAL_DOMAINS = 200;
 export const MAX_FAVICON_ROWS = 250;
+const ARRAY_RELATIONSHIP_FIELDS = {
+    nameserver_set: { field: 'nameservers', maximum: MAX_NAMESERVERS_PER_ROW },
+    ip_address: { field: 'ipAddresses', maximum: MAX_IPS_PER_ROW },
+    tracking_identifier: { field: 'trackingIdentifiers', maximum: MAX_TRACKING_IDS_PER_ROW },
+    official_asset: { field: 'officialAssetHosts', maximum: MAX_OFFICIAL_ASSET_HOSTS_PER_ROW },
+};
 const CONTROL_RE = /[\x00-\x1f\x7f]/;
 const FAVICON_SHA_RE = /^[a-f0-9]{64}$/i;
 const FAVICON_PHASH_RE = /^[a-f0-9]{16}$/i;
@@ -92,7 +99,7 @@ function tlsCertificateFingerprint(availability) {
     const certificate = record(tls?.certificate);
     const fingerprint = certificate?.fingerprintSha256;
     const status = tls?.status;
-    if (tls?.source !== 'tls' || !SUPPORTED_TLS_RELATIONSHIP_PROFILE_VERSIONS.some((version) => version === Number(tls?.profileVersion))
+    if (tls?.source !== 'tls' || !SUPPORTED_TLS_RELATIONSHIP_PROFILE_VERSIONS.some((version) => version === tls?.profileVersion)
         || typeof status !== 'string' || !['success', 'partial'].includes(status) || typeof fingerprint !== 'string'
         || fingerprint.length !== 64 || !CERTIFICATE_SHA_RE.test(fingerprint))
         return null;
@@ -131,6 +138,36 @@ export function relationshipObservation(rawAvailability, rawOfficialDomains = []
         ? availability.faviconHash.toLowerCase() : null;
     const faviconPHash = typeof availability.faviconPHash === 'string' && FAVICON_PHASH_RE.test(availability.faviconPHash)
         ? availability.faviconPHash.toLowerCase() : null;
+    const certificateFingerprint = tlsCertificateFingerprint(availability);
+    const dnsSource = relationshipSourceEvidence('dns', availability.dns);
+    const httpSource = relationshipSourceEvidence('http', availability.http);
+    const projectedSource = (source, truncated) => truncated
+        ? { ...source, complete: false, truncated: true } : source;
+    const sourceEvidence = {};
+    if (nameservers.values.length)
+        sourceEvidence.nameserver_set = [
+            // The compact availability nameserver list can be registration data or a
+            // DNS fallback. Its source is not distinguishable from this projection.
+            ...(Array.isArray(availability.nameservers) && availability.nameservers.length
+                ? [availability.source === 'dns' ? projectedSource(dnsSource, nameservers.truncated)
+                        : unknownRelationshipSource('registration_or_dns')] : []),
+            ...(Array.isArray(records.ns) && records.ns.length ? [projectedSource(dnsSource, nameservers.truncated)] : []),
+        ];
+    if (ipAddresses.values.length)
+        sourceEvidence.ip_address = [projectedSource(dnsSource, ipAddresses.truncated)];
+    if (certificateFingerprint)
+        sourceEvidence.certificate = [relationshipSourceEvidence('tls', availability.tls)];
+    if (trackingIdentifiers.values.length)
+        sourceEvidence.tracking_identifier = [
+            projectedSource(httpSource, trackingIdentifiers.truncated),
+            relationshipSourceEvidence('page_identity', availability.pageIdentity),
+        ];
+    if (officialAssetHosts.length)
+        sourceEvidence.official_asset = [projectedSource(httpSource, assets.truncated
+                || officialDomainSource.length > MAX_OFFICIAL_DOMAINS)];
+    // A homepage timestamp does not date the independently fetched favicon.
+    if (faviconHash || faviconPHash)
+        sourceEvidence.favicon = [unknownRelationshipSource('favicon')];
     return {
         version: RELATIONSHIP_EVIDENCE_VERSION,
         nameservers: nameservers.values,
@@ -139,7 +176,8 @@ export function relationshipObservation(rawAvailability, rawOfficialDomains = []
         officialAssetHosts,
         faviconHash,
         faviconPHash,
-        certificateFingerprint: tlsCertificateFingerprint(availability),
+        certificateFingerprint,
+        sourceEvidence,
         truncated: nameservers.truncated || ipAddresses.truncated || trackingIdentifiers.truncated || assets.truncated
             || officialDomainSource.length > MAX_OFFICIAL_DOMAINS,
     };
@@ -152,7 +190,22 @@ function addBucket(buckets, value, domain) {
     buckets.get(value)?.add(domain);
 }
 function group(type, label, method, value, domains, description, normalizedValue = value) {
-    return { type, label, method, value, normalizedValue, domains, description };
+    return { type, label, method, value, normalizedValue, domains, description, ...qualifyRelationshipSources([], domains) };
+}
+function contributesToGroup(observation, item, domain) {
+    if (item.type === 'certificate')
+        return typeof observation.certificateFingerprint === 'string'
+            && observation.certificateFingerprint.toLowerCase() === item.normalizedValue;
+    if (item.type === 'nameserver_set')
+        return Array.isArray(observation.nameservers)
+            && [...new Set(observation.nameservers.slice(0, MAX_NAMESERVERS_PER_ROW).map(hostname).filter(Boolean))].sort().join(' · ') === item.normalizedValue;
+    const field = ARRAY_RELATIONSHIP_FIELDS[item.type];
+    if (field)
+        return Array.isArray(observation[field.field]) && observation[field.field].slice(0, field.maximum).some((value) => (item.type === 'ip_address' ? ipAddress(value) : item.type === 'official_asset' ? hostname(value) : value) === item.normalizedValue);
+    return item.type === 'favicon' && item.normalizedValue.split('|').includes(`${domain}=${[
+        typeof observation.faviconHash === 'string' && FAVICON_SHA_RE.test(observation.faviconHash) ? `sha256:${observation.faviconHash.toLowerCase()}` : '',
+        typeof observation.faviconPHash === 'string' && FAVICON_PHASH_RE.test(observation.faviconPHash) ? `dhash:${observation.faviconPHash.toLowerCase()}` : '',
+    ].filter(Boolean).join(',')}`);
 }
 /**
  * @param {Array<{domain?:unknown,trusted?:unknown,relationship?:unknown}>} rawRows
@@ -164,7 +217,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 || observation.version !== RELATIONSHIP_EVIDENCE_VERSION)
+        if (!domain || raw?.trusted || !observation || ![2, RELATIONSHIP_EVIDENCE_VERSION].some((version) => version === observation.version))
             continue;
         rows.push({ domain, observation });
         if (observation.truncated === true)
@@ -245,11 +298,35 @@ export function buildScanRelationships(rawRows) {
     output.sort((left, right) => (Number(order.get(left.type)) - Number(order.get(right.type))) || left.value.localeCompare(right.value) || left.domains.join('|').localeCompare(right.domains.join('|')));
     if (output.length > MAX_RELATIONSHIP_GROUPS)
         truncated = true;
+    const rowsByDomain = new Map();
+    for (const row of rows) {
+        const members = rowsByDomain.get(row.domain) ?? [];
+        members.push(row);
+        rowsByDomain.set(row.domain, members);
+    }
     const groups = output.slice(0, MAX_RELATIONSHIP_GROUPS).map((item) => {
-        if (item.domains.length <= MAX_RELATIONSHIP_DOMAINS)
-            return item;
-        truncated = true;
-        return { ...item, domains: item.domains.slice(0, MAX_RELATIONSHIP_DOMAINS) };
+        const domains = item.domains.slice(0, MAX_RELATIONSHIP_DOMAINS);
+        let groupTruncated = item.domains.length > domains.length || input.length > MAX_RELATIONSHIP_ROWS;
+        if (groupTruncated)
+            truncated = true;
+        const contributors = [];
+        for (const domain of domains)
+            for (const { observation } of rowsByDomain.get(domain) ?? []) {
+                if (!contributesToGroup(observation, item, domain))
+                    continue;
+                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
+                    ? normalizeRelationshipSourceProjection(observation.sourceEvidence) : {};
+                for (const source of projection[item.type] ?? [unknownRelationshipSource()]) {
+                    if (contributors.length >= MAX_RELATIONSHIP_DOMAINS * MAX_RELATIONSHIP_SOURCES_PER_DOMAIN)
+                        groupTruncated = true;
+                    else
+                        contributors.push({ domain, ...source });
+                }
+            }
+        return { ...item, domains, ...qualifyRelationshipSources(contributors, domains, { truncated: groupTruncated, type: item.type }) };
     });
     return {
         version: RELATIONSHIP_EVIDENCE_VERSION,

package/packages/comparison/relationship-provenance.mjs

@@ -0,0 +1,93 @@
+// Only the source metadata needed to qualify an observed relationship crosses
+// this boundary. Collection and retention times are never source-time fallbacks.
+import { normalizeDomain } from "../cases/case-model.mjs";
+import { normalizeExplicitIsoTimestamp, readObservationEnvelope } from "../evidence/observation.mjs";
+export const RELATIONSHIP_TYPES = Object.freeze([
+    'nameserver_set', 'ip_address', 'certificate', 'tracking_identifier', 'favicon', 'official_asset',
+]);
+const SOURCES = ['dns', 'tls', 'http', 'page_identity', 'favicon', 'registration_or_dns', 'unknown'];
+const SOURCES_BY_TYPE = {
+    nameserver_set: ['dns', 'registration_or_dns'], ip_address: ['dns'], certificate: ['tls'],
+    tracking_identifier: ['http', 'page_identity'], favicon: ['favicon'], official_asset: ['http'],
+};
+const STATUSES = ['success', 'partial', 'not_found', 'skipped', 'error', 'unsupported', 'not_applicable', 'unknown'];
+export const MAX_RELATIONSHIP_SOURCES_PER_DOMAIN = 3;
+export const MAX_RELATIONSHIP_SOURCE_DOMAINS = 50;
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+export function unknownRelationshipSource(source = 'unknown') {
+    return { source, status: 'unknown', observedAt: null, complete: false, truncated: null };
+}
+export function relationshipSourceEvidence(source, raw) {
+    const result = readObservationEnvelope(raw);
+    if (result.state !== 'supported' || result.observation.source !== source) {
+        return { ...unknownRelationshipSource(source), status: result.state === 'unsupported' ? 'unsupported' : 'unknown' };
+    }
+    return normalizeSource({ ...result.observation, truncated: record(raw).truncated });
+}
+function normalizeSource(raw, type) {
+    const value = record(raw);
+    const source = SOURCES.find((candidate) => candidate === value.source) ?? 'unknown';
+    if (type && source !== 'unknown' && !SOURCES_BY_TYPE[type].includes(source))
+        return unknownRelationshipSource();
+    const status = STATUSES.find((candidate) => candidate === value.status) ?? 'unknown';
+    const observedAt = normalizeExplicitIsoTimestamp(value.observedAt);
+    const truncated = typeof value.truncated === 'boolean' ? value.truncated : null;
+    return {
+        source, status, observedAt, truncated,
+        complete: source !== 'unknown' && source !== 'registration_or_dns' && status === 'success'
+            && value.complete === true && truncated === false && observedAt !== null,
+    };
+}
+export function normalizeRelationshipSourceProjection(raw) {
+    const value = record(raw);
+    const output = {};
+    for (const type of RELATIONSHIP_TYPES) {
+        if (!Array.isArray(value[type]))
+            continue;
+        const candidates = value[type];
+        output[type] = candidates.slice(0, MAX_RELATIONSHIP_SOURCES_PER_DOMAIN).map((candidate) => {
+            const source = normalizeSource(candidate, type);
+            return candidates.length > MAX_RELATIONSHIP_SOURCES_PER_DOMAIN ? { ...source, complete: false, truncated: true } : source;
+        });
+    }
+    return output;
+}
+/** Missing, malformed or omitted contributors cannot make a group complete. */
+export function qualifyRelationshipSources(raw, rawDomains, options = {}) {
+    const domains = [...new Set(rawDomains.slice(0, MAX_RELATIONSHIP_SOURCE_DOMAINS * 2).map(normalizeDomain).filter(Boolean))].slice(0, MAX_RELATIONSHIP_SOURCE_DOMAINS);
+    const allowed = new Set(domains);
+    const candidates = Array.isArray(raw) ? raw : [];
+    const maximum = MAX_RELATIONSHIP_SOURCE_DOMAINS * MAX_RELATIONSHIP_SOURCES_PER_DOMAIN;
+    const byDomain = new Map();
+    let omitted = options.truncated === true || rawDomains.length > MAX_RELATIONSHIP_SOURCE_DOMAINS || candidates.length > maximum;
+    for (const candidate of candidates.slice(0, maximum)) {
+        const value = record(candidate);
+        const domain = normalizeDomain(value.domain);
+        if (!domain || !allowed.has(domain)) {
+            omitted = true;
+            continue;
+        }
+        const contribution = { domain, ...normalizeSource(value, options.type) };
+        const entries = byDomain.get(domain) ?? new Map();
+        const key = JSON.stringify(contribution);
+        if (!entries.has(key) && entries.size >= MAX_RELATIONSHIP_SOURCES_PER_DOMAIN)
+            omitted = true;
+        else
+            entries.set(key, contribution);
+        byDomain.set(domain, entries);
+    }
+    const sourceEvidence = domains.sort().flatMap((domain) => {
+        const entries = byDomain.get(domain);
+        return entries?.size ? [...entries.values()].sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)))
+            : [{ domain, ...unknownRelationshipSource() }];
+    });
+    const observedAt = sourceEvidence.length && sourceEvidence.every((entry) => entry.observedAt !== null)
+        ? sourceEvidence.map((entry) => entry.observedAt).sort().at(-1) ?? null : null;
+    return {
+        sourceEvidence, observedAt,
+        complete: sourceEvidence.length > 0 && !omitted && sourceEvidence.every((entry) => entry.complete),
+        truncated: omitted || sourceEvidence.some((entry) => entry.truncated === true),
+    };
+}