context-probe 0.1.0

package/dist/src/analyzers/architecture-observation-ingest-telemetry.js

@@ -0,0 +1,71 @@
+import { average, clamp01, unique } from "./architecture-observation-ingest-shared.js";
+export function ingestTelemetryExportBundle(bundle) {
+    const findings = [];
+    const unknowns = [];
+    const confidenceSignals = [];
+    const bands = bundle.bands.map((band) => {
+        const rawBand = {
+            bandId: band.bandId,
+            trafficWeight: band.trafficWeight,
+            ...(band.latencyP95 !== undefined ? { latencyP95: band.latencyP95 } : {}),
+            ...(band.errorRate !== undefined ? { errorRate: band.errorRate } : {}),
+            ...(band.saturationRatio !== undefined ? { saturationRatio: band.saturationRatio } : {}),
+        };
+        const mappings = [
+            { component: "latencyP95", observed: band.latencyP95 },
+            { component: "errorRate", observed: band.errorRate },
+            { component: "saturationRatio", observed: band.saturationRatio },
+        ];
+        for (const mapping of mappings) {
+            if (mapping.observed === undefined) {
+                unknowns.push(`The telemetry export for ${band.bandId} is missing ${mapping.component}.`);
+                findings.push({
+                    kind: "telemetry_export_missing_signal",
+                    confidence: 0.62,
+                    note: `The telemetry export for ${band.bandId} is missing ${mapping.component}.`,
+                    bandId: band.bandId,
+                    component: mapping.component,
+                    ...(bundle.sourceSystem ? { sourceSystem: bundle.sourceSystem } : {}),
+                    ...(band.window ? { window: band.window } : {}),
+                });
+                confidenceSignals.push(0.55);
+                continue;
+            }
+            findings.push({
+                kind: "telemetry_export_band_mapped",
+                confidence: 0.84,
+                note: `Imported ${mapping.component} for ${band.bandId} from the telemetry export into raw telemetry input.`,
+                bandId: band.bandId,
+                component: mapping.component,
+                observed: mapping.observed,
+                ...(bundle.sourceSystem ? { sourceSystem: bundle.sourceSystem } : {}),
+                ...(band.window ? { window: band.window } : {}),
+            });
+            confidenceSignals.push(0.84);
+        }
+        return rawBand;
+    });
+    if (bands.length === 0) {
+        unknowns.push("The telemetry export bundle has no traffic bands, so CommonOps for OAS is close to unobserved.");
+        confidenceSignals.push(0.3);
+    }
+    if (bundle.patternRuntime) {
+        findings.push({
+            kind: "telemetry_export_pattern_runtime_embedded",
+            confidence: 0.8,
+            note: "Pattern runtime observations included in the telemetry export bundle are available.",
+            ...(bundle.sourceSystem ? { sourceSystem: bundle.sourceSystem } : {}),
+        });
+        confidenceSignals.push(0.8);
+    }
+    return {
+        telemetryRawObservations: {
+            version: bundle.version,
+            bands,
+        },
+        ...(bundle.patternRuntime ? { patternRuntimeObservations: bundle.patternRuntime } : {}),
+        confidence: clamp01(average(confidenceSignals, 0.6)),
+        unknowns: unique(unknowns),
+        findings,
+    };
+}

package/dist/src/analyzers/architecture-observation-ingest.d.ts

@@ -0,0 +1,5 @@
+export type { IngestedDeliveryExport } from "./architecture-observation-ingest-delivery.js";
+export { ingestDeliveryExportBundle } from "./architecture-observation-ingest-delivery.js";
+export type { ObservationIngestFinding } from "./architecture-observation-ingest-shared.js";
+export type { IngestedTelemetryExport } from "./architecture-observation-ingest-telemetry.js";
+export { ingestTelemetryExportBundle } from "./architecture-observation-ingest-telemetry.js";

package/dist/src/analyzers/architecture-observation-ingest.js

