context-probe 0.1.0

package/dist/src/core/domain-design-scoring-core.js

@@ -0,0 +1,137 @@
+import { detectBoundaryLeaks, detectContractUsage, parseCodebase } from "../analyzers/code.js";
+import { createDomainDesignDocsLoaders } from "./domain-design-scoring-context.js";
+import { buildDomainDocsMetricFormulas } from "./domain-design-scoring-core-docs.js";
+import { computeDomainDocsMetricScores } from "./domain-design-scoring-docs.js";
+import { evaluateDomainLocality } from "./domain-design-scoring-locality.js";
+import { buildMccsMetric } from "./domain-design-scoring-mccs.js";
+import { resolveDomainPersistencePilot } from "./domain-design-scoring-pilot.js";
+import { buildDomainDesignScoreResponse } from "./domain-design-scoring-response.js";
+import { evaluateFormula } from "./formula.js";
+import { getDomainPolicy } from "./policy.js";
+import { createProgressTracker } from "./progress.js";
+import { toMetricScore } from "./scoring-shared.js";
+export async function computeDomainDesignScores(options) {
+    const startedAt = Date.now();
+    const { repoPath, model, policyConfig, profileName } = options;
+    const progress = createProgressTracker(options.progressReporter);
+    const policy = getDomainPolicy(policyConfig, profileName, "domain_design");
+    const codebase = await progress.withProgress("domain_design", `Parsing codebase for ${repoPath}.`, () => parseCodebase(repoPath));
+    const docsLoaders = createDomainDesignDocsLoaders({
+        repoPath,
+        docsRoot: options.docsRoot,
+        reportProgress: progress.reportProgress,
+        extraction: options.extraction,
+        codebase,
+    });
+    const contractUsage = await progress.withProgress("domain_design", `Detecting contract usage in ${repoPath}.`, () => detectContractUsage(codebase, model));
+    const leakFindings = await progress.withProgress("domain_design", `Detecting boundary leaks in ${repoPath}.`, () => detectBoundaryLeaks(codebase, model));
+    const diagnostics = [];
+    const unknowns = [];
+    const additionalEvidence = [];
+    let historyMs = 0;
+    let extractionMs = 0;
+    const requiresLocalityComparison = options.shadowPersistence || Boolean(options.pilotPersistenceCategory);
+    const locality = await progress.withProgress("history", `Analyzing Git history for modeled paths in ${repoPath}.`, async () => {
+        const historyStartedAt = Date.now();
+        const result = evaluateDomainLocality({
+            repoPath,
+            model,
+            policyConfig,
+            profileName,
+            requiresLocalityComparison,
+            progressReporter: progress.reportProgress,
+        });
+        historyMs = Date.now() - historyStartedAt;
+        return result;
+    });
+    const { history, historySignals, historyConfidence, shadow, shadowLocalityConfidence } = locality;
+    unknowns.push(...locality.unknowns);
+    diagnostics.push(...locality.diagnostics);
+    const elsComponents = historySignals;
+    const scores = [];
+    const docsMetrics = docsLoaders && options.docsRoot
+        ? await progress.withProgress("docs", `Computing document-derived metrics from ${options.docsRoot}.`, () => (async () => {
+            const extractionStartedAt = Date.now();
+            const result = await computeDomainDocsMetricScores({
+                docsRoot: options.docsRoot,
+                model,
+                codeFiles: codebase.scorableSourceFiles,
+                contractUsage,
+                leakFindings,
+                getGlossaryResult: async () => progress.withProgress("docs", `Extracting glossary evidence from ${options.docsRoot}.`, () => docsLoaders.getGlossaryResult()),
+                getRulesResult: async () => progress.withProgress("docs", `Extracting rule evidence from ${options.docsRoot}.`, () => docsLoaders.getRulesResult()),
+                getInvariantsResult: async () => progress.withProgress("docs", `Extracting invariant evidence from ${options.docsRoot}.`, () => docsLoaders.getInvariantsResult()),
+                getTermTraceLinks: async () => docsLoaders.getTermTraceLinks(),
+                reportProgress: progress.reportProgress,
+                formulas: buildDomainDocsMetricFormulas(policy),
+            });
+            extractionMs = Date.now() - extractionStartedAt;
+            return result;
+        })())
+        : { scores: [], evidence: [], diagnostics: [], unknowns: [] };
+    scores.push(...docsMetrics.scores);
+    additionalEvidence.push(...docsMetrics.evidence);
+    diagnostics.push(...docsMetrics.diagnostics);
+    unknowns.push(...docsMetrics.unknowns);
+    const mccsPolicy = policy.metrics.MCCS;
+    if (mccsPolicy) {
+        const mccs = await progress.withProgress("domain_design", "Computing MCCS.", () => buildMccsMetric({
+            metricPolicy: mccsPolicy,
+            contractUsage,
+            leakFindings,
+        }));
+        scores.push(mccs.metric);
+        additionalEvidence.push(...mccs.evidence);
+        unknowns.push(...mccs.unknowns);
+    }
+    const elsPolicy = policy.metrics.ELS;
+    if (elsPolicy) {
+        scores.push(await progress.withProgress("history", "Computing ELS.", () => toMetricScore("ELS", evaluateFormula(elsPolicy.formula, elsComponents), elsComponents, [], historyConfidence, history ? [] : ["History analysis did not complete, so ELS confidence is low."])));
+    }
+    let pilot;
+    if (options.pilotPersistenceCategory) {
+        if (!options.pilotGateEvaluation) {
+            throw new Error("pilotPersistenceCategory requires pilotGateEvaluation");
+        }
+        const elsMetric = scores.find((metric) => metric.metricId === "ELS");
+        if (!elsMetric) {
+            throw new Error("ELS metric is required for persistence pilot mode");
+        }
+        const pilotResolution = await progress.withProgress("domain_design", "Resolving persistence pilot.", () => resolveDomainPersistencePilot({
+            metric: elsMetric,
+            shadow,
+            shadowLocalityConfidence,
+            ...(options.pilotPersistenceCategory ? { pilotPersistenceCategory: options.pilotPersistenceCategory } : {}),
+            ...(options.pilotGateEvaluation ? { pilotGateEvaluation: options.pilotGateEvaluation } : {}),
+        }));
+        diagnostics.push(...pilotResolution.diagnostics);
+        pilot = pilotResolution.pilot;
+    }
+    return progress.withProgress("domain_design", "Assembling final domain score response.", () => {
+        const totalMs = Date.now() - startedAt;
+        return buildDomainDesignScoreResponse({
+            repoPath,
+            scores,
+            leakFindings,
+            history,
+            contractUsage,
+            shadow,
+            pilot,
+            diagnostics,
+            progress: progress.progress,
+            unknowns,
+            evidence: additionalEvidence,
+            meta: {
+                runtime: {
+                    totalMs,
+                    stages: {
+                        historyMs,
+                        ...(extractionMs > 0 ? { extractionMs } : {}),
+                        analysisMs: totalMs - historyMs - extractionMs,
+                    },
+                },
+            },
+            ...(options.docsRoot ? { docsRoot: options.docsRoot } : {}),
+        });
+    });
+}

