reverseport 0.0.0-stage → 1.0.0

package/dist/domain/javascript/javascriptApplicationGraph.js

@@ -0,0 +1,378 @@
+import { z } from "zod";
+import { arrayContainerSchema, parseElementSteps, } from "../zodCollectionSteps.js";
+import { canonicalJsonDigestSteps } from "../canonicalJsonDigestSteps.js";
+import { canonicalJson } from "../comparisonSemantics.js";
+import { digestCanonicalValue } from "../canonicalDigest.js";
+import { uniqueSorted } from "../canonicalOrdering.js";
+import { compareUnicodeCodePoints } from "../unicodeCodePointOrder.js";
+import { freezeJsonSnapshot, freezeOwnedJsonSnapshotSteps, } from "../immutableJson.js";
+import { applicationEdgeInputSchema, applicationEdgeSchema, applicationNodeInputSchema, applicationNodeObservationSchema, applicationNodeSchema, javascriptApplicationGraphInputSchema, javascriptApplicationGraphRecordSchema, } from "./javascriptApplicationGraphSchemas.js";
+const OBSERVATION_IDENTIFIER_STRATEGY = {
+    strategy: "semantic-content-sha256",
+    stability: "observation-exact",
+};
+const EDGE_IDENTIFIER_STRATEGY = {
+    strategy: "semantic-content-sha256",
+    stability: "relationship-exact",
+};
+const limitKey = (limit) => canonicalJson(limit, "JavaScript Application Graph");
+const normalizeLimits = (limits) => [...new Map(limits.map((limit) => [limitKey(limit), limit])).values()].sort((left, right) => compareUnicodeCodePoints(limitKey(left), limitKey(right)));
+const normalizeEvidence = (evidence) => ({
+    ...evidence,
+    coverage: {
+        ...evidence.coverage,
+        limits: normalizeLimits(evidence.coverage.limits),
+    },
+    limitations: uniqueSorted(evidence.limitations),
+    evidence_ids: uniqueSorted(evidence.evidence_ids),
+});
+const normalizeIdentity = (identity) => identity.strategy === "structural-fingerprint"
+    ? { ...identity, basis: uniqueSorted(identity.basis) }
+    : identity;
+const nodeSemantic = (node) => ({
+    kind: node.kind,
+    identity: node.identity,
+});
+const nodeId = (node) => `jag_node_${digestCanonicalValue(nodeSemantic(node), "JavaScript Application Graph")}`;
+const observationSemantic = (nodeIdentifier, observation) => ({ node_id: nodeIdentifier, ...observation });
+const observationId = (nodeIdentifier, observation) => `jag_observation_${digestCanonicalValue(observationSemantic(nodeIdentifier, observation))}`;
+const edgeId = (edge) => `jag_edge_${digestCanonicalValue(edge, "JavaScript Application Graph")}`;
+const sortedUniqueIssue = (values, path, label, context) => {
+    for (let index = 1; index < values.length; index += 1) {
+        if (compareUnicodeCodePoints(values[index - 1] ?? "", values[index] ?? "") < 0)
+            continue;
+        context.addIssue({
+            code: "custom",
+            message: `${label} must be sorted and unique by Unicode code point`,
+            path: [...path, index],
+        });
+        return;
+    }
+};
+const checkEvidenceNormalization = (evidence, path, context) => {
+    sortedUniqueIssue(evidence.limitations, [...path, "limitations"], "Evidence limitations", context);
+    sortedUniqueIssue(evidence.evidence_ids, [...path, "evidence_ids"], "Evidence identifiers", context);
+    sortedUniqueIssue(evidence.coverage.limits.map(limitKey), [...path, "coverage", "limits"], "Evidence limits", context);
+    const runtimeLocation = evidence.location.available && evidence.location.value.kind === "runtime";
+    const staticAuthority = [
+        "artifact-bytes",
+        "ast-static-analysis",
+        "static-relationship-inference",
+        "native-analysis-provider",
+    ].includes(evidence.authority);
+    if (runtimeLocation && staticAuthority)
+        context.addIssue({
+            code: "custom",
+            message: "Static and native authorities cannot claim a runtime location",
+            path: [...path, "location"],
+        });
+};
+const sourceMapObservationMatchesIdentity = (identity, observation) => {
+    const { evidence, source_map_reference: reference } = observation;
+    const sourceDigests = [
+        observation.properties.content_sha256,
+        // Older graph producers used `source_sha256` for the same source-map fact.
+        observation.properties.source_sha256,
+    ];
+    const hasKnownSourceDigest = identity.source_sha256 !== null;
+    const sourceDigestMatches = sourceDigests.every((digest) => digest === undefined ||
+        digest === null ||
+        digest === identity.source_sha256) &&
+        (!hasKnownSourceDigest || sourceDigests.includes(identity.source_sha256));
+    const contentAvailabilityMatches = (observation.properties.content_available !== true ||
+        hasKnownSourceDigest) &&
+        (observation.properties.content_available !== false ||
+            !hasKnownSourceDigest);
+    return (sourceDigestMatches &&
+        contentAvailabilityMatches &&
+        reference !== null &&
+        evidence.state === "observed" &&
+        evidence.artifact.available &&
+        evidence.artifact.sha256 === identity.source_map_sha256 &&
+        reference.source_name === identity.original_source &&
+        reference.source_root === identity.source_root &&
+        evidence.location.available &&
+        evidence.location.value.kind === "artifact-path" &&
+        reference.map_path === evidence.location.value.path);
+};
+const observationMatchesIdentity = (node, observation) => {
+    const { identity } = node;
+    const { evidence } = observation;
+    if (identity.strategy === "content-digest")
+        return (evidence.state === "observed" &&
+            evidence.artifact.available &&
+            evidence.artifact.sha256 === identity.sha256);
+    if (identity.strategy === "source-map-original")
+        return sourceMapObservationMatchesIdentity(identity, observation);
+    if (identity.strategy === "canonical-path")
+        return (evidence.artifact.available &&
+            evidence.artifact.sha256 === identity.artifact_sha256 &&
+            evidence.location.available &&
+            evidence.location.value.kind === "artifact-path" &&
+            evidence.location.value.path === identity.path);
+    if (identity.strategy === "artifact-local-key")
+        return (evidence.artifact.available &&
+            evidence.artifact.sha256 === identity.artifact_sha256);
+    if (identity.strategy === "runtime-instance") {
+        if (!["passive-cdp-runtime", "controlled-replay"].includes(evidence.authority) ||
+            !evidence.location.available ||
+            evidence.location.value.kind !== "runtime")
+            return false;
+        const location = evidence.location.value;
+        return (location.capture_sha256 === identity.capture_sha256 &&
+            [location.target_key, location.frame_key, location.script_key].includes(identity.runtime_key));
+    }
+    if (identity.strategy === "structural-fingerprint")
+        return evidence.state === "inferred";
+    return evidence.state === "observed";
+};
+const checkNode = (node, index, context) => {
+    if (node.node_id !== nodeId(node))
+        context.addIssue({
+            code: "custom",
+            message: "Node identifier does not match its kind and identity",
+            path: ["nodes", index, "node_id"],
+        });
+    if (node.identity.strategy === "structural-fingerprint" &&
+        canonicalJson(node.identity.basis, "JavaScript Application Graph") !==
+            canonicalJson(uniqueSorted(node.identity.basis), "JavaScript Application Graph"))
+        context.addIssue({
+            code: "custom",
+            message: "Structural fingerprint basis must be sorted and unique",
+            path: ["nodes", index, "identity", "basis"],
+        });
+    sortedUniqueIssue(node.observations.map(({ observation_id: id }) => id), ["nodes", index, "observations"], "Node observations", context);
+    for (const [observationIndex, observation] of node.observations.entries()) {
+        const { observation_id: identifier, ...semantic } = observation;
+        if (identifier !== observationId(node.node_id, semantic))
+            context.addIssue({
+                code: "custom",
+                message: "Observation identifier does not match its semantic content",
+                path: [
+                    "nodes",
+                    index,
+                    "observations",
+                    observationIndex,
+                    "observation_id",
+                ],
+            });
+        if (node.identity.strategy === "source-map-original" &&
+            !observationMatchesIdentity(node, observation))
+            context.addIssue({
+                code: "custom",
+                message: "Source-map observation must retain its exact declaration and map location",
+                path: [
+                    "nodes",
+                    index,
+                    "observations",
+                    observationIndex,
+                    "source_map_reference",
+                ],
+            });
+        checkEvidenceNormalization(observation.evidence, ["nodes", index, "observations", observationIndex, "evidence"], context);
+    }
+    if (!node.observations.some((observation) => observationMatchesIdentity(node, observation)))
+        context.addIssue({
+            code: "custom",
+            message: "Node identity is not supported by a compatible observation",
+            path: ["nodes", index, "identity"],
+        });
+};
+const checkGraphContent = (graph, context) => {
+    const steps = checkGraphContentSteps(graph, context);
+    while (steps.next().done !== true)
+        ;
+};
+function* checkGraphContentSteps(graph, context) {
+    sortedUniqueIssue(graph.root_node_ids, ["root_node_ids"], "Root nodes", context);
+    sortedUniqueIssue(graph.nodes.map(({ node_id: id }) => id), ["nodes"], "Nodes", context);
+    sortedUniqueIssue(graph.edges.map(({ edge_id: id }) => id), ["edges"], "Edges", context);
+    sortedUniqueIssue(graph.limitations, ["limitations"], "Graph limitations", context);
+    sortedUniqueIssue(graph.coverage.limits.map(limitKey), ["coverage", "limits"], "Graph limits", context);
+    if (graph.coverage.status !== "complete" && graph.limitations.length === 0)
+        context.addIssue({
+            code: "custom",
+            message: "Non-complete graph coverage requires an explicit limitation",
+            path: ["limitations"],
+        });
+    const nodesById = new Map(graph.nodes.map((node) => [node.node_id, node]));
+    for (const root of graph.root_node_ids)
+        if (!nodesById.has(root))
+            context.addIssue({
+                code: "custom",
+                message: "Root identifier must name a graph node",
+                path: ["root_node_ids"],
+            });
+    for (const [index, node] of graph.nodes.entries()) {
+        if (index % 64 === 0)
+            yield;
+        checkNode(node, index, context);
+    }
+    for (const [index, edge] of graph.edges.entries()) {
+        if (index % 64 === 0)
+            yield;
+        const { edge_id: identifier, ...semantic } = edge;
+        if (identifier !== edgeId(semantic))
+            context.addIssue({
+                code: "custom",
+                message: "Edge identifier does not match its semantic content",
+                path: ["edges", index, "edge_id"],
+            });
+        if (!nodesById.has(edge.source_node_id) ||
+            !nodesById.has(edge.target_node_id))
+            context.addIssue({
+                code: "custom",
+                message: "Edge endpoints must name graph nodes",
+                path: ["edges", index],
+            });
+        if (edge.source_node_id === edge.target_node_id)
+            context.addIssue({
+                code: "custom",
+                message: "Application graph edges cannot be self-referential",
+                path: ["edges", index],
+            });
+        if (edge.relation === "changed_from" &&
+            nodesById.get(edge.source_node_id)?.kind !==
+                nodesById.get(edge.target_node_id)?.kind)
+            context.addIssue({
+                code: "custom",
+                message: "changed_from endpoints must have the same node kind",
+                path: ["edges", index, "relation"],
+            });
+        checkEvidenceNormalization(edge.evidence, ["edges", index, "evidence"], context);
+    }
+}
+const checkGraphInvariants = (graph, context) => {
+    checkGraphContent(graph, context);
+    const { graph_id: identifier, ...semantic } = graph;
+    if (identifier !==
+        `jag_${digestCanonicalValue(semantic, "JavaScript Application Graph")}`)
+        context.addIssue({
+            code: "custom",
+            message: "Graph identifier does not match its semantic content",
+            path: ["graph_id"],
+        });
+};
+/** Strict JavaScript Application Graph with verified commitments. */
+export const javascriptApplicationGraphSchema = javascriptApplicationGraphRecordSchema.superRefine(checkGraphInvariants);
+const javascriptApplicationGraphContentSchema = javascriptApplicationGraphInputSchema.superRefine(checkGraphContent);
+/** Build one normalized application entity and derive all semantic IDs. */
+export const createJavaScriptApplicationNode = (input) => {
+    const parsed = applicationNodeInputSchema.parse(input);
+    // These properties are newly parsed and exclusively owned. Authenticate
+    // them before the observation/node schemas and final graph validate again.
+    for (const observation of parsed.observations)
+        freezeJsonSnapshot(observation.properties);
+    const identity = normalizeIdentity(parsed.identity);
+    const identifier = nodeId({ kind: parsed.kind, identity });
+    const observations = parsed.observations
+        .map((observation) => {
+        const semantic = {
+            ...observation,
+            evidence: normalizeEvidence(observation.evidence),
+            identifier_strategy: OBSERVATION_IDENTIFIER_STRATEGY,
+        };
+        return applicationNodeObservationSchema.parse({
+            ...semantic,
+            observation_id: observationId(identifier, semantic),
+        });
+    })
+        .sort((left, right) => compareUnicodeCodePoints(left.observation_id, right.observation_id));
+    return applicationNodeSchema.parse({
+        node_id: identifier,
+        kind: parsed.kind,
+        identity,
+        observations,
+    });
+};
+/** Build one normalized directed relationship and derive its semantic ID. */
+export const createJavaScriptApplicationEdge = (input) => {
+    const parsed = applicationEdgeInputSchema.parse(input);
+    freezeJsonSnapshot(parsed.properties);
+    const semantic = {
+        ...parsed,
+        evidence: normalizeEvidence(parsed.evidence),
+        identifier_strategy: EDGE_IDENTIFIER_STRATEGY,
+    };
+    return applicationEdgeSchema.parse({
+        ...semantic,
+        edge_id: edgeId(semantic),
+    });
+};
+/** Normalize a complete graph and derive its top-level semantic ID. */
+export const createJavaScriptApplicationGraph = (input) => {
+    const semantic = normalizeGraphInput(javascriptApplicationGraphInputSchema.parse(input));
+    const content = javascriptApplicationGraphContentSchema.parse(semantic);
+    return {
+        ...content,
+        graph_id: `jag_${digestCanonicalValue(content, "JavaScript Application Graph")}`,
+    };
+};
+const normalizeGraphInput = (parsed) => ({
+    ...parsed,
+    root_node_ids: uniqueSorted(parsed.root_node_ids),
+    nodes: [...parsed.nodes].sort((left, right) => compareUnicodeCodePoints(left.node_id, right.node_id)),
+    edges: [...parsed.edges].sort((left, right) => compareUnicodeCodePoints(left.edge_id, right.edge_id)),
+    coverage: {
+        ...parsed.coverage,
+        limits: normalizeLimits(parsed.coverage.limits),
+    },
+    limitations: uniqueSorted(parsed.limitations),
+});
+const validatedImmutableApplicationGraphs = new WeakSet();
+/** Clone and validate synchronously, then return steps to seal the owned graph. */
+export const createImmutableJavaScriptApplicationGraphSteps = (input) => sealValidatedApplicationGraphSteps(createJavaScriptApplicationGraph(input));
+const applicationGraphShape = javascriptApplicationGraphInputSchema.shape;
+const applicationGraphContainerSchema = javascriptApplicationGraphInputSchema.extend({
+    nodes: arrayContainerSchema(applicationGraphShape.nodes),
+    edges: arrayContainerSchema(applicationGraphShape.edges),
+});
+/**
+ * Seal a graph whose input the caller transfers: the caller neither retains nor
+ * mutates any part of it afterwards. Only the graph's own fields are validated
+ * synchronously; nodes and edges are validated, checked, hashed and frozen in
+ * steps, because doing so at once held the event loop for large applications.
+ */
+export const sealTransferredJavaScriptApplicationGraphSteps = (input) => parseAndSealApplicationGraphSteps(applicationGraphContainerSchema.parse(input));
+function* parseAndSealApplicationGraphSteps(container) {
+    const issues = [];
+    const parsed = {
+        ...container,
+        nodes: yield* parseElementSteps(applicationGraphShape.nodes.element, container.nodes, ["nodes"], issues),
+        edges: yield* parseElementSteps(applicationGraphShape.edges.element, container.edges, ["edges"], issues),
+    };
+    if (issues.length > 0)
+        throw new z.ZodError(issues);
+    const content = normalizeGraphInput(parsed);
+    let invalid = false;
+    yield* checkGraphContentSteps(content, {
+        addIssue: () => {
+            invalid = true;
+        },
+    });
+    // An invalid owned graph is a construction defect; report it with the exact
+    // issues the content schema produces.
+    if (invalid) {
+        javascriptApplicationGraphContentSchema.parse(content);
+        throw new TypeError("Application graph checks disagree with its schema");
+    }
+    return yield* sealValidatedApplicationGraphSteps({
+        ...content,
+        graph_id: `jag_${yield* canonicalJsonDigestSteps(content)}`,
+    });
+}
+function* sealValidatedApplicationGraphSteps(graph) {
+    yield* freezeOwnedJsonSnapshotSteps(graph);
+    validatedImmutableApplicationGraphs.add(graph);
+    return graph;
+}
+/** Recognize the exact completely sealed graph produced by the owned factory. */
+export const isValidatedImmutableJavaScriptApplicationGraph = (value) => typeof value === "object" &&
+    value !== null &&
+    validatedImmutableApplicationGraphs.has(value);
+/** Parse a stored graph and reject stale IDs. */
+export const parseJavaScriptApplicationGraph = (input) => javascriptApplicationGraphSchema.parse(input);
+/** Compute the byte-stable SHA-256 commitment of a verified graph. */
+export const computeJavaScriptApplicationGraphSha256 = (input) => digestCanonicalValue(parseJavaScriptApplicationGraph(input), "JavaScript Application Graph");
+/** Serialize a verified graph as RFC 8785 canonical JSON. */
+export const serializeJavaScriptApplicationGraph = (input) => canonicalJson(parseJavaScriptApplicationGraph(input), "JavaScript Application Graph");

