context-probe 0.1.0

package/dist/src/command-history.js

@@ -0,0 +1,61 @@
+import { getProfile, getRootPath, requireDomainModel } from "./command-helpers.js";
+import { analyzeCochangePersistence, compareEvolutionLocalityModels, evaluateEvolutionLocalityObservationQuality, normalizeHistory, scoreEvolutionLocality, } from "./core/history.js";
+import { loadPolicyConfig } from "./core/policy.js";
+import { createResponse, toProvenance } from "./core/response.js";
+export function createHistoryCommands() {
+    return {
+        async "ingest.normalize_history"(args, context) {
+            const policyConfig = await loadPolicyConfig(typeof args.policy === "string" ? args.policy : undefined);
+            const model = typeof args.model === "string" ? await requireDomainModel(args, context) : undefined;
+            const commits = await normalizeHistory(getRootPath(args, context), policyConfig, getProfile(args), {
+                ...(model ? { includePathGlobs: model.contexts.flatMap((entry) => entry.pathGlobs) } : {}),
+            });
+            return createResponse({ commits }, { provenance: [toProvenance(context.cwd, "history_registry")] });
+        },
+        async "history.mine_cochange"(args, context) {
+            const policyConfig = await loadPolicyConfig(typeof args.policy === "string" ? args.policy : undefined);
+            const model = typeof args.model === "string" ? await requireDomainModel(args, context) : undefined;
+            const commits = await normalizeHistory(getRootPath(args, context), policyConfig, getProfile(args), {
+                ...(model ? { includePathGlobs: model.contexts.flatMap((entry) => entry.pathGlobs) } : {}),
+            });
+            return createResponse({ commits });
+        },
+        async "history.score_evolution_locality"(args, context) {
+            const policyConfig = await loadPolicyConfig(typeof args.policy === "string" ? args.policy : undefined);
+            const model = await requireDomainModel(args, context);
+            const commits = await normalizeHistory(getRootPath(args, context), policyConfig, getProfile(args), {
+                includePathGlobs: model.contexts.flatMap((entry) => entry.pathGlobs),
+            });
+            const analysis = scoreEvolutionLocality(commits, model);
+            const quality = evaluateEvolutionLocalityObservationQuality(commits, model);
+            return createResponse(analysis, {
+                confidence: quality.confidence,
+                unknowns: quality.unknowns,
+            });
+        },
+        async "history.analyze_persistence"(args, context) {
+            const policyConfig = await loadPolicyConfig(typeof args.policy === "string" ? args.policy : undefined);
+            const model = await requireDomainModel(args, context);
+            const commits = await normalizeHistory(getRootPath(args, context), policyConfig, getProfile(args), {
+                includePathGlobs: model.contexts.flatMap((entry) => entry.pathGlobs),
+            });
+            const result = analyzeCochangePersistence(commits, model);
+            return createResponse(result.analysis, {
+                confidence: result.confidence,
+                unknowns: result.unknowns,
+            });
+        },
+        async "history.compare_locality_models"(args, context) {
+            const policyConfig = await loadPolicyConfig(typeof args.policy === "string" ? args.policy : undefined);
+            const model = await requireDomainModel(args, context);
+            const commits = await normalizeHistory(getRootPath(args, context), policyConfig, getProfile(args), {
+                includePathGlobs: model.contexts.flatMap((entry) => entry.pathGlobs),
+            });
+            const result = compareEvolutionLocalityModels(commits, model);
+            return createResponse(result.comparison, {
+                confidence: result.confidence,
+                unknowns: result.unknowns,
+            });
+        },
+    };
+}

package/dist/src/command-input-loaders-architecture-compat-delivery-complexity.d.ts

@@ -0,0 +1,3 @@
+import type { ArchitectureComplexityExportBundle, ArchitectureDeliveryExportBundle } from "./core/contracts.js";
+export declare function normalizeArchitectureDeliveryExportBundle(input: unknown): ArchitectureDeliveryExportBundle;
+export declare function normalizeArchitectureComplexityExportBundle(input: unknown): ArchitectureComplexityExportBundle;

package/dist/src/command-input-loaders-architecture-compat-delivery-complexity.js

