refactor(contracts): simplify workflows and drop readiness tool
This commit is contained in:
@@ -93,7 +93,11 @@ const browserParameters = (
|
||||
input: BrowserEvidenceInput,
|
||||
): EvidenceObservation["parameters"] => {
|
||||
if (!("cdp_endpoint" in input)) {
|
||||
if ("before_scenario" in input)
|
||||
if (
|
||||
"before_scenario" in input &&
|
||||
input.before_scenario !== undefined &&
|
||||
input.after_scenario !== undefined
|
||||
)
|
||||
return {
|
||||
comparison_kind: "browser_scenario",
|
||||
before_browser: input.before_scenario.browser,
|
||||
@@ -102,10 +106,14 @@ const browserParameters = (
|
||||
after_start_origin: input.after_scenario.scenario.start_origin,
|
||||
max_changes: input.max_changes,
|
||||
normalization_sha256: commitBrowserScenarioNormalization(
|
||||
input.normalization,
|
||||
input.normalization ?? { rules: [] },
|
||||
).sha256,
|
||||
};
|
||||
if ("max_changes" in input)
|
||||
if (
|
||||
"max_changes" in input &&
|
||||
input.before !== undefined &&
|
||||
input.after !== undefined
|
||||
)
|
||||
return {
|
||||
before_target_id: input.before.inspection.target.target_id,
|
||||
before_capture_ended_at:
|
||||
@@ -114,12 +122,14 @@ const browserParameters = (
|
||||
after_capture_ended_at: input.after.inspection.capture_window.ended_at,
|
||||
max_changes: input.max_changes,
|
||||
};
|
||||
return {
|
||||
before_artifact_uri: input.before.uri,
|
||||
after_artifact_uri: input.after.uri,
|
||||
channel_threshold: input.channel_threshold,
|
||||
maximum_pixels: input.maximum_pixels,
|
||||
};
|
||||
if (isScreenshotComparison(input))
|
||||
return {
|
||||
before_artifact_uri: input.before.uri,
|
||||
after_artifact_uri: input.after.uri,
|
||||
channel_threshold: input.channel_threshold,
|
||||
maximum_pixels: input.maximum_pixels,
|
||||
};
|
||||
throw new Error("Browser comparison input did not match a comparison type");
|
||||
}
|
||||
const scope = {
|
||||
cdp_endpoint: input.cdp_endpoint,
|
||||
@@ -172,6 +182,10 @@ const browserParameters = (
|
||||
};
|
||||
};
|
||||
|
||||
const isScreenshotComparison = (
|
||||
input: BrowserEvidenceInput,
|
||||
): input is CompareWebScreenshotsInput => "channel_threshold" in input;
|
||||
|
||||
const browserPredicate = (operation: BrowserEvidenceOperation): string => {
|
||||
switch (operation) {
|
||||
case "list_browser_targets":
|
||||
|
||||
@@ -1,67 +0,0 @@
|
||||
import { z } from "zod";
|
||||
|
||||
import {
|
||||
AnalysisInputError,
|
||||
AnalysisProtocolError,
|
||||
type AnalysisError,
|
||||
} from "../domain/errors.js";
|
||||
import { createEvidence, type Evidence } from "../domain/evidence.js";
|
||||
import { jsonObjectSchema, jsonValueSchema } from "../domain/jsonValue.js";
|
||||
import { createReconstructionReadinessReport } from "../domain/reconstructionReadiness.js";
|
||||
import {
|
||||
reconstructionReadinessInputSchema,
|
||||
type ReconstructionReadinessInput,
|
||||
} from "../domain/reconstructionReadinessSchemas.js";
|
||||
import { err, ok, type Result } from "../domain/result.js";
|
||||
import { JAVASCRIPT_APPLICATION_WORKFLOW_PROVIDER } from "./InvestigationProviders.js";
|
||||
|
||||
const OPERATION = "evaluate_reconstruction_readiness" as const;
|
||||
|
||||
/** Parse one portable readiness request for both CLI and MCP adapters. */
|
||||
export const resolveReconstructionReadinessRequest = (
|
||||
input: unknown,
|
||||
): Result<ReconstructionReadinessInput, AnalysisError> => {
|
||||
const parsed = reconstructionReadinessInputSchema.safeParse(input);
|
||||
return parsed.success
|
||||
? ok(parsed.data)
|
||||
: err(new AnalysisInputError(OPERATION, { cause: parsed.error }));
|
||||
};
|
||||
|
||||
/** Evaluate and wrap one deterministic readiness report in Evidence. */
|
||||
export const evaluateReconstructionReadinessValidated = (
|
||||
input: ReconstructionReadinessInput,
|
||||
): Result<Evidence, AnalysisError> => {
|
||||
try {
|
||||
const report = createReconstructionReadinessReport(input);
|
||||
return ok(
|
||||
createEvidence(undefined, JAVASCRIPT_APPLICATION_WORKFLOW_PROVIDER, {
|
||||
predicateType: "rea.reconstruction-readiness-report/v1",
|
||||
operation: OPERATION,
|
||||
parameters: jsonObjectSchema.parse({
|
||||
source_digest: report.source_digest,
|
||||
expected_source_digest: input.replay.expected_source_digest,
|
||||
}),
|
||||
result: jsonValueSchema.parse(report),
|
||||
rawResult: null,
|
||||
confidence: "inferred",
|
||||
authority: "analyst-inference",
|
||||
environment: null,
|
||||
limitations:
|
||||
report.status === "pass"
|
||||
? []
|
||||
: [
|
||||
"Aggregate pass is withheld until every required conformance stage passes.",
|
||||
],
|
||||
evidenceLinks: report.evidence_links,
|
||||
}),
|
||||
);
|
||||
} catch (cause: unknown) {
|
||||
if (cause instanceof z.ZodError)
|
||||
return err(new AnalysisInputError(OPERATION, { cause }));
|
||||
return err(
|
||||
new AnalysisProtocolError("Reconstruction readiness evaluation failed", {
|
||||
cause,
|
||||
}),
|
||||
);
|
||||
}
|
||||
};
|
||||
@@ -29,10 +29,6 @@ import {
|
||||
buildReconstructionObligationLedgerEvidenceValidated,
|
||||
resolveReconstructionObligationLedgerRequest,
|
||||
} from "./application/ReconstructionObligationLedgerService.js";
|
||||
import {
|
||||
evaluateReconstructionReadinessValidated,
|
||||
resolveReconstructionReadinessRequest,
|
||||
} from "./application/ReconstructionReadinessService.js";
|
||||
import { authorizeRootPermission } from "./application/DeferredFileAuthorization.js";
|
||||
import { loadConfiguredPermissionAuthority } from "./application/PermissionConfiguration.js";
|
||||
import { CLI_COMMANDS } from "./cliCommandNames.js";
|
||||
@@ -151,7 +147,6 @@ export const registerApplicationCommands = (
|
||||
executeNodeCharacterization(replayDependencies(config, authority), input),
|
||||
});
|
||||
registerObligationLedgerCommand(cli, logger);
|
||||
registerReadinessCommand(cli, logger);
|
||||
registerCoverageCommand(cli, logger);
|
||||
};
|
||||
|
||||
@@ -169,17 +164,6 @@ const registerObligationLedgerCommand = (
|
||||
workflow: buildReconstructionObligationLedgerEvidenceValidated,
|
||||
});
|
||||
|
||||
const registerReadinessCommand = (cli: CliInstance, logger: Logger): void =>
|
||||
registerJsonCommand({
|
||||
cli,
|
||||
logger,
|
||||
name: CLI_COMMANDS.evaluateReconstructionReadiness,
|
||||
description:
|
||||
"Evaluate a complete Evidence-backed reconstruction readiness journey",
|
||||
resolveInput: resolveReconstructionReadinessRequest,
|
||||
workflow: evaluateReconstructionReadinessValidated,
|
||||
});
|
||||
|
||||
interface AuthorizedJsonCommandOptions {
|
||||
readonly cli: CliInstance;
|
||||
readonly logger: Logger;
|
||||
|
||||
@@ -16,7 +16,6 @@ export const CLI_COMMANDS = Object.freeze({
|
||||
instructions: "instructions",
|
||||
search: "search",
|
||||
importReferenceSource: "import-reference-source",
|
||||
inventoryArtifact: "inventory-artifact",
|
||||
inspectArtifact: "inspect-artifact",
|
||||
extractArtifact: "extract-artifact",
|
||||
inspectManagedArtifact: "inspect-managed-artifact",
|
||||
@@ -64,7 +63,6 @@ export const CLI_COMMANDS = Object.freeze({
|
||||
prepareNodeCharacterization: "prepare-node-characterization",
|
||||
executeNodeCharacterization: "execute-node-characterization",
|
||||
buildReconstructionObligationLedger: "build-reconstruction-obligation-ledger",
|
||||
evaluateReconstructionReadiness: "evaluate-reconstruction-readiness",
|
||||
evaluateReconstructionCoverage: "evaluate-reconstruction-coverage",
|
||||
});
|
||||
|
||||
|
||||
@@ -26,10 +26,6 @@ import {
|
||||
reconstructionObligationLedgerInputSchema,
|
||||
reconstructionObligationLedgerSchema,
|
||||
} from "../domain/reconstructionObligationLedgerSchemas.js";
|
||||
import {
|
||||
reconstructionReadinessInputSchema,
|
||||
reconstructionReadinessReportSchema,
|
||||
} from "../domain/reconstructionReadinessSchemas.js";
|
||||
import { jsonObjectSchema } from "../domain/jsonValue.js";
|
||||
import type { ToolContract } from "./toolContracts.js";
|
||||
import { toolContractMetadata } from "./toolEffects.js";
|
||||
@@ -40,7 +36,6 @@ import {
|
||||
JAVASCRIPT_FEATURE_TRACE_EXAMPLE,
|
||||
SOURCE_TO_BUNDLE_COMPARISON_EXAMPLE,
|
||||
} from "./javascriptApplicationWorkflowExamples.js";
|
||||
import { RECONSTRUCTION_READINESS_EXAMPLE } from "./reconstructionReadinessExample.js";
|
||||
|
||||
const traceOutputSchema = evidenceResultOf(applicationFeatureTraceResultSchema);
|
||||
const semanticTraceOutputSchema = evidenceResultOf(
|
||||
@@ -58,9 +53,6 @@ const exportShapeComparisonOutputSchema = evidenceResultOf(
|
||||
const reconstructionObligationLedgerOutputSchema = evidenceResultOf(
|
||||
reconstructionObligationLedgerSchema,
|
||||
);
|
||||
const reconstructionReadinessOutputSchema = evidenceResultOf(
|
||||
reconstructionReadinessReportSchema,
|
||||
);
|
||||
const HASH = "0".repeat(64);
|
||||
const NODE_PREPARATION_EXAMPLE = jsonObjectSchema.parse({
|
||||
preparation_approved: true,
|
||||
@@ -116,7 +108,7 @@ export const APPLICATION_TOOL_CONTRACTS = [
|
||||
name: "trace_javascript_semantics",
|
||||
...toolContractMetadata("trace_javascript_semantics"),
|
||||
description:
|
||||
"Trace static JavaScript data-flow, direct call/return, and closure relations from the inline Evidence returned by analyze_javascript_application. Dynamic or unsupported semantics remain explicit unknowns; static reachability never claims runtime execution.",
|
||||
"Trace static JavaScript data-flow, direct call/return, and closure relations from application Evidence returned inline by analyze_javascript_application or referenced by its session Evidence ID. Dynamic or unsupported semantics remain explicit unknowns; static reachability never claims runtime execution.",
|
||||
kind: "application",
|
||||
inputSchema: traceJavaScriptSemanticsRequestSchema,
|
||||
outputSchema: semanticTraceOutputSchema,
|
||||
@@ -296,21 +288,6 @@ export const APPLICATION_TOOL_CONTRACTS = [
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
name: "evaluate_reconstruction_readiness",
|
||||
...toolContractMetadata("evaluate_reconstruction_readiness"),
|
||||
description:
|
||||
"Evaluate the fixed nine-stage public reconstruction journey into a deterministic ReconstructionReadinessReport. Exact capability limits, provider routing, CLI/MCP status parity, bounded authority, partial-order comparison, contradictions, obligation closure, cleanup, and replay digests fail closed. Aggregate pass is emitted only when every required stage and check passes with attributable Evidence.",
|
||||
kind: "application",
|
||||
inputSchema: reconstructionReadinessInputSchema,
|
||||
outputSchema: reconstructionReadinessOutputSchema,
|
||||
examples: [
|
||||
{
|
||||
title: "Evaluate the complete synthetic reconstruction journey",
|
||||
input: RECONSTRUCTION_READINESS_EXAMPLE,
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
name: "evaluate_reconstruction_coverage",
|
||||
...toolContractMetadata("evaluate_reconstruction_coverage"),
|
||||
@@ -392,12 +369,9 @@ export function applicationToolContract(
|
||||
export function applicationToolContract(
|
||||
name: "build_reconstruction_obligation_ledger",
|
||||
): (typeof APPLICATION_TOOL_CONTRACTS)[8];
|
||||
export function applicationToolContract(
|
||||
name: "evaluate_reconstruction_readiness",
|
||||
): (typeof APPLICATION_TOOL_CONTRACTS)[9];
|
||||
export function applicationToolContract(
|
||||
name: "evaluate_reconstruction_coverage",
|
||||
): (typeof APPLICATION_TOOL_CONTRACTS)[10];
|
||||
): (typeof APPLICATION_TOOL_CONTRACTS)[9];
|
||||
export function applicationToolContract(
|
||||
name: (typeof APPLICATION_TOOL_CONTRACTS)[number]["name"],
|
||||
): (typeof APPLICATION_TOOL_CONTRACTS)[number] {
|
||||
|
||||
@@ -56,30 +56,44 @@ const compareApplicationVersionsFacts = {
|
||||
compareApplicationVersionsInputSchema.shape.unknown_registry_approved,
|
||||
} as const;
|
||||
|
||||
/** MCP/CLI comparison request accepting full Evidence or ledger references. */
|
||||
export const compareApplicationVersionsRequestSchema = z.union([
|
||||
z.strictObject({
|
||||
...compareApplicationVersionsFacts,
|
||||
left: evidenceSchema,
|
||||
right: evidenceSchema,
|
||||
}),
|
||||
z.strictObject({
|
||||
...compareApplicationVersionsFacts,
|
||||
left: evidenceSchema,
|
||||
right_evidence_id: evidenceIdSchema,
|
||||
}),
|
||||
z.strictObject({
|
||||
...compareApplicationVersionsFacts,
|
||||
left_evidence_id: evidenceIdSchema,
|
||||
right: evidenceSchema,
|
||||
}),
|
||||
z.strictObject({
|
||||
...compareApplicationVersionsFacts,
|
||||
left_evidence_id: evidenceIdSchema,
|
||||
right_evidence_id: evidenceIdSchema,
|
||||
}),
|
||||
const applicationEvidenceReferenceSchema = z.union([
|
||||
evidenceSchema,
|
||||
evidenceIdSchema,
|
||||
]);
|
||||
|
||||
/** MCP/CLI comparison request accepting inline Evidence or session Evidence IDs. */
|
||||
export const compareApplicationVersionsRequestSchema = z
|
||||
.strictObject({
|
||||
...compareApplicationVersionsFacts,
|
||||
left: applicationEvidenceReferenceSchema
|
||||
.optional()
|
||||
.describe(
|
||||
"Full application Evidence or an Evidence ID returned this session",
|
||||
),
|
||||
right: applicationEvidenceReferenceSchema
|
||||
.optional()
|
||||
.describe(
|
||||
"Full application Evidence or an Evidence ID returned this session",
|
||||
),
|
||||
// Retain the original ID property names for existing callers.
|
||||
left_evidence_id: evidenceIdSchema.optional(),
|
||||
right_evidence_id: evidenceIdSchema.optional(),
|
||||
})
|
||||
.superRefine((input, context) => {
|
||||
for (const side of ["left", "right"] as const) {
|
||||
const alias = `${side}_evidence_id` as const;
|
||||
const hasValue = input[side] !== undefined;
|
||||
const hasAlias = input[alias] !== undefined;
|
||||
if (hasValue === hasAlias) {
|
||||
context.addIssue({
|
||||
code: "custom",
|
||||
path: [side],
|
||||
message: `Provide exactly one of ${side} or ${alias}`,
|
||||
});
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
const compareSourceToBundleFacts = {
|
||||
reference: compareSourceToBundleInputSchema.shape.reference,
|
||||
limits: compareSourceToBundleInputSchema.shape.limits,
|
||||
|
||||
@@ -277,7 +277,7 @@ export const BROWSER_TOOL_CONTRACTS = [
|
||||
name: "compare_web_captures",
|
||||
...toolContractMetadata("compare_web_captures"),
|
||||
description:
|
||||
"Compare either passive web captures or step-indexed browser scenarios. Scenario comparison aligns exact step IDs, records deterministic literal normalization, and exposes bounded artifact-level changes plus alignment failures. Missing or truncated evidence never proves equality.",
|
||||
"Compare passive web captures by providing before and after, or compare recorded scenarios by providing before_scenario and after_scenario with an optional normalization policy. Use exactly one input group. Scenario comparison aligns exact step IDs, records deterministic literal normalization, and exposes bounded artifact-level changes plus alignment failures. Missing or truncated evidence never proves equality.",
|
||||
kind: "browser-provider",
|
||||
inputSchema: browserCaptureComparisonInputSchema,
|
||||
outputSchema: captureDiffOutputSchema,
|
||||
|
||||
@@ -59,6 +59,46 @@ const describesObject = (schema: ReturnType<typeof contractJsonSchema>) =>
|
||||
);
|
||||
|
||||
describe("tool contract surface", () => {
|
||||
it("advertises capture comparison alternatives on an object root", () => {
|
||||
const contract = BROWSER_TOOL_CONTRACTS.find(
|
||||
({ name }) => name === "compare_web_captures",
|
||||
);
|
||||
if (contract === undefined)
|
||||
throw new Error("compare_web_captures contract is missing");
|
||||
|
||||
const schema = contractJsonSchema(contract.inputSchema);
|
||||
expect(schema.type).toBe("object");
|
||||
expect(schema.oneOf).toBeUndefined();
|
||||
expect(Object.keys(schema.properties ?? {})).toEqual(
|
||||
expect.arrayContaining([
|
||||
"before",
|
||||
"after",
|
||||
"before_scenario",
|
||||
"after_scenario",
|
||||
"normalization",
|
||||
"max_changes",
|
||||
]),
|
||||
);
|
||||
const example = contract.examples[0];
|
||||
if (example === undefined)
|
||||
throw new Error("compare_web_captures example is missing");
|
||||
if (
|
||||
!("before_scenario" in example.input) ||
|
||||
!("after_scenario" in example.input)
|
||||
)
|
||||
throw new Error("compare_web_captures example is not a scenario pair");
|
||||
const withoutNormalization = Object.fromEntries(
|
||||
Object.entries(example.input).filter(([key]) => key !== "normalization"),
|
||||
);
|
||||
expect(contract.inputSchema.safeParse(withoutNormalization).success).toBe(
|
||||
true,
|
||||
);
|
||||
const incomplete = Object.fromEntries(
|
||||
Object.entries(example.input).filter(([key]) => key !== "after_scenario"),
|
||||
);
|
||||
expect(contract.inputSchema.safeParse(incomplete).success).toBe(false);
|
||||
});
|
||||
|
||||
it("advertises complete typed schemas and annotations for every public tool", () => {
|
||||
const contracts = TOOL_CONTRACTS;
|
||||
for (const contract of contracts) {
|
||||
|
||||
@@ -63,8 +63,8 @@ export const JAVASCRIPT_FEATURE_TRACE_EXAMPLE = {
|
||||
|
||||
/** Natural version comparison using two producer-returned Evidence IDs. */
|
||||
export const JAVASCRIPT_APPLICATION_VERSION_COMPARISON_EXAMPLE = {
|
||||
left_evidence_id: EXAMPLE_EVIDENCE_ID,
|
||||
right_evidence_id: SECOND_EXAMPLE_EVIDENCE_ID,
|
||||
left: EXAMPLE_EVIDENCE_ID,
|
||||
right: SECOND_EXAMPLE_EVIDENCE_ID,
|
||||
};
|
||||
|
||||
/** Historical source inventory compared with one producer-returned graph ID. */
|
||||
|
||||
@@ -91,7 +91,7 @@ describe("guided prompt contracts", () => {
|
||||
expect(
|
||||
rendered
|
||||
.get("compare_application_versions")
|
||||
?.indexOf("`inventory_artifact`"),
|
||||
?.indexOf("`inspect_artifact`"),
|
||||
).toBeLessThan(
|
||||
rendered
|
||||
.get("compare_application_versions")
|
||||
|
||||
@@ -184,9 +184,9 @@ export const PROMPT_CONTRACTS = [
|
||||
},
|
||||
steps: [
|
||||
{
|
||||
tools: ["open_binary", "inventory_artifact"],
|
||||
tools: ["open_binary", "inspect_artifact"],
|
||||
instruction:
|
||||
"For each supplied target path, open that target before inventory because inventory_artifact uses the active target and accepts no path. Follow nodes, occurrences, and edges to completion and retain every Evidence page for each manifest.",
|
||||
"For each supplied target path, open that target before inspection because inspect_artifact uses the active target and accepts no path. Retain the returned graph, substep Evidence, integrity findings, and next probes for each manifest.",
|
||||
},
|
||||
{
|
||||
tools: [
|
||||
|
||||
@@ -19,7 +19,6 @@ describe("tool contract inventory", () => {
|
||||
expect(ENHANCED_TOOL_CONTRACTS).toHaveLength(13);
|
||||
expect(NATIVE_TOOL_CONTRACTS).toHaveLength(5);
|
||||
expect(ARTIFACT_TOOL_CONTRACTS.map(({ name }) => name)).toEqual([
|
||||
"inventory_artifact",
|
||||
"inspect_artifact",
|
||||
"extract_artifact",
|
||||
]);
|
||||
@@ -62,7 +61,6 @@ describe("tool contract inventory", () => {
|
||||
"prepare_node_characterization",
|
||||
"execute_node_characterization",
|
||||
"build_reconstruction_obligation_ledger",
|
||||
"evaluate_reconstruction_readiness",
|
||||
"evaluate_reconstruction_coverage",
|
||||
]);
|
||||
expect(new Set(TOOL_CONTRACTS.map(({ name }) => name)).size).toBe(
|
||||
|
||||
@@ -407,7 +407,7 @@ export const SESSION_TOOL_CONTRACTS = [
|
||||
),
|
||||
session(
|
||||
"compare_artifacts",
|
||||
"Compare complete inventory_artifact Evidence sets by logical occurrence path, content identity, metadata, and graph relations. Every delta cites both sets, and gaps yield truncated or unknown, never equivalence. Returns every change inline.",
|
||||
"Compare complete artifact inventories by logical occurrence path, content identity, metadata, and graph relations. Use the inventory Evidence nested in each inspect_artifact result. Every delta cites both inspections, and gaps yield truncated or unknown, never equivalence. Returns every change inline.",
|
||||
artifactComparisonInputSchema,
|
||||
),
|
||||
session(
|
||||
|
||||
@@ -98,7 +98,6 @@ export const TOOL_EFFECTS: Readonly<Record<string, ToolEffects>> = {
|
||||
inspect_plist: nativeEvidence,
|
||||
list_architectures: nativeEvidence,
|
||||
demangle_swift: nativeEvidence,
|
||||
inventory_artifact: evidence,
|
||||
inspect_artifact: evidence,
|
||||
extract_artifact: effects({ mutatesSession: true, writesFilesystem: true }),
|
||||
inspect_managed_artifact: evidence,
|
||||
@@ -149,7 +148,6 @@ export const TOOL_EFFECTS: Readonly<Record<string, ToolEffects>> = {
|
||||
compare_source_to_bundle: evidence,
|
||||
compare_javascript_export_shapes: evidence,
|
||||
build_reconstruction_obligation_ledger: evidence,
|
||||
evaluate_reconstruction_readiness: evidence,
|
||||
run_replay_machine: effects(),
|
||||
run_controlled_replay: effects({
|
||||
mutatesSession: true,
|
||||
|
||||
@@ -19,10 +19,7 @@ import {
|
||||
inspectSignatureSchema,
|
||||
listArchitecturesSchema,
|
||||
} from "../domain/nativeInspection.js";
|
||||
import {
|
||||
artifactExtractionResultSchema,
|
||||
artifactInventoryResultSchema,
|
||||
} from "../domain/artifactGraph.js";
|
||||
import { artifactExtractionResultSchema } from "../domain/artifactGraph.js";
|
||||
import { artifactInspectionResultSchema } from "../domain/artifactInspection.js";
|
||||
import {
|
||||
managedArtifactInspectionSchema,
|
||||
@@ -296,7 +293,6 @@ export const nativeOutputSchemas: Readonly<Record<string, z.ZodObject>> = {
|
||||
|
||||
/** Exact Evidence v2 schemas for provider-neutral artifact graph operations. */
|
||||
export const artifactOutputSchemas: Readonly<Record<string, z.ZodObject>> = {
|
||||
inventory_artifact: resultOf(artifactInventoryResultSchema),
|
||||
inspect_artifact: resultOf(artifactInspectionResultSchema),
|
||||
extract_artifact: resultOf(artifactExtractionResultSchema),
|
||||
};
|
||||
|
||||
@@ -1,10 +1,7 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import { traceJavaScriptSemanticsRequestSchema } from "./applicationWorkflowInputContracts.js";
|
||||
import {
|
||||
artifactInspectionInputSchema,
|
||||
artifactInventoryInputSchema,
|
||||
} from "./artifactToolContracts.js";
|
||||
import { ARTIFACT_TOOL_CONTRACTS } from "./artifactToolContracts.js";
|
||||
import { JAVASCRIPT_FEATURE_TRACE_FULL_EVIDENCE_EXAMPLE } from "./javascriptApplicationWorkflowExamples.js";
|
||||
import {
|
||||
MANAGED_WORKFLOW_TOOL_CONTRACTS,
|
||||
@@ -89,7 +86,10 @@ describe("workflow input contracts", () => {
|
||||
integrity_policy: "record-and-continue" as const,
|
||||
integrity_continue_approved: false,
|
||||
};
|
||||
expect(artifactInventoryInputSchema.safeParse(input).success).toBe(false);
|
||||
expect(artifactInspectionInputSchema.safeParse(input).success).toBe(false);
|
||||
const inspect = ARTIFACT_TOOL_CONTRACTS.find(
|
||||
({ name }) => name === "inspect_artifact",
|
||||
);
|
||||
if (inspect === undefined) throw new Error("Missing inspect_artifact");
|
||||
expect(inspect.inputSchema.safeParse(input).success).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
@@ -5,12 +5,12 @@ import {
|
||||
compareBrowserScenarios,
|
||||
compareBrowserScenariosInputSchema,
|
||||
type BrowserScenarioDiff,
|
||||
type CompareBrowserScenariosInput,
|
||||
} from "./browserScenarioDiff.js";
|
||||
import {
|
||||
compareWebCaptures,
|
||||
captureSnapshotSchema,
|
||||
webCaptureDiffSchema,
|
||||
type CompareWebCapturesInput,
|
||||
type WebCaptureDiff,
|
||||
} from "./webCaptureDiff.js";
|
||||
|
||||
@@ -22,34 +22,61 @@ const maxChangesSchema = z
|
||||
.default(2_000)
|
||||
.describe("Maximum normalized change records to retain.");
|
||||
|
||||
/** Top-level MCP shape for exactly one complete passive or scenario pair. */
|
||||
export const browserCaptureComparisonInputSchema = z.union([
|
||||
z.strictObject({
|
||||
before: captureSnapshotSchema.describe("Earlier passive web-page capture."),
|
||||
after: captureSnapshotSchema.describe("Later passive web-page capture."),
|
||||
/** Caller-visible object schema for passive and scenario capture comparisons. */
|
||||
export const browserCaptureComparisonInputSchema = z
|
||||
.strictObject({
|
||||
before: captureSnapshotSchema
|
||||
.optional()
|
||||
.describe("Earlier passive web-page capture."),
|
||||
after: captureSnapshotSchema
|
||||
.optional()
|
||||
.describe("Later passive web-page capture."),
|
||||
before_scenario: compareBrowserScenariosInputSchema.shape.before_scenario
|
||||
.optional()
|
||||
.describe("Earlier browser scenario capture."),
|
||||
after_scenario: compareBrowserScenariosInputSchema.shape.after_scenario
|
||||
.optional()
|
||||
.describe("Later browser scenario capture."),
|
||||
normalization: compareBrowserScenariosInputSchema.shape.normalization
|
||||
.unwrap()
|
||||
.optional()
|
||||
.describe("Exact-literal normalization policy."),
|
||||
max_changes: maxChangesSchema,
|
||||
}),
|
||||
z.strictObject({
|
||||
before_scenario:
|
||||
compareBrowserScenariosInputSchema.shape.before_scenario.describe(
|
||||
"Earlier browser scenario capture.",
|
||||
),
|
||||
after_scenario:
|
||||
compareBrowserScenariosInputSchema.shape.after_scenario.describe(
|
||||
"Later browser scenario capture.",
|
||||
),
|
||||
normalization:
|
||||
compareBrowserScenariosInputSchema.shape.normalization.describe(
|
||||
"Exact-literal normalization policy.",
|
||||
),
|
||||
max_changes: maxChangesSchema,
|
||||
}),
|
||||
]);
|
||||
})
|
||||
.superRefine((input, context) => {
|
||||
const passive = input.before !== undefined && input.after !== undefined;
|
||||
const scenario =
|
||||
input.before_scenario !== undefined && input.after_scenario !== undefined;
|
||||
const passiveFieldsPresent =
|
||||
input.before !== undefined || input.after !== undefined;
|
||||
const scenarioFieldsPresent =
|
||||
input.before_scenario !== undefined ||
|
||||
input.after_scenario !== undefined ||
|
||||
input.normalization !== undefined;
|
||||
|
||||
if (passive && !scenarioFieldsPresent) return;
|
||||
if (scenario && !passiveFieldsPresent) return;
|
||||
|
||||
context.addIssue({
|
||||
code: "custom",
|
||||
message:
|
||||
"Provide before and after passive captures, or before_scenario, after_scenario, and normalization; do not mix comparison types.",
|
||||
});
|
||||
});
|
||||
|
||||
/** Parsed browser capture comparison input. */
|
||||
export type BrowserCaptureComparisonInput = z.output<
|
||||
typeof browserCaptureComparisonInputSchema
|
||||
>;
|
||||
type ScenarioCapturePair = Pick<
|
||||
BrowserCaptureComparisonInput,
|
||||
"before_scenario" | "after_scenario" | "normalization" | "max_changes"
|
||||
> & {
|
||||
before_scenario: NonNullable<
|
||||
BrowserCaptureComparisonInput["before_scenario"]
|
||||
>;
|
||||
after_scenario: NonNullable<BrowserCaptureComparisonInput["after_scenario"]>;
|
||||
};
|
||||
|
||||
/** Result from passive page or browser scenario comparison. */
|
||||
export const browserCaptureComparisonSchema = z.union([
|
||||
@@ -64,9 +91,25 @@ export const compareBrowserCaptures = (
|
||||
input: BrowserCaptureComparisonInput,
|
||||
): BrowserCaptureComparison =>
|
||||
isScenarioComparison(input)
|
||||
? compareBrowserScenarios(input)
|
||||
: compareWebCaptures(input);
|
||||
? compareBrowserScenarios({
|
||||
...input,
|
||||
normalization: input.normalization ?? { rules: [] },
|
||||
})
|
||||
: compareWebCaptures(toPassiveComparison(input));
|
||||
|
||||
const isScenarioComparison = (
|
||||
input: BrowserCaptureComparisonInput,
|
||||
): input is CompareBrowserScenariosInput => "before_scenario" in input;
|
||||
): input is ScenarioCapturePair =>
|
||||
input.before_scenario !== undefined && input.after_scenario !== undefined;
|
||||
|
||||
const toPassiveComparison = (
|
||||
input: BrowserCaptureComparisonInput,
|
||||
): CompareWebCapturesInput => {
|
||||
if (input.before === undefined || input.after === undefined)
|
||||
throw new Error("Validated passive comparison is missing a capture");
|
||||
return {
|
||||
before: input.before,
|
||||
after: input.after,
|
||||
max_changes: input.max_changes,
|
||||
};
|
||||
};
|
||||
|
||||
@@ -12,7 +12,7 @@ const input = (
|
||||
});
|
||||
|
||||
describe("reconstruction readiness report", () => {
|
||||
it("passes the complete public-contract journey deterministically", () => {
|
||||
it("passes the complete repository conformance journey deterministically", () => {
|
||||
const first = createReconstructionReadinessReport(input());
|
||||
const second = createReconstructionReadinessReport(input());
|
||||
|
||||
|
||||
@@ -125,7 +125,7 @@ const defaultProbe = (
|
||||
rationale: "Capture complete function dossiers under equal limits.",
|
||||
}
|
||||
: {
|
||||
operation: "inventory_artifact",
|
||||
operation: "inspect_artifact",
|
||||
rationale:
|
||||
"Capture complete artifact inventories under equal limits.",
|
||||
};
|
||||
|
||||
@@ -55,7 +55,7 @@ import {
|
||||
} from "./sessionToolPolicies.js";
|
||||
|
||||
const TARGET_FREE_INSTRUCTIONS =
|
||||
"ASAR/JavaScript -> analyze_javascript_application; archive/package -> open_binary(path), then inspect_artifact/inventory_artifact; managed PE/CLI -> inspect_managed_artifact; browser/Electron -> list_browser_targets/list_electron_targets; capture_browser_scenario/capture_electron_scenario; Node/Electron Inspector -> list_javascript_runtime_targets; native binary/database -> open_binary, then binary_overview. Start with binary_session; use tools/list; capabilities via binary_session.";
|
||||
"Start with binary_session to see the active target and available providers. For an archive or application package, call open_binary(path), then inspect_artifact for the complete graph and findings; use extract_artifact only for selected files. For standalone JavaScript or ASAR analysis, use analyze_javascript_application. For managed PE/CLI files, use inspect_managed_artifact. For native binaries, open the target and start with binary_overview. For a live page or runtime, discover targets with list_browser_targets, list_electron_targets, or list_javascript_runtime_targets before inspection; scenario capture tools are for controlled interactions.";
|
||||
|
||||
const ACTIVE_TARGET_INSTRUCTIONS =
|
||||
"REA analyzes the active reverse-engineering target. Start native analysis with binary_overview, then use analyze_function, literal search, callers, callees, and xrefs as needed.";
|
||||
|
||||
@@ -9,7 +9,6 @@ import { registerControlledReplayTool } from "./registerApplicationTools/control
|
||||
import { registerCharacterizationTools } from "./registerApplicationTools/characterization.js";
|
||||
import { registerCoverageTools } from "./registerApplicationTools/coverage.js";
|
||||
import { registerReconstructionObligationLedgerTool } from "./registerApplicationTools/obligationLedger.js";
|
||||
import { registerReconstructionReadinessTool } from "./registerApplicationTools/readiness.js";
|
||||
import type { ApplicationToolRegistration } from "./registerApplicationTools/types.js";
|
||||
|
||||
export type { ApplicationToolRegistration };
|
||||
@@ -27,6 +26,5 @@ export const registerApplicationTools = (
|
||||
registerControlledReplayTool(server, options);
|
||||
registerCharacterizationTools(server, options);
|
||||
registerReconstructionObligationLedgerTool(server, options);
|
||||
registerReconstructionReadinessTool(server, options);
|
||||
registerCoverageTools(server, options);
|
||||
};
|
||||
|
||||
@@ -1,45 +0,0 @@
|
||||
import { recordSessionEvidenceSources } from "../sessionEvidence.js";
|
||||
import type { McpServer } from "@modelcontextprotocol/server";
|
||||
|
||||
import {
|
||||
evaluateReconstructionReadinessValidated,
|
||||
resolveReconstructionReadinessRequest,
|
||||
} from "../../application/ReconstructionReadinessService.js";
|
||||
import { applicationToolContract } from "../../contracts/applicationToolContracts.js";
|
||||
import { logToolExecution } from "../toolLogging.js";
|
||||
import { toolRegistrationOptions } from "../toolRegistrationOptions.js";
|
||||
import { toCallToolResult } from "../toolResult.js";
|
||||
|
||||
import type { ApplicationToolRegistration } from "./types.js";
|
||||
|
||||
const contract = applicationToolContract("evaluate_reconstruction_readiness");
|
||||
|
||||
/** Register deterministic public-contract reconstruction conformance. */
|
||||
export const registerReconstructionReadinessTool = (
|
||||
server: McpServer,
|
||||
options: ApplicationToolRegistration,
|
||||
): void => {
|
||||
server.registerTool(
|
||||
contract.name,
|
||||
toolRegistrationOptions(contract),
|
||||
async (input) => {
|
||||
const resolved = resolveReconstructionReadinessRequest(input);
|
||||
if (!resolved.ok) return toCallToolResult(resolved, contract);
|
||||
const result = await logToolExecution(options.logger, contract.name, () =>
|
||||
Promise.resolve(
|
||||
evaluateReconstructionReadinessValidated(resolved.value),
|
||||
),
|
||||
);
|
||||
if (!result.ok) return toCallToolResult(result, contract);
|
||||
const recorded = recordSessionEvidenceSources(
|
||||
options.recordEvidence,
|
||||
resolved.value.evidence_bundle.records,
|
||||
);
|
||||
if (!recorded.ok) return toCallToolResult(recorded, contract);
|
||||
const recordedResult = options.recordEvidence?.(result.value);
|
||||
if (recordedResult !== undefined && !recordedResult.ok)
|
||||
return toCallToolResult(recordedResult, contract);
|
||||
return toCallToolResult({ ok: true, value: result.value }, contract);
|
||||
},
|
||||
);
|
||||
};
|
||||
@@ -137,7 +137,7 @@ const permissionRequest = (
|
||||
operation_identity: `extract_artifact:${parameters.output_root}`,
|
||||
};
|
||||
if (
|
||||
["inventory_artifact", "inspect_artifact"].includes(operation) &&
|
||||
operation === "inspect_artifact" &&
|
||||
parameters.native_mount_approved === true
|
||||
)
|
||||
return {
|
||||
|
||||
Reference in New Issue
Block a user