From 90ce8bae4af5530f618e4788c0248f5b9ead62d5 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Sun, 15 Nov 2026 23:59:23 +0800 Subject: [PATCH] fix(javascript): report version-comparison coverage unknown when a source graph cannot tell (#11206) * fix(javascript): report version-comparison coverage unknown when a source graph cannot tell * refactor(javascript): name the unavailable-graph coverage mapping once * fix(javascript): give the version change graph and its edges the same unknown coverage * fix(javascript): report export-shape comparison coverage unknown when a source graph cannot tell (#11218) * fix(javascript): report export-shape comparison coverage unknown when a source graph cannot tell * test(javascript): keep unknown export-shape coverage beside a truncated projection * fix(javascript): read runtime-reconciliation input coverage once and report unknown when a static graph cannot tell (#11230) * fix(javascript): read runtime-reconciliation input coverage once and report unknown when a static graph cannot tell * fix(javascript): keep a known input truncation beside unknown reconciliation coverage * fix(javascript): report export-shape source omission counts unknown when a side has no projection (#11261) compare_export_shapes reported left/right_omitted_fields and omitted_property_coverage as 0 for a side whose export selection recovered no return-shape projection (missing, ambiguous or unavailable), while the sibling source_omitted_variants already reported null. Add Known (src/domain/known.ts) and read each side's source coverage once through it; the counts are now null (unknown) with a limitation naming why. The runtime-reconciliation graph's omission sum and its parallel 'omissions known' flag become one Known via sumKnownCounts (no output change). --- .../verify/architecture-guard-baselines.json | 3 +- .../javascriptApplicationChangeGraph.ts | 43 ++--- .../javascriptApplicationEvidenceSchemas.ts | 15 ++ ...scriptApplicationVersionComparison.test.ts | 87 +++++++++ .../javascriptApplicationVersionComparison.ts | 22 ++- ...riptApplicationVersionComparisonSchemas.ts | 22 ++- .../javascriptExportShapeComparison.ts | 111 +++++++++-- .../javascriptExportShapeComparisonSchemas.ts | 37 ++-- .../javascriptRuntimeReconciliationGraph.ts | 177 ++++++++++++------ ...ptRuntimeReconciliationInputStatus.test.ts | 66 +++++++ .../javascriptRuntimeReconciliationResult.ts | 69 ++++--- .../javascriptRuntimeReconciliationSchemas.ts | 11 +- src/domain/known.test.ts | 23 +++ src/domain/known.ts | 38 ++++ .../javascriptExportShapeComparison.test.ts | 110 +++++++++++ 15 files changed, 665 insertions(+), 169 deletions(-) create mode 100644 src/domain/javascript/javascriptRuntimeReconciliationInputStatus.test.ts create mode 100644 src/domain/known.test.ts create mode 100644 src/domain/known.ts diff --git a/scripts/verify/architecture-guard-baselines.json b/scripts/verify/architecture-guard-baselines.json index 8e507cc77c..fd8f8a7f65 100644 --- a/scripts/verify/architecture-guard-baselines.json +++ b/scripts/verify/architecture-guard-baselines.json @@ -447,8 +447,7 @@ "src/domain/flutter/flutterBuildAnalysis.ts": 4, "src/domain/gpu/gpuCodeObjects.ts": 5, "src/domain/javascript/electronActiveObservation.ts": 1, - "src/domain/javascript/javascriptApplicationVersionComparisonSchemas.ts": 2, - "src/domain/javascript/javascriptExportShapeComparisonSchemas.ts": 4, + "src/domain/javascript/javascriptExportShapeComparisonSchemas.ts": 2, "src/domain/javascript/javascriptFeatureTraceSchemas.ts": 2, "src/domain/javascript/javascriptRecovery.ts": 1, "src/domain/javascript/javascriptRouteInventory.ts": 2, diff --git a/src/domain/javascript/javascriptApplicationChangeGraph.ts b/src/domain/javascript/javascriptApplicationChangeGraph.ts index 08336bb0d6..4b320b939a 100644 --- a/src/domain/javascript/javascriptApplicationChangeGraph.ts +++ b/src/domain/javascript/javascriptApplicationChangeGraph.ts @@ -10,6 +10,8 @@ import type { } from "./javascriptApplicationGraphSchemas.js"; import type { ApplicationGraphEvidence } from "./javascriptApplicationEvidenceSchemas.js"; import { uniqueSorted } from "../canonicalOrdering.js"; +import { joinCoverageStatus } from "../coverage.js"; +import { applicationCoverageKnowledge } from "./javascriptApplicationEvidenceSchemas.js"; import { compareUnicodeCodePoints } from "../unicodeCodePointOrder.js"; import type { ApplicationVersionComparisonItem } from "./javascriptApplicationVersionComparisonSchemas.js"; @@ -151,9 +153,6 @@ const comparisonEvidence = ( ): ApplicationGraphEvidence => { const source = right?.observations[0]?.evidence ?? left?.observations[0]?.evidence; - const complete = - input.left.coverage.status === "complete" && - input.right.coverage.status === "complete"; return { authority: "cross-version-comparison", state: "inferred", @@ -174,23 +173,7 @@ const comparisonEvidence = ( operation: "compare_application_versions", executable_sha256: null, }, - coverage: complete - ? { - status: "complete", - truncated: false, - omitted_count: 0, - limits: sourceCoverageLimits(input), - } - : { - status: "partial", - truncated: - input.left.coverage.truncated || input.right.coverage.truncated, - omitted_count: combineOmittedCounts( - input.left.coverage.omitted_count, - input.right.coverage.omitted_count, - ), - limits: sourceCoverageLimits(input), - }, + coverage: changeGraphCoverage(input), limitations: [ "Cross-version pairing is inferred from the stated match basis; changed_from does not prove runtime reachability.", ...item.limitations, @@ -199,19 +182,31 @@ const comparisonEvidence = ( }; }; +/** + * The coverage both source graphs support, for the change graph and each + * `changed_from` edge. A source that cannot tell makes it unknown. + */ const changeGraphCoverage = ( input: ChangeGraphInput, ): JavaScriptApplicationGraph["coverage"] => { - if ( - input.left.coverage.status === "complete" && - input.right.coverage.status === "complete" - ) + const joined = joinCoverageStatus([ + applicationCoverageKnowledge(input.left.coverage.status), + applicationCoverageKnowledge(input.right.coverage.status), + ]); + if (joined === "complete") return { status: "complete", truncated: false, omitted_count: 0, limits: sourceCoverageLimits(input), }; + if (joined === "unknown") + return { + status: "unknown", + truncated: false, + omitted_count: null, + limits: sourceCoverageLimits(input), + }; return { status: "partial", truncated: input.left.coverage.truncated || input.right.coverage.truncated, diff --git a/src/domain/javascript/javascriptApplicationEvidenceSchemas.ts b/src/domain/javascript/javascriptApplicationEvidenceSchemas.ts index 29f13c54ca..fd53b23c85 100644 --- a/src/domain/javascript/javascriptApplicationEvidenceSchemas.ts +++ b/src/domain/javascript/javascriptApplicationEvidenceSchemas.ts @@ -1,3 +1,4 @@ +import { coverageStatusSchema, type CoverageStatus } from "../coverage.js"; import { z } from "zod"; import { javascriptSourceRangeSchema } from "./javascriptSourceCoordinates.js"; import { digestSchema, prefixedDigestSchema } from "../digests.js"; @@ -203,6 +204,20 @@ export const applicationCoverageSchema = z.union([ ]); export type ApplicationCoverage = z.infer; +/** + * An application graph's coverage status: the shared coverage vocabulary plus + * `unavailable`, for a graph whose producer could not run. + */ +export const applicationCoverageStatusSchema = z.enum([ + ...coverageStatusSchema.options, + "unavailable", +]); + +/** What an application graph's coverage says about its inputs: a graph whose producer could not run cannot tell. */ +export const applicationCoverageKnowledge = ( + status: z.infer, +): CoverageStatus => (status === "unavailable" ? "unknown" : status); + /** Construct complete bounded coverage under the stated configured limits. */ export const completeApplicationCoverage = ( limits: ApplicationCoverage["limits"] = [], diff --git a/src/domain/javascript/javascriptApplicationVersionComparison.test.ts b/src/domain/javascript/javascriptApplicationVersionComparison.test.ts index d434cbae29..f8c9928650 100644 --- a/src/domain/javascript/javascriptApplicationVersionComparison.test.ts +++ b/src/domain/javascript/javascriptApplicationVersionComparison.test.ts @@ -439,3 +439,90 @@ describe("application version comparison graph ownership", () => { ).toThrow("Comparison coverage must match source graph completeness"); }); }); + +describe("version comparison coverage", () => { + const withCoverage = ( + graph: JavaScriptApplicationGraph, + coverage: JavaScriptApplicationGraph["coverage"], + ): JavaScriptApplicationGraph => { + const { graph_id: _graphId, ...input } = graph; + return createJavaScriptApplicationGraph({ + ...input, + coverage, + limitations: ["Fixture graph coverage is incomplete."], + }); + }; + const compareWith = ( + left: JavaScriptApplicationGraph["coverage"], + right: JavaScriptApplicationGraph["coverage"], + ) => + compareJavaScriptApplicationVersions({ + left: { + evidenceId: `ev_${"1".repeat(64)}`, + rootArtifactSha256: LEFT_SHA, + graph: withCoverage(buildGraph(LEFT_SHA, 1), left), + }, + right: { + evidenceId: `ev_${"2".repeat(64)}`, + rootArtifactSha256: RIGHT_SHA, + graph: withCoverage(buildGraph(RIGHT_SHA, 2), right), + }, + leftNativeEvidence: [], + rightNativeEvidence: [], + }); + type Coverage = JavaScriptApplicationGraph["coverage"]; + const unknown = (status: "unknown" | "unavailable"): Coverage => ({ + status, + truncated: false, + omitted_count: null, + limits: [], + }); + const truncated: Coverage = { + status: "partial", + truncated: true, + omitted_count: 3, + limits: [{ name: "modules", value: 3, unit: "items" }], + }; + + it.each(["unknown", "unavailable"] as const)( + "reports unknown, not a known gap, when a source graph is %s", + (status) => { + const result = compareWith(completeCoverage, unknown(status)); + expect(result.coverage).toMatchObject({ + right_graph_status: status, + status: "unknown", + }); + // The change graph and each changed_from edge make the same claim. + expect(result.graph.coverage).toMatchObject({ + status: "unknown", + omitted_count: null, + }); + const changed = result.graph.edges.filter( + ({ relation }) => relation === "changed_from", + ); + expect(changed.length).toBeGreaterThan(0); + for (const edge of changed) + expect(edge.evidence.coverage.status).toBe("unknown"); + // Unknown wins over a known truncation on the other side. + expect(compareWith(truncated, unknown(status)).coverage.status).toBe( + "unknown", + ); + }, + ); + + it("keeps a known truncation when both graphs report their coverage", () => { + expect(compareWith(truncated, completeCoverage).coverage.status).toBe( + "truncated", + ); + }); + + it("refuses an unknown status that the source graphs do not support", () => { + const result = compare(); + expect(() => + ownedApplicationVersionComparisonResultSchema.parse({ + ...result, + coverage: { ...result.coverage, status: "unknown" }, + }), + ).toThrow(/unknown exactly when/u); + }); +}); diff --git a/src/domain/javascript/javascriptApplicationVersionComparison.ts b/src/domain/javascript/javascriptApplicationVersionComparison.ts index be60d067a2..8eee2d3a88 100644 --- a/src/domain/javascript/javascriptApplicationVersionComparison.ts +++ b/src/domain/javascript/javascriptApplicationVersionComparison.ts @@ -1,6 +1,8 @@ import { digestCanonicalValue } from "../canonicalDigest.js"; import { uniqueSorted } from "../canonicalOrdering.js"; import type { Evidence } from "../evidence.js"; +import { joinCoverageStatus } from "../coverage.js"; +import { applicationCoverageKnowledge } from "./javascriptApplicationEvidenceSchemas.js"; import { buildJavaScriptApplicationChangeGraph } from "./javascriptApplicationChangeGraph.js"; import { ownedApplicationVersionComparisonResultSchema, @@ -129,19 +131,23 @@ const comparisonCoverage = ( left_graph_status: input.left.graph.coverage.status, right_graph_status: input.right.graph.coverage.status, }; - const sourceGraphsComplete = - input.left.graph.coverage.status === "complete" && - input.right.graph.coverage.status === "complete"; + const joined = joinCoverageStatus([ + applicationCoverageKnowledge(input.left.graph.coverage.status), + applicationCoverageKnowledge(input.right.graph.coverage.status), + ]); const sourceGraphsTruncated = input.left.graph.coverage.truncated || input.right.graph.coverage.truncated; return { ...context, ...omissions, - status: sourceGraphsComplete - ? "complete-within-inputs" - : sourceGraphsTruncated - ? "truncated" - : "partial", + status: + joined === "complete" + ? "complete-within-inputs" + : joined === "unknown" + ? "unknown" + : sourceGraphsTruncated + ? "truncated" + : "partial", }; }; diff --git a/src/domain/javascript/javascriptApplicationVersionComparisonSchemas.ts b/src/domain/javascript/javascriptApplicationVersionComparisonSchemas.ts index 859ddaf286..92f3a8d8fd 100644 --- a/src/domain/javascript/javascriptApplicationVersionComparisonSchemas.ts +++ b/src/domain/javascript/javascriptApplicationVersionComparisonSchemas.ts @@ -9,6 +9,7 @@ import { import { JAVASCRIPT_APPLICATION_NODE_KINDS } from "./javascriptApplicationGraphSchemas.js"; import { prefixedDigestSchema } from "../digests.js"; import { nonEmptyTextSchema } from "../textSchemas.js"; +import { applicationCoverageStatusSchema } from "./javascriptApplicationEvidenceSchemas.js"; const evidenceIdSchema = prefixedDigestSchema("ev"); const nodeIdSchema = prefixedDigestSchema("jag_node"); @@ -170,11 +171,15 @@ const comparisonItemSchema = z.union([ ]); const comparisonCoverageSchema = z.strictObject({ - left_graph_status: z.enum(["complete", "partial", "unknown", "unavailable"]), - right_graph_status: z.enum(["complete", "partial", "unknown", "unavailable"]), + left_graph_status: applicationCoverageStatusSchema, + right_graph_status: applicationCoverageStatusSchema, left_graph_omitted_count: z.int().min(0).nullable(), right_graph_omitted_count: z.int().min(0).nullable(), - status: z.enum(["complete-within-inputs", "partial", "truncated"]), + /** + * `unknown` when either source graph's coverage is unknown or unavailable; + * `truncated` and `partial` are known gaps. + */ + status: z.enum(["complete-within-inputs", "partial", "truncated", "unknown"]), }); /** Tiered module/entity matching plus its complete cross-version change graph. */ @@ -227,6 +232,17 @@ export const applicationVersionComparisonResultSchema = z path: ["coverage", "status"], message: "Comparison coverage must match source graph completeness", }); + const sourceGraphUnknown = [ + result.coverage.left_graph_status, + result.coverage.right_graph_status, + ].some((status) => status === "unknown" || status === "unavailable"); + if ((result.coverage.status === "unknown") !== sourceGraphUnknown) + context.addIssue({ + code: "custom", + path: ["coverage", "status"], + message: + "Comparison coverage is unknown exactly when a source graph's coverage is unknown or unavailable", + }); }); /** Reuse the exact owned change graph while validating the rest of the result. */ diff --git a/src/domain/javascript/javascriptExportShapeComparison.ts b/src/domain/javascript/javascriptExportShapeComparison.ts index a59798df8e..829ca5025f 100644 --- a/src/domain/javascript/javascriptExportShapeComparison.ts +++ b/src/domain/javascript/javascriptExportShapeComparison.ts @@ -2,10 +2,14 @@ import { uniqueSorted } from "../canonicalOrdering.js"; import { compareUnicodeCodePoints } from "../unicodeCodePointOrder.js"; import { canonicalJson } from "../comparisonSemantics.js"; import { digestCanonicalValue } from "../canonicalDigest.js"; +import { joinCoverageStatus } from "../coverage.js"; +import { known, knownOrNull, unknownBecause, type Known } from "../known.js"; +import { applicationCoverageKnowledge } from "./javascriptApplicationEvidenceSchemas.js"; import { javaScriptExportShapeComparisonResultSchema, type JavaScriptExportShapeComparisonChange, type JavaScriptExportShapeComparisonResult, + type ProjectedExportReturnShapes, } from "./javascriptExportShapeComparisonSchemas.js"; import { retainJavaScriptExportShapes, @@ -125,20 +129,42 @@ interface CoverageInput { readonly omittedChanges: number; } +type ReturnShapeCoverage = ProjectedExportReturnShapes["return_shape_coverage"]; + +/** + * The side's source return-shape coverage. A side without a projection did + * not recover return shapes, so its source omissions are unknown, not zero. + */ +const sourceCoverage = ( + selection: SelectedJavaScriptExport, +): Known => + selection.projection === null + ? unknownBecause(`the export selection is ${selection.selection.status}`) + : known(selection.projection.return_shape_coverage); + const comparisonCoverage = (context: CoverageInput) => { - const leftSource = context.left.projection?.return_shape_coverage; - const rightSource = context.right.projection?.return_shape_coverage; + const leftSource = sourceCoverage(context.left); + const rightSource = sourceCoverage(context.right); const omittedCandidates = context.left.selection.omitted_candidates + context.right.selection.omitted_candidates; const truncated = comparisonTruncated(context, omittedCandidates); const partial = comparisonPartial(context); + // A source graph that cannot tell its coverage makes the comparison + // unknown, even beside a known gap. + const graphs = joinCoverageStatus([ + applicationCoverageKnowledge(context.input.left.graph.coverage.status), + applicationCoverageKnowledge(context.input.right.graph.coverage.status), + ]); return { - status: truncated - ? ("truncated" as const) - : partial - ? ("partial" as const) - : ("complete-within-inputs" as const), + status: + graphs === "unknown" + ? ("unknown" as const) + : truncated + ? ("truncated" as const) + : partial + ? ("partial" as const) + : ("complete-within-inputs" as const), left_graph_status: context.input.left.graph.coverage.status, right_graph_status: context.input.right.graph.coverage.status, paired_variants: context.pairing.pairs.length, @@ -146,13 +172,32 @@ const comparisonCoverage = (context: CoverageInput) => { unpaired_right_variants: context.pairing.unpairedRight.length, omitted_left_variants: context.leftRetained.omitted, omitted_right_variants: context.rightRetained.omitted, - left_source_omitted_variants: leftSource?.omitted_return_sites ?? null, - right_source_omitted_variants: rightSource?.omitted_return_sites ?? null, - left_omitted_fields: leftSource?.omitted_fields ?? 0, - right_omitted_fields: rightSource?.omitted_fields ?? 0, - left_omitted_property_coverage: leftSource?.omitted_property_coverage ?? 0, - right_omitted_property_coverage: - rightSource?.omitted_property_coverage ?? 0, + // omitted_return_sites is itself null when the projection could not + // count them. + left_source_omitted_variants: knownOrNull( + leftSource, + ({ omitted_return_sites }) => omitted_return_sites, + ), + right_source_omitted_variants: knownOrNull( + rightSource, + ({ omitted_return_sites }) => omitted_return_sites, + ), + left_omitted_fields: knownOrNull( + leftSource, + ({ omitted_fields }) => omitted_fields, + ), + right_omitted_fields: knownOrNull( + rightSource, + ({ omitted_fields }) => omitted_fields, + ), + left_omitted_property_coverage: knownOrNull( + leftSource, + ({ omitted_property_coverage }) => omitted_property_coverage, + ), + right_omitted_property_coverage: knownOrNull( + rightSource, + ({ omitted_property_coverage }) => omitted_property_coverage, + ), omitted_candidates: omittedCandidates, omitted_changes: context.omittedChanges, }; @@ -172,8 +217,9 @@ const comparisonTruncated = ( const sourceProjectionTruncated = ( selection: SelectedJavaScriptExport, ): boolean => { - const coverage = selection.projection?.return_shape_coverage; - if (coverage === undefined) return false; + const source = sourceCoverage(selection); + if (!source.known) return false; + const coverage = source.value; return ( coverage.status === "truncated" || coverage.omitted_fields > 0 || @@ -194,19 +240,38 @@ const comparisonPartial = (context: CoverageInput): boolean => context.allChanges.some(({ status }) => status === "unknown"); const selectionPartial = (selection: SelectedJavaScriptExport): boolean => { - const coverage = selection.projection?.return_shape_coverage; + const source = sourceCoverage(selection); return ( selection.selection.status !== "selected" || !selection.observationComplete || - coverage?.status !== "complete" || - coverage.projection_complete !== true + !source.known || + source.value.status !== "complete" || + !source.value.projection_complete ); }; +/** Name each side whose source omission counts are null, and why. */ +const unknownSourceLimitations = ( + left: SelectedJavaScriptExport, + right: SelectedJavaScriptExport, +): string[] => + ( + [ + ["left", sourceCoverage(left)], + ["right", sourceCoverage(right)], + ] as const + ).flatMap(([side, source]) => + source.known + ? [] + : [ + `The ${side} export has no return-shape projection because ${source.reason}, so its source omission counts are null (unknown), not zero.`, + ], + ); + const comparisonLimitations = ( left: SelectedJavaScriptExport, right: SelectedJavaScriptExport, - status: "complete-within-inputs" | "partial" | "truncated", + status: JavaScriptExportShapeComparisonResult["coverage"]["status"], ): string[] => uniqueSorted([ "Return shapes are inferred from inert syntax and do not prove runtime behavior.", @@ -215,6 +280,7 @@ const comparisonLimitations = ( "This static comparison cannot establish runtime semantics; run behavioral probes directly against the relevant application versions when that evidence is required.", ...left.limitations, ...right.limitations, + ...unknownSourceLimitations(left, right), ...(status === "truncated" ? [ "Comparison output or source return-shape recovery reached an explicit limit.", @@ -225,6 +291,11 @@ const comparisonLimitations = ( "At least one selector, graph, return shape, or property boundary is incomplete.", ] : []), + ...(status === "unknown" + ? [ + "At least one source graph's coverage is unknown or unavailable, so the comparison's coverage is unknown.", + ] + : []), ]); const summarize = ( diff --git a/src/domain/javascript/javascriptExportShapeComparisonSchemas.ts b/src/domain/javascript/javascriptExportShapeComparisonSchemas.ts index 028ee0540c..5a673c5399 100644 --- a/src/domain/javascript/javascriptExportShapeComparisonSchemas.ts +++ b/src/domain/javascript/javascriptExportShapeComparisonSchemas.ts @@ -5,6 +5,7 @@ import { javascriptSourceRangeSchema } from "./javascriptSourceCoordinates.js"; import { evidenceSchema } from "../evidence.js"; import { prefixedDigestSchema } from "../digests.js"; import { nonEmptyTextSchema } from "../textSchemas.js"; +import { applicationCoverageStatusSchema } from "./javascriptApplicationEvidenceSchemas.js"; const evidenceIdSchema = prefixedDigestSchema("ev"); const graphIdSchema = prefixedDigestSchema("jag"); @@ -175,6 +176,15 @@ export const projectedExportReturnShapesSchema = z }); }); +/** A side's source omission count; null when the side has no return-shape projection. */ +const sourceOmissionCountSchema = z + .int() + .min(0) + .nullable() + .describe( + "Null (unknown) when the side's export selection recovered no return-shape projection; zero only when the projection omitted none.", + ); + const exportCandidateSchema = z.strictObject({ node_id: nodeIdSchema, module_path: nonEmptyTextSchema, @@ -283,19 +293,18 @@ export const javaScriptExportShapeComparisonResultSchema = z.strictObject({ }), changes: z.array(javaScriptExportShapeComparisonChangeSchema), coverage: z.strictObject({ - status: z.enum(["complete-within-inputs", "partial", "truncated"]), - left_graph_status: z.enum([ - "complete", + /** + * `unknown` when either source graph's coverage is unknown or + * unavailable; `truncated` and `partial` are known gaps. + */ + status: z.enum([ + "complete-within-inputs", "partial", + "truncated", "unknown", - "unavailable", - ]), - right_graph_status: z.enum([ - "complete", - "partial", - "unknown", - "unavailable", ]), + left_graph_status: applicationCoverageStatusSchema, + right_graph_status: applicationCoverageStatusSchema, paired_variants: z.int().min(0), unpaired_left_variants: z.int().min(0), unpaired_right_variants: z.int().min(0), @@ -303,10 +312,10 @@ export const javaScriptExportShapeComparisonResultSchema = z.strictObject({ omitted_right_variants: z.int().min(0), left_source_omitted_variants: z.int().min(0).nullable(), right_source_omitted_variants: z.int().min(0).nullable(), - left_omitted_fields: z.int().min(0), - right_omitted_fields: z.int().min(0), - left_omitted_property_coverage: z.int().min(0), - right_omitted_property_coverage: z.int().min(0), + left_omitted_fields: sourceOmissionCountSchema, + right_omitted_fields: sourceOmissionCountSchema, + left_omitted_property_coverage: sourceOmissionCountSchema, + right_omitted_property_coverage: sourceOmissionCountSchema, omitted_candidates: z.int().min(0), omitted_changes: z.int().min(0), }), diff --git a/src/domain/javascript/javascriptRuntimeReconciliationGraph.ts b/src/domain/javascript/javascriptRuntimeReconciliationGraph.ts index d1703ad3cd..df909f6886 100644 --- a/src/domain/javascript/javascriptRuntimeReconciliationGraph.ts +++ b/src/domain/javascript/javascriptRuntimeReconciliationGraph.ts @@ -9,6 +9,15 @@ import type { } from "./javascriptApplicationGraphSchemas.js"; import type { ParsedStaticLayer } from "./javascriptRuntimeReconciliationParsing.js"; import type { ParsedRuntimeCapture } from "./javascriptRuntimeReconciliationCaptureParsing.js"; +import { joinCoverageStatus } from "../coverage.js"; +import { + known, + knownOrNull, + sumKnownCounts, + unknownBecause, + type Known, +} from "../known.js"; +import { applicationCoverageKnowledge } from "./javascriptApplicationEvidenceSchemas.js"; import { uniqueSorted } from "../canonicalOrdering.js"; import { compareUnicodeCodePoints } from "../unicodeCodePointOrder.js"; import type { RuntimeProjection } from "./javascriptRuntimeReconciliationRuntime.js"; @@ -23,12 +32,55 @@ interface ReconciledGraphInput { interface GraphCoverageFacts { readonly projectionOmissions: number; - readonly knownOmissions: number; - readonly omissionsKnown: boolean; - readonly inputStatus: "complete" | "partial" | "truncated"; + /** Projection plus source omissions; unknown when any source cannot count. */ + readonly omissions: Known; + readonly inputStatus: ReconciliationInputStatus; + readonly inputTruncated: boolean; readonly outputTruncated: boolean; } +/** What the static graphs and passive captures establish about their coverage. */ +export type ReconciliationInputStatus = + | "complete" + | "partial" + | "truncated" + | "unknown"; + +/** + * The one reading of reconciliation input coverage. Bounded captures report + * only known gaps; a static graph whose producer could not tell or could not + * run makes the inputs unknown, which wins over a known truncation. + * `truncated` keeps a known input truncation even when the status is unknown. + */ +export const reconciliationInputCoverage = ( + input: Pick, +): { + readonly status: ReconciliationInputStatus; + readonly truncated: boolean; +} => { + const coverage = joinCoverageStatus([ + "complete", + ...input.layers.map(({ graph }) => + applicationCoverageKnowledge(graph.coverage.status), + ), + ...input.captures.map(({ inspection }) => + inspection.completeness.status === "complete_within_window" + ? ("complete" as const) + : ("partial" as const), + ), + ]); + const truncated = + input.layers.some(({ graph }) => graph.coverage.truncated) || + input.captures.some(({ inspection }) => + inspection.completeness.conditions.includes("truncated"), + ); + return { + status: + coverage === "unknown" ? "unknown" : truncated ? "truncated" : coverage, + truncated, + }; +}; + /** Combined graph plus omissions introduced while merging its observations. */ export interface ReconciledApplicationGraphProjection { readonly graph: JavaScriptApplicationGraph; @@ -61,11 +113,16 @@ export const buildReconciledApplicationGraph = ( "Runtime presence is bounded to passive capture windows and does not prove feature execution.", "Cross-layer observed_as edges are inferences; digest equality proves byte identity only.", "Source-map relationships retain their original static authority and are not promoted into runtime matches.", - ...(facts.inputStatus === "truncated" + ...(facts.inputTruncated ? [ "One or more source graphs or passive captures were incomplete or truncated.", ] : []), + ...(facts.inputStatus === "unknown" + ? [ + "One or more source graphs could not establish their coverage, so the reconciled graph's coverage is unknown.", + ] + : []), ...(facts.outputTruncated ? [ "The reconciled graph omitted entities or classifications during projection.", @@ -141,33 +198,27 @@ const graphCoverageFacts = ( inspection.completeness.attach_limited_sections.length > 0 || inspection.completeness.unavailable_sections.length > 0, ); - const inputTruncated = - input.layers.some(({ graph }) => graph.coverage.truncated) || - captureTruncated; - const inputComplete = - input.layers.every(({ graph }) => graph.coverage.status === "complete") && - input.captures.every( - ({ inspection }) => - inspection.completeness.status === "complete_within_window", - ); const outputTruncated = projectionOmissions > 0; - const sourceOmissions = input.layers.reduce( - (total, { graph }) => total + (graph.coverage.omitted_count ?? 0), - 0, - ); - const omissionsKnown = - !captureTruncated && - !captureHasUnknownOmissions && - input.layers.every(({ graph }) => graph.coverage.omitted_count !== null); + const omissions = captureTruncated + ? unknownBecause("a passive capture is truncated") + : captureHasUnknownOmissions + ? unknownBecause( + "a passive capture has attach-limited or unavailable sections", + ) + : sumKnownCounts([ + known(projectionOmissions), + ...input.layers.map(({ graph }) => + graph.coverage.omitted_count === null + ? unknownBecause("a static graph did not count its omissions") + : known(graph.coverage.omitted_count), + ), + ]); + const inputCoverage = reconciliationInputCoverage(input); return { projectionOmissions, - knownOmissions: projectionOmissions + sourceOmissions, - omissionsKnown, - inputStatus: inputTruncated - ? "truncated" - : inputComplete - ? "complete" - : "partial", + omissions, + inputStatus: inputCoverage.status, + inputTruncated: inputCoverage.truncated, outputTruncated, }; }; @@ -177,40 +228,42 @@ const graphCoverage = ( facts: GraphCoverageFacts, nodeCount: number, ): JavaScriptApplicationGraph["coverage"] => - facts.inputStatus === "complete" && !facts.outputTruncated - ? { status: "complete", truncated: false, omitted_count: 0, limits: [] } - : facts.inputStatus === "truncated" || facts.outputTruncated - ? { - status: "partial", - truncated: true, - omitted_count: facts.omissionsKnown ? facts.knownOmissions : null, - limits: [ - ...(facts.inputStatus === "truncated" - ? [ - { - name: "runtime-reconciliation-input-coverage", - value: input.layers.length + input.captures.length, - unit: "items" as const, - }, - ] - : []), - ...(facts.outputTruncated - ? [ - { - name: "runtime-reconciliation-output-limits", - value: nodeCount, - unit: "items" as const, - }, - ] - : []), - ], - } - : { - status: "partial", - truncated: false, - omitted_count: facts.omissionsKnown ? facts.knownOmissions : null, - limits: [], - }; + facts.inputStatus === "unknown" + ? { status: "unknown", truncated: false, omitted_count: null, limits: [] } + : facts.inputStatus === "complete" && !facts.outputTruncated + ? { status: "complete", truncated: false, omitted_count: 0, limits: [] } + : facts.inputStatus === "truncated" || facts.outputTruncated + ? { + status: "partial", + truncated: true, + omitted_count: knownOrNull(facts.omissions, (count) => count), + limits: [ + ...(facts.inputStatus === "truncated" + ? [ + { + name: "runtime-reconciliation-input-coverage", + value: input.layers.length + input.captures.length, + unit: "items" as const, + }, + ] + : []), + ...(facts.outputTruncated + ? [ + { + name: "runtime-reconciliation-output-limits", + value: nodeCount, + unit: "items" as const, + }, + ] + : []), + ], + } + : { + status: "partial", + truncated: false, + omitted_count: knownOrNull(facts.omissions, (count) => count), + limits: [], + }; const uniqueEdges = (edges: readonly ApplicationEdge[]): ApplicationEdge[] => [ ...new Map(edges.map((edge) => [edge.edge_id, edge])).values(), diff --git a/src/domain/javascript/javascriptRuntimeReconciliationInputStatus.test.ts b/src/domain/javascript/javascriptRuntimeReconciliationInputStatus.test.ts new file mode 100644 index 0000000000..ec229e091f --- /dev/null +++ b/src/domain/javascript/javascriptRuntimeReconciliationInputStatus.test.ts @@ -0,0 +1,66 @@ +import { expect, it } from "vitest"; + +import type { JavaScriptApplicationGraph } from "./javascriptApplicationGraph.js"; +import { reconciliationInputCoverage } from "./javascriptRuntimeReconciliationGraph.js"; + +const status = (input: Input) => reconciliationInputCoverage(input).status; + +type Input = Parameters[0]; +type Coverage = JavaScriptApplicationGraph["coverage"]; + +// Only the coverage facts the reading consumes; the rest of a parsed layer or +// capture does not affect it. +const layer = (coverage: Coverage): Input["layers"][number] => + ({ graph: { coverage } }) as unknown as Input["layers"][number]; +const capture = ( + status: "complete_within_window" | "attach_limited" | "truncated", +): Input["captures"][number] => + ({ + inspection: { completeness: { status, conditions: [status] } }, + }) as unknown as Input["captures"][number]; + +const complete: Coverage = { + status: "complete", + truncated: false, + omitted_count: 0, + limits: [], +}; +const unknown = (status: "unknown" | "unavailable"): Coverage => ({ + status, + truncated: false, + omitted_count: null, + limits: [], +}); + +it("reads complete inputs as complete and a limited capture as a known gap", () => { + expect( + status({ + layers: [layer(complete)], + captures: [capture("complete_within_window")], + }), + ).toBe("complete"); + expect( + status({ + layers: [layer(complete)], + captures: [capture("attach_limited")], + }), + ).toBe("partial"); + expect( + status({ + layers: [layer(complete)], + captures: [capture("truncated")], + }), + ).toBe("truncated"); +}); + +it.each(["unknown", "unavailable"] as const)( + "reads a %s static graph as unknown and keeps a truncated capture's truncation", + (graphStatus) => { + expect( + reconciliationInputCoverage({ + layers: [layer(complete), layer(unknown(graphStatus))], + captures: [capture("truncated")], + }), + ).toEqual({ status: "unknown", truncated: true }); + }, +); diff --git a/src/domain/javascript/javascriptRuntimeReconciliationResult.ts b/src/domain/javascript/javascriptRuntimeReconciliationResult.ts index 4483a46fd7..cdaada5e25 100644 --- a/src/domain/javascript/javascriptRuntimeReconciliationResult.ts +++ b/src/domain/javascript/javascriptRuntimeReconciliationResult.ts @@ -1,6 +1,10 @@ import type { JavaScriptApplicationGraph } from "./javascriptApplicationGraph.js"; import { digestCanonicalValue } from "../canonicalDigest.js"; import { uniqueSorted } from "../canonicalOrdering.js"; +import { + reconciliationInputCoverage, + type ReconciliationInputStatus, +} from "./javascriptRuntimeReconciliationGraph.js"; import type { StaticLoadStateProjection } from "./javascriptRuntimeLoadState.js"; import type { RuntimeMatchingProjection } from "./javascriptRuntimeReconciliationMatching.js"; import type { ParsedStaticLayer } from "./javascriptRuntimeReconciliationParsing.js"; @@ -23,7 +27,8 @@ interface ReconciliationProjection { interface CompletionFlags { readonly outputTruncated: boolean; - readonly inputStatus: "complete" | "partial" | "truncated"; + readonly inputStatus: ReconciliationInputStatus; + readonly inputTruncated: boolean; } /** Build and verify the deterministic caller-visible reconciliation result. */ @@ -144,45 +149,35 @@ const reconciliationCoverage = ( completion: CompletionFlags, ): JavaScriptRuntimeReconciliationResult["coverage"] => ({ status: - completion.outputTruncated || completion.inputStatus === "truncated" - ? "truncated" - : completion.inputStatus === "partial" - ? "partial" - : "complete-within-inputs", - truncated: - completion.outputTruncated || completion.inputStatus === "truncated", + completion.inputStatus === "unknown" + ? "unknown" + : completion.outputTruncated || completion.inputStatus === "truncated" + ? "truncated" + : completion.inputStatus === "partial" + ? "partial" + : "complete-within-inputs", + // A known input truncation stays visible even when the status is unknown. + truncated: completion.outputTruncated || completion.inputTruncated, omitted_runtime_entities: input.runtime.omittedEntities, omitted_reconciliation_items: input.matching.omittedItems, omitted_static_load_states: input.loadStates.omittedStates, omitted_graph_items: input.omittedGraphItems, }); -const completionFlags = (input: ReconciliationProjection): CompletionFlags => { - const inputTruncated = - input.layers.some(({ graph }) => graph.coverage.truncated) || - input.captures.some(({ inspection }) => - inspection.completeness.conditions.includes("truncated"), - ); - const inputPartial = - input.layers.some(({ graph }) => graph.coverage.status !== "complete") || - input.captures.some( - ({ inspection }) => - inspection.completeness.status !== "complete_within_window", - ); - return { - outputTruncated: - input.runtime.omittedEntities > 0 || - input.matching.omittedItems > 0 || - input.loadStates.omittedStates > 0 || - input.omittedGraphItems > 0, - inputStatus: inputTruncated - ? "truncated" - : inputPartial - ? "partial" - : "complete", - }; +const inputCompletion = (input: ReconciliationProjection) => { + const { status, truncated } = reconciliationInputCoverage(input); + return { inputStatus: status, inputTruncated: truncated }; }; +const completionFlags = (input: ReconciliationProjection): CompletionFlags => ({ + outputTruncated: + input.runtime.omittedEntities > 0 || + input.matching.omittedItems > 0 || + input.loadStates.omittedStates > 0 || + input.omittedGraphItems > 0, + ...inputCompletion(input), +}); + const reconciliationLimitations = (completion: CompletionFlags): string[] => uniqueSorted([ "Only caller-supplied, semantically verified Evidence records were reconciled.", @@ -191,9 +186,13 @@ const reconciliationLimitations = (completion: CompletionFlags): string[] => "Not-observed means absent from the bounded captures in scope, never globally unloaded.", "Caller-declared file and URL mappings are inference inputs and do not expand CDP origin or filesystem-root authority.", "Source-map authority remains separate from passive runtime authority.", - ...(completion.inputStatus !== "complete" - ? ["One or more static graphs or passive captures were incomplete."] - : []), + ...(completion.inputStatus === "unknown" + ? [ + "One or more static graphs could not establish their coverage, so reconciliation coverage is unknown.", + ] + : completion.inputStatus !== "complete" + ? ["One or more static graphs or passive captures were incomplete."] + : []), ...(completion.outputTruncated ? [ "Runtime reconciliation omitted entities or classifications during projection.", diff --git a/src/domain/javascript/javascriptRuntimeReconciliationSchemas.ts b/src/domain/javascript/javascriptRuntimeReconciliationSchemas.ts index b678e67376..662c6916cb 100644 --- a/src/domain/javascript/javascriptRuntimeReconciliationSchemas.ts +++ b/src/domain/javascript/javascriptRuntimeReconciliationSchemas.ts @@ -285,7 +285,16 @@ export const javascriptRuntimeReconciliationResultSchema = z.strictObject({ limitation: nonEmptyTextSchema, }), coverage: z.strictObject({ - status: z.enum(["complete-within-inputs", "partial", "truncated"]), + /** + * `unknown` when a static graph's coverage is unknown or unavailable; + * `truncated` and `partial` are known gaps. + */ + status: z.enum([ + "complete-within-inputs", + "partial", + "truncated", + "unknown", + ]), truncated: z.boolean(), omitted_runtime_entities: z.int().min(0), omitted_reconciliation_items: z.int().min(0), diff --git a/src/domain/known.test.ts b/src/domain/known.test.ts new file mode 100644 index 0000000000..607b3868c6 --- /dev/null +++ b/src/domain/known.test.ts @@ -0,0 +1,23 @@ +import { expect, it } from "vitest"; + +import { known, knownOrNull, sumKnownCounts, unknownBecause } from "./known.js"; + +it("sums known counts and keeps the first unknown rather than counting it as zero", () => { + expect(sumKnownCounts([])).toEqual(known(0)); + expect(sumKnownCounts([known(2), known(3)])).toEqual(known(5)); + expect( + sumKnownCounts([ + known(2), + unknownBecause("first"), + known(3), + unknownBecause("second"), + ]), + ).toEqual({ known: false, reason: "first" }); +}); + +it("projects an unknown fact to null and a known zero to zero", () => { + expect(knownOrNull(known(0), (count) => count)).toBe(0); + expect(knownOrNull(unknownBecause("unread"), (count: number) => count)).toBe( + null, + ); +}); diff --git a/src/domain/known.ts b/src/domain/known.ts new file mode 100644 index 0000000000..150afb47a4 --- /dev/null +++ b/src/domain/known.ts @@ -0,0 +1,38 @@ +/** + * A fact its producer established, or the reason it could not. An unknown + * fact is never a default value: a count it would have supplied is unknown, + * not zero, and a list is unknown, not empty. + */ +export type Known = + | { readonly known: true; readonly value: T } + | { readonly known: false; readonly reason: string }; + +/** A fact the producer established. */ +export const known = (value: T): Known => ({ known: true, value }); + +/** A fact the producer could not establish, with why. */ +export const unknownBecause = (reason: string): Known => ({ + known: false, + reason, +}); + +/** + * Sum counts; one unknown count makes the sum unknown, with the first + * unknown's reason, rather than counting as zero. + */ +export const sumKnownCounts = ( + counts: readonly Known[], +): Known => { + let total = 0; + for (const count of counts) { + if (!count.known) return count; + total += count.value; + } + return known(total); +}; + +/** Project a fact onto a wire field where `null` means unknown. */ +export const knownOrNull = ( + fact: Known, + read: (value: T) => R, +): R | null => (fact.known ? read(fact.value) : null); diff --git a/tests/boundary/filesystem/javascriptExportShapeComparison.test.ts b/tests/boundary/filesystem/javascriptExportShapeComparison.test.ts index 2bc51d20a0..4bd55451b0 100644 --- a/tests/boundary/filesystem/javascriptExportShapeComparison.test.ts +++ b/tests/boundary/filesystem/javascriptExportShapeComparison.test.ts @@ -301,6 +301,103 @@ describe("JavaScript export return-shape value uncertainty", () => { }); }); +describe("JavaScript export comparison source-graph coverage", () => { + it.each(["unknown", "unavailable"] as const)( + "reports unknown, not partial, when a source graph's coverage is %s", + async (status) => { + const [left, right] = await analyzeSources({ + left: 'export default () => ({kind:"result"});', + right: 'export default () => ({kind:"result",total:1});', + }); + expect(compare(left, right).coverage.status).toBe( + "complete-within-inputs", + ); + const { graph_id: _graphId, ...input } = right.graph; + const graph = createJavaScriptApplicationGraph({ + ...input, + coverage: { status, truncated: false, omitted_count: null, limits: [] }, + limitations: ["Fixture graph coverage cannot be established."], + }); + const result = javaScriptExportShapeComparisonResultSchema.parse( + compare(left, { ...right, graph }), + ); + expect(result.coverage).toMatchObject({ + status: "unknown", + right_graph_status: status, + }); + expect(result.limitations).toContain( + "At least one source graph's coverage is unknown or unavailable, so the comparison's coverage is unknown.", + ); + }, + ); +}); + +describe("JavaScript export comparison mixed source coverage", () => { + it("keeps unknown source-graph coverage beside a truncated return-shape projection, with its omission counts", async () => { + const [left, right] = await analyzeSources({ + left: 'export default () => ({kind:"result"});', + right: 'export default () => ({kind:"result",total:1});', + }); + // Left: a known projection limit (two omitted fields). + const truncatedLeft = createJavaScriptApplicationGraph({ + schema: "JavaScriptApplicationGraph", + root_node_ids: left.graph.root_node_ids, + edges: left.graph.edges, + coverage: left.graph.coverage, + limitations: left.graph.limitations, + nodes: left.graph.nodes.map((node) => + createJavaScriptApplicationNode({ + kind: node.kind, + identity: node.identity, + observations: node.observations.map( + ({ label, properties, evidence }) => ({ + label, + evidence, + properties: + properties.semantic_role !== "export-return-shapes" + ? properties + : { + ...properties, + return_shape_coverage: { + ...projectedExportReturnShapesSchema.parse(properties) + .return_shape_coverage, + omitted_fields: 2, + projection_complete: false, + }, + }, + }), + ), + }), + ), + }); + expect( + compare({ ...left, graph: truncatedLeft }, right).coverage.status, + ).toBe("truncated"); + // Right: a source graph that cannot tell its coverage. + const { graph_id: _graphId, ...input } = right.graph; + const unknownRight = createJavaScriptApplicationGraph({ + ...input, + coverage: { + status: "unknown", + truncated: false, + omitted_count: null, + limits: [], + }, + limitations: ["Fixture graph coverage cannot be established."], + }); + expect( + compare( + { ...left, graph: truncatedLeft }, + { ...right, graph: unknownRight }, + ).coverage, + ).toMatchObject({ + status: "unknown", + left_omitted_fields: 2, + right_graph_status: "unknown", + }); + }); +}); + describe("JavaScript export return-shape pairing limits", () => { it("does not pair an inline discriminant with absent or unknown presence", async () => { const rows = [ @@ -1148,6 +1245,19 @@ describe("JavaScript export return-shape selection", () => { expect.objectContaining({ export_name: "third" }), ]), }); + // The missing side recovered no return shapes, so its source omission + // counts are unknown, not zero; the selected side keeps its counts. + expect(missing.coverage).toMatchObject({ + left_source_omitted_variants: null, + left_omitted_fields: null, + left_omitted_property_coverage: null, + right_source_omitted_variants: 0, + right_omitted_fields: 0, + right_omitted_property_coverage: 0, + }); + expect(missing.limitations).toContain( + "The left export has no return-shape projection because the export selection is missing, so its source omission counts are null (unknown), not zero.", + ); const parsers = await sourceOwnedParsers(); const variants = compare(parsers[0], parsers[1]);