@@ -0,0 +1,132 @@
+import { asMetricValue, asNumber, asString, isRecord, toVersion, withNumericField, withOptionalString, } from "./command-input-loaders-architecture-compat-shared.js";
+function sanitizeDeliveryMeasurements(input) {
+    if (!isRecord(input)) {
+        return {};
+    }
+    return {
+        ...withNumericField("leadTime", asNumber(input.leadTime)),
+        ...withNumericField("deployFrequency", asNumber(input.deployFrequency)),
+        ...withNumericField("recoveryTime", asNumber(input.recoveryTime)),
+        ...withNumericField("changeFailRate", asNumber(input.changeFailRate)),
+        ...withNumericField("reworkRate", asNumber(input.reworkRate)),
+    };
+}
+function sanitizeComplexityMetrics(input) {
+    if (!isRecord(input)) {
+        return {};
+    }
+    return {
+        ...withNumericField("teamCount", asNumber(input.teamCount)),
+        ...withNumericField("deployableCount", asNumber(input.deployableCount)),
+        ...withNumericField("pipelineCount", asNumber(input.pipelineCount)),
+        ...withNumericField("contractOrSchemaCount", asNumber(input.contractOrSchemaCount)),
+        ...withNumericField("serviceCount", asNumber(input.serviceCount)),
+        ...withNumericField("serviceGroupCount", asNumber(input.serviceGroupCount)),
+        ...withNumericField("datastoreCount", asNumber(input.datastoreCount)),
+        ...withNumericField("onCallSurface", asNumber(input.onCallSurface)),
+        ...withNumericField("syncDepthP95", asNumber(input.syncDepthP95)),
+        ...withNumericField("runCostPerBusinessTransaction", asNumber(input.runCostPerBusinessTransaction)),
+    };
+}
+export function normalizeArchitectureDeliveryExportBundle(input) {
+    if (!isRecord(input)) {
+        return { version: "1.0", measurements: {} };
+    }
+    if (isRecord(input.measurements)) {
+        return {
+            version: toVersion(input),
+            ...withOptionalString("sourceSystem", asString(input.sourceSystem)),
+            measurements: sanitizeDeliveryMeasurements(input.measurements),
+            ...withOptionalString("note", asString(input.note)),
+        };
+    }
+    const embeddedExport = isRecord(input.contextProbe) && isRecord(input.contextProbe.exportBundle)
+        ? input.contextProbe.exportBundle
+        : undefined;
+    if (isRecord(embeddedExport) && isRecord(embeddedExport.measurements)) {
+        return {
+            version: toVersion(embeddedExport),
+            ...withOptionalString("sourceSystem", asString(embeddedExport.sourceSystem)),
+            measurements: sanitizeDeliveryMeasurements(embeddedExport.measurements),
+            ...withOptionalString("note", asString(embeddedExport.note)),
+        };
+    }
+    const dora = isRecord(input.dora) ? input.dora : undefined;
+    const metrics = isRecord(input.metrics) ? input.metrics : undefined;
+    const sourceSystem = asString(input.sourceSystem);
+    const note = asString(input.note);
+    const leadTime = asMetricValue(dora?.leadTime) ?? asMetricValue(metrics?.LeadTime);
+    const deployFrequency = asMetricValue(dora?.deployFrequency) ?? asMetricValue(metrics?.DeployFrequency);
+    const recoveryTime = asMetricValue(dora?.recoveryTime) ?? asMetricValue(metrics?.RecoveryTime);
+    const changeFailRate = asMetricValue(dora?.changeFailRate) ?? asMetricValue(metrics?.ChangeFailRate);
+    const reworkRate = asMetricValue(dora?.reworkRate) ?? asMetricValue(metrics?.ReworkRate);
+    return {
+        version: toVersion(input),
+        ...(sourceSystem ? { sourceSystem } : {}),
+        measurements: {
+            ...withNumericField("leadTime", leadTime),
+            ...withNumericField("deployFrequency", deployFrequency),
+            ...withNumericField("recoveryTime", recoveryTime),
+            ...withNumericField("changeFailRate", changeFailRate),
+            ...withNumericField("reworkRate", reworkRate),
+        },
+        ...(note ? { note } : {}),
+    };
+}
+export function normalizeArchitectureComplexityExportBundle(input) {
+    if (!isRecord(input)) {
+        return { version: "1.0", metrics: {} };
+    }
+    if (isRecord(input.metrics)) {
+        return {
+            version: toVersion(input),
+            ...withOptionalString("sourceSystem", asString(input.sourceSystem)),
+            metrics: sanitizeComplexityMetrics(input.metrics),
+            ...withOptionalString("note", asString(input.note)),
+        };
+    }
+    const embeddedExport = isRecord(input.contextProbe) && isRecord(input.contextProbe.exportBundle)
+        ? input.contextProbe.exportBundle
+        : undefined;
+    if (isRecord(embeddedExport) && isRecord(embeddedExport.metrics)) {
+        return {
+            version: toVersion(embeddedExport),
+            ...withOptionalString("sourceSystem", asString(embeddedExport.sourceSystem)),
+            metrics: sanitizeComplexityMetrics(embeddedExport.metrics),
+            ...withOptionalString("note", asString(embeddedExport.note)),
+        };
+    }
+    const team = isRecord(input.team) ? input.team : undefined;
+    const platform = isRecord(input.platform) ? input.platform : undefined;
+    const architecture = isRecord(input.architecture) ? input.architecture : undefined;
+    const finance = isRecord(input.finance) ? input.finance : undefined;
+    const sourceSystem = asString(input.sourceSystem);
+    const note = asString(input.note);
+    const teamCount = asNumber(team?.count);
+    const deployableCount = asNumber(platform?.deployableCount);
+    const pipelineCount = asNumber(platform?.pipelinesPerDeployable);
+    const contractOrSchemaCount = asNumber(architecture?.contractOrSchemaCount);
+    const serviceCount = asNumber(architecture?.serviceCount);
+    const serviceGroupCount = asNumber(architecture?.serviceGroupCount);
+    const datastoreCount = asNumber(platform?.datastoreCount);
+    const onCallSurface = asNumber(platform?.onCallSurface);
+    const syncDepthP95 = asNumber(platform?.syncDepthP95);
+    const runCostPerBusinessTransaction = asNumber(finance?.runCostPerBusinessTransaction);
+    return {
+        version: toVersion(input),
+        ...(sourceSystem ? { sourceSystem } : {}),
+        metrics: {
+            ...withNumericField("teamCount", teamCount),
+            ...withNumericField("deployableCount", deployableCount),
+            ...withNumericField("pipelineCount", pipelineCount),
+            ...withNumericField("contractOrSchemaCount", contractOrSchemaCount),
+            ...withNumericField("serviceCount", serviceCount),
+            ...withNumericField("serviceGroupCount", serviceGroupCount),
+            ...withNumericField("datastoreCount", datastoreCount),
+            ...withNumericField("onCallSurface", onCallSurface),
+            ...withNumericField("syncDepthP95", syncDepthP95),
+            ...withNumericField("runCostPerBusinessTransaction", runCostPerBusinessTransaction),
+        },
+        ...(note ? { note } : {}),
+    };
+}

