Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
import {
artifactGraphManifestSchema,
artifactInventoryCoverageSchema,
artifactNodeSchema,
artifactOccurrenceSchema,
artifactEdgeSchema,
integrityContradictionSchema,
} from "../artifactGraph.js";
import { artifactInspectionResultSchema } from "../artifactInspection.js";
import {
artifactFormatMetadataSchema,
type ArtifactFormatMetadata,
} from "../artifactFormatMetadata.js";
import { prefixedDigestSchema } from "../digests.js";
import type { ArtifactOccurrence } from "../artifactGraph.js";
import { isImmutableJsonSnapshot } from "../immutableJson.js";
import { z } from "zod";
import { AnalysisInputError } from "../analysisErrorCore.js";
import type { AnalysisError } from "../analysisErrorBase.js";
import { uniqueSorted } from "../canonicalOrdering.js";
import { err, ok, type Result } from "../result.js";
import {
validateArtifactInventorySubject,
parseArtifactInspectionInventoryResult,
parseArtifactInventoryResult,
ArtifactInventoryValidationError,
type InventorySet,
} from "../artifactInventoryEvidence.js";
import type { ArtifactInspectionResult } from "../artifactInspection.js";
import type {
AnalysisViewParent,
AnalysisViewRequest,
UnsignedAnalysisView,
} from "./analysisView.js";
import {
completeWithinViewCoverage,
pageViewCoverage,
} from "./analysisViewCoverage.js";
import { analysisViewResultInputError } from "./analysisViewParent.js";
const page = {
kind: z.literal("inventory"),
offset: z.number().int().nonnegative().default(0),
limit: z.number().int().positive().default(64),
};
/** Exact selection intersects filters; record identities always survive projection. */
export const artifactInventoryViewRequestSchema = z.discriminatedUnion(
"collection",
[
z.strictObject({
...page,
collection: z.literal("occurrences"),
occurrence_ids: z.array(prefixedDigestSchema("occ")).optional(),
logical_paths: z.array(z.string()).optional(),
entry_kinds: z
.array(artifactOccurrenceSchema.shape.entry_kind)
.optional(),
fields: z.array(artifactOccurrenceSchema.keyof()).optional(),
}),
z.strictObject({
...page,
collection: z.literal("nodes"),
artifact_ids: z.array(prefixedDigestSchema("art")).optional(),
fields: z.array(artifactNodeSchema.keyof()).optional(),
}),
z.strictObject({
...page,
collection: z.enum(["edges", "integrity_contradictions"]),
}),
],
);
export const artifactInventoryItemsSchema = z.array(
z.union([
artifactNodeSchema.partial().required({ artifact_id: true }).strict(),
artifactOccurrenceSchema
.partial()
.required({
occurrence_id: true,
artifact_id: true,
parent_occurrence_id: true,
})
.strict(),
artifactEdgeSchema,
integrityContradictionSchema,
]),
);
export const artifactInventorySummarySchema = z.strictObject({
source_coverage: artifactInventoryCoverageSchema.exactOptional(),
available_hash_status_counts: z
.strictObject({
verified: z.number().int().nonnegative(),
mismatched: z.number().int().nonnegative(),
unavailable: z.number().int().nonnegative(),
"not-hashed": z.number().int().nonnegative(),
})
.exactOptional(),
manifest: artifactGraphManifestSchema,
root_format_metadata: artifactFormatMetadataSchema.exactOptional(),
available_counts: z.strictObject({
nodes: z.number().int().nonnegative(),
occurrences: z.number().int().nonnegative(),
edges: z.number().int().nonnegative(),
integrity_contradictions: z.number().int().nonnegative(),
}),
observed_entry_kind_counts: z.strictObject({
file: z.number().int().nonnegative(),
directory: z.number().int().nonnegative(),
symlink: z.number().int().nonnegative(),
slice: z.number().int().nonnegative(),
metadata: z.number().int().nonnegative().exactOptional(),
}),
source_complete: z.boolean(),
inventory_evidence_ids: z.array(prefixedDigestSchema("ev")).min(1),
inspection: z
.strictObject({
coverage: artifactInspectionResultSchema.shape.coverage,
unexplored_branches:
artifactInspectionResultSchema.shape.unexplored_branches,
})
.nullable(),
limitation_count: z.number().int().nonnegative(),
});
const inputError = (message: string): AnalysisInputError =>
new AnalysisInputError("inspect_analysis_view", undefined, [
{
path: ["source"],
reason: "invalid_value",
message,
},
]);
interface InventoryCounts {
readonly kinds: Readonly<Record<ArtifactOccurrence["entry_kind"], number>>;
readonly hashes: Readonly<Record<ArtifactOccurrence["hash_status"], number>>;
}
interface InventorySource {
readonly inventory: InventorySet;
readonly evidenceIds: readonly string[];
readonly inspection: ArtifactInspectionResult | null;
rootMetadata?: ArtifactFormatMetadata | null;
nodeIndex?: ReadonlyMap<string, number>;
index?: {
byId: ReadonlyMap<string, number>;
byPath: ReadonlyMap<string, readonly number[]>;
byKind: ReadonlyMap<ArtifactOccurrence["entry_kind"], readonly number[]>;
};
counts?: InventoryCounts;
}
/** Reuse the owning inventory integrity/completeness parser for both carriers. */
const checkedSources = new WeakMap<
object,
{ readonly operation: string; readonly source: InventorySource }
>();
const parseSource = (
parent: AnalysisViewParent,
): Result<InventorySource, AnalysisError> => {
const key = parent.normalizedResult;
const reusable =
parent.sealedResult === true &&
typeof key === "object" &&
key !== null &&
isImmutableJsonSnapshot(key);
const cached = reusable ? checkedSources.get(key) : undefined;
if (cached !== undefined && cached.operation === parent.operation) {
try {
validateArtifactInventorySubject(
parent.subject ?? null,
cached.source.inventory.manifest,
);
} catch (cause: unknown) {
return sourceFailure(parent.normalizedResult, cause);
}
return ok(cached.source);
}
const parsed = parseSourceUncached(parent);
if (parsed.ok && reusable)
checkedSources.set(key, {
operation: parent.operation,
source: parsed.value,
});
return parsed;
};
const parseSourceUncached = (
parent: AnalysisViewParent,
): Result<InventorySource, AnalysisError> => {
try {
if (parent.operation === "inventory_artifact")
return ok({
inventory: parseArtifactInventoryResult(
parent.normalizedResult,
parent.subject ?? null,
),
evidenceIds: [],
inspection: null,
});
const parsed = parseArtifactInspectionInventoryResult(
parent.normalizedResult,
parent.subject ?? null,
);
return ok({
inventory: parsed.inventory,
evidenceIds: parsed.evidenceIds,
inspection: parsed.inspection,
});
} catch (cause: unknown) {
return sourceFailure(parent.normalizedResult, cause);
}
};
const sourceFailure = (
input: unknown,
cause: unknown,
): Result<never, AnalysisError> => {
if (cause instanceof z.ZodError)
return err(analysisViewResultInputError(input, cause));
if (!(cause instanceof ArtifactInventoryValidationError)) throw cause;
return err(inputError(cause.message));
};
/** Project exact source records; exhausted pages cover available records, not runtime behavior. */
export const projectArtifactInventoryView = (
parent: AnalysisViewParent,
view: AnalysisViewRequest,
): Result<UnsignedAnalysisView, AnalysisError> => {
const operation = parent.operation;
if (operation !== "inventory_artifact" && operation !== "inspect_artifact")
return err(
inputError(
"Inventory views require inventory_artifact or inspect_artifact Evidence.",
),
);
if (view.kind !== "summary" && view.kind !== "inventory")
return err(
inputError("Artifact Evidence supports summary and inventory views."),
);
const parsed = parseSource(parent);
if (!parsed.ok) return parsed;
const source = parsed.value;
const { inventory, inspection } = source;
const evidenceIds =
inspection === null ? [parent.evidenceId] : source.evidenceIds;
if (source.rootMetadata === undefined)
source.rootMetadata =
inventory.occurrences.find((row) => row.logical_path === ".")
?.format_metadata ?? null;
const rootMetadata = source.rootMetadata;
// Producer traversal coverage is the owner's fact for every format; missing
// coverage would read as unknown, so every view carries it inline.
const sourceCoverage = { source_coverage: inventory.coverage };
const includeHashCounts =
view.kind === "inventory" ||
inventory.manifest.root_format === "godot-pck" ||
inventory.manifest.root_format === "pyinstaller";
const counts = inventoryCounts(source);
const limitations = uniqueSorted([
...parent.limitations,
...inventory.limitations,
...(inspection?.limitations ?? []),
]);
const shared = {
parent_evidence_id: parent.evidenceId,
parent_operation: operation,
parent_digest: parent.evidenceId.slice(3),
artifact: {
path: parent.artifact?.path ?? "",
sha256: inventory.manifest.root_sha256,
},
limitations,
unknowns: [
"Inventory does not establish application runtime behavior or complete format-specific analysis.",
...(inventory.coverage.status === "unknown"
? [
"Producer traversal coverage is unknown; missing matches do not prove source absence.",
]
: []),
...(counts.hashes.unavailable > 0 || counts.hashes["not-hashed"] > 0
? [
"Content hashes are unknown for some recorded files; missing node IDs do not prove content absence.",
]
: []),
...(inventory.complete
? []
: [
"Parent inventory is partial; counts and exhausted pages cover only available records. Missing matches do not establish absence.",
]),
],
} satisfies Pick<
UnsignedAnalysisView,
| "parent_evidence_id"
| "parent_operation"
| "parent_digest"
| "artifact"
| "limitations"
| "unknowns"
>;
if (view.kind === "summary") {
const examined =
inventory.nodes.length +
inventory.occurrences.length +
inventory.edges.length;
return ok({
kind: "summary",
view,
summary: {
manifest: inventory.manifest,
available_counts: {
nodes: inventory.nodes.length,
occurrences: inventory.occurrences.length,
edges: inventory.edges.length,
integrity_contradictions: inventory.integrityContradictions.length,
},
observed_entry_kind_counts: {
file: counts.kinds.file,
directory: counts.kinds.directory,
symlink: counts.kinds.symlink,
slice: counts.kinds.slice,
...(counts.kinds.metadata === 0
? {}
: { metadata: counts.kinds.metadata }),
},
...(includeHashCounts
? { available_hash_status_counts: counts.hashes }
: {}),
source_complete: inventory.complete,
...sourceCoverage,
inventory_evidence_ids: [...evidenceIds],
...(rootMetadata === null
? {}
: { root_format_metadata: rootMetadata }),
inspection:
inspection === null
? null
: {
coverage: inspection.coverage,
unexplored_branches: inspection.unexplored_branches,
},
limitation_count: limitations.length,
},
coverage: completeWithinViewCoverage(examined, examined),
...shared,
});
}
const selected =
view.collection === "occurrences"
? occurrencePage(source, view)
: view.collection === "nodes"
? nodePage(source, view)
: {
items: (view.collection === "edges"
? inventory.edges
: inventory.integrityContradictions
).slice(view.offset, view.offset + view.limit),
total:
view.collection === "edges"
? inventory.edges.length
: inventory.integrityContradictions.length,
};
return ok({
kind: "inventory",
view,
manifest: inventory.manifest,
inventory_evidence_ids: [...evidenceIds],
source_complete: inventory.complete,
...sourceCoverage,
items: selected.items,
coverage: pageViewCoverage(
view.offset,
selected.items.length,
selected.total,
),
...shared,
});
};
const occurrencePage = (source: InventorySource, view: OccurrenceView) => {
const indices = occurrenceIndices(source, view);
const rows = source.inventory.occurrences;
const total = indices?.length ?? rows.length;
const items = [];
for (
let at = view.offset;
at < Math.min(total, view.offset + view.limit);
at++
)
items.push(selectOccurrenceFields(rows[indices?.[at] ?? at]!, view.fields));
return { items, total };
};
const nodePage = (
source: InventorySource,
view: Extract<
AnalysisViewRequest,
{ kind: "inventory"; collection: "nodes" }
>,
) => {
const indices = nodeIndices(source, view.artifact_ids);
const rows = source.inventory.nodes;
const total = indices?.length ?? rows.length;
const items = [];
for (
let at = view.offset;
at < Math.min(total, view.offset + view.limit);
at++
) {
const row = rows[indices?.[at] ?? at]!;
items.push(
view.fields === undefined
? row
: { ...selectFields(row, view.fields), artifact_id: row.artifact_id },
);
}
return { items, total };
};
const inventoryCounts = (source: InventorySource): InventoryCounts => {
if (source.counts !== undefined) return source.counts;
const kinds = { file: 0, directory: 0, symlink: 0, slice: 0, metadata: 0 };
const hashes = {
verified: 0,
mismatched: 0,
unavailable: 0,
"not-hashed": 0,
};
for (const occurrence of source.inventory.occurrences) {
kinds[occurrence.entry_kind]++;
if (occurrence.entry_kind === "file" || occurrence.entry_kind === "slice")
hashes[occurrence.hash_status]++;
}
source.counts = Object.freeze({
kinds: Object.freeze(kinds),
hashes: Object.freeze(hashes),
});
return source.counts;
};
type OccurrenceView = Extract<
AnalysisViewRequest,
{ kind: "inventory"; collection: "occurrences" }
>;
/** Index authenticated facts only when an exact lookup is requested. */
const occurrenceIndices = (
source: InventorySource,
view: OccurrenceView,
): number[] | undefined => {
if (
view.occurrence_ids === undefined &&
view.logical_paths === undefined &&
view.entry_kinds === undefined
)
return undefined;
if (
view.occurrence_ids?.length === 0 ||
view.logical_paths?.length === 0 ||
view.entry_kinds?.length === 0
)
return [];
if (source.index === undefined) {
const byId = new Map<string, number>();
const byPath = new Map<string, number[]>();
const byKind = new Map<ArtifactOccurrence["entry_kind"], number[]>();
for (const [index, row] of source.inventory.occurrences.entries()) {
byId.set(row.occurrence_id, index);
const existing = byPath.get(row.logical_path);
if (existing === undefined) byPath.set(row.logical_path, [index]);
else existing.push(index);
const kind = byKind.get(row.entry_kind);
if (kind === undefined) byKind.set(row.entry_kind, [index]);
else kind.push(index);
}
source.index = { byId, byPath, byKind };
}
const lookup = source.index;
const paths =
view.logical_paths === undefined ? undefined : new Set(view.logical_paths);
const selected =
view.occurrence_ids === undefined
? paths === undefined
? [...new Set(view.entry_kinds)].flatMap(
(kind) => lookup.byKind.get(kind) ?? [],
)
: [...paths].flatMap((path) => lookup.byPath.get(path) ?? [])
: [...new Set(view.occurrence_ids)].flatMap((id) => {
const index = lookup.byId.get(id);
return index === undefined ||
(paths !== undefined &&
!paths.has(source.inventory.occurrences[index]!.logical_path))
? []
: [index];
});
const kinds =
view.entry_kinds === undefined ? undefined : new Set(view.entry_kinds);
return selected
.filter(
(index) =>
kinds === undefined ||
kinds.has(source.inventory.occurrences[index]!.entry_kind),
)
.sort((left, right) => left - right);
};
const nodeIndices = (
source: InventorySource,
ids: string[] | undefined,
): number[] | undefined => {
if (ids === undefined) return undefined;
if (ids.length === 0) return [];
const byId = (source.nodeIndex ??= new Map(
source.inventory.nodes.map((row, index) => [row.artifact_id, index]),
));
return [...new Set(ids)]
.flatMap((id) => {
const index = byId.get(id);
return index === undefined ? [] : [index];
})
.sort((left, right) => left - right);
};
const selectFields = <Row extends object>(
row: Row,
fields: (keyof Row)[] | undefined,
): Partial<Row> => {
if (fields === undefined) return row;
const selected: Partial<Row> = {};
for (const field of fields) {
const value = row[field];
if (value !== undefined) selected[field] = value;
}
return selected;
};
/** Parent linkage and content identity survive even an explicitly empty field set. */
const selectOccurrenceFields = (
row: ArtifactOccurrence,
fields: OccurrenceView["fields"],
) =>
fields === undefined
? row
: {
...selectFields(row, fields),
occurrence_id: row.occurrence_id,
artifact_id: row.artifact_id,
parent_occurrence_id: row.parent_occurrence_id,
};