@slicedearth/whoisleuth-cli 1.45.0 → 1.47.4

package/frontend/src/lib/analysis/case-response-packet.js

@@ -1,8 +1,10 @@
 // Pure abuse-evidence packet builder. It creates local review artifacts only:
 // no network requests, mailto links, submissions, or provider side effects.
 import { buildCaseActionOutcomeSummary } from "./case-response-model.js";
+import { canonicalArtifactJsonV2, SORTED_JSON_V2 } from "./artifact-integrity.js";
 export const CASE_RESPONSE_PACKET_SCHEMA = 'whoisleuth.case-response-packet';
-export const CASE_RESPONSE_PACKET_VERSION = 5;
+export const CASE_RESPONSE_PACKET_VERSION = 6;
+export const LEGACY_CASE_RESPONSE_PACKET_VERSION = 5;
 export const MAX_ABUSIVE_URLS = 20;
 export const MAX_RESPONSE_CONTACTS = 12;
 export const MAX_RESPONSE_ACTION_HISTORY = 20;
@@ -387,13 +389,21 @@ async function sha256(value) {
 }
 export async function verifyCaseResponsePacketIntegrity(packet) {
     const { integrity, ...unsigned } = packet;
+    const canonicalization = packet.schemaVersion === LEGACY_CASE_RESPONSE_PACKET_VERSION
+        && integrity.canonicalization === 'sorted-json-v1'
+        ? canonicalJson
+        : packet.schemaVersion === CASE_RESPONSE_PACKET_VERSION
+            && integrity.canonicalization === SORTED_JSON_V2
+            ? canonicalArtifactJsonV2
+            : null;
     if (integrity.algorithm !== 'SHA-256'
-        || integrity.canonicalization !== 'sorted-json-v1'
+        || !canonicalization
         || integrity.scope !== 'packet excluding integrity'
+        || typeof integrity.digestSha256 !== 'string'
         || !/^[a-f0-9]{64}$/u.test(integrity.digestSha256)) {
         return false;
     }
-    return integrity.digestSha256 === await sha256(canonicalJson(unsigned));
+    return integrity.digestSha256 === await sha256(canonicalization(unsigned));
 }
 function escapeMarkdown(value) {
     return value.replace(/([\\`*_[\]<>|])/gu, '\\$1').replace(/\r?\n/gu, ' ');
@@ -472,12 +482,12 @@ export async function buildCaseResponsePacket(caseRecord, input, generatedAt = n
             limitations,
         },
     };
-    const digestSha256 = await sha256(canonicalJson(unsigned));
+    const digestSha256 = await sha256(canonicalArtifactJsonV2(unsigned));
     const json = {
         ...unsigned,
         integrity: {
             algorithm: 'SHA-256',
-            canonicalization: 'sorted-json-v1',
+            canonicalization: SORTED_JSON_V2,
             scope: 'packet excluding integrity',
             digestSha256,
         },

package/frontend/src/lib/analysis/comparison-ledger-bulk.js

@@ -0,0 +1,366 @@
+import { MAX_BULK_SESSIONS, compareBulkSessions, normalizeBulkSession, } from "./bulk-session-model.js";
+import { MAX_COMPARISON_LEDGER_BULK_PAIRS, boundedComparisonLedgerId, comparisonLedgerCollector, comparisonLedgerInputArray, comparisonLedgerRecord, comparisonLedgerValuePresent, comparisonLedgerValueState, makeComparisonLedgerCandidate, stableComparisonLedgerId, } from "./comparison-ledger-contract.js";
+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';
+    if (family === 'collection')
+        return 'retained';
+    return result.status;
+}
+function bulkSide(session, result, family, value, sourceState) {
+    return {
+        source: `Saved Bulk session · ${session.name}`,
+        sourceState: sourceState ?? (result ? bulkFamilyState(result, family) : session.state),
+        value,
+        observedAt: session.state === 'complete' ? session.completedAt : null,
+        retainedAt: session.updatedAt,
+    };
+}
+const BULK_FIELDS = Object.freeze([
+    { field: 'Availability', family: 'registration', kind: 'source', read: (item) => item.availability, sourceState: (item) => namedBulkSourceState(item, 'availability') },
+    { field: 'Registrar', family: 'registration', kind: 'registrar', read: (item) => item.registrar, sourceState: () => 'not_reported' },
+    { field: 'Website activity', family: 'website', kind: 'source', read: (item) => item.activityStatus, sourceState: (item) => namedBulkSourceState(item, 'http') },
+    { field: 'Risk score', family: 'model', kind: 'model', read: (item) => item.risk, sourceState: () => 'derived' },
+    { field: 'Opportunity score', family: 'model', kind: 'model', read: (item) => item.opportunity, sourceState: () => 'derived' },
+    { field: 'Technology IDs', family: 'technology', kind: 'source', read: (item) => item.comparisonEvidence?.technology.ids ?? null, sourceState: (item) => item.comparisonEvidence?.technology.state ?? 'not_reported' },
+    { field: 'TLS issuer', family: 'certificate', kind: 'source', read: (item) => item.comparisonEvidence?.tls.issuerLabel ?? null, sourceState: (item) => item.comparisonEvidence?.tls.state ?? 'not_reported' },
+    { field: 'TLS public key', family: 'certificate', kind: 'source', read: (item) => item.comparisonEvidence?.tls.spkiSha256 ?? null, sourceState: (item) => item.comparisonEvidence?.tls.state ?? 'not_reported' },
+]);
+function completeBulkSourceState(value) { return value === 'complete' || value === 'success'; }
+function settledBulkCoverageState(value) {
+    return value === 'complete' || value === 'skipped' || value === 'unsupported';
+}
+function bulkFieldDecision(field, earlier, later, before, after) {
+    const earlierState = field.sourceState(earlier);
+    const laterState = field.sourceState(later);
+    if (earlier.scanDepth !== later.scanDepth)
+        return { state: 'not_compared', completeness: 'partial', earlierState, laterState, limitation: 'Unlike Fast and Deep result rows are not compared as an observed field change.' };
+    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') {
+        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.' };
+    }
+    if (earlierState !== laterState)
+        return { state: 'collection_changed', completeness: 'partial', earlierState, laterState, limitation: 'The exact retained family source state changed, so the values are not represented as an observed field change.' };
+    if (!completeBulkSourceState(earlierState) || !completeBulkSourceState(laterState)) {
+        const state = laterState === 'unsupported' ? 'unsupported' : ['error', 'not_found', 'unavailable'].includes(laterState) ? 'unavailable' : 'not_compared';
+        return { state, completeness: state === 'not_compared' ? 'partial' : 'unavailable', earlierState, laterState, limitation: 'Both retained family source states must be complete before values are compared.' };
+    }
+    return { state: comparisonLedgerValueState(before, after, true), completeness: 'complete', earlierState, laterState, limitation: null };
+}
+function bulkPairCompleteness(earlier, later) {
+    if (bulkCompleteness(earlier) !== 'complete' || bulkCompleteness(later) !== 'complete' || earlier.mode !== later.mode)
+        return 'partial';
+    const before = new Map(earlier.results.map((item) => [item.domain, item]));
+    const after = new Map(later.results.map((item) => [item.domain, item]));
+    if (before.size !== after.size)
+        return 'partial';
+    for (const [domain, left] of before) {
+        const right = after.get(domain);
+        if (!right || left.scanDepth !== right.scanDepth)
+            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';
+        for (const field of BULK_FIELDS) {
+            if (field.kind === 'registrar' && exactEqual(field.read(left), field.read(right)))
+                continue;
+            const decision = bulkFieldDecision(field, left, right, field.read(left), field.read(right));
+            if (decision.completeness !== 'complete')
+                return 'partial';
+        }
+        const leftSources = sourceMap(left);
+        const rightSources = sourceMap(right);
+        if ([...new Set([...leftSources.keys(), ...rightSources.keys()])].some((source) => leftSources.get(source) !== rightSources.get(source)
+            || !settledBulkCoverageState(leftSources.get(source)) || !settledBulkCoverageState(rightSources.get(source))))
+            return 'partial';
+    }
+    return 'complete';
+}
+function exactEqual(left, right) {
+    if (Array.isArray(left) || Array.isArray(right)) {
+        return Array.isArray(left) && Array.isArray(right)
+            && left.length === right.length
+            && left.every((value, index) => value === right[index]);
+    }
+    return Object.is(left, right);
+}
+function buildBulkRows(ownerId, earlier, later, pairCompleteness) {
+    const output = comparisonLedgerCollector();
+    const before = new Map(earlier.results.map((item) => [item.domain, item]));
+    const after = new Map(later.results.map((item) => [item.domain, item]));
+    for (const domain of [...new Set([...before.keys(), ...after.keys()])].sort()) {
+        const left = before.get(domain) ?? null;
+        const right = after.get(domain) ?? null;
+        if (!left && right) {
+            output.add({
+                comparisonId: ownerId,
+                ownerId,
+                entityId: domain,
+                mode: 'membership',
+                state: 'added',
+                field: 'Settled result-set membership',
+                family: 'membership',
+                earlier: bulkSide(earlier, null, 'membership', null),
+                later: bulkSide(later, right, 'membership', 'Included in the later settled result set'),
+                completeness: bulkCompleteness(later),
+                limitations: ['This is membership in two explicitly selected saved sessions, not evidence that the domain itself was created or became active.'],
+            });
+            continue;
+        }
+        if (left && !right) {
+            output.add({
+                comparisonId: ownerId,
+                ownerId,
+                entityId: domain,
+                mode: 'membership',
+                state: 'not_compared',
+                field: 'Settled result-set membership',
+                family: 'membership',
+                earlier: bulkSide(earlier, left, 'membership', 'Included in the earlier settled result set'),
+                later: bulkSide(later, null, 'membership', null),
+                completeness: 'partial',
+                limitations: ['No settled row is retained in the later saved session. This is not domain removal, release, resolution, or an availability finding.'],
+            });
+            continue;
+        }
+        if (!left || !right)
+            continue;
+        const riskModelsComparable = left.riskModelVersion !== null
+            && right.riskModelVersion !== null
+            && left.riskModelVersion === right.riskModelVersion;
+        const riskModelChanged = left.riskModelVersion !== null
+            && right.riskModelVersion !== null
+            && left.riskModelVersion !== right.riskModelVersion;
+        const leftOpportunityVersion = left.opportunityModelVersion ?? null;
+        const rightOpportunityVersion = right.opportunityModelVersion ?? null;
+        const opportunityModelsComparable = leftOpportunityVersion !== null
+            && rightOpportunityVersion !== null
+            && leftOpportunityVersion === rightOpportunityVersion;
+        const opportunityModelChanged = leftOpportunityVersion !== null
+            && rightOpportunityVersion !== null
+            && leftOpportunityVersion !== rightOpportunityVersion;
+        for (const field of BULK_FIELDS) {
+            const beforeValue = field.read(left);
+            const afterValue = field.read(right);
+            if ((field.field === 'Risk score' && !riskModelsComparable)
+                || (field.field === 'Opportunity score' && !opportunityModelsComparable))
+                continue;
+            const decision = bulkFieldDecision(field, left, right, beforeValue, afterValue);
+            if (exactEqual(beforeValue, afterValue) && decision.state !== 'collection_changed')
+                continue;
+            output.add({
+                comparisonId: ownerId,
+                ownerId,
+                entityId: domain,
+                mode: 'temporal',
+                state: decision.state,
+                field: field.field,
+                family: field.family,
+                earlier: bulkSide(earlier, left, field.family, beforeValue, decision.earlierState),
+                later: bulkSide(later, right, field.family, afterValue, decision.laterState),
+                completeness: decision.completeness,
+                limitations: [
+                    'Saved Bulk rows are compact derived observations, not raw source publications or current provider state.',
+                    ...(decision.limitation ? [decision.limitation] : []),
+                ],
+            });
+        }
+        if (riskModelChanged) {
+            output.add({
+                comparisonId: ownerId,
+                ownerId,
+                entityId: domain,
+                mode: 'temporal',
+                state: 'model_changed',
+                field: 'Risk model version',
+                family: 'model',
+                earlier: bulkSide(earlier, left, 'model', left.riskModelVersion),
+                later: bulkSide(later, right, 'model', right.riskModelVersion),
+                completeness: 'partial',
+                limitations: ['Risk scores from unlike model versions are not represented as an observed domain change.'],
+            });
+        }
+        else if (!riskModelsComparable && (left.risk !== null || right.risk !== null)) {
+            output.add({
+                comparisonId: ownerId,
+                ownerId,
+                entityId: domain,
+                mode: 'temporal',
+                state: 'not_compared',
+                field: 'Risk model version',
+                family: 'model',
+                earlier: bulkSide(earlier, left, 'model', left.riskModelVersion),
+                later: bulkSide(later, right, 'model', right.riskModelVersion),
+                completeness: 'partial',
+                limitations: ['At least one saved Risk score lacks a retained model version, so score values are not compared.'],
+            });
+        }
+        if (opportunityModelChanged) {
+            output.add({
+                comparisonId: ownerId,
+                ownerId,
+                entityId: domain,
+                mode: 'temporal',
+                state: 'model_changed',
+                field: 'Opportunity model version',
+                family: 'model',
+                earlier: bulkSide(earlier, left, 'model', leftOpportunityVersion),
+                later: bulkSide(later, right, 'model', rightOpportunityVersion),
+                completeness: 'partial',
+                limitations: ['Opportunity scores from unlike model versions are not represented as an observed domain change.'],
+            });
+        }
+        else if (!opportunityModelsComparable && (left.opportunity !== null || right.opportunity !== null)) {
+            output.add({
+                comparisonId: ownerId,
+                ownerId,
+                entityId: domain,
+                mode: 'temporal',
+                state: 'not_compared',
+                field: 'Opportunity model version',
+                family: 'model',
+                earlier: bulkSide(earlier, left, 'model', leftOpportunityVersion),
+                later: bulkSide(later, right, 'model', rightOpportunityVersion),
+                completeness: 'partial',
+                limitations: ['At least one saved Opportunity score lacks a retained model version, so score values are not compared.'],
+            });
+        }
+        const beforeSources = sourceMap(left);
+        const afterSources = sourceMap(right);
+        for (const source of [...new Set([...beforeSources.keys(), ...afterSources.keys()])].sort()) {
+            const beforeState = beforeSources.get(source) ?? 'not_reported';
+            const afterState = afterSources.get(source) ?? 'not_reported';
+            if (beforeState === afterState)
+                continue;
+            output.add({
+                comparisonId: ownerId,
+                ownerId,
+                entityId: domain,
+                mode: 'temporal',
+                state: 'collection_changed',
+                field: `${source} source state`,
+                family: 'collection',
+                earlier: bulkSide(earlier, left, 'collection', beforeState),
+                later: bulkSide(later, right, 'collection', afterState),
+                completeness: 'partial',
+                limitations: ['A source-state difference can reflect collection conditions rather than a target change.'],
+            });
+        }
+    }
+    if (earlier.mode !== later.mode) {
+        output.add({
+            comparisonId: ownerId,
+            ownerId,
+            entityId: `${earlier.id}:${later.id}`,
+            mode: 'temporal',
+            state: 'collection_changed',
+            field: 'Bulk collection mode',
+            family: 'collection',
+            earlier: bulkSide(earlier, null, 'collection', earlier.mode),
+            later: bulkSide(later, null, 'collection', later.mode),
+            completeness: 'partial',
+            limitations: ['Fast and Deep saved sessions have different collection contracts; unlike fields remain not compared.'],
+        });
+    }
+    if (!output.totalRows) {
+        output.add({
+            comparisonId: ownerId,
+            ownerId,
+            entityId: `${earlier.id}:${later.id}`,
+            mode: 'temporal',
+            state: pairCompleteness === 'complete' ? 'equivalent' : 'incomplete',
+            field: 'Compact comparable saved rows',
+            family: 'summary',
+            earlier: bulkSide(earlier, null, 'summary', 'No bounded material difference'),
+            later: bulkSide(later, null, 'summary', 'No bounded material difference'),
+            completeness: pairCompleteness,
+            limitations: [pairCompleteness === 'complete'
+                    ? 'Equivalence applies only to the compact fields retained in both explicitly selected saved sessions.'
+                    : 'At least one compact field or source state is not completely comparable across both saved sessions, so the absence of a retained row difference is not represented as equivalence or resolution.'],
+        });
+    }
+    return { rows: output.rows, totalRows: output.totalRows, sourceOmittedRows: 0 };
+}
+export function comparisonLedgerBulkPairIndexId(earlierSessionId, laterSessionId) {
+    return stableComparisonLedgerId('ledger-bulk_session_pair', [String(earlierSessionId ?? ''), String(laterSessionId ?? '')]);
+}
+export function buildBulkComparisonCandidates(sessionsRaw, pairsRaw, counters) {
+    const input = comparisonLedgerInputArray(sessionsRaw);
+    counters.inputRecords += Math.max(0, input.length - MAX_BULK_SESSIONS);
+    const sessions = new Map();
+    for (const value of input.slice(0, MAX_BULK_SESSIONS)) {
+        const item = normalizeBulkSession(value);
+        if (!item) {
+            counters.invalidRecords += 1;
+            continue;
+        }
+        if (sessions.has(item.id)) {
+            counters.duplicateRecords += 1;
+            continue;
+        }
+        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();
+    for (const rawPair of pairs.slice(0, MAX_COMPARISON_LEDGER_BULK_PAIRS)) {
+        const pair = comparisonLedgerRecord(rawPair);
+        const earlierId = boundedComparisonLedgerId(pair?.earlierSessionId, counters);
+        const laterId = boundedComparisonLedgerId(pair?.laterSessionId, counters);
+        const earlier = sessions.get(earlierId);
+        const later = sessions.get(laterId);
+        if (!pair || !earlierId || !laterId || earlierId === laterId || !earlier || !later
+            || earlier.updatedAt > later.updatedAt) {
+            counters.invalidRecords += 1;
+            continue;
+        }
+        const id = comparisonLedgerBulkPairIndexId(earlierId, laterId);
+        if (seen.has(id)) {
+            counters.duplicateRecords += 1;
+            continue;
+        }
+        seen.add(id);
+        const comparison = compareBulkSessions(earlier, later);
+        if (!comparison) {
+            counters.invalidRecords += 1;
+            continue;
+        }
+        const ownerId = stableComparisonLedgerId('bulk-pair', [earlierId, laterId]);
+        const pairCompleteness = bulkPairCompleteness(earlier, later);
+        const candidate = makeComparisonLedgerCandidate({
+            idParts: [earlierId, laterId],
+            ownerType: 'bulk_session_pair',
+            ownerId,
+            entityId: `${earlierId}:${laterId}`,
+            label: `${earlier.name} → ${later.name} · explicit saved-session pair`,
+            mode: 'temporal',
+            earlier: { source: `Saved Bulk session · ${earlier.name}`, sourceState: earlier.state, observedAt: earlier.completedAt, retainedAt: earlier.updatedAt },
+            later: { source: `Saved Bulk session · ${later.name}`, sourceState: later.state, observedAt: later.completedAt, retainedAt: later.updatedAt },
+            completeness: pairCompleteness,
+            truncated: false,
+            limitations: [
+                ...comparison.limitations,
+                ...(pairCompleteness === 'complete' ? [] : ['At least one compact field or retained source state is not completely comparable across both selected sessions.']),
+            ],
+            ownerHref: '/bulk#bulk-sessions-title',
+            buildDetails: () => buildBulkRows(ownerId, earlier, later, pairCompleteness),
+        }, counters);
+        if (candidate)
+            candidates.push(candidate);
+        else
+            counters.invalidRecords += 1;
+    }
+    return candidates;
+}

package/frontend/src/lib/analysis/comparison-ledger-contract.js

@@ -0,0 +1,241 @@
+import { safeComparisonLedgerHref, stableComparisonLedgerId, } from "./comparison-ledger-serialization.js";
+import { projectComparisonLedgerJson } from "./comparison-ledger-json.js";
+export { stableComparisonLedgerJson } from "./comparison-ledger-json.js";
+export { safeComparisonLedgerHref, stableComparisonLedgerId } from "./comparison-ledger-serialization.js";
+export const COMPARISON_LEDGER_MODES = Object.freeze([
+    'publication',
+    'entity',
+    'temporal',
+    'expectation',
+    'membership',
+    'reconciliation',
+]);
+export const COMPARISON_LEDGER_STATES = Object.freeze([
+    'equivalent',
+    'added',
+    'removed',
+    'different',
+    'conflict',
+    'collection_changed',
+    'model_changed',
+    'incomplete',
+    'unavailable',
+    'unsupported',
+    'not_compared',
+]);
+export const MAX_COMPARISON_LEDGER_INDEX_ITEMS = 2_000;
+export const MAX_COMPARISON_LEDGER_ENTITIES_PER_REQUEST = 20;
+export const MAX_COMPARISON_LEDGER_DETAIL_ROWS = 256;
+export const MAX_COMPARISON_LEDGER_LIMITATIONS = 8;
+export const MAX_COMPARISON_LEDGER_STRING_LENGTH = 500;
+export const MAX_COMPARISON_LEDGER_ID_LENGTH = 128;
+export const MAX_COMPARISON_LEDGER_BULK_PAIRS = MAX_COMPARISON_LEDGER_INDEX_ITEMS;
+const MAX_LABEL_LENGTH = 160;
+const MAX_FIELD_LENGTH = 120;
+const MAX_SOURCE_LENGTH = 120;
+const MAX_LIMITATION_SCAN = MAX_COMPARISON_LEDGER_LIMITATIONS * 4;
+const CONTROL_RE = /[\u0000-\u001f\u007f]/gu;
+const CONTROL_TEST_RE = /[\u0000-\u001f\u007f]/u;
+export function freshComparisonLedgerCounters() {
+    return { inputRecords: 0, inputScanTruncations: 0, invalidRecords: 0, duplicateRecords: 0, limitations: 0, truncatedStrings: 0 };
+}
+export function comparisonLedgerRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+export function comparisonLedgerInputArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+export function boundedComparisonLedgerText(value, maximum, counters, preserveWhitespace = false) {
+    if (typeof value !== 'string' && typeof value !== 'number' && typeof value !== 'boolean')
+        return '';
+    const raw = String(value).replace(CONTROL_RE, ' ');
+    const normalised = preserveWhitespace ? raw.trim() : raw.replace(/\s+/gu, ' ').trim();
+    if (normalised.length > maximum)
+        counters && (counters.truncatedStrings += 1);
+    return normalised.slice(0, maximum).trim();
+}
+export function boundedComparisonLedgerId(value, counters) {
+    const text = boundedComparisonLedgerText(value, MAX_COMPARISON_LEDGER_ID_LENGTH * 2, counters);
+    const safe = text.replace(/[^A-Za-z0-9:._-]+/gu, '-').replace(/^-+|-+$/gu, '');
+    if (safe.length > MAX_COMPARISON_LEDGER_ID_LENGTH)
+        counters && (counters.truncatedStrings += 1);
+    return safe.slice(0, MAX_COMPARISON_LEDGER_ID_LENGTH);
+}
+function timestamp(value) {
+    if (typeof value !== 'string' || value.length > 64 || CONTROL_TEST_RE.test(value))
+        return null;
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? new Date(parsed).toISOString() : null;
+}
+function normaliseCompleteness(value) {
+    return value === 'complete' || value === 'partial' || value === 'unavailable' || value === 'not_reported'
+        ? value
+        : 'not_reported';
+}
+export function boundedComparisonLedgerLimitations(value, counters) {
+    const raw = Array.isArray(value) ? value : [];
+    const unscanned = Math.max(0, raw.length - MAX_LIMITATION_SCAN);
+    const seen = new Set();
+    const all = [];
+    for (const item of raw.slice(0, MAX_LIMITATION_SCAN)) {
+        const entry = boundedComparisonLedgerText(item, MAX_COMPARISON_LEDGER_STRING_LENGTH, counters);
+        if (!entry || seen.has(entry))
+            continue;
+        seen.add(entry);
+        all.push(entry);
+    }
+    const values = all.slice(0, MAX_COMPARISON_LEDGER_LIMITATIONS);
+    const omitted = unscanned + Math.max(0, all.length - values.length);
+    counters.limitations += omitted;
+    return { values: Object.freeze(values), omitted };
+}
+function exactValue(value, counters) {
+    if (value === null || value === undefined)
+        return { value: null, truncated: false };
+    const traversal = typeof value === 'string'
+        ? { value, truncated: false }
+        : projectComparisonLedgerJson(value);
+    const before = counters.truncatedStrings;
+    if (traversal.truncated)
+        counters.truncatedStrings += 1;
+    const projected = boundedComparisonLedgerText(traversal.value, MAX_COMPARISON_LEDGER_STRING_LENGTH, counters, true);
+    return { value: projected || null, truncated: counters.truncatedStrings > before };
+}
+function sourceSide(raw, counters) {
+    const projected = exactValue(raw.value, counters);
+    return {
+        side: Object.freeze({
+            source: boundedComparisonLedgerText(raw.source, MAX_SOURCE_LENGTH, counters) || 'Not recorded',
+            sourceState: boundedComparisonLedgerText(raw.sourceState, 64, counters) || 'not_reported',
+            value: projected.value,
+            observedAt: timestamp(raw.observedAt),
+            publishedAt: timestamp(raw.publishedAt),
+            retainedAt: timestamp(raw.retainedAt),
+        }),
+        truncated: projected.truncated,
+    };
+}
+function isMode(value) {
+    return typeof value === 'string' && COMPARISON_LEDGER_MODES.includes(value);
+}
+function isState(value) {
+    return typeof value === 'string' && COMPARISON_LEDGER_STATES.includes(value);
+}
+export function normaliseComparisonLedgerRowWithCounters(raw, counters) {
+    const item = comparisonLedgerRecord(raw);
+    const earlierRaw = comparisonLedgerRecord(item?.earlier);
+    const laterRaw = comparisonLedgerRecord(item?.later);
+    const ownerId = boundedComparisonLedgerId(item?.ownerId, counters);
+    const entityId = boundedComparisonLedgerId(item?.entityId, counters);
+    const mode = item?.mode;
+    const state = item?.state;
+    const field = boundedComparisonLedgerText(item?.field, MAX_FIELD_LENGTH, counters);
+    const family = boundedComparisonLedgerText(item?.family, MAX_FIELD_LENGTH, counters);
+    if (!item || !earlierRaw || !laterRaw || !ownerId || !entityId || !isMode(mode) || !isState(state) || !field || !family) {
+        return null;
+    }
+    const earlier = sourceSide(earlierRaw, counters);
+    const later = sourceSide(laterRaw, counters);
+    const rowLimitations = boundedComparisonLedgerLimitations(item.limitations, counters);
+    const truncated = item.truncated === true || earlier.truncated || later.truncated || rowLimitations.omitted > 0;
+    const completeness = normaliseCompleteness(item.completeness);
+    const comparisonId = boundedComparisonLedgerId(item.comparisonId, counters);
+    const id = stableComparisonLedgerId('ledger-row', [
+        comparisonId, ownerId, entityId, mode, state, family, field,
+        earlier.side.source, earlier.side.sourceState, earlier.side.value,
+        earlier.side.observedAt, earlier.side.publishedAt, earlier.side.retainedAt,
+        later.side.source, later.side.sourceState, later.side.value,
+        later.side.observedAt, later.side.publishedAt, later.side.retainedAt,
+        completeness, truncated, rowLimitations.omitted, ...rowLimitations.values,
+    ]);
+    return Object.freeze({
+        id,
+        ownerId,
+        entityId,
+        mode,
+        state,
+        field,
+        family,
+        earlier: earlier.side,
+        later: later.side,
+        completeness,
+        truncated,
+        limitations: rowLimitations.values,
+        omittedLimitations: rowLimitations.omitted,
+    });
+}
+export function normaliseComparisonLedgerRow(raw) {
+    return normaliseComparisonLedgerRowWithCounters(raw, freshComparisonLedgerCounters());
+}
+export function comparisonLedgerCollector() {
+    const output = {
+        rows: [],
+        totalRows: 0,
+        add(row) {
+            output.totalRows += 1;
+            if (output.rows.length < MAX_COMPARISON_LEDGER_DETAIL_ROWS)
+                output.rows.push(row);
+        },
+    };
+    return output;
+}
+export function comparisonLedgerValuePresent(value) {
+    if (value === null || value === undefined)
+        return false;
+    if (typeof value === 'string')
+        return value.trim() !== '' && value.trim() !== '—';
+    if (Array.isArray(value))
+        return value.length > 0;
+    return true;
+}
+export function comparisonLedgerValueState(before, after, removalAllowed) {
+    if (!comparisonLedgerValuePresent(before) && comparisonLedgerValuePresent(after))
+        return 'added';
+    if (comparisonLedgerValuePresent(before) && !comparisonLedgerValuePresent(after))
+        return removalAllowed ? 'removed' : 'incomplete';
+    return 'different';
+}
+function indexSide(raw, counters) {
+    return Object.freeze({
+        source: boundedComparisonLedgerText(raw.source, MAX_SOURCE_LENGTH, counters) || 'Not recorded',
+        sourceState: boundedComparisonLedgerText(raw.sourceState, 64, counters) || 'not_reported',
+        observedAt: timestamp(raw.observedAt),
+        publishedAt: timestamp(raw.publishedAt),
+        retainedAt: timestamp(raw.retainedAt),
+    });
+}
+export function makeComparisonLedgerCandidate(raw, counters) {
+    const ownerId = boundedComparisonLedgerId(raw.ownerId, counters);
+    const entityId = boundedComparisonLedgerId(raw.entityId, counters);
+    const label = boundedComparisonLedgerText(raw.label, MAX_LABEL_LENGTH, counters);
+    if (!ownerId || !entityId || !label)
+        return null;
+    const projectedLimitations = boundedComparisonLedgerLimitations(raw.limitations, counters);
+    const id = stableComparisonLedgerId(`ledger-${raw.ownerType}`, raw.idParts);
+    const item = Object.freeze({
+        id,
+        ownerType: raw.ownerType,
+        ownerId,
+        entityId,
+        label,
+        mode: raw.mode,
+        earlier: indexSide(raw.earlier, counters),
+        later: indexSide(raw.later, counters),
+        completeness: raw.completeness,
+        truncated: raw.truncated || projectedLimitations.omitted > 0,
+        limitations: projectedLimitations.values,
+        omittedLimitations: projectedLimitations.omitted,
+        sourceOmittedRows: Math.max(0, Math.trunc(Number(raw.sourceOmittedRows) || 0)),
+        ownerHref: safeComparisonLedgerHref(raw.ownerHref),
+    });
+    return Object.freeze({ item, buildDetails: raw.buildDetails });
+}
+export function validComparisonLedgerRequestId(value) {
+    return typeof value === 'string'
+        && value.length > 0
+        && value.length <= MAX_COMPARISON_LEDGER_ID_LENGTH
+        && !CONTROL_TEST_RE.test(value)
+        && boundedComparisonLedgerId(value) === value;
+}