package/dist/src/command-input-loaders-architecture-compat-pattern-runtime.d.ts

@@ -0,0 +1,2 @@
+import type { ArchitecturePatternRuntimeObservationSet } from "./core/contracts.js";
+export declare function normalizePatternRuntimeObservations(input: unknown): ArchitecturePatternRuntimeObservationSet | undefined;

package/dist/src/command-input-loaders-architecture-compat-pattern-runtime.js

@@ -0,0 +1,54 @@
+import { asNumber, asPatternFamily, asString, isRecord, withNumericField, withOptionalObject, withOptionalString, withOptionalValue, } from "./command-input-loaders-architecture-compat-shared.js";
+function sanitizePatternRuntimeBlock(input, keys) {
+    if (!isRecord(input)) {
+        return undefined;
+    }
+    const sanitized = {};
+    for (const key of keys) {
+        const value = asNumber(input[key]);
+        if (value !== undefined) {
+            sanitized[key] = value;
+        }
+    }
+    return Object.keys(sanitized).length > 0 ? sanitized : undefined;
+}
+export function normalizePatternRuntimeObservations(input) {
+    if (!isRecord(input)) {
+        return undefined;
+    }
+    const metrics = isRecord(input.metrics)
+        ? Object.fromEntries(Object.entries(input.metrics).filter((entry) => typeof entry[0] === "string" && asNumber(entry[1]) !== undefined))
+        : undefined;
+    const sanitizedMetrics = metrics && Object.keys(metrics).length > 0 ? metrics : undefined;
+    const layeredRuntime = sanitizePatternRuntimeBlock(input.layeredRuntime, [
+        "FailureContainmentScore",
+        "DependencyIsolationScore",
+    ]);
+    const serviceBasedRuntime = sanitizePatternRuntimeBlock(input.serviceBasedRuntime, [
+        "PartialFailureContainmentScore",
+        "RetryAmplificationScore",
+        "SyncHopDepthScore",
+    ]);
+    const cqrsRuntime = sanitizePatternRuntimeBlock(input.cqrsRuntime, [
+        "ProjectionFreshnessScore",
+        "ReplayDivergenceScore",
+        "StaleReadAcceptabilityScore",
+    ]);
+    const eventDrivenRuntime = sanitizePatternRuntimeBlock(input.eventDrivenRuntime, [
+        "DeadLetterHealthScore",
+        "ConsumerLagScore",
+        "ReplayRecoveryScore",
+    ]);
+    return {
+        version: asString(input.version) ?? "1.0",
+        ...withOptionalString("source", asString(input.source)),
+        ...withOptionalString("note", asString(input.note)),
+        ...withOptionalObject("layeredRuntime", layeredRuntime),
+        ...withOptionalObject("serviceBasedRuntime", serviceBasedRuntime),
+        ...withOptionalObject("cqrsRuntime", cqrsRuntime),
+        ...withOptionalObject("eventDrivenRuntime", eventDrivenRuntime),
+        ...withOptionalObject("metrics", sanitizedMetrics),
+        ...withOptionalValue("patternFamily", asPatternFamily(input.patternFamily)),
+        ...withNumericField("score", asNumber(input.score)),
+    };
+}

