refactor(contracts): simplify workflows and drop readiness tool
This commit is contained in:
@@ -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);
|
||||
});
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user