@slicedearth/whoisleuth-cli 1.39.1 → 1.45.0

package/lib/browser-library-profile.mjs

@@ -4,10 +4,19 @@
 // scripts. Upstream URLs, filenames, inline bodies, and catalogue expressions
 // are treated as untrusted inputs and are not retained in the result.
 import { createHash } from 'node:crypto';
+import { Worker } from 'node:worker_threads';
 import { RETIRE_BROWSER_CATALOG } from "./generated/retire-browser-catalog.mjs";
 import { CISA_KEV_CATALOG } from "./generated/cisa-kev-catalog.mjs";
 import { createObservation } from "./observation.mjs";
 import { MAX_INLINE_SCRIPT_CHARS, MAX_INLINE_SCRIPT_TOTAL_CHARS, MAX_SCRIPT_ELEMENTS, MAX_STATIC_HTML_CHARS, analyzeStaticHtml, } from "./static-html-analysis.mjs";
+// Catalogue expressions are reviewed third-party inputs. Keep every individual
+// regular-expression evaluation and the aggregate inline-signature work small
+// enough that a target-controlled script cannot monopolise the Node event loop.
+// Full-content hashes still use the complete already-capped script body.
+const MAX_INLINE_LIBRARY_SCAN_CHARS = 1_024;
+const MAX_INLINE_LIBRARY_SCAN_TOTAL_CHARS = 4_096;
+const MAX_INLINE_LIBRARY_SCAN_MS = 750;
+const MAX_INLINE_LIBRARY_WORKER_BYTES = 64 * 1024;
 const BROWSER_LIBRARY_PROFILE_VERSION = 2;
 const MAX_LIBRARY_HTML_CHARS = MAX_STATIC_HTML_CHARS;
 const MAX_LIBRARY_FINDINGS = 16;
@@ -29,6 +38,68 @@ const SEVERITY_WEIGHT = Object.freeze({
 });
 const CATALOG_COMPONENTS = RETIRE_BROWSER_CATALOG.components;
 const KNOWN_EXPLOITED_IDENTIFIERS = new Set(CISA_KEV_CATALOG.identifiers);
+const INLINE_EXTRACTOR_CATALOGUE = Object.freeze(Object.entries(CATALOG_COMPONENTS).map(([component, value]) => {
+    const extractors = record(record(value).extractors);
+    return Object.freeze({
+        component,
+        patterns: Object.freeze((Array.isArray(extractors.filecontent) ? extractors.filecontent : [])
+            .filter((pattern) => typeof pattern === 'string' && pattern.length > 0 && pattern.length <= 2_048)
+            .slice(0, 64)),
+        replacements: Object.freeze((Array.isArray(extractors.filecontentreplace) ? extractors.filecontentreplace : [])
+            .filter((pattern) => typeof pattern === 'string' && pattern.length > 0 && pattern.length <= 2_048)
+            .slice(0, 64)),
+    });
+}));
+const INLINE_REGEX_WORKER_SOURCE = String.raw `
+const { parentPort, workerData } = require('node:worker_threads');
+const versions = /^[0-9][0-9.a-z_-]{0,63}$/i;
+parentPort.on('message', (job) => {
+  const control = new Int32Array(job.control);
+  const output = new Uint8Array(job.output);
+  const matches = [];
+  const add = (component, version) => {
+    const normalized = String(version).replace(/(?:\.|-)?min$/i, '').slice(0, 64);
+    if (versions.test(normalized) && matches.length < 64) matches.push([component, normalized]);
+  };
+  try {
+    for (const entry of workerData.catalogue) {
+      for (const pattern of entry.patterns) {
+        let expression;
+        try { expression = new RegExp(pattern, 'g'); } catch { continue; }
+        let match;
+        let count = 0;
+        while ((match = expression.exec(job.value)) && count < 4) {
+          if (typeof match[1] === 'string') add(entry.component, match[1]);
+          if (match[0] === '') expression.lastIndex += 1;
+          count += 1;
+        }
+      }
+      for (const descriptorValue of entry.replacements) {
+        const descriptor = /^\/(.*[^\\])\/([^/]+)\/$/.exec(descriptorValue);
+        if (!descriptor || !descriptor[1]) continue;
+        let expression;
+        try { expression = new RegExp(descriptor[1], 'g'); } catch { continue; }
+        let match;
+        let count = 0;
+        while ((match = expression.exec(job.value)) && count < 4) {
+          let replaced = match[0];
+          try { replaced = match[0].replace(new RegExp(descriptor[1]), descriptor[2]); } catch { break; }
+          add(entry.component, replaced);
+          if (match[0] === '') expression.lastIndex += 1;
+          count += 1;
+        }
+      }
+    }
+    const encoded = Buffer.from(JSON.stringify(matches));
+    if (encoded.length > output.length) Atomics.store(control, 0, -2);
+    else { output.set(encoded); Atomics.store(control, 0, encoded.length); }
+  } catch {
+    Atomics.store(control, 0, -1);
+  }
+  Atomics.notify(control, 0);
+});
+`;
+let inlineRegexWorker = null;
 function record(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value)
         ? value