package/dist/src/command-input-loaders-architecture-compat-scenario.d.ts

@@ -0,0 +1,3 @@
+import type { ArchitectureScenarioCatalog, ScenarioObservationSet } from "./core/contracts.js";
+export declare function normalizeArchitectureScenarioCatalog(input: unknown): ArchitectureScenarioCatalog;
+export declare function normalizeArchitectureScenarioObservations(input: unknown): ScenarioObservationSet;

package/dist/src/command-input-loaders-architecture-compat-scenario.js

@@ -0,0 +1,94 @@
+import { asNumber, asScenarioDirection, asString, isRecord, normalizeScenarioPriority, toVersion, withOptionalObject, withOptionalString, } from "./command-input-loaders-architecture-compat-shared.js";
+function sanitizeScenarioCatalogEntries(input) {
+    if (!Array.isArray(input)) {
+        return [];
+    }
+    return input.flatMap((entry) => {
+        if (!isRecord(entry)) {
+            return [];
+        }
+        const scenarioId = asString(entry.scenarioId) ?? asString(entry.id);
+        if (!scenarioId) {
+            return [];
+        }
+        const expectations = Array.isArray(entry.quality_expectations) ? entry.quality_expectations.filter(isRecord) : [];
+        const firstExpectation = expectations[0];
+        const responseMeasure = isRecord(entry.responseMeasure)
+            ? {
+                ...withOptionalString("metric", asString(entry.responseMeasure.metric)),
+                ...withOptionalString("unit", asString(entry.responseMeasure.unit)),
+            }
+            : undefined;
+        const sanitizedResponseMeasure = responseMeasure && Object.keys(responseMeasure).length > 0 ? responseMeasure : undefined;
+        return [
+            {
+                scenarioId,
+                direction: asScenarioDirection(entry.direction) ?? "higher_is_better",
+                priority: normalizeScenarioPriority(entry.priority),
+                target: asNumber(entry.target) ?? 1,
+                worstAcceptable: asNumber(entry.worstAcceptable) ?? 0,
+                ...withOptionalString("name", asString(entry.name)),
+                ...withOptionalString("qualityAttribute", asString(entry.qualityAttribute) ?? asString(firstExpectation?.attribute)),
+                ...withOptionalString("stimulus", asString(entry.stimulus) ??
+                    (isRecord(entry.entry_surface) ? asString(entry.entry_surface.trigger) : undefined)),
+                ...withOptionalString("environment", asString(entry.environment) ??
+                    (isRecord(entry.entry_surface) ? asString(entry.entry_surface.user_surface) : undefined)),
+                ...withOptionalString("response", asString(entry.response) ?? asString(firstExpectation?.expectation)),
+                ...withOptionalObject("responseMeasure", sanitizedResponseMeasure),
+            },
+        ];
+    });
+}
+function sanitizeScenarioObservations(input) {
+    if (!Array.isArray(input)) {
+        return [];
+    }
+    return input.flatMap((entry) => {
+        if (!isRecord(entry)) {
+            return [];
+        }
+        const scenarioId = asString(entry.scenarioId) ?? asString(entry.id);
+        const observed = asNumber(entry.observed);
+        if (!scenarioId || observed === undefined) {
+            return [];
+        }
+        return [
+            {
+                scenarioId,
+                observed,
+                ...withOptionalString("source", asString(entry.source)),
+                ...withOptionalString("note", asString(entry.note)),
+            },
+        ];
+    });
+}
+export function normalizeArchitectureScenarioCatalog(input) {
+    if (!isRecord(input)) {
+        return { version: "1.0", scenarios: [] };
+    }
+    return {
+        version: toVersion(input),
+        scenarios: sanitizeScenarioCatalogEntries(input.scenarios),
+    };
+}
+export function normalizeArchitectureScenarioObservations(input) {
+    if (!isRecord(input)) {
+        return { version: "1.0", observations: [] };
+    }
+    if (Array.isArray(input.observations)) {
+        return {
+            version: toVersion(input),
+            observations: sanitizeScenarioObservations(input.observations),
+        };
+    }
+    const observationsSource = (isRecord(input.benchmarkSummary) && Array.isArray(input.benchmarkSummary.observations)
+        ? input.benchmarkSummary.observations
+        : undefined) ??
+        (isRecord(input.incidentReviewSummary) && Array.isArray(input.incidentReviewSummary.observations)
+            ? input.incidentReviewSummary.observations
+            : undefined);
+    return {
+        version: toVersion(input),
+        observations: sanitizeScenarioObservations(observationsSource),
+    };
+}