package/dist/src/core/domain-design-scoring-docs-afs.d.ts

@@ -0,0 +1,2 @@
+import type { DomainDocsMetricContribution, DomainDocsMetricOptionsBase } from "./domain-design-scoring-docs-shared.js";
+export declare function computeDomainDocsAfsContribution(options: DomainDocsMetricOptionsBase, formula: string): Promise<DomainDocsMetricContribution>;

package/dist/src/core/domain-design-scoring-docs-afs.js

@@ -0,0 +1,40 @@
+import { computeAggregateFitness } from "./aggregate-fitness.js";
+import { evaluateFormula } from "./formula.js";
+import { toMetricScore } from "./scoring-shared.js";
+export async function computeDomainDocsAfsContribution(options, formula) {
+    if (!options.docsRoot) {
+        return {
+            scores: [],
+            evidence: [],
+            diagnostics: [],
+            unknowns: ["Skipped AFS because `--docs-root` was not provided."],
+        };
+    }
+    const [glossary, invariantsResult, links] = await Promise.all([
+        options.getGlossaryResult(),
+        options.getInvariantsResult(),
+        options.getTermTraceLinks(),
+    ]);
+    const afsResult = computeAggregateFitness({
+        model: options.model,
+        fragments: invariantsResult.fragments,
+        terms: glossary.terms,
+        links,
+        invariants: invariantsResult.invariants,
+        ...(options.reportProgress ? { reportProgress: options.reportProgress } : {}),
+    });
+    return {
+        scores: [
+            toMetricScore("AFS", evaluateFormula(formula, {
+                SIC: afsResult.SIC,
+                XTC: afsResult.XTC,
+            }), {
+                SIC: afsResult.SIC,
+                XTC: afsResult.XTC,
+            }, afsResult.evidence.map((entry) => entry.evidenceId), afsResult.confidence, afsResult.unknowns),
+        ],
+        evidence: afsResult.evidence,
+        diagnostics: afsResult.diagnostics,
+        unknowns: afsResult.unknowns,
+    };
+}