@@ -106,32 +177,6 @@ function matchPattern(pattern, value) {
     }
     return matches;
 }
-function matchReplacementPattern(pattern, value) {
-    if (typeof pattern !== 'string' || pattern.length === 0 || pattern.length > 2_048)
-        return [];
-    const descriptor = /^\/(.*[^\\])\/([^/]+)\/$/.exec(pattern);
-    const expressionSource = descriptor?.[1];
-    const replacement = descriptor?.[2];
-    if (!expressionSource || replacement === undefined)
-        return [];
-    let expression;
-    try {
-        expression = new RegExp(expressionSource, 'g');
-    }
-    catch {
-        return [];
-    }
-    const matches = [];
-    let match;
-    while ((match = expression.exec(value)) && matches.length < MAX_MATCHES_PER_PATTERN) {
-        const replaced = match[0].replace(new RegExp(expressionSource), replacement).replace(/(?:\.|-)?min$/i, '');
-        if (VERSION_RE.test(replaced))
-            matches.push(replaced);
-        if (match[0] === '')
-            expression.lastIndex += 1;
-    }
-    return matches;
-}
 function addDetected(detected, component, version, method) {
     const normalizedVersion = version.replace(/(?:\.|-)?min$/i, '').slice(0, MAX_VERSION_LENGTH);
     if (!COMPONENT_RE.test(component) || !VERSION_RE.test(normalizedVersion))
@@ -174,24 +219,87 @@ function scanFilename(detected, reference) {
         }
     }
 }
