context-probe 0.1.0

package/dist/src/command-shadow-rollout-batch.d.ts

@@ -0,0 +1,5 @@
+import type { CommandLookup } from "./command-types.js";
+import type { CommandResponse, DomainDesignShadowRolloutBatchResult } from "./core/contracts.js";
+export declare function handleObserveShadowRolloutBatchCommand(commandLookup: CommandLookup, args: Record<string, string | boolean>, context: {
+    cwd: string;
+}): Promise<CommandResponse<DomainDesignShadowRolloutBatchResult>>;

package/dist/src/command-shadow-rollout-batch.js

@@ -0,0 +1,85 @@
+import path from "node:path";
+import { requireShadowRolloutBatchSpec, resolveSpecRelativePath } from "./command-helpers.js";
+import { requireRegisteredCommand, resolveTieTolerance } from "./command-shadow-rollout-shared.js";
+import { confidenceFromSignals, createResponse, mergeStatus, toProvenance } from "./core/response.js";
+import { inferShadowRolloutModelSource, summarizeShadowRolloutBatchObservations } from "./core/shadow-rollout.js";
+export async function handleObserveShadowRolloutBatchCommand(commandLookup, args, context) {
+    const observeShadowRollout = requireRegisteredCommand(commandLookup, "score.observe_shadow_rollout");
+    const { spec, specPath } = await requireShadowRolloutBatchSpec(args, context);
+    const specDirectory = path.dirname(specPath);
+    const argPolicyPath = typeof args.policy === "string" ? new URL(args.policy, `file://${context.cwd}/`).pathname : undefined;
+    const observations = [];
+    const statuses = new Set();
+    const unknowns = new Set();
+    const diagnostics = new Set();
+    const confidenceSignals = [];
+    for (const entry of spec.entries) {
+        const repoPath = resolveSpecRelativePath(specDirectory, entry.repo);
+        const modelPath = resolveSpecRelativePath(specDirectory, entry.model);
+        const resolvedPolicyInput = entry.policy
+            ? resolveSpecRelativePath(specDirectory, entry.policy)
+            : spec.policy
+                ? resolveSpecRelativePath(specDirectory, spec.policy)
+                : argPolicyPath;
+        if (!resolvedPolicyInput) {
+            throw new Error(`Shadow rollout batch entry \`${entry.repoId}\` is missing a policy path`);
+        }
+        const tieTolerance = resolveTieTolerance(entry.tieTolerance, spec.tieTolerance, typeof args["tie-tolerance"] === "string" ? args["tie-tolerance"] : undefined);
+        const response = (await observeShadowRollout({
+            repo: repoPath,
+            model: modelPath,
+            policy: resolvedPolicyInput,
+            ...(tieTolerance !== undefined ? { "tie-tolerance": String(tieTolerance) } : {}),
+        }, context));
+        const category = entry.category ?? "uncategorized";
+        statuses.add(response.status);
+        confidenceSignals.push(response.confidence);
+        response.unknowns.forEach((unknown) => {
+            unknowns.add(`${entry.repoId}: ${unknown}`);
+        });
+        response.diagnostics.forEach((diagnostic) => {
+            diagnostics.add(`${entry.repoId}: ${diagnostic}`);
+        });
+        observations.push({
+            repoId: entry.repoId,
+            ...(entry.label ? { label: entry.label } : {}),
+            category,
+            modelSource: entry.modelSource ?? inferShadowRolloutModelSource(modelPath),
+            repoPath,
+            modelPath,
+            policyPath: resolvedPolicyInput,
+            status: response.status,
+            elsMetric: response.result.elsMetric.value,
+            persistenceLocalityScore: response.result.shadow.localityModels.persistenceCandidate.localityScore,
+            policyDelta: response.result.observation.policyDelta,
+            modelDelta: response.result.observation.modelDelta,
+            driftCategory: response.result.observation.driftCategory,
+            relevantCommitCount: response.result.shadow.localityModels.persistenceAnalysis.relevantCommitCount,
+            confidence: response.confidence,
+            unknowns: response.unknowns,
+        });
+    }
+    const categories = Array.from(observations
+        .reduce((groups, observation) => {
+        const existing = groups.get(observation.category) ?? [];
+        existing.push(observation);
+        groups.set(observation.category, existing);
+        return groups;
+    }, new Map())
+        .entries()).map(([category, categoryObservations]) => ({
+        category,
+        repoIds: categoryObservations.map((entry) => entry.repoId),
+        summary: summarizeShadowRolloutBatchObservations(categoryObservations),
+    }));
+    return createResponse({
+        observations,
+        categories,
+        overall: summarizeShadowRolloutBatchObservations(observations),
+    }, {
+        status: mergeStatus(...statuses),
+        confidence: confidenceFromSignals(confidenceSignals),
+        unknowns: Array.from(unknowns),
+        diagnostics: Array.from(diagnostics),
+        provenance: [toProvenance(specPath, "shadow rollout batch spec")],
+    });
+}