package/dist/src/core/domain-design-scoring-docs-bfs.d.ts

@@ -0,0 +1,2 @@
+import type { DomainDocsMetricContribution, DomainDocsMetricOptionsBase } from "./domain-design-scoring-docs-shared.js";
+export declare function computeDomainDocsBfsContribution(options: DomainDocsMetricOptionsBase, formula: string): Promise<DomainDocsMetricContribution>;

package/dist/src/core/domain-design-scoring-docs-bfs.js

@@ -0,0 +1,46 @@
+import { computeBoundaryFitness } from "./boundary-fitness.js";
+import { evaluateFormula } from "./formula.js";
+import { toMetricScore } from "./scoring-shared.js";
+import { buildModelCodeLinks } from "./trace.js";
+export async function computeDomainDocsBfsContribution(options, formula) {
+    if (!options.docsRoot) {
+        return {
+            scores: [],
+            evidence: [],
+            diagnostics: [],
+            unknowns: ["Skipped BFS because `--docs-root` was not provided."],
+        };
+    }
+    const [glossary, rulesResult, invariantsResult, links] = await Promise.all([
+        options.getGlossaryResult(),
+        options.getRulesResult(),
+        options.getInvariantsResult(),
+        options.getTermTraceLinks(),
+    ]);
+    const bfsResult = computeBoundaryFitness({
+        model: options.model,
+        fragments: rulesResult.fragments,
+        terms: glossary.terms,
+        links,
+        rules: rulesResult.rules,
+        invariants: invariantsResult.invariants,
+        contractUsage: options.contractUsage,
+        leakFindings: options.leakFindings,
+        modelCodeLinks: buildModelCodeLinks(options.model, options.codeFiles),
+        ...(options.reportProgress ? { reportProgress: options.reportProgress } : {}),
+    });
+    return {
+        scores: [
+            toMetricScore("BFS", evaluateFormula(formula, {
+                A: bfsResult.A,
+                R: bfsResult.R,
+            }), {
+                A: bfsResult.A,
+                R: bfsResult.R,
+            }, bfsResult.evidence.map((entry) => entry.evidenceId), bfsResult.confidence, bfsResult.unknowns),
+        ],
+        evidence: bfsResult.evidence,
+        diagnostics: bfsResult.diagnostics,
+        unknowns: bfsResult.unknowns,
+    };
+}

package/dist/src/core/domain-design-scoring-docs-core.d.ts

