@slicedearth/whoisleuth-cli 2.3.0 → 2.5.1

package/lib/domain-control-flight-recorder.mjs

@@ -1,10 +1,13 @@
 import { Buffer } from 'node:buffer';
+import { canonicalDomainControlRecords } from "../packages/evidence/domain-control-runtime.mjs";
 import { requireBoundedString, requireDomainName, requireIsoTimestamp, } from "./bounded-contract-normalizers.mjs";
-import { DOMAIN_CONTROL_FLIGHT_RECORDER_FIELDS, DOMAIN_CONTROL_FLIGHT_RECORDER_APPROVED_WINDOW_KEYS, DOMAIN_CONTROL_FLIGHT_RECORDER_EVENT_KEYS, DOMAIN_CONTROL_FLIGHT_RECORDER_FIELD_KEYS, DOMAIN_CONTROL_FLIGHT_RECORDER_INPUT_KEYS, DOMAIN_CONTROL_FLIGHT_RECORDER_INPUT_SCHEMA, DOMAIN_CONTROL_FLIGHT_RECORDER_LIMITATIONS, DOMAIN_CONTROL_FLIGHT_RECORDER_OBSERVATION_KEYS, DOMAIN_CONTROL_FLIGHT_RECORDER_ROOT_KEYS, DOMAIN_CONTROL_FLIGHT_RECORDER_SCHEMA, DOMAIN_CONTROL_FLIGHT_RECORDER_SUMMARY_KEYS, DOMAIN_CONTROL_FLIGHT_RECORDER_VERSION, DOMAIN_CONTROL_FLIGHT_RECORDER_WINDOW_KEYS, MAX_DOMAIN_CONTROL_FLIGHT_RECORDER_INPUT_BYTES, MAX_DOMAIN_CONTROL_FLIGHT_RECORDER_OUTPUT_BYTES, MAX_FLIGHT_RECORDER_FIELDS, MAX_FLIGHT_RECORDER_EVENTS, MAX_FLIGHT_RECORDER_INPUT_VALUES, MAX_FLIGHT_RECORDER_JSON_DEPTH, MAX_FLIGHT_RECORDER_JSON_VALUES, MAX_FLIGHT_RECORDER_OBSERVATIONS, MAX_FLIGHT_RECORDER_SOURCE_LENGTH, MAX_FLIGHT_RECORDER_VALUE_LENGTH, MAX_FLIGHT_RECORDER_VALUES, MAX_FLIGHT_RECORDER_WINDOWS, MAX_FLIGHT_RECORDER_WINDOW_ID_LENGTH, MAX_FLIGHT_RECORDER_WINDOW_REASON_LENGTH, MIN_FLIGHT_RECORDER_OBSERVATIONS, } from "../packages/contracts/domain-control-flight-recorder.mjs";
+import { DOMAIN_CONTROL_FLIGHT_RECORDER_FIELDS, DOMAIN_CONTROL_FLIGHT_RECORDER_APPROVED_WINDOW_KEYS, DOMAIN_CONTROL_FLIGHT_RECORDER_EVENT_KEYS, DOMAIN_CONTROL_FLIGHT_RECORDER_FIELD_KEYS, DOMAIN_CONTROL_FLIGHT_RECORDER_INPUT_KEYS, DOMAIN_CONTROL_FLIGHT_RECORDER_INPUT_SCHEMA, DOMAIN_CONTROL_FLIGHT_RECORDER_LIMITATIONS, DOMAIN_CONTROL_FLIGHT_RECORDER_OBSERVATION_KEYS, DOMAIN_CONTROL_FLIGHT_RECORDER_ROOT_KEYS, DOMAIN_CONTROL_FLIGHT_RECORDER_SCHEMA, DOMAIN_CONTROL_FLIGHT_RECORDER_SUMMARY_KEYS, DOMAIN_CONTROL_FLIGHT_RECORDER_VERSION, PUBLIC_DOMAIN_CONTROL_FLIGHT_RECORDER_VERSION, PUBLIC_DOMAIN_CONTROL_FLIGHT_RECORDER_OBSERVATION_KEYS, PUBLIC_DOMAIN_CONTROL_FLIGHT_RECORDER_FIELD_KEYS, PUBLIC_DOMAIN_CONTROL_FLIGHT_RECORDER_EVENT_KEYS, PUBLIC_DOMAIN_CONTROL_FLIGHT_RECORDER_SUMMARY_KEYS, PUBLIC_DOMAIN_CONTROL_FLIGHT_RECORDER_LIMITATIONS, SOURCE_TIMED_FLIGHT_RECORDER_EVENT_KEYS, SOURCE_TIMED_FLIGHT_RECORDER_LIMITATIONS, FLIGHT_RECORDER_CHANGE_INTERVAL_KEYS, HISTORICAL_FLIGHT_RECORDER_APPROVED_WINDOW_KEYS, PUBLIC_MAX_FLIGHT_RECORDER_INPUT_VALUES, PUBLIC_MAX_FLIGHT_RECORDER_VALUES, PUBLIC_MAX_FLIGHT_RECORDER_VALUE_LENGTH, SUPPORTED_DOMAIN_CONTROL_FLIGHT_RECORDER_VERSIONS, DOMAIN_CONTROL_FLIGHT_RECORDER_WINDOW_KEYS, MAX_DOMAIN_CONTROL_FLIGHT_RECORDER_INPUT_BYTES, MAX_DOMAIN_CONTROL_FLIGHT_RECORDER_OUTPUT_BYTES, MAX_FLIGHT_RECORDER_FIELDS, MAX_FLIGHT_RECORDER_EVENTS, MAX_FLIGHT_RECORDER_INPUT_VALUES, MAX_FLIGHT_RECORDER_JSON_DEPTH, MAX_FLIGHT_RECORDER_JSON_VALUES, MAX_FLIGHT_RECORDER_OBSERVATIONS, MAX_FLIGHT_RECORDER_SOURCE_LENGTH, MAX_FLIGHT_RECORDER_VALUE_LENGTH, MAX_FLIGHT_RECORDER_VALUES, MAX_FLIGHT_RECORDER_WINDOWS, MAX_FLIGHT_RECORDER_WINDOW_ID_LENGTH, MAX_FLIGHT_RECORDER_WINDOW_REASON_LENGTH, MIN_FLIGHT_RECORDER_OBSERVATIONS, } from "../packages/contracts/domain-control-flight-recorder.mjs";
 export { DOMAIN_CONTROL_FLIGHT_RECORDER_FIELDS, DOMAIN_CONTROL_FLIGHT_RECORDER_INPUT_SCHEMA, DOMAIN_CONTROL_FLIGHT_RECORDER_SCHEMA, DOMAIN_CONTROL_FLIGHT_RECORDER_VERSION, MAX_FLIGHT_RECORDER_FIELDS, MAX_FLIGHT_RECORDER_OBSERVATIONS, MAX_FLIGHT_RECORDER_VALUES, MAX_FLIGHT_RECORDER_WINDOWS, };
 const ROOT_KEYS = new Set(DOMAIN_CONTROL_FLIGHT_RECORDER_INPUT_KEYS);
 const OBSERVATION_KEYS = new Set(DOMAIN_CONTROL_FLIGHT_RECORDER_OBSERVATION_KEYS);
 const FIELD_KEYS = new Set(DOMAIN_CONTROL_FLIGHT_RECORDER_FIELD_KEYS);