package/dist/src/command-shadow-rollout-gate.d.ts

@@ -0,0 +1,5 @@
+import type { CommandLookup } from "./command-types.js";
+import type { CommandResponse, DomainDesignShadowRolloutGateResult } from "./core/contracts.js";
+export declare function handleEvaluateShadowRolloutGateCommand(commandLookup: CommandLookup, args: Record<string, string | boolean>, context: {
+    cwd: string;
+}): Promise<CommandResponse<DomainDesignShadowRolloutGateResult>>;

package/dist/src/command-shadow-rollout-gate.js

@@ -0,0 +1,33 @@
+import { requireShadowRolloutRegistry } from "./command-helpers.js";
+import { requireRegisteredCommand } from "./command-shadow-rollout-shared.js";
+import { createResponse, toProvenance } from "./core/response.js";
+import { batchToGateObservations, evaluateShadowRolloutGate, loadShadowRolloutRegistry, registryToGateObservations, } from "./core/shadow-rollout.js";
+export async function handleEvaluateShadowRolloutGateCommand(commandLookup, args, context) {
+    const observeShadowRolloutBatch = requireRegisteredCommand(commandLookup, "score.observe_shadow_rollout_batch");
+    if (typeof args["batch-spec"] === "string") {
+        const response = (await observeShadowRolloutBatch(args, context));
+        const evaluation = evaluateShadowRolloutGate(batchToGateObservations(response.result.observations));
+        return createResponse({
+            source: "batch_spec",
+            batchSpecPath: new URL(args["batch-spec"], `file://${context.cwd}/`).pathname,
+            evaluation,
+        }, {
+            status: evaluation.rolloutDisposition === "replace" ? response.status : "warning",
+            evidence: response.evidence,
+            confidence: response.confidence,
+            unknowns: response.unknowns,
+            diagnostics: response.diagnostics,
+            provenance: response.provenance,
+        });
+    }
+    const { registry, registryPath } = await requireShadowRolloutRegistry(args, context, loadShadowRolloutRegistry);
+    const evaluation = evaluateShadowRolloutGate(registryToGateObservations(registry, registryPath));
+    return createResponse({
+        source: "registry",
+        registryPath,
+        evaluation,
+    }, {
+        status: evaluation.rolloutDisposition === "replace" ? "ok" : "warning",
+        provenance: [toProvenance(registryPath, "shadow rollout registry")],
+    });
+}

package/dist/src/command-shadow-rollout-observe.d.ts

@@ -0,0 +1,5 @@
+import type { CommandLookup } from "./command-types.js";
+import type { CommandResponse, DomainDesignShadowRolloutObservation } from "./core/contracts.js";
+export declare function handleObserveShadowRolloutCommand(commandLookup: CommandLookup, args: Record<string, string | boolean>, context: {
+    cwd: string;
+}): Promise<CommandResponse<DomainDesignShadowRolloutObservation>>;

package/dist/src/command-shadow-rollout-observe.js