package/dist/domain/javascript/javascriptApplicationGraphSchemas.js

@@ -0,0 +1,126 @@
+import { z } from "zod";
+import { javascriptSourceMapReferenceSchema } from "./javascriptSourceMapPaths.js";
+import { applicationCoverageSchema, applicationGraphEvidenceSchema, applicationNodeIdentitySchema, } from "./javascriptApplicationEvidenceSchemas.js";
+import { jsonValueSchema } from "../jsonValue.js";
+import { prefixedDigestSchema } from "../digests.js";
+const boundedTextSchema = z.string().min(1);
+/** Node kinds admitted by JavaScript Application Graph. */
+export const JAVASCRIPT_APPLICATION_NODE_KINDS = [
+    "package",
+    "installer",
+    "artifact",
+    "asar-entry",
+    "electron-main",
+    "electron-preload",
+    "electron-renderer",
+    "electron-utility",
+    "javascript-asset",
+    "javascript-chunk",
+    "javascript-module",
+    "javascript-expression",
+    "source-map",
+    "source-module",
+    "browser-window",
+    "frame",
+    "target",
+    "context-bridge-api",
+    "ipc-channel",
+    "ipc-handler",
+    "worker",
+    "service-worker",
+    "endpoint",
+    "storage",
+    "native-addon",
+    "native-export",
+    "managed-assembly",
+    "managed-module",
+    "managed-type",
+    "managed-method",
+    "managed-field",
+    "managed-pinvoke-import",
+    "managed-native-implementation",
+    "runtime-script-instance",
+    "unknown",
+];
+/** Provider-neutral application entity categories. */
+const applicationNodeKindSchema = z.enum(JAVASCRIPT_APPLICATION_NODE_KINDS);
+/** Directed relations admitted by JavaScript Application Graph. */
+export const JAVASCRIPT_APPLICATION_RELATIONS = [
+    "contains",
+    "loads",
+    "imports",
+    "maps_to",
+    "exposes",
+    "sends",
+    "invokes",
+    "handles",
+    "calls",
+    "persists_to",
+    "observed_as",
+    "changed_from",
+];
+/** Provider-neutral relation categories. */
+const applicationRelationSchema = z.enum(JAVASCRIPT_APPLICATION_RELATIONS);
+const applicationPropertiesSchema = z.record(z.string().min(1), jsonValueSchema);
+/** One node observation before its semantic identifier is derived. */
+const applicationNodeObservationBaseSchema = z.strictObject({
+    label: z.string().min(1).nullable(),
+    source_map_reference: javascriptSourceMapReferenceSchema.nullable(),
+    properties: applicationPropertiesSchema,
+    evidence: applicationGraphEvidenceSchema,
+});
+const applicationNodeObservationInputSchema = applicationNodeObservationBaseSchema.extend({
+    source_map_reference: javascriptSourceMapReferenceSchema
+        .nullable()
+        .default(null),
+});
+/** One immutable, evidence-bearing observation attached to an entity. */
+export const applicationNodeObservationSchema = applicationNodeObservationBaseSchema.extend({
+    observation_id: prefixedDigestSchema("jag_observation"),
+    identifier_strategy: z.strictObject({
+        strategy: z.literal("semantic-content-sha256"),
+        stability: z.literal("observation-exact"),
+    }),
+});
+/** One application entity before its stable identifier is derived. */
+export const applicationNodeInputSchema = z.strictObject({
+    kind: applicationNodeKindSchema,
+    identity: applicationNodeIdentitySchema,
+    observations: z.array(applicationNodeObservationInputSchema).min(1),
+});
+/** One stable application entity with one or more bounded observations. */
+export const applicationNodeSchema = z.strictObject({
+    node_id: prefixedDigestSchema("jag_node"),
+    kind: applicationNodeKindSchema,
+    identity: applicationNodeIdentitySchema,
+    observations: z.array(applicationNodeObservationSchema).min(1),
+});
+/** One directed relationship before its semantic identifier is derived. */
+export const applicationEdgeInputSchema = z.strictObject({
+    source_node_id: prefixedDigestSchema("jag_node"),
+    target_node_id: prefixedDigestSchema("jag_node"),
+    relation: applicationRelationSchema,
+    properties: applicationPropertiesSchema,
+    evidence: applicationGraphEvidenceSchema,
+});
+/** One directed, evidence-bearing application relationship. */
+export const applicationEdgeSchema = applicationEdgeInputSchema.extend({
+    edge_id: prefixedDigestSchema("jag_edge"),
+    identifier_strategy: z.strictObject({
+        strategy: z.literal("semantic-content-sha256"),
+        stability: z.literal("relationship-exact"),
+    }),
+});
+/** Graph content before its top-level semantic identifier is derived. */
+export const javascriptApplicationGraphInputSchema = z.strictObject({
+    schema: z.literal("JavaScriptApplicationGraph"),
+    root_node_ids: z.array(prefixedDigestSchema("jag_node")).min(1),
+    nodes: z.array(applicationNodeSchema).min(1),
+    edges: z.array(applicationEdgeSchema),
+    coverage: applicationCoverageSchema,
+    limitations: z.array(boundedTextSchema),
+});
+/** Strict stored shape for a JavaScript Application Graph. */
+export const javascriptApplicationGraphRecordSchema = javascriptApplicationGraphInputSchema.extend({
+    graph_id: prefixedDigestSchema("jag"),
+});

