feat(analysis): make resource budgets recoverable across CLI and MCP (#9706)

* refactor(analysis): centralize resource budgets and recovery facts

* feat(analysis): expose ASAR and Ghidra runtime admission controls

* feat(artifacts): expose reader admission and preserve limited recognition

* feat(javascript): expose recoverable semantic precision budgets

* feat(web): add recoverable source-map budgets and compact retained views

* feat(web): make historical capture decoding budgets recoverable

* fix(desktop): enforce selected view policies across capture and export

* feat(runtime): make Frida and LLDB retention budgets selectable

* feat(native): expose diagnostic budgets and preserve exhaustion causes

* feat(managed): expose recoverable snapshot and representation budgets

* feat(metadata): make Go and Rust inspection budgets recoverable

* feat(wasm): expose representation and producer admissions

* feat(evm): expose per-call worker resource budgets

* feat(android): make resource and string-pool omissions recoverable

* feat(producers): expose command and recorded-capture budgets

* docs(analysis): record recovery contracts and integrated validation

* fix(docs): link calibration oracle from published verification pages

* fix(docs): restore desktop task anchors and receipt links

* test(analysis): align fixtures with selectable budget contracts

* fix(analysis): remove source-location projector dependency cycle

* test(analysis): refresh budget recovery and verifier regressions

* test(analysis): preserve format and publication recovery expectations

* test(windows): align conformance with owned runtime admission

* fix(desktop): preserve selected alias kinds in exported state

* test(analysis): align provider fixtures with recoverable budgets

* test(desktop): validate emitted alias metadata structurally

* fix(ghidra): classify bounded Windows endpoint refusals

* test(cli): assert selectable artifact admission recovery

* fix(cli): preserve capture provenance in environment builds
This commit is contained in:
morluto authored and GitHub committed 2026-11-10 05:11:20 -05:00
1 parent 55b6d2ca20
commit cb4e5cfbff
515 files changed
+21066 -3637

No files matched your search

+8
View File
@@ -1,3 +1,4 @@
import { projectWebSourceLocationView } from "./webSourceLocationView.js";
import { projectNativeProcedureReferencesView } from "./nativeProcedureReferencesView.js";
import { projectPlaywrightTraceView } from "./playwrightTraceView.js";
import { projectApiContractView } from "./apiContractView.js";
@@ -106,6 +107,9 @@ import {
type InspectAnalysisViewInput,
} from "./analysisViewRequest.js";
import {
webSourceLocationSummaryViewResultSchema,
webSourceLocationMatchesViewResultSchema,
webSourceLocationTextViewResultSchema,
procedurePseudocodeSummaryViewResultSchema,
nativeObservationSummaryViewResultSchemas,
byteEntropySummaryViewResultSchema,
@@ -183,6 +187,9 @@ export {
type AnalysisViewParent,
};
export {
webSourceLocationSummaryViewResultSchema,
webSourceLocationMatchesViewResultSchema,
webSourceLocationTextViewResultSchema,
procedurePseudocodeSummaryViewResultSchema,
nativeObservationSummaryViewResultSchemas,
nativeFeatureTraceSummaryViewResultSchema,
@@ -384,6 +391,7 @@ const retainedViewProjectors = new Map<string, RetainedViewProjector>([
retain("inspect_artifact", projectArtifactInventoryView),
retain("inventory_artifact", projectArtifactInventoryView),
retain("analyze_web_bundle", projectWebBundleView),
retain("trace_web_source_location", projectWebSourceLocationView),
]);
/** Budgets retained across source admission and the selected grouping projection. */
@@ -1,3 +1,4 @@
import { webSourceLocationViewRequestSchema } from "./webSourceLocationView.js";
import { nativeProcedureReferencesViewRequestSchema } from "./nativeProcedureReferencesView.js";
import { graphqlContractViewRequestSchema } from "../apiContract/graphqlContractQuery.js";
import { playwrightTraceViewRequestSchema } from "../playwrightTrace/playwrightTraceQuery.js";
@@ -97,6 +98,7 @@ export const analysisViewRequestSchema = z.discriminatedUnion("kind", [
nativeFeatureTraceViewRequestSchema,
batchDecompileViewRequestSchema,
summaryViewSchema,
webSourceLocationViewRequestSchema,
goBinaryViewRequestSchema,
rustBinaryViewRequestSchema,
desktopViewRequestSchema,
@@ -1,3 +1,10 @@
import {
webSourceLocationViewRequestSchema,
webSourceLocationContextSchema,
webSourceLocationSummarySchema,
webSourceLocationMatchViewSchema,
} from "./webSourceLocationView.js";
import { analysisTextPageItemSchema } from "./analysisViewText.js";
import { graphqlContractViewRequestSchema } from "../apiContract/graphqlContractQuery.js";
import {
graphqlContractViewContextSchema,
@@ -357,6 +364,7 @@ const javascriptSummarySchema = z.strictObject({
const viewResultBase = {
parent_evidence_id: prefixedDigestSchema("ev"),
parent_operation: z.enum([
"trace_web_source_location",
"inspect_python_pyc",
"inspect_erlang_beam",
"inspect_devicetree",
@@ -410,6 +418,30 @@ const summaryViewResultBase = {
...viewResultBase,
} as const;
export const webSourceLocationSummaryViewResultSchema = z.strictObject({
...summaryViewResultBase,
parent_operation: z.literal("trace_web_source_location"),
summary: webSourceLocationSummarySchema,
});
export const webSourceLocationMatchesViewResultSchema = z.strictObject({
...viewResultBase,
kind: z.literal("source-location"),
parent_operation: z.literal("trace_web_source_location"),
view: webSourceLocationViewRequestSchema.options[0],
source_location: webSourceLocationContextSchema,
items: z.array(webSourceLocationMatchViewSchema),
});
export const webSourceLocationTextViewResultSchema = z.strictObject({
...viewResultBase,
kind: z.literal("source-location-text"),
coverage: nullableCollectionViewCoverageSchema,
parent_operation: z.literal("trace_web_source_location"),
view: webSourceLocationViewRequestSchema.options[1],
source_location: webSourceLocationContextSchema,
match: webSourceLocationMatchViewSchema,
item: analysisTextPageItemSchema.nullable(),
});
/** Original selector and text availability without the complete decompiled text. */
export const procedurePseudocodeSummaryViewResultSchema = z.strictObject({
...summaryViewResultBase,
@@ -1332,6 +1364,7 @@ export const analysisViewResultSchema = z.discriminatedUnion("kind", [
view: environmentCoverageViewRequestSchema,
}),
z.discriminatedUnion("parent_operation", [
webSourceLocationSummaryViewResultSchema,
procedurePseudocodeSummaryViewResultSchema,
nativeObservationSummaryViewResultSchema,
nativeValueTraceSummaryViewResultSchema,
@@ -1389,6 +1422,8 @@ export const analysisViewResultSchema = z.discriminatedUnion("kind", [
devicetree: devicetreePageContextSchema,
items: devicetreeViewItemsSchema,
}),
webSourceLocationMatchesViewResultSchema,
webSourceLocationTextViewResultSchema,
erlangBeamTableViewResultSchema,
pythonPycCodeObjectsViewResultSchema,
z.strictObject({
@@ -15,6 +15,7 @@ import { prefixedDigestSchema } from "../digests.js";
import type { ArtifactOccurrence } from "../artifactGraph.js";
import { isImmutableJsonSnapshot } from "../immutableJson.js";
import { z } from "zod";
import { artifactReaderLimitsSchema } from "../artifactReaderLimits.js";
import { AnalysisInputError } from "../analysisErrorCore.js";
import type { AnalysisError } from "../analysisErrorBase.js";
import { uniqueSorted } from "../canonicalOrdering.js";
@@ -93,6 +94,7 @@ export const artifactInventoryItemsSchema = z.array(
);
export const artifactInventorySummarySchema = z.strictObject({
effective_limits: artifactReaderLimitsSchema.exactOptional(),
source_coverage: artifactInventoryCoverageSchema.exactOptional(),
available_hash_status_counts: z
.strictObject({
@@ -333,6 +335,9 @@ export const projectArtifactInventoryView = (
kind: "summary" as const,
view,
summary: {
...(inventory.effectiveLimits === undefined
? {}
: { effective_limits: inventory.effectiveLimits }),
manifest: inventory.manifest,
available_counts: {
nodes: inventory.nodes.length,
+15 -20
View File
@@ -4,10 +4,10 @@ import { z } from "zod";
import {
goBinarySchema,
goBuildInfoSchema,
goMaxStringLiteralsSchema,
goModuleMetadataSchema,
goModuleSchema,
goStringLiteralSchema,
goStringLiteralsSchema,
} from "../go/goBinary.js";
import { err, ok } from "../result.js";
import type { AnalysisViewParent } from "./analysisViewParent.js";
@@ -116,15 +116,9 @@ export const goBinarySummarySchema = z.strictObject({
}),
})
.nullable(),
string_literals: z
.strictObject({
evidence_kind: z.literal("inferred"),
available_count: count,
discovered_count: count,
aggregate_bytes: count,
max_items: goMaxStringLiteralsSchema,
truncated: z.boolean(),
})
string_literals: goStringLiteralsSchema
.omit({ items: true })
.extend({ available_count: count })
.exactOptional(),
});
@@ -227,7 +221,14 @@ export const projectGoBinaryView = (
runtimeUnknown,
]),
};
if (view.kind === "summary")
if (view.kind === "summary") {
let stringSummary: z.output<
typeof goBinarySummarySchema
>["string_literals"];
if (stringLiterals !== undefined) {
const { items, ...facts } = stringLiterals;
stringSummary = { ...facts, available_count: items.length };
}
return ok({
kind: "summary" as const,
view,
@@ -263,21 +264,15 @@ export const projectGoBinaryView = (
},
},
},
...(stringLiterals === undefined
...(stringSummary === undefined
? {}
: {
string_literals: {
evidence_kind: stringLiterals.evidence_kind,
available_count: stringLiterals.items.length,
discovered_count: stringLiterals.discovered_count,
aggregate_bytes: stringLiterals.aggregate_bytes,
max_items: stringLiterals.max_items,
truncated: stringLiterals.truncated,
},
string_literals: stringSummary,
}),
},
coverage: completeWithinViewCoverage(1, 1),
});
}
const indices =
view.indices === undefined ? undefined : new Set(view.indices);
const fields =
+8 -7
View File
@@ -88,6 +88,13 @@ const summarize = (
cyclic_packages: metadata.cyclic_dependency_indices.length,
},
};
let compilerSummary: z.output<
typeof rustBinarySummarySchema
>["rustc_commit"] = null;
if (compiler !== null) {
const { hashes, ...facts } = compiler;
compilerSummary = { ...facts, hashes_count: hashes.length };
}
return {
format: report.format,
architecture: report.architecture,
@@ -98,13 +105,7 @@ const summarize = (
: { selected_slice: report.selected_slice }),
bytes: artifact.bytes,
auditable_metadata: section,
rustc_commit:
compiler === null
? null
: {
evidence_kind: compiler.evidence_kind,
hashes_count: compiler.hashes.length,
},
rustc_commit: compilerSummary,
};
};
@@ -0,0 +1,317 @@
import { z } from "zod";
import {
webSourceLocationResultSchema,
webSourceMapMatchSchema,
} from "../webSourceLocation.js";
import {
MAX_SOURCE_MAP_ENCODED_BYTES,
sourceMapLimitsSchema,
} from "../sourceMapLimits.js";
import { jsonValueByteLength } from "../jsonValueByteLength.js";
import type { JsonValue } from "../jsonValue.js";
import { AnalysisResourceConstraintError } from "../analysisErrorCore.js";
import { err, ok } from "../result.js";
import {
createAnalysisViewResultReader,
type AnalysisViewParent,
} from "./analysisViewParent.js";
import {
ownedView,
type AdmittedView,
type SummaryAnalysisView,
} from "./analysisViewShape.js";
import { analysisViewInputError } from "./analysisViewErrors.js";
import {
boundedViewMessages,
pageViewCoverage,
unavailableViewCoverage,
} from "./analysisViewCoverage.js";
import { analysisTextPage } from "./analysisViewText.js";
const DEFAULT_PAGE_BYTES = 1024 * 1024;
const DEFAULT_MATCH_LIMIT = 64;
const DEFAULT_TEXT_LIMIT = 1024;
const viewByteSchema = sourceMapLimitsSchema.shape.output_bytes.unwrap();
const page = {
kind: z.literal("source-location"),
offset: z.int().nonnegative().default(0),
max_bytes: viewByteSchema
.default(DEFAULT_PAGE_BYTES)
.describe(
`Serialized selected-view byte allowance; default ${String(DEFAULT_PAGE_BYTES)}. Independent of complete Evidence and MCP delivery limits.`,
),
};
export const webSourceLocationViewRequestSchema = z.discriminatedUnion(
"collection",
[
z.strictObject({
...page,
collection: z.literal("matches"),
limit: z.int().positive().default(DEFAULT_MATCH_LIMIT),
}),
z.strictObject({
...page,
collection: z.literal("source-text"),
match_index: z.int().nonnegative(),
limit: z.int().positive().default(DEFAULT_TEXT_LIMIT),
}),
],
);
const generated = webSourceMapMatchSchema.options[0];
const mapped = webSourceMapMatchSchema.options[1];
const content = z.discriminatedUnion("state", [
mapped.shape.content.options[0]
.omit({ text: true })
.extend({ code_units: z.int().nonnegative() }),
mapped.shape.content.options[1],
]);
export const webSourceLocationMatchViewSchema = z.discriminatedUnion("state", [
generated.extend({ match_index: z.int().nonnegative() }),
mapped
.omit({ content: true })
.extend({ match_index: z.int().nonnegative(), content }),
]);
export const webSourceLocationContextSchema = webSourceLocationResultSchema
.omit({ matches: true, limitations: true, diagnostics: true })
.extend({
match_count: z.int().nonnegative(),
diagnostic_count: z.int().nonnegative(),
});
export const webSourceLocationSummarySchema =
webSourceLocationContextSchema.extend({
matches: z.array(webSourceLocationMatchViewSchema),
});
export const webSourceLocationCompleteDeliveryShape = {
detail: z.literal("complete").optional().default("complete"),
view: z.never().exactOptional(),
};
export const webSourceLocationSummaryDeliveryShape = {
detail: z.literal("summary"),
view: webSourceLocationViewRequestSchema.exactOptional(),
};
export const webSourceLocationDeliverySchema = z.discriminatedUnion("detail", [
z.strictObject(webSourceLocationCompleteDeliveryShape),
z.strictObject(webSourceLocationSummaryDeliveryShape),
]);
const readReport = createAnalysisViewResultReader(
webSourceLocationResultSchema,
);
type Match = z.output<typeof webSourceMapMatchSchema>;
const metadata = (
match: Match,
match_index: number,
): z.output<typeof webSourceLocationMatchViewSchema> => {
if (match.state === "generated-only") return { ...match, match_index };
const { content: sourceContent, ...mappedMatch } = match;
if (sourceContent.state === "unavailable")
return { ...mappedMatch, match_index, content: sourceContent };
const { text, ...identity } = sourceContent;
return {
...mappedMatch,
match_index,
content: { ...identity, code_units: text.length },
};
};
const tooLarge = (maxBytes: number, parentEvidenceId: string) =>
err(
new AnalysisResourceConstraintError(
"inspect_analysis_view",
"memory",
"The selected source-location view exceeds its byte allowance.",
{
max_bytes: maxBytes,
evidence_reference: {
kind: "retained-evidence",
evidence_id: parentEvidenceId,
},
},
{
remediationAction:
maxBytes < MAX_SOURCE_MAP_ENCODED_BYTES
? `Select a smaller source-location limit or increase view.max_bytes (maximum ${String(MAX_SOURCE_MAP_ENCODED_BYTES)}) and retry this retained parent. A single metadata row may require a larger allowance; complete Evidence remains available for export.`
: "view.max_bytes is already at its supported maximum. Select a smaller source-location limit or export complete parent Evidence; a single metadata row that cannot fit requires export.",
},
),
);
const withinBudget = (value: unknown, maxBytes: number) =>
jsonValueByteLength(
{ ...(value as Record<string, JsonValue>), view_digest: "0".repeat(64) },
maxBytes,
) <= maxBytes;
type Report = z.output<typeof webSourceLocationResultSchema>;
type LocationView = z.output<typeof webSourceLocationViewRequestSchema>;
const viewContext = (parent: AnalysisViewParent, report: Report) => {
const { matches, diagnostics, limitations, ...identity } = report;
const context = {
...identity,
match_count: matches.length,
diagnostic_count: diagnostics.length,
};
const shared = {
parent_evidence_id: parent.evidenceId,
parent_operation: "trace_web_source_location" as const,
parent_digest: parent.evidenceId.slice(3),
artifact: { path: identity.source.path, sha256: identity.source.sha256 },
limitations: boundedViewMessages(
[
...parent.limitations,
...limitations,
"Match pages preserve retained lookup alternatives; exhausting a page does not establish execution or deployment authenticity. Complete map text and diagnostics remain in parent Evidence.",
],
parent.evidenceId,
"limitations",
),
unknowns: [] as string[],
};
return { shared, context };
};
type Context = ReturnType<typeof viewContext>;
const projectSourceText = (
{ shared, context }: Context,
matches: readonly Match[],
view: Extract<LocationView, { collection: "source-text" }>,
) => {
const match = matches[view.match_index];
if (match === undefined)
return err(
analysisViewInputError([
{
path: ["view", "match_index"],
reason: "invalid_value",
message: "No match exists at this original match index.",
},
]),
);
const selected = metadata(match, view.match_index);
if (match.state === "generated-only" || match.content.state !== "embedded") {
const result = {
...shared,
kind: "source-location-text" as const,
view,
source_location: context,
match: selected,
item: null,
coverage: unavailableViewCoverage(),
};
return withinBudget(result, view.max_bytes)
? ok(result)
: tooLarge(view.max_bytes, shared.parent_evidence_id);
}
const selectedUnits = Math.min(
view.limit,
Math.max(0, match.content.text.length - view.offset),
);
// Each retained UTF-16 unit needs at least one JSON byte. Refuse before copying a huge selected range; exact escaping is checked below.
if (selectedUnits + 2 > view.max_bytes)
return tooLarge(view.max_bytes, shared.parent_evidence_id);
// Text is already bounded and retained by the parent admission. Check serialized expansion before Evidence cloning/encoding.
const text = analysisTextPage(
match.content.text,
view.offset,
view.limit,
"Source text",
);
if (!text.ok) return text;
const result = {
...shared,
kind: "source-location-text" as const,
view,
source_location: context,
match: selected,
...text.value,
};
return withinBudget(result, view.max_bytes)
? ok(result)
: tooLarge(view.max_bytes, shared.parent_evidence_id);
};
const projectMatches = (
{ shared, context }: Context,
matches: readonly Match[],
view: SummaryAnalysisView | Extract<LocationView, { collection: "matches" }>,
) => {
const offset = view.kind === "summary" ? 0 : view.offset;
const limit = view.kind === "summary" ? DEFAULT_MATCH_LIMIT : view.limit;
const maxBytes =
view.kind === "summary" ? DEFAULT_PAGE_BYTES : view.max_bytes;
const items: z.output<typeof webSourceLocationMatchViewSchema>[] = [];
const common = {
...shared,
coverage: pageViewCoverage(offset, 0, matches.length),
};
const build = () =>
view.kind === "summary"
? {
...common,
view,
kind: "summary" as const,
summary: { ...context, matches: items },
}
: {
...common,
view,
kind: "source-location" as const,
source_location: context,
items,
};
const base = build();
// Reserve maximum numeric coverage widths once; row admission remains linear in returned rows.
let bytes = jsonValueByteLength(
{
...base,
view_digest: "0".repeat(64),
coverage: {
...common.coverage,
examined: Number.MAX_SAFE_INTEGER,
next_offset: Number.MAX_SAFE_INTEGER,
},
} as JsonValue,
maxBytes,
);
if (bytes > maxBytes) return tooLarge(maxBytes, shared.parent_evidence_id);
for (
let index = offset;
index < matches.length && items.length < limit;
index++
) {
const item = metadata(matches[index]!, index);
const added =
jsonValueByteLength(item as JsonValue, maxBytes - bytes) +
(items.length === 0 ? 0 : 1);
if (bytes + added > maxBytes) {
if (items.length === 0)
return tooLarge(maxBytes, shared.parent_evidence_id);
break;
}
items.push(item);
bytes += added;
}
common.coverage = pageViewCoverage(offset, items.length, matches.length);
return ok(build());
};
/** Query authenticated source-location facts without reopening any selected artifact. */
export const projectWebSourceLocationView = (
parent: AnalysisViewParent,
admitted: AdmittedView,
) => {
const view = ownedView<
SummaryAnalysisView | z.output<typeof webSourceLocationViewRequestSchema>
>(admitted, "summary", "source-location");
if (view === undefined)
return err(
analysisViewInputError([
{
path: ["view"],
reason: "invalid_value",
message:
"Source-location Evidence supports summary and source-location views.",
},
]),
);
const parsed = readReport(parent);
if (!parsed.ok) return parsed;
const context = viewContext(parent, parsed.value);
return view.kind !== "summary" && view.collection === "source-text"
? projectSourceText(context, parsed.value.matches, view)
: projectMatches(context, parsed.value.matches, view);
};