+const PUBLIC_OBSERVATION_KEYS = new Set(PUBLIC_DOMAIN_CONTROL_FLIGHT_RECORDER_OBSERVATION_KEYS);
+const PUBLIC_FIELD_KEYS = new Set(PUBLIC_DOMAIN_CONTROL_FLIGHT_RECORDER_FIELD_KEYS);
 const WINDOW_KEYS = new Set(DOMAIN_CONTROL_FLIGHT_RECORDER_WINDOW_KEYS);
 const DOCUMENT_ROOT_KEYS = new Set(DOMAIN_CONTROL_FLIGHT_RECORDER_ROOT_KEYS);
 const EVENT_KEYS = new Set(DOMAIN_CONTROL_FLIGHT_RECORDER_EVENT_KEYS);
@@ -217,22 +220,23 @@ function assertPrettyJsonByteBudget(value, maximum, label) {
         throw new TypeError(`${label} must be serialisable as bounded JSON.`);
     }
 }
-function snapshotFlightRecorderInput(input) {
+function snapshotFlightRecorderInput(input, legacy) {
     const observations = boundedDataArray(input.observations, 'Domain control flight-recorder input observations', MIN_FLIGHT_RECORDER_OBSERVATIONS, MAX_FLIGHT_RECORDER_OBSERVATIONS).map((raw, index) => {
-        const item = exactRecord(raw, OBSERVATION_KEYS, `observations[${index}]`);
+        const item = exactRecord(raw, legacy ? PUBLIC_OBSERVATION_KEYS : OBSERVATION_KEYS, `observations[${index}]`);
         const fields = boundedDataArray(item.fields, `observations[${index}].fields`, 0, MAX_FLIGHT_RECORDER_FIELDS)
             .map((fieldRaw, fieldIndex) => {
-            const field = exactRecord(fieldRaw, FIELD_KEYS, `observations[${index}].fields[${fieldIndex}]`);
+            const field = exactRecord(fieldRaw, legacy ? PUBLIC_FIELD_KEYS : FIELD_KEYS, `observations[${index}].fields[${fieldIndex}]`);
             return Object.freeze({
                 id: field.id,
                 source: field.source,
                 state: field.state,
-                values: boundedDataArray(field.values, `observations[${index}].fields[${fieldIndex}].values`, 0, MAX_FLIGHT_RECORDER_INPUT_VALUES),
+                ...(!legacy ? { observedAt: field.observedAt } : {}),
+                values: boundedDataArray(field.values, `observations[${index}].fields[${fieldIndex}].values`, 0, legacy ? PUBLIC_MAX_FLIGHT_RECORDER_INPUT_VALUES : MAX_FLIGHT_RECORDER_INPUT_VALUES),
             });
         });
         return Object.freeze({
             domain: item.domain,
-            observedAt: item.observedAt,
+            ...(legacy ? { observedAt: item.observedAt } : { capturedAt: item.capturedAt }),
             collectionDepth: item.collectionDepth,
             fields: Object.freeze(fields),
         });
@@ -251,7 +255,7 @@ function snapshotFlightRecorderInput(input) {
     });
     return Object.freeze({
         schema: DOMAIN_CONTROL_FLIGHT_RECORDER_INPUT_SCHEMA,
-        version: DOMAIN_CONTROL_FLIGHT_RECORDER_VERSION,
+        version: input.version,
         observations: Object.freeze(observations),
         approvedWindows: Object.freeze(approvedWindows),
     });
@@ -262,25 +266,41 @@ function text(value, label, maximum = 240) {
         .replace(/\s+/gu, ' ')
         .trim();
 }
-function values(value, label) {
-    const input = boundedDataArray(value, label, 0, MAX_FLIGHT_RECORDER_INPUT_VALUES);
+const RECORD_FIELDS = Object.freeze({
+    registry_nameservers: 'nameservers', whois_nameservers: 'nameservers', delegated_nameservers: 'nameservers',
+    delegation_ds: 'ds', mail_exchangers: 'mx', caa_policy: 'caa',
+});
+function recorderValue(value, label, legacy, field, complete = true) {
+    if (legacy)
+        return text(value, label, PUBLIC_MAX_FLIGHT_RECORDER_VALUE_LENGTH).toLowerCase();
+    if (typeof value !== 'string' || !value.trim() || value.length > MAX_FLIGHT_RECORDER_VALUE_LENGTH
+        || /[\u0000-\u001f\u007f]/u.test(value)) {
+        throw new TypeError(`${label} must be bounded text without control characters.`);
+    }
+    const recordField = RECORD_FIELDS[field];
+    return recordField && complete ? canonicalDomainControlRecords([value], recordField)[0] : value.trim();
+}
+function values(value, label, legacy, field, complete) {
+    const input = boundedDataArray(value, label, 0, legacy ? PUBLIC_MAX_FLIGHT_RECORDER_INPUT_VALUES : MAX_FLIGHT_RECORDER_INPUT_VALUES);
+    const maximum = legacy ? PUBLIC_MAX_FLIGHT_RECORDER_VALUES : MAX_FLIGHT_RECORDER_VALUES;
     const output = new Set();
     for (let index = 0; index < input.length; index += 1) {
-        const normalized = text(input[index], `${label}[${index}]`, MAX_FLIGHT_RECORDER_VALUE_LENGTH).toLowerCase();
+        const normalized = recorderValue(input[index], `${label}[${index}]`, legacy, field, complete);
         if (normalized)
             output.add(normalized);
-        if (output.size > MAX_FLIGHT_RECORDER_VALUES) {
-            throw new TypeError(`${label} must contain at most ${MAX_FLIGHT_RECORDER_VALUES} unique normalized values.`);
+        if (output.size > maximum) {
+            throw new TypeError(`${label} must contain at most ${maximum} unique normalized values.`);
         }
     }
     return [...output].sort(ordinalCompare);
 }
-function observation(value, index) {
-    const item = exactRecord(value, OBSERVATION_KEYS, `observations[${index}]`);
+function observation(value, index, legacy) {
+    const item = exactRecord(value, legacy ? PUBLIC_OBSERVATION_KEYS : OBSERVATION_KEYS, `observations[${index}]`);
+    const capturedAt = requireIsoTimestamp(legacy ? item.observedAt : item.capturedAt, `observations[${index}].${legacy ? 'observedAt' : 'capturedAt'}`);
     const inputFields = boundedDataArray(item.fields, `observations[${index}].fields`, 0, MAX_FLIGHT_RECORDER_FIELDS);
     const seen = new Set();
     const fields = inputFields.map((raw, fieldIndex) => {
-        const field = exactRecord(raw, FIELD_KEYS, `observations[${index}].fields[${fieldIndex}]`);
+        const field = exactRecord(raw, legacy ? PUBLIC_FIELD_KEYS : FIELD_KEYS, `observations[${index}].fields[${fieldIndex}]`);
         if (typeof field.id !== 'string' || !FIELD_IDS.has(field.id) || seen.has(field.id)) {
             throw new TypeError(`observations[${index}] contains an unsupported or duplicate field.`);
         }
@@ -288,11 +308,27 @@ function observation(value, index) {
             throw new TypeError(`observations[${index}].fields[${fieldIndex}].state is unsupported.`);
         }
         seen.add(field.id);
+        let fieldState = field.state;
+        let fieldValues = values(field.values, `observations[${index}].fields[${fieldIndex}].values`, legacy, field.id, fieldState === 'observed');
+        const recordField = RECORD_FIELDS[field.id];
+        if (legacy && recordField) {
+            try {
+                fieldValues = canonicalDomainControlRecords(fieldValues, recordField);
+            }
+            catch (cause) {
+                if (!(cause instanceof TypeError))
+                    throw cause;
+                if (fieldState === 'observed')
+                    fieldState = 'partial';
+            }
+        }
         return Object.freeze({
             id: field.id,
             source: text(field.source, `observations[${index}].fields[${fieldIndex}].source`, MAX_FLIGHT_RECORDER_SOURCE_LENGTH),
-            state: field.state,
-            values: Object.freeze(values(field.values, `observations[${index}].fields[${fieldIndex}].values`)),
+            state: fieldState,
+            values: Object.freeze(fieldValues),
+            observedAt: legacy ? capturedAt : field.observedAt === null ? null
+                : requireIsoTimestamp(field.observedAt, `observations[${index}].fields[${fieldIndex}].observedAt`),
         });
     }).sort((left, right) => ordinalCompare(left.id, right.id));
     const collectionDepth = item.collectionDepth === 'deep' || item.collectionDepth === 'fast'
@@ -304,11 +340,18 @@ function observation(value, index) {
         throw new TypeError(`observations[${index}].collectionDepth is unsupported.`);
     return Object.freeze({
         domain: requireDomainName(item.domain, `observations[${index}].domain`),
-        observedAt: requireIsoTimestamp(item.observedAt, `observations[${index}].observedAt`),
+        capturedAt,
         collectionDepth,
         fields: Object.freeze(fields),
     });
 }
+export function normalizeDomainControlFlightRecorderObservations(value, version) {
+    if (!SUPPORTED_DOMAIN_CONTROL_FLIGHT_RECORDER_VERSIONS.some((supported) => supported === version)) {
+        throw new TypeError('Domain control observations use an unsupported version.');
+    }
+    return Object.freeze(boundedDataArray(value, 'observations', MIN_FLIGHT_RECORDER_OBSERVATIONS, MAX_FLIGHT_RECORDER_OBSERVATIONS)
+        .map((item, index) => observation(item, index, version === PUBLIC_DOMAIN_CONTROL_FLIGHT_RECORDER_VERSION)));
+}
 function approvedWindow(value, index) {
     const item = exactRecord(value, WINDOW_KEYS, `approvedWindows[${index}]`);
     const inputFields = boundedDataArray(item.fields, `approvedWindows[${index}].fields`, 1, MAX_FLIGHT_RECORDER_FIELDS);
@@ -335,109 +378,158 @@ function approvedWindow(value, index) {
 function sameValues(left, right) {
     return left.length === right.length && left.every((value, index) => value === right[index]);
 }
-function matchingWindow(windows, domain, field, observedAt) {
-    const time = Date.parse(observedAt);
+function matchingWindow(windows, domain, field, after, by) {
     return windows.find((window) => (window.domain === domain
         && window.fields.includes(field)
-        && Date.parse(window.startsAt) <= time
-        && time <= Date.parse(window.endsAt))) ?? null;
+        && Date.parse(window.startsAt) <= Date.parse(after)
+        && Date.parse(by) <= Date.parse(window.endsAt))) ?? null;
+}
+/** Equal-capture disagreement stays incomplete, independently of input ordering. */
+export function mergeConcurrentDomainControlFields(observations) {
+    return Object.freeze(DOMAIN_CONTROL_FLIGHT_RECORDER_FIELDS.flatMap((id) => {
+        const candidates = observations.flatMap((fields) => fields.filter((field) => field.id === id));
+        const first = candidates[0];
+        if (!first)
+            return [];
+        const identity = (field) => JSON.stringify([field.source, field.state, field.observedAt, field.values]);
+        if (candidates.every((field) => identity(field) === identity(first)))
+            return [first];
+        const retained = [...new Set(candidates.flatMap((field) => field.values))].sort(ordinalCompare);
+        const omitted = Math.max(0, retained.length - MAX_FLIGHT_RECORDER_VALUES);
+        const sources = new Set(candidates.map((field) => field.source));
+        const times = new Set(candidates.map((field) => field.observedAt));
+        return [Object.freeze({
+                id, source: `${sources.size === 1 ? first.source.slice(0, 60) : 'Multiple sources'} (conflicting observations; ${omitted} omitted)`,
+                state: 'partial', observedAt: times.size === 1 ? first.observedAt : null,
+                values: Object.freeze(retained.slice(0, MAX_FLIGHT_RECORDER_VALUES)),
+            })];
+    }));
+}
+function observationTimeline(observations) {
+    const cohorts = new Map();
+    for (const item of observations) {
+        const key = `${item.domain}\u0000${item.capturedAt}`;
+        const cohort = cohorts.get(key) ?? [];
+        cohort.push(item);
+        cohorts.set(key, cohort);
+    }
+    return [...cohorts.values()].map((cohort) => {
+        const first = cohort[0];
+        const collectionDepth = cohort.every((item) => item.collectionDepth === first.collectionDepth)
+            ? first.collectionDepth : 'unknown';
+        return Object.freeze({ ...first, collectionDepth, fields: mergeConcurrentDomainControlFields(cohort.map((item) => item.fields)) });
+    }).sort((left, right) => Date.parse(left.capturedAt) - Date.parse(right.capturedAt)
+        || ordinalCompare(left.domain, right.domain));
 }
 export function buildDomainControlFlightRecorder(inputRaw, generatedAtValue = new Date().toISOString()) {
     const inputRoot = exactRecord(inputRaw, ROOT_KEYS, 'Domain control flight-recorder input');
     if (inputRoot.schema !== DOMAIN_CONTROL_FLIGHT_RECORDER_INPUT_SCHEMA
-        || inputRoot.version !== DOMAIN_CONTROL_FLIGHT_RECORDER_VERSION) {
-        throw new TypeError(`Domain control flight-recorder input must use ${DOMAIN_CONTROL_FLIGHT_RECORDER_INPUT_SCHEMA} version ${DOMAIN_CONTROL_FLIGHT_RECORDER_VERSION}.`);
+        || !SUPPORTED_DOMAIN_CONTROL_FLIGHT_RECORDER_VERSIONS.some((version) => version === inputRoot.version)) {
+        throw new TypeError(`Domain control flight-recorder input must use ${DOMAIN_CONTROL_FLIGHT_RECORDER_INPUT_SCHEMA} supported version ${SUPPORTED_DOMAIN_CONTROL_FLIGHT_RECORDER_VERSIONS.join(' or ')}.`);
     }
-    const input = snapshotFlightRecorderInput(inputRoot);
+    const input = snapshotFlightRecorderInput(inputRoot, inputRoot.version === PUBLIC_DOMAIN_CONTROL_FLIGHT_RECORDER_VERSION);
     assertPrettyJsonByteBudget(input, MAX_DOMAIN_CONTROL_FLIGHT_RECORDER_INPUT_BYTES, 'Domain control flight-recorder input');
-    const inputObservations = input.observations;
     const inputWindows = input.approvedWindows;
-    const observations = inputObservations.map(observation)
-        .sort((left, right) => Date.parse(left.observedAt) - Date.parse(right.observedAt)
-        || ordinalCompare(left.domain, right.domain));
+    const observations = normalizeDomainControlFlightRecorderObservations(input.observations, Number(input.version));
     const windows = inputWindows.map(approvedWindow);
     if (new Set(windows.map((window) => window.id)).size !== windows.length) {
         throw new TypeError('Approved change-window ids must be unique.');
     }
     const generatedAt = requireIsoTimestamp(generatedAtValue, 'generatedAt');
-    if (observations.some((item) => Date.parse(item.observedAt) > Date.parse(generatedAt))) {
-        throw new TypeError('Domain control flight-recorder observations cannot be later than generatedAt.');
+    if (observations.some((item) => Date.parse(item.capturedAt) > Date.parse(generatedAt))) {
+        throw new TypeError('Domain control flight-recorder captures cannot be later than generatedAt.');
     }
     const latest = new Map();
+    const lastComplete = new Map();
+    const incompleteSince = new Map();
     const events = [];
-    for (const item of observations) {
-        for (const field of item.fields) {
+    let incompleteFields = 0;
+    for (const item of observationTimeline(observations)) {
+        const fields = [...item.fields];
+        for (const [key, previous] of latest) {
+            if (key.startsWith(`${item.domain}\u0000`) && !fields.some(field => field.id === previous.field.id)) {
+                fields.push({ id: previous.field.id, source: 'Not supplied in this capture', state: 'unavailable', observedAt: null, values: [] });
+            }
+        }
+        fields.sort((a, b) => ordinalCompare(a.id, b.id));
+        for (const field of fields) {
             const key = `${item.domain}\u0000${field.id}`;
             const previous = latest.get(key);
-            latest.set(key, field);
-            if (!previous) {
-                if (field.state !== 'observed')
-                    continue;
-                events.push(Object.freeze({
-                    id: `${item.domain}:${field.id}:${item.observedAt}`,
-                    domain: item.domain,
-                    field: field.id,
-                    observedAt: item.observedAt,
-                    kind: 'first_observation',
-                    state: 'observed',
-                    before: Object.freeze([]),
-                    after: field.values,
-                    source: field.source,
-                    approvedWindow: null,
-                    explanation: 'The first complete value for this source-attributed field was retained.',
-                }));
+            let baseline = lastComplete.get(key);
+            let complete = field.state === 'observed' && field.observedAt !== null
+                && Date.parse(field.observedAt) <= Date.parse(item.capturedAt) && item.collectionDepth !== 'unknown';
+            const sameContext = previous?.field.source === field.source && previous.collectionDepth === item.collectionDepth;
+            const repeated = previous?.complete && complete && sameContext
+                && previous.field.observedAt === field.observedAt && sameValues(previous.field.values, field.values);
+            if (repeated)
                 continue;
+            let limitation = field.observedAt === null ? 'The source observation time is unavailable.'
+                : Date.parse(field.observedAt) > Date.parse(item.capturedAt) ? 'The source observation time is later than capture.'
+                    : item.collectionDepth === 'unknown' ? 'Collection conditions are unknown or conflicting.'
+                        : `The source is ${field.state}.`;
+            const contextChanged = baseline && field.source !== 'Not supplied in this capture'
+                && (baseline.field.source !== field.source || (item.collectionDepth !== 'unknown' && baseline.collectionDepth !== item.collectionDepth));
+            if (contextChanged) {
+                if (complete) {
+                    complete = false;
+                    limitation = 'The source identity or collection conditions changed.';
+                }
+                lastComplete.delete(key);
+                baseline = undefined;
             }
-            const window = matchingWindow(windows, item.domain, field.id, item.observedAt);
-            if (previous.state === 'observed' && field.state === 'observed') {
-                if (sameValues(previous.values, field.values))
-                    continue;
-                events.push(Object.freeze({
-                    id: `${item.domain}:${field.id}:${item.observedAt}`,
-                    domain: item.domain,
-                    field: field.id,
-                    observedAt: item.observedAt,
-                    kind: 'observed_change',
-                    state: 'observed',
-                    before: previous.values,
-                    after: field.values,
-                    source: field.source,
-                    approvedWindow: window ? Object.freeze({ id: window.id, reason: window.reason }) : null,
-                    explanation: window
-                        ? 'A complete observed value changed during an analyst-approved change window. The evidence is retained and labelled expected rather than removed.'
-                        : 'Two complete source-attributed observations contain different values.',
-                }));
+            else if (complete && baseline && Date.parse(field.observedAt) <= Date.parse(baseline.field.observedAt)) {
+                complete = false;
+                limitation = 'The source observation time did not increase.';
+            }
+            latest.set(key, { field, collectionDepth: item.collectionDepth, complete });
+            let kind;
+            let explanation;
+            let before = [];
+            let approved = null;
+            let changeInterval = null;
+            if (!complete) {
+                incompleteSince.set(key, (incompleteSince.get(key) ?? 0) + 1);
+                incompleteFields += 1;
+                kind = previous?.complete ? 'collection_change' : 'incomplete_observation';
+                before = previous?.complete ? previous.field.values : [];
+                explanation = `${limitation} Retained values are incomplete; this is not evidence that a prior value disappeared or changed.`;
             }
-            else if (previous.state !== 'observed' && field.state === 'observed') {
-                events.push(Object.freeze({
-                    id: `${item.domain}:${field.id}:${item.observedAt}`,
-                    domain: item.domain,
-                    field: field.id,
-                    observedAt: item.observedAt,
-                    kind: 'recovered',
-                    state: 'observed',
-                    before: Object.freeze([]),
-                    after: field.values,
-                    source: field.source,
-                    approvedWindow: null,
-                    explanation: 'Collection returned a complete value after an earlier incomplete source state.',
-                }));
+            else if (baseline && !sameValues(baseline.field.values, field.values)) {
+                kind = 'observed_change';
+                before = baseline.field.values;
+                changeInterval = Object.freeze({ after: baseline.field.observedAt, by: field.observedAt, incompleteObservations: incompleteSince.get(key) ?? 0 });
+                approved = matchingWindow(windows, item.domain, field.id, changeInterval.after, changeInterval.by);
+                explanation = `Comparable complete observations contain different values. The change occurred after ${changeInterval.after} and by ${changeInterval.by}; its exact time is unknown.`
+                    + (changeInterval.incompleteObservations ? ` ${changeInterval.incompleteObservations} incomplete observation(s) occurred in this interval.` : '')
+                    + (approved ? ' The recorded approved window contains the entire interval.' : ' No recorded approved window contains the entire interval.');
             }
-            else if (previous.state === 'observed' && field.state !== 'observed') {
-                events.push(Object.freeze({
-                    id: `${item.domain}:${field.id}:${item.observedAt}`,
-                    domain: item.domain,
-                    field: field.id,
-                    observedAt: item.observedAt,
-                    kind: 'collection_change',
-                    state: 'partial',
-                    before: previous.values,
-                    after: Object.freeze([]),
-                    source: field.source,
-                    approvedWindow: null,
-                    explanation: `The source became ${field.state}; this is a collection-quality change, not evidence that the prior value disappeared.`,
-                }));
+            else if (!previous) {
+                kind = 'first_observation';
+                explanation = 'The first complete source-timed value for this field was retained.';
             }
+            else if (!previous.complete) {
+                kind = 'recovered';
+                explanation = baseline
+                    ? 'The recovered complete value matches the last comparable complete observation. Intervening changes during the incomplete interval remain unknown.'
+                    : 'A complete source-timed value is available after an incomplete observation; this does not establish a value change.';
+            }
+            else {
+                lastComplete.set(key, { field, collectionDepth: item.collectionDepth, complete });
+                incompleteSince.delete(key);
+                continue;
+            }
+            if (complete) {
+                lastComplete.set(key, { field, collectionDepth: item.collectionDepth, complete });
+                incompleteSince.delete(key);
+            }
+            events.push(Object.freeze({
+                id: `${item.domain}:${field.id}:${item.capturedAt}:${events.length + 1}`,
+                domain: item.domain, field: field.id, observedAt: field.observedAt, capturedAt: item.capturedAt,
+                kind, state: complete ? 'observed' : 'partial', before: Object.freeze([...before]), after: field.values,
+                source: field.source, approvedWindow: approved ? Object.freeze({ id: approved.id, reason: approved.reason, startsAt: approved.startsAt, endsAt: approved.endsAt }) : null,
+                collectionDepth: item.collectionDepth, changeInterval,
+                explanation,
+            }));
         }
     }
     const domains = [...new Set(observations.map((item) => item.domain))].sort(ordinalCompare);
@@ -457,6 +549,7 @@ export function buildDomainControlFlightRecorder(inputRaw, generatedAtValue = ne
             unexpectedChanges: observedChanges.filter((event) => event.approvedWindow === null).length,
             collectionChanges: collectionChanges.length,
             recoveredSources: events.filter((event) => event.kind === 'recovered').length,
+            incompleteFields,
         }),
         limitations: DOMAIN_CONTROL_FLIGHT_RECORDER_LIMITATIONS,
     });
@@ -475,9 +568,15 @@ function exactRecorderInteger(value, minimum, maximum, label) {
     }
     return Number(value);
 }
-function exactRecorderValues(value, label) {
-    const input = boundedDataArray(value, label, 0, MAX_FLIGHT_RECORDER_VALUES);
-    const normalized = input.map((item, index) => exactRecorderText(item, `${label}[${index}]`, MAX_FLIGHT_RECORDER_VALUE_LENGTH));
+function exactRecorderValues(value, label, legacy, field, complete) {
+    const input = boundedDataArray(value, label, 0, legacy ? PUBLIC_MAX_FLIGHT_RECORDER_VALUES : MAX_FLIGHT_RECORDER_VALUES);
+    const normalized = input.map((item, index) => {
+        const result = legacy ? exactRecorderText(item, `${label}[${index}]`, PUBLIC_MAX_FLIGHT_RECORDER_VALUE_LENGTH)
+            : recorderValue(item, `${label}[${index}]`, false, field, complete);
+        if (result !== item)
+            throw new TypeError(`${label} must use canonical values.`);
+        return result;
+    });
     if (new Set(normalized).size !== normalized.length
         || normalized.some((item, index) => index > 0 && normalized[index - 1] >= item)) {
         throw new TypeError(`${label} must contain unique canonically ordered values.`);
@@ -487,9 +586,11 @@ function exactRecorderValues(value, label) {
 export function validateDomainControlFlightRecorderDocument(value) {
     const root = exactRecord(value, DOCUMENT_ROOT_KEYS, 'Domain control flight-recorder document');
     if (root.schema !== DOMAIN_CONTROL_FLIGHT_RECORDER_SCHEMA
-        || root.version !== DOMAIN_CONTROL_FLIGHT_RECORDER_VERSION) {
-        throw new TypeError(`Domain control flight-recorder document must use ${DOMAIN_CONTROL_FLIGHT_RECORDER_SCHEMA} version ${DOMAIN_CONTROL_FLIGHT_RECORDER_VERSION}.`);
+        || !SUPPORTED_DOMAIN_CONTROL_FLIGHT_RECORDER_VERSIONS.some((version) => version === root.version)) {
+        throw new TypeError(`Domain control flight-recorder document must use ${DOMAIN_CONTROL_FLIGHT_RECORDER_SCHEMA} supported version ${SUPPORTED_DOMAIN_CONTROL_FLIGHT_RECORDER_VERSIONS.join(' or ')}.`);
     }
+    const legacy = root.version === PUBLIC_DOMAIN_CONTROL_FLIGHT_RECORDER_VERSION;
+    const intervalVersion = root.version === DOMAIN_CONTROL_FLIGHT_RECORDER_VERSION;
     const generatedAt = requireIsoTimestamp(root.generatedAt, 'Domain control flight-recorder document generatedAt');
     if (generatedAt !== root.generatedAt) {
         throw new TypeError('Domain control flight-recorder document generatedAt must use its canonical timestamp form.');
@@ -517,10 +618,17 @@ export function validateDomainControlFlightRecorderDocument(value) {
         collection_change: 0,
         recovered: 0,
         approved_change: 0,
+        incomplete_observation: 0,
     };
+    const seenIds = new Set();
+    const latest = new Map();
+    const lastComplete = new Map();
+    const incompleteSince = new Map();
+    let lastCapture = -Infinity;
     const events = eventInput.map((eventValue, index) => {
         const label = `Domain control flight-recorder document event ${index + 1}`;
-        const event = exactRecord(eventValue, EVENT_KEYS, label);
+        const event = exactRecord(eventValue, legacy ? new Set(PUBLIC_DOMAIN_CONTROL_FLIGHT_RECORDER_EVENT_KEYS)
+            : intervalVersion ? EVENT_KEYS : new Set(SOURCE_TIMED_FLIGHT_RECORDER_EVENT_KEYS), label);
         const eventDomain = requireDomainName(event.domain, `${label}.domain`);
         if (eventDomain !== event.domain || !domains.includes(eventDomain)) {
             throw new TypeError(`${label}.domain must be present in the document domain list.`);
@@ -528,52 +636,115 @@ export function validateDomainControlFlightRecorderDocument(value) {
         if (typeof event.field !== 'string' || !FIELD_IDS.has(event.field)) {
             throw new TypeError(`${label}.field is unsupported.`);
         }
-        const observedAt = requireIsoTimestamp(event.observedAt, `${label}.observedAt`);
-        if (observedAt !== event.observedAt || Date.parse(observedAt) > Date.parse(generatedAt)) {
-            throw new TypeError(`${label}.observedAt must not be later than document generation.`);
-        }
+        const observedAt = !legacy && event.observedAt === null ? null : requireIsoTimestamp(event.observedAt, `${label}.observedAt`);
+        const capturedAt = legacy ? undefined : requireIsoTimestamp(event.capturedAt, `${label}.capturedAt`);
+        if (observedAt !== event.observedAt || (legacy && Date.parse(observedAt) > Date.parse(generatedAt))
+            || (!legacy && (capturedAt !== event.capturedAt || Date.parse(capturedAt) > Date.parse(generatedAt)
+                || Date.parse(capturedAt) < lastCapture)))
+            throw new TypeError(`${label} contains an invalid or unordered timestamp.`);
+        if (capturedAt)
+            lastCapture = Date.parse(capturedAt);
         if (event.kind !== 'first_observation'
             && event.kind !== 'observed_change'
             && event.kind !== 'collection_change'
-            && event.kind !== 'recovered') {
+            && event.kind !== 'recovered'
+            && (legacy || event.kind !== 'incomplete_observation')) {
             throw new TypeError(`${label}.kind is unsupported.`);
         }
-        const expectedState = event.kind === 'collection_change' ? 'partial' : 'observed';
+        const kind = event.kind;
+        const expectedState = kind === 'collection_change' || kind === 'incomplete_observation' ? 'partial' : 'observed';
         if (event.state !== expectedState)
             throw new TypeError(`${label}.state is inconsistent.`);
-        const before = exactRecorderValues(event.before, `${label}.before`);
-        const after = exactRecorderValues(event.after, `${label}.after`);
+        if (!legacy && expectedState === 'observed' && (observedAt === null || Date.parse(observedAt) > Date.parse(capturedAt))) {
+            throw new TypeError(`${label} cannot claim a complete observation without a source time at or before capture.`);
+        }
+        const collectionDepth = intervalVersion ? event.collectionDepth : undefined;
+        if (intervalVersion && (collectionDepth !== 'deep' && collectionDepth !== 'fast' && collectionDepth !== 'unknown'
+            || expectedState === 'observed' && collectionDepth === 'unknown')) {
+            throw new TypeError(`${label} has invalid collection conditions.`);
+        }
+        const before = exactRecorderValues(event.before, `${label}.before`, legacy, event.field, expectedState === 'observed');
+        const after = exactRecorderValues(event.after, `${label}.after`, legacy, event.field, expectedState === 'observed');
         if (((event.kind === 'first_observation' || event.kind === 'recovered') && before.length)
-            || (event.kind === 'collection_change' && after.length)) {
+            || (legacy && event.kind === 'collection_change' && after.length)) {
             throw new TypeError(`${label} before/after values are inconsistent.`);
         }
+        let changeInterval = null;
+        if (intervalVersion && event.changeInterval !== null) {
+            const interval = exactRecord(event.changeInterval, new Set(FLIGHT_RECORDER_CHANGE_INTERVAL_KEYS), `${label}.changeInterval`);
+            const after = requireIsoTimestamp(interval.after, `${label}.changeInterval.after`);
+            const by = requireIsoTimestamp(interval.by, `${label}.changeInterval.by`);
+            if (kind !== 'observed_change' || after !== interval.after || by !== interval.by || by !== observedAt || Date.parse(after) >= Date.parse(by)) {
+                throw new TypeError(`${label} has an inconsistent change interval.`);
+            }
+            changeInterval = Object.freeze({ after, by, incompleteObservations: exactRecorderInteger(interval.incompleteObservations, 0, MAX_FLIGHT_RECORDER_OBSERVATIONS, `${label}.changeInterval.incompleteObservations`) });
+        }
+        if (intervalVersion && (kind === 'observed_change') !== (changeInterval !== null))
+            throw new TypeError(`${label} must retain its change interval.`);
         let approvedWindow = null;
         if (event.approvedWindow !== null) {
             if (event.kind !== 'observed_change')
                 throw new TypeError(`${label}.approvedWindow is inconsistent.`);
-            const window = exactRecord(event.approvedWindow, EVENT_APPROVED_WINDOW_KEYS, `${label}.approvedWindow`);
+            const window = exactRecord(event.approvedWindow, intervalVersion ? EVENT_APPROVED_WINDOW_KEYS : new Set(HISTORICAL_FLIGHT_RECORDER_APPROVED_WINDOW_KEYS), `${label}.approvedWindow`);
+            const startsAt = intervalVersion ? requireIsoTimestamp(window.startsAt, `${label}.approvedWindow.startsAt`) : undefined;
+            const endsAt = intervalVersion ? requireIsoTimestamp(window.endsAt, `${label}.approvedWindow.endsAt`) : undefined;
+            if (intervalVersion && (!changeInterval || startsAt !== window.startsAt || endsAt !== window.endsAt
+                || Date.parse(startsAt) > Date.parse(changeInterval.after) || Date.parse(endsAt) < Date.parse(changeInterval.by))) {
+                throw new TypeError(`${label}.approvedWindow does not contain the change interval.`);
+            }
             approvedWindow = Object.freeze({
                 id: exactRecorderText(window.id, `${label}.approvedWindow.id`, MAX_FLIGHT_RECORDER_WINDOW_ID_LENGTH),
                 reason: exactRecorderText(window.reason, `${label}.approvedWindow.reason`, MAX_FLIGHT_RECORDER_WINDOW_REASON_LENGTH),
+                ...(intervalVersion ? { startsAt: startsAt, endsAt: endsAt } : {}),
             });
             kindCounts.approved_change += 1;
         }
-        kindCounts[event.kind] += 1;
-        return Object.freeze({
+        kindCounts[kind] += 1;
+        const result = Object.freeze({
             id: exactRecorderText(event.id, `${label}.id`, 400),
             domain: eventDomain,
             field: event.field,
             observedAt,
-            kind: event.kind,
+            ...(capturedAt ? { capturedAt } : {}),
+            kind,
             state: expectedState,
             before,
             after,
             source: exactRecorderText(event.source, `${label}.source`, MAX_FLIGHT_RECORDER_SOURCE_LENGTH),
             approvedWindow,
-            explanation: exactRecorderText(event.explanation, `${label}.explanation`, MAX_FLIGHT_RECORDER_VALUE_LENGTH),
+            explanation: exactRecorderText(event.explanation, `${label}.explanation`, legacy ? PUBLIC_MAX_FLIGHT_RECORDER_VALUE_LENGTH : MAX_FLIGHT_RECORDER_VALUE_LENGTH),
+            ...(intervalVersion ? { collectionDepth: collectionDepth, changeInterval } : {}),
         });
+        if (!legacy) {
+            const key = `${eventDomain}\u0000${event.field}`;
+            const previous = intervalVersion ? lastComplete.get(key) : latest.get(key);
+            if (seenIds.has(result.id) || (kind === 'observed_change' && (!previous || previous.state !== 'observed'
+                || previous.source !== result.source || Date.parse(previous.observedAt) >= Date.parse(result.observedAt)
+                || !sameValues(previous.after, before) || sameValues(before, after)
+                || intervalVersion && (previous.collectionDepth !== result.collectionDepth || !changeInterval
+                    || Date.parse(changeInterval.after) < Date.parse(previous.observedAt)
+                    || changeInterval.incompleteObservations !== (incompleteSince.get(key) ?? 0))))) {
+                throw new TypeError(`${label} has a duplicate identity or an unsupported observed-change claim.`);
+            }
+            seenIds.add(result.id);
+            latest.set(key, result);
+            if (intervalVersion) {
+                if (expectedState === 'observed') {
+                    lastComplete.set(key, result);
+                    incompleteSince.delete(key);
+                }
+                else {
+                    incompleteSince.set(key, (incompleteSince.get(key) ?? 0) + 1);
+                    if (previous && result.source !== 'Not supplied in this capture'
+                        && (previous.source !== result.source || result.collectionDepth !== 'unknown' && previous.collectionDepth !== result.collectionDepth))
+                        lastComplete.delete(key);
+                }
+            }
+        }
+        return result;
     });
-    const summaryInput = exactRecord(root.summary, SUMMARY_KEYS, 'Domain control flight-recorder document summary');
+    const summaryKeys = legacy ? PUBLIC_DOMAIN_CONTROL_FLIGHT_RECORDER_SUMMARY_KEYS : DOMAIN_CONTROL_FLIGHT_RECORDER_SUMMARY_KEYS;
+    const summaryInput = exactRecord(root.summary, legacy ? new Set(summaryKeys) : SUMMARY_KEYS, 'Domain control flight-recorder document summary');
     const expectedSummary = Object.freeze({
         firstObservations: kindCounts.first_observation,
         observedChanges: kindCounts.observed_change,
@@ -581,26 +752,29 @@ export function validateDomainControlFlightRecorderDocument(value) {
         unexpectedChanges: kindCounts.observed_change - kindCounts.approved_change,
         collectionChanges: kindCounts.collection_change,
         recoveredSources: kindCounts.recovered,
+        ...(!legacy ? { incompleteFields: kindCounts.collection_change + kindCounts.incomplete_observation } : {}),
     });
-    for (const key of DOMAIN_CONTROL_FLIGHT_RECORDER_SUMMARY_KEYS) {
+    for (const key of summaryKeys) {
         const supplied = exactRecorderInteger(summaryInput[key], 0, MAX_FLIGHT_RECORDER_EVENTS, `Domain control flight-recorder document summary ${key}`);
         if (supplied !== expectedSummary[key]) {
             throw new TypeError('Domain control flight-recorder document summary is inconsistent.');
         }
     }
-    const limitationsInput = boundedDataArray(root.limitations, 'Domain control flight-recorder document limitations', DOMAIN_CONTROL_FLIGHT_RECORDER_LIMITATIONS.length, DOMAIN_CONTROL_FLIGHT_RECORDER_LIMITATIONS.length);
-    if (limitationsInput.some((item, index) => item !== DOMAIN_CONTROL_FLIGHT_RECORDER_LIMITATIONS[index])) {
+    const limitations = legacy ? PUBLIC_DOMAIN_CONTROL_FLIGHT_RECORDER_LIMITATIONS
+        : intervalVersion ? DOMAIN_CONTROL_FLIGHT_RECORDER_LIMITATIONS : SOURCE_TIMED_FLIGHT_RECORDER_LIMITATIONS;
+    const limitationsInput = boundedDataArray(root.limitations, 'Domain control flight-recorder document limitations', limitations.length, limitations.length);
+    if (limitationsInput.some((item, index) => item !== limitations[index])) {
         throw new TypeError('Domain control flight-recorder document limitations are invalid.');
     }
     const document = Object.freeze({
         schema: DOMAIN_CONTROL_FLIGHT_RECORDER_SCHEMA,
-        version: DOMAIN_CONTROL_FLIGHT_RECORDER_VERSION,
+        version: root.version,
         generatedAt,
         domains: Object.freeze(domains),
         observationCount,
         events: Object.freeze(events),
         summary: expectedSummary,
-        limitations: DOMAIN_CONTROL_FLIGHT_RECORDER_LIMITATIONS,
+        limitations,
     });
     assertPrettyJsonByteBudget(document, MAX_DOMAIN_CONTROL_FLIGHT_RECORDER_OUTPUT_BYTES, 'Domain control flight-recorder document');
     return document;
@@ -621,10 +795,13 @@ export function formatDomainControlFlightRecorder(document) {
         `Unexpected changes  ${document.summary.unexpectedChanges}`,
         `Approved changes    ${document.summary.approvedChanges}`,
         `Collection changes  ${document.summary.collectionChanges}`,
+        ...(document.summary.incompleteFields === undefined ? [] : [`Incomplete fields   ${document.summary.incompleteFields}`]),
         '',
     ];
     for (const event of document.events.filter((item) => item.kind !== 'first_observation')) {
-        lines.push(`${event.observedAt}  ${event.domain}  ${event.field.replaceAll('_', ' ')}  ${event.kind.replaceAll('_', ' ')}`);
+        lines.push(`${event.observedAt ?? 'Source time unavailable'}  ${event.domain}  ${event.field.replaceAll('_', ' ')}  ${event.kind.replaceAll('_', ' ')}`);
+        if (event.capturedAt)
+            lines.push(`  Captured ${event.capturedAt}`);
         lines.push(`  ${event.explanation}`);
     }
     if (!document.events.some((item) => item.kind !== 'first_observation')) {