@@ -0,0 +1,2 @@
+export { ingestDeliveryExportBundle } from "./architecture-observation-ingest-delivery.js";
+export { ingestTelemetryExportBundle } from "./architecture-observation-ingest-telemetry.js";

package/dist/src/analyzers/architecture-observation-normalization-shared.d.ts

@@ -0,0 +1,10 @@
+import type { ScenarioDirection } from "../core/contracts.js";
+export declare function clamp01(value: number): number;
+export declare function average(values: number[], fallback: number): number;
+export declare function uniqueUnknowns(values: string[]): string[];
+export declare function normalizeObservedValue(input: {
+    direction: ScenarioDirection;
+    observed: number;
+    target: number;
+    worstAcceptable: number;
+}): number;

package/dist/src/analyzers/architecture-observation-normalization-shared.js

@@ -0,0 +1,19 @@
+export function clamp01(value) {
+    return Math.max(0, Math.min(1, Number.isFinite(value) ? value : 0));
+}
+export function average(values, fallback) {
+    if (values.length === 0) {
+        return fallback;
+    }
+    return values.reduce((sum, value) => sum + value, 0) / values.length;
+}
+export function uniqueUnknowns(values) {
+    return Array.from(new Set(values));
+}
+export function normalizeObservedValue(input) {
+    const { direction, observed, target, worstAcceptable } = input;
+    if (direction === "lower_is_better") {
+        return clamp01((worstAcceptable - observed) / Math.max(0.0001, worstAcceptable - target));
+    }
+    return clamp01((observed - worstAcceptable) / Math.max(0.0001, target - worstAcceptable));
+}

package/dist/src/analyzers/architecture-operations-common-ops.d.ts

@@ -0,0 +1,16 @@
+import type { ArchitectureTelemetryObservationSet } from "../core/contracts.js";
+export interface CommonOpsFinding {
+    kind: "missing_band_signal" | "weak_common_ops";
+    confidence: number;
+    note: string;
+    bandId?: string;
+    component?: "LatencyScore" | "ErrorScore" | "SaturationScore";
+}
+export interface CommonOpsScoreResult {
+    CommonOps: number;
+    bandCount: number;
+    weightedBandCoverage: number;
+    unknowns: string[];
+    findings: CommonOpsFinding[];
+}
+export declare function scoreCommonOperations(telemetry: ArchitectureTelemetryObservationSet | undefined): CommonOpsScoreResult;

package/dist/src/analyzers/architecture-operations-common-ops.js