@@ -0,0 +1,43 @@
+import { parseSafeTieTolerance, requireRegisteredCommand } from "./command-shadow-rollout-shared.js";
+import { createResponse } from "./core/response.js";
+export async function handleObserveShadowRolloutCommand(commandLookup, args, context) {
+    const scoreCompute = requireRegisteredCommand(commandLookup, "score.compute");
+    const { "pilot-persistence": _pilotPersistence, "rollout-category": _rolloutCategory, "shadow-rollout-registry": _shadowRolloutRegistry, registry: _registry, ...shadowArgs } = args;
+    const scoreResponse = (await scoreCompute({
+        ...shadowArgs,
+        domain: "domain_design",
+        "shadow-persistence": true,
+    }, context));
+    const elsMetric = scoreResponse.result.metrics.find((metric) => metric.metricId === "ELS");
+    if (!elsMetric) {
+        throw new Error("ELS metric is not available in the current domain score response");
+    }
+    if (!scoreResponse.result.shadow) {
+        throw new Error("Shadow persistence payload is not available in the current domain score response");
+    }
+    const safeTieTolerance = parseSafeTieTolerance(typeof args["tie-tolerance"] === "string" ? args["tie-tolerance"] : undefined);
+    const baselineElsValue = scoreResponse.result.pilot?.baselineElsValue ?? elsMetric.value;
+    const policyDelta = scoreResponse.result.shadow.localityModels.persistenceCandidate.localityScore - baselineElsValue;
+    const driftCategory = Math.abs(policyDelta) <= safeTieTolerance ? "aligned" : policyDelta > 0 ? "candidate_higher" : "candidate_lower";
+    return createResponse({
+        domainId: "domain_design",
+        metricId: "ELS",
+        elsMetric,
+        shadow: scoreResponse.result.shadow,
+        observation: {
+            policyDelta,
+            modelDelta: scoreResponse.result.shadow.localityModels.delta,
+            driftCategory,
+            tieTolerance: safeTieTolerance,
+        },
+        history: scoreResponse.result.history,
+        crossContextReferences: scoreResponse.result.crossContextReferences,
+    }, {
+        status: scoreResponse.status,
+        evidence: scoreResponse.evidence,
+        confidence: scoreResponse.confidence,
+        unknowns: scoreResponse.unknowns,
+        diagnostics: scoreResponse.diagnostics,
+        provenance: scoreResponse.provenance,
+    });
+}

package/dist/src/command-shadow-rollout-shared.d.ts

@@ -0,0 +1,4 @@
+import type { CommandHandler, CommandLookup } from "./command-types.js";
+export declare function requireRegisteredCommand(commandLookup: CommandLookup, name: string): CommandHandler;
+export declare function parseSafeTieTolerance(rawValue: string | undefined): number;
+export declare function resolveTieTolerance(...rawValues: Array<string | number | undefined>): number;

package/dist/src/command-shadow-rollout-shared.js

@@ -0,0 +1,23 @@
+export function requireRegisteredCommand(commandLookup, name) {
+    const command = commandLookup(name);
+    if (!command) {
+        throw new Error(`${name} is not registered`);
+    }
+    return command;
+}
+export function parseSafeTieTolerance(rawValue) {
+    const tieTolerance = typeof rawValue === "string" ? Number.parseFloat(rawValue) : 0.02;
+    return Number.isFinite(tieTolerance) && tieTolerance >= 0 ? tieTolerance : 0.02;
+}
+export function resolveTieTolerance(...rawValues) {
+    for (const rawValue of rawValues) {
+        if (rawValue === undefined) {
+            continue;
+        }
+        const tieTolerance = typeof rawValue === "number" ? rawValue : Number.parseFloat(rawValue);
+        if (Number.isFinite(tieTolerance) && tieTolerance >= 0) {
+            return tieTolerance;
+        }
+    }
+    return 0.02;
+}

package/dist/src/command-shadow-rollout.d.ts

@@ -0,0 +1,2 @@
+import type { CommandHandler, CommandLookup } from "./command-types.js";
+export declare function createShadowRolloutCommands(commandLookup: CommandLookup): Record<string, CommandHandler>;

