wabachi 0.1.0

package/dist/runtime/fixtureProvider.js

@@ -0,0 +1,30 @@
+import { readdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+/**
+ * Minimal deterministic provider used to exercise the provider contract in
+ * tests and as a template for future concrete providers. It writes one raw
+ * artifact listing the workspace's top-level entries.
+ */
+export function createFixtureProvider(options = {}) {
+    const id = options.id ?? "fixture";
+    const available = options.available ?? true;
+    return {
+        identity: { id, version: "0.0.1", determinism: "deterministic" },
+        async isAvailable() {
+            return available;
+        },
+        async execute(context) {
+            const startedAt = new Date().toISOString();
+            const entries = await readdir(context.workspaceRoot);
+            const artifactRelativePath = "entries.json";
+            await writeFile(path.join(context.artifactRoot, artifactRelativePath), `${JSON.stringify({ entries }, null, 2)}\n`, "utf8");
+            return {
+                status: "ok",
+                artifacts: [artifactRelativePath],
+                startedAt,
+                finishedAt: new Date().toISOString(),
+            };
+        },
+    };
+}
+//# sourceMappingURL=fixtureProvider.js.map

package/dist/runtime/fixtureProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixtureProvider.js","sourceRoot":"","sources":["../../src/runtime/fixtureProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,IAAI,MAAM,WAAW,CAAC;AAG7B;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,UAAkE,EAAE;IACxG,MAAM,EAAE,GAAG,OAAO,CAAC,EAAE,IAAI,SAAS,CAAC;IACnC,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,IAAI,CAAC;IAE5C,OAAO;QACL,QAAQ,EAAE,EAAE,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE;QAChE,KAAK,CAAC,WAAW;YACf,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,KAAK,CAAC,OAAO,CAAC,OAAwB;YACpC,MAAM,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;YAC3C,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;YAErD,MAAM,oBAAoB,GAAG,cAAc,CAAC;YAC5C,MAAM,SAAS,CACb,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,oBAAoB,CAAC,EACrD,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAC3C,MAAM,CACP,CAAC;YAEF,OAAO;gBACL,MAAM,EAAE,IAAI;gBACZ,SAAS,EAAE,CAAC,oBAAoB,CAAC;gBACjC,SAAS;gBACT,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;aACrC,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/runtime/graftProvider.d.ts

@@ -0,0 +1,8 @@
+import type { Provider } from "./provider.js";
+export interface GraftProviderOptions {
+    /** Override the `graft` executable, e.g. for tests that stub the CLI. */
+    readonly binary?: string;
+    /** File extensions passed through to `graft build --extensions`. */
+    readonly extensions?: readonly string[];
+}
+export declare function createGraftProvider(options?: GraftProviderOptions): Provider;

package/dist/runtime/graftProvider.js

@@ -0,0 +1,107 @@
+import { execFile } from "node:child_process";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+import { OBSERVATION_SCHEMA_VERSION } from "./observation.js";
+const execFileAsync = promisify(execFile);
+/**
+ * Deterministic structural relations `graft build` (without `--deep`) can
+ * emit that map onto a common observation predicate. Any edge relation not
+ * listed here has no safe common predicate and is only preserved as raw,
+ * provider-native evidence in wiring.json rather than forced into the
+ * common envelope.
+ */
+const RELATION_TO_PREDICATE = {
+    calls: "calls",
+    imports: "imports",
+    extends: "extends",
+    implements: "implements",
+    references: "references",
+};
+const GRAFT_BINARY = "graft";
+export function createGraftProvider(options = {}) {
+    const binary = options.binary ?? GRAFT_BINARY;
+    let resolvedVersion = "unknown";
+    return {
+        get identity() {
+            return { id: "graft", version: resolvedVersion, determinism: "deterministic" };
+        },
+        async isAvailable(_context) {
+            try {
+                resolvedVersion = await resolveVersion(binary);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        async execute(context) {
+            const startedAt = new Date().toISOString();
+            const graftDir = path.join(context.artifactRoot, "graft");
+            const buildArgs = ["build", context.workspaceRoot, "--dir", graftDir];
+            if (options.extensions && options.extensions.length > 0) {
+                buildArgs.push("--extensions", ...options.extensions);
+            }
+            resolvedVersion = await resolveVersion(binary);
+            const version = resolvedVersion;
+            const invocation = { binary, args: buildArgs, version, deep: false };
+            const invocationRelativePath = "invocation.json";
+            await writeFile(path.join(context.artifactRoot, invocationRelativePath), `${JSON.stringify(invocation, null, 2)}\n`, "utf8");
+            await mkdir(graftDir, { recursive: true });
+            await execFileAsync(binary, buildArgs);
+            const wiringRelativePath = "graft/.graph/wiring.json";
+            const wiring = JSON.parse(await readFile(path.join(context.artifactRoot, wiringRelativePath), "utf8"));
+            const identity = { id: "graft", version, determinism: "deterministic" };
+            const observations = adaptWiringGraph(wiring, identity, context);
+            const observationsRelativePath = "observations.json";
+            await writeFile(path.join(context.artifactRoot, observationsRelativePath), `${JSON.stringify(observations, null, 2)}\n`, "utf8");
+            return {
+                status: "ok",
+                artifacts: [invocationRelativePath, wiringRelativePath, observationsRelativePath],
+                observationArtifacts: [observationsRelativePath],
+                startedAt,
+                finishedAt: new Date().toISOString(),
+            };
+        },
+    };
+}
+async function resolveVersion(binary) {
+    const { stdout } = await execFileAsync(binary, ["--version"]);
+    return stdout.trim();
+}
+/**
+ * Adapts Graft's wiring graph into the common observation envelope where a
+ * safe predicate mapping exists. Nodes/edges without a safe mapping (e.g.
+ * the file-contains-symbol structural edge, or any future Graft-specific
+ * relation) are not force-normalized — they remain available only in the
+ * raw wiring.json artifact retained alongside these observations.
+ */
+function adaptWiringGraph(wiring, provider, context) {
+    const nodesById = new Map(wiring.nodes.map((node) => [node.id, node]));
+    const observations = [];
+    for (const edge of wiring.edges) {
+        const predicate = RELATION_TO_PREDICATE[edge.relation];
+        if (!predicate)
+            continue;
+        const sourceNode = nodesById.get(edge.source);
+        const targetNode = nodesById.get(edge.target);
+        if (!sourceNode || !targetNode)
+            continue;
+        observations.push(toObservation(edge, sourceNode, targetNode, predicate, provider, context));
+    }
+    return observations;
+}
+function toObservation(edge, sourceNode, targetNode, predicate, provider, context) {
+    return {
+        schemaVersion: OBSERVATION_SCHEMA_VERSION,
+        subject: { id: sourceNode.id, kind: sourceNode.kind },
+        predicate,
+        object: { id: targetNode.id, kind: targetNode.kind },
+        provider,
+        repository: context.repository,
+        source: { path: sourceNode.path, span: sourceNode.span ?? undefined },
+        determinism: "deterministic",
+        providerNative: { node: sourceNode, sourceNode, targetNode, edge },
+    };
+}
+//# sourceMappingURL=graftProvider.js.map

package/dist/runtime/graftProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graftProvider.js","sourceRoot":"","sources":["../../src/runtime/graftProvider.ts"],"names":[],"mappings":"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"}

package/dist/runtime/graftWiring.d.ts

@@ -0,0 +1,30 @@
+/** Shape of graft/.graph/wiring.json as produced by `graft build` (deterministic, non-`--deep` mode). */
+export interface GraftWiringNode {
+    readonly id: string;
+    readonly name: string;
+    readonly kind: string;
+    readonly path: string;
+    readonly span: string | null;
+    readonly signature: string | null;
+    readonly exported: boolean;
+    readonly origin: string;
+    readonly [key: string]: unknown;
+}
+export interface GraftWiringEdge {
+    readonly source: string;
+    readonly target: string;
+    readonly relation: string;
+    readonly confidence: string;
+    readonly [key: string]: unknown;
+}
+export interface GraftWiringGraph {
+    readonly meta: {
+        readonly version: number;
+        readonly nodeCount: number;
+        readonly edgeCount: number;
+        readonly languages: readonly string[];
+        readonly [key: string]: unknown;
+    };
+    readonly nodes: readonly GraftWiringNode[];
+    readonly edges: readonly GraftWiringEdge[];
+}

package/dist/runtime/graftWiring.js

@@ -0,0 +1,3 @@
+/** Shape of graft/.graph/wiring.json as produced by `graft build` (deterministic, non-`--deep` mode). */
+export {};
+//# sourceMappingURL=graftWiring.js.map

package/dist/runtime/graftWiring.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graftWiring.js","sourceRoot":"","sources":["../../src/runtime/graftWiring.ts"],"names":[],"mappings":"AAAA,yGAAyG"}

package/dist/runtime/manifest.d.ts

@@ -0,0 +1,17 @@
+import type { ProviderExecutionResult, ProviderIdentity, ResolvedRepository } from "./provider.js";
+export interface ManifestProviderEntry {
+    readonly identity: ProviderIdentity;
+    readonly result: ProviderExecutionResult;
+}
+export interface RunManifest {
+    readonly runId: string;
+    readonly repository: ResolvedRepository;
+    readonly startedAt: string;
+    readonly finishedAt: string;
+    /** Runtime and command-line tool versions used by the experiment. */
+    readonly toolchain: Readonly<Record<string, string>>;
+    readonly providers: readonly ManifestProviderEntry[];
+}
+/** Collects versions that are outside an individual provider identity. */
+export declare function collectToolchainVersions(): Promise<Readonly<Record<string, string>>>;
+export declare function writeManifest(runRoot: string, manifest: RunManifest): Promise<string>;

package/dist/runtime/manifest.js

@@ -0,0 +1,39 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { execFile } from "node:child_process";
+import path from "node:path";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+/** Collects versions that are outside an individual provider identity. */
+export async function collectToolchainVersions() {
+    const versions = {
+        node: process.version,
+        platform: `${process.platform}/${process.arch}`,
+    };
+    for (const [name, command, args] of [
+        ["git", "git", ["--version"]],
+        ["pnpm", "pnpm", ["--version"]],
+        ["tar", "tar", ["--version"]],
+        ["graft", "graft", ["--version"]],
+    ]) {
+        versions[name] = await commandVersion(command, args);
+    }
+    versions.tsx = await commandVersion("pnpm", ["exec", "tsx", "--version"], process.cwd());
+    return versions;
+}
+async function commandVersion(command, args, cwd) {
+    try {
+        const options = { encoding: "utf8", ...(cwd === undefined ? {} : { cwd }) };
+        const { stdout } = await execFileAsync(command, [...args], options);
+        return stdout.trim().split("\n")[0] ?? "unknown";
+    }
+    catch {
+        return "unavailable";
+    }
+}
+export async function writeManifest(runRoot, manifest) {
+    await mkdir(runRoot, { recursive: true });
+    const manifestPath = path.join(runRoot, "manifest.json");
+    await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+    return manifestPath;
+}
+//# sourceMappingURL=manifest.js.map

package/dist/runtime/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../../src/runtime/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAGtC,MAAM,aAAa,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AAiB1C,0EAA0E;AAC1E,MAAM,CAAC,KAAK,UAAU,wBAAwB;IAC5C,MAAM,QAAQ,GAA2B;QACvC,IAAI,EAAE,OAAO,CAAC,OAAO;QACrB,QAAQ,EAAE,GAAG,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,IAAI,EAAE;KAChD,CAAC;IACF,KAAK,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,IAAI;QAClC,CAAC,KAAK,EAAE,KAAK,EAAE,CAAC,WAAW,CAAC,CAAC;QAC7B,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,WAAW,CAAC,CAAC;QAC/B,CAAC,KAAK,EAAE,KAAK,EAAE,CAAC,WAAW,CAAC,CAAC;QAC7B,CAAC,OAAO,EAAE,OAAO,EAAE,CAAC,WAAW,CAAC,CAAC;KACzB,EAAE,CAAC;QACX,QAAQ,CAAC,IAAI,CAAC,GAAG,MAAM,cAAc,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACvD,CAAC;IACD,QAAQ,CAAC,GAAG,GAAG,MAAM,cAAc,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,WAAW,CAAC,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IACzF,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,KAAK,UAAU,cAAc,CAAC,OAAe,EAAE,IAAuB,EAAE,GAAY;IAClF,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,EAAE,QAAQ,EAAE,MAAe,EAAE,GAAG,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC;QACrF,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,aAAa,CAAC,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC;QACpE,OAAO,MAAM,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,SAAS,CAAC;IACnD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,aAAa,CAAC;IACvB,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,OAAe,EAAE,QAAqB;IACxE,MAAM,KAAK,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1C,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC;IACzD,MAAM,SAAS,CAAC,YAAY,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAChF,OAAO,YAAY,CAAC;AACtB,CAAC"}

package/dist/runtime/matrix.d.ts

@@ -0,0 +1,337 @@
+import { open } from "node:fs/promises";
+import { FACT_SCHEMA_VERSION, type FactEnvelope, type FactComparison, type FactNormalizationResult, type UnsupportedProviderEvidence } from "./facts.js";
+import type { CorrelationResult, CorrelationStatus, NormalizedSourceRange } from "./correlation.js";
+import type { ProviderIdentity, ResolvedRepository } from "./provider.js";
+/** Version of the deterministic Provider Matrix artifact. */
+export declare const PROVIDER_MATRIX_SCHEMA_VERSION: 1;
+export type ProviderMatrixSchemaVersion = typeof PROVIDER_MATRIX_SCHEMA_VERSION;
+/**
+ * A matrix state describes the comparison result, not provider quality.
+ * Correlation status is retained separately on every fact row.
+ */
+export type MatrixFactState = "overlap" | "provider-only" | "conflict" | "unsupported" | "ambiguous" | "unmatched";
+export type MatrixProviderFactState = "present" | "missing" | "unsupported" | "ambiguous" | "unmatched";
+export interface MatrixMetricDefinition {
+    readonly id: string;
+    readonly numerator: string;
+    readonly denominator: string;
+    readonly meaning: string;
+}
+export interface MatrixRatio {
+    readonly numerator: number;
+    readonly denominator: number;
+    /** Null means the denominator is zero and the metric is not applicable. */
+    readonly value: number | null;
+}
+export interface NormalizedFactsArtifact {
+    readonly schemaVersion: typeof FACT_SCHEMA_VERSION;
+    readonly facts: readonly FactEnvelope[];
+    readonly unsupported: readonly UnsupportedProviderEvidence[];
+    readonly correlation: CorrelationResult;
+    /** Optional original #11 comparison projection, retained when persisted. */
+    readonly comparisons?: readonly FactComparison[];
+}
+export interface ProviderMatrixOptions {
+    /**
+     * Providers expected in the matrix, including providers with no facts.
+     * When omitted, providers are collected from facts, unsupported evidence,
+     * correlation metrics, and then sorted by identity.
+     */
+    readonly providers?: readonly ProviderIdentity[];
+    /**
+     * Explicit order for the incremental information-gain experiment. If
+     * omitted, the canonical provider identity order is used.
+     */
+    readonly additionOrder?: readonly ProviderIdentity[];
+}
+export interface MatrixEntityReference {
+    readonly provider: ProviderIdentity;
+    readonly nativeId: string;
+    readonly kind: string;
+    readonly canonicalId?: string;
+    readonly candidateCanonicalIds: readonly string[];
+    readonly correlationStatus: CorrelationStatus;
+    readonly path?: string;
+    readonly range?: NormalizedSourceRange;
+}
+export type MatrixFactObject = {
+    readonly kind: "entity";
+    readonly entity: MatrixEntityReference;
+} | {
+    readonly kind: "value";
+    readonly value: string;
+};
+export interface MatrixFactVariant {
+    /** Exact normalized fact identity, or an evidence identity for unsupported records. */
+    readonly key: string;
+    readonly factIds: readonly string[];
+    readonly evidenceIds: readonly string[];
+    readonly providers: readonly ProviderIdentity[];
+    readonly subject: MatrixEntityReference;
+    readonly predicate: string;
+    readonly object: MatrixFactObject;
+}
+export interface MatrixProviderFactStatus {
+    readonly provider: ProviderIdentity;
+    readonly state: MatrixProviderFactState;
+    readonly factIds: readonly string[];
+    readonly evidenceIds: readonly string[];
+}
+export interface MatrixFactRecord {
+    /** Stable row identity. */
+    readonly key: string;
+    /** Stable comparable subject/predicate identity when correlation permits it. */
+    readonly logicalKey: string;
+    readonly repository: ResolvedRepository;
+    readonly factClass: string;
+    readonly predicate: string;
+    readonly state: MatrixFactState;
+    readonly comparisonPossible: boolean;
+    readonly correlationStatus: CorrelationStatus | "not-applicable";
+    readonly variants: readonly MatrixFactVariant[];
+    /** Includes an explicit missing state for every expected provider. */
+    readonly providerStates: readonly MatrixProviderFactStatus[];
+    readonly observedProviders: readonly ProviderIdentity[];
+    readonly missingProviders: readonly ProviderIdentity[];
+}
+export interface MatrixFactCorrelationCounts {
+    readonly matched: number;
+    readonly probable: number;
+    readonly correlated: number;
+    readonly ambiguous: number;
+    readonly unmatched: number;
+    readonly matchedCoverage: MatrixRatio;
+    readonly correlatedCoverage: MatrixRatio;
+}
+export interface MatrixEntityCorrelationCounts {
+    readonly total: number;
+    readonly matched: number;
+    readonly probable: number;
+    readonly correlated: number;
+    readonly ambiguous: number;
+    readonly unmatched: number;
+    readonly matchedCoverage: MatrixRatio;
+    readonly correlatedCoverage: MatrixRatio;
+}
+export interface FactClassCoverage {
+    readonly factClass: string;
+    /** Fact records plus unsupported provider evidence records. */
+    readonly rawObservedFactCount: number;
+    readonly normalizedFactCount: number;
+    readonly unsupportedFactCount: number;
+    readonly factCorrelation: MatrixFactCorrelationCounts;
+    readonly normalizationCoverage: MatrixRatio;
+    readonly uniqueFactCount: number;
+    readonly uniqueCoverage: MatrixRatio;
+    /** Distinct comparable logical fact keys observed by this provider only. */
+    readonly uniqueFactKeys: readonly string[];
+}
+export interface ProviderCoverage extends FactClassCoverage {
+    readonly provider: ProviderIdentity;
+    readonly factClasses: readonly FactClassCoverage[];
+    readonly entityCorrelation: MatrixEntityCorrelationCounts;
+}
+export interface PairwiseOverlap {
+    readonly left: ProviderIdentity;
+    readonly right: ProviderIdentity;
+    readonly factClass: string;
+    readonly leftComparableFactCount: number;
+    readonly rightComparableFactCount: number;
+    readonly comparedLogicalFactCount: number;
+    /** Distinct exact comparable fact keys observed by both providers. */
+    readonly overlapFactCount: number;
+    /** Logical keys observed only by the left/right provider. */
+    readonly leftOnlyFactCount: number;
+    readonly rightOnlyFactCount: number;
+    /** Logical keys where the two providers expose different exact values/relations. */
+    readonly conflictFactCount: number;
+    readonly overlapCoverage: MatrixRatio;
+    readonly overlapFactKeys: readonly string[];
+    readonly conflictLogicalKeys: readonly string[];
+}
+export interface AllProviderOverlap {
+    readonly factClass: string;
+    readonly providers: readonly ProviderIdentity[];
+    readonly providerCount: number;
+    readonly comparableFactUnionCount: number;
+    /** Distinct exact comparable fact keys present for every selected provider. */
+    readonly allProviderOverlapFactCount: number;
+    readonly allProviderOverlapCoverage: MatrixRatio;
+    readonly overlapFactKeys: readonly string[];
+}
+export interface ProviderMatrixOverlap {
+    readonly pairwise: readonly PairwiseOverlap[];
+    readonly allProviders: readonly AllProviderOverlap[];
+    readonly facts: readonly MatrixFactRecord[];
+}
+export interface ProviderMatrixUnmatched {
+    /** Rows whose entity correlation has competing candidates. */
+    readonly ambiguous: readonly MatrixFactRecord[];
+    /** Rows with no canonical entity identity. */
+    readonly unmatched: readonly MatrixFactRecord[];
+    /** Rows retained because the predicate has no normalized mapping. */
+    readonly unsupported: readonly MatrixFactRecord[];
+    readonly records: readonly MatrixFactRecord[];
+}
+export interface InformationGainClassCount {
+    readonly factClass: string;
+    readonly newComparableFactCount: number;
+    readonly newComparableFactKeys: readonly string[];
+}
+export interface InformationGain {
+    readonly provider: ProviderIdentity;
+    /** Providers already present when this provider is added. */
+    readonly existingProviders: readonly ProviderIdentity[];
+    readonly newComparableFactCount: number;
+    readonly newComparableFactKeys: readonly string[];
+    readonly newFactClasses: readonly InformationGainClassCount[];
+    readonly uniqueFactCount: number;
+    readonly uniqueFactKeys: readonly string[];
+    readonly informationGainCoverage: MatrixRatio;
+    readonly newUnsupportedFactCount: number;
+    readonly newUnsupportedEvidenceIds: readonly string[];
+    readonly newAmbiguousFactCount: number;
+    readonly newAmbiguousFactIds: readonly string[];
+    readonly newUnmatchedFactCount: number;
+    readonly newUnmatchedFactIds: readonly string[];
+}
+export interface ProviderMatrix {
+    readonly schemaVersion: ProviderMatrixSchemaVersion;
+    readonly inputFactSchemaVersion: typeof FACT_SCHEMA_VERSION;
+    readonly generatedBy: "deterministic-rules";
+    readonly repositories: readonly ResolvedRepository[];
+    readonly providers: readonly ProviderIdentity[];
+    readonly additionOrder: readonly ProviderIdentity[];
+    readonly metricDefinitions: readonly MatrixMetricDefinition[];
+    readonly coverage: readonly ProviderCoverage[];
+    readonly overlap: ProviderMatrixOverlap;
+    readonly conflicts: readonly MatrixFactRecord[];
+    readonly unmatched: ProviderMatrixUnmatched;
+    readonly informationGain: readonly InformationGain[];
+    /** Complete row set; the derived artifact files are projections of this set. */
+    readonly facts: readonly MatrixFactRecord[];
+}
+export interface ProviderMatrixArtifactPaths {
+    readonly matrixPath: string;
+    readonly coveragePath: string;
+    readonly overlapPath: string;
+    readonly conflictsPath: string;
+    readonly unmatchedPath: string;
+    readonly informationGainPath: string;
+    readonly reportPath: string;
+}
+/**
+ * A `MatrixEntityReference` reduced to the identity fields needed to read a
+ * row without re-embedding the full entity (path/range/kind), which is
+ * already persisted once in normalized/facts.json and reachable through
+ * `factIds`/`evidenceIds`.
+ */
+export interface MatrixEntityRefProjection {
+    readonly provider: ProviderIdentity;
+    readonly nativeId: string;
+    readonly canonicalId?: string;
+    readonly candidateCanonicalIds: readonly string[];
+}
+export type MatrixFactObjectProjection = {
+    readonly kind: "entity";
+    readonly entity: MatrixEntityRefProjection;
+} | {
+    readonly kind: "value";
+    readonly value: string;
+};
+/** `MatrixFactVariant` reduced to identity references; see `MatrixEntityRefProjection`. */
+export interface MatrixFactVariantProjection {
+    readonly key: string;
+    readonly factIds: readonly string[];
+    readonly evidenceIds: readonly string[];
+    readonly providers: readonly ProviderIdentity[];
+    readonly subject: MatrixEntityRefProjection;
+    readonly predicate: string;
+    readonly object: MatrixFactObjectProjection;
+}
+/**
+ * `MatrixFactRecord` projected for persistence: variants are reduced to
+ * identity references instead of full entity/object copies. Readers resolve
+ * `factIds`/`evidenceIds` against normalized/facts.json for full detail.
+ */
+export interface MatrixFactRecordProjection {
+    readonly key: string;
+    readonly logicalKey: string;
+    readonly repository: ResolvedRepository;
+    readonly factClass: string;
+    readonly predicate: string;
+    readonly state: MatrixFactState;
+    readonly comparisonPossible: boolean;
+    readonly correlationStatus: CorrelationStatus | "not-applicable";
+    readonly variants: readonly MatrixFactVariantProjection[];
+    readonly providerStates: readonly MatrixProviderFactStatus[];
+    readonly observedProviders: readonly ProviderIdentity[];
+    readonly missingProviders: readonly ProviderIdentity[];
+}
+export declare const MATRIX_METRIC_DEFINITIONS: readonly MatrixMetricDefinition[];
+/**
+ * Builds all matrix views from normalized/persisted facts. It only consumes
+ * artifacts; provider execution and observation generation are intentionally
+ * outside this function.
+ */
+export declare function buildProviderMatrix(input: NormalizedFactsArtifact | FactNormalizationResult, options?: ProviderMatrixOptions): ProviderMatrix;
+/** Alias for callers that use the generation vocabulary. */
+export declare const generateProviderMatrix: typeof buildProviderMatrix;
+/** Renders the matrix without consulting a model or changing any matrix state. */
+export declare function renderProviderMatrixReport(matrix: ProviderMatrix): string;
+/**
+ * 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 declare function writeProviderMatrixArtifacts(runRoot: string, matrix: ProviderMatrix): Promise<ProviderMatrixArtifactPaths>;
+/** Builds then persists a matrix, accepting either normalized facts or a matrix. */
+export declare function writeProviderMatrix(runRoot: string, input: NormalizedFactsArtifact | FactNormalizationResult | ProviderMatrix, options?: ProviderMatrixOptions): Promise<ProviderMatrixArtifactPaths>;
+/** Persists the exact normalized artifact consumed by the matrix builder. */
+export declare function writeNormalizedFactsArtifact(filePath: string, input: NormalizedFactsArtifact | FactNormalizationResult): Promise<string>;
+/**
+ * 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 declare function readNormalizedFactsArtifact(filePath: string): Promise<NormalizedFactsArtifact>;
+/** Reads a persisted normalized artifact and generates its deterministic matrix. */
+export declare function buildProviderMatrixFromArtifact(filePath: string, options?: ProviderMatrixOptions): Promise<ProviderMatrix>;
+/**
+ * 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 declare function writeStreamingJson(filePath: string, value: unknown): Promise<void>;
+/**
+ * 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 declare class JsonArtifactWriter {
+    private readonly handle;
+    private buffer;
+    constructor(handle: Awaited<ReturnType<typeof open>>);
+    write(value: string): Promise<void>;
+    flush(): Promise<void>;
+    /**
+     * 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))`).
+     */
+    writeArray<T>(values: readonly T[], transform: (value: T) => unknown): Promise<void>;
+    writeValue(value: unknown): Promise<void>;
+}