rea-agents 2.4.0 → 3.0.0

package/dist/application/ReconstructionObligationLedgerProjection.js

@@ -0,0 +1,86 @@
+import { createHash } from "node:crypto";
+import canonicalize from "canonicalize";
+export const obligationLedgerCoverage = (omittedCount, maxObligations, incomplete) => ({
+    status: incomplete ? "partial" : "complete",
+    truncated: omittedCount > 0,
+    omitted_count: omittedCount,
+    max_obligations: maxObligations,
+});
+export const summarizeObligations = (obligations) => ({
+    total: obligations.length,
+    required: obligations.filter(({ required }) => required).length,
+    verified: obligations.filter(({ status }) => status === "verified").length,
+    required_open: obligations.filter(({ required, status }) => required && status !== "verified").length,
+    by_status: countBy(obligations, [
+        "unowned",
+        "characterized",
+        "implemented",
+        "verified",
+        "contradicted",
+        "blocked",
+        "out-of-scope",
+        "unknown",
+    ], ({ status }) => status),
+    by_application_layer: countBy(obligations, [
+        "cli",
+        "protocol",
+        "electron",
+        "persistence",
+        "process",
+        "runtime",
+        "packaging",
+        "native-abi",
+        "application",
+        "other",
+    ], ({ application_layer: layer }) => layer),
+    by_evidence_authority: countBy(obligations, ["candidate", "observed", "reviewed", "unknown"], ({ source_state: state }) => state),
+});
+export const obligationReports = (obligations) => ({
+    missing_owner_obligation_ids: obligationIdsWith(obligations, "missing-owner"),
+    missing_verifier_obligation_ids: obligationIdsWith(obligations, "missing-verifier"),
+    contradicted_obligation_ids: obligationIdsWith(obligations, "contradiction"),
+    residual_unknown_ids: [
+        ...new Set(obligations.flatMap(({ residual_unknown_ids: ids }) => ids)),
+    ].sort(),
+});
+export const obligationLedgerEvidenceLinks = (obligations, manifest) => [
+    ...new Set([
+        ...obligations.flatMap(({ authority_references: references }) => references.map(({ evidence_id: id }) => id)),
+        ...manifest.bindings.flatMap((binding) => [
+            ...binding.original_cases.map(({ evidence_id: id }) => id),
+            ...binding.fixtures.flatMap(({ evidence_ids: ids }) => ids),
+            ...(binding.verifier === null
+                ? []
+                : [binding.verifier.result_evidence_id]),
+        ]),
+        ...manifest.contradictions.flatMap(({ evidence_ids: ids }) => ids),
+    ]),
+].sort();
+export const obligationLedgerStatus = (obligations, omittedCount) => {
+    if (obligations.length === 0)
+        return "unknown";
+    const requiredOpen = obligations.filter(({ required, status }) => required && status !== "verified");
+    if (requiredOpen.some(({ status, diagnostics }) => status === "contradicted" ||
+        hasDiagnostic(diagnostics, "verifier-failed")))
+        return "failed";
+    if (omittedCount > 0 ||
+        requiredOpen.some(({ status }) => status === "unknown"))
+        return "unknown";
+    return requiredOpen.length === 0 ? "ready" : "open";
+};
+export const obligationEdgeOrder = (left, right) => JSON.stringify(left).localeCompare(JSON.stringify(right));
+export const digestObligationLedgerValue = (value) => {
+    const encoded = canonicalize(value);
+    if (encoded === undefined)
+        throw new TypeError("Reconstruction obligation ledger is not canonical JSON");
+    return createHash("sha256").update(encoded).digest("hex");
+};
+const countBy = (items, values, valueFor) => values.map((value) => ({
+    key: value,
+    count: items.filter((item) => valueFor(item) === value).length,
+}));
+const obligationIdsWith = (obligations, code) => obligations
+    .filter(({ diagnostics }) => hasDiagnostic(diagnostics, code))
+    .map(({ obligation_id: id }) => id)
+    .sort();
+const hasDiagnostic = (diagnostics, code) => diagnostics.some((diagnostic) => diagnostic.code === code);

package/dist/application/ReconstructionObligationLedgerService.js