package/dist/src/command-input-loaders-architecture-compat-shared.d.ts

@@ -0,0 +1,17 @@
+import type { ArchitecturePatternRuntimeObservationSet, ArchitectureScenarioCatalog, ArchitectureTopologyModel } from "./core/contracts.js";
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function asString(value: unknown): string | undefined;
+export declare function asStringArray(value: unknown): string[];
+export declare function asNumber(value: unknown): number | undefined;
+export declare function asMetricValue(value: unknown): number | undefined;
+export declare function withNumericField<T extends string>(key: T, value: number | undefined): Partial<Record<T, number>>;
+export declare function toVersion(input: Record<string, unknown>): string;
+export declare function normalizeScenarioPriority(value: unknown): number;
+export declare function asScenarioDirection(value: unknown): ArchitectureScenarioCatalog["scenarios"][number]["direction"] | undefined;
+export declare function asTopologyNodeKind(value: unknown): ArchitectureTopologyModel["nodes"][number]["kind"] | undefined;
+export declare function asTopologyEdgeKind(value: unknown): ArchitectureTopologyModel["edges"][number]["kind"] | undefined;
+export declare function asPatternFamily(value: unknown): ArchitecturePatternRuntimeObservationSet["patternFamily"] | undefined;
+export declare function withOptionalString<T extends string>(key: T, value: string | undefined): Partial<Record<T, string>>;
+export declare function withOptionalBoolean<T extends string>(key: T, value: boolean | undefined): Partial<Record<T, boolean>>;
+export declare function withOptionalObject<T extends string, U extends object>(key: T, value: U | undefined): Partial<Record<T, U>>;
+export declare function withOptionalValue<T extends string, U>(key: T, value: U | undefined): Partial<Record<T, U>>;

package/dist/src/command-input-loaders-architecture-compat-shared.js

