@slicedearth/whoisleuth-cli 2.3.0 → 2.5.1

package/packages/workspace/hostile-input.mjs

@@ -1,4 +1,5 @@
 import { MAX_WORKSPACE_INPUT_ARRAY_LENGTH, MAX_WORKSPACE_INPUT_GRAPH_DEPTH, MAX_WORKSPACE_INPUT_GRAPH_NODES, MAX_WORKSPACE_INPUT_OBJECT_KEYS, MAX_WORKSPACE_INPUT_STRING_CODE_UNITS, } from "../contracts/workspace-portability.mjs";
+import { boundedJsonLimitsForBytes } from "../analysis/bounded-json.mjs";
 function inputError(label, detail) {
     return new TypeError(`${label} must be bounded ordinary JSON data; ${detail}.`);
 }
@@ -27,9 +28,7 @@ function ownDataDescriptors(value, label) {
         return [key, descriptor];
     });
 }
-export function ordinaryWorkspaceRecord(value, label = 'Workspace input') {
-    if (!value || typeof value !== 'object' || Array.isArray(value))
-        return null;
+function ordinaryRecordDescriptors(value, label) {
     let prototype;
     try {
         prototype = Object.getPrototypeOf(value);
@@ -47,19 +46,33 @@ export function ordinaryWorkspaceRecord(value, label = 'Workspace input') {
     if (descriptors.some(([, descriptor]) => !descriptor.enumerable)) {
         throw inputError(label, 'non-enumerable object fields are not supported');
     }
+    return descriptors;
+}
+export function ordinaryWorkspaceRecord(value, label = 'Workspace input') {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    ordinaryRecordDescriptors(value, label);
     return value;
 }
-export function assertWorkspaceInputGraph(value, label = 'Workspace input') {
+export function assertWorkspaceInputGraph(value, label = 'Workspace input', options = {}) {
+    const limits = options.maximumBytes === undefined ? null : boundedJsonLimitsForBytes(options.maximumBytes);
+    const maximumStringCodeUnits = limits?.maximumStringCodeUnits ?? MAX_WORKSPACE_INPUT_STRING_CODE_UNITS;
     const pending = [{ value, depth: 0, label }];
     const seen = new WeakSet();
     let nodes = 0;
+    let values = 0;
+    let keys = 0;
     let stringCodeUnits = 0;
     while (pending.length) {
         const current = pending.pop();
         const candidate = current.value;
+        values += 1;
+        if (limits && values > limits.maximumValues) {
+            throw inputError(label, 'the graph exceeds the byte-budgeted value ceiling');
+        }
         if (typeof candidate === 'string') {
             stringCodeUnits += candidate.length;
-            if (stringCodeUnits > MAX_WORKSPACE_INPUT_STRING_CODE_UNITS) {
+            if (stringCodeUnits > maximumStringCodeUnits) {
                 throw inputError(label, 'aggregate text exceeds the string ceiling');
             }
             continue;
@@ -76,7 +89,7 @@ export function assertWorkspaceInputGraph(value, label = 'Workspace input') {
             throw inputError(label, 'the nesting depth exceeds the graph ceiling');
         }
         nodes += 1;
-        if (nodes > MAX_WORKSPACE_INPUT_GRAPH_NODES) {
+        if (!limits && nodes > MAX_WORKSPACE_INPUT_GRAPH_NODES) {
             throw inputError(label, 'the graph exceeds the node ceiling');
         }
         if (seen.has(candidate))
@@ -118,8 +131,16 @@ export function assertWorkspaceInputGraph(value, label = 'Workspace input') {
             }
             continue;
         }
-        const record = ordinaryWorkspaceRecord(candidate, current.label);
-        const descriptors = ownDataDescriptors(record, current.label);
+        const descriptors = ordinaryRecordDescriptors(candidate, current.label);
+        if (limits) {
+            keys += descriptors.length;
+            if (keys > limits.maximumKeys)
+                throw inputError(label, 'the graph exceeds the byte-budgeted key ceiling');
+            stringCodeUnits += descriptors.reduce((total, [key]) => total + key.length, 0);
+            if (stringCodeUnits > maximumStringCodeUnits) {
+                throw inputError(label, 'aggregate text exceeds the string ceiling');
+            }
+        }
         for (const [key, descriptor] of descriptors) {
             pending.push({
                 value: descriptor.value,

package/packages/workspace/investigation-guide.mjs

@@ -1,4 +1,4 @@
-import { normalizeDomain } from "../cases/case-model.mjs";
+import { normalizeDomain } from "../evidence/domain-name.mjs";
 import { parse } from 'tldts';
 import { normalizeExplicitIsoTimestamp } from "../evidence/observation.mjs";
 export const INVESTIGATION_GUIDE_SCHEMA = 'whoisleuth.investigation-recipe';
@@ -13,7 +13,7 @@ export const MAX_INVESTIGATION_GUIDE_TIMESTAMP_LENGTH = 64;
 export const MAX_INVESTIGATION_GUIDE_SERIALIZED_BYTES = 12_288;
 export const MAX_INVESTIGATION_GUIDE_EXPORT_BYTES = 16_384;
 const CONTROL_RE = /[\x00-\x1f\x7f]/u;
-const SAFE_TEMPLATE_ID_RE = /^[A-Za-z0-9_-]{1,128}$/u;
+export const SAFE_TEMPLATE_ID_RE = /^[A-Za-z0-9_-]{1,128}$/u;
 const GUIDE_STATUSES = new Set(['active', 'paused']);
 const GUIDE_OUTCOMES = new Set(['pending', 'complete', 'partial', 'skipped']);
 function stage(id, workspace, label, detail, expectedEvidence, requestImpact, prerequisite, completionCriteria, instructions, requiresApproval) {

package/packages/workspace/investigation-template-model.mjs

@@ -1,8 +1,27 @@
-import { INVESTIGATION_RECIPES, normalizeInvestigationGuideTemplateSnapshot, } from "./investigation-guide.mjs";
+import { INVESTIGATION_RECIPES, normalizeInvestigationGuideTemplateSnapshot, SAFE_TEMPLATE_ID_RE, } from "./investigation-guide.mjs";
 import { normalizeExplicitIsoTimestamp } from "../evidence/observation.mjs";
 import { assertWorkspaceDeclaredVersion, assertWorkspaceInputGraph, assertWorkspacePortableVersion, ordinaryWorkspaceRecord } from "./hostile-input.mjs";
+import { exact, HEX_DIGEST_RE, text } from "../evidence/artifact-structure.mjs";
+import { SORTED_JSON_V2 } from "../evidence/artifact-integrity.mjs";
 import { INVESTIGATION_TEMPLATE_SCHEMA, INVESTIGATION_TEMPLATE_SUPPORTED_VERSIONS, INVESTIGATION_TEMPLATE_VERSION, MAX_INVESTIGATION_TEMPLATES, MAX_INVESTIGATION_TEMPLATE_STORE_BYTES, } from "../contracts/workspace-portability.mjs";
 export { INVESTIGATION_TEMPLATE_SCHEMA, INVESTIGATION_TEMPLATE_SUPPORTED_VERSIONS, INVESTIGATION_TEMPLATE_VERSION, MAX_INVESTIGATION_TEMPLATES, MAX_INVESTIGATION_TEMPLATE_IMPORT_BYTES, MAX_INVESTIGATION_TEMPLATE_STORE_BYTES, } from "../contracts/workspace-portability.mjs";
+export function readTemplateLessonRevision(raw) {
+    if (raw === undefined)
+        return undefined;
+    assertWorkspaceInputGraph(raw, 'Template revision provenance');
+    const value = exact(raw, ['parentTemplateId', 'parentContentSha256', 'lessonContentSha256', 'canonicalization', 'applicability', 'rationale'], 'Template revision provenance');
+    if (typeof value.parentTemplateId !== 'string' || !SAFE_TEMPLATE_ID_RE.test(value.parentTemplateId)
+        || value.canonicalization !== SORTED_JSON_V2
+        || typeof value.parentContentSha256 !== 'string' || !HEX_DIGEST_RE.test(value.parentContentSha256)
+        || typeof value.lessonContentSha256 !== 'string' || !HEX_DIGEST_RE.test(value.lessonContentSha256))
+        throw new TypeError('Template revision provenance is invalid.');
+    const applicability = text(value.applicability, 'Template applicability', 400).trim();
+    const rationale = text(value.rationale, 'Template revision reason', 400).trim();
+    if (!applicability || !rationale)
+        throw new TypeError('Template applicability and revision reason must not be empty.');
+    return { parentTemplateId: value.parentTemplateId, parentContentSha256: value.parentContentSha256, lessonContentSha256: value.lessonContentSha256,
+        canonicalization: SORTED_JSON_V2, applicability, rationale };
+}
 function record(value) {
     return ordinaryWorkspaceRecord(value, 'Investigation-template input');
 }
@@ -17,11 +36,13 @@ function template(raw) {
     const snapshot = normalizeInvestigationGuideTemplateSnapshot(value);
     const createdAt = timestamp(value?.createdAt);
     const updatedAt = timestamp(value?.updatedAt);
+    const lessonRevision = readTemplateLessonRevision(value?.lessonRevision);
     return snapshot && createdAt && updatedAt
-        ? { ...snapshot, createdAt, updatedAt }
+        ? { ...snapshot, createdAt, updatedAt, ...(lessonRevision ? { lessonRevision } : {}) }
         : null;
 }
 export function normalizeInvestigationTemplate(raw) {
+    assertWorkspaceInputGraph(raw, 'Investigation template');
     return template(raw);
 }
 export function normalizeInvestigationTemplateStore(raw) {
@@ -33,6 +54,9 @@ export function normalizeInvestigationTemplateStore(raw) {
         throw new Error(`Investigation-template schema ${String(value.version)} is unsupported; no data was changed.`);
     }
     const source = Array.isArray(raw) ? raw : Array.isArray(value?.templates) ? value.templates : [];
+    if (value?.version === 2 && source.some(candidate => record(candidate)?.lessonRevision !== undefined)) {
+        throw new Error('Template revision provenance requires schema 3; no data was changed.');
+    }
     const templates = [];
     const seen = new Set();
     for (const candidate of source.slice(0, MAX_INVESTIGATION_TEMPLATES * 2)) {
@@ -85,6 +109,9 @@ export function saveInvestigationTemplate(localRaw, candidateRaw) {
     if (!candidate)
         throw new Error('The investigation template is incomplete or invalid.');
     const local = normalizeInvestigationTemplateStore(localRaw).templates;
+    if (!local.some((item) => item.id === candidate.id) && local.length >= MAX_INVESTIGATION_TEMPLATES) {
+        throw new Error(`Investigation-template storage is full (${MAX_INVESTIGATION_TEMPLATES} templates). Export and remove a template before saving another; no templates were changed.`);
+    }
     return normalizeInvestigationTemplateStore([
         candidate,
         ...local.filter((item) => item.id !== candidate.id),
@@ -126,11 +153,23 @@ export function mergeInvestigationTemplates(localRaw, incomingRaw) {
     const byId = new Map(local.map((item) => [item.id, item]));
     let added = 0;
     let updated = 0;
+    let skipped = 0;
     for (const item of incoming) {
-        if (byId.has(item.id))
+        const existing = byId.get(item.id);
+        if (existing) {
+            if (item.updatedAt <= existing.updatedAt) {
+                skipped += 1;
+                continue;
+            }
             updated += 1;
-        else
+        }
+        else {
+            if (byId.size >= MAX_INVESTIGATION_TEMPLATES) {
+                skipped += 1;
+                continue;
+            }
             added += 1;
+        }
         byId.set(item.id, item);
     }
     const templates = normalizeInvestigationTemplateStore([...byId.values()]).templates;
@@ -138,7 +177,7 @@ export function mergeInvestigationTemplates(localRaw, incomingRaw) {
         templates,
         added,
         updated,
-        skipped: Math.max(0, incoming.length - added - updated),
-        pruned: Math.max(0, byId.size - templates.length),
+        skipped,
+        pruned: 0,
     };
 }

package/packages/workspace/page-baseline.mjs

@@ -2,15 +2,15 @@
 // deliberately accepts only bounded, normalized page-identity fields. Raw
 // HTML, URLs, headers, redirect inventories, and parser diagnostics never
 // cross this storage boundary.
-import { normalizeDomain } from "../cases/case-model.mjs";
-import { isInformativePerceptualHash as isInformativeFaviconHash } from "../../lib/perceptual-hash-comparison.mjs";
+import { normalizeDomain } from "../evidence/domain-name.mjs";
+import { isInformativePerceptualHash as isInformativeFaviconHash } from "../analysis/perceptual-hash-comparison.mjs";
 import { normalizeExplicitIsoTimestamp } from "../evidence/observation.mjs";
-import { MAX_BASELINE_IDENTIFIERS, MAX_BASELINE_RESOURCE_HOSTS, MAX_BASELINE_TITLE_LENGTH, PAGE_BASELINE_VERSION, PAGE_FINGERPRINT_VERSION, PAGE_IDENTITY_VERSION, } from "../contracts/workspace-portability.mjs";
-export { MAX_BASELINE_IDENTIFIERS, MAX_BASELINE_RESOURCE_HOSTS, MAX_BASELINE_TITLE_LENGTH, PAGE_BASELINE_VERSION, PAGE_FINGERPRINT_VERSION, PAGE_IDENTITY_VERSION, } from "../contracts/workspace-portability.mjs";
+import { PAGE_FINGERPRINT_TOKEN_LIMITS } from "../contracts/page-fingerprints.mjs";
+import { MAX_BASELINE_IDENTIFIERS, MAX_BASELINE_RESOURCE_HOSTS, MAX_BASELINE_TITLE_LENGTH, PAGE_BASELINE_VERSION, PAGE_FINGERPRINT_PARSERS, PAGE_IDENTITY_VERSION, } from "../contracts/workspace-portability.mjs";
+export { MAX_BASELINE_IDENTIFIERS, MAX_BASELINE_RESOURCE_HOSTS, MAX_BASELINE_TITLE_LENGTH, PAGE_BASELINE_VERSION, PAGE_FINGERPRINT_VERSION, PAGE_FINGERPRINT_PARSERS, PAGE_IDENTITY_VERSION, } from "../contracts/workspace-portability.mjs";
 const SHA256_RE = /^[a-f0-9]{64}$/i;
 const SIMHASH_RE = /^[a-f0-9]{16}$/i;
 const CONTROL_RE = /[\x00-\x1f\x7f]/;
-const MAX_HTML_TOKENS = 4096;
 const MAX_TEXT_TOKENS = 8192;
 const MAX_FORMS = 50;
 const MAX_FORM_CONTROLS = 500;
@@ -50,12 +50,12 @@ function shaComponent(raw, countKey, maximum) {
         truncated: value.truncated === true,
     };
 }
-function visibleTextComponent(raw) {
+function visibleTextComponent(raw, maximum = MAX_TEXT_TOKENS) {
     const value = record(raw);
     if (!value || value.algorithm !== 'simhash64-v1' || typeof value.value !== 'string' || !SIMHASH_RE.test(value.value))
         return null;
-    const tokenCount = count(value.tokenCount, MAX_TEXT_TOKENS);
-    const featureCount = count(value.featureCount, MAX_TEXT_TOKENS);
+    const tokenCount = count(value.tokenCount, maximum);
+    const featureCount = count(value.featureCount, maximum);
     if (tokenCount === null || featureCount === null)
         return null;
     return {
@@ -66,20 +66,21 @@ function visibleTextComponent(raw) {
         truncated: value.truncated === true,
     };
 }
-function domComponent(raw) {
+function domComponent(raw, fingerprintVersion) {
     const value = record(raw);
-    if (!value || value.algorithm !== 'sha256' || value.parser !== 'static-tag-sequence-v1')
+    if (!value || value.algorithm !== 'sha256' || value.parser !== PAGE_FINGERPRINT_PARSERS[fingerprintVersion])
         return null;
     const digest = sha256(value.value);
-    const nodeCount = count(value.nodeCount, MAX_HTML_TOKENS);
+    const maximum = PAGE_FINGERPRINT_TOKEN_LIMITS[fingerprintVersion];
+    const nodeCount = count(value.nodeCount, maximum);
     if (!digest || nodeCount === null)
         return null;
-    const similarity = value.similarity == null ? null : visibleTextComponent(value.similarity);
+    const similarity = value.similarity == null ? null : visibleTextComponent(value.similarity, maximum);
     return {
         algorithm: 'sha256',
         value: digest,
         nodeCount,
-        parser: 'static-tag-sequence-v1',
+        parser: PAGE_FINGERPRINT_PARSERS[fingerprintVersion],
         truncated: value.truncated === true,
         ...(value.similarity == null ? {} : { similarity }),
     };
@@ -175,11 +176,13 @@ export function normalizePageBaseline(raw) {
     const lookupDomain = normalizeDomain(value.lookupDomain);
     const observedAt = timestamp(value.observedAt);
     const pageIdentityVersion = count(value.pageIdentityVersion, PAGE_IDENTITY_VERSION);
-    const fingerprintVersion = count(value.fingerprintVersion, PAGE_FINGERPRINT_VERSION);
-    const normalizedHtml = shaComponent(value.normalizedHtml, 'tokenCount', MAX_HTML_TOKENS);
-    const domStructure = domComponent(value.domStructure);
+    if (typeof value.fingerprintVersion !== 'number' || !Object.hasOwn(PAGE_FINGERPRINT_PARSERS, value.fingerprintVersion))
+        return null;
+    const fingerprintVersion = value.fingerprintVersion;
+    const normalizedHtml = shaComponent(value.normalizedHtml, 'tokenCount', PAGE_FINGERPRINT_TOKEN_LIMITS[fingerprintVersion]);
+    const domStructure = domComponent(value.domStructure, fingerprintVersion);
     if (!domain || !lookupDomain || !observedAt || pageIdentityVersion !== PAGE_IDENTITY_VERSION
-        || fingerprintVersion !== PAGE_FINGERPRINT_VERSION || !normalizedHtml || !domStructure)
+        || !normalizedHtml || !domStructure)
         return null;
     const visibleText = value.visibleText == null ? null : visibleTextComponent(value.visibleText);
     const formStructure = value.formStructure == null ? null : formComponent(value.formStructure);

package/packages/workspace/relationship-observation-model.mjs

@@ -1,16 +1,11 @@
-import { normalizeDomain } from "../cases/case-model.mjs";
+import { normalizeDomain } from "../evidence/domain-name.mjs";
 import { normalizeExplicitIsoTimestamp } from "../evidence/observation.mjs";
+import { RELATIONSHIP_EVIDENCE_VERSION, RELATIONSHIP_SOURCE_PROVENANCE_VERSION, RELATIONSHIP_PUBLIC_ADDRESS_VERSION } from "../contracts/offline-comparison.mjs";
+import { RELATIONSHIP_TYPES, qualifyRelationshipSources, isNonPublicAddressRelationship, NON_PUBLIC_RELATIONSHIP_LIMITATION, FAVICON_RELATIONSHIP_DESCRIPTION } from "../comparison/relationship-provenance.mjs";
 import { assertWorkspaceDeclaredVersion, assertWorkspaceInputGraph, assertWorkspacePortableVersion, ordinaryWorkspaceRecord } from "./hostile-input.mjs";
 import { MAX_RELATIONSHIP_OBSERVATIONS, MAX_RELATIONSHIP_OBSERVATION_DOMAINS, MAX_RELATIONSHIP_OBSERVATION_INPUTS, MAX_RELATIONSHIP_OBSERVATION_LIMITATIONS, MAX_RELATIONSHIP_OBSERVATION_STORE_BYTES, MAX_RELATIONSHIP_OBSERVATION_VALUE_LENGTH, RELATIONSHIP_OBSERVATION_SCHEMA, RELATIONSHIP_OBSERVATION_SCHEMA_VERSION, } from "../contracts/workspace-portability.mjs";
 export { MAX_RELATIONSHIP_OBSERVATIONS, MAX_RELATIONSHIP_OBSERVATION_DOMAINS, MAX_RELATIONSHIP_OBSERVATION_INPUTS, MAX_RELATIONSHIP_OBSERVATION_LIMITATIONS, MAX_RELATIONSHIP_OBSERVATION_STORE_BYTES, MAX_RELATIONSHIP_OBSERVATION_VALUE_LENGTH, RELATIONSHIP_OBSERVATION_SCHEMA, RELATIONSHIP_OBSERVATION_SCHEMA_VERSION, } from "../contracts/workspace-portability.mjs";
-export const RELATIONSHIP_OBSERVATION_TYPES = Object.freeze([
-    'nameserver_set',
-    'ip_address',
-    'certificate',
-    'tracking_identifier',
-    'favicon',
-    'official_asset',
-]);
+export const RELATIONSHIP_OBSERVATION_TYPES = RELATIONSHIP_TYPES;
 const CONTROL_RE = /[\u0000-\u001f\u007f]/u;
 const SAFE_ID_RE = /^relationship-[a-z0-9]{1,16}-[a-z0-9]{1,16}$/u;
 const SHA256_RE = /^[a-f0-9]{64}$/iu;
@@ -39,9 +34,9 @@ const TYPE_METADATA = Object.freeze({
         description: 'These pages exposed the same recognised public tracking identifier in bounded static HTML.',
     }),
     favicon: Object.freeze({
-        label: 'Similar favicon',
+        label: 'Connected favicon matches',
         method: 'Exact SHA-256 or perceptual dHash distance ≤ 6',
-        description: 'These domains used an identical or perceptually similar favicon in the retained scan.',
+        description: FAVICON_RELATIONSHIP_DESCRIPTION,
     }),
     official_asset: Object.freeze({
         label: 'Official asset host match',
@@ -205,7 +200,7 @@ export function relationshipObservationId(raw) {
 }
 export function relationshipObservationStoreVersion(raw) {
     const value = record(raw);
-    return positiveInteger(value?.version);
+    return typeof value?.version === 'number' && Number.isSafeInteger(value.version) && value.version > 0 ? value.version : null;
 }
 function observationList(raw) {
     if (Array.isArray(raw))
@@ -213,7 +208,7 @@ function observationList(raw) {
     const value = record(raw);
     return Array.isArray(value?.observations) ? value.observations : [];
 }
-export function normalizeRelationshipObservation(raw) {
+export function normalizeRelationshipObservation(raw, sourceStoreVersion = RELATIONSHIP_OBSERVATION_SCHEMA_VERSION) {
     const value = record(raw);
     if (!value || typeof value.type !== 'string' || !TYPES.has(value.type))
         return null;
@@ -230,34 +225,50 @@ export function normalizeRelationshipObservation(raw) {
     const id = observationId(canonical);
     const observedAt = timestamp(value.observedAt);
     const retainedAt = timestamp(value.retainedAt);
-    if (!observedAt || !retainedAt)
+    if (!retainedAt || (value.observedAt !== null && !observedAt))
         return null;
+    const sourceVersion = positiveInteger(value.sourceVersion) || 1;
+    if (value.sourceVersion !== undefined && !positiveInteger(value.sourceVersion))
+        throw new TypeError('This retained relationship uses an unsupported source-evidence version; no evidence was interpreted.');
+    if (sourceVersion > RELATIONSHIP_EVIDENCE_VERSION)
+        throw new TypeError('This retained relationship uses a newer source-evidence version; no evidence was interpreted.');
+    if (sourceStoreVersion === 1 && sourceVersion > 2)
+        throw new TypeError('Relationship schema 1 cannot contain newer source evidence; no evidence was interpreted.');
+    const qualified = qualifyRelationshipSources(sourceVersion >= RELATIONSHIP_SOURCE_PROVENANCE_VERSION ? value.sourceEvidence : [], domains, { truncated: value.truncated === true, type });
+    const nonPublicAddress = isNonPublicAddressRelationship(type, normalizedValue);
     return {
         id,
         type,
-        label: metadata.label,
+        label: nonPublicAddress ? 'Shared non-public DNS answer' : metadata.label,
         method: metadata.method,
         normalizedValue,
         displayValue: type === 'favicon' ? '' : normalizedValue,
         domains,
-        description: metadata.description,
+        description: nonPublicAddress ? NON_PUBLIC_RELATIONSHIP_LIMITATION : metadata.description,
         classification: 'derived',
         source: 'bulk_relationship_analysis',
-        sourceVersion: positiveInteger(value.sourceVersion) || 1,
-        observedAt,
+        sourceVersion,
+        // Legacy scan timestamps remain available, but cannot qualify missing
+        // contributing-source timestamps or turn the old complete flag into proof.
+        observedAt: qualified.observedAt ?? (observedAt || null),
+        sourceEvidence: qualified.sourceEvidence,
         retainedAt,
-        complete: value.complete === true,
-        truncated: value.truncated === true
+        complete: value.complete === true && qualified.complete,
+        truncated: qualified.truncated
             || (Array.isArray(value.domains) && value.domains.length > MAX_RELATIONSHIP_OBSERVATION_DOMAINS),
-        limitations: observationLimitations(value.limitations),
+        limitations: observationLimitations([...(nonPublicAddress ? [NON_PUBLIC_RELATIONSHIP_LIMITATION] : []), ...(Array.isArray(value.limitations) ? value.limitations : [])]),
     };
 }
 export function normalizeRelationshipObservationStore(raw) {
     assertWorkspaceInputGraph(raw, 'Relationship-observation store');
     assertWorkspaceDeclaredVersion(raw, 'Relationship-observation store');
+    const sourceStoreVersion = relationshipObservationStoreVersion(raw) ?? RELATIONSHIP_OBSERVATION_SCHEMA_VERSION;
+    if (sourceStoreVersion > RELATIONSHIP_OBSERVATION_SCHEMA_VERSION) {
+        throw new TypeError(`This relationship-observation store uses newer schema ${sourceStoreVersion}; no evidence was interpreted.`);
+    }
     const byId = new Map();
     for (const candidate of observationList(raw).slice(0, MAX_RELATIONSHIP_OBSERVATION_INPUTS)) {
-        const observation = normalizeRelationshipObservation(candidate);
+        const observation = normalizeRelationshipObservation(candidate, sourceStoreVersion);
         if (!observation)
             continue;
         const existing = byId.get(observation.id);
@@ -283,31 +294,40 @@ export function createRelationshipObservation(raw, options = {}) {
         throw new Error('That relationship does not contain a supported bounded value and at least one valid domain.');
     }
     const now = new Date().toISOString();
-    const observedAt = Object.hasOwn(options, 'observedAt') ? timestamp(options.observedAt) : now;
+    const sourceVersion = Object.hasOwn(options, 'sourceVersion') ? positiveInteger(options.sourceVersion) : RELATIONSHIP_EVIDENCE_VERSION;
+    if (!sourceVersion || sourceVersion > RELATIONSHIP_EVIDENCE_VERSION)
+        throw new TypeError('This relationship needs a supported source-evidence version.');
+    const nonPublicAddress = isNonPublicAddressRelationship(type, normalizedValue);
+    if (nonPublicAddress && sourceVersion >= RELATIONSHIP_PUBLIC_ADDRESS_VERSION)
+        throw new TypeError('Non-public DNS answers cannot be retained as new public-infrastructure relationships.');
+    const qualified = qualifyRelationshipSources(sourceVersion >= RELATIONSHIP_SOURCE_PROVENANCE_VERSION ? raw.sourceEvidence : [], domains, { truncated: options.truncated === true, type });
+    // Older callers can supply their original scan timestamp. It does not
+    // qualify the missing source metadata, and an explicit current projection
+    // never substitutes that timestamp for unknown contributing-source times.
+    const observedAt = qualified.observedAt
+        ?? (!Object.hasOwn(raw, 'sourceEvidence') ? timestamp(options.observedAt) || null : null);
     const retainedAt = timestamp(options.retainedAt) || now;
-    if (!observedAt) {
-        throw new Error('A relationship observation needs the contributing scan observation time; an unknown time is not replaced with the retention time.');
-    }
     const canonical = canonicalIdentity(type, normalizedValue, domains);
     const metadata = TYPE_METADATA[type];
     return {
         id: observationId(canonical),
         type,
-        label: metadata.label,
+        label: nonPublicAddress ? 'Shared non-public DNS answer' : metadata.label,
         method: metadata.method,
         normalizedValue,
         displayValue: type === 'favicon' ? '' : normalizedValue,
         domains,
-        description: metadata.description,
+        description: nonPublicAddress ? NON_PUBLIC_RELATIONSHIP_LIMITATION : metadata.description,
         classification: 'derived',
         source: 'bulk_relationship_analysis',
-        sourceVersion: positiveInteger(options.sourceVersion) || 1,
+        sourceVersion,
         observedAt,
+        sourceEvidence: qualified.sourceEvidence,
         retainedAt,
-        complete: options.complete === true,
-        truncated: options.truncated === true
+        complete: options.complete !== false && qualified.complete,
+        truncated: qualified.truncated
             || (Array.isArray(raw.domains) && raw.domains.length > MAX_RELATIONSHIP_OBSERVATION_DOMAINS),
-        limitations: observationLimitations(options.limitations),
+        limitations: observationLimitations([...(nonPublicAddress ? [NON_PUBLIC_RELATIONSHIP_LIMITATION] : []), ...(Array.isArray(options.limitations) ? options.limitations : [])]),
     };
 }
 function byteLength(value) {
@@ -359,12 +379,11 @@ export function deleteRelationshipObservation(rawStore, id) {
 export function mergeRelationshipObservations(localRaw, importedRaw) {
     assertWorkspaceInputGraph(localRaw, 'Local relationship-observation store');
     assertWorkspaceInputGraph(importedRaw, 'Imported relationship-observation document');
-    assertWorkspacePortableVersion(importedRaw, RELATIONSHIP_OBSERVATION_SCHEMA_VERSION, 'Imported relationship-observation document');
+    const importedVersion = assertWorkspacePortableVersion(importedRaw, RELATIONSHIP_OBSERVATION_SCHEMA_VERSION, 'Imported relationship-observation document');
     const importedRecord = record(importedRaw);
     if (importedRecord?.schema !== undefined && importedRecord.schema !== RELATIONSHIP_OBSERVATION_SCHEMA) {
         throw new Error('This JSON section is not a WHOISleuth relationship-observation export.');
     }
-    const importedVersion = relationshipObservationStoreVersion(importedRaw);
     if (importedVersion !== null && importedVersion > RELATIONSHIP_OBSERVATION_SCHEMA_VERSION) {
         throw new Error(`This relationship-observation section uses newer schema ${importedVersion}. Update the app before importing it.`);
     }
@@ -375,7 +394,7 @@ export function mergeRelationshipObservations(localRaw, importedRaw) {
     let updated = 0;
     let skipped = Math.max(0, importedInput.length - MAX_RELATIONSHIP_OBSERVATION_INPUTS);
     for (const candidate of importedInput.slice(0, MAX_RELATIONSHIP_OBSERVATION_INPUTS)) {
-        const observation = normalizeRelationshipObservation(candidate);
+        const observation = normalizeRelationshipObservation(candidate, importedVersion ?? RELATIONSHIP_OBSERVATION_SCHEMA_VERSION);
         if (!observation) {
             skipped += 1;
             continue;

package/packages/workspace/shortlist-model.mjs

@@ -2,8 +2,8 @@
 // and downloads; this module owns schema migration, record normalization,
 // import merging, and exact serialized-byte accounting.
 import { compactWatchlistResults } from "./watchlist-history.mjs";
-import { normalizeOpportunityModelVersion } from "../../lib/opportunity-scoring.mjs";
-import { normalizeRiskModelVersion } from "../../lib/risk-scoring.mjs";
+import { normalizeOpportunityModelVersion } from "../analysis/opportunity-scoring.mjs";
+import { normalizeRiskModelVersion } from "../analysis/risk-scoring.mjs";
 import { normalizeExplicitIsoTimestamp } from "../evidence/observation.mjs";
 import { assertWorkspaceDeclaredVersion, assertWorkspaceInputGraph, assertWorkspacePortableVersion, ordinaryWorkspaceRecord } from "./hostile-input.mjs";
 import { MAX_SHORTLIST_ENTRIES, MAX_SHORTLIST_FACTORS, MAX_SHORTLIST_INPUTS, MAX_SHORTLIST_STORE_BYTES, SHORTLIST_SCHEMA, SHORTLIST_SCHEMA_VERSION, SUPPORTED_SHORTLIST_SCHEMA_VERSIONS, } from "../contracts/workspace-portability.mjs";
@@ -188,14 +188,23 @@ export function mergeShortlistStores(localRaw, importedRaw) {
             skipped++;
             continue;
         }
-        if (imported.has(record.domain))
+        const prior = imported.get(record.domain);
+        if (prior)
             skipped++;
-        imported.set(record.domain, record);
+        if (!prior || Date.parse(record.savedAt) > Date.parse(prior.savedAt))
+            imported.set(record.domain, record);
     }
     let added = 0;
     let updated = 0;
     for (const record of imported.values()) {
-        if (byDomain.has(record.domain))
+        const existing = byDomain.get(record.domain);
+        // A backup must not roll back an observation. Equal-time conflicts retain
+        // the local record rather than choosing whichever file was imported last.
+        if (existing && Date.parse(record.savedAt) <= Date.parse(existing.savedAt)) {
+            skipped++;
+            continue;
+        }
+        if (existing)
             updated++;
         else if (byDomain.size >= MAX_SHORTLIST_ENTRIES) {
             skipped++;