@@ -0,0 +1,72 @@
+import { z } from "zod";
+import { AnalysisInputError, AnalysisProtocolError, } from "../domain/errors.js";
+import { createEvidence } from "../domain/evidence.js";
+import { jsonObjectSchema, jsonValueSchema } from "../domain/jsonValue.js";
+import { reconstructionObligationLedgerInputSchema, reconstructionObligationLedgerPageSchema, } from "../domain/reconstructionObligationLedgerSchemas.js";
+import { err, ok } from "../domain/result.js";
+import { JAVASCRIPT_APPLICATION_WORKFLOW_PROVIDER } from "./InvestigationProviders.js";
+import { deriveReconstructionObligationCandidates } from "./ReconstructionObligationCandidates.js";
+import { evaluateReconstructionObligationLedger } from "./ReconstructionObligationLedgerEvaluation.js";
+const OPERATION = "build_reconstruction_obligation_ledger";
+/** Parse one portable ledger request for both CLI and MCP adapters. */
+export const resolveReconstructionObligationLedgerRequest = (input) => {
+    const parsed = reconstructionObligationLedgerInputSchema.safeParse(input);
+    return parsed.success
+        ? ok(parsed.data)
+        : err(new AnalysisInputError(OPERATION, { cause: parsed.error }));
+};
+/** Build one deterministic ledger page and wrap it in portable Evidence v2. */
+export const buildReconstructionObligationLedgerEvidenceValidated = (input) => {
+    try {
+        const generated = deriveReconstructionObligationCandidates(input.evidence_bundle, input.reviewed_obligations);
+        const ledger = evaluateReconstructionObligationLedger({
+            candidates: generated.candidates,
+            bundle: input.evidence_bundle,
+            manifest: input.manifest,
+            maxObligations: input.limits.max_obligations,
+            generationLimitations: generated.limitations,
+        });
+        const page = pageLedger(ledger, input.page.offset, input.page.limit);
+        return ok(createLedgerEvidence(input, page));
+    }
+    catch (cause) {
+        if (cause instanceof z.ZodError)
+            return err(new AnalysisInputError(OPERATION, { cause }));
+        return err(new AnalysisProtocolError("Reconstruction obligation ledger generation failed", { cause }));
+    }
+};
+const pageLedger = (ledger, offset, limit) => {
+    const obligations = ledger.obligations.slice(offset, offset + limit);
+    const nextOffset = offset + obligations.length < ledger.obligations.length
+        ? offset + obligations.length
+        : null;
+    const { obligations: _allObligations, ...summary } = ledger;
+    return reconstructionObligationLedgerPageSchema.parse({
+        ...summary,
+        page: {
+            offset,
+            limit,
+            total: ledger.obligations.length,
+            returned: obligations.length,
+            next_offset: nextOffset,
+        },
+        obligations,
+    });
+};
+const createLedgerEvidence = (input, page) => createEvidence(undefined, JAVASCRIPT_APPLICATION_WORKFLOW_PROVIDER, {
+    predicateType: "rea.reconstruction-obligation-ledger/v1",
+    operation: OPERATION,
+    parameters: jsonObjectSchema.parse({
+        ledger_id: page.ledger_id,
+        closure_digest: page.closure_digest,
+        limits: input.limits,
+        page: input.page,
+    }),
+    result: jsonValueSchema.parse(page),
+    rawResult: null,
+    confidence: "inferred",
+    authority: "analyst-inference",
+    environment: null,
+    limitations: page.limitations,
+    evidenceLinks: page.evidence_links,
+});

package/dist/application/ReconstructionObligationOriginalCases.js