package/dist/src/command-shadow-rollout.js

@@ -0,0 +1,16 @@
+import { handleObserveShadowRolloutBatchCommand } from "./command-shadow-rollout-batch.js";
+import { handleEvaluateShadowRolloutGateCommand } from "./command-shadow-rollout-gate.js";
+import { handleObserveShadowRolloutCommand } from "./command-shadow-rollout-observe.js";
+export function createShadowRolloutCommands(commandLookup) {
+    return {
+        async "score.observe_shadow_rollout"(args, context) {
+            return handleObserveShadowRolloutCommand(commandLookup, args, context);
+        },
+        async "score.observe_shadow_rollout_batch"(args, context) {
+            return handleObserveShadowRolloutBatchCommand(commandLookup, args, context);
+        },
+        async "gate.evaluate_shadow_rollout"(args, context) {
+            return handleEvaluateShadowRolloutGateCommand(commandLookup, args, context);
+        },
+    };
+}

package/dist/src/command-types.d.ts

@@ -0,0 +1,4 @@
+import type { CommandArgs } from "./command-helpers.js";
+import type { CommandContext, CommandResponse } from "./core/contracts.js";
+export type CommandHandler = (args: CommandArgs, context: CommandContext) => Promise<CommandResponse<unknown>>;
+export type CommandLookup = (name: string) => CommandHandler | undefined;

package/dist/src/command-types.js

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

package/dist/src/commands.d.ts

@@ -0,0 +1,6 @@
+import type { CommandHandler } from "./command-types.js";
+import type { CommandContext, CommandResponse } from "./core/contracts.js";
+export type { CommandHandler } from "./command-types.js";
+export declare const COMMANDS: Record<string, CommandHandler>;
+export declare function listCommands(): string[];
+export declare function maybeWriteOutput(response: CommandResponse<unknown>, args: Record<string, string | boolean>, context: CommandContext): Promise<void>;

package/dist/src/commands.js

@@ -0,0 +1,66 @@
+import { promises as fs } from "node:fs";
+import { createArchitectureCommands } from "./command-architecture.js";
+import { createDomainCommands } from "./command-domain.js";
+import { createHistoryCommands } from "./command-history.js";
+import { handleScoreCompute } from "./command-score.js";
+import { handleGateEvaluate, handleReportGenerate, handleReviewListUnknowns } from "./command-score-driven.js";
+import { createShadowRolloutCommands } from "./command-shadow-rollout.js";
+import { readDataFile } from "./core/io.js";
+import { createResponse, toProvenance } from "./core/response.js";
+import { resolveReviewItems } from "./core/review.js";
+export const COMMANDS = {
+    ...createDomainCommands(),
+    ...createHistoryCommands(),
+    ...createArchitectureCommands(),
+    "score.compute": handleScoreCompute,
+    async "review.list_unknowns"(args, context) {
+        const scoreCompute = COMMANDS["score.compute"];
+        if (!scoreCompute) {
+            throw new Error("score.compute is not registered");
+        }
+        return handleReviewListUnknowns(args, context, scoreCompute, COMMANDS);
+    },
+    async "review.resolve"(args, context) {
+        const reviewItemsPath = typeof args["review-items"] === "string"
+            ? new URL(args["review-items"], `file://${context.cwd}/`).pathname
+            : undefined;
+        const resolutionsPath = typeof args.resolutions === "string" ? new URL(args.resolutions, `file://${context.cwd}/`).pathname : undefined;
+        if (!reviewItemsPath || !resolutionsPath) {
+            throw new Error("`--review-items` and `--resolutions` are required");
+        }
+        const reviewItemsPayload = await readDataFile(reviewItemsPath);
+        const reviewItems = reviewItemsPayload.reviewItems ?? reviewItemsPayload.result?.reviewItems ?? [];
+        const resolutions = await readDataFile(resolutionsPath);
+        const resolutionLog = resolveReviewItems(reviewItems, resolutions);
+        return createResponse(resolutionLog, {
+            status: resolutionLog.overrides.length > 0 ? "warning" : "ok",
+            confidence: 0.9,
+            provenance: [toProvenance(reviewItemsPath, "review.resolve"), toProvenance(resolutionsPath, "review.resolve")],
+        });
+    },
+    async "report.generate"(args, context) {
+        const scoreCompute = COMMANDS["score.compute"];
+        if (!scoreCompute) {
+            throw new Error("score.compute is not registered");
+        }
+        return handleReportGenerate(args, context, scoreCompute);
+    },
+    async "gate.evaluate"(args, context) {
+        const scoreCompute = COMMANDS["score.compute"];
+        if (!scoreCompute) {
+            throw new Error("score.compute is not registered");
+        }
+        return handleGateEvaluate(args, context, scoreCompute);
+    },
+    ...createShadowRolloutCommands((name) => COMMANDS[name]),
+};
+export function listCommands() {
+    return Object.keys(COMMANDS).sort();
+}
+export async function maybeWriteOutput(response, args, context) {
+    const output = typeof args.output === "string" ? new URL(args.output, `file://${context.cwd}/`).pathname : undefined;
+    if (!output) {
+        return;
+    }
+    await fs.writeFile(output, JSON.stringify(response, null, 2), "utf8");
+}