@@ -0,0 +1,76 @@
+function clamp01(value) {
+    return Math.max(0, Math.min(1, Number.isFinite(value) ? value : 0));
+}
+function weightedAverage(entries, fallback) {
+    const observed = entries.filter((entry) => entry.value !== undefined && Number.isFinite(entry.value));
+    if (observed.length === 0) {
+        return fallback;
+    }
+    const totalWeight = observed.reduce((sum, entry) => sum + entry.weight, 0);
+    if (totalWeight <= 0) {
+        return fallback;
+    }
+    return observed.reduce((sum, entry) => sum + (entry.value ?? 0) * entry.weight, 0) / totalWeight;
+}
+function uniqueUnknowns(values) {
+    return Array.from(new Set(values));
+}
+export function scoreCommonOperations(telemetry) {
+    const findings = [];
+    const unknowns = [];
+    const bands = telemetry?.bands ?? [];
+    const totalTrafficWeight = bands.reduce((sum, band) => sum + Math.max(0, band.trafficWeight), 0);
+    let weightedBandScore = 0;
+    let weightedCoverage = 0;
+    for (const band of bands) {
+        const signalEntries = [
+            { component: "LatencyScore", weight: 0.45, value: band.LatencyScore },
+            { component: "ErrorScore", weight: 0.35, value: band.ErrorScore },
+            { component: "SaturationScore", weight: 0.2, value: band.SaturationScore },
+        ];
+        const bandCoverage = signalEntries.reduce((sum, entry) => sum + (entry.value !== undefined ? entry.weight : 0), 0);
+        const bandScore = weightedAverage(signalEntries.map((entry) => ({
+            value: entry.value,
+            weight: entry.weight,
+        })), 0.5);
+        const trafficWeight = Math.max(0, band.trafficWeight);
+        weightedBandScore += bandScore * trafficWeight;
+        weightedCoverage += bandCoverage * trafficWeight;
+        for (const entry of signalEntries) {
+            if (entry.value !== undefined) {
+                continue;
+            }
+            unknowns.push(`${band.bandId} is missing ${entry.component}, so CommonOps is only a partial approximation.`);
+            findings.push({
+                kind: "missing_band_signal",
+                bandId: band.bandId,
+                component: entry.component,
+                confidence: 0.66,
+                note: `${band.bandId} is missing ${entry.component}.`,
+            });
+        }
+        if (bandScore < 0.6) {
+            findings.push({
+                kind: "weak_common_ops",
+                bandId: band.bandId,
+                confidence: 0.8,
+                note: `${band.bandId} has a low common-operations score (${bandScore.toFixed(3)}), so runtime behavior is unstable.`,
+            });
+        }
+    }
+    const CommonOps = totalTrafficWeight > 0 ? clamp01(weightedBandScore / totalTrafficWeight) : 0.5;
+    const weightedBandCoverage = totalTrafficWeight > 0 ? clamp01(weightedCoverage / totalTrafficWeight) : 0;
+    if (bands.length === 0) {
+        unknowns.push("No telemetry observations were provided, so CommonOps is using the neutral value 0.5.");
+    }
+    else if (weightedBandCoverage < 1) {
+        unknowns.push("Some traffic-band signals are missing, so CommonOps is only a partial approximation.");
+    }
+    return {
+        CommonOps,
+        bandCount: bands.length,
+        weightedBandCoverage,
+        unknowns: uniqueUnknowns(unknowns),
+        findings,
+    };
+}

package/dist/src/analyzers/architecture-operations.d.ts

@@ -0,0 +1,27 @@
+import type { ArchitecturePatternFamily, ArchitecturePatternRuntimeObservationSet, ArchitectureTelemetryObservationSet } from "../core/contracts.js";
+import { type CommonOpsFinding } from "./architecture-operations-common-ops.js";
+import { type PatternRuntimeSource } from "./architecture-pattern-runtime.js";
+export interface OperationalAdequacyFinding {
+    kind: CommonOpsFinding["kind"] | "missing_pattern_runtime" | "weak_pattern_runtime" | "pattern_runtime_signal_missing" | "pattern_runtime_family_mismatch" | "pattern_runtime_multiple_blocks" | "pattern_runtime_legacy_overridden" | "pattern_runtime_legacy_used" | "pattern_runtime_tis_bridge" | "pattern_runtime_neutral";
+    confidence: number;
+    note: string;
+    bandId?: string;
+    component?: "LatencyScore" | "ErrorScore" | "SaturationScore";
+    patternFamily?: ArchitecturePatternFamily;
+    signal?: string;
+    source?: PatternRuntimeSource;
+}
+export interface OperationalAdequacyScore {
+    CommonOps: number;
+    PatternRuntime: number;
+    bandCount: number;
+    weightedBandCoverage: number;
+    confidence: number;
+    unknowns: string[];
+    findings: OperationalAdequacyFinding[];
+}
+export declare function scoreOperationalAdequacy(input: {
+    telemetry?: ArchitectureTelemetryObservationSet;
+    patternRuntime?: ArchitecturePatternRuntimeObservationSet;
+    topologyIsolationBridge?: number;
+}): OperationalAdequacyScore;

package/dist/src/analyzers/architecture-operations.js