@@ -0,0 +1,12 @@
+import type { Evidence, MetricScore } from "./contracts.js";
+import type { DomainDocsMetricOptionsBase } from "./domain-design-scoring-docs-shared.js";
+interface DomainDocsMetricOptions extends DomainDocsMetricOptionsBase {
+    formulas: Partial<Record<"DRF" | "ULI" | "BFS" | "AFS", string>>;
+}
+export declare function computeDomainDocsMetricScores(options: DomainDocsMetricOptions): Promise<{
+    scores: MetricScore[];
+    evidence: Evidence[];
+    diagnostics: string[];
+    unknowns: string[];
+}>;
+export {};

package/dist/src/core/domain-design-scoring-docs-core.js

@@ -0,0 +1,47 @@
+import { computeDomainDocsAfsContribution } from "./domain-design-scoring-docs-afs.js";
+import { computeDomainDocsBfsContribution } from "./domain-design-scoring-docs-bfs.js";
+import { computeDomainDocsDrfContribution } from "./domain-design-scoring-docs-drf.js";
+import { computeDomainDocsUliContribution } from "./domain-design-scoring-docs-uli.js";
+import { dedupeEvidence } from "./scoring-shared.js";
+function mergeContributions(contributions) {
+    return {
+        scores: contributions.flatMap((contribution) => contribution.scores),
+        evidence: dedupeEvidence(contributions.flatMap((contribution) => contribution.evidence)),
+        diagnostics: contributions.flatMap((contribution) => contribution.diagnostics),
+        unknowns: contributions.flatMap((contribution) => contribution.unknowns),
+    };
+}
+async function runContribution(options, metricId, task) {
+    const startedAt = Date.now();
+    options.reportProgress?.({
+        phase: "docs",
+        message: `Computing ${metricId} from document evidence.`,
+    });
+    const result = await task();
+    options.reportProgress?.({
+        phase: "docs",
+        message: `Computed ${metricId} from document evidence in ${Date.now() - startedAt}ms.`,
+        elapsedMs: Date.now() - startedAt,
+    });
+    return result;
+}
+export async function computeDomainDocsMetricScores(options) {
+    const contributions = [];
+    const drfFormula = options.formulas.DRF;
+    if (drfFormula) {
+        contributions.push(await runContribution(options, "DRF", () => computeDomainDocsDrfContribution(options, drfFormula)));
+    }
+    const uliFormula = options.formulas.ULI;
+    if (uliFormula) {
+        contributions.push(await runContribution(options, "ULI", () => computeDomainDocsUliContribution(options, uliFormula)));
+    }
+    const bfsFormula = options.formulas.BFS;
+    if (bfsFormula) {
+        contributions.push(await runContribution(options, "BFS", () => computeDomainDocsBfsContribution(options, bfsFormula)));
+    }
+    const afsFormula = options.formulas.AFS;
+    if (afsFormula) {
+        contributions.push(await runContribution(options, "AFS", () => computeDomainDocsAfsContribution(options, afsFormula)));
+    }
+    return mergeContributions(contributions);
+}

package/dist/src/core/domain-design-scoring-docs-drf.d.ts

@@ -0,0 +1,2 @@
+import type { DomainDocsMetricContribution, DomainDocsMetricOptionsBase } from "./domain-design-scoring-docs-shared.js";
+export declare function computeDomainDocsDrfContribution(options: DomainDocsMetricOptionsBase, formula: string): Promise<DomainDocsMetricContribution>;

package/dist/src/core/domain-design-scoring-docs-drf.js