@@ -0,0 +1,109 @@
+export function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+export function asString(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+export function asStringArray(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter((entry) => typeof entry === "string" && entry.length > 0);
+}
+export function asNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+export function asMetricValue(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return value;
+    }
+    if (isRecord(value)) {
+        return asNumber(value.value);
+    }
+    return undefined;
+}
+export function withNumericField(key, value) {
+    return value !== undefined ? { [key]: value } : {};
+}
+export function toVersion(input) {
+    return asString(input.version) ?? asString(input.schema_version) ?? "1.0";
+}
+export function normalizeScenarioPriority(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === "string") {
+        switch (value) {
+            case "core":
+                return 1;
+            case "high":
+                return 0.9;
+            case "medium":
+                return 0.75;
+            case "low":
+                return 0.5;
+            case "optional":
+                return 0.35;
+            default:
+                return 0.5;
+        }
+    }
+    return 0.5;
+}
+export function asScenarioDirection(value) {
+    return value === "higher_is_better" || value === "lower_is_better" ? value : undefined;
+}
+const TOPOLOGY_NODE_KINDS = new Set([
+    "service",
+    "datastore",
+    "queue",
+    "cache",
+    "gateway",
+    "worker",
+    "unknown",
+]);
+const TOPOLOGY_EDGE_KINDS = new Set([
+    "sync_call",
+    "async_message",
+    "shared_resource",
+    "runtime_dependency",
+]);
+const PATTERN_FAMILIES = new Set([
+    "layered",
+    "clean",
+    "hexagonal",
+    "modular-monolith",
+    "microservices",
+    "cqrs",
+    "event-driven",
+]);
+export function asTopologyNodeKind(value) {
+    return typeof value === "string" &&
+        TOPOLOGY_NODE_KINDS.has(value)
+        ? value
+        : undefined;
+}
+export function asTopologyEdgeKind(value) {
+    return typeof value === "string" &&
+        TOPOLOGY_EDGE_KINDS.has(value)
+        ? value
+        : undefined;
+}
+export function asPatternFamily(value) {
+    return typeof value === "string" &&
+        PATTERN_FAMILIES.has(value)
+        ? value
+        : undefined;
+}
+export function withOptionalString(key, value) {
+    return value !== undefined ? { [key]: value } : {};
+}
+export function withOptionalBoolean(key, value) {
+    return value !== undefined ? { [key]: value } : {};
+}
+export function withOptionalObject(key, value) {
+    return value !== undefined ? { [key]: value } : {};
+}
+export function withOptionalValue(key, value) {
+    return value !== undefined ? { [key]: value } : {};
+}

package/dist/src/command-input-loaders-architecture-compat-telemetry.d.ts

@@ -0,0 +1,3 @@
+import type { ArchitectureTelemetryExportBundle, ArchitectureTelemetryObservationSet } from "./core/contracts.js";
+export declare function normalizeArchitectureTelemetryObservations(input: unknown): ArchitectureTelemetryObservationSet;
+export declare function normalizeArchitectureTelemetryExportBundle(input: unknown): ArchitectureTelemetryExportBundle;

package/dist/src/command-input-loaders-architecture-compat-telemetry.js