@@ -0,0 +1,56 @@
+import { scoreCommonOperations } from "./architecture-operations-common-ops.js";
+import { scorePatternRuntime } from "./architecture-pattern-runtime.js";
+export function scoreOperationalAdequacy(input) {
+    const commonOps = scoreCommonOperations(input.telemetry);
+    const findings = [...commonOps.findings];
+    const unknowns = [...commonOps.unknowns];
+    const patternRuntimeScore = scorePatternRuntime({
+        ...(input.patternRuntime ? { observations: input.patternRuntime } : {}),
+        ...(input.topologyIsolationBridge !== undefined ? { topologyIsolationBridge: input.topologyIsolationBridge } : {}),
+    });
+    const patternRuntimeSourceConfidence = patternRuntimeScore.confidence;
+    const PatternRuntime = patternRuntimeScore.value;
+    unknowns.push(...patternRuntimeScore.unknowns);
+    findings.push(...patternRuntimeScore.findings.map((finding) => {
+        const kind = finding.kind === "pattern_runtime_tis_bridge" || finding.kind === "pattern_runtime_neutral"
+            ? "missing_pattern_runtime"
+            : finding.kind;
+        const mapped = {
+            kind,
+            confidence: finding.confidence,
+            note: finding.note,
+        };
+        if (finding.patternFamily) {
+            mapped.patternFamily = finding.patternFamily;
+        }
+        if (finding.signal) {
+            mapped.signal = finding.signal;
+        }
+        if (finding.source) {
+            mapped.source = finding.source;
+        }
+        return mapped;
+    }));
+    if (PatternRuntime < 0.6) {
+        findings.push({
+            kind: "weak_pattern_runtime",
+            confidence: 0.78,
+            note: `PatternRuntime is low at ${PatternRuntime.toFixed(3)}, so pattern-specific runtime adequacy is weak.`,
+            ...(patternRuntimeScore.patternFamily ? { patternFamily: patternRuntimeScore.patternFamily } : {}),
+            source: patternRuntimeScore.source,
+        });
+    }
+    return {
+        CommonOps: commonOps.CommonOps,
+        PatternRuntime,
+        bandCount: commonOps.bandCount,
+        weightedBandCoverage: commonOps.weightedBandCoverage,
+        confidence: Math.max(0, Math.min(1, [
+            commonOps.bandCount > 0 ? 0.82 : 0.35,
+            commonOps.bandCount > 0 ? 0.45 + commonOps.weightedBandCoverage * 0.4 : 0.35,
+            patternRuntimeSourceConfidence,
+        ].reduce((sum, value) => sum + value, 0) / 3)),
+        unknowns: Array.from(new Set(unknowns)),
+        findings,
+    };
+}

package/dist/src/analyzers/architecture-pattern-runtime-fallback.d.ts

@@ -0,0 +1,8 @@
+import type { ArchitecturePatternRuntimeObservationSet } from "../core/contracts.js";
+import { type PatternRuntimeFinding, type PatternRuntimeResolution } from "./architecture-pattern-runtime-shared.js";
+export declare function resolveFallbackPatternRuntime(input: {
+    observations: ArchitecturePatternRuntimeObservationSet | undefined;
+    topologyIsolationBridge?: number;
+    findings: PatternRuntimeFinding[];
+    unknowns: string[];
+}): PatternRuntimeResolution;

package/dist/src/analyzers/architecture-pattern-runtime-fallback.js

