wabachi 0.1.0

package/dist/runtime/matrix.js

@@ -0,0 +1,1485 @@
+import { mkdir, open, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { FACT_SCHEMA_VERSION, factEqualityKey, } from "./facts.js";
+/** Version of the deterministic Provider Matrix artifact. */
+export const PROVIDER_MATRIX_SCHEMA_VERSION = 1;
+export const MATRIX_METRIC_DEFINITIONS = [
+    {
+        id: "normalizationCoverage",
+        numerator: "normalizedFactCount",
+        denominator: "rawObservedFactCount",
+        meaning: "Fraction of retained provider observations mapped to a common normalized predicate; null when no raw observation exists.",
+    },
+    {
+        id: "matchedCoverage",
+        numerator: "facts whose entity endpoints are all matched",
+        denominator: "normalizedFactCount",
+        meaning: "Fraction of normalized facts whose entity correlations are deterministic matches.",
+    },
+    {
+        id: "correlationCoverage",
+        numerator: "facts whose entity endpoints are matched or probable",
+        denominator: "normalizedFactCount",
+        meaning: "Fraction of normalized facts with a usable canonical entity identity; ambiguous and unmatched facts are excluded.",
+    },
+    {
+        id: "pairwiseOverlap",
+        numerator: "distinct exact comparable fact keys present in both providers",
+        denominator: "minimum of the two providers' distinct comparable fact-key counts",
+        meaning: "Exact normalized fact overlap; conflicting values are not counted as overlap unless the exact value is also shared.",
+    },
+    {
+        id: "allProviderOverlap",
+        numerator: "distinct exact comparable fact keys present in every selected provider",
+        denominator: "distinct exact comparable fact keys in the selected-provider union",
+        meaning: "Common evidence across the complete selected provider set; a provider with no fact makes the numerator zero.",
+    },
+    {
+        id: "uniqueCoverage",
+        numerator: "distinct comparable logical fact keys observed by exactly one provider",
+        denominator: "that provider's distinct comparable logical fact keys",
+        meaning: "Provider-only comparable coverage; conflicting values are not called unique because both providers observed the same logical fact.",
+    },
+    {
+        id: "incrementalInformationGain",
+        numerator: "new distinct exact comparable fact keys absent from the existing provider set",
+        denominator: "the added provider's distinct comparable fact keys",
+        meaning: "Deterministic gain for the explicitly recorded addition order; unsupported, ambiguous, and unmatched evidence is counted separately.",
+    },
+];
+/**
+ * Builds all matrix views from normalized/persisted facts. It only consumes
+ * artifacts; provider execution and observation generation are intentionally
+ * outside this function.
+ */
+export function buildProviderMatrix(input, options = {}) {
+    const artifact = input;
+    const entries = collectProviders(artifact, options);
+    const providers = entries.map((entry) => entry.provider);
+    const additionEntries = orderAdditions(entries, options.additionOrder);
+    const additionOrder = additionEntries.map((entry) => entry.provider);
+    const providerByKey = new Map(entries.map((entry) => [entry.key, entry.provider]));
+    const facts = artifact.facts.map(toFactDescriptor).sort(compareFactDescriptors);
+    const unsupported = artifact.unsupported.map(toUnsupportedDescriptor).sort(compareUnsupportedDescriptors);
+    const rows = buildFactRows(facts, unsupported, entries);
+    const factClasses = collectFactClasses(facts, unsupported);
+    const uniqueLogicalProviders = indexLogicalProviders(facts);
+    const coverage = providers.map((provider) => buildProviderCoverage(provider, facts, unsupported, factClasses, uniqueLogicalProviders, artifact.correlation));
+    const overlap = buildOverlap(providers, entries, facts, factClasses, rows);
+    const conflicts = rows.filter((row) => row.state === "conflict");
+    const unmatchedRecords = rows.filter((row) => row.state === "ambiguous" || row.state === "unmatched" || row.state === "unsupported");
+    const unmatched = {
+        ambiguous: unmatchedRecords.filter((row) => row.state === "ambiguous"),
+        unmatched: unmatchedRecords.filter((row) => row.state === "unmatched"),
+        unsupported: unmatchedRecords.filter((row) => row.state === "unsupported"),
+        records: unmatchedRecords,
+    };
+    const informationGain = buildInformationGain(additionEntries, facts, unsupported, coverage, factClasses, providerByKey);
+    return {
+        schemaVersion: PROVIDER_MATRIX_SCHEMA_VERSION,
+        inputFactSchemaVersion: FACT_SCHEMA_VERSION,
+        generatedBy: "deterministic-rules",
+        repositories: collectRepositories(facts, unsupported),
+        providers,
+        additionOrder,
+        metricDefinitions: MATRIX_METRIC_DEFINITIONS,
+        coverage,
+        overlap,
+        conflicts,
+        unmatched,
+        informationGain,
+        facts: rows,
+    };
+}
+/** Alias for callers that use the generation vocabulary. */
+export const generateProviderMatrix = buildProviderMatrix;
+function collectProviders(artifact, options) {
+    const byKey = new Map();
+    const add = (provider) => {
+        byKey.set(providerKey(provider), provider);
+    };
+    for (const provider of options.providers ?? [])
+        add(provider);
+    for (const fact of artifact.facts)
+        add(fact.provider);
+    for (const evidence of artifact.unsupported)
+        add(evidence.provider);
+    for (const metric of Object.values(artifact.correlation.metrics))
+        add(metric.provider);
+    return [...byKey.entries()].map(([key, provider]) => ({ key, provider })).sort(compareProviderEntries);
+}
+function orderAdditions(entries, requested) {
+    if (requested === undefined)
+        return [...entries];
+    const byKey = new Map(entries.map((entry) => [entry.key, entry]));
+    const result = [];
+    const seen = new Set();
+    for (const provider of requested) {
+        const key = providerKey(provider);
+        const entry = byKey.get(key);
+        if (entry !== undefined && !seen.has(key)) {
+            result.push(entry);
+            seen.add(key);
+        }
+    }
+    for (const entry of entries) {
+        if (!seen.has(entry.key))
+            result.push(entry);
+    }
+    return result;
+}
+function toFactDescriptor(fact) {
+    const correlationStatus = factCorrelationStatus(fact);
+    const comparable = correlationStatus === "matched" || correlationStatus === "probable";
+    return {
+        fact,
+        providerKey: providerKey(fact.provider),
+        factClass: fact.predicate,
+        exactKey: factEqualityKey(fact),
+        logicalKey: comparable ? logicalFactKey(fact) : undefined,
+        correlationStatus,
+        comparable,
+    };
+}
+function toUnsupportedDescriptor(evidence) {
+    const correlationStatus = factCorrelationStatus(evidence);
+    const comparable = correlationStatus === "matched" || correlationStatus === "probable";
+    return {
+        evidence,
+        providerKey: providerKey(evidence.provider),
+        factClass: evidence.predicate,
+        logicalKey: comparable ? logicalFactKey(evidence) : undefined,
+        correlationStatus,
+        comparable,
+    };
+}
+function buildFactRows(facts, unsupported, entries) {
+    const comparableGroups = new Map();
+    for (const descriptor of facts) {
+        if (descriptor.logicalKey === undefined)
+            continue;
+        const group = comparableGroups.get(descriptor.logicalKey) ?? [];
+        group.push(descriptor);
+        comparableGroups.set(descriptor.logicalKey, group);
+    }
+    const rows = [];
+    for (const [logicalKey, group] of comparableGroups) {
+        rows.push(buildComparableRow(logicalKey, group, entries));
+    }
+    for (const descriptor of facts.filter((item) => !item.comparable)) {
+        rows.push(buildUnresolvedFactRow(descriptor, entries));
+    }
+    const unsupportedGroups = new Map();
+    for (const descriptor of unsupported) {
+        const key = descriptor.logicalKey === undefined
+            ? "unsupported:" + descriptor.providerKey + ":" + descriptor.evidence.nativeEvidence.id
+            : "unsupported:" + descriptor.logicalKey;
+        const group = unsupportedGroups.get(key) ?? [];
+        group.push(descriptor);
+        unsupportedGroups.set(key, group);
+    }
+    for (const [key, group] of unsupportedGroups) {
+        rows.push(buildUnsupportedRow(key, group, entries));
+    }
+    return rows.sort(compareMatrixRows);
+}
+function buildComparableRow(logicalKey, descriptors, entries) {
+    const variantsByKey = new Map();
+    for (const descriptor of descriptors) {
+        const variant = variantsByKey.get(descriptor.exactKey) ?? [];
+        variant.push(descriptor);
+        variantsByKey.set(descriptor.exactKey, variant);
+    }
+    const variants = [...variantsByKey.entries()]
+        .sort(([left], [right]) => compareCodeUnits(left, right))
+        .map(([, group]) => buildFactVariant(group));
+    const observedProviders = uniqueProviders(descriptors.map((descriptor) => descriptor.fact.provider));
+    const state = variants.length > 1 ? "conflict" : observedProviders.length > 1 ? "overlap" : "provider-only";
+    const first = sortFactDescriptors(descriptors)[0];
+    if (first === undefined)
+        throw new Error("matrix comparable group cannot be empty");
+    return makeRow({
+        key: logicalKey,
+        logicalKey,
+        repository: first.fact.repository,
+        factClass: first.factClass,
+        predicate: first.fact.predicate,
+        state,
+        comparisonPossible: true,
+        correlationStatus: descriptors.some((item) => item.correlationStatus === "probable") ? "probable" : "matched",
+        variants,
+        observedProviders,
+        entries,
+        stateForObserved: "present",
+        evidenceForObserved: descriptors,
+    });
+}
+function buildUnresolvedFactRow(descriptor, entries) {
+    const fact = descriptor.fact;
+    const state = descriptor.correlationStatus === "ambiguous" ? "ambiguous" : "unmatched";
+    return makeRow({
+        key: "unresolved:" + descriptor.providerKey + ":" + fact.factId,
+        logicalKey: "unresolved:" + factEqualityKey(fact),
+        repository: fact.repository,
+        factClass: fact.predicate,
+        predicate: fact.predicate,
+        state,
+        comparisonPossible: false,
+        correlationStatus: descriptor.correlationStatus,
+        variants: [buildFactVariant([descriptor])],
+        observedProviders: [fact.provider],
+        entries,
+        stateForObserved: state,
+        evidenceForObserved: [descriptor],
+    });
+}
+function buildUnsupportedRow(key, descriptors, entries) {
+    const ordered = sortUnsupportedDescriptors(descriptors);
+    const first = ordered[0];
+    if (first === undefined)
+        throw new Error("matrix unsupported group cannot be empty");
+    const observedProviders = uniqueProviders(ordered.map((descriptor) => descriptor.evidence.provider));
+    const variants = ordered.map((descriptor) => buildUnsupportedVariant(descriptor));
+    return makeRow({
+        key,
+        logicalKey: key,
+        repository: first.evidence.repository,
+        factClass: first.factClass,
+        predicate: first.evidence.predicate,
+        state: "unsupported",
+        comparisonPossible: false,
+        correlationStatus: first.comparable ? "not-applicable" : first.correlationStatus,
+        variants,
+        observedProviders,
+        entries,
+        stateForObserved: "unsupported",
+        evidenceForObserved: ordered,
+    });
+}
+function makeRow(input) {
+    const observedKeys = new Set(input.observedProviders.map(providerKey));
+    const evidenceByProvider = new Map();
+    for (const item of input.evidenceForObserved) {
+        const provider = "fact" in item ? item.fact.provider : item.evidence.provider;
+        const key = providerKey(provider);
+        const value = evidenceByProvider.get(key) ?? { factIds: [], evidenceIds: [] };
+        if ("fact" in item) {
+            value.factIds.push(item.fact.factId);
+            value.evidenceIds.push(item.fact.nativeEvidence.id);
+        }
+        else {
+            value.evidenceIds.push(item.evidence.nativeEvidence.id);
+        }
+        evidenceByProvider.set(key, value);
+    }
+    const providerStates = input.entries.map((entry) => {
+        const evidence = evidenceByProvider.get(entry.key);
+        return {
+            provider: entry.provider,
+            state: observedKeys.has(entry.key) ? input.stateForObserved : "missing",
+            factIds: [...new Set(evidence?.factIds ?? [])].sort(),
+            evidenceIds: [...new Set(evidence?.evidenceIds ?? [])].sort(),
+        };
+    });
+    return {
+        key: input.key,
+        logicalKey: input.logicalKey,
+        repository: input.repository,
+        factClass: input.factClass,
+        predicate: input.predicate,
+        state: input.state,
+        comparisonPossible: input.comparisonPossible,
+        correlationStatus: input.correlationStatus,
+        variants: [...input.variants].sort(compareVariants),
+        providerStates,
+        observedProviders: [...input.observedProviders].sort(compareProviders),
+        missingProviders: input.entries.filter((entry) => !observedKeys.has(entry.key)).map((entry) => entry.provider),
+    };
+}
+function buildFactVariant(descriptors) {
+    const ordered = sortFactDescriptors(descriptors);
+    const first = ordered[0];
+    if (first === undefined)
+        throw new Error("matrix fact variant cannot be empty");
+    return {
+        key: first.exactKey,
+        factIds: [...new Set(ordered.map((descriptor) => descriptor.fact.factId))].sort(),
+        evidenceIds: [...new Set(ordered.map((descriptor) => descriptor.fact.nativeEvidence.id))].sort(),
+        providers: uniqueProviders(ordered.map((descriptor) => descriptor.fact.provider)),
+        subject: toMatrixEntity(first.fact.subject),
+        predicate: first.fact.predicate,
+        object: toMatrixObject(first.fact.object),
+    };
+}
+function buildUnsupportedVariant(descriptor) {
+    const evidence = descriptor.evidence;
+    return {
+        key: "unsupported:" + evidence.nativeEvidence.id,
+        factIds: [],
+        evidenceIds: [evidence.nativeEvidence.id],
+        providers: [evidence.provider],
+        subject: toMatrixEntity(evidence.subject),
+        predicate: evidence.predicate,
+        object: toMatrixObject(evidence.object),
+    };
+}
+function toMatrixEntity(entity) {
+    return {
+        provider: entity.provider,
+        nativeId: entity.nativeId,
+        kind: entity.kind,
+        ...(entity.canonicalId === undefined ? {} : { canonicalId: entity.canonicalId }),
+        candidateCanonicalIds: [...entity.candidateCanonicalIds].sort(),
+        correlationStatus: entity.correlationStatus,
+        ...(entity.path === undefined ? {} : { path: entity.path }),
+        ...(entity.range === undefined ? {} : { range: entity.range }),
+    };
+}
+function toMatrixObject(object) {
+    if ("nativeId" in object)
+        return { kind: "entity", entity: toMatrixEntity(object) };
+    return { kind: "value", value: object.value };
+}
+function buildProviderCoverage(provider, facts, unsupported, factClasses, uniqueLogicalProviders, correlation) {
+    const providerKeyValue = providerKey(provider);
+    const providerFacts = facts.filter((descriptor) => descriptor.providerKey === providerKeyValue);
+    const providerUnsupported = unsupported.filter((descriptor) => descriptor.providerKey === providerKeyValue);
+    const factCorrelation = countFactCorrelation(providerFacts);
+    const rawObservedFactCount = providerFacts.length + providerUnsupported.length;
+    const uniqueFactKeys = uniqueKeysForProvider(providerFacts, uniqueLogicalProviders);
+    const factsByClass = groupByFactClass(providerFacts);
+    const unsupportedByClass = groupByFactClass(providerUnsupported);
+    const factClassCoverage = factClasses.map((factClass) => {
+        const classFacts = factsByClass.get(factClass) ?? [];
+        const classUnsupported = unsupportedByClass.get(factClass) ?? [];
+        const classCorrelation = countFactCorrelation(classFacts);
+        const classUniqueFactKeys = uniqueKeysForProvider(classFacts, uniqueLogicalProviders);
+        return {
+            factClass,
+            rawObservedFactCount: classFacts.length + classUnsupported.length,
+            normalizedFactCount: classFacts.length,
+            unsupportedFactCount: classUnsupported.length,
+            factCorrelation: classCorrelation,
+            normalizationCoverage: ratio(classFacts.length, classFacts.length + classUnsupported.length),
+            uniqueFactCount: classUniqueFactKeys.length,
+            uniqueCoverage: ratio(classUniqueFactKeys.length, comparableLogicalFactCount(classFacts)),
+            uniqueFactKeys: classUniqueFactKeys,
+        };
+    });
+    const entity = findCorrelationMetric(provider, correlation);
+    const entityCorrelation = toEntityCorrelationCounts(entity);
+    return {
+        provider,
+        factClass: "__all__",
+        rawObservedFactCount,
+        normalizedFactCount: providerFacts.length,
+        unsupportedFactCount: providerUnsupported.length,
+        factCorrelation,
+        normalizationCoverage: ratio(providerFacts.length, rawObservedFactCount),
+        uniqueFactCount: uniqueFactKeys.length,
+        uniqueCoverage: ratio(uniqueFactKeys.length, comparableLogicalFactCount(providerFacts)),
+        uniqueFactKeys,
+        factClasses: factClassCoverage,
+        entityCorrelation,
+    };
+}
+function groupByFactClass(descriptors) {
+    const groups = new Map();
+    for (const descriptor of descriptors) {
+        const group = groups.get(descriptor.factClass) ?? [];
+        group.push(descriptor);
+        groups.set(descriptor.factClass, group);
+    }
+    return groups;
+}
+function countFactCorrelation(facts) {
+    const counts = { matched: 0, probable: 0, ambiguous: 0, unmatched: 0 };
+    for (const descriptor of facts)
+        counts[descriptor.correlationStatus] += 1;
+    const correlated = counts.matched + counts.probable;
+    return {
+        ...counts,
+        correlated,
+        matchedCoverage: ratio(counts.matched, facts.length),
+        correlatedCoverage: ratio(correlated, facts.length),
+    };
+}
+function uniqueKeysForProvider(facts, uniqueLogicalProviders) {
+    if (facts.length === 0)
+        return [];
+    return [
+        ...new Set(facts
+            .filter((descriptor) => descriptor.comparable && descriptor.logicalKey !== undefined)
+            .filter((descriptor) => uniqueLogicalProviders.get(descriptor.logicalKey ?? "")?.size === 1)
+            .map((descriptor) => descriptor.logicalKey)),
+    ].sort();
+}
+function comparableLogicalFactCount(facts) {
+    return new Set(facts
+        .filter((descriptor) => descriptor.comparable && descriptor.logicalKey !== undefined)
+        .map((descriptor) => descriptor.logicalKey)).size;
+}
+function toEntityCorrelationCounts(metric) {
+    const total = metric?.total ?? 0;
+    const matched = metric?.matched ?? 0;
+    const probable = metric?.probable ?? 0;
+    const ambiguous = metric?.ambiguous ?? 0;
+    const unmatched = metric?.unmatched ?? 0;
+    return {
+        total,
+        matched,
+        probable,
+        correlated: matched + probable,
+        ambiguous,
+        unmatched,
+        matchedCoverage: ratio(matched, total),
+        correlatedCoverage: ratio(matched + probable, total),
+    };
+}
+function findCorrelationMetric(provider, correlation) {
+    const expected = providerKey(provider);
+    return Object.values(correlation.metrics).find((metric) => providerKey(metric.provider) === expected);
+}
+function buildOverlap(providers, entries, facts, factClasses, rows) {
+    const index = indexComparableFactSets(facts, entries, factClasses);
+    const pairwise = [];
+    for (let leftIndex = 0; leftIndex < entries.length; leftIndex += 1) {
+        for (let rightIndex = leftIndex + 1; rightIndex < entries.length; rightIndex += 1) {
+            const left = entries[leftIndex];
+            const right = entries[rightIndex];
+            for (const factClass of factClasses) {
+                pairwise.push(buildPairwiseOverlap(left, right, factClass, index));
+            }
+        }
+    }
+    const allProviders = factClasses.map((factClass) => buildAllProviderOverlap(providers, entries, factClass, index));
+    return {
+        pairwise: pairwise.sort(comparePairwiseOverlap),
+        allProviders: allProviders.sort((left, right) => compareCodeUnits(left.factClass, right.factClass)),
+        facts: rows.filter((row) => row.state === "overlap"),
+    };
+}
+/**
+ * Groups comparable facts by provider and fact class once so pairwise and
+ * all-provider overlap can look up a set instead of re-scanning every fact
+ * descriptor for every provider pair. Without this index, overlap
+ * construction is O(providers^2 x factClasses x facts), which took minutes
+ * and pegged a CPU core against the real TypeScript provider's fact volume.
+ */
+function indexComparableFactSets(facts, entries, factClasses) {
+    const index = new Map();
+    for (const entry of entries) {
+        for (const factClass of factClasses) {
+            index.set(indexKey(entry.key, factClass), { byLogical: new Map() });
+        }
+    }
+    for (const descriptor of facts) {
+        if (!descriptor.comparable || descriptor.logicalKey === undefined)
+            continue;
+        const key = indexKey(descriptor.providerKey, descriptor.factClass);
+        const entry = index.get(key);
+        if (entry === undefined)
+            continue;
+        const values = entry.byLogical.get(descriptor.logicalKey) ?? new Set();
+        values.add(descriptor.exactKey);
+        entry.byLogical.set(descriptor.logicalKey, values);
+    }
+    return index;
+}
+/** Collision-free even when providerKeyValue or factClass contain the delimiter. */
+function indexKey(providerKeyValue, factClass) {
+    return JSON.stringify([providerKeyValue, factClass]);
+}
+function buildPairwiseOverlap(left, right, factClass, index) {
+    const leftSets = index.get(indexKey(left.key, factClass)) ?? { byLogical: new Map() };
+    const rightSets = index.get(indexKey(right.key, factClass)) ?? { byLogical: new Map() };
+    const logicalKeys = new Set([...leftSets.byLogical.keys(), ...rightSets.byLogical.keys()]);
+    const overlapFactKeys = intersection(exactKeys(leftSets.byLogical), exactKeys(rightSets.byLogical));
+    const leftOnly = [...leftSets.byLogical.keys()].filter((key) => !rightSets.byLogical.has(key)).sort();
+    const rightOnly = [...rightSets.byLogical.keys()].filter((key) => !leftSets.byLogical.has(key)).sort();
+    const conflictLogicalKeys = [...leftSets.byLogical.keys()]
+        .filter((key) => rightSets.byLogical.has(key))
+        .filter((key) => !setsEqual(leftSets.byLogical.get(key) ?? new Set(), rightSets.byLogical.get(key) ?? new Set()))
+        .sort();
+    const leftCount = exactKeys(leftSets.byLogical).length;
+    const rightCount = exactKeys(rightSets.byLogical).length;
+    return {
+        left: left.provider,
+        right: right.provider,
+        factClass,
+        leftComparableFactCount: leftCount,
+        rightComparableFactCount: rightCount,
+        comparedLogicalFactCount: [...logicalKeys].filter((key) => leftSets.byLogical.has(key) && rightSets.byLogical.has(key)).length,
+        overlapFactCount: overlapFactKeys.length,
+        leftOnlyFactCount: leftOnly.length,
+        rightOnlyFactCount: rightOnly.length,
+        conflictFactCount: conflictLogicalKeys.length,
+        overlapCoverage: ratio(overlapFactKeys.length, Math.min(leftCount, rightCount)),
+        overlapFactKeys,
+        conflictLogicalKeys,
+    };
+}
+function buildAllProviderOverlap(providers, entries, factClass, index) {
+    const exactSets = entries.map((entry) => index.get(indexKey(entry.key, factClass)) ?? { byLogical: new Map() });
+    const exactKeySets = exactSets.map((set) => new Set(exactKeys(set.byLogical)));
+    const union = new Set();
+    for (const keys of exactKeySets)
+        for (const key of keys)
+            union.add(key);
+    const overlap = entries.length === 0 ? [] : [...union].filter((key) => exactKeySets.every((keys) => keys.has(key))).sort();
+    return {
+        factClass,
+        providers,
+        providerCount: providers.length,
+        comparableFactUnionCount: union.size,
+        allProviderOverlapFactCount: overlap.length,
+        allProviderOverlapCoverage: ratio(overlap.length, union.size),
+        overlapFactKeys: overlap,
+    };
+}
+function buildInformationGain(additionEntries, facts, unsupported, coverage, factClasses, providerByKey) {
+    const baseline = new Set();
+    const result = [];
+    for (const entry of additionEntries) {
+        const providerFacts = facts.filter((descriptor) => descriptor.providerKey === entry.key && descriptor.comparable);
+        const exactKeysForProvider = [...new Set(providerFacts.map((descriptor) => descriptor.exactKey))].sort();
+        const newComparableFactKeys = exactKeysForProvider.filter((key) => !baseline.has(key));
+        const newComparableFactKeySet = new Set(newComparableFactKeys);
+        const keysByClass = new Map();
+        for (const descriptor of providerFacts) {
+            const values = keysByClass.get(descriptor.factClass) ?? new Set();
+            values.add(descriptor.exactKey);
+            keysByClass.set(descriptor.factClass, values);
+        }
+        const classCounts = factClasses
+            .map((factClass) => {
+            const classKeys = keysByClass.get(factClass) ?? new Set();
+            const newKeys = [...classKeys].filter((key) => newComparableFactKeySet.has(key)).sort();
+            return { factClass, newComparableFactCount: newKeys.length, newComparableFactKeys: newKeys };
+        })
+            .filter((item) => item.newComparableFactCount > 0);
+        for (const key of exactKeysForProvider)
+            baseline.add(key);
+        const providerCoverage = coverage.find((item) => providerKey(item.provider) === entry.key);
+        const providerUnsupported = unsupported.filter((item) => item.providerKey === entry.key);
+        const providerAmbiguous = facts.filter((item) => item.providerKey === entry.key && item.correlationStatus === "ambiguous");
+        const providerUnmatched = facts.filter((item) => item.providerKey === entry.key && item.correlationStatus === "unmatched");
+        const entryIndex = additionEntries.findIndex((item) => item.key === entry.key);
+        const existingProviders = additionEntries.slice(0, entryIndex).map((item) => item.provider);
+        const normalizedProvider = providerByKey.get(entry.key) ?? entry.provider;
+        result.push({
+            provider: normalizedProvider,
+            existingProviders,
+            newComparableFactCount: newComparableFactKeys.length,
+            newComparableFactKeys,
+            newFactClasses: classCounts,
+            uniqueFactCount: providerCoverage?.uniqueFactCount ?? 0,
+            uniqueFactKeys: providerCoverage?.uniqueFactKeys ?? [],
+            informationGainCoverage: ratio(newComparableFactKeys.length, new Set(providerFacts.map((descriptor) => descriptor.exactKey)).size),
+            newUnsupportedFactCount: providerUnsupported.length,
+            newUnsupportedEvidenceIds: providerUnsupported.map((item) => item.evidence.nativeEvidence.id).sort(),
+            newAmbiguousFactCount: providerAmbiguous.length,
+            newAmbiguousFactIds: providerAmbiguous.map((item) => item.fact.factId).sort(),
+            newUnmatchedFactCount: providerUnmatched.length,
+            newUnmatchedFactIds: providerUnmatched.map((item) => item.fact.factId).sort(),
+        });
+    }
+    return result;
+}
+function factCorrelationStatus(value) {
+    const entities = [value.subject, ...("nativeId" in value.object ? [value.object] : [])];
+    if (entities.some((entity) => entity.correlationStatus === "ambiguous"))
+        return "ambiguous";
+    if (entities.some((entity) => entity.correlationStatus === "unmatched" || entity.canonicalId === undefined)) {
+        return "unmatched";
+    }
+    if (entities.every((entity) => entity.correlationStatus === "matched"))
+        return "matched";
+    return "probable";
+}
+function logicalFactKey(value) {
+    const subject = value.subject.canonicalId;
+    if (subject === undefined)
+        throw new Error("logical fact key requires a canonical subject");
+    return stableSerialize({ repository: value.repository, subject, predicate: value.predicate });
+}
+function indexLogicalProviders(facts) {
+    const result = new Map();
+    for (const descriptor of facts) {
+        if (!descriptor.comparable || descriptor.logicalKey === undefined)
+            continue;
+        const providers = result.get(descriptor.logicalKey) ?? new Set();
+        providers.add(descriptor.providerKey);
+        result.set(descriptor.logicalKey, providers);
+    }
+    return result;
+}
+function collectFactClasses(facts, unsupported) {
+    return [...new Set([...facts.map((fact) => fact.factClass), ...unsupported.map((item) => item.factClass)])].sort();
+}
+function collectRepositories(facts, unsupported) {
+    const values = [...facts.map((item) => item.fact.repository), ...unsupported.map((item) => item.evidence.repository)];
+    const byKey = new Map();
+    for (const repository of values)
+        byKey.set(stableSerialize(repository), repository);
+    return [...byKey.entries()].sort(([left], [right]) => compareCodeUnits(left, right)).map(([, value]) => value);
+}
+function ratio(numerator, denominator) {
+    return { numerator, denominator, value: denominator === 0 ? null : numerator / denominator };
+}
+function providerKey(provider) {
+    return provider.id + "\u0000" + provider.version + "\u0000" + provider.determinism;
+}
+function compareProviderEntries(left, right) {
+    return compareCodeUnits(left.key, right.key);
+}
+function compareProviders(left, right) {
+    return compareCodeUnits(providerKey(left), providerKey(right));
+}
+function compareFactDescriptors(left, right) {
+    const key = compareCodeUnits(left.exactKey, right.exactKey);
+    if (key !== 0)
+        return key;
+    const provider = compareCodeUnits(left.providerKey, right.providerKey);
+    if (provider !== 0)
+        return provider;
+    return compareCodeUnits(left.fact.factId, right.fact.factId);
+}
+function sortFactDescriptors(values) {
+    return [...values].sort(compareFactDescriptors);
+}
+function compareUnsupportedDescriptors(left, right) {
+    const leftKey = stableSerialize({
+        predicate: left.factClass,
+        provider: left.providerKey,
+        evidence: left.evidence.nativeEvidence.id,
+    });
+    const rightKey = stableSerialize({
+        predicate: right.factClass,
+        provider: right.providerKey,
+        evidence: right.evidence.nativeEvidence.id,
+    });
+    return compareCodeUnits(leftKey, rightKey);
+}
+function sortUnsupportedDescriptors(values) {
+    return [...values].sort(compareUnsupportedDescriptors);
+}
+function compareMatrixRows(left, right) {
+    const repository = compareCodeUnits(stableSerialize(left.repository), stableSerialize(right.repository));
+    if (repository !== 0)
+        return repository;
+    const factClass = compareCodeUnits(left.factClass, right.factClass);
+    if (factClass !== 0)
+        return factClass;
+    return compareCodeUnits(left.key, right.key);
+}
+function compareVariants(left, right) {
+    return compareCodeUnits(left.key, right.key);
+}
+function comparePairwiseOverlap(left, right) {
+    const provider = compareCodeUnits(providerKey(left.left), providerKey(right.left));
+    if (provider !== 0)
+        return provider;
+    const rightProvider = compareCodeUnits(providerKey(left.right), providerKey(right.right));
+    if (rightProvider !== 0)
+        return rightProvider;
+    return compareCodeUnits(left.factClass, right.factClass);
+}
+function uniqueProviders(values) {
+    const byKey = new Map();
+    for (const provider of values)
+        byKey.set(providerKey(provider), provider);
+    return [...byKey.values()].sort(compareProviders);
+}
+function exactKeys(byLogical) {
+    return [...new Set([...byLogical.values()].flatMap((values) => [...values]))].sort();
+}
+function intersection(left, right) {
+    const rightSet = new Set(right);
+    return [...new Set(left)].filter((value) => rightSet.has(value)).sort();
+}
+function setsEqual(left, right) {
+    if (left.size !== right.size)
+        return false;
+    for (const value of left)
+        if (!right.has(value))
+            return false;
+    return true;
+}
+/**
+ * Deterministic ordering independent of host locale/ICU data. Artifact
+ * ordering must reproduce identically across machines.
+ */
+function compareCodeUnits(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function stableSerialize(value) {
+    if (value === null)
+        return "null";
+    if (value === undefined)
+        return "undefined";
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    if (typeof value === "number" || typeof value === "boolean")
+        return JSON.stringify(value);
+    if (typeof value === "bigint")
+        return value.toString() + "n";
+    if (Array.isArray(value))
+        return "[" + value.map((item) => stableSerialize(item)).join(",") + "]";
+    if (typeof value === "object") {
+        const record = value;
+        return ("{" +
+            Object.keys(record)
+                .sort()
+                .map((key) => JSON.stringify(key) + ":" + stableSerialize(record[key]))
+                .join(",") +
+            "}");
+    }
+    return JSON.stringify(String(value));
+}
+/** Renders the matrix without consulting a model or changing any matrix state. */
+export function renderProviderMatrixReport(matrix) {
+    const codeMark = String.fromCharCode(96);
+    const lines = [
+        "# Provider Matrix",
+        "",
+        "Generated by deterministic rules from persisted normalized fact evidence.",
+        "",
+        "## Revision",
+        "",
+        matrix.repositories.length === 0
+            ? "No repository revision was present in the supplied fact artifact."
+            : matrix.repositories
+                .map((repository) => "- " + repository.source + " @ " + codeMark + repository.commitSha + codeMark)
+                .join("\n"),
+        "",
+        "## Metric semantics",
+        "",
+        "| Metric | Numerator | Denominator | Meaning |",
+        "| --- | --- | --- | --- |",
+        ...matrix.metricDefinitions.map((definition) => "| " +
+            escapeMarkdown(definition.id) +
+            " | " +
+            escapeMarkdown(definition.numerator) +
+            " | " +
+            escapeMarkdown(definition.denominator) +
+            " | " +
+            escapeMarkdown(definition.meaning) +
+            " |"),
+        "",
+        "## Provider coverage",
+        "",
+        "| Provider | Raw observed | Normalized | Unsupported | Normalization | Correlated | Ambiguous | Unmatched |",
+        "| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: |",
+        ...matrix.coverage.map((coverage) => "| " +
+            escapeMarkdown(providerLabel(coverage.provider)) +
+            " | " +
+            coverage.rawObservedFactCount +
+            " | " +
+            coverage.normalizedFactCount +
+            " | " +
+            coverage.unsupportedFactCount +
+            " | " +
+            formatRatio(coverage.normalizationCoverage) +
+            " | " +
+            coverage.factCorrelation.correlated +
+            " (" +
+            formatRatio(coverage.factCorrelation.correlatedCoverage) +
+            ") | " +
+            coverage.factCorrelation.ambiguous +
+            " | " +
+            coverage.factCorrelation.unmatched +
+            " |"),
+        "",
+        "### Coverage by normalized fact class",
+        "",
+        "| Provider | Fact class | Raw | Normalized | Unsupported | Correlated | Unique logical facts | Unique coverage |",
+        "| --- | --- | ---: | ---: | ---: | ---: | ---: | ---: |",
+        ...matrix.coverage.flatMap((coverage) => coverage.factClasses.map((item) => "| " +
+            escapeMarkdown(providerLabel(coverage.provider)) +
+            " | " +
+            codeMark +
+            escapeMarkdown(item.factClass) +
+            codeMark +
+            " | " +
+            item.rawObservedFactCount +
+            " | " +
+            item.normalizedFactCount +
+            " | " +
+            item.unsupportedFactCount +
+            " | " +
+            item.factCorrelation.correlated +
+            " (" +
+            formatRatio(item.factCorrelation.correlatedCoverage) +
+            ") | " +
+            item.uniqueFactCount +
+            " | " +
+            formatRatio(item.uniqueCoverage) +
+            " |")),
+        "",
+        "## Unique information and incremental gain",
+        "",
+        "Unique means a comparable logical fact key observed by exactly one provider; it is not a quality ranking.",
+        "",
+        "| Added provider | Existing set | New comparable facts | Gain coverage | Unique comparable facts | Ambiguous | Unmatched | Unsupported |",
+        "| --- | --- | ---: | ---: | ---: | ---: | ---: | ---: |",
+        ...matrix.informationGain.map((gain) => "| " +
+            escapeMarkdown(providerLabel(gain.provider)) +
+            " | " +
+            (gain.existingProviders.length === 0
+                ? "∅"
+                : gain.existingProviders.map(providerLabel).map(escapeMarkdown).join(", ")) +
+            " | " +
+            gain.newComparableFactCount +
+            " | " +
+            formatRatio(gain.informationGainCoverage) +
+            " | " +
+            gain.uniqueFactCount +
+            " | " +
+            gain.newAmbiguousFactCount +
+            " | " +
+            gain.newUnmatchedFactCount +
+            " | " +
+            gain.newUnsupportedFactCount +
+            " |"),
+        "",
+        "## Overlap and conflicts",
+        "",
+        ...renderOverlapSummary(matrix),
+        "",
+        "## Incomparable evidence",
+        "",
+        "- Ambiguous correlation rows: " + matrix.unmatched.ambiguous.length,
+        "- Unmatched correlation rows: " + matrix.unmatched.unmatched.length,
+        "- Unsupported predicate rows: " + matrix.unmatched.unsupported.length,
+        "",
+    ];
+    return lines.join("\n") + "\n";
+}
+function renderOverlapSummary(matrix) {
+    const codeMark = String.fromCharCode(96);
+    const lines = [
+        "Exact overlap rows: " + matrix.overlap.facts.length,
+        "Conflict rows: " + matrix.conflicts.length,
+        "",
+        "| Fact class | Provider pair | Exact overlap | Conflicts | Left only | Right only |",
+        "| --- | --- | ---: | ---: | ---: | ---: |",
+    ];
+    for (const pair of matrix.overlap.pairwise) {
+        lines.push("| " +
+            codeMark +
+            escapeMarkdown(pair.factClass) +
+            codeMark +
+            " | " +
+            escapeMarkdown(providerLabel(pair.left) + " / " + providerLabel(pair.right)) +
+            " | " +
+            pair.overlapFactCount +
+            " | " +
+            pair.conflictFactCount +
+            " | " +
+            pair.leftOnlyFactCount +
+            " | " +
+            pair.rightOnlyFactCount +
+            " |");
+    }
+    lines.push("", "### Unique comparable evidence", "");
+    const uniqueCoverage = matrix.coverage.flatMap((coverage) => coverage.factClasses
+        .filter((item) => item.uniqueFactCount > 0)
+        .map((item) => "- " +
+        escapeMarkdown(providerLabel(coverage.provider)) +
+        " / " +
+        codeMark +
+        escapeMarkdown(item.factClass) +
+        codeMark +
+        ": " +
+        item.uniqueFactCount +
+        " logical fact(s)"));
+    lines.push(...(uniqueCoverage.length === 0 ? ["None."] : uniqueCoverage));
+    lines.push("", "### Disagreement details", "");
+    if (matrix.conflicts.length === 0) {
+        lines.push("None.");
+    }
+    else {
+        for (const row of matrix.conflicts) {
+            const subject = row.variants[0]?.subject;
+            const subjectLabel = subject?.canonicalId ?? subject?.nativeId ?? "unknown";
+            const variants = row.variants.map((variant) => {
+                const providers = variant.providers.map(providerLabel).map(escapeMarkdown).join(", ");
+                return providers + " => " + formatMatrixObject(variant.object);
+            });
+            lines.push("- " +
+                codeMark +
+                escapeMarkdown(row.factClass) +
+                codeMark +
+                " subject " +
+                codeMark +
+                escapeMarkdown(subjectLabel) +
+                codeMark +
+                ": " +
+                variants.join("; "));
+        }
+    }
+    return lines;
+}
+function formatMatrixObject(object) {
+    if (object.kind === "value")
+        return JSON.stringify(object.value);
+    return "entity " + (object.entity.canonicalId ?? object.entity.nativeId);
+}
+function providerLabel(provider) {
+    return provider.id + "@" + provider.version;
+}
+function formatRatio(value) {
+    return value.value === null ? value.numerator + "/" + value.denominator + " (n/a)" : value.value.toFixed(3);
+}
+function escapeMarkdown(value) {
+    return value.replaceAll("|", "\\|").replaceAll("\n", " ");
+}
+function projectMatrixEntity(entity) {
+    return {
+        provider: entity.provider,
+        nativeId: entity.nativeId,
+        ...(entity.canonicalId === undefined ? {} : { canonicalId: entity.canonicalId }),
+        candidateCanonicalIds: entity.candidateCanonicalIds,
+    };
+}
+function projectMatrixObject(object) {
+    if (object.kind === "value")
+        return object;
+    return { kind: "entity", entity: projectMatrixEntity(object.entity) };
+}
+function projectMatrixVariant(variant) {
+    return {
+        key: variant.key,
+        factIds: variant.factIds,
+        evidenceIds: variant.evidenceIds,
+        providers: variant.providers,
+        subject: projectMatrixEntity(variant.subject),
+        predicate: variant.predicate,
+        object: projectMatrixObject(variant.object),
+    };
+}
+/**
+ * Projects a row for persistence: `variants[].subject`/`object` are reduced
+ * from full entity copies (kind/path/range) to identity references, since
+ * the full entity is already persisted once per fact in
+ * normalized/facts.json and reachable through `factIds`/`evidenceIds`.
+ */
+function projectMatrixRow(row) {
+    return {
+        key: row.key,
+        logicalKey: row.logicalKey,
+        repository: row.repository,
+        factClass: row.factClass,
+        predicate: row.predicate,
+        state: row.state,
+        comparisonPossible: row.comparisonPossible,
+        correlationStatus: row.correlationStatus,
+        variants: row.variants.map(projectMatrixVariant),
+        providerStates: row.providerStates,
+        observedProviders: row.observedProviders,
+        missingProviders: row.missingProviders,
+    };
+}
+/**
+ * Writes aggregate and sliced machine-readable artifacts plus the report.
+ * The writer performs no provider execution and no normalization.
+ *
+ * `normalized/facts.json` is the source of truth for full fact/evidence
+ * detail. Every persisted row here carries only aggregate counts plus
+ * `factIds`/`evidenceIds`/`canonicalId` references back to it -- no fact
+ * envelope (path/range/provider-native payload) is re-embedded. `matrix.json`
+ * itself omits the full row set and per-state row slices, since those are
+ * exactly what `overlap.json`/`conflicts.json`/`unmatched.json` persist.
+ */
+export async function writeProviderMatrixArtifacts(runRoot, matrix) {
+    const matrixRoot = path.join(runRoot, "matrix");
+    await mkdir(matrixRoot, { recursive: true });
+    const matrixPath = path.join(matrixRoot, "matrix.json");
+    const coveragePath = path.join(matrixRoot, "coverage.json");
+    const overlapPath = path.join(matrixRoot, "overlap.json");
+    const conflictsPath = path.join(matrixRoot, "conflicts.json");
+    const unmatchedPath = path.join(matrixRoot, "unmatched.json");
+    const informationGainPath = path.join(matrixRoot, "information-gain.json");
+    const reportPath = path.join(runRoot, "report.md");
+    const conflictRows = matrix.conflicts.map(projectMatrixRow);
+    const overlapRows = matrix.overlap.facts.map(projectMatrixRow);
+    const unmatchedAmbiguous = matrix.unmatched.ambiguous.map(projectMatrixRow);
+    const unmatchedUnmatched = matrix.unmatched.unmatched.map(projectMatrixRow);
+    const unmatchedUnsupported = matrix.unmatched.unsupported.map(projectMatrixRow);
+    await writeJson(matrixPath, {
+        schemaVersion: matrix.schemaVersion,
+        inputFactSchemaVersion: matrix.inputFactSchemaVersion,
+        generatedBy: matrix.generatedBy,
+        repositories: matrix.repositories,
+        providers: matrix.providers,
+        additionOrder: matrix.additionOrder,
+        metricDefinitions: matrix.metricDefinitions,
+        rowCounts: {
+            total: matrix.facts.length,
+            coverageProviders: matrix.coverage.length,
+            overlapPairwise: matrix.overlap.pairwise.length,
+            overlapAllProviders: matrix.overlap.allProviders.length,
+            overlapFacts: overlapRows.length,
+            conflicts: conflictRows.length,
+            unmatchedAmbiguous: unmatchedAmbiguous.length,
+            unmatchedUnmatched: unmatchedUnmatched.length,
+            unmatchedUnsupported: unmatchedUnsupported.length,
+            informationGain: matrix.informationGain.length,
+        },
+    });
+    await writeJson(coveragePath, {
+        schemaVersion: matrix.schemaVersion,
+        metricDefinitions: matrix.metricDefinitions,
+        repositories: matrix.repositories,
+        providers: matrix.providers,
+        coverage: matrix.coverage,
+    });
+    await writeJson(overlapPath, {
+        schemaVersion: matrix.schemaVersion,
+        metricDefinitions: matrix.metricDefinitions,
+        repositories: matrix.repositories,
+        overlap: {
+            pairwise: matrix.overlap.pairwise,
+            allProviders: matrix.overlap.allProviders,
+            facts: overlapRows,
+        },
+    });
+    await writeJson(conflictsPath, {
+        schemaVersion: matrix.schemaVersion,
+        metricDefinitions: matrix.metricDefinitions,
+        repositories: matrix.repositories,
+        conflicts: conflictRows,
+    });
+    await writeJson(unmatchedPath, {
+        schemaVersion: matrix.schemaVersion,
+        metricDefinitions: matrix.metricDefinitions,
+        repositories: matrix.repositories,
+        // `records` (ambiguous+unmatched+unsupported combined) is omitted: it
+        // duplicated the three arrays above in full. A reader that needs the
+        // combined set concatenates them; each row already carries `state`.
+        unmatched: {
+            ambiguous: unmatchedAmbiguous,
+            unmatched: unmatchedUnmatched,
+            unsupported: unmatchedUnsupported,
+        },
+    });
+    await writeJson(informationGainPath, {
+        schemaVersion: matrix.schemaVersion,
+        metricDefinitions: matrix.metricDefinitions,
+        repositories: matrix.repositories,
+        additionOrder: matrix.additionOrder,
+        informationGain: matrix.informationGain,
+    });
+    await writeFile(reportPath, renderProviderMatrixReport(matrix), "utf8");
+    return {
+        matrixPath,
+        coveragePath,
+        overlapPath,
+        conflictsPath,
+        unmatchedPath,
+        informationGainPath,
+        reportPath,
+    };
+}
+/** Builds then persists a matrix, accepting either normalized facts or a matrix. */
+export async function writeProviderMatrix(runRoot, input, options = {}) {
+    const matrix = isProviderMatrix(input) ? input : buildProviderMatrix(input, options);
+    return writeProviderMatrixArtifacts(runRoot, matrix);
+}
+/** Persists the exact normalized artifact consumed by the matrix builder. */
+export async function writeNormalizedFactsArtifact(filePath, input) {
+    await mkdir(path.dirname(filePath), { recursive: true });
+    const handle = await open(filePath, "w");
+    const writer = new JsonArtifactWriter(handle);
+    try {
+        await writer.write(`{"schemaVersion":${FACT_SCHEMA_VERSION},"facts":`);
+        await writer.writeArray(input.facts, persistFactEnvelope);
+        await writer.write(`,"unsupported":`);
+        await writer.writeArray(input.unsupported, persistUnsupportedEvidence);
+        await writer.write(`,"correlation":`);
+        await writer.writeValue(input.correlation);
+        await writer.write("}\n");
+        await writer.flush();
+    }
+    finally {
+        await handle.close();
+    }
+    return filePath;
+}
+/**
+ * The in-memory envelope carries the provider-native payload in three
+ * places (`providerNative`, `nativeEvidence.providerNative`, and
+ * `nativeEvidence.observation.providerNative`). Persisting all three
+ * verbatim would triple the artifact's size for no benefit, so the payload
+ * is retained once under `nativeEvidence.providerNative` and the other two
+ * locations become `$ref` pointers that `resolveNativeEvidenceRefs` (used by
+ * `readNormalizedFactsArtifact`) expands back on read.
+ */
+function persistFactEnvelope(fact) {
+    const reference = nativeEvidenceRef(fact.nativeEvidence.id);
+    return {
+        ...fact,
+        providerNative: reference,
+        nativeEvidence: {
+            ...fact.nativeEvidence,
+            observation: { ...fact.nativeEvidence.observation, providerNative: reference },
+        },
+    };
+}
+function persistUnsupportedEvidence(evidence) {
+    const reference = nativeEvidenceRef(evidence.nativeEvidence.id);
+    return {
+        ...evidence,
+        providerNative: reference,
+        nativeEvidence: {
+            ...evidence.nativeEvidence,
+            observation: { ...evidence.nativeEvidence.observation, providerNative: reference },
+        },
+    };
+}
+function nativeEvidenceRef(nativeEvidenceId) {
+    return { $ref: `nativeEvidence:${nativeEvidenceId}/providerNative` };
+}
+const NATIVE_EVIDENCE_REF_PATTERN = /^nativeEvidence:(.+)\/providerNative$/u;
+/**
+ * Resolves every `$ref` produced by `persistFactEnvelope`/`persistUnsupportedEvidence`
+ * back to the retained `nativeEvidence.providerNative` payload, so a reader
+ * of the persisted artifact recovers the exact in-memory envelope shape.
+ */
+function resolveNativeEvidenceRefs(record) {
+    const byId = new Map();
+    for (const item of [...record.facts, ...record.unsupported]) {
+        const entry = asRecord(item);
+        const nativeEvidence = entry === undefined ? undefined : asRecord(entry.nativeEvidence);
+        const id = nativeEvidence?.id;
+        if (typeof id === "string" && nativeEvidence !== undefined)
+            byId.set(id, nativeEvidence.providerNative);
+    }
+    const resolve = (value) => {
+        const record = asRecord(value);
+        const ref = typeof record?.$ref === "string" ? NATIVE_EVIDENCE_REF_PATTERN.exec(record.$ref) : null;
+        if (ref === null)
+            return value;
+        const target = byId.get(ref[1]);
+        return target === undefined ? value : target;
+    };
+    for (const item of [...record.facts, ...record.unsupported]) {
+        const entry = asRecord(item);
+        if (entry === undefined)
+            continue;
+        entry.providerNative = resolve(entry.providerNative);
+        const nativeEvidence = asRecord(entry.nativeEvidence);
+        if (nativeEvidence === undefined)
+            continue;
+        const observation = asRecord(nativeEvidence.observation);
+        if (observation !== undefined)
+            observation.providerNative = resolve(observation.providerNative);
+    }
+}
+/**
+ * Reads a persisted #11 normalized-facts artifact without running providers.
+ *
+ * Mottainai-scale artifacts exceed V8's ~1GB single-string limit, so this
+ * never materializes the whole file as one string (unlike `JSON.parse(await
+ * readFile(filePath, "utf8"))`). It streams the file in chunks and parses
+ * each top-level array element (`facts[i]`, `unsupported[i]`) as its own
+ * JSON string instead, relying on the fixed top-level key order
+ * (`schemaVersion`, `facts`, `unsupported`, `correlation`) that
+ * `writeNormalizedFactsArtifact` always writes.
+ */
+export async function readNormalizedFactsArtifact(filePath) {
+    const reader = new StreamingNormalizedFactsReader(filePath);
+    const result = await reader.read();
+    resolveNativeEvidenceRefs({ facts: result.facts, unsupported: result.unsupported });
+    return result;
+}
+/**
+ * Minimal streaming reader for the fixed shape `writeNormalizedFactsArtifact`
+ * produces. It reads the file in fixed-size chunks and only ever holds one
+ * top-level array element's text in memory at a time, so total file size is
+ * not bounded by V8's single-string length limit.
+ */
+class StreamingNormalizedFactsReader {
+    filePath;
+    buffer = "";
+    position = 0;
+    handle;
+    eof = false;
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    async read() {
+        this.handle = await open(this.filePath, "r");
+        try {
+            await this.expectLiteral("{");
+            await this.expectKey("schemaVersion");
+            const schemaVersion = await this.readJsonScalarUntil(new Set([",", "}"]));
+            if (schemaVersion !== FACT_SCHEMA_VERSION) {
+                throw new Error("normalized fact artifact schemaVersion must be " + FACT_SCHEMA_VERSION);
+            }
+            await this.expectSeparatorThenKey("facts");
+            const facts = await this.readJsonArray();
+            await this.expectSeparatorThenKey("unsupported");
+            const unsupported = await this.readJsonArray();
+            await this.expectSeparatorThenKey("correlation");
+            const correlation = await this.readJsonValueUntil(new Set([",", "}"]));
+            if (!isRecord(correlation))
+                throw new Error("normalized fact artifact correlation must be an object");
+            return {
+                schemaVersion,
+                facts: facts,
+                unsupported: unsupported,
+                correlation: correlation,
+            };
+        }
+        finally {
+            await this.handle.close();
+        }
+    }
+    async fill() {
+        if (this.eof || this.handle === undefined)
+            return;
+        const chunkSize = 1024 * 1024;
+        const chunk = Buffer.alloc(chunkSize);
+        const { bytesRead } = await this.handle.read(chunk, 0, chunkSize, null);
+        if (bytesRead === 0) {
+            this.eof = true;
+            return;
+        }
+        this.buffer += chunk.toString("utf8", 0, bytesRead);
+    }
+    async ensure(count) {
+        while (this.buffer.length - this.position < count && !this.eof)
+            await this.fill();
+    }
+    async peek() {
+        await this.ensure(1);
+        return this.buffer[this.position];
+    }
+    compact() {
+        if (this.position > 4 * 1024 * 1024) {
+            const trimmed = this.position;
+            this.buffer = this.buffer.slice(this.position);
+            this.position = 0;
+            return trimmed;
+        }
+        return 0;
+    }
+    async skipWhitespace() {
+        for (;;) {
+            const char = await this.peek();
+            if (char === undefined || !/\s/u.test(char))
+                return;
+            this.position += 1;
+            this.compact();
+        }
+    }
+    async expectLiteral(literal) {
+        await this.skipWhitespace();
+        await this.ensure(literal.length);
+        if (this.buffer.slice(this.position, this.position + literal.length) !== literal) {
+            throw new Error("normalized fact artifact malformed near byte " + this.position);
+        }
+        this.position += literal.length;
+        this.compact();
+    }
+    async expectKey(key) {
+        await this.expectLiteral(JSON.stringify(key));
+        await this.expectLiteral(":");
+    }
+    async expectSeparatorThenKey(key) {
+        await this.expectLiteral(",");
+        await this.expectKey(key);
+    }
+    /** Reads raw JSON text up to (not including) the first unnested delimiter, then parses it. */
+    async readJsonValueUntil(delimiters) {
+        const text = await this.readRawJsonUntil(delimiters);
+        return JSON.parse(text);
+    }
+    async readJsonScalarUntil(delimiters) {
+        const value = await this.readJsonValueUntil(delimiters);
+        if (typeof value !== "number")
+            throw new Error("normalized fact artifact expected a numeric field");
+        return value;
+    }
+    /** Reads raw top-level JSON text (object/array/scalar) up to an unnested delimiter, without consuming it. */
+    async readRawJsonUntil(delimiters) {
+        await this.skipWhitespace();
+        let depth = 0;
+        let inString = false;
+        let escaped = false;
+        let start = this.position;
+        let text = "";
+        for (;;) {
+            const char = await this.peek();
+            if (char === undefined)
+                throw new Error("normalized fact artifact ended unexpectedly");
+            if (inString) {
+                if (escaped) {
+                    escaped = false;
+                }
+                else if (char === "\\") {
+                    escaped = true;
+                }
+                else if (char === '"') {
+                    inString = false;
+                }
+            }
+            else if (char === '"') {
+                inString = true;
+            }
+            else if (depth === 0 && delimiters.has(char)) {
+                text += this.buffer.slice(start, this.position);
+                return text;
+            }
+            else if (char === "{" || char === "[") {
+                depth += 1;
+            }
+            else if (char === "}" || char === "]") {
+                depth -= 1;
+            }
+            this.position += 1;
+            if (this.buffer.length - this.position < 2 && !this.eof) {
+                text += this.buffer.slice(start, this.position);
+                await this.fill();
+                start = this.position;
+            }
+            const trimmed = this.compact();
+            start -= trimmed;
+            if (this.position < start)
+                start = this.position;
+        }
+    }
+    /** Streams a top-level JSON array, parsing one element at a time. */
+    async readJsonArray() {
+        await this.expectLiteral("[");
+        const values = [];
+        await this.skipWhitespace();
+        if ((await this.peek()) === "]") {
+            this.position += 1;
+            this.compact();
+            return values;
+        }
+        for (;;) {
+            const text = await this.readRawJsonUntil(new Set([",", "]"]));
+            values.push(JSON.parse(text));
+            await this.skipWhitespace();
+            const delimiter = await this.peek();
+            this.position += 1;
+            this.compact();
+            if (delimiter === "]")
+                return values;
+            if (delimiter !== ",")
+                throw new Error("normalized fact artifact malformed array near byte " + this.position);
+        }
+    }
+}
+/** Reads a persisted normalized artifact and generates its deterministic matrix. */
+export async function buildProviderMatrixFromArtifact(filePath, options = {}) {
+    return buildProviderMatrix(await readNormalizedFactsArtifact(filePath), options);
+}
+function isProviderMatrix(value) {
+    return isRecord(value) && value.schemaVersion === PROVIDER_MATRIX_SCHEMA_VERSION && "metricDefinitions" in value;
+}
+/**
+ * Streams a value to disk through `JsonArtifactWriter` instead of building
+ * one `JSON.stringify(value)` string first. Exported so every large
+ * generated artifact (not just the ones matrix.ts itself writes) can avoid
+ * the same V8 string-length limit.
+ */
+export async function writeStreamingJson(filePath, value) {
+    await mkdir(path.dirname(filePath), { recursive: true });
+    const handle = await open(filePath, "w");
+    const writer = new JsonArtifactWriter(handle);
+    try {
+        await writer.writeValue(value);
+        await writer.write("\n");
+        await writer.flush();
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function writeJson(filePath, value) {
+    await writeStreamingJson(filePath, value);
+}
+/**
+ * Serializes large generated artifacts without first constructing one giant
+ * JSON string. Mottainai's TypeScript observation set is large enough for a
+ * single JSON.stringify(matrix) call to exceed V8's string limit.
+ */
+export class JsonArtifactWriter {
+    handle;
+    buffer = "";
+    constructor(handle) {
+        this.handle = handle;
+    }
+    async write(value) {
+        this.buffer += value;
+        if (this.buffer.length >= 1024 * 1024)
+            await this.flush();
+    }
+    async flush() {
+        if (this.buffer.length === 0)
+            return;
+        await this.handle.write(this.buffer);
+        this.buffer = "";
+    }
+    /**
+     * Streams a possibly-large array by transforming and serializing one
+     * element at a time, so the whole transformed array is never held in
+     * memory at once (unlike `writeValue(values.map(transform))`).
+     */
+    async writeArray(values, transform) {
+        await this.write("[");
+        for (let index = 0; index < values.length; index += 1) {
+            if (index > 0)
+                await this.write(",");
+            await this.writeValue(transform(values[index]));
+        }
+        await this.write("]");
+    }
+    async writeValue(value) {
+        if (value === null) {
+            await this.write("null");
+            return;
+        }
+        if (Array.isArray(value)) {
+            await this.write("[");
+            for (let index = 0; index < value.length; index += 1) {
+                if (index > 0)
+                    await this.write(",");
+                await this.writeValue(value[index]);
+            }
+            await this.write("]");
+            return;
+        }
+        if (typeof value === "object") {
+            const record = value;
+            await this.write("{");
+            let first = true;
+            for (const key of Object.keys(record)) {
+                if (record[key] === undefined)
+                    continue;
+                if (!first)
+                    await this.write(",");
+                first = false;
+                await this.write(JSON.stringify(key));
+                await this.write(":");
+                await this.writeValue(record[key]);
+            }
+            await this.write("}");
+            return;
+        }
+        const serialized = JSON.stringify(value);
+        await this.write(serialized === undefined ? "null" : serialized);
+    }
+}
+function asRecord(value) {
+    return isRecord(value) ? value : undefined;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=matrix.js.map