@@ -0,0 +1,55 @@
+import { buildReviewItemsForCandidates, computeDrfComponents, inspectDrfEvidenceQuality, } from "./domain-design-scoring-support.js";
+import { evaluateFormula } from "./formula.js";
+import { confidenceFromSignals } from "./response.js";
+import { dedupeEvidence, toMetricScore } from "./scoring-shared.js";
+export async function computeDomainDocsDrfContribution(options, formula) {
+    if (!options.docsRoot) {
+        return {
+            scores: [],
+            evidence: [],
+            diagnostics: [],
+            unknowns: ["Skipped DRF because `--docs-root` was not provided."],
+        };
+    }
+    const [rulesResult, invariantsResult] = await Promise.all([options.getRulesResult(), options.getInvariantsResult()]);
+    const reviewItems = [
+        ...buildReviewItemsForCandidates("rules", rulesResult.rules, rulesResult.confidence, rulesResult.unknowns),
+        ...buildReviewItemsForCandidates("invariants", invariantsResult.invariants, invariantsResult.confidence, invariantsResult.unknowns),
+    ];
+    const drfComponents = computeDrfComponents(rulesResult.fragments, rulesResult.rules, invariantsResult.invariants, reviewItems.length);
+    const drfEvidenceQuality = inspectDrfEvidenceQuality(rulesResult.fragments, rulesResult.rules, invariantsResult.invariants);
+    const drfUnknowns = [...rulesResult.unknowns, ...invariantsResult.unknowns];
+    if (drfEvidenceQuality.explicitUseCaseCount === 0) {
+        drfUnknowns.push("SC is an approximation based on use-case signals.");
+    }
+    if (drfEvidenceQuality.explicitRuleCount === 0 && drfEvidenceQuality.explicitInvariantCount === 0) {
+        drfUnknowns.push("IV is an approximation based on review burden.");
+    }
+    if (drfComponents.totalCandidates === 0) {
+        drfUnknowns.push("No rules or invariants were extracted, so DRF evidence is insufficient.");
+    }
+    if (drfComponents.useCaseFragments === 0) {
+        drfUnknowns.push("Too little use-case-like text was found, so SC evidence is limited.");
+    }
+    const drfEvidence = dedupeEvidence([
+        ...rulesResult.rules.flatMap((rule) => rule.evidence),
+        ...invariantsResult.invariants.flatMap((invariant) => invariant.evidence),
+    ]);
+    return {
+        scores: [
+            toMetricScore("DRF", evaluateFormula(formula, drfComponents), {
+                SC: drfComponents.SC,
+                RC: drfComponents.RC,
+                IV: drfComponents.IV,
+                RA: drfComponents.RA,
+            }, drfEvidence.map((entry) => entry.evidenceId), confidenceFromSignals([
+                rulesResult.confidence,
+                invariantsResult.confidence,
+                drfComponents.useCaseFragments > 0 ? 0.8 : 0.55,
+            ]), drfUnknowns),
+        ],
+        evidence: drfEvidence,
+        diagnostics: [...rulesResult.diagnostics, ...invariantsResult.diagnostics],
+        unknowns: drfUnknowns,
+    };
+}

package/dist/src/core/domain-design-scoring-docs-shared.d.ts

@@ -0,0 +1,25 @@
+import type { detectBoundaryLeaks, detectContractUsage } from "../analyzers/code.js";
+import type { DomainModel, Evidence, MetricScore, TermTraceLink } from "./contracts.js";
+import type { extractGlossary, extractInvariants, extractRules } from "./document-extractors.js";
+import type { ProgressReporter } from "./progress.js";
+export type GlossaryExtractionResult = Awaited<ReturnType<typeof extractGlossary>>;
+export type RulesExtractionResult = Awaited<ReturnType<typeof extractRules>>;
+export type InvariantsExtractionResult = Awaited<ReturnType<typeof extractInvariants>>;
+export interface DomainDocsMetricOptionsBase {
+    docsRoot: string | undefined;
+    model: DomainModel;
+    codeFiles: string[];
+    contractUsage: ReturnType<typeof detectContractUsage>;
+    leakFindings: ReturnType<typeof detectBoundaryLeaks>;
+    getGlossaryResult: () => Promise<GlossaryExtractionResult>;
+    getRulesResult: () => Promise<RulesExtractionResult>;
+    getInvariantsResult: () => Promise<InvariantsExtractionResult>;
+    getTermTraceLinks: () => Promise<TermTraceLink[]>;
+    reportProgress?: ProgressReporter;
+}
+export interface DomainDocsMetricContribution {
+    scores: MetricScore[];
+    evidence: Evidence[];
+    diagnostics: string[];
+    unknowns: string[];
+}