@@ -0,0 +1,79 @@
+import { clamp01, unique, } from "./architecture-pattern-runtime-shared.js";
+export function resolveFallbackPatternRuntime(input) {
+    const { observations, topologyIsolationBridge, findings, unknowns } = input;
+    if (observations?.score !== undefined) {
+        const finding = {
+            kind: "pattern_runtime_legacy_used",
+            confidence: 0.76,
+            note: "The legacy pattern runtime score is being used as-is.",
+            source: "legacy",
+        };
+        if (observations.patternFamily) {
+            finding.patternFamily = observations.patternFamily;
+        }
+        findings.push(finding);
+        const result = {
+            value: clamp01(observations.score),
+            confidence: 0.76,
+            unknowns: unique(unknowns),
+            findings,
+            source: "legacy",
+            usedSignals: [],
+            missingSignals: [],
+        };
+        if (observations.patternFamily) {
+            result.patternFamily = observations.patternFamily;
+        }
+        return result;
+    }
+    if (topologyIsolationBridge !== undefined) {
+        unknowns.push("No pattern runtime observations were provided, so PatternRuntime is using the TIS bridge.");
+        const finding = {
+            kind: "pattern_runtime_tis_bridge",
+            confidence: 0.68,
+            note: "Pattern runtime observations are missing, so the TIS bridge is being used for PatternRuntime.",
+            source: "tis_bridge",
+        };
+        if (observations?.patternFamily) {
+            finding.patternFamily = observations.patternFamily;
+        }
+        findings.push(finding);
+        const result = {
+            value: clamp01(topologyIsolationBridge),
+            confidence: 0.62,
+            unknowns: unique(unknowns),
+            findings,
+            source: "tis_bridge",
+            usedSignals: [],
+            missingSignals: [],
+        };
+        if (observations?.patternFamily) {
+            result.patternFamily = observations.patternFamily;
+        }
+        return result;
+    }
+    unknowns.push("No pattern runtime observations were provided, so PatternRuntime is using the neutral value 0.5.");
+    const finding = {
+        kind: "pattern_runtime_neutral",
+        confidence: 0.62,
+        note: "Pattern runtime observations are missing, so PatternRuntime is close to unobserved.",
+        source: "neutral",
+    };
+    if (observations?.patternFamily) {
+        finding.patternFamily = observations.patternFamily;
+    }
+    findings.push(finding);
+    const result = {
+        value: 0.5,
+        confidence: 0.35,
+        unknowns: unique(unknowns),
+        findings,
+        source: "neutral",
+        usedSignals: [],
+        missingSignals: [],
+    };
+    if (observations?.patternFamily) {
+        result.patternFamily = observations.patternFamily;
+    }
+    return result;
+}

package/dist/src/analyzers/architecture-pattern-runtime-family.d.ts

@@ -0,0 +1,7 @@
+import type { ArchitecturePatternRuntimeObservationSet } from "../core/contracts.js";
+import { type PatternRuntimeFinding, type PatternRuntimeResolution } from "./architecture-pattern-runtime-shared.js";
+export declare function resolveFamilyPatternRuntime(input: {
+    observations: ArchitecturePatternRuntimeObservationSet | undefined;
+    findings: PatternRuntimeFinding[];
+    unknowns: string[];
+}): PatternRuntimeResolution | undefined;

package/dist/src/analyzers/architecture-pattern-runtime-family.js

