@slicedearth/whoisleuth-cli 1.45.0 → 2.0.0

package/cli/registry-cohort.mjs

@@ -1,119 +1,401 @@
 import { Buffer } from 'node:buffer';
+import { canonicalArtifactJsonV2 } from "../packages/evidence/artifact-integrity.mjs";
+import { normalizeExplicitIsoTimestamp } from "../packages/evidence/observation.mjs";
+import { scanBoundedJson } from "./bounded-json.mjs";
 import { CliUsageError } from "./errors.mjs";
 import { buildRegistryDoctorReport } from "./registry-doctor.mjs";
+import { SAVED_LOOKUP_SCHEMA, parseSavedLookupDocument, } from "./saved-lookup.mjs";
 export const REGISTRY_COHORT_SCHEMA = 'whoisleuth.cli.registry-cohort';
-export const REGISTRY_COHORT_VERSION = 1;
+export const REGISTRY_COHORT_VERSION = 2;
 export const MAX_REGISTRY_COHORT_INPUT_BYTES = 16 * 1024 * 1024;
 export const MAX_REGISTRY_COHORT_SAMPLES = 500;
+export const MAX_REGISTRY_COHORT_GROUPS = 500;
+export const MAX_REGISTRY_COHORT_INPUT_POINTS = 2_000;
+export const MAX_REGISTRY_COHORT_TIMELINE_POINTS = 50;
+export const MAX_REGISTRY_COHORT_OMISSIONS = 1_000_000;
 export const MIN_REGISTRY_COHORT_SAMPLE = 5;
-function record(value) {
-    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+const ROOT_KEYS = new Set(['schema', 'version', 'generatedAt', 'inputFamily', 'sampleCount', 'reportsMerged', 'minimumCohortSample', 'sampleWindow', 'cohorts', 'omissions', 'truncated', 'limitations']);
+const COHORT_KEYS = new Set(['suffix', 'profileId', 'sampleCount', 'state', 'latestState', 'sampleWindow', 'sourceAlignment', 'publication', 'timeline', 'timelineOmitted']);
+const POINT_KEYS = new Set(['reportGeneratedAt', 'sampleWindow', 'sampleCount', 'state', 'sourceAlignment', 'publication']);
+const SOURCE_KEYS = new Set(['investigate', 'expectedConstraints', 'observed']);
+const PUBLICATION_KEYS = new Set(['reviewItems', 'objectIdentifiersObserved', 'baseConformanceObserved', 'selfLinksObserved', 'redactionMetadataObserved']);
+const WINDOW_KEYS = new Set(['from', 'to']);
+const OMISSION_KEYS = new Set(['duplicateTimelinePoints', 'timelinePoints']);
+const LIMITATIONS = Object.freeze([
+    'The report intentionally omits domains, queries and raw evidence. It groups retained observations only by suffix and capability profile.',
+    `Every timeline point retains its original state. Cohorts with fewer than ${MIN_REGISTRY_COHORT_SAMPLE} observations remain insufficient sample and are never promoted by summing overlapping reports.`,
+    'A merged cohort keeps the most conservative retained state and separately reports the latest point. Duplicate points are suppressed and inherited omission counts are not summed across overlapping retained reports.',
+    'Review fixture provenance and source health before changing a parser or registry access profile.',
+]);
+function record(value, label) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new CliUsageError(`${label} must be an object.`);
+    return value;
 }
