Compare commits

..
9 changed files with 238 additions and 253 deletions

No files matched your search

@@ -5,6 +5,8 @@ import { expect, it, vi } from "vitest";
import { ArtifactResourceScope } from "../../artifacts/ArtifactResourceScope.js";
import { apiContractSchema } from "../../domain/apiContract/apiContract.js";
import { AnalysisResourceConstraintError } from "../../domain/analysisErrorCore.js";
import { parseEvidence } from "../../domain/evidence.js";
import { projectAnalysisView } from "../../domain/analysisView/analysisView.js";
import { createTestTempDirectory } from "../../../tests/fixtures/temporaryDirectory.js";
import { inspectApiContractEvidence } from "./ApiContractService.js";
import * as readOwner from "./ApiContractRead.js";
@@ -317,3 +319,89 @@ it("cancels a cooperative document traversal after the actual verified file read
await resources.close();
}
});
it.each(["between-paths", "after-projection"] as const)(
"preserves authenticated OpenAPI facts on cancellation %s",
async (stage) => {
const bytes = JSON.stringify({
openapi: "3.1.2",
info: { title: "Cancellation", version: "1" },
paths: { "/first": { get: {} }, "/second": { post: {} } },
});
const { path } = await inputFile(bytes);
const resources = new ArtifactResourceScope();
const controller = new AbortController();
const realParse = parser.parseApiContractSteps;
try {
const baseline = await inspectApiContractEvidence({ path }, resources);
if (!baseline.ok) throw baseline.error;
const complete = apiContractSchema.parse(
baseline.value.normalized_result,
);
const scheduled = vi
.spyOn(parser, "parseApiContractSteps")
.mockImplementationOnce(function* (...args) {
const steps = realParse(...args);
if (stage === "between-paths") {
expect(steps.next().done).toBe(false);
expect(steps.next().done).toBe(false);
setImmediate(() => controller.abort(stage));
return yield* steps;
}
const result = yield* steps;
setImmediate(() => controller.abort(stage));
return result;
});
try {
const result = await inspectApiContractEvidence({ path }, resources, {
signal: controller.signal,
});
if (result.ok) throw new Error("Expected cancellation");
expect(result.error._tag).toBe("AnalysisCancelledError");
expect(result.error.cause).toBe(stage);
const evidence = parseEvidence(result.error.partialObservation);
const retained = apiContractSchema.parse(evidence.normalized_result);
expect(evidence.subject).toEqual(baseline.value.subject);
expect(evidence.parameters).toEqual(baseline.value.parameters);
expect(retained.artifact).toEqual(complete.artifact);
expect(retained.contract_id).toBe(complete.contract_id);
if (stage === "between-paths") {
expect(retained.operations).toEqual(complete.operations.slice(0, 1));
expect(retained.source_coverage.status).toBe("partial");
expect(evidence.evidence_id).not.toBe(baseline.value.evidence_id);
const page = projectAnalysisView(
{
evidenceId: evidence.evidence_id,
operation: evidence.operation,
predicateType: evidence.predicate_type,
normalizedResult: evidence.normalized_result,
limitations: evidence.limitations,
},
{
kind: "api-contract",
collection: "operations",
offset: 0,
limit: 1,
},
);
expect(page).toMatchObject({
ok: true,
value: {
parent_evidence_id: evidence.evidence_id,
items: [{ path: "/first", state: "declared" }],
coverage: { exhausted: true },
source_coverage: { status: "partial" },
},
});
} else {
expect(retained).toEqual(complete);
expect(evidence.evidence_id).toBe(baseline.value.evidence_id);
}
} finally {
scheduled.mockRestore();
}
} finally {
await resources.close();
}
},
);
@@ -11,6 +11,8 @@ import { err, ok, type Result } from "../../domain/result.js";
import {
API_CONTRACT_OPERATION as operation,
API_CONTRACT_PROVIDER,
apiContractSchema,
type ApiContract,
type ApiContractArtifact,
} from "../../domain/apiContract/apiContract.js";
import {
@@ -70,8 +72,32 @@ function* documentSteps(document: unknown, artifact: ApiContractArtifact) {
return yield* parseApiContractSteps(document, artifact);
}
type OpenApiInput = Extract<
InspectApiContractInput,
{ format: "openapi-json" }
>;
const documentEvidence = (input: OpenApiInput, result: ApiContract): Evidence =>
createEvidence(
{ path: input.path, format: "file", sha256: result.artifact.sha256 },
API_CONTRACT_PROVIDER,
{
operation,
predicateType: "rea.api-contract-inventory",
parameters: {
path: input.path,
format: input.format,
max_file_bytes: input.max_file_bytes,
},
result,
confidence: "observed",
limitations: result.limitations,
locations: [{ kind: "artifact-path", path: input.path }],
},
);
const importDocument = async (
input: Extract<InspectApiContractInput, { format: "openapi-json" }>,
input: OpenApiInput,
bytes: Buffer,
sha256: string,
signal?: AbortSignal,
@@ -86,26 +112,16 @@ const importDocument = async (
}),
signal,
);
if (!parsed.ok) return parsed;
const result = parsed.value;
if (!parsed.ok) {
const partial = apiContractSchema.safeParse(
parsed.error.partialObservation,
);
if (partial.success)
parsed.error.partialObservation = documentEvidence(input, partial.data);
return parsed;
}
return completeProviderEvidence(
createEvidence(
{ path: input.path, format: "file", sha256 },
API_CONTRACT_PROVIDER,
{
operation,
predicateType: "rea.api-contract-inventory",
parameters: {
path: input.path,
format: input.format,
max_file_bytes: input.max_file_bytes,
},
result,
confidence: "observed",
limitations: result.limitations,
locations: [{ kind: "artifact-path", path: input.path }],
},
),
documentEvidence(input, parsed.value),
signal,
);
};
+2
View File
@@ -1,6 +1,7 @@
import type { PartialTaskMeasurement } from "./desktop/taskDifficulty.js";
import type { AppleIpsPartialObservation } from "./native/appleIps.js";
import type { PlaywrightTrace } from "./playwrightTrace/playwrightTrace.js";
import type { ApiContract } from "./apiContract/apiContract.js";
import type { GraphqlContract } from "./apiContract/graphqlContract.js";
import type { SavedAnalysisSnapshotPartialObservation } from "./savedAnalysisSnapshot.js";
import type { AnalysisSettingLimit } from "./analysisSettings.js";
@@ -498,6 +499,7 @@ export type AnalysisPartialObservation =
}
| { readonly kind: "unretained-evidence"; readonly evidence: Evidence }
| { readonly kind: "retained-evidence"; readonly evidence_id: string }
| ApiContract
| GraphqlContract
| PlaywrightTrace
| SavedAnalysisSnapshotPartialObservation
+1 -1
View File
@@ -185,7 +185,7 @@ export const projectApiContractView = (
unknowns:
context.source_coverage.status === "partial"
? [
"Unresolved or malformed declarations limit this inventory; query path-item-references and diagnostics for exact source pointers.",
"This inventory is partial. Inspect limitations for coverage and query path-item-references and diagnostics for any retained source pointers.",
]
: [],
};
@@ -3,6 +3,7 @@ import { readFileSync } from "node:fs";
import { expect, it } from "vitest";
import { apiContractSchema, type ApiContractArtifact } from "./apiContract.js";
import { parseApiContractSteps } from "./parseApiContract.js";
import { AnalysisCancelledError } from "../analysisErrorCore.js";
const artifact: ApiContractArtifact = {
path: "/contract.json",
@@ -305,9 +306,39 @@ it("handles 3.2 QUERY and case-sensitive additional methods, diagnosing invalid
it("bounds expanded identities and source pointers before building a giant row", () => {
const result = parse(
document({ [`/${"a".repeat(1_100_000)}`]: { get: {} } }),
document({
"/retained": { get: {} },
[`/${"a".repeat(1_100_000)}`]: { get: {} },
}),
);
expect(result.ok).toBe(false);
if (!result.ok)
expect(result.error._tag).toBe("AnalysisResourceConstraintError");
if (result.ok) throw new Error("Expected a retained-facts refusal");
expect(result.error._tag).toBe("AnalysisResourceConstraintError");
const partial = apiContractSchema.parse(result.error.partialObservation);
expect(partial.operations.map((row) => row.path)).toEqual(["/retained"]);
expect(partial.source_coverage.status).toBe("partial");
});
it("retains an interpreted path when cancellation interrupts traversal", () => {
const input = document({
"/first": { get: { operationId: "first" } },
"/second": { get: { operationId: "second" } },
});
const steps = parseApiContractSteps(input, artifact);
for (let checkpoint = 0; checkpoint < 3; checkpoint++)
expect(steps.next().done).toBe(false);
const cancellation = new AnalysisCancelledError("inspect_api_contract");
const stopped = steps.throw(cancellation);
if (!stopped.done || stopped.value.ok)
throw new Error("Expected cancellation");
expect(stopped.value.error).toBe(cancellation);
const partial = apiContractSchema.parse(cancellation.partialObservation);
const complete = report(input);
expect(partial.operations).toEqual(complete.operations.slice(0, 1));
expect(partial.summary.operation_slots).toBe(1);
expect(partial.source_coverage).toMatchObject({
status: "partial",
path_entries_examined: 1,
});
expect(complete.source_coverage.status).toBe("complete-within-scope");
});
+72 -39
View File
@@ -1,4 +1,5 @@
import {
AnalysisCancelledError,
AnalysisInputError,
AnalysisResourceConstraintError,
AnalysisUnsupportedTargetError,
@@ -316,14 +317,17 @@ function* pathItem(
return ok(undefined);
}
const completedInventory = (
interface ContractReportContext {
readonly openapi: string;
readonly info: ApiContract["info"];
readonly pathsState: ApiContract["source_coverage"]["paths_state"];
examined: number;
}
const contractReport = (
inventory: ContractInventory,
context: {
openapi: string;
info: ApiContract["info"];
pathsState: ApiContract["source_coverage"]["paths_state"];
examined: number;
},
context: ContractReportContext,
incomplete = false,
): ApiContract => {
const artifact = inventory.artifact;
let declared = 0;
@@ -348,7 +352,9 @@ const completedInventory = (
source_coverage: {
scope: "inline-path-operations",
status:
inventory.references.length > 0 || inventory.diagnostics.length > 0
incomplete ||
inventory.references.length > 0 ||
inventory.diagnostics.length > 0
? "partial"
: "complete-within-scope",
paths_state: context.pathsState,
@@ -358,6 +364,11 @@ const completedInventory = (
duplicate_json_members: "last-value-wins",
},
limitations: [
...(incomplete
? [
"Traversal stopped before the inventory was complete. Counts describe the retained rows.",
]
: []),
"Operations are document declarations, not evidence of runtime implementation, reachability or authorization.",
"Only inline operations under paths are inventoried; callbacks, webhooks, components, servers, parameters, schemas, request/response contracts and security are not analyzed.",
"No reference is resolved, including local fragments. A Path Item reference makes its effective operations unknown; adjacent inline slots are preserved without merging referenced definitions.",
@@ -368,6 +379,32 @@ const completedInventory = (
};
};
function* collectPaths(
sourcePaths: Record<string, unknown>,
inventory: ContractInventory,
context: ContractReportContext,
modern: boolean,
): Generator<void, Result<void, AnalysisError>> {
for (const path in sourcePaths) {
if (!Object.hasOwn(sourcePaths, path) || path.startsWith("x-")) continue;
yield;
context.examined++;
// Reserve expanded pointer/path strings before escaping or building a row.
const admitted = inventory.reserve(512 + path.length * 16);
if (!admitted.ok) return admitted;
const pointer = `/paths/${pointerPart(path)}`;
const read = path.startsWith("/")
? yield* pathItem(sourcePaths[path], { inventory, path, pointer, modern })
: inventory.diagnostic(
"invalid-path-key",
pointer,
"A Paths entry must start with /; it was not interpreted as an endpoint.",
);
if (!read.ok) return read;
}
return ok(undefined);
}
/** Enumerate declarations only; never resolve references, servers, callbacks or runtime expressions. */
export function* parseApiContractSteps(
value: unknown,
@@ -417,36 +454,32 @@ export function* parseApiContractSteps(
);
if (!diagnosed.ok) return diagnosed;
}
let examined = 0;
const sourcePaths = paths ?? {};
for (const path in sourcePaths) {
if (!Object.hasOwn(sourcePaths, path) || path.startsWith("x-")) continue;
yield;
examined++;
// Reserve expanded pointer/path strings before escaping or building a row.
const admitted = inventory.reserve(512 + path.length * 16);
if (!admitted.ok) return admitted;
const pointer = `/paths/${pointerPart(path)}`;
const read = path.startsWith("/")
? yield* pathItem(sourcePaths[path], {
inventory,
path,
pointer,
modern: version[1] === "2",
})
: inventory.diagnostic(
"invalid-path-key",
pointer,
"A Paths entry must start with /; it was not interpreted as an endpoint.",
);
if (!read.ok) return read;
const context: ContractReportContext = {
openapi: root.openapi,
info: info.value,
pathsState,
examined: 0,
};
const interrupted = (error: AnalysisError) => {
const retainedRows =
inventory.operations.length +
inventory.references.length +
inventory.diagnostics.length;
if (retainedRows > 0)
error.retainPartialObservation(contractReport(inventory, context, true));
return err(error);
};
try {
const read = yield* collectPaths(
paths ?? {},
inventory,
context,
version[1] === "2",
);
if (!read.ok) return interrupted(read.error);
} catch (cause: unknown) {
if (cause instanceof AnalysisCancelledError) return interrupted(cause);
throw cause;
}
return ok(
completedInventory(inventory, {
openapi: root.openapi,
info: info.value,
pathsState,
examined,
}),
);
return ok(contractReport(inventory, context));
}
@@ -615,108 +615,3 @@ it("keeps a valid comparison selected for the wrong claim kind as caller input",
});
}
});
describe("retained reconstruction source coverage", () => {
const omittedTerminalCapture = {
...EMPTY_PROCESS_CAPTURE_EXAMPLE,
truncated: true,
truncation_details: {
...EMPTY_PROCESS_CAPTURE_EXAMPLE.truncation_details,
raw_terminal: {
...EMPTY_PROCESS_CAPTURE_EXAMPLE.truncation_details.raw_terminal,
observed_frames: 1,
observed_bytes: 1,
},
},
};
it("keeps old unchanged terminal and overall claims unknown while retaining unrelated claims", () => {
const left = source("1", "controlled-replay");
const right = source("2", "controlled-replay", "observed", {
captureResult: omittedTerminalCapture,
});
const comparison = processComparison(left, right, processResult());
const bundle = createEvidenceBundle([left, right, comparison]);
const before = JSON.stringify(bundle);
const result = verifyReconstruction(
{
name: "Retained capture coverage",
claims: ["terminal", "overall", "exit", "interaction"].map(
(dimension) => ({
kind: "behavioral",
claim_id: dimension,
title: dimension,
dimension,
comparison_evidence_id: comparison.evidence_id,
}),
),
},
bundle,
);
expect(
result.claims.items.map(({ claim_id, status }) => [claim_id, status]),
).toEqual([
["exit", "pass"],
["interaction", "pass"],
["overall", "unknown"],
["terminal", "unknown"],
]);
expect(
result.claims.items.find(({ claim_id }) => claim_id === "terminal")
?.limitations,
).toContain(
`Source ${right.evidence_id}: terminal observation coverage is incomplete.`,
);
expect(JSON.stringify(bundle)).toBe(before);
});
it("retains a decisive changed claim despite omitted terminal observations", () => {
const left = source("1", "controlled-replay");
const right = source("2", "controlled-replay", "observed", {
captureResult: omittedTerminalCapture,
});
const comparison = processComparison(left, right, processResult("changed"));
const claims = ["terminal", "overall"].map((dimension) => ({
kind: "behavioral",
claim_id: dimension,
title: dimension,
dimension,
comparison_evidence_id: comparison.evidence_id,
}));
expect(
verifyReconstruction(
{ name: "Observed disagreement", claims },
createEvidenceBundle([left, right, comparison]),
),
).toMatchObject({
status: "fail",
summary: { failed: 2, unknown: 0 },
});
});
it.each(["status", "kind"] as const)(
"rejects a summary inconsistent with actual claim %s",
(field) => {
const left = source("1", "controlled-replay");
const right = source("2", "controlled-replay");
const comparison = processComparison(left, right, processResult());
const result = verifyReconstruction(
behavioralSpec(comparison),
createEvidenceBundle([left, right, comparison]),
);
const inconsistent = {
...result,
claims: {
items: result.claims.items.map((claim) =>
field === "status"
? { ...claim, status: "fail", observed_status: "changed" }
: { ...claim, kind: "structural-function" },
),
},
};
expect(
reconstructionVerificationResultSchema.safeParse(inconsistent).success,
).toBe(false);
},
);
});
+5 -66
View File
@@ -15,16 +15,7 @@ import { analysisInputErrorFromIssues } from "./inputIssueProjection.js";
import { readEvidencePayload } from "./evidenceValidation.js";
import { functionDossierSchema } from "./native/functionDossier.js";
import { assessFunctionCallCoverage } from "./functionCallCoverage.js";
import {
processCaptureSchema,
type UnverifiedProcessCapture,
} from "./process/processCapture.js";
import { processSourceTruncated } from "./process/processCaptureCoverage.js";
import {
PROCESS_COMPARISON_DIMENSIONS,
type ProcessComparisonDimension,
} from "./process/processComparison.js";
import type { ProcessObservationSource } from "./process/processObservation.js";
import { processCaptureSchema } from "./process/processCapture.js";
import { digestCanonicalValue } from "./canonicalDigest.js";
import {
reconstructionClaimResultSchema,
@@ -54,14 +45,6 @@ interface FunctionSourceFacts {
readonly callCoverageDiagnostics: readonly string[];
}
interface ValidatedSourceFacts {
readonly functions: readonly FunctionSourceFacts[];
readonly processes: readonly {
readonly evidence_id: string;
readonly capture: UnverifiedProcessCapture;
}[];
}
/** Verify only explicitly declared claims; no global equivalence is inferred. */
export const verifyReconstruction = (
specificationInput: unknown,
@@ -161,18 +144,17 @@ const evaluateClaim = (
);
return source;
});
const sourceFacts = readValidatedSourceFacts(claim, sources);
const functionSourceFacts = readValidatedSourceFacts(claim, sources);
const observation = comparisonObservation(claim, comparison);
const observed = observation.status;
const callCoverage = sourceCallCoverage(
claim,
sourceFacts.functions,
functionSourceFacts,
observation.hasIndependentFunctionChange === true,
);
const blockers = [
...authorityLimitations(claim, sources, sides),
...callCoverage.blockers,
...sourceProcessCoverage(claim, sourceFacts.processes, observed),
];
const relevantUnknowns = reconstructionClaimUnknowns(
heads,
@@ -207,7 +189,7 @@ const evaluateClaim = (
const readValidatedSourceFacts = (
claim: Claim,
sources: readonly Evidence[],
): ValidatedSourceFacts => {
): readonly FunctionSourceFacts[] => {
const isExpectedType = (source: Evidence): boolean => {
if (claim.kind === "behavioral")
return (
@@ -234,7 +216,6 @@ const readValidatedSourceFacts = (
},
);
const functionSources: FunctionSourceFacts[] = [];
const processSources: ValidatedSourceFacts["processes"][number][] = [];
for (const source of sources) {
if (claim.kind === "behavioral") {
const capture = readEvidencePayload(
@@ -242,10 +223,6 @@ const readValidatedSourceFacts = (
source.normalized_result,
);
if (!capture.ok) throw capture.error;
processSources.push({
evidence_id: source.evidence_id,
capture: capture.value,
});
} else if (claim.kind === "structural-function") {
const parsedDossier = readEvidencePayload(
functionDossierSchema,
@@ -279,7 +256,7 @@ const readValidatedSourceFacts = (
}
}
}
return { functions: functionSources, processes: processSources };
return functionSources;
};
const validateComparisonIdentity = (
@@ -427,44 +404,6 @@ const authorityLimitations = (
return limitations;
};
const processObservationSourceByDimension: Readonly<
Record<ProcessComparisonDimension, ProcessObservationSource>
> = {
terminal: "terminal_rendered",
interaction: "interaction",
exit: "lifecycle",
filesystem: "filesystem",
process: "process",
};
const sourceProcessCoverage = (
claim: Claim,
sources: ValidatedSourceFacts["processes"],
observed: ObservedStatus,
): string[] => {
if (
claim.kind !== "behavioral" ||
["changed", "added", "removed", "contradiction"].includes(observed)
)
return [];
const dimensions =
claim.dimension === "overall"
? PROCESS_COMPARISON_DIMENSIONS
: [claim.dimension];
return sources.flatMap(({ evidence_id, capture }) =>
dimensions.flatMap((dimension) =>
processSourceTruncated(
capture,
processObservationSourceByDimension[dimension],
)
? [
`Source ${evidence_id}: ${dimension} observation coverage is incomplete.`,
]
: [],
),
);
};
const sourceCallCoverage = (
claim: Claim,
functionSources: readonly FunctionSourceFacts[],
@@ -118,28 +118,9 @@ export const reconstructionVerificationResultSchema = z
})
.superRefine((result, context) => {
const { summary } = result;
const claims = result.claims.items;
const expectedStatus =
summary.failed > 0 ? "fail" : summary.unknown > 0 ? "unknown" : "pass";
const issues = [
[
summary.passed !==
claims.filter(({ status }) => status === "pass").length ||
summary.failed !==
claims.filter(({ status }) => status === "fail").length ||
summary.unknown !==
claims.filter(({ status }) => status === "unknown").length,
"Claim status counts must summarize retained claims",
["summary"],
],
[
summary.behavioral !==
claims.filter(({ kind }) => kind === "behavioral").length ||
summary.structural !==
claims.filter(({ kind }) => kind !== "behavioral").length,
"Claim kind counts must summarize retained claims",
["summary"],
],
[
summary.total !== summary.passed + summary.failed + summary.unknown,
"Claim status counts must equal the summary total",