package/dist/src/core/domain-design-scoring-docs-shared.js

@@ -0,0 +1 @@
+export {};

package/dist/src/core/domain-design-scoring-docs-uli.d.ts

@@ -0,0 +1,2 @@
+import type { DomainDocsMetricContribution, DomainDocsMetricOptionsBase } from "./domain-design-scoring-docs-shared.js";
+export declare function computeDomainDocsUliContribution(options: DomainDocsMetricOptionsBase, formula: string): Promise<DomainDocsMetricContribution>;

package/dist/src/core/domain-design-scoring-docs-uli.js

@@ -0,0 +1,39 @@
+import { computeUliComponents } from "./domain-design-scoring-support.js";
+import { evaluateFormula } from "./formula.js";
+import { confidenceFromSignals, toEvidence } from "./response.js";
+import { toMetricScore } from "./scoring-shared.js";
+export async function computeDomainDocsUliContribution(options, formula) {
+    if (!options.docsRoot) {
+        return {
+            scores: [],
+            evidence: [],
+            diagnostics: [],
+            unknowns: ["Skipped ULI because `--docs-root` was not provided."],
+        };
+    }
+    const [glossary, links] = await Promise.all([options.getGlossaryResult(), options.getTermTraceLinks()]);
+    const uliComponents = computeUliComponents(glossary.terms, links);
+    const averageTraceConfidence = links.length === 0 ? 0.5 : links.reduce((sum, link) => sum + link.confidence, 0) / links.length;
+    const uliUnknowns = [...glossary.unknowns];
+    if (glossary.terms.length === 0) {
+        uliUnknowns.push("No glossary terms were extracted, so ULI evidence is insufficient.");
+    }
+    if (glossary.terms.every((term) => term.aliases.length === 0)) {
+        uliUnknowns.push("Alias Entropy is approximated from alias counts.");
+    }
+    const termEvidence = glossary.terms.flatMap((term) => term.evidence);
+    const traceGapEvidence = links
+        .filter((link) => link.coverage.codeHits === 0)
+        .map((link) => toEvidence(`${link.canonicalTerm} is not traced to code`, {
+        termId: link.termId,
+        docsRoot: options.docsRoot,
+    }, [link.termId], 0.8));
+    return {
+        scores: [
+            toMetricScore("ULI", evaluateFormula(formula, uliComponents), uliComponents, [...termEvidence, ...traceGapEvidence].map((entry) => entry.evidenceId), confidenceFromSignals([glossary.confidence, averageTraceConfidence, glossary.terms.length > 0 ? 0.85 : 0.4]), uliUnknowns),
+        ],
+        evidence: [...termEvidence, ...traceGapEvidence],
+        diagnostics: [...glossary.diagnostics],
+        unknowns: uliUnknowns,
+    };
+}

package/dist/src/core/domain-design-scoring-docs.d.ts

@@ -0,0 +1 @@
+export { computeDomainDocsMetricScores } from "./domain-design-scoring-docs-core.js";

package/dist/src/core/domain-design-scoring-docs.js

@@ -0,0 +1 @@
+export { computeDomainDocsMetricScores } from "./domain-design-scoring-docs-core.js";

package/dist/src/core/domain-design-scoring-locality.d.ts

