feat(artifacts): add provider-neutral inspection

This commit is contained in:
morluto
2026-07-24 13:14:24 +00:00
parent 8e7709d35a
commit d9977286f9
8 changed files with 798 additions and 30 deletions
+8 -2
View File
@@ -40,6 +40,7 @@ import {
workflowAnalysisProfile,
} from "./InvestigationProviders.js";
import type { AnalysisProviderSelector } from "../contracts/providerSelection.js";
import { artifactInspectionResultSchema } from "../domain/artifactInspection.js";
export {
runCapabilityStatus,
@@ -144,7 +145,7 @@ const authorizeAnalysis = async (
);
}
if (
tool === "inventory_artifact" &&
["inventory_artifact", "inspect_artifact"].includes(tool) &&
arguments_.native_mount_approved === true
) {
const result = await authority.authorize(
@@ -155,7 +156,7 @@ const authorizeAnalysis = async (
environment_names: [],
network: "none",
mount: true,
operation_identity: "inventory_artifact:native_mount",
operation_identity: `${tool}:native_mount`,
},
"read",
);
@@ -381,6 +382,11 @@ const executeAnalysisTool = async (input: {
rawResult: result.value.rawResult,
limitations: result.value.limitations,
locations: result.value.locations,
evidenceLinks:
tool === "inspect_artifact"
? artifactInspectionResultSchema.parse(result.value.result)
.evidence_links
: [],
},
);
return { output: evidence, evidence };
+125 -26
View File
@@ -11,6 +11,7 @@ import { inventoryArtifact } from "../application/ArtifactInventory.js";
import { extractArtifact } from "../application/ArtifactExtraction.js";
import {
ARTIFACT_TOOL_CONTRACTS,
artifactInspectionInputSchema,
artifactInventoryInputSchema,
artifactExtractionInputSchema,
type ArtifactToolName,
@@ -28,6 +29,8 @@ import {
type ArtifactLimits,
} from "./ArtifactReader.js";
import { ARTIFACT_GRAPH_PROVIDER } from "../application/InvestigationProviders.js";
import { createEvidence } from "../domain/evidence.js";
import { createArtifactInspection } from "../domain/artifactInspection.js";
const IDENTITY: ProviderIdentity = Object.freeze(ARTIFACT_GRAPH_PROVIDER);
@@ -47,7 +50,10 @@ export class ArtifactProvider implements AnalysisProvider {
outputContractVersion: 1,
available: true as const,
reason: null,
pagination: "offset" as const,
pagination:
contract.name === "inspect_artifact"
? ("none" as const)
: ("offset" as const),
exhaustive: false,
effects: Object.freeze({
mutatesArtifact: false,
@@ -111,6 +117,10 @@ class ArtifactClient implements AnalysisClient {
),
);
try {
if (operation === "inspect_artifact") {
const inspected = await this.inspectArtifact(parameters, options);
return inspected;
}
if (operation === "extract_artifact") {
const parsed = artifactExtractionInputSchema.parse(parameters);
const result = await extractArtifact(
@@ -143,31 +153,7 @@ class ArtifactClient implements AnalysisClient {
);
}
const parsed = artifactInventoryInputSchema.parse(parameters);
const result = await inventoryArtifact(
this.target.sourcePath ?? this.target.path,
limitsFrom(parsed),
{
nodeOffset: parsed.node_offset,
nodeLimit: parsed.node_limit,
occurrenceOffset: parsed.occurrence_offset,
occurrenceLimit: parsed.occurrence_limit,
edgeOffset: parsed.edge_offset,
edgeLimit: parsed.edge_limit,
},
{
...(options?.signal === undefined ? {} : { signal: options.signal }),
nativeMount: {
nativeMountApproved: parsed.native_mount_approved === true,
nativeMountEnabled: this.nativeMountEnabled,
},
integrity: {
mode: parsed.integrity_policy,
approved: parsed.integrity_continue_approved === true,
enabled: this.integrityContinueEnabled,
maxMismatches: parsed.max_integrity_mismatches,
},
},
);
const result = await this.inventory(parsed, options);
return ok(
createAnalysisExecution(result, IDENTITY, {
rawResult: null,
@@ -190,6 +176,119 @@ class ArtifactClient implements AnalysisClient {
close(): Promise<void> {
return Promise.resolve();
}
private async inspectArtifact(
parameters: Readonly<Record<string, JsonValue>>,
options?: ExecutionOptions,
) {
const parsed = artifactInspectionInputSchema.parse(parameters);
const inventoryParameters = artifactInventoryInputSchema.parse({
node_offset: 0,
node_limit: parsed.max_observations,
occurrence_offset: 0,
occurrence_limit: parsed.max_observations,
edge_offset: 0,
edge_limit: parsed.max_relationships,
native_mount_approved: parsed.native_mount_approved,
integrity_policy: parsed.integrity_policy,
integrity_continue_approved: parsed.integrity_continue_approved,
max_integrity_mismatches: parsed.max_integrity_mismatches,
max_entries: parsed.max_entries,
max_total_bytes: parsed.max_total_bytes,
max_entry_bytes: parsed.max_entry_bytes,
max_compression_ratio: parsed.max_compression_ratio,
max_depth: parsed.max_depth,
max_path_bytes: parsed.max_path_bytes,
});
await options?.progress?.report({
phase: "inspect_artifact.inventory",
completed: 0,
total: 1,
message: "inventory substep started",
});
const inventory = await this.inventory(inventoryParameters, options);
const subject = subjectFor(
this.target.sourcePath ?? this.target.path,
inventory.manifest,
);
const locations = inventory.occurrences.items.map(
({ logical_path: path }) => ({
kind: "artifact-path" as const,
path,
}),
);
const inventoryEvidence = createEvidence(subject, IDENTITY, {
operation: "inventory_artifact",
parameters: inventoryParameters,
result: inventory,
rawResult: null,
limitations: inventory.limitations,
locations,
});
const result = createArtifactInspection(inventoryEvidence, parsed);
await options?.progress?.report({
phase: "inspect_artifact.inventory",
completed: 1,
total: 1,
message: "inventory substep completed",
});
return ok(
createAnalysisExecution(result, IDENTITY, {
rawResult: null,
limitations: result.limitations,
subject,
locations,
}),
);
}
private inventory(
parsed: {
readonly node_offset: number;
readonly node_limit: number;
readonly occurrence_offset: number;
readonly occurrence_limit: number;
readonly edge_offset: number;
readonly edge_limit: number;
readonly native_mount_approved: boolean;
readonly integrity_policy: "fail" | "record-and-continue";
readonly integrity_continue_approved: boolean;
readonly max_integrity_mismatches: number;
readonly max_entries: number;
readonly max_total_bytes: number;
readonly max_entry_bytes: number;
readonly max_compression_ratio: number;
readonly max_depth: number;
readonly max_path_bytes: number;
},
options?: ExecutionOptions,
) {
return inventoryArtifact(
this.target.sourcePath ?? this.target.path,
limitsFrom(parsed),
{
nodeOffset: parsed.node_offset,
nodeLimit: parsed.node_limit,
occurrenceOffset: parsed.occurrence_offset,
occurrenceLimit: parsed.occurrence_limit,
edgeOffset: parsed.edge_offset,
edgeLimit: parsed.edge_limit,
},
{
...(options?.signal === undefined ? {} : { signal: options.signal }),
nativeMount: {
nativeMountApproved: parsed.native_mount_approved === true,
nativeMountEnabled: this.nativeMountEnabled,
},
integrity: {
mode: parsed.integrity_policy,
approved: parsed.integrity_continue_approved === true,
enabled: this.integrityContinueEnabled,
maxMismatches: parsed.max_integrity_mismatches,
},
},
);
}
}
const limitsFrom = (input: {
+51
View File
@@ -10,6 +10,12 @@ export const registerArtifactCommands = (
cli: CliInstance,
logger: Logger,
): void => {
registerInventoryCommand(cli, logger);
registerInspectionCommand(cli, logger);
registerExtractionCommand(cli, logger);
};
const registerInventoryCommand = (cli: CliInstance, logger: Logger): void => {
cli.command(CLI_COMMANDS.inventoryArtifact, {
description: "Build a bounded deterministic artifact graph",
args: z.object({
@@ -76,6 +82,9 @@ export const registerArtifactCommands = (
),
),
});
};
const registerExtractionCommand = (cli: CliInstance, logger: Logger): void => {
cli.command(CLI_COMMANDS.extractArtifact, {
description: "Extract explicitly selected artifact occurrences safely",
args: z.object({
@@ -103,3 +112,45 @@ export const registerArtifactCommands = (
),
});
};
const registerInspectionCommand = (cli: CliInstance, logger: Logger): void => {
cli.command(CLI_COMMANDS.inspectArtifact, {
description:
"Inspect one artifact with bounded observations and explicit next probes",
args: z.object({
path: z.string().describe("Application or package path"),
}),
options: z.object({
maxObservations: z
.number()
.int()
.min(1)
.max(500)
.default(100)
.describe("Maximum retained observations"),
maxRelationships: z
.number()
.int()
.min(1)
.max(500)
.default(100)
.describe("Maximum retained derived relationships"),
}),
alias: {
maxObservations: "max-observations",
maxRelationships: "max-relationships",
},
run: ({ args, options }) =>
logCliCommand(logger, "inspect-artifact", () =>
runProviderAnalysis(
args.path,
"inspect_artifact",
{
max_observations: options.maxObservations,
max_relationships: options.maxRelationships,
},
logger,
),
),
});
};
+29
View File
@@ -4,6 +4,7 @@ import type { ToolContract } from "./toolContracts.js";
import { artifactOutputSchemas } from "./toolOutputSchemas.js";
import { jsonValueSchema } from "../domain/jsonValue.js";
import { toolContractMetadata } from "./toolEffects.js";
import { artifactInspectionLimitsSchema } from "../domain/artifactInspection.js";
const pageInput = {
node_offset: z.number().int().min(0).default(0),
@@ -68,9 +69,32 @@ export const artifactExtractionInputSchema = z.object({
...traversalLimitsInput,
});
/** Bounded provider-neutral inspection using one atomic inventory substep. */
export const artifactInspectionInputSchema = z
.object({
native_mount_approved: z.boolean().default(false),
integrity_policy: z.enum(["fail", "record-and-continue"]).default("fail"),
integrity_continue_approved: z.boolean().default(false),
max_integrity_mismatches: z.number().int().min(1).max(100).default(10),
...artifactInspectionLimitsSchema.shape,
...traversalLimitsInput,
})
.superRefine((input, context) => {
if (
input.integrity_policy === "record-and-continue" &&
input.integrity_continue_approved !== true
)
context.addIssue({
code: "custom",
path: ["integrity_continue_approved"],
message: "record-and-continue requires explicit approval",
});
});
const exampleInputSchema = z.record(z.string(), jsonValueSchema);
const examples: Readonly<Record<string, Readonly<Record<string, unknown>>>> = {
inventory_artifact: {},
inspect_artifact: {},
extract_artifact: {
approved: true,
output_root: "/tmp/rea-extracted",
@@ -109,6 +133,11 @@ export const ARTIFACT_TOOL_CONTRACTS = [
"Inventory the active application or package as a deterministic, content-addressed artifact graph. Returns bounded node and edge pages without extracting or mounting by default.",
artifactInventoryInputSchema,
),
artifact(
"inspect_artifact",
"Inspect the active artifact through one bounded, cancellable inventory substep. Returns the full substep Evidence and its ID, observations, derived relationships, hypotheses, contradictions, unexplored branches, limitations, and format-specific next probes. Any substep failure fails the whole call.",
artifactInspectionInputSchema,
),
artifact(
"extract_artifact",
"Extract selected graph artifacts beneath an explicit output root. Requires approval, rejects traversal and symlink escapes, never overwrites, enforces bomb limits, and verifies cleanup.",
+476
View File
@@ -0,0 +1,476 @@
import { createHash } from "node:crypto";
import canonicalize from "canonicalize";
import { z } from "zod";
import {
artifactInventoryResultSchema,
type ArtifactInventoryResult,
} from "./artifactGraph.js";
import { evidenceSchema, parseEvidence, type Evidence } from "./evidence.js";
import { jsonValueSchema } from "./jsonValue.js";
const boundedTextSchema = z.string().min(1).max(4_096);
const evidenceIdSchema = z.string().regex(/^ev_[a-f0-9]{64}$/u);
const artifactIdSchema = z.string().regex(/^art_[a-f0-9]{64}$/u);
const inspectionLimitsSchema = z.strictObject({
max_observations: z.number().int().min(1).max(500).default(100),
max_relationships: z.number().int().min(1).max(500).default(100),
max_hypotheses: z.number().int().min(1).max(100).default(20),
max_unexplored_branches: z.number().int().min(1).max(100).default(20),
max_next_probes: z.number().int().min(1).max(50).default(20),
max_substeps: z.literal(1).default(1),
});
export const artifactInspectionLimitsSchema = inspectionLimitsSchema;
const inspectionObservationSchema = z.strictObject({
observation_id: z.string().regex(/^aio_[a-f0-9]{64}$/u),
kind: z.enum(["root-manifest", "artifact", "occurrence", "integrity"]),
subject: boundedTextSchema,
value: jsonValueSchema,
evidence_id: evidenceIdSchema,
});
const inspectionRelationshipSchema = z.strictObject({
relationship_id: z.string().regex(/^air_[a-f0-9]{64}$/u),
relation: z.enum([
"contains",
"extracts",
"slice-of",
"embeds",
"loads",
"maps-source",
"derived-from",
]),
source_artifact_id: artifactIdSchema,
target_artifact_id: artifactIdSchema,
occurrence_id: z.string().regex(/^occ_[a-f0-9]{64}$/u),
logical_path: boundedTextSchema.nullable(),
evidence_id: evidenceIdSchema,
});
const inspectionHypothesisSchema = z.strictObject({
hypothesis_id: z.string().regex(/^aih_[a-f0-9]{64}$/u),
statement: boundedTextSchema,
confidence: z.enum(["medium", "low"]),
basis_evidence_ids: z.array(evidenceIdSchema).min(1).max(8),
limitation: boundedTextSchema,
});
const inspectionContradictionSchema = z.strictObject({
contradiction_id: z.string().regex(/^aic_[a-f0-9]{64}$/u),
statement: boundedTextSchema,
occurrence_id: z.string().regex(/^occ_[a-f0-9]{64}$/u),
declared_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
observed_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
evidence_id: evidenceIdSchema,
});
const nextProbeSchema = z.strictObject({
operation: z.string().min(1).max(128),
rationale: boundedTextSchema,
authority: z.enum([
"artifact-bytes",
"managed-static-analysis",
"native-analysis-provider",
"ast-static-analysis",
]),
});
const unexploredBranchSchema = z.strictObject({
branch_id: z.string().regex(/^aib_[a-f0-9]{64}$/u),
reason: z.enum([
"page-limit",
"format-specific-analysis-required",
"unknown-format",
]),
detail: boundedTextSchema,
next_probe: nextProbeSchema.nullable(),
evidence_id: evidenceIdSchema,
});
/** Provider-neutral inspection result with its atomic source Evidence. */
export const artifactInspectionResultSchema = z.strictObject({
schema_version: z.literal(1),
inspection_id: z.string().regex(/^ai_[a-f0-9]{64}$/u),
subject: z.strictObject({
manifest_id: z.string().regex(/^agm_[a-f0-9]{64}$/u),
root_artifact_id: artifactIdSchema,
root_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
root_format: z.string().min(1).max(128),
}),
substeps: z
.array(
z.strictObject({
substep_id: z.string().regex(/^ais_[a-f0-9]{64}$/u),
operation: z.literal("inventory_artifact"),
status: z.literal("completed"),
evidence_id: evidenceIdSchema,
evidence: evidenceSchema,
}),
)
.min(1)
.max(1),
observations: z.array(inspectionObservationSchema).max(500),
derived_relationships: z.array(inspectionRelationshipSchema).max(500),
hypotheses: z.array(inspectionHypothesisSchema).max(100),
contradictions: z.array(inspectionContradictionSchema).max(100),
unexplored_branches: z.array(unexploredBranchSchema).max(100),
next_probes: z.array(nextProbeSchema).max(50),
coverage: z.strictObject({
status: z.enum(["complete-within-substeps", "partial", "truncated"]),
substeps_completed: z.literal(1),
observations_retained: z.number().int().min(0),
observations_omitted: z.number().int().min(0),
relationships_retained: z.number().int().min(0),
relationships_omitted: z.number().int().min(0),
hypotheses_retained: z.number().int().min(0),
hypotheses_omitted: z.number().int().min(0),
unexplored_branches_retained: z.number().int().min(0),
unexplored_branches_omitted: z.number().int().min(0),
next_probes_retained: z.number().int().min(0),
next_probes_omitted: z.number().int().min(0),
}),
evidence_links: z.array(evidenceIdSchema).min(1).max(1),
limitations: z.array(boundedTextSchema).max(1_000),
});
export type ArtifactInspectionLimits = z.infer<
typeof artifactInspectionLimitsSchema
>;
export type ArtifactInspectionResult = z.infer<
typeof artifactInspectionResultSchema
>;
/** Project one successful inventory Evidence record into an inspection report. */
export const createArtifactInspection = (
inventoryInput: unknown,
limits: ArtifactInspectionLimits,
): ArtifactInspectionResult => {
const inventoryEvidence = parseInventoryEvidence(inventoryInput);
const inventory = artifactInventoryResultSchema.parse(
inventoryEvidence.normalized_result,
);
const observations = allObservations(
inventory,
inventoryEvidence.evidence_id,
);
const relationships = allRelationships(
inventory,
inventoryEvidence.evidence_id,
);
const hypotheses = allHypotheses(inventory, inventoryEvidence.evidence_id);
const nextProbes = probesFor(inventory);
const branches = allUnexploredBranches(
inventory,
inventoryEvidence.evidence_id,
nextProbes,
);
const retained = {
observations: observations.slice(0, limits.max_observations),
relationships: relationships.slice(0, limits.max_relationships),
hypotheses: hypotheses.slice(0, limits.max_hypotheses),
branches: branches.slice(0, limits.max_unexplored_branches),
probes: nextProbes.slice(0, limits.max_next_probes),
};
const omissions = {
observations: observations.length - retained.observations.length,
relationships: relationships.length - retained.relationships.length,
hypotheses: hypotheses.length - retained.hypotheses.length,
branches: branches.length - retained.branches.length,
probes: nextProbes.length - retained.probes.length,
};
const semantic = {
schema_version: 1 as const,
subject: {
manifest_id: inventory.manifest.manifest_id,
root_artifact_id: inventory.manifest.root_artifact_id,
root_sha256: inventory.manifest.root_sha256,
root_format: inventory.manifest.root_format,
},
substeps: [
{
substep_id: `ais_${digestCanonical({
operation: "inventory_artifact",
evidence_id: inventoryEvidence.evidence_id,
})}`,
operation: "inventory_artifact" as const,
status: "completed" as const,
evidence_id: inventoryEvidence.evidence_id,
evidence: inventoryEvidence,
},
],
observations: retained.observations,
derived_relationships: retained.relationships,
hypotheses: retained.hypotheses,
contradictions: contradictions(inventory, inventoryEvidence.evidence_id),
unexplored_branches: retained.branches,
next_probes: retained.probes,
coverage: {
status: inspectionCoverage(inventory, omissions),
substeps_completed: 1 as const,
observations_retained: retained.observations.length,
observations_omitted: omissions.observations,
relationships_retained: retained.relationships.length,
relationships_omitted: omissions.relationships,
hypotheses_retained: retained.hypotheses.length,
hypotheses_omitted: omissions.hypotheses,
unexplored_branches_retained: retained.branches.length,
unexplored_branches_omitted: omissions.branches,
next_probes_retained: retained.probes.length,
next_probes_omitted: omissions.probes,
},
evidence_links: [inventoryEvidence.evidence_id],
limitations: uniqueSorted([
...inventory.limitations,
"Inspection derives bounded static hypotheses and next probes; it does not execute the artifact or claim format-specific semantics.",
]),
};
return artifactInspectionResultSchema.parse({
...semantic,
inspection_id: `ai_${digestCanonical(semantic)}`,
});
};
const parseInventoryEvidence = (input: unknown): Evidence => {
const evidence = parseEvidence(input);
if (evidence.operation !== "inventory_artifact")
throw new TypeError(
"Artifact inspection substep requires inventory_artifact Evidence",
);
return evidence;
};
const allObservations = (
inventory: ArtifactInventoryResult,
evidenceId: string,
): ArtifactInspectionResult["observations"] => [
observation(
"root-manifest",
inventory.manifest.root_artifact_id,
inventory.manifest,
evidenceId,
),
...inventory.nodes.items.map((node) =>
observation("artifact", node.artifact_id, node, evidenceId),
),
...inventory.occurrences.items.map((occurrence) =>
observation("occurrence", occurrence.occurrence_id, occurrence, evidenceId),
),
...inventory.integrity_contradictions.map((value) =>
observation("integrity", value.contradiction_id, value, evidenceId),
),
];
const observation = (
kind: ArtifactInspectionResult["observations"][number]["kind"],
subject: string,
value: unknown,
evidenceId: string,
): ArtifactInspectionResult["observations"][number] => {
const semantic = {
kind,
subject,
value: jsonValueSchema.parse(value),
evidence_id: evidenceId,
};
return { observation_id: `aio_${digestCanonical(semantic)}`, ...semantic };
};
const allRelationships = (
inventory: ArtifactInventoryResult,
evidenceId: string,
): ArtifactInspectionResult["derived_relationships"] =>
inventory.edges.items.map((edge) => {
const semantic = {
relation: edge.relation,
source_artifact_id: edge.parent_artifact_id,
target_artifact_id: edge.child_artifact_id,
occurrence_id: edge.occurrence_id,
logical_path: edge.logical_path,
evidence_id: evidenceId,
};
return {
relationship_id: `air_${digestCanonical(semantic)}`,
...semantic,
};
});
const allHypotheses = (
inventory: ArtifactInventoryResult,
evidenceId: string,
): ArtifactInspectionResult["hypotheses"] => {
const statements =
inventory.manifest.root_format === "pe"
? [
"The PE artifact may contain managed CLI metadata or native code; inventory bytes alone do not distinguish them.",
]
: ["asar", "javascript-bundle"].includes(inventory.manifest.root_format)
? [
"The artifact may contain a recoverable JavaScript application graph.",
]
: [];
return statements.map((statement) => {
const semantic = {
statement,
confidence: "low" as const,
basis_evidence_ids: [evidenceId],
limitation:
"Format classification proposes a bounded follow-up; it is not semantic proof.",
};
return { hypothesis_id: `aih_${digestCanonical(semantic)}`, ...semantic };
});
};
const contradictions = (
inventory: ArtifactInventoryResult,
evidenceId: string,
): ArtifactInspectionResult["contradictions"] =>
inventory.integrity_contradictions.map((value) => {
const semantic = {
statement: `Declared integrity for ${value.logical_path} contradicts observed bytes.`,
occurrence_id: value.occurrence_id,
declared_sha256: value.declared_sha256,
observed_sha256: value.observed_sha256,
evidence_id: evidenceId,
};
return {
contradiction_id: `aic_${digestCanonical(semantic)}`,
...semantic,
};
});
const probesFor = (
inventory: ArtifactInventoryResult,
): ArtifactInspectionResult["next_probes"] => {
const format = inventory.manifest.root_format;
if (["asar", "javascript-bundle", "directory"].includes(format))
return [
{
operation: "analyze_javascript_application",
rationale:
"Recover bounded JavaScript modules, source maps, Electron boundaries, and application relationships.",
authority: "ast-static-analysis",
},
];
if (format === "pe")
return [
{
operation: "inspect_managed_artifact",
rationale:
"Check execution-free CLI metadata before choosing a deep native provider.",
authority: "managed-static-analysis",
},
{
operation: "open_binary",
rationale:
"Open as native code only when managed inspection reports a native or mixed boundary.",
authority: "native-analysis-provider",
},
];
if (["mach-o", "mach-o-universal", "elf"].includes(format))
return [
{
operation: "open_binary",
rationale:
"Bind one deep native provider before function-level analysis.",
authority: "native-analysis-provider",
},
];
if (format === "plist")
return [
{
operation: "inspect_plist",
rationale: "Parse property-list values without executing the artifact.",
authority: "artifact-bytes",
},
];
return [];
};
const allUnexploredBranches = (
inventory: ArtifactInventoryResult,
evidenceId: string,
nextProbes: ArtifactInspectionResult["next_probes"],
): ArtifactInspectionResult["unexplored_branches"] => {
const pages = [
["nodes", inventory.nodes.next_offset],
["occurrences", inventory.occurrences.next_offset],
["relationships", inventory.edges.next_offset],
] as const;
const branches = pages.flatMap(([collection, nextOffset]) =>
nextOffset === null
? []
: [
branch(
"page-limit",
`${collection} continue at offset ${String(nextOffset)}.`,
null,
evidenceId,
),
],
);
branches.push(
...nextProbes.map((probe) =>
branch(
"format-specific-analysis-required",
`${probe.operation} was not run by provider-neutral artifact inspection.`,
probe,
evidenceId,
),
),
);
if (inventory.manifest.root_format === "unknown")
branches.push(
branch(
"unknown-format",
"Artifact bytes did not match an admitted format classifier.",
null,
evidenceId,
),
);
return branches;
};
const branch = (
reason: ArtifactInspectionResult["unexplored_branches"][number]["reason"],
detail: string,
nextProbe: ArtifactInspectionResult["next_probes"][number] | null,
evidenceId: string,
): ArtifactInspectionResult["unexplored_branches"][number] => {
const semantic = {
reason,
detail,
next_probe: nextProbe,
evidence_id: evidenceId,
};
return { branch_id: `aib_${digestCanonical(semantic)}`, ...semantic };
};
const inspectionCoverage = (
inventory: ArtifactInventoryResult,
omissions: Readonly<Record<string, number>>,
): ArtifactInspectionResult["coverage"]["status"] => {
if (Object.values(omissions).some((count) => count > 0)) return "truncated";
return [
inventory.nodes.next_offset,
inventory.occurrences.next_offset,
inventory.edges.next_offset,
].some((offset) => offset !== null)
? "partial"
: "complete-within-substeps";
};
const digestCanonical = (value: unknown): string => {
const encoded = canonicalize(value);
if (encoded === undefined)
throw new TypeError("Artifact inspection could not canonicalize");
return createHash("sha256").update(encoded).digest("hex");
};
const uniqueSorted = (values: readonly string[]): string[] =>
[...new Set(values)].sort((left, right) =>
left < right ? -1 : left > right ? 1 : 0,
);
+10 -1
View File
@@ -7,6 +7,7 @@ import type { BinaryTarget } from "../domain/binaryTarget.js";
import type { Logger } from "../logger.js";
import { registerEvidenceTools } from "./registerEvidenceTools.js";
import type { PermissionAuthority } from "../application/PermissionAuthority.js";
import { artifactInspectionResultSchema } from "../domain/artifactInspection.js";
/** Register deterministic artifact inventory and safe extraction operations. */
export const registerArtifactTools = (
@@ -19,5 +20,13 @@ export const registerArtifactTools = (
readonly permissionAuthority?: PermissionAuthority;
},
): void => {
registerEvidenceTools(server, analysis, ARTIFACT_TOOL_CONTRACTS, options);
registerEvidenceTools(server, analysis, ARTIFACT_TOOL_CONTRACTS, {
...options,
sourceEvidence: (operation, result) =>
operation === "inspect_artifact"
? artifactInspectionResultSchema
.parse(result)
.substeps.map(({ evidence }) => evidence)
: [],
});
};
+59 -1
View File
@@ -196,6 +196,26 @@ describe("artifact graph MCP integration", () => {
}),
]),
);
const inspected = await client.callTool({
name: "inspect_artifact",
arguments: {
integrity_policy: "record-and-continue",
integrity_continue_approved: true,
},
});
expect(inspected.isError).not.toBe(true);
expect(compactResult(inspected.structuredContent).result).toMatchObject({
contradictions: [
expect.objectContaining({ occurrence_id: expect.any(String) }),
expect.objectContaining({ occurrence_id: expect.any(String) }),
],
substeps: [
expect.objectContaining({
operation: "inventory_artifact",
status: "completed",
}),
],
});
const compared = await client.callTool({
name: "compare_artifacts",
arguments: {
@@ -326,6 +346,44 @@ describe("artifact graph MCP integration", () => {
arguments: { path: archive },
});
expect(opened.isError).not.toBe(true);
const inspected = await client.callTool({
name: "inspect_artifact",
arguments: { max_observations: 1, max_relationships: 1 },
});
expect(inspected.isError).not.toBe(true);
const inspectionResult = compactResult(inspected.structuredContent);
const inspectionEvidence = session.evidenceById(
inspectionResult.evidence_id,
);
if (inspectionEvidence === undefined)
throw new Error("missing inspection Evidence");
const inspection = z
.object({
substeps: z.array(
z.object({
evidence_id: z.string(),
status: z.literal("completed"),
}),
),
coverage: z.object({
status: z.literal("truncated"),
substeps_completed: z.literal(1),
}),
unexplored_branches: z.array(z.object({ reason: z.string() })),
})
.parse(inspectionResult.result);
expect(inspection.substeps).toHaveLength(1);
expect(
session.evidenceById(inspection.substeps[0]?.evidence_id ?? ""),
).toMatchObject({ operation: "inventory_artifact" });
expect(inspectionEvidence.evidence_links).toEqual([
inspection.substeps[0]?.evidence_id,
]);
expect(inspection.unexplored_branches).toEqual(
expect.arrayContaining([
expect.objectContaining({ reason: "page-limit" }),
]),
);
const inventory = await client.callTool({
name: "inventory_artifact",
arguments: {},
@@ -381,7 +439,7 @@ describe("artifact graph MCP integration", () => {
const envelope = z
.object({ result: evidenceBundleSchema })
.parse(exported.structuredContent);
expect(envelope.result.records).toHaveLength(4);
expect(envelope.result.records).toHaveLength(6);
expect(envelope.result.artifacts).toContainEqual({
digest: { sha256: evidence.subject?.digest.sha256 },
format: "ipa",
+40
View File
@@ -23,6 +23,7 @@ import {
} from "../src/artifacts/ArtifactPaths.js";
import {
artifactExtractionInputSchema,
artifactInspectionInputSchema,
artifactInventoryInputSchema,
} from "../src/contracts/artifactToolContracts.js";
import type { BinaryTarget } from "../src/domain/binaryTarget.js";
@@ -34,6 +35,7 @@ import {
artifactExtractionResultSchema,
artifactInventoryResultSchema,
} from "../src/domain/artifactGraph.js";
import { artifactInspectionResultSchema } from "../src/domain/artifactInspection.js";
describe("artifact graph provider", () => {
it("inventories app trees deterministically without following symlinks", async () => {
@@ -124,6 +126,28 @@ describe("artifact graph provider", () => {
provider: { id: "rea-artifact-graph" },
subject: { format: "apk" },
});
const inspectionEvidence = parseEvidence(
await runProviderAnalysis(zipPath, "inspect_artifact", {
max_observations: 2,
max_relationships: 1,
}),
);
const inspection = artifactInspectionResultSchema.parse(
inspectionEvidence.normalized_result,
);
expect(inspection).toMatchObject({
substeps: [
{
operation: "inventory_artifact",
status: "completed",
evidence_id: expect.stringMatching(/^ev_[a-f0-9]{64}$/u),
},
],
coverage: { status: "truncated", substeps_completed: 1 },
});
expect(inspectionEvidence.evidence_links).toEqual(
inspection.evidence_links,
);
const cancellation = new AbortController();
cancellation.abort();
await expect(
@@ -135,6 +159,15 @@ describe("artifact graph provider", () => {
cancellation.signal,
),
).resolves.toMatchObject({ code: "cancelled" });
await expect(
runProviderAnalysis(
zipPath,
"inspect_artifact",
{},
undefined,
cancellation.signal,
),
).resolves.toMatchObject({ code: "cancelled" });
const source = join(root, "asar-source");
await mkdir(source);
@@ -177,6 +210,13 @@ describe("artifact graph provider", () => {
},
},
});
const failedInspection = await new ArtifactProvider()
.createClient(target(unpackedPath, "asar"))
.execute("inspect_artifact", artifactInspectionInputSchema.parse({}));
expect(failedInspection).toMatchObject({
ok: false,
error: { _tag: "ArtifactOperationError", reason: "integrity" },
});
});
it.each([