feat(application): add cross-layer graph workflows

This commit is contained in:
N0zoM1z0
2026-07-16 11:29:54 +09:00
committed by N0zoM1z0
parent 87b23482e2
commit 778b995bbf
218 changed files with 6783 additions and 325 deletions
@@ -39,6 +39,13 @@ export const JAVASCRIPT_RUNTIME_RECONCILIATION_PROVIDER = {
version: "1",
} as const;
/** Provider identity for graph-native feature tracing and version comparison. */
export const JAVASCRIPT_APPLICATION_WORKFLOW_PROVIDER = {
id: "rea-javascript-application-workflows",
name: "REA JavaScript application workflows",
version: "1",
} as const;
/** Provider identity for deterministic cross-artifact comparisons. */
export const ARTIFACT_COMPARISON_PROVIDER = {
id: "rea-artifact-comparison",
@@ -0,0 +1,141 @@
import {
JAVASCRIPT_APPLICATION_PROVIDER,
JAVASCRIPT_RUNTIME_RECONCILIATION_PROVIDER,
} from "./InvestigationProviders.js";
import { parseEvidence, type Evidence } from "../domain/evidence.js";
import {
analyzeJavaScriptApplicationInputSchema,
javascriptApplicationAnalysisResultSchema,
type JavaScriptApplicationAnalysisResult,
} from "../domain/javascriptApplicationAnalysis.js";
import type { JavaScriptApplicationGraph } from "../domain/javascriptApplicationGraph.js";
import { javascriptRuntimeReconciliationResultSchema } from "../domain/javascriptRuntimeReconciliationSchemas.js";
/** Supported immutable source for an application-level graph workflow. */
export interface ApplicationGraphEvidenceSource {
readonly evidence: Evidence;
readonly graph: JavaScriptApplicationGraph;
readonly kind: "static-application" | "static-runtime-reconciliation";
readonly rootArtifactSha256: string;
}
/** Parse and authenticate one REA-produced JavaScript Application Graph Evidence. */
export const parseApplicationGraphEvidence = (
input: unknown,
): ApplicationGraphEvidenceSource => {
const evidence = parseEvidence(input);
if (
evidence.operation === "analyze_javascript_application" &&
evidence.predicate_type === "rea.javascript-application-analysis/v1" &&
providerMatches(evidence, JAVASCRIPT_APPLICATION_PROVIDER)
)
return staticApplicationSource(evidence);
if (
evidence.operation === "reconcile_javascript_runtime" &&
evidence.predicate_type === "rea.javascript-runtime-reconciliation/v1" &&
providerMatches(evidence, JAVASCRIPT_RUNTIME_RECONCILIATION_PROVIDER)
)
return staticRuntimeSource(evidence);
throw new TypeError(
"Application workflow requires authenticated analyze_javascript_application or reconcile_javascript_runtime Evidence",
);
};
const staticApplicationSource = (
evidence: Evidence,
): ApplicationGraphEvidenceSource => {
if (
evidence.authority !== "shipped-artifact" ||
evidence.confidence !== "derived"
)
throw new TypeError(
"JavaScript application Evidence authority or confidence is invalid",
);
const result = javascriptApplicationAnalysisResultSchema.parse(
evidence.normalized_result,
);
analyzeJavaScriptApplicationInputSchema.parse({
input_path: result.input_path,
...evidence.parameters,
});
assertApplicationSubject(evidence, result);
return {
evidence,
graph: result.graph,
kind: "static-application",
rootArtifactSha256: result.root_artifact_sha256,
};
};
const staticRuntimeSource = (
evidence: Evidence,
): ApplicationGraphEvidenceSource => {
if (
evidence.authority !== "analyst-inference" ||
evidence.confidence !== "inferred"
)
throw new TypeError(
"JavaScript runtime reconciliation Evidence authority or confidence is invalid",
);
const result = javascriptRuntimeReconciliationResultSchema.parse(
evidence.normalized_result,
);
if (
result.evidence_links.some(
(evidenceId) => !evidence.evidence_links.includes(evidenceId),
)
)
throw new TypeError(
"Runtime reconciliation result references Evidence outside its envelope",
);
const applicationLayer = result.static_layers.find(
({ role }) => role === "application",
);
if (applicationLayer === undefined)
throw new TypeError("Runtime reconciliation application layer is missing");
return {
evidence,
graph: result.graph,
kind: "static-runtime-reconciliation",
rootArtifactSha256: applicationLayer.root_artifact_sha256,
};
};
const assertApplicationSubject = (
evidence: Evidence,
result: JavaScriptApplicationAnalysisResult,
): void => {
if (
evidence.subject === null ||
evidence.subject.digest.sha256 !== result.root_artifact_sha256 ||
evidence.subject.format !== result.format
)
throw new TypeError(
"JavaScript application Evidence subject does not match its result",
);
};
const providerMatches = (
evidence: Evidence,
provider: {
readonly id: string;
readonly name: string;
readonly version: string;
},
): boolean =>
evidence.provider.id === provider.id &&
evidence.provider.name === provider.name &&
evidence.provider.version === provider.version;
/** Parse unique, artifact-bound Evidence that may extend a native handoff. */
export const parseNativeApplicationEvidence = (
inputs: readonly unknown[],
): Evidence[] => {
const parsed = inputs.map((input) => parseEvidence(input));
if (parsed.some(({ subject }) => subject === null))
throw new TypeError("Native handoff Evidence requires an artifact subject");
const ids = parsed.map(({ evidence_id: id }) => id);
if (new Set(ids).size !== ids.length)
throw new TypeError("Native handoff Evidence must be unique");
return parsed;
};
@@ -0,0 +1,45 @@
import {
createEvidence,
type Evidence,
type EvidenceObservation,
} from "../domain/evidence.js";
import type { ApplicationVersionComparisonResult } from "../domain/javascriptApplicationVersionComparisonSchemas.js";
import type { ApplicationFeatureTraceResult } from "../domain/javascriptFeatureTraceSchemas.js";
import { jsonValueSchema } from "../domain/jsonValue.js";
import { JAVASCRIPT_APPLICATION_WORKFLOW_PROVIDER } from "./InvestigationProviders.js";
/** Create derived Evidence for one bounded application-graph feature trace. */
export const createApplicationFeatureTraceEvidence = (
parameters: EvidenceObservation["parameters"],
result: ApplicationFeatureTraceResult,
): Evidence =>
createEvidence(undefined, JAVASCRIPT_APPLICATION_WORKFLOW_PROVIDER, {
predicateType: "rea.application-feature-trace/v1",
operation: "trace_application_feature",
parameters,
result: jsonValueSchema.parse(result),
rawResult: null,
confidence: "inferred",
authority: "analyst-inference",
environment: null,
limitations: result.limitations,
evidenceLinks: result.evidence_links,
});
/** Create derived Evidence for one tiered application version comparison. */
export const createApplicationVersionComparisonEvidence = (
parameters: EvidenceObservation["parameters"],
result: ApplicationVersionComparisonResult,
): Evidence =>
createEvidence(undefined, JAVASCRIPT_APPLICATION_WORKFLOW_PROVIDER, {
predicateType: "rea.application-version-comparison/v1",
operation: "compare_application_versions",
parameters,
result: jsonValueSchema.parse(result),
rawResult: null,
confidence: "inferred",
authority: "analyst-inference",
environment: null,
limitations: result.limitations,
evidenceLinks: result.evidence_links,
});
@@ -0,0 +1,121 @@
import { z } from "zod";
import {
AnalysisInputError,
AnalysisProtocolError,
type AnalysisError,
} from "../domain/errors.js";
import type { Evidence } from "../domain/evidence.js";
import { compareJavaScriptApplicationVersions } from "../domain/javascriptApplicationVersionComparison.js";
import { compareApplicationVersionsInputSchema } from "../domain/javascriptApplicationVersionComparisonSchemas.js";
import { traceApplicationFeature } from "../domain/javascriptFeatureTrace.js";
import { traceApplicationFeatureInputSchema } from "../domain/javascriptFeatureTraceSchemas.js";
import { err, ok, type Result } from "../domain/result.js";
import {
parseApplicationGraphEvidence,
parseNativeApplicationEvidence,
} from "./JavaScriptApplicationEvidenceGraph.js";
import {
createApplicationFeatureTraceEvidence,
createApplicationVersionComparisonEvidence,
} from "./JavaScriptApplicationWorkflowEvidence.js";
/** Authenticate Evidence and derive one bounded cross-layer feature trace. */
export const traceApplicationFeatureEvidence = (
rawInput: unknown,
): Result<Evidence, AnalysisError> => {
const operation = "trace_application_feature";
const parsed = traceApplicationFeatureInputSchema.safeParse(rawInput);
if (!parsed.success) return err(new AnalysisInputError(operation));
try {
const source = parseApplicationGraphEvidence(parsed.data.application);
const nativeEvidence = parseNativeApplicationEvidence(
parsed.data.native_observations,
);
const result = traceApplicationFeature({
sourceEvidenceId: source.evidence.evidence_id,
graph: source.graph,
nativeEvidence,
seed: parsed.data.seed,
direction: parsed.data.direction,
limits: parsed.data.limits,
});
return ok(
createApplicationFeatureTraceEvidence(
{
application_evidence_id: source.evidence.evidence_id,
native_evidence_ids: nativeEvidence.map(({ evidence_id: id }) => id),
seed: parsed.data.seed,
direction: parsed.data.direction,
limits: parsed.data.limits,
},
result,
),
);
} catch (cause: unknown) {
return workflowFailure(operation, cause);
}
};
/** Authenticate both graphs and derive a tiered cross-version change graph. */
export const compareApplicationVersionsEvidence = (
rawInput: unknown,
): Result<Evidence, AnalysisError> => {
const operation = "compare_application_versions";
const parsed = compareApplicationVersionsInputSchema.safeParse(rawInput);
if (!parsed.success) return err(new AnalysisInputError(operation));
try {
const left = parseApplicationGraphEvidence(parsed.data.left);
const right = parseApplicationGraphEvidence(parsed.data.right);
const leftNative = parseNativeApplicationEvidence(
parsed.data.left_native_observations,
);
const rightNative = parseNativeApplicationEvidence(
parsed.data.right_native_observations,
);
const result = compareJavaScriptApplicationVersions({
left: {
evidenceId: left.evidence.evidence_id,
rootArtifactSha256: left.rootArtifactSha256,
graph: left.graph,
},
right: {
evidenceId: right.evidence.evidence_id,
rootArtifactSha256: right.rootArtifactSha256,
graph: right.graph,
},
leftNativeEvidence: leftNative,
rightNativeEvidence: rightNative,
limits: parsed.data.limits,
});
return ok(
createApplicationVersionComparisonEvidence(
{
left_evidence_id: left.evidence.evidence_id,
right_evidence_id: right.evidence.evidence_id,
left_native_evidence_ids: leftNative.map(({ evidence_id: id }) => id),
right_native_evidence_ids: rightNative.map(
({ evidence_id: id }) => id,
),
limits: parsed.data.limits,
},
result,
),
);
} catch (cause: unknown) {
return workflowFailure(operation, cause);
}
};
const workflowFailure = (
operation: string,
cause: unknown,
): Result<never, AnalysisError> =>
err(
cause instanceof z.ZodError || cause instanceof TypeError
? new AnalysisInputError(operation)
: new AnalysisProtocolError(
"JavaScript application workflow produced an invalid result",
{ cause },
),
);
+2
View File
@@ -34,6 +34,7 @@ import { registerPolicyCommands } from "./cliPolicyCommands.js";
import { registerBrowserCommands } from "./cliBrowserCommands.js";
import { registerAdvancedBrowserCommands } from "./cliBrowserAdvancedCommands.js";
import { registerElectronCommands } from "./cliElectronCommands.js";
import { registerApplicationCommands } from "./cliApplicationCommands.js";
import { CLI_COMMANDS } from "./cliCommandNames.js";
import {
analysisProviderSelectorSchema,
@@ -89,6 +90,7 @@ export const createCli = (): ReturnType<typeof Cli.create> => {
registerBrowserCommands(cli, logger);
registerAdvancedBrowserCommands(cli, logger);
registerElectronCommands(cli, logger);
registerApplicationCommands(cli, logger);
return cli;
};
+68
View File
@@ -0,0 +1,68 @@
import { Cli, z } from "incur";
import {
compareApplicationVersionsEvidence,
traceApplicationFeatureEvidence,
} from "./application/JavaScriptApplicationWorkflowService.js";
import { CLI_COMMANDS } from "./cliCommandNames.js";
import { parseCliJsonInput } from "./cliJsonInput.js";
import { logCliCommand } from "./cliLogging.js";
import { AnalysisInputError, projectAnalysisError } from "./domain/errors.js";
import type { JsonValue } from "./domain/jsonValue.js";
import type { Logger } from "./logger.js";
/** Register CLI equivalents of provider-neutral application graph workflows. */
export const registerApplicationCommands = (
cli: ReturnType<typeof Cli.create>,
logger: Logger,
): void => {
registerJsonCommand(
cli,
logger,
CLI_COMMANDS.traceApplicationFeature,
"Trace a typed seed through authenticated application Evidence JSON",
traceApplicationFeatureEvidence,
);
registerJsonCommand(
cli,
logger,
CLI_COMMANDS.compareApplicationVersions,
"Compare two authenticated JavaScript Application Graph versions",
compareApplicationVersionsEvidence,
);
};
const registerJsonCommand = (
cli: ReturnType<typeof Cli.create>,
logger: Logger,
name: string,
description: string,
workflow: (
input: unknown,
) =>
| { readonly ok: true; readonly value: JsonValue }
| { readonly ok: false; readonly error: Error },
): void => {
cli.command(name, {
description,
args: z.object({
inputJson: z.string().describe("Inline workflow JSON or JSON file path"),
}),
run: ({ args }) =>
logCliCommand(logger, name, async () => {
const input = await parseCliJsonInput(args.inputJson, name);
if (!input.ok) return input.error;
const result = workflow(input.value);
return result.ok
? result.value
: {
error: "Application workflow failed",
...projectAnalysisError(
result.error instanceof AnalysisInputError
? result.error
: new AnalysisInputError(name),
),
};
}),
});
};
+2
View File
@@ -40,6 +40,8 @@ export const CLI_COMMANDS = Object.freeze({
inspectElectronPage: "inspect-electron-page",
analyzeJavaScriptApplication: "analyze-javascript-application",
reconcileJavaScriptRuntime: "reconcile-javascript-runtime",
traceApplicationFeature: "trace-application-feature",
compareApplicationVersions: "compare-application-versions",
});
/** Ordered primary CLI inventory; aliases are intentionally excluded. */
+5 -59
View File
@@ -1,5 +1,3 @@
import { readFile, stat } from "node:fs/promises";
import { Cli, z } from "incur";
import {
@@ -21,8 +19,7 @@ import { AnalysisInputError, projectAnalysisError } from "./domain/errors.js";
import type { JsonValue } from "./domain/jsonValue.js";
import type { Logger } from "./logger.js";
import { CLI_COMMANDS } from "./cliCommandNames.js";
const MAX_RECONCILIATION_INPUT_BYTES = 64 * 1_024 * 1_024;
import { parseCliJsonInput } from "./cliJsonInput.js";
const scopeOptions = {
allowedFileRoots: z
@@ -61,7 +58,10 @@ const registerJavaScriptRuntimeReconciliationCommand = (
logger,
CLI_COMMANDS.reconcileJavaScriptRuntime,
async () => {
const input = await parseJsonInput(args.inputJson);
const input = await parseCliJsonInput(
args.inputJson,
"reconcile_javascript_runtime",
);
if (!input.ok) return input.error;
const result = reconcileJavaScriptRuntimeEvidence(input.value);
return result.ok ? result.value : cliError(result.error);
@@ -266,60 +266,6 @@ const electronContext = async () => {
const inputError = (operation: string): JsonValue =>
cliError(new AnalysisInputError(operation));
const parseJson = (value: string): unknown => {
try {
return JSON.parse(value);
} catch {
return undefined;
}
};
const parseJsonInput = async (
value: string,
): Promise<
| { readonly ok: true; readonly value: unknown }
| { readonly ok: false; readonly error: JsonValue }
> => {
const inline = parseJson(value);
if (inline !== undefined) return { ok: true, value: inline };
if (["{", "["].includes(value.trimStart()[0] ?? ""))
return {
ok: false,
error: inputError("reconcile_javascript_runtime"),
};
try {
const metadata = await stat(value);
if (!metadata.isFile()) return jsonFileError(value, "not-file");
if (metadata.size > MAX_RECONCILIATION_INPUT_BYTES)
return jsonFileError(value, "too-large");
const bytes = await readFile(value);
if (bytes.byteLength > MAX_RECONCILIATION_INPUT_BYTES)
return jsonFileError(value, "too-large");
const parsed = parseJson(bytes.toString("utf8"));
return parsed === undefined
? jsonFileError(value, "invalid-json")
: { ok: true, value: parsed };
} catch {
return jsonFileError(value, "read-failed");
}
};
const jsonFileError = (
path: string,
reason: "not-file" | "too-large" | "invalid-json" | "read-failed",
) => ({
ok: false as const,
error: {
error: "Electron analysis failed",
...projectAnalysisError(
new AnalysisInputError("reconcile_javascript_runtime"),
),
input_path: path,
input_reason: reason,
maximum_input_bytes: MAX_RECONCILIATION_INPUT_BYTES,
},
});
const cliError = (
error: Parameters<typeof projectAnalysisError>[0],
): JsonValue => ({
+63
View File
@@ -0,0 +1,63 @@
import { readFile, stat } from "node:fs/promises";
import { AnalysisInputError, projectAnalysisError } from "./domain/errors.js";
import type { JsonValue } from "./domain/jsonValue.js";
const MAX_JSON_INPUT_BYTES = 64 * 1_024 * 1_024;
/** Parse bounded inline JSON or one bounded local JSON file for a CLI workflow. */
export const parseCliJsonInput = async (
value: string,
operation: string,
): Promise<
| { readonly ok: true; readonly value: unknown }
| { readonly ok: false; readonly error: JsonValue }
> => {
const inline = parseJson(value);
if (inline !== undefined) return { ok: true, value: inline };
if (["{", "["].includes(value.trimStart()[0] ?? ""))
return { ok: false, error: inputError(operation) };
try {
const metadata = await stat(value);
if (!metadata.isFile()) return jsonFileError(value, operation, "not-file");
if (metadata.size > MAX_JSON_INPUT_BYTES)
return jsonFileError(value, operation, "too-large");
const bytes = await readFile(value);
if (bytes.byteLength > MAX_JSON_INPUT_BYTES)
return jsonFileError(value, operation, "too-large");
const parsed = parseJson(bytes.toString("utf8"));
return parsed === undefined
? jsonFileError(value, operation, "invalid-json")
: { ok: true, value: parsed };
} catch {
return jsonFileError(value, operation, "read-failed");
}
};
const parseJson = (value: string): unknown => {
try {
return JSON.parse(value);
} catch {
return undefined;
}
};
const inputError = (operation: string): JsonValue => ({
error: "Application workflow failed",
...projectAnalysisError(new AnalysisInputError(operation)),
});
const jsonFileError = (
path: string,
operation: string,
reason: "not-file" | "too-large" | "invalid-json" | "read-failed",
) => ({
ok: false as const,
error: {
error: "Application workflow failed",
...projectAnalysisError(new AnalysisInputError(operation)),
input_path: path,
input_reason: reason,
maximum_input_bytes: MAX_JSON_INPUT_BYTES,
},
});
+65
View File
@@ -0,0 +1,65 @@
import {
applicationVersionComparisonResultSchema,
compareApplicationVersionsInputSchema,
} from "../domain/javascriptApplicationVersionComparisonSchemas.js";
import {
applicationFeatureTraceResultSchema,
traceApplicationFeatureInputSchema,
} from "../domain/javascriptFeatureTraceSchemas.js";
import { evidenceEnvelopeSchema } from "../domain/evidence.js";
import type { ToolContract } from "./toolContracts.js";
import {
JAVASCRIPT_APPLICATION_VERSION_COMPARISON_EXAMPLE,
JAVASCRIPT_FEATURE_TRACE_EXAMPLE,
} from "./javascriptApplicationWorkflowExamples.js";
const traceOutputSchema = evidenceEnvelopeSchema
.omit({ normalized_result: true })
.extend({ normalized_result: applicationFeatureTraceResultSchema });
const comparisonOutputSchema = evidenceEnvelopeSchema
.omit({ normalized_result: true })
.extend({ normalized_result: applicationVersionComparisonResultSchema });
/** Provider-neutral graph workflow contracts shared by MCP and CLI adapters. */
export const APPLICATION_TOOL_CONTRACTS = [
{
name: "trace_application_feature",
description:
"Trace a typed literal seed through an authenticated JavaScript Application Graph with explicit direction, depth, node, edge, and path bounds. Original static, native, passive-runtime, inferred, and unknown authorities remain distinct; native addon handoffs never open a provider or execute the application.",
kind: "application",
inputSchema: traceApplicationFeatureInputSchema,
outputSchema: traceOutputSchema,
annotations: {
readOnlyHint: true,
destructiveHint: false,
idempotentHint: true,
openWorldHint: false,
},
examples: [
{
title: "Trace one module seed through a retained application graph",
input: JAVASCRIPT_FEATURE_TRACE_EXAMPLE,
},
],
},
{
name: "compare_application_versions",
description:
"Compare two authenticated JavaScript Application Graph versions using unique-only exact digest, module source digest, source-map identity, structural fingerprint, and non-module semantic-key tiers. Reports added, removed, changed, ambiguous, and unknown entities plus a bounded changed_from graph without fuzzy or module-ordinal pairing.",
kind: "application",
inputSchema: compareApplicationVersionsInputSchema,
outputSchema: comparisonOutputSchema,
annotations: {
readOnlyHint: true,
destructiveHint: false,
idempotentHint: true,
openWorldHint: false,
},
examples: [
{
title: "Compare authenticated static and reconciled application graphs",
input: JAVASCRIPT_APPLICATION_VERSION_COMPARISON_EXAMPLE,
},
],
},
] as const satisfies readonly ToolContract[];
@@ -0,0 +1,64 @@
import { createEvidence } from "../domain/evidence.js";
import { reconcileJavaScriptRuntime } from "../domain/javascriptRuntimeReconciliation.js";
import {
JAVASCRIPT_APPLICATION_EVIDENCE_EXAMPLE,
JAVASCRIPT_RUNTIME_RECONCILIATION_EXAMPLE,
} from "./javascriptRuntimeReconciliationExample.js";
const reconciliation = reconcileJavaScriptRuntime(
JAVASCRIPT_RUNTIME_RECONCILIATION_EXAMPLE,
);
const reconciliationEvidence = createEvidence(
undefined,
{
id: "rea-javascript-runtime-reconciliation",
name: "REA JavaScript runtime reconciliation",
version: "1",
},
{
predicateType: "rea.javascript-runtime-reconciliation/v1",
operation: "reconcile_javascript_runtime",
parameters: {
static_layers:
JAVASCRIPT_RUNTIME_RECONCILIATION_EXAMPLE.static_layers.map(
({ role, analysis }) => ({
role,
evidence_id: analysis.evidence_id,
runtime_mappings: [],
}),
),
runtime_evidence_ids:
JAVASCRIPT_RUNTIME_RECONCILIATION_EXAMPLE.runtime_observations.map(
({ evidence_id: id }) => id,
),
limits: {
max_runtime_entities: 10_000,
max_reconciliation_items: 20_000,
max_static_load_states: 20_000,
},
},
result: reconciliation,
confidence: "inferred",
authority: "analyst-inference",
limitations: reconciliation.limitations,
evidenceLinks: reconciliation.evidence_links,
},
);
/** Valid public trace request without proprietary artifacts. */
export const JAVASCRIPT_FEATURE_TRACE_EXAMPLE = {
application: JAVASCRIPT_APPLICATION_EVIDENCE_EXAMPLE,
seed: {
kind: "module" as const,
value: "renderer.js",
match: "exact" as const,
case_sensitive: false,
},
direction: "both" as const,
};
/** Valid static/runtime graph pair demonstrating comparison authority. */
export const JAVASCRIPT_APPLICATION_VERSION_COMPARISON_EXAMPLE = {
left: JAVASCRIPT_APPLICATION_EVIDENCE_EXAMPLE,
right: reconciliationEvidence,
};
@@ -132,6 +132,9 @@ const staticEvidence = createEvidence(
},
);
/** Minimal valid static application Evidence for graph workflow examples. */
export const JAVASCRIPT_APPLICATION_EVIDENCE_EXAMPLE = staticEvidence;
const runtimeEvidence = createEvidence(
undefined,
{
+20 -2
View File
@@ -114,9 +114,13 @@ export const PROMPT_CONTRACTS = [
},
steps: [
{
tools: ["binary_session", "open_binary"],
tools: [
"binary_session",
"open_binary",
"analyze_javascript_application",
],
instruction:
"Inspect provider availability and effects first. Open target_path only when no matching target is active.",
"Inspect provider availability and effects first. For an approved JavaScript/Electron artifact, reconstruct its application graph without execution; otherwise open target_path only when no matching target is active.",
},
{
tools: ["list_documents", "set_current_document", "binary_overview"],
@@ -128,6 +132,11 @@ export const PROMPT_CONTRACTS = [
instruction:
"Search in literal mode first, follow every continuation needed for the stated scope, and resolve selected procedures to canonical addresses.",
},
{
tools: ["trace_application_feature"],
instruction:
"When authenticated application-graph Evidence exists, trace a typed literal route, API, channel, module, string, or native export through a bounded cross-layer subgraph before native localization.",
},
{
tools: [
"analyze_function",
@@ -179,6 +188,15 @@ export const PROMPT_CONTRACTS = [
instruction:
"Inventory each target independently before extraction. Follow nodes, occurrences, and edges to completion and retain every Evidence page for each manifest.",
},
{
tools: [
"analyze_javascript_application",
"reconcile_javascript_runtime",
"compare_application_versions",
],
instruction:
"For JavaScript/Electron versions, reconstruct each approved artifact independently, optionally reconcile separately retained passive runtime Evidence, then compare authenticated graphs with unique-only identity tiers. Keep ambiguous and incomplete matches unknown.",
},
{
tools: ["export_evidence_bundle", "compare_artifacts"],
instruction:
+1
View File
@@ -24,6 +24,7 @@ export type ToolKind =
| "artifact-provider"
| "browser-provider"
| "electron-provider"
| "application"
| "session";
/** Single source of truth for a public MCP tool. */
+2
View File
@@ -28,6 +28,7 @@ import { NATIVE_TOOL_CONTRACTS } from "./nativeToolContracts.js";
import { ARTIFACT_TOOL_CONTRACTS } from "./artifactToolContracts.js";
import { BROWSER_TOOL_CONTRACTS } from "./browserToolContracts.js";
import { ELECTRON_TOOL_CONTRACTS } from "./electronToolContracts.js";
import { APPLICATION_TOOL_CONTRACTS } from "./applicationToolContracts.js";
import {
closeBinaryInputSchema,
openBinaryInputSchema,
@@ -526,5 +527,6 @@ export const TOOL_CONTRACTS = [
...ARTIFACT_TOOL_CONTRACTS,
...BROWSER_TOOL_CONTRACTS,
...ELECTRON_TOOL_CONTRACTS,
...APPLICATION_TOOL_CONTRACTS,
...SESSION_TOOL_CONTRACTS,
] as const;
@@ -0,0 +1,324 @@
import {
compareCodePoints,
createJavaScriptApplicationEdge,
createJavaScriptApplicationGraph,
createJavaScriptApplicationNode,
type ApplicationEdge,
type ApplicationGraphEvidence,
type ApplicationNode,
type JavaScriptApplicationGraph,
} from "./javascriptApplicationGraph.js";
import type {
ApplicationVersionComparisonItem,
CompareApplicationVersionsInput,
} from "./javascriptApplicationVersionComparisonSchemas.js";
interface ChangeGraphInput {
readonly left: JavaScriptApplicationGraph;
readonly right: JavaScriptApplicationGraph;
readonly leftEvidenceId: string;
readonly rightEvidenceId: string;
readonly items: readonly ApplicationVersionComparisonItem[];
readonly omittedComparisonItems: number;
readonly limits: CompareApplicationVersionsInput["limits"];
}
/** Bounded cross-version graph and exact projection omission counts. */
export interface ApplicationChangeGraphProjection {
readonly graph: JavaScriptApplicationGraph;
readonly omittedNodes: number;
readonly omittedEdges: number;
readonly omittedObservations: number;
}
/** Merge compared nodes and add inferred right-to-left changed_from edges. */
export const buildJavaScriptApplicationChangeGraph = (
input: ChangeGraphInput,
): ApplicationChangeGraphProjection => {
const allNodes = nodeCandidates(input);
const preferredRoots = uniqueSorted([
...input.right.root_node_ids,
...input.left.root_node_ids,
]).filter((nodeId) => allNodes.has(nodeId));
const orderedNodeIds = uniqueSorted([
...preferredRoots,
...input.items.flatMap(({ left_node_id: left, right_node_id: right }) => [
...(right === null ? [] : [right]),
...(left === null ? [] : [left]),
]),
]);
const retainedIds = orderedNodeIds.slice(0, input.limits.max_graph_nodes);
const retained = new Set(retainedIds);
const merged = mergeNodes(
retainedIds.flatMap((nodeId) => allNodes.get(nodeId) ?? []),
);
const sourceEdges = uniqueEdges([
...input.left.edges,
...input.right.edges,
]).filter(
({ source_node_id: source, target_node_id: target }) =>
retained.has(source) && retained.has(target),
);
const comparisonEdges = input.items.flatMap((item) =>
changedFromEdge(item, input, retained),
);
const candidateEdges = uniqueEdges([...sourceEdges, ...comparisonEdges]);
const edges = candidateEdges.slice(0, input.limits.max_graph_edges);
const omittedNodes = Math.max(0, orderedNodeIds.length - retainedIds.length);
const omittedEdges = Math.max(0, candidateEdges.length - edges.length);
const graphOmissions =
omittedNodes + omittedEdges + merged.omittedObservations;
const rootNodeIds = preferredRoots
.filter((nodeId) => retained.has(nodeId))
.slice(0, 1_000);
const fallbackRoot = merged.nodes[0]?.node_id;
const graph = createJavaScriptApplicationGraph({
schema: "JavaScriptApplicationGraph",
schema_version: 1,
root_node_ids:
rootNodeIds.length > 0
? rootNodeIds
: fallbackRoot === undefined
? []
: [fallbackRoot],
nodes: merged.nodes,
edges,
coverage: changeGraphCoverage(input, graphOmissions),
limitations: uniqueSorted([
...input.left.limitations.map((value) => `Left: ${value}`),
...input.right.limitations.map((value) => `Right: ${value}`),
"changed_from edges are cross-version inferences and never promote structural or semantic matches to exact identity.",
"The change graph contains compared entities and their retained relationships; it is not an executable application.",
...(graphOmissions === 0
? []
: ["The change graph omitted content at explicit caller bounds."]),
]),
});
return {
graph,
omittedNodes,
omittedEdges,
omittedObservations: merged.omittedObservations,
};
};
const nodeCandidates = (
input: ChangeGraphInput,
): Map<string, ApplicationNode[]> => {
const required = new Set([
...input.left.root_node_ids,
...input.right.root_node_ids,
...input.items.flatMap(({ left_node_id: left, right_node_id: right }) => [
...(left === null ? [] : [left]),
...(right === null ? [] : [right]),
]),
]);
const output = new Map<string, ApplicationNode[]>();
for (const node of [...input.left.nodes, ...input.right.nodes])
if (required.has(node.node_id))
output.set(node.node_id, [...(output.get(node.node_id) ?? []), node]);
return output;
};
const changedFromEdge = (
item: ApplicationVersionComparisonItem,
input: ChangeGraphInput,
retained: ReadonlySet<string>,
): ApplicationEdge[] => {
const left = item.left_node_id;
const right = item.right_node_id;
if (
item.match.status !== "matched" ||
item.status === "unchanged" ||
left === null ||
right === null ||
left === right ||
!retained.has(left) ||
!retained.has(right)
)
return [];
const evidence = comparisonEvidence(item, input);
return [
createJavaScriptApplicationEdge({
source_node_id: right,
target_node_id: left,
relation: "changed_from",
properties: {
comparison_item_id: item.item_id,
status: item.status,
match_basis: item.match.basis,
match_confidence: item.match.confidence,
dimensions: item.dimensions,
},
evidence,
}),
];
};
const comparisonEvidence = (
item: ApplicationVersionComparisonItem,
input: ChangeGraphInput,
): ApplicationGraphEvidence => {
const right = input.right.nodes.find(
({ node_id: id }) => id === item.right_node_id,
);
const left = input.left.nodes.find(
({ node_id: id }) => id === item.left_node_id,
);
const source =
right?.observations[0]?.evidence ?? left?.observations[0]?.evidence;
const complete =
input.left.coverage.status === "complete" &&
input.right.coverage.status === "complete" &&
input.omittedComparisonItems === 0;
return {
authority: "cross-version-comparison",
state: "inferred",
confidence: item.match.confidence === "medium" ? "medium" : "high",
artifact: source?.artifact ?? {
available: false,
reason: "unresolved",
detail: "Compared node has no artifact-backed observation.",
},
location: source?.location ?? {
available: false,
reason: "unresolved",
detail: "Compared node has no actionable source location.",
},
extractor: {
name: "rea-application-version-comparison",
version: "1",
operation: "compare_application_versions",
executable_sha256: null,
},
coverage: complete
? { status: "complete", truncated: false, omitted_count: 0, limits: [] }
: {
status: "partial",
truncated: input.omittedComparisonItems > 0,
omitted_count:
input.omittedComparisonItems > 0
? input.omittedComparisonItems
: (source?.coverage.omitted_count ?? null),
limits:
input.omittedComparisonItems > 0
? [
{
name: "max-comparison-items",
value: input.limits.max_comparison_items,
unit: "items",
},
]
: [],
},
limitations: [
"Cross-version pairing is inferred from the stated match basis; changed_from does not prove runtime reachability.",
...item.limitations,
],
evidence_ids: [input.leftEvidenceId, input.rightEvidenceId],
};
};
const changeGraphCoverage = (
input: ChangeGraphInput,
graphOmissions: number,
): JavaScriptApplicationGraph["coverage"] => {
const outputOmissions = graphOmissions + input.omittedComparisonItems;
if (outputOmissions > 0)
return {
status: "partial",
truncated: true,
omitted_count: outputOmissions,
limits: [
{
name: "max-comparison-items",
value: input.limits.max_comparison_items,
unit: "items",
},
{
name: "max-graph-nodes",
value: input.limits.max_graph_nodes,
unit: "items",
},
{
name: "max-graph-edges",
value: input.limits.max_graph_edges,
unit: "items",
},
],
};
if (
input.left.coverage.status === "complete" &&
input.right.coverage.status === "complete"
)
return {
status: "complete",
truncated: false,
omitted_count: 0,
limits: [],
};
const counts = [
input.left.coverage.omitted_count,
input.right.coverage.omitted_count,
];
return {
status: "partial",
truncated: false,
omitted_count: counts.every((value) => value !== null)
? counts.reduce<number>((total, value) => total + (value ?? 0), 0)
: null,
limits: [],
};
};
const mergeNodes = (
nodes: readonly ApplicationNode[],
): {
readonly nodes: ApplicationNode[];
readonly omittedObservations: number;
} => {
const groups = new Map<string, ApplicationNode[]>();
for (const node of nodes)
groups.set(node.node_id, [...(groups.get(node.node_id) ?? []), node]);
let omittedObservations = 0;
const merged = [...groups.values()].map((group) => {
const first = group[0];
if (first === undefined)
throw new TypeError("Empty change-graph node group");
const observations = [
...new Map(
group
.flatMap(({ observations: values }) => values)
.map((observation) => [observation.observation_id, observation]),
).values(),
].sort((left, right) =>
compareCodePoints(left.observation_id, right.observation_id),
);
omittedObservations += Math.max(0, observations.length - 64);
return createJavaScriptApplicationNode({
kind: first.kind,
identity: first.identity,
observations: observations
.slice(0, 64)
.map(
({ observation_id: _id, identifier_strategy: _strategy, ...value }) =>
value,
),
});
});
return {
nodes: merged.sort((left, right) =>
compareCodePoints(left.node_id, right.node_id),
),
omittedObservations,
};
};
const uniqueEdges = (edges: readonly ApplicationEdge[]): ApplicationEdge[] =>
[...new Map(edges.map((edge) => [edge.edge_id, edge])).values()].sort(
(left, right) => compareCodePoints(left.edge_id, right.edge_id),
);
const uniqueSorted = <Value extends string>(
values: readonly Value[],
): Value[] => [...new Set(values)].sort(compareCodePoints);
@@ -24,6 +24,7 @@ const applicationEvidenceAuthoritySchema = z.enum([
"static-relationship-inference",
"passive-cdp-runtime",
"cross-layer-reconciliation",
"cross-version-comparison",
"controlled-replay",
"native-analysis-provider",
"historical-reference",
@@ -269,6 +270,15 @@ const checkAuthorityState = (
path: ["state"],
message: "Cross-layer reconciliation authority must remain inferred",
});
if (
evidence.authority === "cross-version-comparison" &&
evidence.state !== "inferred"
)
context.addIssue({
code: "custom",
path: ["state"],
message: "Cross-version comparison authority must remain inferred",
});
if (
evidence.authority === "unknown" &&
!["unknown", "unavailable"].includes(evidence.state)
@@ -0,0 +1,187 @@
import { createHash } from "node:crypto";
import canonicalize from "canonicalize";
import type { Evidence } from "./evidence.js";
import { buildJavaScriptApplicationChangeGraph } from "./javascriptApplicationChangeGraph.js";
import {
applicationVersionComparisonResultSchema,
type ApplicationVersionComparisonResult,
type CompareApplicationVersionsInput,
} from "./javascriptApplicationVersionComparisonSchemas.js";
import type { JavaScriptApplicationGraph } from "./javascriptApplicationGraph.js";
import { compareCodePoints } from "./javascriptApplicationGraph.js";
import { classifyJavaScriptApplicationVersions } from "./javascriptApplicationVersionItems.js";
import { matchJavaScriptApplicationVersions } from "./javascriptApplicationVersionKeys.js";
/** Pure inputs after application-layer Evidence authentication. */
export interface ApplicationVersionComparisonProjectionInput {
readonly left: {
readonly evidenceId: string;
readonly rootArtifactSha256: string;
readonly graph: JavaScriptApplicationGraph;
};
readonly right: {
readonly evidenceId: string;
readonly rootArtifactSha256: string;
readonly graph: JavaScriptApplicationGraph;
};
readonly leftNativeEvidence: readonly Evidence[];
readonly rightNativeEvidence: readonly Evidence[];
readonly limits: CompareApplicationVersionsInput["limits"];
}
/** Compare application entities with ordered unique-only identity tiers. */
export const compareJavaScriptApplicationVersions = (
input: ApplicationVersionComparisonProjectionInput,
): ApplicationVersionComparisonResult => {
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,
maxCandidates: input.limits.max_candidate_nodes,
});
const items = projection.items.slice(0, input.limits.max_comparison_items);
const omittedComparisonItems = projection.items.length - items.length;
const changeGraph = buildJavaScriptApplicationChangeGraph({
left: input.left.graph,
right: input.right.graph,
leftEvidenceId: input.left.evidenceId,
rightEvidenceId: input.right.evidenceId,
items,
omittedComparisonItems,
limits: input.limits,
});
const evidenceLinks = uniqueSorted(
projection.items.flatMap(({ evidence_links: links }) => links),
);
const omissions = {
omitted_comparison_items: omittedComparisonItems,
omitted_candidate_references: projection.omittedCandidateReferences,
omitted_graph_nodes: changeGraph.omittedNodes,
omitted_graph_edges: changeGraph.omittedEdges,
omitted_graph_observations: changeGraph.omittedObservations,
};
const semantic = {
schema_version: 1 as const,
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,
graph: changeGraph.graph,
coverage: {
status: comparisonCoverageStatus(input, omissions),
left_graph_status: input.left.graph.coverage.status,
right_graph_status: input.right.graph.coverage.status,
...omissions,
},
evidence_links: evidenceLinks,
limitations: comparisonLimitations(input, omissions),
};
return applicationVersionComparisonResultSchema.parse({
...semantic,
comparison_id: `javc_${digestCanonical(semantic)}`,
});
};
const summary = (
items: readonly ApplicationVersionComparisonResult["items"][number][],
): ApplicationVersionComparisonResult["summary"] => ({
unchanged: countStatus(items, "unchanged"),
added: countStatus(items, "added"),
removed: countStatus(items, "removed"),
changed: countStatus(items, "changed"),
unknown: countStatus(items, "unknown"),
});
const countStatus = (
items: readonly ApplicationVersionComparisonResult["items"][number][],
status: ApplicationVersionComparisonResult["items"][number]["status"],
): number => items.filter((item) => item.status === status).length;
const matchingSummary = (
items: readonly ApplicationVersionComparisonResult["items"][number][],
): ApplicationVersionComparisonResult["matching"] => ({
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: readonly ApplicationVersionComparisonResult["items"][number][],
basis: ApplicationVersionComparisonResult["items"][number]["match"]["basis"],
): number => items.filter(({ match }) => match.basis === basis).length;
type ComparisonOmissions = ApplicationVersionComparisonResult["coverage"];
const comparisonCoverageStatus = (
input: ApplicationVersionComparisonProjectionInput,
omissions: Omit<
ComparisonOmissions,
"status" | "left_graph_status" | "right_graph_status"
>,
): ApplicationVersionComparisonResult["coverage"]["status"] =>
Object.values(omissions).some((value) => value > 0)
? "truncated"
: input.left.graph.coverage.status === "complete" &&
input.right.graph.coverage.status === "complete"
? "complete-within-inputs"
: "partial";
const comparisonLimitations = (
input: ApplicationVersionComparisonProjectionInput,
omissions: Omit<
ComparisonOmissions,
"status" | "left_graph_status" | "right_graph_status"
>,
): string[] =>
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.",
]),
...(Object.values(omissions).some((value) => value > 0)
? ["Comparison output was truncated at explicit caller limits."]
: []),
]);
const digestCanonical = (value: unknown): string => {
const encoded = canonicalize(value);
if (encoded === undefined)
throw new TypeError(
"Application version comparison could not canonicalize data",
);
return createHash("sha256").update(encoded).digest("hex");
};
const uniqueSorted = <Value extends string>(
values: readonly Value[],
): Value[] => [...new Set(values)].sort(compareCodePoints);
@@ -0,0 +1,161 @@
import { z } from "zod";
import { evidenceSchema } from "./evidence.js";
import { javascriptApplicationGraphSchema } from "./javascriptApplicationGraph.js";
import { JAVASCRIPT_APPLICATION_NODE_KINDS } from "./javascriptApplicationGraphSchemas.js";
const evidenceIdSchema = z.string().regex(/^ev_[a-f0-9]{64}$/u);
const nodeIdSchema = z.string().regex(/^jag_node_[a-f0-9]{64}$/u);
const boundedTextSchema = z.string().min(1).max(4_096);
const comparisonLimitsSchema = z.strictObject({
max_comparison_items: z.number().int().min(1).max(50_000).default(20_000),
max_candidate_nodes: z.number().int().min(1).max(1_000).default(100),
max_graph_nodes: z.number().int().min(1).max(100_000).default(20_000),
max_graph_edges: z.number().int().min(1).max(200_000).default(40_000),
});
/** Two authenticated application versions and deterministic output bounds. */
export const compareApplicationVersionsInputSchema = z
.strictObject({
left: evidenceSchema,
right: evidenceSchema,
left_native_observations: z.array(evidenceSchema).max(64).default([]),
right_native_observations: z.array(evidenceSchema).max(64).default([]),
limits: comparisonLimitsSchema.default({
max_comparison_items: 20_000,
max_candidate_nodes: 100,
max_graph_nodes: 20_000,
max_graph_edges: 40_000,
}),
unknown_registry_approved: z.literal(true).optional(),
})
.superRefine((input, context) => {
if (input.left.evidence_id === input.right.evidence_id)
context.addIssue({
code: "custom",
path: ["right"],
message: "Application version Evidence must be distinct",
});
for (const side of [
"left_native_observations",
"right_native_observations",
] as const) {
const ids = input[side].map(({ evidence_id: id }) => id);
if (new Set(ids).size !== ids.length)
context.addIssue({
code: "custom",
path: [side],
message: "Native observations must be unique on each side",
});
}
});
const applicationVersionMatchBasisSchema = z.enum([
"exact-node-identity",
"exact-content-digest",
"exact-module-source-digest",
"source-map-identity",
"structural-fingerprint",
"semantic-key",
"none",
]);
const comparisonItemSchema = z.strictObject({
item_id: z.string().regex(/^javc_item_[a-f0-9]{64}$/u),
status: z.enum(["unchanged", "added", "removed", "changed", "unknown"]),
node_kind: z.enum(JAVASCRIPT_APPLICATION_NODE_KINDS),
left_node_id: nodeIdSchema.nullable(),
right_node_id: nodeIdSchema.nullable(),
match: z.strictObject({
status: z.enum(["matched", "unmatched", "ambiguous"]),
basis: applicationVersionMatchBasisSchema,
confidence: z.enum(["exact", "high", "medium", "unknown"]),
candidate_left_node_ids: z.array(nodeIdSchema).max(1_000),
candidate_right_node_ids: z.array(nodeIdSchema).max(1_000),
}),
dimensions: z
.array(
z.enum([
"content",
"location",
"properties",
"relationships",
"availability",
"coverage",
]),
)
.max(6),
evidence_links: z.array(evidenceIdSchema).min(2).max(130),
limitations: z.array(boundedTextSchema).max(100),
});
/** Tiered module/entity matching plus a bounded cross-version change graph. */
export const applicationVersionComparisonResultSchema = z.strictObject({
schema_version: z.literal(1),
comparison_id: z.string().regex(/^javc_[a-f0-9]{64}$/u),
left: z.strictObject({
evidence_id: evidenceIdSchema,
graph_id: z.string().regex(/^jag_[a-f0-9]{64}$/u),
root_artifact_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
}),
right: z.strictObject({
evidence_id: evidenceIdSchema,
graph_id: z.string().regex(/^jag_[a-f0-9]{64}$/u),
root_artifact_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
}),
summary: z.strictObject({
unchanged: z.number().int().min(0),
added: z.number().int().min(0),
removed: z.number().int().min(0),
changed: z.number().int().min(0),
unknown: z.number().int().min(0),
}),
matching: z.strictObject({
exact_node_identity: z.number().int().min(0),
exact_content_digest: z.number().int().min(0),
exact_module_source_digest: z.number().int().min(0),
source_map_identity: z.number().int().min(0),
structural_fingerprint: z.number().int().min(0),
semantic_key: z.number().int().min(0),
ambiguous: z.number().int().min(0),
unmatched: z.number().int().min(0),
}),
items: z.array(comparisonItemSchema).max(50_000),
graph: javascriptApplicationGraphSchema,
coverage: z.strictObject({
status: z.enum(["complete-within-inputs", "partial", "truncated"]),
left_graph_status: z.enum([
"complete",
"partial",
"unknown",
"unavailable",
]),
right_graph_status: z.enum([
"complete",
"partial",
"unknown",
"unavailable",
]),
omitted_comparison_items: z.number().int().min(0),
omitted_candidate_references: z.number().int().min(0),
omitted_graph_nodes: z.number().int().min(0),
omitted_graph_edges: z.number().int().min(0),
omitted_graph_observations: z.number().int().min(0),
}),
evidence_links: z.array(evidenceIdSchema).min(2).max(130),
limitations: z.array(boundedTextSchema).max(1_000),
});
export type CompareApplicationVersionsInput = z.infer<
typeof compareApplicationVersionsInputSchema
>;
export type ApplicationVersionComparisonItem = z.infer<
typeof comparisonItemSchema
>;
export type ApplicationVersionComparisonResult = z.infer<
typeof applicationVersionComparisonResultSchema
>;
export type ApplicationVersionMatchBasis = z.infer<
typeof applicationVersionMatchBasisSchema
>;
@@ -0,0 +1,371 @@
import { createHash } from "node:crypto";
import canonicalize from "canonicalize";
import type { Evidence } from "./evidence.js";
import {
compareCodePoints,
type ApplicationEdge,
type ApplicationNode,
type JavaScriptApplicationGraph,
} from "./javascriptApplicationGraph.js";
import type {
ApplicationVersionComparisonItem,
CompareApplicationVersionsInput,
} from "./javascriptApplicationVersionComparisonSchemas.js";
import type {
ApplicationVersionMatchingProjection,
ApplicationVersionNodePair,
} from "./javascriptApplicationVersionKeys.js";
/** All classified entities before the caller's item bound is applied. */
export interface ApplicationVersionItemProjection {
readonly items: ApplicationVersionComparisonItem[];
readonly omittedCandidateReferences: number;
}
interface ItemContext {
readonly leftGraph: JavaScriptApplicationGraph;
readonly rightGraph: JavaScriptApplicationGraph;
readonly leftEvidenceId: string;
readonly rightEvidenceId: string;
readonly leftNativeEvidence: readonly Evidence[];
readonly rightNativeEvidence: readonly Evidence[];
readonly pairByLeft: ReadonlyMap<string, string>;
readonly pairByRight: ReadonlyMap<string, string>;
readonly maxCandidates: number;
}
/** Classify matched, unmatched, and ambiguous nodes without inventing absence. */
export const classifyJavaScriptApplicationVersions = (
matching: ApplicationVersionMatchingProjection,
context: Omit<ItemContext, "pairByLeft" | "pairByRight" | "maxCandidates"> & {
readonly maxCandidates: CompareApplicationVersionsInput["limits"]["max_candidate_nodes"];
},
): ApplicationVersionItemProjection => {
const pairByLeft = new Map(
matching.pairs.map(({ left, right }) => [
left.node_id,
`pair:${left.node_id}:${right.node_id}`,
]),
);
const pairByRight = new Map(
matching.pairs.map(({ left, right }) => [
right.node_id,
`pair:${left.node_id}:${right.node_id}`,
]),
);
const fullContext: ItemContext = { ...context, pairByLeft, pairByRight };
let omittedCandidateReferences = 0;
const leftItems = matching.unmatchedLeft.map((node) => {
const candidates = matching.candidatesForLeft.get(node.node_id) ?? [];
omittedCandidateReferences += Math.max(
0,
candidates.length - context.maxCandidates,
);
return unmatchedItem(
node,
"left",
candidates.slice(0, context.maxCandidates),
fullContext,
);
});
const rightItems = matching.unmatchedRight.map((node) => {
const candidates = matching.candidatesForRight.get(node.node_id) ?? [];
omittedCandidateReferences += Math.max(
0,
candidates.length - context.maxCandidates,
);
return unmatchedItem(
node,
"right",
candidates.slice(0, context.maxCandidates),
fullContext,
);
});
return {
items: [
...matching.pairs.map((pair) => matchedItem(pair, fullContext)),
...leftItems,
...rightItems,
].sort((left, right) => compareCodePoints(left.item_id, right.item_id)),
omittedCandidateReferences,
};
};
const matchedItem = (
pair: ApplicationVersionNodePair,
context: ItemContext,
): ApplicationVersionComparisonItem => {
const dimensions = changedDimensions(pair, context);
const complete = graphsComplete(context);
const observedChange = dimensions.some((dimension) =>
["content", "location", "properties"].includes(dimension),
);
const status: ApplicationVersionComparisonItem["status"] =
observedChange || (complete && dimensions.length > 0)
? "changed"
: complete
? "unchanged"
: "unknown";
const finalDimensions =
status === "unknown" && !dimensions.includes("coverage")
? [...dimensions, "coverage" as const]
: dimensions;
const semantic = {
status,
node_kind: pair.left.kind,
left_node_id: pair.left.node_id,
right_node_id: pair.right.node_id,
match: {
status: "matched" as const,
basis: pair.basis,
confidence: pair.confidence,
candidate_left_node_ids: [],
candidate_right_node_ids: [],
},
dimensions: finalDimensions,
evidence_links: itemEvidenceLinks(pair.left, pair.right, context),
limitations: pairLimitations(pair, status),
};
return itemWithId(semantic);
};
const unmatchedItem = (
node: ApplicationNode,
side: "left" | "right",
candidates: readonly string[],
context: ItemContext,
): ApplicationVersionComparisonItem => {
const ambiguous = candidates.length > 0;
const oppositeComplete =
(side === "left" ? context.rightGraph : context.leftGraph).coverage
.status === "complete";
const status: ApplicationVersionComparisonItem["status"] = ambiguous
? "unknown"
: oppositeComplete
? side === "left"
? "removed"
: "added"
: "unknown";
const semantic = {
status,
node_kind: node.kind,
left_node_id: side === "left" ? node.node_id : null,
right_node_id: side === "right" ? node.node_id : null,
match: {
status: ambiguous ? ("ambiguous" as const) : ("unmatched" as const),
basis: "none" as const,
confidence: "unknown" as const,
candidate_left_node_ids: side === "right" ? [...candidates] : [],
candidate_right_node_ids: side === "left" ? [...candidates] : [],
},
dimensions: [
"availability" as const,
...(status === "unknown" && !ambiguous ? (["coverage"] as const) : []),
],
evidence_links: itemEvidenceLinks(
side === "left" ? node : undefined,
side === "right" ? node : undefined,
context,
),
limitations: [
...(ambiguous
? [
"Multiple nodes share the same permitted match key; no cross-version pair was selected.",
]
: []),
...(status === "unknown" && !ambiguous
? [
"The opposite graph is incomplete, so an unmatched node cannot be classified as added or removed.",
]
: []),
],
};
return itemWithId(semantic);
};
const changedDimensions = (
pair: ApplicationVersionNodePair,
context: ItemContext,
): ApplicationVersionComparisonItem["dimensions"] => {
const dimensions: ApplicationVersionComparisonItem["dimensions"] = [];
const leftContent = contentIdentity(pair.left);
const rightContent = contentIdentity(pair.right);
if (
leftContent !== null &&
rightContent !== null &&
leftContent !== rightContent
)
dimensions.push("content");
if (canonical(locations(pair.left)) !== canonical(locations(pair.right)))
dimensions.push("location");
if (canonical(properties(pair.left)) !== canonical(properties(pair.right)))
dimensions.push("properties");
if (
relationshipSignature(pair.left, "left", context) !==
relationshipSignature(pair.right, "right", context)
)
dimensions.push("relationships");
return dimensions;
};
const contentIdentity = (node: ApplicationNode): string | null => {
if (node.identity.strategy === "content-digest")
return `content:${node.identity.sha256}`;
if (node.kind === "javascript-module")
return stringProperty(node, "source_sha256");
if (
node.kind === "source-module" &&
node.identity.strategy === "source-map-original"
)
return node.identity.source_sha256;
return null;
};
const locations = (node: ApplicationNode) =>
node.observations
.map(({ evidence }) =>
evidence.location.available ? evidence.location.value : evidence.location,
)
.sort((left, right) =>
compareCodePoints(canonical(left), canonical(right)),
);
const properties = (node: ApplicationNode) =>
node.observations
.map(({ label, properties: values }) => ({ label, properties: values }))
.sort((left, right) =>
compareCodePoints(canonical(left), canonical(right)),
);
const relationshipSignature = (
node: ApplicationNode,
side: "left" | "right",
context: ItemContext,
): string => {
const graph = side === "left" ? context.leftGraph : context.rightGraph;
const paired = side === "left" ? context.pairByLeft : context.pairByRight;
const nodeById = new Map(graph.nodes.map((value) => [value.node_id, value]));
const signatures = graph.edges.flatMap((edge) => {
if (edge.source_node_id === node.node_id)
return [
edgeSignature(
"out",
edge.relation,
edge.target_node_id,
paired,
nodeById,
),
];
if (edge.target_node_id === node.node_id)
return [
edgeSignature(
"in",
edge.relation,
edge.source_node_id,
paired,
nodeById,
),
];
return [];
});
return canonical(signatures.sort(compareCodePoints));
};
const edgeSignature = (
direction: "in" | "out",
relation: ApplicationEdge["relation"],
neighborId: string,
paired: ReadonlyMap<string, string>,
nodeById: ReadonlyMap<string, ApplicationNode>,
): string => {
const mapped = paired.get(neighborId);
const neighbor = nodeById.get(neighborId);
return `${direction}\0${relation}\0${mapped ?? `unmatched:${neighbor?.kind ?? "unknown"}`}`;
};
const itemEvidenceLinks = (
left: ApplicationNode | undefined,
right: ApplicationNode | undefined,
context: ItemContext,
): string[] =>
[
...new Set([
context.leftEvidenceId,
context.rightEvidenceId,
...nativeLinks(left, context.leftNativeEvidence),
...nativeLinks(right, context.rightNativeEvidence),
]),
].sort(compareCodePoints);
const nativeLinks = (
node: ApplicationNode | undefined,
evidence: readonly Evidence[],
): string[] => {
const digest =
node === undefined
? null
: contentIdentity(node)?.replace(/^content:/u, "");
return digest === null
? []
: evidence
.filter(({ subject }) => subject?.digest.sha256 === digest)
.map(({ evidence_id: id }) => id);
};
const pairLimitations = (
pair: ApplicationVersionNodePair,
status: ApplicationVersionComparisonItem["status"],
): string[] => [
...(pair.basis === "structural-fingerprint"
? [
"Structural fingerprint equality is rename-resistant inference; it is not byte identity or proof of semantic equivalence.",
]
: []),
...(pair.basis === "source-map-identity"
? [
"Source-map original names identify a candidate source lineage; changed or unavailable source content remains explicit.",
]
: []),
...(pair.basis === "semantic-key"
? [
"Semantic-key pairing is a deterministic inference and is never promoted to exact identity.",
]
: []),
...(status === "unknown"
? ["Incomplete graph coverage prevents a complete node-level conclusion."]
: []),
];
const itemWithId = (
semantic: Omit<ApplicationVersionComparisonItem, "item_id">,
): ApplicationVersionComparisonItem => ({
...semantic,
item_id: `javc_item_${digestCanonical(semantic)}`,
});
const stringProperty = (node: ApplicationNode, key: string): string | null => {
const values = [
...new Set(
node.observations
.map(({ properties: values }) => values[key])
.filter((value): value is string => typeof value === "string"),
),
];
return values.length === 1 ? (values[0] ?? null) : null;
};
const graphsComplete = (context: ItemContext): boolean =>
context.leftGraph.coverage.status === "complete" &&
context.rightGraph.coverage.status === "complete";
const canonical = (value: unknown): string => {
const encoded = canonicalize(value);
if (encoded === undefined)
throw new TypeError("Application version item could not canonicalize data");
return encoded;
};
const digestCanonical = (value: unknown): string =>
createHash("sha256").update(canonical(value)).digest("hex");
@@ -0,0 +1,273 @@
import type { ApplicationNode } from "./javascriptApplicationGraph.js";
import { compareCodePoints } from "./javascriptApplicationGraph.js";
import type { ApplicationVersionMatchBasis } from "./javascriptApplicationVersionComparisonSchemas.js";
import type { JsonValue } from "./jsonValue.js";
/** One deterministic one-to-one match between two graph versions. */
export interface ApplicationVersionNodePair {
readonly left: ApplicationNode;
readonly right: ApplicationNode;
readonly basis: Exclude<ApplicationVersionMatchBasis, "none">;
readonly confidence: "exact" | "high" | "medium";
}
/** Matched nodes plus ambiguity candidates that were never forced into pairs. */
export interface ApplicationVersionMatchingProjection {
readonly pairs: ApplicationVersionNodePair[];
readonly unmatchedLeft: ApplicationNode[];
readonly unmatchedRight: ApplicationNode[];
readonly candidatesForLeft: ReadonlyMap<string, readonly string[]>;
readonly candidatesForRight: ReadonlyMap<string, readonly string[]>;
}
interface MatchTier {
readonly basis: ApplicationVersionNodePair["basis"];
readonly confidence: ApplicationVersionNodePair["confidence"];
readonly key: (node: ApplicationNode) => string | null;
}
const matchTiers = (): readonly MatchTier[] => [
{ basis: "exact-content-digest", confidence: "exact", key: contentDigestKey },
{
basis: "exact-module-source-digest",
confidence: "exact",
key: moduleSourceDigestKey,
},
{ basis: "exact-node-identity", confidence: "exact", key: nodeIdentityKey },
{ basis: "source-map-identity", confidence: "high", key: sourceMapKey },
{
basis: "structural-fingerprint",
confidence: "medium",
key: structuralFingerprintKey,
},
{ basis: "semantic-key", confidence: "medium", key: semanticKey },
];
/** Apply ordered, unique-only matching tiers without fuzzy pairing. */
export const matchJavaScriptApplicationVersions = (
leftNodes: readonly ApplicationNode[],
rightNodes: readonly ApplicationNode[],
): ApplicationVersionMatchingProjection => {
const left = new Map(leftNodes.map((node) => [node.node_id, node]));
const right = new Map(rightNodes.map((node) => [node.node_id, node]));
const leftCandidates = new Map<string, Set<string>>();
const rightCandidates = new Map<string, Set<string>>();
const pairs: ApplicationVersionNodePair[] = [];
for (const tier of matchTiers())
applyTier(left, right, pairs, leftCandidates, rightCandidates, tier);
const remainingLeft = sortedNodes(left.values());
const remainingRight = sortedNodes(right.values());
const leftIds = new Set(remainingLeft.map(({ node_id: id }) => id));
const rightIds = new Set(remainingRight.map(({ node_id: id }) => id));
return {
pairs: pairs.sort((a, b) =>
compareCodePoints(
`${a.left.node_id}\0${a.right.node_id}`,
`${b.left.node_id}\0${b.right.node_id}`,
),
),
unmatchedLeft: remainingLeft,
unmatchedRight: remainingRight,
candidatesForLeft: filteredCandidates(leftCandidates, rightIds),
candidatesForRight: filteredCandidates(rightCandidates, leftIds),
};
};
const applyTier = (
left: Map<string, ApplicationNode>,
right: Map<string, ApplicationNode>,
pairs: ApplicationVersionNodePair[],
leftCandidates: Map<string, Set<string>>,
rightCandidates: Map<string, Set<string>>,
tier: MatchTier,
): void => {
const leftByKey = nodesByKey(left.values(), tier.key);
const rightByKey = nodesByKey(right.values(), tier.key);
for (const key of [...leftByKey.keys()].sort(compareCodePoints)) {
const leftGroup = leftByKey.get(key) ?? [];
const rightGroup = rightByKey.get(key) ?? [];
if (rightGroup.length === 0) continue;
recordCandidates(leftGroup, rightGroup, leftCandidates, rightCandidates);
if (leftGroup.length !== 1 || rightGroup.length !== 1) continue;
const leftNode = leftGroup[0];
const rightNode = rightGroup[0];
if (leftNode === undefined || rightNode === undefined) continue;
pairs.push({ left: leftNode, right: rightNode, ...tier });
left.delete(leftNode.node_id);
right.delete(rightNode.node_id);
}
};
const nodesByKey = (
nodes: Iterable<ApplicationNode>,
keyFor: (node: ApplicationNode) => string | null,
): Map<string, ApplicationNode[]> => {
const output = new Map<string, ApplicationNode[]>();
for (const node of nodes) {
const key = keyFor(node);
if (key === null) continue;
output.set(key, [...(output.get(key) ?? []), node]);
}
return output;
};
const recordCandidates = (
left: readonly ApplicationNode[],
right: readonly ApplicationNode[],
leftCandidates: Map<string, Set<string>>,
rightCandidates: Map<string, Set<string>>,
): void => {
for (const leftNode of left) {
const candidates =
leftCandidates.get(leftNode.node_id) ?? new Set<string>();
for (const rightNode of right) candidates.add(rightNode.node_id);
leftCandidates.set(leftNode.node_id, candidates);
}
for (const rightNode of right) {
const candidates =
rightCandidates.get(rightNode.node_id) ?? new Set<string>();
for (const leftNode of left) candidates.add(leftNode.node_id);
rightCandidates.set(rightNode.node_id, candidates);
}
};
const filteredCandidates = (
candidates: ReadonlyMap<string, ReadonlySet<string>>,
retained: ReadonlySet<string>,
): ReadonlyMap<string, readonly string[]> =>
new Map(
[...candidates.entries()].flatMap(([nodeId, values]) => {
const filtered = [...values]
.filter((value) => retained.has(value))
.sort(compareCodePoints);
return filtered.length === 0 ? [] : [[nodeId, filtered] as const];
}),
);
const nodeIdentityKey = (node: ApplicationNode): string =>
`node\0${node.kind}\0${node.node_id}`;
const contentDigestKey = (node: ApplicationNode): string | null =>
node.identity.strategy === "content-digest"
? `content\0${node.kind}\0${node.identity.sha256}`
: null;
const moduleSourceDigestKey = (node: ApplicationNode): string | null => {
if (node.kind !== "javascript-module") return null;
const value = uniqueStringProperty(node, "source_sha256");
return value === null ? null : `module-source\0${node.kind}\0${value}`;
};
const sourceMapKey = (node: ApplicationNode): string | null =>
node.kind === "source-module" &&
node.identity.strategy === "source-map-original"
? `source-map\0${node.identity.original_source}`
: null;
const structuralFingerprintKey = (node: ApplicationNode): string | null => {
if (node.kind !== "javascript-module") return null;
const digest = uniqueStringProperty(node, "structural_fingerprint_sha256");
const algorithm = uniqueStringProperty(
node,
"structural_fingerprint_algorithm",
);
const status = uniqueStringProperty(node, "structural_fingerprint_status");
return digest === null || algorithm === null || status !== "complete"
? null
: `structural\0${node.kind}\0${algorithm}\0${digest}`;
};
const semanticKey = (node: ApplicationNode): string | null => {
if (
[
"javascript-module",
"javascript-chunk",
"runtime-script-instance",
"unknown",
].includes(node.kind)
)
return null;
const properties = firstProperties(node);
const value = semanticValue(node, properties);
return value === null ? null : `semantic\0${node.kind}\0${value}`;
};
const semanticValue = (
node: ApplicationNode,
properties: Readonly<Record<string, JsonValue>>,
): string | null => {
if (node.kind === "endpoint")
return joined(properties.endpoint_kind, properties.value);
if (node.kind === "storage")
return joined(
properties.storage_kind,
properties.name ?? properties.mechanism,
);
if (node.kind === "ipc-channel")
return properties.resolution === "dynamic"
? null
: (stringValue(properties.channel) ?? firstLabel(node));
if (node.kind === "context-bridge-api")
return firstLabel(node) ?? stringValue(properties.api_name);
if (node.kind === "native-export")
return (
joined(
properties.specifier,
stringList(properties.requested_members).join(","),
) ?? firstLabel(node)
);
if (
[
"electron-main",
"electron-preload",
"electron-renderer",
"electron-utility",
].includes(node.kind)
)
return joined(properties.declared_path, properties.resolved_path);
if (node.kind === "package") return stringValue(properties.name);
return canonicalPath(node) ?? stringValue(properties.path);
};
const canonicalPath = (node: ApplicationNode): string | null =>
node.identity.strategy === "canonical-path" ? node.identity.path : null;
const firstProperties = (node: ApplicationNode) =>
node.observations[0]?.properties ?? {};
const firstLabel = (node: ApplicationNode): string | null =>
node.observations.find(({ label }) => label !== null)?.label ?? null;
const uniqueStringProperty = (
node: ApplicationNode,
name: string,
): string | null => {
const values = [
...new Set(
node.observations
.map(({ properties }) => properties[name])
.filter((value): value is string => typeof value === "string"),
),
];
return values.length === 1 ? (values[0] ?? null) : null;
};
const joined = (...values: readonly unknown[]): string | null => {
const strings = values.map(stringValue);
return strings.some((value) => value === null) ? null : strings.join("\0");
};
const stringValue = (value: unknown): string | null =>
typeof value === "string" && value !== "" ? value : null;
const stringList = (value: unknown): string[] =>
Array.isArray(value)
? value
.filter((item): item is string => typeof item === "string")
.sort(compareCodePoints)
: [];
const sortedNodes = (nodes: Iterable<ApplicationNode>): ApplicationNode[] =>
[...nodes].sort((left, right) =>
compareCodePoints(left.node_id, right.node_id),
);
+191
View File
@@ -0,0 +1,191 @@
import type { ApplicationNode } from "./javascriptApplicationGraph.js";
import { compareCodePoints } from "./javascriptApplicationGraph.js";
import type { ApplicationFeatureSeed } from "./javascriptFeatureTraceSchemas.js";
import type { JsonValue } from "./jsonValue.js";
/** One explicit field that matched a feature seed. */
export interface ApplicationFeatureSeedMatch {
readonly node_id: string;
readonly kind: ApplicationNode["kind"];
readonly basis: "node-id" | "label" | "identity" | "property";
readonly field: string;
}
interface CandidateField {
readonly basis: ApplicationFeatureSeedMatch["basis"];
readonly field: string;
readonly value: string;
}
/** Locate every graph node matching a typed literal seed without regex execution. */
export const findApplicationFeatureSeeds = (
nodes: readonly ApplicationNode[],
seed: ApplicationFeatureSeed,
): ApplicationFeatureSeedMatch[] =>
nodes
.flatMap((node) => seedMatch(node, seed))
.sort((left, right) =>
compareCodePoints(
`${left.node_id}\0${left.basis}\0${left.field}`,
`${right.node_id}\0${right.basis}\0${right.field}`,
),
);
const seedMatch = (
node: ApplicationNode,
seed: ApplicationFeatureSeed,
): ApplicationFeatureSeedMatch[] => {
if (seed.kind === "node-id")
return node.node_id === seed.value
? [
{
node_id: node.node_id,
kind: node.kind,
basis: "node-id",
field: "node_id",
},
]
: [];
if (!kindMatches(node, seed.kind)) return [];
const mode = seed.match ?? (seed.kind === "string" ? "contains" : "exact");
const query = normalized(seed.value, seed.case_sensitive);
const match = candidateFields(node, seed.kind).find((candidate) => {
const value = normalized(candidate.value, seed.case_sensitive);
return mode === "exact" ? value === query : value.includes(query);
});
return match === undefined
? []
: [
{
node_id: node.node_id,
kind: node.kind,
basis: match.basis,
field: match.field,
},
];
};
const kindMatches = (
node: ApplicationNode,
kind: Exclude<ApplicationFeatureSeed["kind"], "node-id">,
): boolean => {
if (kind === "string") return true;
if (kind === "route")
return (
node.kind === "endpoint" &&
node.observations.some(
({ properties }) => properties.endpoint_kind === "route",
)
);
if (kind === "api") return node.kind === "context-bridge-api";
if (kind === "channel") return node.kind === "ipc-channel";
if (kind === "module")
return ["javascript-asset", "javascript-module", "source-module"].includes(
node.kind,
);
return node.kind === "native-export";
};
const candidateFields = (
node: ApplicationNode,
seedKind: Exclude<ApplicationFeatureSeed["kind"], "node-id">,
): CandidateField[] => {
const fields: CandidateField[] = [
...identityFields(node),
...node.observations.flatMap((observation, index) => [
...(observation.label === null
? []
: [
{
basis: "label" as const,
field: `observations[${String(index)}].label`,
value: observation.label,
},
]),
...propertyFields(
observation.properties,
`observations[${String(index)}].properties`,
),
]),
];
if (seedKind === "string") return fields;
const names = relevantFields[seedKind];
return fields.filter(({ field }) =>
names.some((name) => field === "identity" || field.endsWith(name)),
);
};
const relevantFields = {
route: [".label", ".value", ".path"],
api: [".label", ".api_name", ".key", ".methods", ".members"],
channel: [".label", ".channel", ".key"],
module: [
".label",
".module_key",
".path",
".source",
".original_source",
".exports",
],
"native-export": [".label", ".key", ".requested_members", ".members"],
} as const;
const identityFields = (node: ApplicationNode): CandidateField[] => {
const identity = node.identity;
if (identity.strategy === "content-digest")
return [{ basis: "identity", field: "identity", value: identity.sha256 }];
if (identity.strategy === "source-map-original")
return [
{
basis: "identity",
field: "identity.original_source",
value: identity.original_source,
},
];
if (identity.strategy === "canonical-path")
return [
{ basis: "identity", field: "identity.path", value: identity.path },
];
if (identity.strategy === "artifact-local-key")
return [{ basis: "identity", field: "identity.key", value: identity.key }];
if (identity.strategy === "runtime-instance")
return [
{
basis: "identity",
field: "identity.runtime_key",
value: identity.runtime_key,
},
];
return [];
};
const propertyFields = (
value: Readonly<Record<string, JsonValue>>,
prefix: string,
): CandidateField[] => {
const output: CandidateField[] = [];
const visit = (current: JsonValue, path: string, depth: number): void => {
if (output.length >= 512 || depth > 6) return;
if (typeof current === "string") {
output.push({ basis: "property", field: path, value: current });
return;
}
if (Array.isArray(current)) {
for (const [index, item] of current.entries())
visit(item, `${path}[${String(index)}]`, depth + 1);
return;
}
if (current !== null && typeof current === "object")
for (const key of Object.keys(current).sort(compareCodePoints))
visit(current[key] ?? null, `${path}.${key}`, depth + 1);
};
visit(value, prefix, 0);
return output;
};
const normalized = (value: string, caseSensitive: boolean): string => {
const normalizedValue = value.normalize("NFKC");
return caseSensitive
? normalizedValue
: normalizedValue.toLocaleLowerCase("en-US");
};
+349
View File
@@ -0,0 +1,349 @@
import { createHash } from "node:crypto";
import canonicalize from "canonicalize";
import type { Evidence } from "./evidence.js";
import {
compareCodePoints,
createJavaScriptApplicationGraph,
type ApplicationEdge,
type ApplicationNode,
type JavaScriptApplicationGraph,
} from "./javascriptApplicationGraph.js";
import {
applicationFeatureTraceResultSchema,
type ApplicationFeatureTraceResult,
type TraceApplicationFeatureInput,
} from "./javascriptFeatureTraceSchemas.js";
import {
findApplicationFeatureSeeds,
type ApplicationFeatureSeedMatch,
} from "./javascriptFeatureSeed.js";
import {
traverseApplicationFeature,
type ApplicationFeatureTraversal,
} from "./javascriptFeatureTraversal.js";
import { buildJavaScriptNativeHandoffs } from "./javascriptNativeHandoff.js";
/** Pure, authenticated inputs projected by the application service. */
export interface ApplicationFeatureTraceProjectionInput {
readonly sourceEvidenceId: string;
readonly graph: JavaScriptApplicationGraph;
readonly nativeEvidence: readonly Evidence[];
readonly seed: TraceApplicationFeatureInput["seed"];
readonly direction: TraceApplicationFeatureInput["direction"];
readonly limits: TraceApplicationFeatureInput["limits"];
}
/** Trace a literal feature through a bounded, authority-preserving JAG. */
export const traceApplicationFeature = (
input: ApplicationFeatureTraceProjectionInput,
): ApplicationFeatureTraceResult => {
const allSeedMatches = findApplicationFeatureSeeds(
input.graph.nodes,
input.seed,
);
const seedMatches = allSeedMatches.slice(0, input.limits.max_seed_matches);
if (seedMatches.length === 0) return noMatchResult(input);
const traversal = traverseApplicationFeature(
input.graph,
seedMatches.map(({ node_id: id }) => id),
input.direction,
input.limits,
);
const graph = traceGraph(
input,
seedMatches,
traversal,
allSeedMatches.length,
);
const allPaths = terminalPaths(traversal, seedMatches);
const paths = allPaths.slice(0, input.limits.max_paths);
const nativeHandoffs = buildJavaScriptNativeHandoffs(
traversal.nodes,
traversal.edges,
input.nativeEvidence,
);
const evidenceLinks = uniqueSorted([
input.sourceEvidenceId,
...nativeHandoffs.flatMap(({ evidence_ids: ids }) => ids),
]);
const omissions = traceOmissions(
input,
traversal,
allSeedMatches.length,
allPaths.length,
);
const semantic = {
schema_version: 1 as const,
source_evidence_id: input.sourceEvidenceId,
source_graph_id: input.graph.graph_id,
seed: input.seed,
direction: input.direction,
seed_matches: seedMatches,
graph,
paths,
native_handoffs: nativeHandoffs,
summary: {
matched_seeds: seedMatches.length,
traced_nodes: traversal.nodes.length,
traced_edges: traversal.edges.length,
terminal_paths: paths.length,
native_handoffs: nativeHandoffs.length,
...factSummary(traversal.nodes, traversal.edges),
},
coverage: {
status: traceCoverageStatus(input.graph, omissions),
source_graph_status: input.graph.coverage.status,
scanned_nodes: input.graph.nodes.length,
total_seed_matches: allSeedMatches.length,
...omissions,
frontier_node_ids: traversal.frontierNodeIds,
},
evidence_links: evidenceLinks,
limitations: traceLimitations(input.graph, omissions),
};
return applicationFeatureTraceResultSchema.parse({
...semantic,
trace_id: `jatr_${digestCanonical(semantic)}`,
});
};
const noMatchResult = (
input: ApplicationFeatureTraceProjectionInput,
): ApplicationFeatureTraceResult => {
const semantic = {
schema_version: 1 as const,
source_evidence_id: input.sourceEvidenceId,
source_graph_id: input.graph.graph_id,
seed: input.seed,
direction: input.direction,
seed_matches: [],
graph: null,
paths: [],
native_handoffs: [],
summary: {
matched_seeds: 0,
traced_nodes: 0,
traced_edges: 0,
terminal_paths: 0,
native_handoffs: 0,
observed_facts: 0,
inferred_facts: 0,
unknown_facts: 0,
unavailable_facts: 0,
},
coverage: {
status: "no-match" as const,
source_graph_status: input.graph.coverage.status,
scanned_nodes: input.graph.nodes.length,
total_seed_matches: 0,
omitted_seed_matches: 0,
omitted_nodes: 0,
omitted_edges: 0,
omitted_paths: 0,
frontier_node_ids: [],
},
evidence_links: [input.sourceEvidenceId],
limitations: uniqueSorted([
"No graph entity matched the literal seed; this is not evidence that the feature is absent.",
...sourceCoverageLimitations(input.graph),
]),
};
return applicationFeatureTraceResultSchema.parse({
...semantic,
trace_id: `jatr_${digestCanonical(semantic)}`,
});
};
const traceGraph = (
input: ApplicationFeatureTraceProjectionInput,
seedMatches: readonly ApplicationFeatureSeedMatch[],
traversal: ApplicationFeatureTraversal,
totalSeedMatches: number,
): JavaScriptApplicationGraph => {
const omitted =
traversal.omittedNodeCount +
traversal.omittedEdgeCount +
(totalSeedMatches - seedMatches.length);
return createJavaScriptApplicationGraph({
schema: "JavaScriptApplicationGraph",
schema_version: 1,
root_node_ids: uniqueSorted(seedMatches.map(({ node_id: id }) => id)),
nodes: traversal.nodes,
edges: traversal.edges,
coverage: traceGraphCoverage(input.graph, input.limits, omitted),
limitations: uniqueSorted([
...input.graph.limitations,
"Trace edges retain their source authority; graph connectivity does not prove runtime execution or reachability.",
...(omitted === 0
? []
: ["Trace output stopped at explicit caller bounds."]),
]),
});
};
const traceGraphCoverage = (
source: JavaScriptApplicationGraph,
limits: TraceApplicationFeatureInput["limits"],
omitted: number,
): JavaScriptApplicationGraph["coverage"] => {
if (omitted > 0)
return {
status: "partial",
truncated: true,
omitted_count: omitted,
limits: [
{
name: "max-seed-matches",
value: limits.max_seed_matches,
unit: "items",
},
{ name: "max-depth", value: limits.max_depth, unit: "depth" },
{ name: "max-nodes", value: limits.max_nodes, unit: "items" },
{ name: "max-edges", value: limits.max_edges, unit: "items" },
],
};
return source.coverage.status === "complete"
? { status: "complete", truncated: false, omitted_count: 0, limits: [] }
: {
status: source.coverage.status,
truncated: source.coverage.truncated,
omitted_count: source.coverage.omitted_count,
limits: source.coverage.limits,
};
};
const terminalPaths = (
traversal: ApplicationFeatureTraversal,
seeds: readonly ApplicationFeatureSeedMatch[],
): ApplicationFeatureTraceResult["paths"] => {
const seedIds = new Set(seeds.map(({ node_id: id }) => id));
const edgeById = new Map(traversal.edges.map((edge) => [edge.edge_id, edge]));
return traversal.nodes
.filter(
(node) =>
isTerminal(node) &&
(!seedIds.has(node.node_id) || traversal.nodes.length === 1),
)
.map((node) => pathTo(node, traversal.predecessors, edgeById))
.filter((path): path is NonNullable<typeof path> => path !== null)
.sort((left, right) => compareCodePoints(left.path_id, right.path_id));
};
const pathTo = (
node: ApplicationNode,
predecessors: ApplicationFeatureTraversal["predecessors"],
edgeById: ReadonlyMap<string, ApplicationEdge>,
): ApplicationFeatureTraceResult["paths"][number] | null => {
const nodeIds = [node.node_id];
const edgeIds: string[] = [];
let current = node.node_id;
while (predecessors.has(current)) {
const predecessor = predecessors.get(current);
if (predecessor === undefined) break;
nodeIds.push(predecessor.previousNodeId);
edgeIds.push(predecessor.edgeId);
current = predecessor.previousNodeId;
}
nodeIds.reverse();
edgeIds.reverse();
const edges = edgeIds
.map((edgeId) => edgeById.get(edgeId))
.filter((edge): edge is ApplicationEdge => edge !== undefined);
if (edges.length !== edgeIds.length) return null;
const semantic = {
start_node_id: nodeIds[0] ?? node.node_id,
end_node_id: node.node_id,
end_kind: node.kind,
node_ids: nodeIds,
edge_ids: edgeIds,
authorities: uniqueSorted(edges.map(({ evidence }) => evidence.authority)),
contains_inference: edges.some(
({ evidence }) => evidence.state === "inferred",
),
};
return { ...semantic, path_id: `jatp_${digestCanonical(semantic)}` };
};
const isTerminal = (node: ApplicationNode): boolean =>
["endpoint", "storage", "native-addon", "native-export", "unknown"].includes(
node.kind,
);
const factSummary = (
nodes: readonly ApplicationNode[],
edges: readonly ApplicationEdge[],
) => {
const states = [
...nodes.flatMap(({ observations }) =>
observations.map(({ evidence }) => evidence.state),
),
...edges.map(({ evidence }) => evidence.state),
];
return {
observed_facts: states.filter((state) => state === "observed").length,
inferred_facts: states.filter((state) => state === "inferred").length,
unknown_facts: states.filter((state) => state === "unknown").length,
unavailable_facts: states.filter((state) => state === "unavailable").length,
};
};
const traceOmissions = (
input: ApplicationFeatureTraceProjectionInput,
traversal: ApplicationFeatureTraversal,
seedMatches: number,
paths: number,
) => ({
omitted_seed_matches: Math.max(
0,
seedMatches - input.limits.max_seed_matches,
),
omitted_nodes: traversal.omittedNodeCount,
omitted_edges: traversal.omittedEdgeCount,
omitted_paths: Math.max(0, paths - input.limits.max_paths),
});
const traceCoverageStatus = (
graph: JavaScriptApplicationGraph,
omissions: ReturnType<typeof traceOmissions>,
): ApplicationFeatureTraceResult["coverage"]["status"] =>
Object.values(omissions).some((value) => value > 0)
? "truncated"
: graph.coverage.status === "complete"
? "complete-within-source"
: "partial";
const traceLimitations = (
graph: JavaScriptApplicationGraph,
omissions: ReturnType<typeof traceOmissions>,
): string[] =>
uniqueSorted([
"A trace reports graph relationships, not proof that code executed or that a feature is reachable in every state.",
"Static, native, passive-runtime, inferred, and unknown facts retain their original authority in the returned graph.",
"Native handoffs never open a binary or invoke a provider automatically; snapshot reuse remains provider/profile/target exact.",
...sourceCoverageLimitations(graph),
...(Object.values(omissions).some((value) => value > 0)
? ["Trace results were truncated at explicit caller limits."]
: []),
]);
const sourceCoverageLimitations = (
graph: JavaScriptApplicationGraph,
): string[] =>
graph.coverage.status === "complete"
? []
: [
"The source application graph is incomplete; unmatched seeds and frontiers remain unknown.",
];
const digestCanonical = (value: unknown): string => {
const encoded = canonicalize(value);
if (encoded === undefined)
throw new TypeError("Feature trace could not canonicalize data");
return createHash("sha256").update(encoded).digest("hex");
};
const uniqueSorted = <Value extends string>(
values: readonly Value[],
): Value[] => [...new Set(values)].sort(compareCodePoints);
+157
View File
@@ -0,0 +1,157 @@
import { z } from "zod";
import { evidenceSchema, providerSchema } from "./evidence.js";
import { javascriptApplicationGraphSchema } from "./javascriptApplicationGraph.js";
const digestSchema = z.string().regex(/^[a-f0-9]{64}$/u);
const evidenceIdSchema = z.string().regex(/^ev_[a-f0-9]{64}$/u);
const nodeIdSchema = z.string().regex(/^jag_node_[a-f0-9]{64}$/u);
const edgeIdSchema = z.string().regex(/^jag_edge_[a-f0-9]{64}$/u);
const boundedTextSchema = z.string().min(1).max(4_096);
/** Literal starting point for one bounded application trace. */
const applicationFeatureSeedSchema = z.strictObject({
kind: z.enum([
"node-id",
"route",
"string",
"api",
"channel",
"module",
"native-export",
]),
value: boundedTextSchema,
match: z.enum(["exact", "contains"]).nullable().default(null),
case_sensitive: z.boolean().default(false),
});
const featureTraceLimitsSchema = z.strictObject({
max_seed_matches: z.number().int().min(1).max(1_000).default(25),
max_depth: z.number().int().min(0).max(64).default(12),
max_nodes: z.number().int().min(1).max(50_000).default(2_000),
max_edges: z.number().int().min(1).max(100_000).default(4_000),
max_paths: z.number().int().min(1).max(1_000).default(100),
});
/** Evidence-backed application graph and explicit trace bounds. */
export const traceApplicationFeatureInputSchema = z
.strictObject({
application: evidenceSchema,
native_observations: z.array(evidenceSchema).max(64).default([]),
seed: applicationFeatureSeedSchema,
direction: z.enum(["outgoing", "incoming", "both"]).default("both"),
limits: featureTraceLimitsSchema.default({
max_seed_matches: 25,
max_depth: 12,
max_nodes: 2_000,
max_edges: 4_000,
max_paths: 100,
}),
})
.superRefine((input, context) => {
const ids = input.native_observations.map(({ evidence_id: id }) => id);
if (new Set(ids).size !== ids.length)
context.addIssue({
code: "custom",
path: ["native_observations"],
message: "Native observations must be unique",
});
});
const seedMatchSchema = z.strictObject({
node_id: nodeIdSchema,
kind: z.string().min(1).max(128),
basis: z.enum(["node-id", "label", "identity", "property"]),
field: z.string().min(1).max(256),
});
const tracePathSchema = z.strictObject({
path_id: z.string().regex(/^jatp_[a-f0-9]{64}$/u),
start_node_id: nodeIdSchema,
end_node_id: nodeIdSchema,
end_kind: z.string().min(1).max(128),
node_ids: z.array(nodeIdSchema).min(1).max(65),
edge_ids: z.array(edgeIdSchema).max(64),
authorities: z.array(z.string().min(1).max(128)).max(16),
contains_inference: z.boolean(),
});
const nativeHandoffSchema = z.strictObject({
native_node_id: nodeIdSchema,
artifact_sha256: digestSchema,
artifact_path: z.string().min(1).max(4_096).nullable(),
export_node_ids: z.array(nodeIdSchema).max(1_000),
requested_exports: z.array(boundedTextSchema).max(1_000),
status: z.enum(["evidence-linked", "requires-provider-analysis"]),
providers: z.array(providerSchema).max(64),
evidence_ids: z.array(evidenceIdSchema).max(64),
recommended_tools: z
.array(
z.enum([
"open_binary",
"binary_overview",
"search_procedures",
"analyze_function",
"xrefs",
]),
)
.max(5),
});
/** Evidence-preserving bounded subgraph and native-analysis frontiers. */
export const applicationFeatureTraceResultSchema = z.strictObject({
schema_version: z.literal(1),
trace_id: z.string().regex(/^jatr_[a-f0-9]{64}$/u),
source_evidence_id: evidenceIdSchema,
source_graph_id: z.string().regex(/^jag_[a-f0-9]{64}$/u),
seed: applicationFeatureSeedSchema,
direction: z.enum(["outgoing", "incoming", "both"]),
seed_matches: z.array(seedMatchSchema).max(1_000),
graph: javascriptApplicationGraphSchema.nullable(),
paths: z.array(tracePathSchema).max(1_000),
native_handoffs: z.array(nativeHandoffSchema).max(10_000),
summary: z.strictObject({
matched_seeds: z.number().int().min(0),
traced_nodes: z.number().int().min(0),
traced_edges: z.number().int().min(0),
terminal_paths: z.number().int().min(0),
native_handoffs: z.number().int().min(0),
observed_facts: z.number().int().min(0),
inferred_facts: z.number().int().min(0),
unknown_facts: z.number().int().min(0),
unavailable_facts: z.number().int().min(0),
}),
coverage: z.strictObject({
status: z.enum([
"complete-within-source",
"partial",
"truncated",
"no-match",
]),
source_graph_status: z.enum([
"complete",
"partial",
"unknown",
"unavailable",
]),
scanned_nodes: z.number().int().min(0),
total_seed_matches: z.number().int().min(0),
omitted_seed_matches: z.number().int().min(0),
omitted_nodes: z.number().int().min(0),
omitted_edges: z.number().int().min(0),
omitted_paths: z.number().int().min(0),
frontier_node_ids: z.array(nodeIdSchema).max(50_000),
}),
evidence_links: z.array(evidenceIdSchema).min(1).max(65),
limitations: z.array(boundedTextSchema).max(1_000),
});
export type TraceApplicationFeatureInput = z.infer<
typeof traceApplicationFeatureInputSchema
>;
export type ApplicationFeatureSeed = z.infer<
typeof applicationFeatureSeedSchema
>;
export type ApplicationFeatureTraceResult = z.infer<
typeof applicationFeatureTraceResultSchema
>;
+143
View File
@@ -0,0 +1,143 @@
import {
compareCodePoints,
type ApplicationEdge,
type ApplicationNode,
type JavaScriptApplicationGraph,
} from "./javascriptApplicationGraph.js";
import type { TraceApplicationFeatureInput } from "./javascriptFeatureTraceSchemas.js";
interface AdjacencyEntry {
readonly edge: ApplicationEdge;
readonly nextNodeId: string;
}
interface Predecessor {
readonly previousNodeId: string;
readonly edgeId: string;
}
/** Bounded graph projection plus the first deterministic path to each node. */
export interface ApplicationFeatureTraversal {
readonly nodes: ApplicationNode[];
readonly edges: ApplicationEdge[];
readonly depths: ReadonlyMap<string, number>;
readonly predecessors: ReadonlyMap<string, Predecessor>;
readonly frontierNodeIds: string[];
readonly omittedNodeCount: number;
readonly omittedEdgeCount: number;
}
/** Traverse a JAG without treating edge inference as observed reachability. */
export const traverseApplicationFeature = (
graph: JavaScriptApplicationGraph,
seedNodeIds: readonly string[],
direction: TraceApplicationFeatureInput["direction"],
limits: TraceApplicationFeatureInput["limits"],
): ApplicationFeatureTraversal => {
const nodeById = new Map(graph.nodes.map((node) => [node.node_id, node]));
const adjacency = buildAdjacency(graph.edges, direction);
const visited = new Set(seedNodeIds);
const retainedEdges = new Map<string, ApplicationEdge>();
const omittedNodes = new Set<string>();
const omittedEdges = new Set<string>();
const frontier = new Set<string>();
const depths = new Map(seedNodeIds.map((nodeId) => [nodeId, 0]));
const predecessors = new Map<string, Predecessor>();
const queue = [...seedNodeIds];
for (let offset = 0; offset < queue.length; offset += 1) {
const current = queue[offset];
if (current === undefined) continue;
const depth = depths.get(current) ?? 0;
for (const entry of adjacency.get(current) ?? []) {
if (depth >= limits.max_depth) {
recordOmission(entry, current, omittedNodes, omittedEdges, frontier);
continue;
}
if (!visited.has(entry.nextNodeId) && visited.size >= limits.max_nodes) {
recordOmission(entry, current, omittedNodes, omittedEdges, frontier);
continue;
}
if (
!retainedEdges.has(entry.edge.edge_id) &&
retainedEdges.size >= limits.max_edges
) {
omittedEdges.add(entry.edge.edge_id);
frontier.add(current);
frontier.add(entry.nextNodeId);
continue;
}
retainedEdges.set(entry.edge.edge_id, entry.edge);
if (visited.has(entry.nextNodeId)) continue;
if (!nodeById.has(entry.nextNodeId)) continue;
visited.add(entry.nextNodeId);
depths.set(entry.nextNodeId, depth + 1);
predecessors.set(entry.nextNodeId, {
previousNodeId: current,
edgeId: entry.edge.edge_id,
});
queue.push(entry.nextNodeId);
}
}
return {
nodes: [...visited]
.map((nodeId) => nodeById.get(nodeId))
.filter((node): node is ApplicationNode => node !== undefined)
.sort((left, right) => compareCodePoints(left.node_id, right.node_id)),
edges: [...retainedEdges.values()].sort((left, right) =>
compareCodePoints(left.edge_id, right.edge_id),
),
depths,
predecessors,
frontierNodeIds: [...frontier].sort(compareCodePoints),
omittedNodeCount: omittedNodes.size,
omittedEdgeCount: omittedEdges.size,
};
};
const buildAdjacency = (
edges: readonly ApplicationEdge[],
direction: TraceApplicationFeatureInput["direction"],
): ReadonlyMap<string, AdjacencyEntry[]> => {
const adjacency = new Map<string, AdjacencyEntry[]>();
for (const edge of edges) {
if (direction !== "incoming")
addAdjacency(adjacency, edge.source_node_id, {
edge,
nextNodeId: edge.target_node_id,
});
if (direction !== "outgoing")
addAdjacency(adjacency, edge.target_node_id, {
edge,
nextNodeId: edge.source_node_id,
});
}
for (const entries of adjacency.values())
entries.sort((left, right) =>
compareCodePoints(
`${left.edge.edge_id}\0${left.nextNodeId}`,
`${right.edge.edge_id}\0${right.nextNodeId}`,
),
);
return adjacency;
};
const addAdjacency = (
adjacency: Map<string, AdjacencyEntry[]>,
nodeId: string,
entry: AdjacencyEntry,
): void => {
adjacency.set(nodeId, [...(adjacency.get(nodeId) ?? []), entry]);
};
const recordOmission = (
entry: AdjacencyEntry,
current: string,
omittedNodes: Set<string>,
omittedEdges: Set<string>,
frontier: Set<string>,
): void => {
omittedNodes.add(entry.nextNodeId);
omittedEdges.add(entry.edge.edge_id);
frontier.add(current);
frontier.add(entry.nextNodeId);
};
+132
View File
@@ -0,0 +1,132 @@
import type { Evidence } from "./evidence.js";
import {
compareCodePoints,
type ApplicationEdge,
type ApplicationNode,
} from "./javascriptApplicationGraph.js";
import type { ApplicationFeatureTraceResult } from "./javascriptFeatureTraceSchemas.js";
type NativeHandoff = ApplicationFeatureTraceResult["native_handoffs"][number];
/** Build provider-neutral addon targets and link exact-subject native Evidence. */
export const buildJavaScriptNativeHandoffs = (
nodes: readonly ApplicationNode[],
edges: readonly ApplicationEdge[],
nativeEvidence: readonly Evidence[],
): NativeHandoff[] => {
const nodeById = new Map(nodes.map((node) => [node.node_id, node]));
return nodes
.filter(({ kind }) => kind === "native-addon")
.flatMap((node) => {
const digest = artifactDigest(node);
if (digest === null) return [];
const linked = nativeEvidence.filter(
({ subject }) => subject?.digest.sha256 === digest,
);
const exportNodes = nativeExportNodes(node, edges, nodeById);
return [
{
native_node_id: node.node_id,
artifact_sha256: digest,
artifact_path: artifactPath(node),
export_node_ids: exportNodes.map(({ node_id: id }) => id),
requested_exports: requestedExports(exportNodes),
status:
linked.length === 0
? ("requires-provider-analysis" as const)
: ("evidence-linked" as const),
providers: uniqueProviders(linked),
evidence_ids: linked
.map(({ evidence_id: id }) => id)
.sort(compareCodePoints),
recommended_tools: [
"open_binary" as const,
"binary_overview" as const,
"search_procedures" as const,
"analyze_function" as const,
"xrefs" as const,
],
},
];
})
.sort((left, right) =>
compareCodePoints(left.native_node_id, right.native_node_id),
);
};
const artifactDigest = (node: ApplicationNode): string | null => {
if (node.identity.strategy === "content-digest") return node.identity.sha256;
const observation = node.observations.find(
({ evidence }) => evidence.artifact.available,
);
return observation?.evidence.artifact.available === true
? observation.evidence.artifact.sha256
: null;
};
const artifactPath = (node: ApplicationNode): string | null => {
for (const { evidence } of node.observations)
if (
evidence.location.available &&
evidence.location.value.kind === "artifact-path"
)
return evidence.location.value.path;
return null;
};
const nativeExportNodes = (
addon: ApplicationNode,
edges: readonly ApplicationEdge[],
nodeById: ReadonlyMap<string, ApplicationNode>,
): ApplicationNode[] => {
const ids = edges.flatMap((edge) => {
if (
edge.source_node_id === addon.node_id &&
["contains", "exposes"].includes(edge.relation)
)
return [edge.target_node_id];
if (
edge.target_node_id === addon.node_id &&
["imports", "loads"].includes(edge.relation)
)
return [edge.source_node_id];
return [];
});
return [...new Set(ids)]
.map((id) => nodeById.get(id))
.filter((node): node is ApplicationNode => node?.kind === "native-export")
.sort((left, right) => compareCodePoints(left.node_id, right.node_id));
};
const requestedExports = (nodes: readonly ApplicationNode[]): string[] => {
const values = nodes.flatMap((node) =>
node.observations.flatMap((observation) => [
...(observation.label === null ? [] : [observation.label]),
...stringArray(observation.properties.requested_members),
...stringArray(observation.properties.members),
]),
);
return [...new Set(values)].sort(compareCodePoints).slice(0, 1_000);
};
const stringArray = (value: unknown): string[] =>
Array.isArray(value)
? value.filter((item): item is string => typeof item === "string")
: [];
const uniqueProviders = (
evidence: readonly Evidence[],
): NativeHandoff["providers"] =>
[
...new Map(
evidence.map(({ provider }) => [
`${provider.id}\0${provider.name}\0${provider.version ?? ""}`,
provider,
]),
).values(),
].sort((left, right) =>
compareCodePoints(
`${left.id}\0${left.name}\0${left.version ?? ""}`,
`${right.id}\0${right.name}\0${right.version ?? ""}`,
),
);
+1 -1
View File
@@ -5,5 +5,5 @@ export const PACKAGE_METADATA = {
serverSdkVersion: "2.0.0-beta.4",
clientSdkVersion: "2.0.0-beta.4",
coreSdkVersion: "2.0.0-beta.4",
skillVersion: "16",
skillVersion: "17",
} as const;
+17
View File
@@ -19,6 +19,7 @@ import type { BrowserObservationPort } from "../application/BrowserObservationPo
import { registerBrowserTools } from "./registerBrowserTools.js";
import type { ElectronObservationPort } from "../application/ElectronObservationPort.js";
import { registerElectronTools } from "./registerElectronTools.js";
import { registerApplicationTools } from "./registerApplicationTools.js";
export interface CreateServerOptions {
readonly logger?: Logger;
@@ -113,6 +114,17 @@ export const createServer = (
server.sendResourceListChanged();
return recorded;
};
const recordEvidenceWithUnknown =
session === undefined
? undefined
: (
evidence: Parameters<typeof session.recordEvidenceWithUnknown>[0],
input: Parameters<typeof session.recordEvidenceWithUnknown>[1],
) => {
const recorded = session.recordEvidenceWithUnknown(evidence, input);
if (recorded.ok) server.sendResourceListChanged();
return recorded;
};
registerOfficialTools(server, analysis, {
logger: toolLogger,
activeTarget,
@@ -158,6 +170,11 @@ export const createServer = (
permissionAuthority: options.permissionAuthority,
recordEvidence,
});
registerApplicationTools(server, {
logger: toolLogger,
recordEvidence,
recordEvidenceWithUnknown,
});
registerGuidedPrompts(server, analysis, session);
if (session !== undefined) {
registerEvidenceResources(server, session);
+131
View File
@@ -0,0 +1,131 @@
import type { McpServer } from "@modelcontextprotocol/server";
import type { BinarySessionPort } from "../application/BinarySession.js";
import {
compareApplicationVersionsEvidence,
traceApplicationFeatureEvidence,
} from "../application/JavaScriptApplicationWorkflowService.js";
import { APPLICATION_TOOL_CONTRACTS } from "../contracts/applicationToolContracts.js";
import { compareApplicationVersionsInputSchema } from "../domain/javascriptApplicationVersionComparisonSchemas.js";
import { applicationVersionComparisonResultSchema } from "../domain/javascriptApplicationVersionComparisonSchemas.js";
import { traceApplicationFeatureInputSchema } from "../domain/javascriptFeatureTraceSchemas.js";
import type { Evidence } from "../domain/evidence.js";
import type { Logger } from "../logger.js";
import { logToolExecution } from "./toolLogging.js";
import { toCallToolResult } from "./toolResult.js";
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
interface ApplicationToolRegistration {
readonly logger: Logger;
readonly recordEvidence: BinarySessionPort["recordEvidence"] | undefined;
readonly recordEvidenceWithUnknown:
| BinarySessionPort["recordEvidenceWithUnknown"]
| undefined;
}
/** Register provider-neutral JavaScript application graph workflows. */
export const registerApplicationTools = (
server: McpServer,
options: ApplicationToolRegistration,
): void => {
const [traceContract, compareContract] = APPLICATION_TOOL_CONTRACTS;
server.registerTool(
traceContract.name,
toolRegistrationOptions(traceContract),
async (input) => {
const parsed = traceApplicationFeatureInputSchema.parse(input);
const result = await logToolExecution(
options.logger,
traceContract.name,
() => Promise.resolve(traceApplicationFeatureEvidence(parsed)),
);
if (!result.ok) return toCallToolResult(result, traceContract);
const sources = [parsed.application, ...parsed.native_observations];
const recorded = recordSources(options.recordEvidence, sources);
if (!recorded.ok) return toCallToolResult(recorded, traceContract);
return recordResult(options, traceContract, result.value);
},
);
server.registerTool(
compareContract.name,
toolRegistrationOptions(compareContract),
async (input) => {
const parsed = compareApplicationVersionsInputSchema.parse(input);
const result = await logToolExecution(
options.logger,
compareContract.name,
() => Promise.resolve(compareApplicationVersionsEvidence(parsed)),
);
if (!result.ok) return toCallToolResult(result, compareContract);
const sources = [
parsed.left,
parsed.right,
...parsed.left_native_observations,
...parsed.right_native_observations,
];
const recorded = recordSources(options.recordEvidence, sources);
if (!recorded.ok) return toCallToolResult(recorded, compareContract);
const comparison = applicationVersionComparisonResultSchema.parse(
result.value.normalized_result,
);
const unknown = comparison.summary.unknown > 0;
return recordResult(
options,
compareContract,
result.value,
parsed.unknown_registry_approved === true && unknown,
);
},
);
};
const recordSources = (
recordEvidence: ApplicationToolRegistration["recordEvidence"],
sources: readonly Evidence[],
) => {
for (const source of sources) {
const recorded = recordEvidence?.(source);
if (recorded !== undefined && !recorded.ok) return recorded;
}
return { ok: true as const, value: null };
};
const recordResult = (
options: ApplicationToolRegistration,
contract: (typeof APPLICATION_TOOL_CONTRACTS)[number],
evidence: Evidence,
recordUnknown = false,
) => {
const recorded = recordUnknown
? options.recordEvidenceWithUnknown?.(evidence, {
approved: true,
question:
"Which application entities remain unmatched or ambiguous across these versions?",
severity: "medium",
domain: "application-version-comparison",
supporting_evidence_ids: [evidence.evidence_id],
contradicting_evidence_ids: [],
required_authority: "shipped-artifact",
required_confidence: "observed",
required_environment: null,
recommended_probes: [
{
operation: "analyze_javascript_application",
rationale:
"Repeat static reconstruction with complete artifacts and source maps when available.",
},
{
operation: "reconcile_javascript_runtime",
rationale:
"Add approved passive runtime Evidence without promoting it to static fact.",
},
],
relationships: [],
})
: options.recordEvidence?.(evidence);
if (recorded !== undefined && !recorded.ok)
return toCallToolResult(recorded, contract);
return toCallToolResult({ ok: true, value: evidence }, contract, {
evidenceResourcesAvailable: recorded !== undefined,
});
};