@@ -0,0 +1,27 @@
+import type { CochangeAnalysis, DomainDesignScoreResult, DomainModel, PolicyConfig } from "./contracts.js";
+interface EvaluateDomainLocalityOptions {
+    repoPath: string;
+    model: DomainModel;
+    policyConfig: PolicyConfig;
+    profileName: string;
+    requiresLocalityComparison: boolean;
+    progressReporter?: (update: {
+        phase: string;
+        message: string;
+    }) => void;
+}
+export interface DomainLocalityEvaluation {
+    history: CochangeAnalysis | null;
+    historySignals: {
+        CCL: number;
+        FS: number;
+        SCR: number;
+    };
+    historyConfidence: number;
+    shadow?: DomainDesignScoreResult["shadow"];
+    shadowLocalityConfidence: number;
+    unknowns: string[];
+    diagnostics: string[];
+}
+export declare function evaluateDomainLocality(options: EvaluateDomainLocalityOptions): Promise<DomainLocalityEvaluation>;
+export {};

package/dist/src/core/domain-design-scoring-locality.js

@@ -0,0 +1,87 @@
+import { compareEvolutionLocalityModels, evaluateEvolutionLocalityObservationQuality, normalizeHistory, scoreEvolutionLocality, } from "./history.js";
+export async function evaluateDomainLocality(options) {
+    const { repoPath, model, policyConfig, profileName, requiresLocalityComparison, progressReporter } = options;
+    const unknowns = [];
+    const diagnostics = [];
+    let history = null;
+    let historySignals = {
+        CCL: 0,
+        FS: 0,
+        SCR: 0,
+    };
+    let historyConfidence = 0;
+    let shadow;
+    let shadowLocalityConfidence = 0;
+    try {
+        const modeledPathCount = new Set(model.contexts.flatMap((entry) => entry.pathGlobs)).size;
+        progressReporter?.({
+            phase: "history",
+            message: `Starting history analysis across ${modeledPathCount} modeled path glob(s).`,
+        });
+        const commits = await normalizeHistory(repoPath, policyConfig, profileName, {
+            includePathGlobs: model.contexts.flatMap((entry) => entry.pathGlobs),
+            onProgress: (event) => {
+                if (event.phase === "heartbeat") {
+                    progressReporter?.({
+                        phase: "history",
+                        message: `History analysis is still running: ${event.observedCommitCount} commit marker(s) scanned in ${Math.round(event.elapsedMs / 1000)}s.`,
+                    });
+                    return;
+                }
+                if (event.phase === "complete") {
+                    progressReporter?.({
+                        phase: "history",
+                        message: `History analysis completed in ${Math.round(event.elapsedMs / 1000)}s with ${event.emittedCommitCount} relevant commit(s).`,
+                    });
+                }
+            },
+        });
+        history = scoreEvolutionLocality(commits, model);
+        const historyQuality = evaluateEvolutionLocalityObservationQuality(commits, model);
+        historySignals = {
+            CCL: history.crossContextChangeLocality,
+            FS: history.featureScatter,
+            SCR: history.surpriseCouplingRatio,
+        };
+        historyConfidence = historyQuality.confidence;
+        unknowns.push(...historyQuality.unknowns);
+        if (requiresLocalityComparison) {
+            const localityModels = compareEvolutionLocalityModels(commits, model);
+            shadowLocalityConfidence = localityModels.confidence;
+            shadow = {
+                localityModels: localityModels.comparison,
+            };
+            unknowns.push(...localityModels.unknowns);
+        }
+    }
+    catch (error) {
+        const modeledPathCount = new Set(model.contexts.flatMap((entry) => entry.pathGlobs)).size;
+        historyConfidence = 0.2;
+        diagnostics.push(error instanceof Error
+            ? `Skipped history analysis after scanning ${modeledPathCount} modeled path glob(s): ${error.message}`
+            : `Skipped history analysis after scanning ${modeledPathCount} modeled path glob(s).`);
+        unknowns.push("Git information required for history analysis is missing.");
+        progressReporter?.({
+            phase: "history",
+            message: error instanceof Error ? `History analysis failed: ${error.message}` : "History analysis failed.",
+        });
+        if (requiresLocalityComparison) {
+            const fallbackLocalityModels = compareEvolutionLocalityModels([], model);
+            shadowLocalityConfidence = fallbackLocalityModels.confidence;
+            shadow = {
+                localityModels: fallbackLocalityModels.comparison,
+            };
+            unknowns.push(...fallbackLocalityModels.unknowns);
+            unknowns.push("Locality comparison fell back to the baseline ELS because Git history is unavailable.");
+        }
+    }
+    return {
+        history,
+        historySignals,
+        historyConfidence,
+        ...(shadow ? { shadow } : {}),
+        shadowLocalityConfidence,
+        unknowns,
+        diagnostics,
+    };
+}

