refactor(contracts): simplify workflows and drop readiness tool

This commit is contained in:
morluto
2026-09-29 09:22:44 +08:00
parent 0fe96d92df
commit 7acac615ca
37 changed files with 401 additions and 505 deletions
+2 -28
View File
@@ -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,
+1 -1
View File
@@ -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,
+40
View File
@@ -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. */
+1 -1
View File
@@ -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")
+2 -2
View File
@@ -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: [
-2
View File
@@ -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(
+1 -1
View File
@@ -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(
-2
View File
@@ -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,
+1 -5
View File
@@ -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),
};
+6 -6
View File
@@ -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);
});
});