@@ -0,0 +1,56 @@
+import { clamp01, resolveSelectedSpec, unique, weightedObservedAverage, } from "./architecture-pattern-runtime-shared.js";
+export function resolveFamilyPatternRuntime(input) {
+    const { observations, findings, unknowns } = input;
+    const selected = resolveSelectedSpec({ observations, findings, unknowns });
+    if (!selected.spec || !selected.block) {
+        return undefined;
+    }
+    const weighted = weightedObservedAverage(selected.block, selected.spec.weights);
+    for (const signal of weighted.missingSignals) {
+        unknowns.push(`${selected.spec.blockName} is missing ${signal}, so PatternRuntime is only a partial approximation.`);
+        const finding = {
+            kind: "pattern_runtime_signal_missing",
+            confidence: 0.68,
+            note: `${selected.spec.blockName} is missing ${signal}.`,
+            signal,
+            source: "family",
+        };
+        if (selected.family) {
+            finding.patternFamily = selected.family;
+        }
+        findings.push(finding);
+    }
+    if (observations?.score !== undefined) {
+        unknowns.push("Family-specific pattern runtime data took precedence over the legacy score.");
+        const finding = {
+            kind: "pattern_runtime_legacy_overridden",
+            confidence: 0.74,
+            note: "The family-specific pattern runtime block was prioritized and the legacy score was treated as supplemental.",
+            source: "family",
+        };
+        if (selected.family) {
+            finding.patternFamily = selected.family;
+        }
+        findings.push(finding);
+    }
+    const mismatchPenalty = findings.some((finding) => finding.kind === "pattern_runtime_family_mismatch") ? 0.3 : 0;
+    const multiplePenalty = findings.some((finding) => finding.kind === "pattern_runtime_multiple_blocks") ? 0.12 : 0;
+    const confidence = clamp01(0.42 +
+        weighted.coverage * 0.4 +
+        (selected.family && selected.spec.families.includes(selected.family) ? 0.08 : 0) -
+        mismatchPenalty -
+        multiplePenalty);
+    const result = {
+        value: weighted.value,
+        confidence,
+        unknowns: unique(unknowns),
+        findings,
+        source: "family",
+        usedSignals: weighted.usedSignals,
+        missingSignals: weighted.missingSignals,
+    };
+    if (selected.family) {
+        result.patternFamily = selected.family;
+    }
+    return result;
+}

package/dist/src/analyzers/architecture-pattern-runtime-normalization-blocks.d.ts

@@ -0,0 +1,12 @@
+import type { ArchitecturePatternRuntimeNormalizationProfile, ArchitecturePatternRuntimeRawObservationSet } from "../core/contracts.js";
+export type PatternRuntimeNormalizationBlockName = "layeredRuntime" | "serviceBasedRuntime" | "cqrsRuntime" | "eventDrivenRuntime";
+export interface PatternRuntimeNormalizationBlockSpec {
+    blockName: PatternRuntimeNormalizationBlockName;
+    rawBlock: ArchitecturePatternRuntimeRawObservationSet[PatternRuntimeNormalizationBlockName];
+    profileBlock: ArchitecturePatternRuntimeNormalizationProfile[PatternRuntimeNormalizationBlockName];
+    mappings: Array<{
+        rawSignal: string;
+        scoreSignal: string;
+    }>;
+}
+export declare const PATTERN_RUNTIME_NORMALIZATION_BLOCK_SPECS: readonly PatternRuntimeNormalizationBlockSpec[];

package/dist/src/analyzers/architecture-pattern-runtime-normalization-blocks.js

@@ -0,0 +1,41 @@
+export const PATTERN_RUNTIME_NORMALIZATION_BLOCK_SPECS = [
+    {
+        blockName: "layeredRuntime",
+        rawBlock: undefined,
+        profileBlock: undefined,
+        mappings: [
+            { rawSignal: "FailureContainment", scoreSignal: "FailureContainmentScore" },
+            { rawSignal: "DependencyIsolation", scoreSignal: "DependencyIsolationScore" },
+        ],
+    },
+    {
+        blockName: "serviceBasedRuntime",
+        rawBlock: undefined,
+        profileBlock: undefined,
+        mappings: [
+            { rawSignal: "PartialFailureContainment", scoreSignal: "PartialFailureContainmentScore" },
+            { rawSignal: "RetryAmplification", scoreSignal: "RetryAmplificationScore" },
+            { rawSignal: "SyncHopDepth", scoreSignal: "SyncHopDepthScore" },
+        ],
+    },
+    {
+        blockName: "cqrsRuntime",
+        rawBlock: undefined,
+        profileBlock: undefined,
+        mappings: [
+            { rawSignal: "ProjectionFreshness", scoreSignal: "ProjectionFreshnessScore" },
+            { rawSignal: "ReplayDivergence", scoreSignal: "ReplayDivergenceScore" },
+            { rawSignal: "StaleReadAcceptability", scoreSignal: "StaleReadAcceptabilityScore" },
+        ],
+    },
+    {
+        blockName: "eventDrivenRuntime",
+        rawBlock: undefined,
+        profileBlock: undefined,
+        mappings: [
+            { rawSignal: "DeadLetterHealth", scoreSignal: "DeadLetterHealthScore" },
+            { rawSignal: "ConsumerLag", scoreSignal: "ConsumerLagScore" },
+            { rawSignal: "ReplayRecovery", scoreSignal: "ReplayRecoveryScore" },
+        ],
+    },
+];