package/dist/src/core/aggregate-fitness-core.d.ts

@@ -0,0 +1,24 @@
+import type { DomainModel, Evidence, Fragment, GlossaryTerm, InvariantCandidate, TermTraceLink } from "./contracts.js";
+import type { ProgressReporter } from "./progress.js";
+export interface AggregateFitnessResult {
+    SIC: number;
+    XTC: number;
+    confidence: number;
+    evidence: Evidence[];
+    unknowns: string[];
+    diagnostics: string[];
+    details: {
+        mappedInvariants: number;
+        localizedInvariants: number;
+        crossContextInvariants: number;
+        strongConsistencyInvariants: number;
+    };
+}
+export declare function computeAggregateFitness(input: {
+    model: DomainModel;
+    fragments: Fragment[];
+    terms: GlossaryTerm[];
+    links: TermTraceLink[];
+    invariants: InvariantCandidate[];
+    reportProgress?: ProgressReporter;
+}): AggregateFitnessResult;

package/dist/src/core/aggregate-fitness-core.js

@@ -0,0 +1,40 @@
+import { mapAggregateInvariants } from "./aggregate-fitness-mapping.js";
+import { scoreAggregateFitness } from "./aggregate-fitness-scoring.js";
+export function computeAggregateFitness(input) {
+    const aggregateDefinitions = input.model.aggregates ?? [];
+    const hasExplicitAggregates = aggregateDefinitions.length > 0;
+    const unknowns = hasExplicitAggregates
+        ? []
+        : ["No aggregate definitions were found, so context is being used as an aggregate proxy."];
+    input.reportProgress?.({
+        phase: "docs",
+        message: "AFS: mapping invariants to aggregates and contexts.",
+    });
+    const mappingResult = mapAggregateInvariants({
+        aggregateDefinitions,
+        fragments: input.fragments,
+        terms: input.terms,
+        links: input.links,
+        invariants: input.invariants,
+        model: input.model,
+        unknowns,
+        ...(input.reportProgress ? { reportProgress: input.reportProgress } : {}),
+    });
+    const diagnostics = mappingResult.skippedInvariants.length > 0
+        ? [
+            `Ignored ${mappingResult.skippedInvariants.length} acceptance-condition-like invariant(s) without aggregate anchors when computing AFS.`,
+        ]
+        : [];
+    input.reportProgress?.({
+        phase: "docs",
+        message: "AFS: scoring consistency and cross-transaction coordination signals.",
+    });
+    return scoreAggregateFitness({
+        model: input.model,
+        invariants: mappingResult.consideredInvariants,
+        aggregateDefinitions,
+        mappedInvariants: mappingResult.mappings,
+        unknowns,
+        diagnostics,
+    });
+}