@@ -0,0 +1,137 @@
+import { normalizePatternRuntimeObservations } from "./command-input-loaders-architecture-compat-pattern-runtime.js";
+import { asNumber, asString, isRecord, toVersion, withNumericField, withOptionalObject, withOptionalString, } from "./command-input-loaders-architecture-compat-shared.js";
+function sanitizeTelemetryObservationBands(input) {
+    if (!Array.isArray(input)) {
+        return [];
+    }
+    return input.flatMap((entry) => {
+        if (!isRecord(entry)) {
+            return [];
+        }
+        const bandId = asString(entry.bandId);
+        const trafficWeight = asNumber(entry.trafficWeight);
+        if (!bandId || trafficWeight === undefined) {
+            return [];
+        }
+        return [
+            {
+                bandId,
+                trafficWeight,
+                ...withNumericField("LatencyScore", asNumber(entry.LatencyScore)),
+                ...withNumericField("ErrorScore", asNumber(entry.ErrorScore)),
+                ...withNumericField("SaturationScore", asNumber(entry.SaturationScore)),
+            },
+        ];
+    });
+}
+function sanitizeTelemetryExportBands(input) {
+    if (!Array.isArray(input)) {
+        return [];
+    }
+    return input.flatMap((entry) => {
+        if (!isRecord(entry)) {
+            return [];
+        }
+        const bandId = asString(entry.bandId);
+        const trafficWeight = asNumber(entry.trafficWeight);
+        if (!bandId || trafficWeight === undefined) {
+            return [];
+        }
+        return [
+            {
+                bandId,
+                trafficWeight,
+                ...withNumericField("latencyP95", asNumber(entry.latencyP95)),
+                ...withNumericField("errorRate", asNumber(entry.errorRate)),
+                ...withNumericField("saturationRatio", asNumber(entry.saturationRatio)),
+                ...withOptionalString("source", asString(entry.source)),
+                ...withOptionalString("window", asString(entry.window)),
+            },
+        ];
+    });
+}
+function telemetryReadinessScore(status, gaps) {
+    const normalized = (status ?? "").toLowerCase();
+    let base = normalized === "emitting" || normalized === "observed-in-code"
+        ? 0.88
+        : normalized === "configured"
+            ? 0.74
+            : normalized === "configured-not-sampled"
+                ? 0.66
+                : normalized === "documented-only"
+                    ? 0.45
+                    : 0.5;
+    const gapCount = Array.isArray(gaps) ? gaps.length : 0;
+    base -= Math.min(0.2, gapCount * 0.04);
+    return Math.max(0, Math.min(1, base));
+}
+export function normalizeArchitectureTelemetryObservations(input) {
+    if (!isRecord(input)) {
+        return { version: "1.0", bands: [] };
+    }
+    if (Array.isArray(input.bands)) {
+        return {
+            version: toVersion(input),
+            bands: sanitizeTelemetryObservationBands(input.bands),
+        };
+    }
+    const sources = Array.isArray(input.sources) ? input.sources.filter(isRecord) : [];
+    const observations = Array.isArray(input.observations) ? input.observations.filter(isRecord) : [];
+    const candidates = [...sources, ...observations];
+    if (candidates.length === 0) {
+        return {
+            version: toVersion(input),
+            bands: [],
+        };
+    }
+    const total = candidates.reduce((sum, candidate) => {
+        return sum + telemetryReadinessScore(asString(candidate.status), candidate.gaps);
+    }, 0);
+    const averageScore = total / candidates.length;
+    return {
+        version: toVersion(input),
+        bands: [
+            {
+                bandId: "inventory",
+                trafficWeight: 1,
+                LatencyScore: averageScore,
+                ErrorScore: averageScore,
+                SaturationScore: averageScore,
+            },
+        ],
+    };
+}
+export function normalizeArchitectureTelemetryExportBundle(input) {
+    if (!isRecord(input)) {
+        return { version: "1.0", bands: [] };
+    }
+    if (Array.isArray(input.bands)) {
+        return {
+            version: toVersion(input),
+            bands: sanitizeTelemetryExportBands(input.bands),
+            ...withOptionalString("sourceSystem", asString(input.sourceSystem)),
+            ...withOptionalObject("patternRuntime", normalizePatternRuntimeObservations(input.patternRuntime)),
+            ...withOptionalString("note", asString(input.note)),
+        };
+    }
+    const embeddedExport = isRecord(input.contextProbe) && isRecord(input.contextProbe.exportBundle)
+        ? input.contextProbe.exportBundle
+        : undefined;
+    if (isRecord(embeddedExport) && Array.isArray(embeddedExport.bands)) {
+        return {
+            version: toVersion(embeddedExport),
+            bands: sanitizeTelemetryExportBands(embeddedExport.bands),
+            ...withOptionalString("sourceSystem", asString(embeddedExport.sourceSystem)),
+            ...withOptionalObject("patternRuntime", normalizePatternRuntimeObservations(embeddedExport.patternRuntime)),
+            ...withOptionalString("note", asString(embeddedExport.note)),
+        };
+    }
+    const sourceSystem = asString(input.sourceSystem);
+    const note = asString(input.note);
+    return {
+        version: toVersion(input),
+        bands: [],
+        ...(sourceSystem ? { sourceSystem } : {}),
+        ...(note ? { note } : {}),
+    };
+}

package/dist/src/command-input-loaders-architecture-compat-topology-boundary.d.ts

@@ -0,0 +1,3 @@
+import type { ArchitectureBoundaryMap, ArchitectureTopologyModel } from "./core/contracts.js";
+export declare function normalizeArchitectureTopologyModel(input: unknown): ArchitectureTopologyModel;
+export declare function normalizeArchitectureBoundaryMap(input: unknown): ArchitectureBoundaryMap;