package/dist/src/analyzers/architecture-pattern-runtime-normalization-math.d.ts

@@ -0,0 +1,10 @@
+import type { ScenarioDirection } from "../core/contracts.js";
+export declare function clamp01(value: number): number;
+export declare function average(values: number[], fallback: number): number;
+export declare function uniqueUnknowns(values: string[]): string[];
+export declare function normalizeObservedValue(input: {
+    direction: ScenarioDirection;
+    observed: number;
+    target: number;
+    worstAcceptable: number;
+}): number;

package/dist/src/analyzers/architecture-pattern-runtime-normalization-math.js

@@ -0,0 +1,19 @@
+export function clamp01(value) {
+    return Math.max(0, Math.min(1, Number.isFinite(value) ? value : 0));
+}
+export function average(values, fallback) {
+    if (values.length === 0) {
+        return fallback;
+    }
+    return values.reduce((sum, value) => sum + value, 0) / values.length;
+}
+export function uniqueUnknowns(values) {
+    return Array.from(new Set(values));
+}
+export function normalizeObservedValue(input) {
+    const { direction, observed, target, worstAcceptable } = input;
+    if (direction === "lower_is_better") {
+        return clamp01((worstAcceptable - observed) / Math.max(0.0001, worstAcceptable - target));
+    }
+    return clamp01((observed - worstAcceptable) / Math.max(0.0001, target - worstAcceptable));
+}

package/dist/src/analyzers/architecture-pattern-runtime-normalization.d.ts

@@ -0,0 +1,21 @@
+import type { ArchitecturePatternRuntimeNormalizationProfile, ArchitecturePatternRuntimeObservationSet, ArchitecturePatternRuntimeRawObservationSet } from "../core/contracts.js";
+export interface PatternRuntimeNormalizationFinding {
+    kind: "normalized_signal" | "missing_raw_signal" | "missing_normalization_rule";
+    confidence: number;
+    note: string;
+    block: "layeredRuntime" | "serviceBasedRuntime" | "cqrsRuntime" | "eventDrivenRuntime";
+    rawSignal: string;
+    scoreSignal: string;
+    observed?: number;
+    normalized?: number;
+}
+export interface NormalizedPatternRuntimeResult {
+    patternRuntimeObservations: ArchitecturePatternRuntimeObservationSet;
+    confidence: number;
+    unknowns: string[];
+    findings: PatternRuntimeNormalizationFinding[];
+}
+export declare function normalizePatternRuntimeObservations(input: {
+    raw?: ArchitecturePatternRuntimeRawObservationSet;
+    profile?: ArchitecturePatternRuntimeNormalizationProfile;
+}): NormalizedPatternRuntimeResult;

package/dist/src/analyzers/architecture-pattern-runtime-normalization.js