@@ -0,0 +1,33 @@
+import { evidenceSupportsOriginalAuthority } from "./ReconstructionObligationAuthority.js";
+/** Merge generated and manifest-supplied original observations canonically. */
+export const originalCasesFor = (candidate, binding) => [
+    ...new Map([...candidate.observed_cases, ...(binding?.original_cases ?? [])].map((observed) => [
+        `${observed.kind}:${observed.evidence_id}:${observed.location}`,
+        observed,
+    ])).values(),
+].sort((left, right) => `${left.kind}:${left.evidence_id}:${left.location}`.localeCompare(`${right.kind}:${right.evidence_id}:${right.location}`));
+/** Report original cases that are absent or lack comparable Evidence authority. */
+export const originalCaseDiagnostics = (candidate, binding, evidenceById) => {
+    const diagnostics = [];
+    const originalCases = originalCasesFor(candidate, binding);
+    for (const caseKind of candidate.required_case_kinds) {
+        const cases = originalCases.filter(({ kind }) => kind === caseKind);
+        if (cases.length === 0) {
+            diagnostics.push({
+                code: "missing-original-case",
+                detail: `Original ${caseKind} behavior has not been observed.`,
+            });
+            continue;
+        }
+        if (!cases.some(({ evidence_id: evidenceId }) => {
+            const evidence = evidenceById.get(evidenceId);
+            return (evidence !== undefined &&
+                evidenceSupportsOriginalAuthority(evidence, candidate.required_original_authority));
+        }))
+            diagnostics.push({
+                code: "weak-original-case-authority",
+                detail: `Original ${caseKind} behavior lacks ${candidate.required_original_authority} Evidence.`,
+            });
+    }
+    return diagnostics;
+};

package/dist/application/ReconstructionObligationPolicies.js

@@ -0,0 +1,132 @@
+const APPLICATION_NODE_POLICIES = {
+    package: policy("packaging", "package-lifecycle", "packaged-process", [
+        "positive",
+        "negative",
+        "teardown",
+    ]),
+    installer: policy("packaging", "installer", "packaged-process", [
+        "positive",
+        "negative",
+        "teardown",
+    ]),
+    "context-bridge-api": policy("electron", "context-bridge", "renderer", [
+        "positive",
+        "negative",
+        "malformed",
+    ]),
+    "ipc-channel": policy("electron", "ipc", "renderer", [
+        "positive",
+        "negative",
+        "malformed",
+    ]),
+    "ipc-handler": policy("electron", "ipc", "renderer", [
+        "positive",
+        "negative",
+        "malformed",
+    ]),
+    endpoint: policy("protocol", "endpoint", "protocol", [
+        "positive",
+        "negative",
+        "malformed",
+    ]),
+    storage: policy("persistence", "persistence", "integration", [
+        "positive",
+        "negative",
+        "malformed",
+    ]),
+    worker: policy("process", "worker-lifecycle", "packaged-process", [
+        "positive",
+        "cancellation",
+        "teardown",
+    ]),
+    "service-worker": policy("process", "worker-lifecycle", "packaged-process", [
+        "positive",
+        "cancellation",
+        "teardown",
+    ]),
+    "native-addon": nativePolicy("native-addon"),
+    "native-export": nativePolicy("native-export"),
+    "managed-pinvoke-import": nativePolicy("managed-pinvoke"),
+    "managed-native-implementation": nativePolicy("managed-native"),
+};
+const SEMANTIC_NODE_POLICIES = {
+    "child-process": policy("process", "child-process", "packaged-process", [
+        "positive",
+        "negative",
+        "cancellation",
+        "teardown",
+    ]),
+    stdio: policy("process", "stdio", "packaged-process", [
+        "positive",
+        "negative",
+        "teardown",
+    ]),
+    signal: policy("process", "signal", "packaged-process", [
+        "positive",
+        "cancellation",
+        "teardown",
+    ]),
+    "config-source": parserPolicy("cli", "configuration", "integration"),
+    request: parserPolicy("protocol", "request", "protocol"),
+    response: parserPolicy("protocol", "response", "protocol"),
+    boundary: parserPolicy("application", "parser-boundary", "integration"),
+    resource: policy("persistence", "resource-lifecycle", "integration", [
+        "positive",
+        "negative",
+        "teardown",
+    ]),
+    event: policy("runtime", "event", "packaged-process", [
+        "positive",
+        "negative",
+        "cancellation",
+    ]),
+    timer: policy("runtime", "timer", "packaged-process", [
+        "positive",
+        "cancellation",
+        "teardown",
+    ]),
+    promise: policy("runtime", "promise-ownership", "packaged-process", [
+        "positive",
+        "negative",
+        "cancellation",
+    ]),
+    task: policy("runtime", "task-lifecycle", "packaged-process", [
+        "positive",
+        "cancellation",
+        "teardown",
+    ]),
+};
+export const applicationObligationPolicy = (nodeKind) => APPLICATION_NODE_POLICIES[nodeKind];
+export const semanticObligationPolicy = (nodeKind) => SEMANTIC_NODE_POLICIES[nodeKind];
+function policy(applicationLayer, family, authority, cases) {
+    return {
+        applicationLayer,
+        family,
+        fixtureAuthority: authority,
+        verifierAuthority: authority,
+        originalAuthority: "runtime",
+        cases,
+        requiresParserType: false,
+    };
+}
+function parserPolicy(applicationLayer, family, authority) {
+    return {
+        ...policy(applicationLayer, family, authority, [
+            "positive",
+            "negative",
+            "malformed",
+        ]),
+        requiresParserType: true,
+    };
+}
+function nativePolicy(family) {
+    return {
+        applicationLayer: "native-abi",
+        family,
+        fixtureAuthority: "native-abi",
+        verifierAuthority: "native-abi",
+        originalAuthority: "static",
+        cases: ["positive", "negative"],
+        requiresParserType: false,
+    };
+}