package/dist/domain/javascript/javascriptApplicationProjectionResources.js

@@ -0,0 +1,43 @@
+/** Forecast static-fact expansion into observations, nodes and relationships. */
+export const estimateJavaScriptStaticApplicationProjection = (facts, checkpointBytes, sourcePath) => {
+    // A finding can produce a node, a separate observation and several edges.
+    // Allow for identifiers, locations, authority, coverage and schema copies,
+    // independently of the producer's compact checkpoint representation.
+    const findings = facts.references.length +
+        facts.endpoints.length +
+        facts.storage.length +
+        facts.role_paths.length +
+        facts.source_map_urls.length +
+        facts.electron.browser_windows.length +
+        facts.electron.context_bridge_apis.length +
+        facts.electron.ipc.length +
+        facts.electron.sender_validations.length +
+        facts.electron.utility_processes.length +
+        facts.electron.native_addon_bindings.length;
+    let records = findings * 8;
+    let repeatedBytes = 0;
+    for (const registration of facts.bundler_registrations) {
+        records +=
+            3 +
+                registration.modules.length * 3 +
+                registration.entry_module_keys.length * 3 +
+                registration.async_chunk_keys.length * 3;
+        // Every module observation and containment edge repeats its chunk keys.
+        repeatedBytes +=
+            Buffer.byteLength(JSON.stringify(registration.chunk_keys)) *
+                registration.modules.length *
+                2;
+    }
+    for (const binding of facts.electron.native_addon_bindings)
+        records += binding.members.length * 3;
+    for (const path of facts.electron.call_paths ?? []) {
+        // One contextual node and edge per step, with repeated guards and identity.
+        records += path.steps.length * 4 + 8;
+        repeatedBytes +=
+            Buffer.byteLength(JSON.stringify(path.conditions)) *
+                path.steps.length *
+                2;
+    }
+    const metadataBytes = 2048 + Buffer.byteLength(sourcePath) * 4;
+    return (checkpointBytes * 4 + repeatedBytes + records * metadataBytes) * 8;
+};