@@ -0,0 +1,103 @@
+import { PATTERN_RUNTIME_NORMALIZATION_BLOCK_SPECS } from "./architecture-pattern-runtime-normalization-blocks.js";
+import { average, clamp01, normalizeObservedValue, uniqueUnknowns, } from "./architecture-pattern-runtime-normalization-math.js";
+export function normalizePatternRuntimeObservations(input) {
+    const findings = [];
+    const unknowns = [];
+    const raw = input.raw;
+    const profile = input.profile;
+    if (!raw) {
+        return {
+            patternRuntimeObservations: {
+                version: "1.0",
+            },
+            confidence: 0.25,
+            unknowns: ["No pattern-runtime raw observations were provided, so raw normalization is unobserved."],
+            findings,
+        };
+    }
+    if (!profile) {
+        return {
+            patternRuntimeObservations: {
+                version: raw.version,
+                ...(raw.patternFamily ? { patternFamily: raw.patternFamily } : {}),
+                ...(raw.source ? { source: raw.source } : {}),
+                ...(raw.note ? { note: raw.note } : {}),
+            },
+            confidence: 0.3,
+            unknowns: ["No pattern-runtime normalization profile was provided, so raw runtime cannot be scored."],
+            findings,
+        };
+    }
+    let observedSignals = 0;
+    let possibleSignals = 0;
+    const normalized = {
+        version: raw.version,
+        ...(raw.patternFamily ? { patternFamily: raw.patternFamily } : {}),
+        ...(raw.source ? { source: raw.source } : {}),
+        ...(raw.note ? { note: raw.note } : {}),
+    };
+    for (const blockSpec of PATTERN_RUNTIME_NORMALIZATION_BLOCK_SPECS) {
+        const rawBlock = raw[blockSpec.blockName];
+        const profileBlock = profile[blockSpec.blockName];
+        if (!rawBlock) {
+            continue;
+        }
+        const normalizedBlock = {};
+        for (const mapping of blockSpec.mappings) {
+            possibleSignals += 1;
+            const rule = profileBlock?.[mapping.rawSignal];
+            const observed = rawBlock[mapping.rawSignal];
+            if (!rule) {
+                unknowns.push(`${blockSpec.blockName} is missing a normalization rule for ${mapping.rawSignal}.`);
+                findings.push({
+                    kind: "missing_normalization_rule",
+                    block: blockSpec.blockName,
+                    rawSignal: mapping.rawSignal,
+                    scoreSignal: mapping.scoreSignal,
+                    confidence: 0.58,
+                    note: `${blockSpec.blockName} has no rule to normalize ${mapping.rawSignal}.`,
+                });
+                continue;
+            }
+            if (observed === undefined) {
+                unknowns.push(`${blockSpec.blockName} is missing the raw ${mapping.rawSignal} signal.`);
+                findings.push({
+                    kind: "missing_raw_signal",
+                    block: blockSpec.blockName,
+                    rawSignal: mapping.rawSignal,
+                    scoreSignal: mapping.scoreSignal,
+                    confidence: 0.62,
+                    note: `${blockSpec.blockName} is missing the raw ${mapping.rawSignal} signal.`,
+                });
+                continue;
+            }
+            const normalizedValue = normalizeObservedValue({
+                direction: rule.direction,
+                observed,
+                target: rule.target,
+                worstAcceptable: rule.worstAcceptable,
+            });
+            normalizedBlock[mapping.scoreSignal] = normalizedValue;
+            observedSignals += 1;
+            findings.push({
+                kind: "normalized_signal",
+                block: blockSpec.blockName,
+                rawSignal: mapping.rawSignal,
+                scoreSignal: mapping.scoreSignal,
+                observed,
+                normalized: normalizedValue,
+                confidence: 0.86,
+                note: `${blockSpec.blockName} normalized ${mapping.rawSignal} from raw runtime to ${normalizedValue.toFixed(3)}.`,
+            });
+        }
+        if (Object.keys(normalizedBlock).length > 0) {
+            normalized[blockSpec.blockName] = normalizedBlock;
+        }
+    }
+    return {
+        patternRuntimeObservations: normalized,
+        confidence: clamp01(average([possibleSignals > 0 ? 0.82 : 0.25, observedSignals / Math.max(1, possibleSignals), 0.84], 0.35)),
+        unknowns: uniqueUnknowns(unknowns),
+        findings,
+    };
+}