package/dist/application/ReconstructionReadinessService.js

@@ -0,0 +1,48 @@
+import { z } from "zod";
+import { AnalysisInputError, AnalysisProtocolError, } from "../domain/errors.js";
+import { createEvidence } from "../domain/evidence.js";
+import { jsonObjectSchema, jsonValueSchema } from "../domain/jsonValue.js";
+import { createReconstructionReadinessReport } from "../domain/reconstructionReadiness.js";
+import { reconstructionReadinessInputSchema, } from "../domain/reconstructionReadinessSchemas.js";
+import { err, ok } from "../domain/result.js";
+import { JAVASCRIPT_APPLICATION_WORKFLOW_PROVIDER } from "./InvestigationProviders.js";
+const OPERATION = "evaluate_reconstruction_readiness";
+/** Parse one portable readiness request for both CLI and MCP adapters. */
+export const resolveReconstructionReadinessRequest = (input) => {
+    const parsed = reconstructionReadinessInputSchema.safeParse(input);
+    return parsed.success
+        ? ok(parsed.data)
+        : err(new AnalysisInputError(OPERATION, { cause: parsed.error }));
+};
+/** Evaluate and wrap one deterministic readiness report in Evidence v2. */
+export const evaluateReconstructionReadinessValidated = (input) => {
+    try {
+        const report = createReconstructionReadinessReport(input);
+        return ok(createEvidence(undefined, JAVASCRIPT_APPLICATION_WORKFLOW_PROVIDER, {
+            predicateType: "rea.reconstruction-readiness-report/v1",
+            operation: OPERATION,
+            parameters: jsonObjectSchema.parse({
+                source_digest: report.source_digest,
+                expected_source_digest: input.replay.expected_source_digest,
+            }),
+            result: jsonValueSchema.parse(report),
+            rawResult: null,
+            confidence: "inferred",
+            authority: "analyst-inference",
+            environment: null,
+            limitations: report.status === "pass"
+                ? []
+                : [
+                    "Aggregate pass is withheld until every required conformance stage passes.",
+                ],
+            evidenceLinks: report.evidence_links,
+        }));
+    }
+    catch (cause) {
+        if (cause instanceof z.ZodError)
+            return err(new AnalysisInputError(OPERATION, { cause }));
+        return err(new AnalysisProtocolError("Reconstruction readiness evaluation failed", {
+            cause,
+        }));
+    }
+};

package/dist/application/SessionProviderRouter.js