-function scanInlineContent(detected, content) {
+function scanInlineSignatures(detected, value) {
+    if (!value)
+        return { timedOut: false, unavailable: false };
+    const controlBuffer = new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT);
+    const outputBuffer = new SharedArrayBuffer(MAX_INLINE_LIBRARY_WORKER_BYTES);
+    const control = new Int32Array(controlBuffer);
+    try {
+        if (!inlineRegexWorker) {
+            const createdWorker = new Worker(INLINE_REGEX_WORKER_SOURCE, {
+                eval: true,
+                workerData: { catalogue: INLINE_EXTRACTOR_CATALOGUE },
+            });
+            inlineRegexWorker = createdWorker;
+            createdWorker.unref();
+            createdWorker.once('exit', () => {
+                if (inlineRegexWorker === createdWorker)
+                    inlineRegexWorker = null;
+            });
+            createdWorker.once('error', () => {
+                if (inlineRegexWorker === createdWorker)
+                    inlineRegexWorker = null;
+            });
+        }
+        inlineRegexWorker.postMessage({ value, control: controlBuffer, output: outputBuffer });
+    }
+    catch {
+        void inlineRegexWorker?.terminate().catch(() => { });
+        inlineRegexWorker = null;
+        return { timedOut: false, unavailable: true };
+    }
+    const wait = Atomics.wait(control, 0, 0, MAX_INLINE_LIBRARY_SCAN_MS);
+    const length = Atomics.load(control, 0);
+    if (wait === 'timed-out') {
+        void inlineRegexWorker?.terminate().catch(() => { });
+        inlineRegexWorker = null;
+        return { timedOut: true, unavailable: false };
+    }
+    if (length < 1 || length > MAX_INLINE_LIBRARY_WORKER_BYTES) {
+        return { timedOut: false, unavailable: true };
+    }
+    try {
+        const parsed = JSON.parse(Buffer.from(new Uint8Array(outputBuffer, 0, length)).toString('utf8'));
+        if (!Array.isArray(parsed))
+            return { timedOut: false, unavailable: true };
+        for (const item of parsed.slice(0, MAX_LIBRARY_FINDINGS * 4)) {
+            if (!Array.isArray(item) || item.length !== 2)
+                continue;
+            const [component, version] = item;
+            if (typeof component === 'string' && typeof version === 'string') {
+                addDetected(detected, component, version, 'inline signature');
+            }
+        }
+        return { timedOut: false, unavailable: false };
+    }
+    catch {
+        return { timedOut: false, unavailable: true };
+    }
+}
+function scanInlineContent(detected, content, maximumSignatureCharacters) {
     const normalized = content.replace(/\r\n?|\n/g, '\n');
     const digest = createHash('sha1').update(normalized).digest('hex');
-    scanExtractor(detected, 'filecontent', normalized, 'inline signature');
+    const retainedCharacters = Math.max(0, Math.min(MAX_INLINE_LIBRARY_SCAN_CHARS, maximumSignatureCharacters, normalized.length));
+    const headCharacters = Math.ceil(retainedCharacters / 2);
+    const tailCharacters = retainedCharacters - headCharacters;
+    const signatureContent = retainedCharacters === 0
+        ? ''
+        : normalized.length <= retainedCharacters
+            ? normalized
+            : `${normalized.slice(0, headCharacters)}${tailCharacters ? normalized.slice(-tailCharacters) : ''}`;
     for (const [componentName, rawComponent] of Object.entries(CATALOG_COMPONENTS)) {
-        const component = record(rawComponent);
-        const extractors = record(component.extractors);
-        const replacementPatterns = Array.isArray(extractors.filecontentreplace) ? extractors.filecontentreplace : [];
-        for (const pattern of replacementPatterns.slice(0, 64)) {
-            for (const version of matchReplacementPattern(pattern, normalized)) {
-                addDetected(detected, componentName, version, 'inline signature');
-            }
-        }
+        const extractors = record(record(rawComponent).extractors);
         const hashes = record(extractors.hashes);
         const version = hashes[digest];
         if (typeof version === 'string')
             addDetected(detected, componentName, version, 'inline hash');
     }
+    return {
+        charactersExamined: retainedCharacters,
+        truncated: retainedCharacters < normalized.length,
+        signatureContent,
+    };
 }
 function severity(value) {
     return typeof value === 'string' && Object.hasOwn(SEVERITY_WEIGHT, value)
@@ -243,6 +351,9 @@ function analyzeBrowserLibraries(input = {}) {
     const detected = new Map();
     let referencesExamined = 0;
     let inlineScriptsExamined = 0;
+    let inlineSignatureCharactersExamined = 0;
+    let inlineSignatureLimitReached = false;
+    const inlineSignatureSamples = [];
     for (const script of htmlAnalysis.scripts) {
         if (script.reference) {
             referencesExamined += 1;
@@ -251,9 +362,16 @@ function analyzeBrowserLibraries(input = {}) {
         }
         else if (script.inlineContent && script.mediaType !== 'application/ld+json') {
             inlineScriptsExamined += 1;
-            scanInlineContent(detected, script.inlineContent);
+            const remaining = Math.max(0, MAX_INLINE_LIBRARY_SCAN_TOTAL_CHARS - inlineSignatureCharactersExamined);
+            const signatureScan = scanInlineContent(detected, script.inlineContent, remaining);
+            inlineSignatureCharactersExamined += signatureScan.charactersExamined;
+            inlineSignatureLimitReached ||= signatureScan.truncated;
+            if (signatureScan.signatureContent)
+                inlineSignatureSamples.push(signatureScan.signatureContent);
         }
     }
+    const inlineSignatureResult = scanInlineSignatures(detected, inlineSignatureSamples.join('\u0000'));
+    const inlineSignatureUnavailable = inlineSignatureResult.timedOut || inlineSignatureResult.unavailable;
     const allFindings = [...detected.values()]
         .map(findingFromDetection)
         .sort((left, right) => ((right.highestSeverity ? SEVERITY_WEIGHT[right.highestSeverity] : -1)
@@ -267,6 +385,8 @@ function analyzeBrowserLibraries(input = {}) {
         || htmlAnalysis.tagLimitReached
         || htmlAnalysis.scriptLimitReached
         || htmlAnalysis.inlineLimitReached
+        || inlineSignatureLimitReached
+        || inlineSignatureUnavailable
         || findingLimitReached;
     const limitations = [
         'Library versions are inferred from passive static signatures and may be absent, transformed, or misleading.',
@@ -284,6 +404,12 @@ function analyzeBrowserLibraries(input = {}) {
         limitations.push(`Only the first ${MAX_SCRIPT_ELEMENTS} script elements were evaluated.`);
     if (htmlAnalysis.inlineLimitReached)
         limitations.push(`Inline script evaluation reached its ${MAX_INLINE_SCRIPT_TOTAL_CHARS}-character cumulative boundary.`);
+    if (inlineSignatureLimitReached)
+        limitations.push(`Passive library signature matching evaluated a deterministic ${MAX_INLINE_LIBRARY_SCAN_TOTAL_CHARS}-character cumulative sample across inline scripts; full-content hashes still used the complete bounded script content.`);
+    if (inlineSignatureResult.timedOut)
+        limitations.push(`Passive library signature matching exceeded its ${MAX_INLINE_LIBRARY_SCAN_MS} ms isolated-worker deadline; hash evidence was still evaluated.`);
+    if (inlineSignatureResult.unavailable)
+        limitations.push('Passive library signature matching was unavailable in its isolated worker; hash evidence was still evaluated.');
     if (findingLimitReached)
         limitations.push(`Only the first ${MAX_LIBRARY_FINDINGS} library findings were retained.`);
     return {
@@ -311,6 +437,9 @@ function analyzeBrowserLibraries(input = {}) {
                 referencesExamined,
                 inlineScriptsExamined,
                 inlineCharactersExamined: htmlAnalysis.inlineCharactersExamined,
+                inlineSignatureCharactersExamined,
+                inlineSignatureTimedOut: inlineSignatureResult.timedOut,
+                inlineSignatureUnavailable: inlineSignatureResult.unavailable,
                 catalogComponents: Object.keys(CATALOG_COMPONENTS).length,
                 findings: allFindings.length,
                 advisoryMatches: allFindings.reduce((sum, finding) => sum + finding.advisoryCount, 0),
@@ -320,4 +449,4 @@ function analyzeBrowserLibraries(input = {}) {
         findings: allFindings.slice(0, MAX_LIBRARY_FINDINGS),
     };
 }
-export { BROWSER_LIBRARY_PROFILE_VERSION, MAX_INLINE_SCRIPT_CHARS, MAX_INLINE_SCRIPT_TOTAL_CHARS, MAX_LIBRARY_FINDINGS, MAX_LIBRARY_HTML_CHARS, MAX_SCRIPT_ELEMENTS, analyzeBrowserLibraries, };
+export { BROWSER_LIBRARY_PROFILE_VERSION, MAX_INLINE_SCRIPT_CHARS, MAX_INLINE_SCRIPT_TOTAL_CHARS, MAX_INLINE_LIBRARY_SCAN_CHARS, MAX_INLINE_LIBRARY_SCAN_TOTAL_CHARS, MAX_LIBRARY_FINDINGS, MAX_LIBRARY_HTML_CHARS, MAX_SCRIPT_ELEMENTS, analyzeBrowserLibraries, };

package/lib/dns-convergence-review.mjs

@@ -0,0 +1,183 @@
+import { exactKeys, requireBoundedString, requireDomainName, requireIsoTimestamp, requireRecord, } from "./bounded-contract-normalizers.mjs";
+import { normaliseRdata } from "./zone-intent-review.mjs";
+export const DNS_CONVERGENCE_INPUT_SCHEMA = 'whoisleuth.dns-convergence.input';
+export const DNS_CONVERGENCE_REVIEW_SCHEMA = 'whoisleuth.dns-convergence.review';
+export const DNS_CONVERGENCE_REVIEW_VERSION = 1;
+export const MAX_DNS_CONVERGENCE_SNAPSHOTS = 100;
+export const MAX_DNS_CONVERGENCE_RECORDS = 2_000;
+const RECORD_TYPES = new Set(['A', 'AAAA', 'CAA', 'CNAME', 'MX', 'NS', 'SOA', 'SRV', 'SVCB', 'HTTPS', 'TLSA', 'TXT']);
+const ROOT_KEYS = new Set(['schema', 'version', 'domain', 'expected', 'snapshots']);
+const EXPECTED_KEYS = new Set(['owner', 'type', 'values']);
+const SNAPSHOT_KEYS = new Set(['observer', 'source', 'observedAt', 'state', 'records']);
+const RECORD_KEYS = new Set(['owner', 'type', 'value', 'ttl']);
+function type(value, label) {
+    const candidate = requireBoundedString(value, label, 16).toUpperCase();
+    if (!RECORD_TYPES.has(candidate))
+        throw new TypeError(`${label} is unsupported.`);
+    return candidate;
+}
+function owner(value, apex, label) {
+    const candidate = requireBoundedString(value, label, 253).toLowerCase().replace(/\.$/u, '');
+    if (candidate === '@')
+        return apex;
+    if (candidate.length > 253 || candidate.split('.').some((part) => !/^[a-z0-9_](?:[a-z0-9_-]{0,61}[a-z0-9_])?$/u.test(part))) {
+        throw new TypeError(`${label} must be a valid DNS owner name.`);
+    }
+    return candidate;
+}
+function state(value, label) {
+    if (value !== 'observed' && value !== 'partial' && value !== 'unavailable')
+        throw new TypeError(`${label} is unsupported.`);
+    return value;
+}
+function ttl(value, label) {
+    if (value === null || value === undefined)
+        return null;
+    if (!Number.isSafeInteger(value) || Number(value) < 0 || Number(value) > 0x7fff_ffff)
+        throw new TypeError(`${label} is outside its supported range.`);
+    return Number(value);
+}
+function normaliseValue(recordType, value) {
+    if (recordType !== 'SOA')
+        return normaliseRdata(recordType, value, null);
+    const fields = value.trim().split(/\s+/u);
+    if (fields.length >= 2) {
+        fields[0] = fields[0]?.toLowerCase().replace(/\.$/u, '') ?? '';
+        fields[1] = fields[1]?.toLowerCase().replace(/\.$/u, '') ?? '';
+    }
+    return { value: fields.join(' '), valueTreatment: 'normalised' };
+}
+function record(value, apex, label) {
+    const input = requireRecord(value, label);
+    exactKeys(input, RECORD_KEYS, label);
+    const recordType = type(input.type, `${label}.type`);
+    const normalised = normaliseValue(recordType, requireBoundedString(input.value, `${label}.value`, 16_384));
+    return Object.freeze({
+        owner: owner(input.owner, apex, `${label}.owner`),
+        type: recordType,
+        value: normalised.value,
+        valueTreatment: normalised.valueTreatment,
+        ttl: ttl(input.ttl, `${label}.ttl`),
+    });
+}
+function expectedRows(value, apex) {
+    if (value === null || value === undefined)
+        return Object.freeze([]);
+    if (!Array.isArray(value) || value.length > 100)
+        throw new TypeError('expected must contain no more than 100 rows.');
+    const keys = new Set();
+    return Object.freeze(value.map((raw, index) => {
+        const input = requireRecord(raw, `expected[${index}]`);
+        exactKeys(input, EXPECTED_KEYS, `expected[${index}]`);
+        const recordType = type(input.type, `expected[${index}].type`);
+        const recordOwner = owner(input.owner, apex, `expected[${index}].owner`);
+        const key = `${recordOwner}\u0000${recordType}`;
+        if (keys.has(key))
+            throw new TypeError(`expected[${index}] duplicates an owner and type.`);
+        keys.add(key);
+        if (!Array.isArray(input.values) || input.values.length > 100)
+            throw new TypeError(`expected[${index}].values must contain no more than 100 entries.`);
+        const values = [...new Set(input.values.map((entry, valueIndex) => normaliseValue(recordType, requireBoundedString(entry, `expected[${index}].values[${valueIndex}]`, 16_384)).value))].sort();
+        return Object.freeze({ owner: recordOwner, type: recordType, values: Object.freeze(values) });
+    }));
+}
+export function reviewDnsConvergence(inputRaw, generatedAtValue = new Date().toISOString()) {
+    const input = requireRecord(inputRaw, 'DNS convergence input');
+    if (input.schema !== DNS_CONVERGENCE_INPUT_SCHEMA || input.version !== 1) {
+        throw new TypeError(`DNS convergence input must use ${DNS_CONVERGENCE_INPUT_SCHEMA} version 1.`);
+    }
+    exactKeys(input, ROOT_KEYS, 'DNS convergence input');
+    const apex = requireDomainName(input.domain, 'domain');
+    const expected = expectedRows(input.expected, apex);
+    if (!Array.isArray(input.snapshots) || input.snapshots.length < 2 || input.snapshots.length > MAX_DNS_CONVERGENCE_SNAPSHOTS) {
+        throw new TypeError(`snapshots must contain between 2 and ${MAX_DNS_CONVERGENCE_SNAPSHOTS} entries.`);
+    }
+    let recordCount = 0;
+    const snapshots = input.snapshots.map((raw, index) => {
+        const item = requireRecord(raw, `snapshots[${index}]`);
+        exactKeys(item, SNAPSHOT_KEYS, `snapshots[${index}]`);
+        if (!Array.isArray(item.records))
+            throw new TypeError(`snapshots[${index}].records must be an array.`);
+        recordCount += item.records.length;
+        if (recordCount > MAX_DNS_CONVERGENCE_RECORDS)
+            throw new TypeError(`DNS convergence input is limited to ${MAX_DNS_CONVERGENCE_RECORDS} records.`);
+        const observationState = state(item.state, `snapshots[${index}].state`);
+        if (observationState === 'unavailable' && item.records.length)
+            throw new TypeError(`snapshots[${index}] cannot contain records when unavailable.`);
+        return Object.freeze({
+            observer: requireBoundedString(item.observer, `snapshots[${index}].observer`, 120),
+            source: requireBoundedString(item.source, `snapshots[${index}].source`, 240),
+            observedAt: requireIsoTimestamp(item.observedAt, `snapshots[${index}].observedAt`),
+            state: observationState,
+            records: Object.freeze(item.records.map((entry, recordIndex) => record(entry, apex, `snapshots[${index}].records[${recordIndex}]`))),
+        });
+    }).sort((left, right) => left.observedAt.localeCompare(right.observedAt) || left.observer.localeCompare(right.observer));
+    const observers = [...new Set(snapshots.map((item) => item.observer))];
+    if (observers.length < 2)
+        throw new TypeError('DNS convergence review requires at least two distinct observer labels.');
+    const latestByObserver = observers.map((observer) => snapshots.filter((item) => item.observer === observer).at(-1));
+    const keys = [...new Set([
+            ...expected.map((item) => `${item.owner}\u0000${item.type}`),
+            ...snapshots.flatMap((item) => item.records.map((entry) => `${entry.owner}\u0000${entry.type}`)),
+        ])].sort();
+    const rows = keys.map((key) => {
+        const [recordOwner = '', recordType = ''] = key.split('\u0000');
+        const expectedRow = expected.find((item) => item.owner === recordOwner && item.type === recordType);
+        const observations = latestByObserver.map((snapshot) => {
+            const matching = snapshot.records.filter((entry) => entry.owner === recordOwner && entry.type === recordType);
+            const values = [...new Set(matching.map((entry) => entry.value))].sort();
+            const ttls = matching.flatMap((entry) => entry.ttl === null ? [] : [entry.ttl]);
+            const cacheUntil = ttls.length
+                ? new Date(Date.parse(snapshot.observedAt) + Math.max(...ttls) * 1_000).toISOString()
+                : null;
+            return Object.freeze({
+                observer: snapshot.observer,
+                source: snapshot.source,
+                observedAt: snapshot.observedAt,
+                state: snapshot.state,
+                values: Object.freeze(values),
+                cacheUntil,
+            });
+        });
+        const complete = observations.filter((item) => item.state === 'observed');
+        const incomplete = observations.some((item) => item.state !== 'observed');
+        const signatures = new Set(complete.map((item) => JSON.stringify(item.values)));
+        const aligned = complete.length >= 2 && signatures.size === 1;
+        const matchesExpected = expectedRow
+            ? aligned && JSON.stringify(complete[0]?.values ?? []) === JSON.stringify(expectedRow.values)
+            : null;
+        const rowState = incomplete ? 'incomplete'
+            : complete.length < 2 ? 'insufficient'
+                : !aligned ? 'divergent'
+                    : matchesExpected === false ? 'unexpected'
+                        : 'converged';
+        return Object.freeze({
+            owner: recordOwner,
+            type: recordType,
+            state: rowState,
+            expectedValues: expectedRow?.values ?? null,
+            observations: Object.freeze(observations),
+        });
+    });
+    const reasons = Object.freeze([
+        ...rows.filter((row) => row.state !== 'converged').map((row) => `${row.owner} ${row.type} is ${row.state}.`),
+        ...latestByObserver.filter((item) => item.state !== 'observed').map((item) => `${item.observer} latest evidence is ${item.state}.`),
+    ].slice(0, 200));
+    return Object.freeze({
+        schema: DNS_CONVERGENCE_REVIEW_SCHEMA,
+        version: DNS_CONVERGENCE_REVIEW_VERSION,
+        generatedAt: requireIsoTimestamp(generatedAtValue, 'generatedAt'),
+        domain: apex,
+        state: reasons.length ? 'review' : 'converged',
+        observers: Object.freeze(observers),
+        snapshots: Object.freeze(snapshots),
+        rows: Object.freeze(rows),
+        gate: Object.freeze({ pass: reasons.length === 0, reasons }),
+        limitations: Object.freeze([
+            'This local workbench compares only supplied observations and makes no DNS request.',
+            'Resolver differences can reflect caches, split-horizon policy, interception, collection timing, or propagation; they do not establish which value is authoritative.',
+            'Cache-until times are simple observation-time plus supplied TTL projections and do not reveal actual cache age, refresh behaviour, or resolver policy.',
+            'Partial and unavailable snapshots remain incomplete and are never interpreted as record absence.',
+        ]),
+    });
+}