package/dist/src/core/aggregate-fitness-evidence.d.ts

@@ -0,0 +1,2 @@
+import type { AggregateInvariantMapping } from "./aggregate-fitness-shared.js";
+export declare function buildAggregateFitnessEvidence(mappings: AggregateInvariantMapping[]): import("./contracts.js").Evidence[];

package/dist/src/core/aggregate-fitness-evidence.js

@@ -0,0 +1,24 @@
+import { clamp01 } from "./aggregate-fitness-shared.js";
+import { toEvidence } from "./response.js";
+export function buildAggregateFitnessEvidence(mappings) {
+    const evidence = [];
+    for (const entry of mappings.filter((mapping) => mapping.localityTargets.length === 1).slice(0, 4)) {
+        const localityLabel = entry.aggregateTargets[0] ?? entry.contexts[0];
+        evidence.push(toEvidence(`${entry.invariant.statement.slice(0, 120)} closes within ${localityLabel}`, {
+            invariantId: entry.invariant.invariantId,
+            contexts: entry.contexts,
+            localityTargets: entry.localityTargets,
+            fragmentIds: entry.invariant.fragmentIds,
+        }, [entry.invariant.invariantId], clamp01(entry.invariant.confidence)));
+    }
+    for (const entry of mappings.filter((mapping) => mapping.localityTargets.length > 1).slice(0, 4)) {
+        const localityLabel = entry.localityTargets.join(", ");
+        evidence.push(toEvidence(`${entry.invariant.statement.slice(0, 120)} spans ${localityLabel}`, {
+            invariantId: entry.invariant.invariantId,
+            contexts: entry.contexts,
+            localityTargets: entry.localityTargets,
+            fragmentIds: entry.invariant.fragmentIds,
+        }, [entry.invariant.invariantId], clamp01(Math.min(entry.invariant.confidence, 0.82))));
+    }
+    return evidence;
+}

package/dist/src/core/aggregate-fitness-mapping.d.ts

@@ -0,0 +1,17 @@
+import { type AggregateInvariantMapping } from "./aggregate-fitness-shared.js";
+import type { AggregateDefinition, DomainModel, Fragment, GlossaryTerm, InvariantCandidate, TermTraceLink } from "./contracts.js";
+import type { ProgressReporter } from "./progress.js";
+export declare function mapAggregateInvariants(input: {
+    aggregateDefinitions: AggregateDefinition[];
+    fragments: Fragment[];
+    terms: GlossaryTerm[];
+    links: TermTraceLink[];
+    invariants: InvariantCandidate[];
+    model: DomainModel;
+    unknowns: string[];
+    reportProgress?: ProgressReporter;
+}): {
+    mappings: AggregateInvariantMapping[];
+    consideredInvariants: InvariantCandidate[];
+    skippedInvariants: InvariantCandidate[];
+};

package/dist/src/core/aggregate-fitness-mapping.js

