@slicedearth/whoisleuth-cli 2.3.0 → 2.5.1

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. */
@@ -88,6 +88,31 @@ 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,

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/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

@@ -295,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();
@@ -310,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/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) {
@@ -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')