-function documents(text) {
-    if (Buffer.byteLength(text, 'utf8') > MAX_REGISTRY_COHORT_INPUT_BYTES) {
-        throw new CliUsageError(`Registry cohort input is limited to ${MAX_REGISTRY_COHORT_INPUT_BYTES} bytes.`);
+function exact(value, keys, label) {
+    const item = record(value, label);
+    if (Object.keys(item).some((key) => !keys.has(key)) || [...keys].some((key) => !Object.hasOwn(item, key))) {
+        throw new CliUsageError(`${label} does not match its exact retained contract.`);
+    }
+    return item;
+}
+function integer(value, minimum, maximum, label) {
+    if (!Number.isSafeInteger(value) || Number(value) < minimum || Number(value) > maximum) {
+        throw new CliUsageError(`${label} is outside its supported bound.`);
     }
+    return Number(value);
+}
+function timestamp(value, label) {
+    if (typeof value !== 'string' || value.length > 64 || /[\u0000-\u001f\u007f]/u.test(value)) {
+        throw new CliUsageError(`${label} is invalid.`);
+    }
+    const normalized = normalizeExplicitIsoTimestamp(value);
+    if (normalized)
+        return normalized;
+    throw new CliUsageError(`${label} is invalid.`);
+}
+function identifier(value, label) {
+    if (typeof value !== 'string' || !/^[a-z0-9][a-z0-9_-]{0,119}$/u.test(value))
+        throw new CliUsageError(`${label} is invalid.`);
+    return value;
+}
+function suffix(value) {
+    if (typeof value !== 'string' || !/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/u.test(value))
+        throw new CliUsageError('Registry cohort suffix is invalid.');
+    return value;
+}
+function state(value, label) {
+    if (value !== 'consistent' && value !== 'insufficient_sample' && value !== 'review')
+        throw new CliUsageError(`${label} is invalid.`);
+    return value;
+}
+function window(value, label) {
+    const item = exact(value, WINDOW_KEYS, label);
+    const from = timestamp(item.from, `${label} from`);
+    const to = timestamp(item.to, `${label} to`);
+    if (from > to)
+        throw new CliUsageError(`${label} is reversed.`);
+    return Object.freeze({ from, to });
+}
+function sourceAlignment(value, sampleCount, label) {
+    const item = exact(value, SOURCE_KEYS, label);
+    return Object.freeze({
+        investigate: integer(item.investigate, 0, sampleCount * 2, `${label} investigate`),
+        expectedConstraints: integer(item.expectedConstraints, 0, sampleCount * 2, `${label} expected constraints`),
+        observed: integer(item.observed, 0, sampleCount * 2, `${label} observed`),
+    });
+}
+function publication(value, sampleCount, label) {
+    const item = exact(value, PUBLICATION_KEYS, label);
+    return Object.freeze({
+        reviewItems: integer(item.reviewItems, 0, sampleCount * 4, `${label} review items`),
+        objectIdentifiersObserved: integer(item.objectIdentifiersObserved, 0, sampleCount, `${label} object identifiers`),
+        baseConformanceObserved: integer(item.baseConformanceObserved, 0, sampleCount, `${label} base conformance`),
+        selfLinksObserved: integer(item.selfLinksObserved, 0, sampleCount, `${label} self links`),
+        redactionMetadataObserved: integer(item.redactionMetadataObserved, 0, sampleCount, `${label} redaction metadata`),
+    });
+}
+function derivedState(sampleCount, sources, published) {
+    return sampleCount < MIN_REGISTRY_COHORT_SAMPLE
+        ? 'insufficient_sample'
+        : sources.investigate || published.reviewItems
+            ? 'review'
+            : 'consistent';
+}
+function conservativeState(states) {
+    return states.includes('review') ? 'review' : states.includes('insufficient_sample') ? 'insufficient_sample' : 'consistent';
+}
+function timelinePoint(value, label) {
+    const item = exact(value, POINT_KEYS, label);
+    const sampleCount = integer(item.sampleCount, 1, MAX_REGISTRY_COHORT_SAMPLES, `${label} sample count`);
+    const sources = sourceAlignment(item.sourceAlignment, sampleCount, `${label} source alignment`);
+    const published = publication(item.publication, sampleCount, `${label} publication`);
+    const pointState = state(item.state, `${label} state`);
+    if (pointState !== derivedState(sampleCount, sources, published))
+        throw new CliUsageError(`${label} state does not match its retained counts.`);
+    return Object.freeze({
+        reportGeneratedAt: timestamp(item.reportGeneratedAt, `${label} report generatedAt`),
+        sampleWindow: window(item.sampleWindow, `${label} sample window`),
+        sampleCount,
+        state: pointState,
+        sourceAlignment: sources,
+        publication: published,
+    });
+}
+function boundedLimitations(value, expected, label) {
+    if (!Array.isArray(value) || value.length !== expected.length || value.some((item, index) => item !== expected[index])) {
+        throw new CliUsageError(`${label} limitations do not match the supported target-free contract.`);
+    }
+}
+function parseInputDocuments(text) {
+    if (Buffer.byteLength(text, 'utf8') > MAX_REGISTRY_COHORT_INPUT_BYTES)
+        throw new CliUsageError(`Registry cohort input is limited to ${MAX_REGISTRY_COHORT_INPUT_BYTES} bytes.`);
     const trimmed = text.replace(/^\uFEFF/u, '').trim();
     if (!trimmed)
         throw new CliUsageError('Registry cohort input is empty.');
     let values;
     if (trimmed.startsWith('[')) {
-        let parsed;
         try {
-            parsed = JSON.parse(trimmed);
+            scanBoundedJson(trimmed);
+            const parsed = JSON.parse(trimmed);
+            if (!Array.isArray(parsed))
+                throw new Error('not array');
+            values = parsed;
         }
-        catch {
-            throw new CliUsageError('Registry cohort input must be valid JSON or JSONL.');
+        catch (error) {
+            if (error instanceof TypeError && /duplicate|nesting|value limit|key limit/iu.test(error.message))
+                throw new CliUsageError(error.message);
+            throw new CliUsageError('Registry cohort JSON input must be a valid array.');
         }
-        if (!Array.isArray(parsed))
-            throw new CliUsageError('Registry cohort JSON input must be an array.');
-        values = parsed;
     }
     else {
         const lines = trimmed.split(/\r?\n/u).filter((line) => line.trim());
+        if (!lines.length || lines.length > MAX_REGISTRY_COHORT_SAMPLES) {
+            throw new CliUsageError(`Registry cohort input must contain from 1 to ${MAX_REGISTRY_COHORT_SAMPLES} saved Lookups or retained cohort reports.`);
+        }
         values = lines.map((line, index) => {
             try {
+                scanBoundedJson(line);
                 return JSON.parse(line);
             }
-            catch {
+            catch (error) {
+                if (error instanceof TypeError && /duplicate|nesting|value limit|key limit/iu.test(error.message))
+                    throw new CliUsageError(`Registry cohort JSONL line ${index + 1}: ${error.message}`);
                 throw new CliUsageError(`Registry cohort JSONL line ${index + 1} is invalid.`);
             }
         });
     }
-    if (!values.length || values.length > MAX_REGISTRY_COHORT_SAMPLES) {
-        throw new CliUsageError(`Registry cohort input must contain from 1 to ${MAX_REGISTRY_COHORT_SAMPLES} saved Lookups.`);
-    }
-    const output = values.map(record);
-    if (output.some((item) => !Object.keys(item).length))
-        throw new CliUsageError('Every registry cohort item must be one saved Lookup object.');
-    return output;
+    if (!values.length || values.length > MAX_REGISTRY_COHORT_SAMPLES)
+        throw new CliUsageError(`Registry cohort input must contain from 1 to ${MAX_REGISTRY_COHORT_SAMPLES} saved Lookups or retained cohort reports.`);
+    return values.map((value, index) => record(value, `Registry cohort item ${index + 1}`));
 }
-export function buildRegistryCohortReport(text, generatedAt = new Date().toISOString()) {
-    const reports = documents(text).map((item) => buildRegistryDoctorReport(JSON.stringify(item), generatedAt));
+function groupPoint(reports, reportGeneratedAt) {
+    const sampleCount = reports.length;
+    const sources = Object.freeze({
+        investigate: reports.reduce((total, item) => total + item.summary.investigate, 0),
+        expectedConstraints: reports.reduce((total, item) => total + item.summary.expectedConstraints, 0),
+        observed: reports.reduce((total, item) => total + item.summary.observed, 0),
+    });
+    const published = Object.freeze({
+        reviewItems: reports.reduce((total, item) => total + item.publication.reviewItems, 0),
+        objectIdentifiersObserved: reports.filter((item) => item.publication.objectIdentifier.state === 'observed').length,
+        baseConformanceObserved: reports.filter((item) => item.publication.baseConformance.state === 'observed').length,
+        selfLinksObserved: reports.filter((item) => item.publication.selfLink.state === 'observed').length,
+        redactionMetadataObserved: reports.filter((item) => item.publication.redactionMetadata.state === 'observed').length,
+    });
+    const observed = reports.map((report) => report.generatedAt).sort();
+    return Object.freeze({
+        reportGeneratedAt,
+        sampleWindow: Object.freeze({ from: observed[0], to: observed.at(-1) }),
+        sampleCount,
+        state: derivedState(sampleCount, sources, published),
+        sourceAlignment: sources,
+        publication: published,
+    });
+}
+function sourceReportsFromLookups(documents, generatedAt) {
+    const reports = documents.map((item) => {
+        const raw = JSON.stringify(item);
+        const lookup = parseSavedLookupDocument(raw, { label: 'Registry cohort saved Lookup' });
+        return buildRegistryDoctorReport(raw, timestamp(lookup.generatedAt, 'Saved Lookup generatedAt'));
+    });
     const groups = new Map();
     for (const report of reports) {
         const key = `${report.suffix}\u0000${report.profile.id}`;
-        const group = groups.get(key) ?? [];
-        group.push(report);
-        groups.set(key, group);
+        groups.set(key, [...(groups.get(key) ?? []), report]);
     }
     const cohorts = [...groups.values()].map((group) => {
         const sample = group[0];
-        if (!sample)
-            throw new CliUsageError('Registry cohort grouping failed.');
-        const sampleCount = group.length;
-        const investigate = group.reduce((total, item) => total + item.summary.investigate, 0);
-        const publicationReviewItems = group.reduce((total, item) => total + item.publication.reviewItems, 0);
+        const point = groupPoint(group, generatedAt);
+        return Object.freeze({ suffix: sample.suffix, profileId: sample.profile.id, sampleWindow: point.sampleWindow, points: Object.freeze([point]), inheritedState: point.state, upstreamTimelineOmitted: 0 });
+    });
+    const observed = reports.map((report) => report.generatedAt).sort();
+    return [Object.freeze({ generatedAt, sampleWindow: Object.freeze({ from: observed[0], to: observed.at(-1) }), cohorts: Object.freeze(cohorts), duplicateTimelinePoints: 0 })];
+}
+function parseCurrentReport(value) {
+    const root = exact(value, ROOT_KEYS, 'Registry cohort v2 report');
+    if (root.schema !== REGISTRY_COHORT_SCHEMA || root.version !== REGISTRY_COHORT_VERSION)
+        throw new CliUsageError('Registry cohort report version is unsupported.');
+    const generatedAt = timestamp(root.generatedAt, 'Registry cohort v2 generatedAt');
+    if (root.inputFamily !== 'saved_lookups' && root.inputFamily !== 'retained_reports')
+        throw new CliUsageError('Registry cohort v2 input family is invalid.');
+    const reportsMerged = integer(root.reportsMerged, 0, MAX_REGISTRY_COHORT_SAMPLES, 'Registry cohort v2 reports merged');
+    if ((root.inputFamily === 'saved_lookups') !== (reportsMerged === 0))
+        throw new CliUsageError('Registry cohort v2 report count does not match its input family.');
+    if (root.minimumCohortSample !== MIN_REGISTRY_COHORT_SAMPLE)
+        throw new CliUsageError('Registry cohort v2 minimum sample is unsupported.');
+    const reportWindow = window(root.sampleWindow, 'Registry cohort v2 sample window');
+    boundedLimitations(root.limitations, LIMITATIONS, 'Registry cohort v2');
+    const omissions = exact(root.omissions, OMISSION_KEYS, 'Registry cohort v2 omissions');
+    const duplicateTimelinePoints = integer(omissions.duplicateTimelinePoints, 0, MAX_REGISTRY_COHORT_OMISSIONS, 'Registry cohort v2 duplicate points');
+    const omittedTimelinePoints = integer(omissions.timelinePoints, 0, MAX_REGISTRY_COHORT_OMISSIONS, 'Registry cohort v2 omitted points');
+    if (root.truncated !== (omittedTimelinePoints > 0))
+        throw new CliUsageError('Registry cohort v2 truncation state is inconsistent.');
+    if (!Array.isArray(root.cohorts) || !root.cohorts.length || root.cohorts.length > MAX_REGISTRY_COHORT_GROUPS)
+        throw new CliUsageError('Registry cohort v2 groups are invalid.');
+    const seen = new Set();
+    let represented = 0;
+    let cohortOmitted = 0;
+    const cohorts = root.cohorts.map((candidate, index) => {
+        const item = exact(candidate, COHORT_KEYS, `Registry cohort v2 group ${index + 1}`);
+        const groupSuffix = suffix(item.suffix);
+        const profileId = identifier(item.profileId, 'Registry cohort v2 profile ID');
+        const key = `${groupSuffix}\u0000${profileId}`;
+        if (seen.has(key))
+            throw new CliUsageError('Registry cohort v2 groups must be unique.');
+        seen.add(key);
+        const count = integer(item.sampleCount, 1, MAX_REGISTRY_COHORT_SAMPLES, 'Registry cohort v2 group sample count');
+        const groupWindow = window(item.sampleWindow, 'Registry cohort v2 group sample window');
+        const timelineOmitted = integer(item.timelineOmitted, 0, MAX_REGISTRY_COHORT_OMISSIONS, 'Registry cohort v2 group omitted points');
+        cohortOmitted += timelineOmitted;
+        if (!Array.isArray(item.timeline) || !item.timeline.length || item.timeline.length > MAX_REGISTRY_COHORT_TIMELINE_POINTS)
+            throw new CliUsageError('Registry cohort v2 timeline is invalid.');
+        const points = item.timeline.map((point, pointIndex) => timelinePoint(point, `Registry cohort v2 point ${pointIndex + 1}`));
+        const identities = points.map(canonicalArtifactJsonV2);
+        if (new Set(identities).size !== points.length || identities.some((identity, pointIndex) => pointIndex > 0 && pointOrder(points[pointIndex - 1], points[pointIndex]) > 0))
+            throw new CliUsageError('Registry cohort v2 timeline must be unique and ordered.');
+        const latest = points.at(-1);
+        const groupState = state(item.state, 'Registry cohort v2 group state');
+        const latestState = state(item.latestState, 'Registry cohort v2 latest state');
+        const sources = sourceAlignment(item.sourceAlignment, count, 'Registry cohort v2 group source alignment');
+        const published = publication(item.publication, count, 'Registry cohort v2 group publication');
+        const visibleState = conservativeState(points.map((point) => point.state));
+        const pointFrom = points.map((point) => point.sampleWindow.from).sort()[0];
+        const pointTo = points.map((point) => point.sampleWindow.to).sort().at(-1);
+        if (latestState !== latest.state || count !== latest.sampleCount
+            || canonicalArtifactJsonV2(sources) !== canonicalArtifactJsonV2(latest.sourceAlignment)
+            || canonicalArtifactJsonV2(published) !== canonicalArtifactJsonV2(latest.publication)
+            || (timelineOmitted === 0 && groupState !== visibleState)
+            || (timelineOmitted > 0 && conservativeState([groupState, visibleState]) !== groupState)
+            || groupWindow.from > pointFrom || groupWindow.to < pointTo) {
+            throw new CliUsageError('Registry cohort v2 current group projection is inconsistent with its timeline.');
+        }
+        represented += count;
+        return Object.freeze({ suffix: groupSuffix, profileId, sampleWindow: groupWindow, points: Object.freeze(points), inheritedState: groupState, upstreamTimelineOmitted: timelineOmitted });
+    });
+    if (integer(root.sampleCount, 1, MAX_REGISTRY_COHORT_GROUPS * MAX_REGISTRY_COHORT_SAMPLES, 'Registry cohort v2 sample count') !== represented
+        || cohortOmitted !== omittedTimelinePoints
+        || reportWindow.from !== [...cohorts].sort((a, b) => a.sampleWindow.from.localeCompare(b.sampleWindow.from))[0]?.sampleWindow.from
+        || reportWindow.to !== [...cohorts].sort((a, b) => b.sampleWindow.to.localeCompare(a.sampleWindow.to))[0]?.sampleWindow.to) {
+        throw new CliUsageError('Registry cohort v2 report summary is inconsistent with its groups.');
+    }
+    return Object.freeze({ generatedAt, sampleWindow: reportWindow, cohorts: Object.freeze(cohorts), duplicateTimelinePoints });
+}
+function pointOrder(left, right) {
+    return left.sampleWindow.to.localeCompare(right.sampleWindow.to)
+        || left.reportGeneratedAt.localeCompare(right.reportGeneratedAt)
+        || canonicalArtifactJsonV2(left).localeCompare(canonicalArtifactJsonV2(right));
+}
+function buildCurrentReport(sourceReports, generatedAt, inputFamily, directSampleCount) {
+    const totalPoints = sourceReports.reduce((sum, report) => sum + report.cohorts.reduce((groupSum, cohort) => groupSum + cohort.points.length, 0), 0);
+    if (totalPoints > MAX_REGISTRY_COHORT_INPUT_POINTS)
+        throw new CliUsageError(`Retained registry cohort input contains more than ${MAX_REGISTRY_COHORT_INPUT_POINTS} timeline points.`);
+    const groups = new Map();
+    for (const report of sourceReports)
+        for (const cohort of report.cohorts) {
+            const key = `${cohort.suffix}\u0000${cohort.profileId}`;
+            groups.set(key, [...(groups.get(key) ?? []), cohort]);
+        }
+    if (!groups.size || groups.size > MAX_REGISTRY_COHORT_GROUPS)
+        throw new CliUsageError(`Registry cohort output is limited to ${MAX_REGISTRY_COHORT_GROUPS} suffix/profile groups.`);
+    let duplicateTimelinePoints = Math.max(0, ...sourceReports.map((report) => report.duplicateTimelinePoints));
+    const cohorts = [...groups.entries()].map(([key, inputs]) => {
+        const unique = new Map();
+        for (const input of inputs)
+            for (const point of input.points) {
+                const identity = canonicalArtifactJsonV2(point);
+                if (unique.has(identity))
+                    duplicateTimelinePoints += 1;
+                else
+                    unique.set(identity, point);
+            }
+        const allPoints = [...unique.values()].sort(pointOrder);
+        const locallyOmitted = Math.max(0, allPoints.length - MAX_REGISTRY_COHORT_TIMELINE_POINTS);
+        const timeline = allPoints.slice(-MAX_REGISTRY_COHORT_TIMELINE_POINTS);
+        const latest = timeline.at(-1);
+        const upstreamTimelineOmitted = Math.max(0, ...inputs.map((input) => input.upstreamTimelineOmitted));
+        const groupWindow = Object.freeze({
+            from: inputs.map((input) => input.sampleWindow.from).sort()[0],
+            to: inputs.map((input) => input.sampleWindow.to).sort().at(-1),
+        });
         return Object.freeze({
-            suffix: sample.suffix,
-            profileId: sample.profile.id,
-            sampleCount,
-            state: sampleCount < MIN_REGISTRY_COHORT_SAMPLE
-                ? 'insufficient_sample'
-                : investigate || publicationReviewItems
-                    ? 'review'
-                    : 'consistent',
-            sourceAlignment: Object.freeze({
-                investigate,
-                expectedConstraints: group.reduce((total, item) => total + item.summary.expectedConstraints, 0),
-                observed: group.reduce((total, item) => total + item.summary.observed, 0),
-            }),
-            publication: Object.freeze({
-                reviewItems: publicationReviewItems,
-                objectIdentifiersObserved: group.filter((item) => item.publication.objectIdentifier.state === 'observed').length,
-                baseConformanceObserved: group.filter((item) => item.publication.baseConformance.state === 'observed').length,
-                selfLinksObserved: group.filter((item) => item.publication.selfLink.state === 'observed').length,
-                redactionMetadataObserved: group.filter((item) => item.publication.redactionMetadata.state === 'observed').length,
-            }),
+            suffix: key.split('\u0000')[0],
+            profileId: key.split('\u0000')[1],
+            sampleCount: latest.sampleCount,
+            state: conservativeState([...inputs.map((input) => input.inheritedState), ...allPoints.map((point) => point.state)]),
+            latestState: latest.state,
+            sampleWindow: groupWindow,
+            sourceAlignment: latest.sourceAlignment,
+            publication: latest.publication,
+            timeline: Object.freeze(timeline),
+            timelineOmitted: upstreamTimelineOmitted + locallyOmitted,
         });
     }).sort((left, right) => left.suffix.localeCompare(right.suffix) || left.profileId.localeCompare(right.profileId));
+    const timelinePoints = cohorts.reduce((sum, cohort) => sum + cohort.timelineOmitted, 0);
+    if (duplicateTimelinePoints > MAX_REGISTRY_COHORT_OMISSIONS || timelinePoints > MAX_REGISTRY_COHORT_OMISSIONS) {
+        throw new CliUsageError(`Registry cohort omission accounting exceeds the ${MAX_REGISTRY_COHORT_OMISSIONS}-item bound.`);
+    }
+    const allWindows = sourceReports.map((report) => report.sampleWindow);
     return Object.freeze({
         schema: REGISTRY_COHORT_SCHEMA,
         version: REGISTRY_COHORT_VERSION,
-        generatedAt,
-        sampleCount: reports.length,
+        generatedAt: timestamp(generatedAt, 'Registry cohort generatedAt'),
+        inputFamily,
+        sampleCount: inputFamily === 'saved_lookups' ? directSampleCount : cohorts.reduce((sum, cohort) => sum + cohort.sampleCount, 0),
+        reportsMerged: inputFamily === 'retained_reports' ? sourceReports.length : 0,
         minimumCohortSample: MIN_REGISTRY_COHORT_SAMPLE,
+        sampleWindow: Object.freeze({
+            from: allWindows.map((item) => item.from).sort()[0],
+            to: allWindows.map((item) => item.to).sort().at(-1),
+        }),
         cohorts: Object.freeze(cohorts),
-        limitations: Object.freeze([
-            'The report intentionally omits domains, queries and raw evidence. It groups saved observations only by suffix and capability profile.',
-            `Cohorts with fewer than ${MIN_REGISTRY_COHORT_SAMPLE} observations remain insufficient sample and must not drive catalogue changes.`,
-            'Repeated observations from one environment are not representative by themselves. Review fixture provenance and source health before changing a parser or access profile.',
-        ]),
+        omissions: Object.freeze({ duplicateTimelinePoints, timelinePoints }),
+        truncated: timelinePoints > 0,
+        limitations: LIMITATIONS,
     });
 }
+export function buildRegistryCohortReport(text, generatedAt = new Date().toISOString()) {
+    const documents = parseInputDocuments(text);
+    const families = new Set(documents.map((document) => document.schema === SAVED_LOOKUP_SCHEMA ? 'saved_lookups' : document.schema === REGISTRY_COHORT_SCHEMA ? 'retained_reports' : 'unsupported'));
+    if (families.size !== 1 || families.has('unsupported'))
+        throw new CliUsageError('Registry cohort input must contain only saved Lookups or only retained registry cohort reports; mixed families are rejected.');
+    const inputFamily = [...families][0];
+    if (inputFamily === 'saved_lookups') {
+        return buildCurrentReport(sourceReportsFromLookups(documents, timestamp(generatedAt, 'Registry cohort generatedAt')), generatedAt, inputFamily, documents.length);
+    }
+    const reports = [];
+    let retainedPoints = 0;
+    for (const document of documents) {
+        const report = document.version === REGISTRY_COHORT_VERSION
+            ? parseCurrentReport(document)
+            : (() => { throw new CliUsageError('Registry cohort report version is unsupported.'); })();
+        retainedPoints += report.cohorts.reduce((total, cohort) => total + cohort.points.length, 0);
+        if (retainedPoints > MAX_REGISTRY_COHORT_INPUT_POINTS) {
+            throw new CliUsageError(`Retained registry cohort input contains more than ${MAX_REGISTRY_COHORT_INPUT_POINTS} timeline points.`);
+        }
+        reports.push(report);
+    }
+    return buildCurrentReport(reports, generatedAt, inputFamily, 0);
+}
 export function formatRegistryCohortReport(report) {
     const output = [
-        'Registry quality cohort',
-        `Saved observations  ${report.sampleCount}`,
+        'Registry quality cohort timeline',
+        `Input family        ${report.inputFamily.replaceAll('_', ' ')}`,
+        `Current samples     ${report.sampleCount}`,
+        `Reports merged      ${report.reportsMerged}`,
+        `Sample window       ${report.sampleWindow.from} → ${report.sampleWindow.to}`,
         `Minimum sample      ${report.minimumCohortSample}`,
         '',
     ];
     for (const cohort of report.cohorts) {
         output.push(`.${cohort.suffix} · ${cohort.profileId} [${cohort.state.replaceAll('_', ' ')}]`);
-        output.push(`  Samples: ${cohort.sampleCount}`);
+        output.push(`  Latest: ${cohort.latestState.replaceAll('_', ' ')} · ${cohort.sampleCount} samples`);
+        output.push(`  Timeline points: ${cohort.timeline.length}${cohort.timelineOmitted ? ` · ${cohort.timelineOmitted} omitted` : ''}`);
         output.push(`  Source review items: ${cohort.sourceAlignment.investigate}`);
         output.push(`  Publication review items: ${cohort.publication.reviewItems}`);
     }
+    if (report.omissions.duplicateTimelinePoints)
+        output.push('', `Duplicate timeline points suppressed: ${report.omissions.duplicateTimelinePoints}`);
     output.push('', 'Limitations:');
     for (const limitation of report.limitations)
         output.push(`  - ${limitation}`);

package/cli/registry-doctor.mjs

@@ -1,9 +1,10 @@
 import { registryCapabilityFor, REGISTRY_CAPABILITIES_VERSION } from "../lib/registry-capabilities.mjs";
 import { recordOrEmpty } from "../lib/bounded-contract-normalizers.mjs";
+import { registryDateIso } from "../lib/registry-dates.mjs";
 import { CliUsageError } from "./errors.mjs";
 import { parseSavedLookupDocument } from "./saved-lookup.mjs";
 const REGISTRY_DOCTOR_SCHEMA = 'whoisleuth.cli.registry-doctor';
-const REGISTRY_DOCTOR_VERSION = 2;
+const REGISTRY_DOCTOR_VERSION = 3;
 function status(value) {
     return typeof value === 'string'
         ? value.replace(/[\u0000-\u001f\u007f]+/gu, ' ').trim().toLowerCase().slice(0, 40) || 'unavailable'
@@ -41,27 +42,37 @@ function publicationQuality(parsed, rdapStatus) {
             objectClass: unavailable,
             objectIdentifier: unavailable,
             mediaType: unavailable,
-            baseConformance: { state: 'unavailable', declarations: [] },
+            baseConformance: { state: 'unavailable', declarations: [], truncated: false },
             redactionMetadata: { state: 'unavailable', count: 0, truncated: false },
-            selfLink: { state: 'unavailable', observedRelations: [] },
-            events: { state: 'unavailable', count: 0, conflictingActions: [] },
+            selfLink: { state: 'unavailable', observedRelations: [], truncated: false },
+            events: { state: 'unavailable', count: 0, conflictingActions: [], truncated: false },
             reviewItems: 0,
         };
     }
     const objectClassName = typeof parsed.objectClassName === 'string' ? parsed.objectClassName.trim().toLowerCase() : '';
     const identifier = [parsed.handle, parsed.objectIdentifier, parsed.registryObjectId, parsed.id]
         .find((value) => typeof value === 'string' && Boolean(value.trim()))?.trim() ?? null;
-    const declarations = stringArray(parsed.conformance);
+    const conformanceValues = Array.isArray(parsed.conformance) ? parsed.conformance : [];
+    const conformanceTruncated = parsed.conformanceTruncated === true || conformanceValues.length > 100;
+    const declarations = stringArray(conformanceValues);
     const redactions = Array.isArray(parsed.redactions) ? parsed.redactions.slice(0, 100) : [];
-    const links = Array.isArray(parsed.links) ? parsed.links.slice(0, 100).map(recordOrEmpty) : [];
+    const redactionsTruncated = parsed.redactionsTruncated === true
+        || (Array.isArray(parsed.redactions) && parsed.redactions.length > 100);
+    const linkValues = Array.isArray(parsed.links) ? parsed.links : [];
+    const links = linkValues.slice(0, 100).map(recordOrEmpty);
+    const linksTruncated = parsed.linksTruncated === true
+        || linkValues.length > 100
+        || links.some((link) => Array.isArray(link.rel) && link.rel.length > 10);
     const relations = [...new Set(links.flatMap((link) => stringArray(link.rel, 10).length
             ? stringArray(link.rel, 10)
             : typeof link.rel === 'string' ? [link.rel.trim().toLowerCase()] : []).filter(Boolean))];
-    const events = Array.isArray(parsed.events) ? parsed.events.slice(0, 100).map(recordOrEmpty) : [];
+    const eventValues = Array.isArray(parsed.events) ? parsed.events : [];
+    const events = eventValues.slice(0, 100).map(recordOrEmpty);
+    const eventsTruncated = parsed.eventsTruncated === true || eventValues.length > 100;
     const actionDates = new Map();
     for (const event of events) {
         const action = typeof event.action === 'string' ? event.action.trim().toLowerCase() : '';
-        const date = typeof event.date === 'string' ? event.date.trim() : '';
+        const date = registryDateIso(event.date);
         if (!action || !date)
             continue;
         const dates = actionDates.get(action) ?? [];
@@ -79,8 +90,21 @@ function publicationQuality(parsed, rdapStatus) {
         ['reinstantiation', 'reinstantiationDateIso', true],
         ['last update of rdap database', 'databaseUpdatedDateIso', true],
     ];
+    const lifecycleDates = new Map();
+    let lifecycleMalformed = false;
+    for (const [, field] of lifecycleMappings) {
+        const supplied = lifecycle[field];
+        if (supplied === undefined || supplied === null)
+            continue;
+        const normalized = registryDateIso(supplied);
+        if (normalized)
+            lifecycleDates.set(field, normalized);
+        else
+            lifecycleMalformed = true;
+    }
     const conflictingActions = lifecycleMappings.flatMap(([action, field, newest]) => {
-        const published = typeof lifecycle[field] === 'string' ? Date.parse(lifecycle[field]) : Number.NaN;
+        const publishedDate = lifecycleDates.get(field);
+        const published = publishedDate ? Date.parse(publishedDate) : Number.NaN;
         if (!Number.isFinite(published))
             return [];
         const dates = (actionDates.get(action) ?? []).map(Date.parse).filter(Number.isFinite);
@@ -90,30 +114,41 @@ function publicationQuality(parsed, rdapStatus) {
         return selected === published ? [] : [action];
     }).sort();
     const objectClassState = !objectClassName ? 'not_observed' : objectClassName === 'domain' ? 'observed' : 'inconsistent';
-    const baseConformanceState = declarations.includes('rdap_level_0') ? 'observed' : 'not_observed';
-    const selfLinkState = relations.includes('self') ? 'observed' : 'not_observed';
-    const hasLifecycle = lifecycleMappings.some(([, field]) => typeof lifecycle[field] === 'string');
-    const eventsState = conflictingActions.length
-        ? 'inconsistent'
-        : events.length && hasLifecycle
-            ? 'observed'
-            : events.length
-                ? 'unavailable'
-                : 'not_observed';
+    const baseConformanceState = declarations.includes('rdap_level_0')
+        ? 'observed'
+        : conformanceTruncated ? 'unavailable' : 'not_observed';
+    const selfLinkState = relations.includes('self')
+        ? 'observed'
+        : linksTruncated ? 'unavailable' : 'not_observed';
+    const hasLifecycle = lifecycleDates.size > 0;
+    const eventsState = eventsTruncated || lifecycleMalformed
+        ? 'unavailable'
+        : conflictingActions.length
+            ? 'inconsistent'
+            : events.length && hasLifecycle
+                ? 'observed'
+                : events.length
+                    ? 'unavailable'
+                    : 'not_observed';
     return {
         objectClass: { state: objectClassState, value: objectClassName || null },
         objectIdentifier: { state: identifier ? 'observed' : 'not_observed', value: identifier },
         mediaType: { state: 'unavailable', value: null },
-        baseConformance: { state: baseConformanceState, declarations },
+        baseConformance: { state: baseConformanceState, declarations, truncated: conformanceTruncated },
         redactionMetadata: {
-            state: redactions.length ? 'observed' : 'not_observed',
+            state: redactions.length ? 'observed' : redactionsTruncated ? 'unavailable' : 'not_observed',
             count: redactions.length,
-            truncated: parsed.redactionsTruncated === true,
+            truncated: redactionsTruncated,
+        },
+        selfLink: { state: selfLinkState, observedRelations: relations.sort(), truncated: linksTruncated },
+        events: {
+            state: eventsState,
+            count: events.length,
+            conflictingActions: eventsTruncated || lifecycleMalformed ? [] : conflictingActions,
+            truncated: eventsTruncated,
         },
-        selfLink: { state: selfLinkState, observedRelations: relations.sort() },
-        events: { state: eventsState, count: events.length, conflictingActions },
         reviewItems: [objectClassState, baseConformanceState, selfLinkState, eventsState]
-            .filter((state) => state === 'inconsistent' || state === 'not_observed').length,
+            .filter((state) => state !== 'observed').length,
     };
 }
 function buildRegistryDoctorReport(raw, generatedAt = new Date().toISOString()) {
@@ -182,6 +217,10 @@ function buildRegistryDoctorReport(raw, generatedAt = new Date().toISOString())
             'A catalogue alignment does not prove live reachability, parser completeness, current registry policy, registration, availability, ownership, safety, or maliciousness.',
             'A missing registry object identifier can be a publication characteristic. It remains not observed and is not converted into a collection failure.',
             'Publication-quality observations describe the saved normalised RDAP object. The saved Lookup format does not retain the response media type, so that field remains unavailable.',
+            ...(publication.baseConformance.truncated || publication.redactionMetadata.truncated
+                || publication.selfLink.truncated || publication.events.truncated
+                ? ['One or more bounded RDAP publication families were truncated; omitted values remain unavailable and cannot support absence or consistency conclusions.']
+                : []),
             'Use fixture-based maintenance checks before changing a registry parser or access profile; automated tests must not contact live registries.',
         ],
     };
@@ -203,9 +242,9 @@ function formatRegistryDoctorReport(report) {
     output.push('', 'RDAP publication quality');
     output.push(`  Object class: ${report.publication.objectClass.state.replaceAll('_', ' ')}`);
     output.push(`  Object identifier: ${report.publication.objectIdentifier.state.replaceAll('_', ' ')}`);
-    output.push(`  Base conformance: ${report.publication.baseConformance.state.replaceAll('_', ' ')}`);
-    output.push(`  Self link: ${report.publication.selfLink.state.replaceAll('_', ' ')}`);
-    output.push(`  Events: ${report.publication.events.state.replaceAll('_', ' ')}`);
+    output.push(`  Base conformance: ${report.publication.baseConformance.state.replaceAll('_', ' ')}${report.publication.baseConformance.truncated ? ' (partial)' : ''}`);
+    output.push(`  Self link: ${report.publication.selfLink.state.replaceAll('_', ' ')}${report.publication.selfLink.truncated ? ' (partial)' : ''}`);
+    output.push(`  Events: ${report.publication.events.state.replaceAll('_', ' ')}${report.publication.events.truncated ? ' (partial)' : ''}`);
     output.push('  Media type: unavailable in the saved Lookup contract');
     if (report.recommendations.length) {
         output.push('', 'Recommendations:');

package/cli/registry-support.mjs

@@ -1,6 +1,6 @@
 import { registryStandardsCoverageSnapshot, } from "../lib/registry-capabilities.mjs";
 const REGISTRY_SUPPORT_SCHEMA = 'whoisleuth.cli.registry-support';
-const REGISTRY_SUPPORT_SCHEMA_VERSION = 3;
+const REGISTRY_SUPPORT_SCHEMA_VERSION = 4;
 const REGISTRY_STANDARDS_COVERAGE_SCHEMA = 'whoisleuth.registry-standards-coverage';
 const MAX_REGISTRY_SUPPORT_TEXT_LENGTH = 2048;
 const MAX_REGISTRY_SUPPORT_REFERENCES = 20;
@@ -88,6 +88,7 @@ function buildRegistrySupportDocument(requestedInput, capability, catalogueVersi
             explicitSuffixProfile: capability.explicitSuffixProfile === true,
             registryClass: boundedText(capability.registryClass, 'unknown', 64),
             coverageState: boundedText(capability.coverageState, 'unknown', 64),
+            officialLookupUrl: boundedList([capability.officialLookupUrl], 'url')[0] ?? null,
             rdap: {
                 discovery: boundedText(capability.rdapDiscovery, 'unknown', 64),
                 accessProfile: boundedText(capability.rdapAccessProfile, 'unknown', 128),