@@ -0,0 +1,57 @@
+import { collectAggregateTargets, localizationScore, } from "./aggregate-fitness-shared.js";
+import { buildFragmentContextMentions, collectStatementContexts, collectTermContexts } from "./boundary-fitness.js";
+import { INVARIANT_ACCEPTANCE_AMBIGUITY } from "./document-extractor-text-review.js";
+export function mapAggregateInvariants(input) {
+    const fragmentContextMentions = buildFragmentContextMentions(input.fragments, input.model);
+    const linkByTermId = new Map(input.links.map((link) => [link.termId, link]));
+    input.reportProgress?.({
+        phase: "docs",
+        message: "AFS: collecting glossary term contexts for aggregate mapping.",
+    });
+    const mappedTerms = input.terms
+        .map((term) => ({
+        labels: [term.canonicalTerm, ...(term.aliases ?? [])],
+        contexts: collectTermContexts(term, linkByTermId.get(term.termId), fragmentContextMentions, input.model),
+    }))
+        .filter((entry) => entry.contexts.length > 0);
+    let lastHeartbeatAt = Date.now();
+    const mappings = [];
+    const consideredInvariants = [];
+    const skippedInvariants = [];
+    for (const [index, invariant] of input.invariants.entries()) {
+        const now = Date.now();
+        if (now - lastHeartbeatAt >= 5000) {
+            input.reportProgress?.({
+                phase: "docs",
+                message: `AFS: mapped ${index}/${input.invariants.length} invariant candidate(s).`,
+                elapsedMs: now - lastHeartbeatAt,
+            });
+            lastHeartbeatAt = now;
+        }
+        const contexts = collectStatementContexts(invariant.statement, invariant.fragmentIds, fragmentContextMentions, mappedTerms, input.model);
+        const aggregateTargets = collectAggregateTargets(input.aggregateDefinitions, contexts, invariant, mappedTerms);
+        const shouldSkip = invariant.unknowns.includes(INVARIANT_ACCEPTANCE_AMBIGUITY) &&
+            (invariant.relatedTerms?.length ?? 0) === 0 &&
+            !aggregateTargets.hasAnchorEvidence;
+        if (shouldSkip) {
+            skippedInvariants.push(invariant);
+            continue;
+        }
+        const localityTargets = aggregateTargets.targets.length > 0 ? aggregateTargets.targets : contexts;
+        input.unknowns.push(...aggregateTargets.unknowns);
+        consideredInvariants.push(invariant);
+        mappings.push({
+            invariant,
+            contexts,
+            localityTargets,
+            localization: localizationScore(localityTargets),
+            usedContextProxy: aggregateTargets.targets.length === 0,
+            aggregateTargets: aggregateTargets.targets,
+        });
+    }
+    return {
+        mappings,
+        consideredInvariants,
+        skippedInvariants,
+    };
+}

package/dist/src/core/aggregate-fitness-scoring.d.ts

@@ -0,0 +1,24 @@
+import { type AggregateInvariantMapping } from "./aggregate-fitness-shared.js";
+import type { AggregateDefinition, DomainModel, Evidence, InvariantCandidate } from "./contracts.js";
+export interface AggregateFitnessScoringResult {
+    SIC: number;
+    XTC: number;
+    confidence: number;
+    evidence: Evidence[];
+    unknowns: string[];
+    diagnostics: string[];
+    details: {
+        mappedInvariants: number;
+        localizedInvariants: number;
+        crossContextInvariants: number;
+        strongConsistencyInvariants: number;
+    };
+}
+export declare function scoreAggregateFitness(input: {
+    model: DomainModel;
+    invariants: InvariantCandidate[];
+    aggregateDefinitions: AggregateDefinition[];
+    mappedInvariants: AggregateInvariantMapping[];
+    unknowns: string[];
+    diagnostics?: string[];
+}): AggregateFitnessScoringResult;

package/dist/src/core/aggregate-fitness-scoring.js