package/dist/domain/javascript/javascriptApplicationVersionComparison.js

@@ -0,0 +1,104 @@
+import { digestCanonicalValue } from "../canonicalDigest.js";
+import { uniqueSorted } from "../canonicalOrdering.js";
+import { buildJavaScriptApplicationChangeGraph } from "./javascriptApplicationChangeGraph.js";
+import { ownedApplicationVersionComparisonResultSchema, } from "./javascriptApplicationVersionComparisonSchemas.js";
+import { classifyJavaScriptApplicationVersions } from "./javascriptApplicationVersionItems.js";
+import { matchJavaScriptApplicationVersions } from "./javascriptApplicationVersionKeys.js";
+/** Compare application entities with ordered unique-only identity tiers. */
+export const compareJavaScriptApplicationVersions = (input) => {
+    const matching = matchJavaScriptApplicationVersions(input.left.graph.nodes, input.right.graph.nodes);
+    const projection = classifyJavaScriptApplicationVersions(matching, {
+        leftGraph: input.left.graph,
+        rightGraph: input.right.graph,
+        leftEvidenceId: input.left.evidenceId,
+        rightEvidenceId: input.right.evidenceId,
+        leftNativeEvidence: input.leftNativeEvidence,
+        rightNativeEvidence: input.rightNativeEvidence,
+    });
+    const changeGraph = buildJavaScriptApplicationChangeGraph({
+        left: input.left.graph,
+        right: input.right.graph,
+        leftEvidenceId: input.left.evidenceId,
+        rightEvidenceId: input.right.evidenceId,
+        items: projection.items,
+    });
+    const evidenceLinks = uniqueSorted(projection.items.flatMap(({ evidence_links: links }) => links));
+    const omissions = {
+        left_graph_omitted_count: input.left.graph.coverage.omitted_count,
+        right_graph_omitted_count: input.right.graph.coverage.omitted_count,
+    };
+    const coverage = comparisonCoverage(input, omissions);
+    const semantic = {
+        left: {
+            evidence_id: input.left.evidenceId,
+            graph_id: input.left.graph.graph_id,
+            root_artifact_sha256: input.left.rootArtifactSha256,
+        },
+        right: {
+            evidence_id: input.right.evidenceId,
+            graph_id: input.right.graph.graph_id,
+            root_artifact_sha256: input.right.rootArtifactSha256,
+        },
+        summary: summary(projection.items),
+        matching: matchingSummary(projection.items),
+        items: projection.items,
+        graph: changeGraph.graph,
+        coverage,
+        evidence_links: evidenceLinks,
+        limitations: comparisonLimitations(input),
+    };
+    return ownedApplicationVersionComparisonResultSchema.parse({
+        ...semantic,
+        comparison_id: `javc_${digestCanonicalValue(semantic, "Application version comparison")}`,
+    });
+};
+const summary = (items) => ({
+    unchanged: countStatus(items, "unchanged"),
+    added: countStatus(items, "added"),
+    removed: countStatus(items, "removed"),
+    changed: countStatus(items, "changed"),
+    unknown: countStatus(items, "unknown"),
+});
+const countStatus = (items, status) => items.filter((item) => item.status === status).length;
+const matchingSummary = (items) => ({
+    exact_node_identity: countBasis(items, "exact-node-identity"),
+    exact_content_digest: countBasis(items, "exact-content-digest"),
+    exact_module_source_digest: countBasis(items, "exact-module-source-digest"),
+    source_map_identity: countBasis(items, "source-map-identity"),
+    structural_fingerprint: countBasis(items, "structural-fingerprint"),
+    semantic_key: countBasis(items, "semantic-key"),
+    ambiguous: items.filter(({ match }) => match.status === "ambiguous").length,
+    unmatched: items.filter(({ match }) => match.status === "unmatched").length,
+});
+const countBasis = (items, basis) => items.filter(({ match }) => match.basis === basis).length;
+const comparisonCoverage = (input, omissions) => {
+    const context = {
+        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 sourceGraphsTruncated = input.left.graph.coverage.truncated || input.right.graph.coverage.truncated;
+    return {
+        ...context,
+        ...omissions,
+        status: sourceGraphsComplete
+            ? "complete-within-inputs"
+            : sourceGraphsTruncated
+                ? "truncated"
+                : "partial",
+    };
+};
+const comparisonLimitations = (input) => uniqueSorted([
+    "Application comparison never uses bundler module ordinals as persistent identity and performs no fuzzy pairing.",
+    "Exact digest equality proves byte identity only; source-map, structural-fingerprint, and semantic-key matches retain inferred confidence.",
+    "Minified names and chunk locations are not assumed stable across versions.",
+    "The comparison reads retained graphs and Evidence only; it does not execute either application.",
+    "Native Evidence is linked only by exact subject digest; provider snapshot reuse remains target/provider/profile exact.",
+    ...(input.left.graph.coverage.status === "complete" &&
+        input.right.graph.coverage.status === "complete"
+        ? []
+        : [
+            "At least one source graph is incomplete; unmatched entities on the opposite side remain unknown rather than added or removed.",
+        ]),
+]);