package/dist/src/core/domain-design-scoring-mccs.d.ts

@@ -0,0 +1,18 @@
+import type { detectBoundaryLeaks, detectContractUsage } from "../analyzers/code.js";
+import type { Evidence } from "./contracts.js";
+import { toMetricScore } from "./scoring-shared.js";
+type BoundaryLeakFinding = ReturnType<typeof detectBoundaryLeaks>[number];
+type ContractUsageSummary = ReturnType<typeof detectContractUsage>;
+export interface MccsMetricBuildResult {
+    metric: ReturnType<typeof toMetricScore>;
+    evidence: Evidence[];
+    unknowns: string[];
+}
+export declare function buildMccsMetric(input: {
+    metricPolicy: {
+        formula: string;
+    };
+    contractUsage: ContractUsageSummary;
+    leakFindings: BoundaryLeakFinding[];
+}): MccsMetricBuildResult;
+export {};

package/dist/src/core/domain-design-scoring-mccs.js

@@ -0,0 +1,29 @@
+import { evaluateFormula } from "./formula.js";
+import { confidenceFromSignals, toEvidence } from "./response.js";
+import { computeLeakRatio, toMetricScore } from "./scoring-shared.js";
+export function buildMccsMetric(input) {
+    const evidence = input.leakFindings.map((finding) => toEvidence(`${finding.sourceContext} -> ${finding.targetContext} internal leak`, {
+        path: finding.path,
+        violationType: finding.violationType,
+    }, [finding.findingId], 0.95));
+    const leakRatio = computeLeakRatio(input.leakFindings, input.contractUsage.applicableReferences);
+    const unknowns = input.contractUsage.applicableReferences > 0
+        ? []
+        : [
+            "No applicable cross-context references were found, so MCCS evidence is limited.",
+            "No cross-context references were observed, so MCCS should be interpreted carefully.",
+        ];
+    const mccsConfidence = input.contractUsage.applicableReferences > 0 ? 0.9 : 0.55;
+    const components = {
+        MRP: 1 - leakRatio,
+        BLR: leakRatio,
+        CLA: input.contractUsage.adherence,
+    };
+    return {
+        metric: toMetricScore("MCCS", evaluateFormula(input.metricPolicy.formula, components), components, evidence.map((entry) => entry.evidenceId), confidenceFromSignals([0.9, mccsConfidence, 0.9]), input.contractUsage.applicableReferences > 0
+            ? []
+            : ["No cross-context references were observed, so MCCS should be interpreted carefully."]),
+        evidence,
+        unknowns,
+    };
+}

package/dist/src/core/domain-design-scoring-pilot.d.ts

@@ -0,0 +1,13 @@
+import type { DomainDesignScoreResult, DomainDesignShadowRolloutGateEvaluation, MetricScore } from "./contracts.js";
+export interface PilotResolutionResult {
+    metric: MetricScore;
+    pilot?: DomainDesignScoreResult["pilot"];
+    diagnostics: string[];
+}
+export declare function resolveDomainPersistencePilot(input: {
+    metric: MetricScore;
+    shadow: DomainDesignScoreResult["shadow"];
+    shadowLocalityConfidence: number;
+    pilotPersistenceCategory?: string;
+    pilotGateEvaluation?: DomainDesignShadowRolloutGateEvaluation;
+}): PilotResolutionResult;