@@ -0,0 +1,71 @@
+import { buildAggregateFitnessEvidence } from "./aggregate-fitness-evidence.js";
+import { average, clamp01, impliesStrongConsistencyWrite, unique, } from "./aggregate-fitness-shared.js";
+export function scoreAggregateFitness(input) {
+    const hasExplicitAggregates = input.aggregateDefinitions.length > 0;
+    const diagnostics = [...(input.diagnostics ?? [])];
+    const localizedInvariants = input.mappedInvariants.filter((entry) => entry.localityTargets.length === 1);
+    const crossContextInvariants = input.mappedInvariants.filter((entry) => entry.localityTargets.length > 1);
+    const mappedInvariantCount = input.mappedInvariants.filter((entry) => entry.localityTargets.length > 0).length;
+    const sicSignals = input.mappedInvariants.map((entry) => entry.localization * entry.invariant.confidence);
+    const sicWeights = input.mappedInvariants.map((entry) => entry.invariant.confidence);
+    const SIC = input.mappedInvariants.length === 0
+        ? 0.45
+        : clamp01(sicSignals.reduce((sum, value) => sum + value, 0) /
+            Math.max(0.0001, sicWeights.reduce((sum, value) => sum + value, 0)));
+    if (mappedInvariantCount === 0) {
+        input.unknowns.push("Invariant responsibility assignment could not be observed, so SIC is provisional.");
+    }
+    else if (mappedInvariantCount < input.invariants.length) {
+        input.unknowns.push("Some invariants could not be mapped to contexts, so SIC is approximate.");
+    }
+    if (hasExplicitAggregates &&
+        input.mappedInvariants.some((entry) => entry.usedContextProxy && entry.contexts.length > 0)) {
+        input.unknowns.push("Some invariants could not be mapped to explicit aggregates, so context proxy was retained.");
+    }
+    const strongConsistencyInvariants = input.mappedInvariants.filter((entry) => impliesStrongConsistencyWrite(entry.invariant.statement));
+    let XTC = 0.25;
+    if (strongConsistencyInvariants.length === 0) {
+        input.unknowns.push("There are too few strong-consistency invariants to support a strong XTC judgment.");
+    }
+    else {
+        const xtcSignals = strongConsistencyInvariants.map((entry) => {
+            if (entry.localityTargets.length > 1) {
+                return 1 * entry.invariant.confidence;
+            }
+            if (entry.localityTargets.length === 0) {
+                return 0.5 * entry.invariant.confidence;
+            }
+            return 0;
+        });
+        const xtcWeights = strongConsistencyInvariants.map((entry) => entry.invariant.confidence);
+        XTC = clamp01(xtcSignals.reduce((sum, value) => sum + value, 0) /
+            Math.max(0.0001, xtcWeights.reduce((sum, value) => sum + value, 0)));
+    }
+    const confidence = clamp01(average([
+        average(input.invariants.map((invariant) => invariant.confidence), 0.5),
+        mappedInvariantCount > 0 ? 0.78 : 0.45,
+        strongConsistencyInvariants.length > 0 ? 0.76 : 0.55,
+        hasExplicitAggregates ? 0.84 : input.model.contexts.length >= 2 ? 0.82 : 0.4,
+        hasExplicitAggregates &&
+            input.mappedInvariants.every((entry) => !entry.usedContextProxy || entry.contexts.length === 0)
+            ? 0.8
+            : 0.6,
+    ], 0.55));
+    if (hasExplicitAggregates) {
+        diagnostics.push(`Used ${input.aggregateDefinitions.length} explicit aggregate definition(s) across ${unique(input.aggregateDefinitions.map((aggregate) => aggregate.context)).length} context(s).`);
+    }
+    return {
+        SIC,
+        XTC,
+        confidence,
+        evidence: buildAggregateFitnessEvidence(input.mappedInvariants),
+        unknowns: unique(input.unknowns),
+        diagnostics,
+        details: {
+            mappedInvariants: mappedInvariantCount,
+            localizedInvariants: localizedInvariants.length,
+            crossContextInvariants: crossContextInvariants.length,
+            strongConsistencyInvariants: strongConsistencyInvariants.length,
+        },
+    };
+}

package/dist/src/core/aggregate-fitness-shared.d.ts

@@ -0,0 +1,21 @@
+import type { AggregateDefinition, InvariantCandidate } from "./contracts.js";
+import { average, clamp01Finite as clamp01, unique } from "./shared-utils.js";
+export interface AggregateInvariantMapping {
+    invariant: InvariantCandidate;
+    contexts: string[];
+    localityTargets: string[];
+    localization: number;
+    usedContextProxy: boolean;
+    aggregateTargets: string[];
+}
+export { average, clamp01, unique };
+export declare function localizationScore(contexts: string[]): number;
+export declare function impliesStrongConsistencyWrite(statement: string): boolean;
+export declare function collectAggregateTargets(aggregateDefinitions: AggregateDefinition[], contexts: string[], invariant: InvariantCandidate, mappedTerms?: Array<{
+    labels: string[];
+    contexts: string[];
+}>): {
+    targets: string[];
+    unknowns: string[];
+    hasAnchorEvidence: boolean;
+};