@@ -26,7 +26,7 @@ export class SessionProviderRouter {
                 : (target, resolutionOptions) => provider.resolveAnalysisProfile?.(target, resolutionOptions) ??
                     Promise.resolve(ok({ profile: null, compatibility: {} })));
         return new SessionProviderRouter({
-            kind: "legacy",
+            kind: "single",
             provider,
             identity,
             capabilities,
@@ -61,7 +61,7 @@ export class SessionProviderRouter {
     }
     /** Provider identities exposed through the flat 1.x compatibility field. */
     providerIdentities(route) {
-        if (this.runtime.kind === "legacy") {
+        if (this.runtime.kind === "single") {
             if (route.capabilities === undefined)
                 return [route.identity];
             return uniqueProviderIdentities([...route.capabilities.values()].map(({ provider }) => provider));
@@ -86,7 +86,7 @@ export class SessionProviderRouter {
             compatibility: {},
             binding: null,
             selection: undefined,
-            createClient: (target, context) => createLegacyClient(runtime, target, undefined, context),
+            createClient: (target, context) => createSingleProviderClient(runtime, target, undefined, context),
         };
     }
     /** Resolve target routes before any provider client is created. */
@@ -122,12 +122,12 @@ export class SessionProviderRouter {
             compatibility: normalized.value.compatibility,
             binding: null,
             selection: undefined,
-            createClient: (openedTarget, context) => createLegacyClient(runtime, openedTarget, normalized.value.profile ?? undefined, context),
+            createClient: (openedTarget, context) => createSingleProviderClient(runtime, openedTarget, normalized.value.profile ?? undefined, context),
         });
     }
     /** Candidate status authoritative for the active or target-free route. */
     candidateStatuses(route) {
-        if (this.runtime.kind === "legacy")
+        if (this.runtime.kind === "single")
             return [];
         return route.selection?.candidates ?? this.runtime.registry.candidates();
     }
@@ -160,7 +160,7 @@ const selectableRoute = (auxiliaryProviders, selection) => {
             emptyClient(identity),
     };
 };
-const createLegacyClient = (runtime, target, profile, context) => typeof runtime.provider === "function"
+const createSingleProviderClient = (runtime, target, profile, context) => typeof runtime.provider === "function"
     ? runtime.provider(target, profile, context)
     : runtime.provider.createClient(target, profile, context);
 const emptyClient = (identity) => ({

package/dist/application/SetupClientConfiguration.js

@@ -5,6 +5,7 @@ import { z } from "zod";
 import writeFileAtomic from "write-file-atomic";
 import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
 import { PRODUCT_IDENTITY } from "../identity.js";
+import { MCP_STARTUP_POLICY } from "../mcpStartupPolicy.js";
 import { resolveClientConfigTransactionPath } from "./ClientConfigPath.js";
 const defaultCommand = () => [
     "npx",
@@ -12,7 +13,6 @@ const defaultCommand = () => [
     PRODUCT_IDENTITY.registrationPackageSpecifier,
     "mcp",
 ];
-const CODEX_STARTUP_TIMEOUT_SECONDS = 30;
 /** Back up, atomically update, and semantically read back one JSON MCP configuration. */
 export const configureJsonClient = async (client, environment = {}, command = defaultCommand()) => {
     const transactionPath = await resolveClientConfigTransactionPath(client.configPath);
@@ -214,7 +214,9 @@ const clientConfigurationDesired = (client, providerEnvironment, command) => {
         command: command[0] ?? PRODUCT_IDENTITY.cliBinary,
         args: command.slice(1),
         ...(client.name === "codex"
-            ? { startup_timeout_sec: CODEX_STARTUP_TIMEOUT_SECONDS }
+            ? {
+                startup_timeout_sec: MCP_STARTUP_POLICY.codexStartupTimeoutSeconds,
+            }
             : {}),
         ...(Object.keys(environment).length === 0 ? {} : { env: environment }),
     };

package/dist/application/runtime.js

@@ -1,12 +1,10 @@
-import { BinarySession } from "./BinarySession.js";
 import { HopperProvider } from "../hopper/HopperProvider.js";
 import { GhidraProvider } from "../ghidra/GhidraProvider.js";
-import { NativeMacOSProvider } from "../native/NativeMacOSProvider.js";
-import { ArtifactProvider } from "../artifacts/ArtifactProvider.js";
-import { ManagedStaticProvider } from "../dotnet/ManagedStaticProvider.js";
 import { silentLogger } from "../logger.js";
+import { GENERATED_AUXILIARY_PROVIDERS } from "../generatedMcpToolCatalog.js";
 import { AnalysisProviderRegistry } from "./AnalysisProviderRegistry.js";
-import { SessionProviderRouter } from "./SessionProviderRouter.js";
+import { composeBinarySession } from "./BinarySessionComposition.js";
+import { LazyAnalysisProvider } from "./LazyAnalysisProvider.js";
 /**
  * Compose the target-switching runtime shared directly by CLI and MCP adapters.
  * This is the sole production wiring point, so both adapters share identical
@@ -15,9 +13,28 @@ import { SessionProviderRouter } from "./SessionProviderRouter.js";
 export const createBinarySession = (config, logger = silentLogger) => {
     const hopper = new HopperProvider(config, logger);
     const ghidra = new GhidraProvider(config, logger);
-    return new BinarySession(SessionProviderRouter.selectable(new AnalysisProviderRegistry([hopper, ghidra], config.analysisProvider), [
-        new ArtifactProvider(config.artifactNativeMountEnabled, config.artifactIntegrityContinueEnabled),
-        new NativeMacOSProvider(),
-        new ManagedStaticProvider(),
+    const auxiliary = new Map(GENERATED_AUXILIARY_PROVIDERS.map((provider) => [
+        provider.identity.id,
+        provider,
     ]));
+    const lazyProvider = (id, load) => {
+        const generated = auxiliary.get(id);
+        if (generated === undefined)
+            throw new TypeError(`Missing generated provider metadata for ${id}`);
+        return new LazyAnalysisProvider({ ...generated, load });
+    };
+    return composeBinarySession(new AnalysisProviderRegistry([hopper, ghidra], config.analysisProvider), [
+        lazyProvider("rea-artifact-graph", async () => {
+            const { ArtifactProvider } = await import("../artifacts/ArtifactProvider.js");
+            return new ArtifactProvider(config.artifactNativeMountEnabled, config.artifactIntegrityContinueEnabled);
+        }),
+        lazyProvider("native-macos", async () => {
+            const { NativeMacOSProvider } = await import("../native/NativeMacOSProvider.js");
+            return new NativeMacOSProvider();
+        }),
+        lazyProvider("rea-dotnet-static", async () => {
+            const { ManagedStaticProvider } = await import("../dotnet/ManagedStaticProvider.js");
+            return new ManagedStaticProvider();
+        }),
+    ]);
 };

package/dist/artifacts/ArtifactProvider.js

@@ -1,11 +1,13 @@
 import { createAnalysisExecution, } from "../application/AnalysisProvider.js";
 import { inventoryArtifact } from "../application/ArtifactInventory.js";
 import { extractArtifact } from "../application/ArtifactExtraction.js";
-import { ARTIFACT_TOOL_CONTRACTS, artifactInventoryInputSchema, artifactExtractionInputSchema, } from "../contracts/artifactToolContracts.js";
+import { ARTIFACT_TOOL_CONTRACTS, artifactInspectionInputSchema, artifactInventoryInputSchema, artifactExtractionInputSchema, } from "../contracts/artifactToolContracts.js";
 import { AnalysisCapabilityUnavailableError, ArtifactOperationError, } from "../domain/errors.js";
 import { err, ok } from "../domain/result.js";
 import { ArtifactReaderFailure, } 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 = Object.freeze(ARTIFACT_GRAPH_PROVIDER);
 /** Read-only inventory and exclusively owned extraction provider. */
 export class ArtifactProvider {
@@ -22,7 +24,9 @@ export class ArtifactProvider {
         outputContractVersion: 1,
         available: true,
         reason: null,
-        pagination: "offset",
+        pagination: contract.name === "inspect_artifact"
+            ? "none"
+            : "offset",
         exhaustive: false,
         effects: Object.freeze({
             mutatesArtifact: false,
@@ -68,6 +72,10 @@ class ArtifactClient {
         if (!isArtifactOperation(operation))
             return err(new AnalysisCapabilityUnavailableError(IDENTITY.id, operation, "Operation is not implemented by artifact graph provider."));
         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({
@@ -90,26 +98,7 @@ class ArtifactClient {
                 }));
             }
             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,
                 limitations: result.limitations,
@@ -127,6 +116,82 @@ class ArtifactClient {
     close() {
         return Promise.resolve();
     }
+    async inspectArtifact(parameters, options) {
+        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",
+            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,
+        }));
+    }
+    inventory(parsed, options) {
+        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) => ({
     maxEntries: input.max_entries,