rea-agents 0.3.0 → 0.5.0

package/dist/contracts/toolContracts.js

@@ -1,13 +1,28 @@
 import { z } from "zod";
-import { evidenceBundleSchema } from "../domain/evidenceBundle.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
 import { processCaptureSchema, processScenarioSchema, } from "../domain/processCapture.js";
+import { recordUnknownInputSchema, updateUnknownInputSchema, } from "../domain/residualUnknown.js";
+import { artifactComparisonInputSchema } from "../domain/artifactComparison.js";
+import { functionComparisonInputSchema } from "../domain/functionComparison.js";
+import { bundleComparisonInputSchema } from "../domain/bundleComparison.js";
+import { changedBehaviorInputSchema } from "../domain/changedBehavior.js";
+import { callPathInputSchema } from "../domain/callPath.js";
+import { staticRuntimeCorrelationInputSchema } from "../domain/staticRuntimeCorrelation.js";
+import { reconstructionVerificationInputSchema } from "../domain/reconstructionVerification.js";
 import { enhancedInputSchemas } from "./enhancedInputs.js";
-import { enhancedOutputSchemas, officialOutputSchemas, sessionOutputSchemas, } from "./toolOutputSchemas.js";
+import { enhancedOutputSchemas, officialOutputSchemas, requireOutputSchema, sessionOutputSchemas, } from "./toolOutputSchemas.js";
+import { TOOL_EXAMPLE_OVERRIDES } from "./toolContractExamples.js";
+import { NATIVE_TOOL_CONTRACTS } from "./nativeToolContracts.js";
+import { ARTIFACT_TOOL_CONTRACTS } from "./artifactToolContracts.js";
 const document = z.string().optional().describe("The document name");
 const address = z.string().describe("A Hopper address");
 const optionalAddress = address.optional();
 const procedure = z.string().describe("The procedure name or address");
-const pattern = z.string().describe("The regex pattern to search for");
+const searchPattern = z
+    .string()
+    .min(1)
+    .max(256)
+    .describe("The literal text or bounded regex pattern to search for");
 const caseSensitive = z
     .boolean()
     .default(false)
@@ -16,29 +31,55 @@ const pagination = {
     offset: z.number().int().min(0).default(0),
     limit: z.number().int().min(1).max(500).default(100),
 };
+const searchInput = {
+    pattern: searchPattern,
+    mode: z.enum(["literal", "regex"]).default("literal"),
+    case_sensitive: caseSensitive,
+    offset: z.number().int().min(0).default(0),
+    limit: z.number().int().min(1).max(100).default(100),
+    document,
+};
+const exampleInputSchema = z.record(z.string(), jsonValueSchema);
+const examplesFor = (name, inputSchema) => {
+    const parsed = inputSchema.parse(TOOL_EXAMPLE_OVERRIDES[name] ?? {});
+    return [
+        {
+            title: `Example ${name.replaceAll("_", " ")} request`,
+            input: exampleInputSchema.parse(parsed),
+        },
+    ];
+};
 const annotations = (name, kind) => ({
-    readOnlyHint: kind === "enhanced" ||
-        name === "export_evidence_bundle" ||
-        (!name.startsWith("set_") &&
-            name !== "unset_bookmark" &&
-            name !== "goto_address" &&
-            kind !== "session"),
-    destructiveHint: name === "unset_bookmark" ||
+    readOnlyHint: (kind === "enhanced" && name !== "trace_feature") ||
+        name === "binary_session" ||
+        name === "list_unknowns" ||
+        name === "verify_unknown_resolution",
+    destructiveHint: name === "export_evidence_bundle" ||
+        name === "unset_bookmark" ||
         name === "set_address_name" ||
         name === "set_addresses_names" ||
         name === "set_comment" ||
         name === "set_inline_comment",
-    idempotentHint: true,
-    openWorldHint: false,
-});
-const official = (name, description, inputSchema) => ({
-    name,
-    description,
-    kind: "official-proxy",
-    inputSchema,
-    outputSchema: requireOutputSchema(officialOutputSchemas, name),
-    annotations: annotations(name, "official-proxy"),
+    idempotentHint: name !== "record_unknown" && name !== "update_unknown",
+    openWorldHint: name === "capture_process_scenario",
 });
+const official = (name, description, inputSchema) => {
+    const trackedInputSchema = inputSchema.extend({
+        unknown_registry_approved: z
+            .literal(true)
+            .optional()
+            .describe("Explicit approval to record typed capability unavailability as a residual unknown"),
+    });
+    return {
+        name,
+        description,
+        kind: "official-proxy",
+        inputSchema: trackedInputSchema,
+        outputSchema: requireOutputSchema(officialOutputSchemas, name),
+        annotations: annotations(name, "official-proxy"),
+        examples: examplesFor(name, trackedInputSchema),
+    };
+};
 const enhanced = (name, description, inputSchema) => ({
     name,
     description,
@@ -46,6 +87,7 @@ const enhanced = (name, description, inputSchema) => ({
     inputSchema,
     outputSchema: requireOutputSchema(enhancedOutputSchemas, name),
     annotations: annotations(name, "enhanced"),
+    examples: examplesFor(name, inputSchema),
 });
 const session = (name, description, inputSchema) => ({
     name,
@@ -54,13 +96,8 @@ const session = (name, description, inputSchema) => ({
     inputSchema,
     outputSchema: requireOutputSchema(sessionOutputSchemas, name),
     annotations: annotations(name, "session"),
+    examples: examplesFor(name, inputSchema),
 });
-const requireOutputSchema = (schemas, name) => {
-    const schema = schemas[name];
-    if (schema === undefined)
-        throw new Error(`Missing output schema for ${name}`);
-    return schema;
-};
 /** Bridge operations exposed without additional application composition. */
 export const OFFICIAL_TOOL_CONTRACTS = [
     official("address_name", "Resolve the analyzed name at a code or data address, defaulting to Hopper's current cursor. Use before following a symbol into xrefs; null means Hopper has no name at that address.", z.object({ document, address: optionalAddress })),
@@ -93,8 +130,8 @@ export const OFFICIAL_TOOL_CONTRACTS = [
     })),
     official("procedure_pseudo_code", "Decompile one analyzed procedure by symbol name or hexadecimal address. Returns Hopper pseudocode, not original source, and may return null; request procedure_assembly when instruction precision matters.", z.object({ procedure, document })),
     official("resolve_containing_procedure", "Resolve an arbitrary address, including an xref source or interior instruction, to its Hopper-analyzed containing procedure. A negative result includes an explicit reason and is not guessed from nearby symbols.", z.object({ address, document })),
-    official("search_procedures", "Regex-search all analyzed procedure names with optional case sensitivity. The current bridge returns an unpaginated address/name map, so constrain patterns and use list_procedures for controlled exhaustive traversal.", z.object({ pattern, case_sensitive: caseSensitive, document })),
-    official("search_strings", "Regex-search all analyzed strings with optional case sensitivity. The current bridge is unpaginated and evaluates Python regex, so use narrow patterns and follow matches with xrefs.", z.object({ pattern, case_sensitive: caseSensitive, document })),
+    official("search_procedures", "Search analyzed procedure names using literal matching by default or a structurally bounded regex. Returns a deterministic, offset-paginated page; continue at next_offset while has_more is true.", z.object(searchInput)),
+    official("search_strings", "Search analyzed strings using literal matching by default or a structurally bounded regex. Returns a deterministic, offset-paginated page with explicit value truncation; follow matches with xrefs.", z.object(searchInput)),
     official("set_address_name", "Assign an analyst name to one hexadecimal address and report Hopper's boolean result. This mutates analysis metadata; read it back with address_name before relying on it.", z.object({ address, name: z.string(), document })),
     official("set_addresses_names", "Assign analyst names to an address/name map and return per-address success booleans. This mutates analysis metadata; use for bounded batches and verify failures individually.", z.object({ names: z.record(z.string(), z.string()), document })),
     official("set_bookmark", "Create or replace a bookmark at a hexadecimal address. This mutates navigation metadata; verify with list_bookmarks and do not treat bookmarks as binary evidence.", z.object({ address, name: z.string().optional(), document })),
@@ -115,30 +152,56 @@ export const ENHANCED_TOOL_CONTRACTS = [
     enhanced("find_xrefs_to_name", "Resolve a name through Hopper and return analyzed references to its address. Use when starting from a selector or symbol; resolution failure is returned explicitly and xrefs remain untyped.", enhancedInputSchemas.find_xrefs_to_name),
     enhanced("binary_overview", "Use immediately after opening a target to summarize document, exhaustive procedure/string counts, and a bounded segment sample. detail controls segment fields and limit controls only the returned segment sample.", enhancedInputSchemas.binary_overview),
     enhanced("analyze_function", "Preferred bounded analysis for one procedure symbol or address. Returns identity, pseudocode, optional assembly, comments, calls, incoming references, and blocks; unsupported outgoing references and CFG edges carry explicit unavailable metadata.", enhancedInputSchemas.analyze_function),
-    enhanced("trace_feature", "Trace a bounded literal feature query through matching strings and procedures, xrefs, and truthful containing-procedure resolution. Returns the operation budget, truncation, and residual unknowns; it does not infer reference kinds.", enhancedInputSchemas.trace_feature),
+    enhanced("trace_feature", "Trace a bounded literal feature query through matching strings and procedures, xrefs, and truthful containing-procedure resolution. Returns the operation budget, truncation, and residual unknowns; unknown_registry_approved: true records them durably without inferring reference kinds.", enhancedInputSchemas.trace_feature),
 ];
 /** Target lifecycle tools available only on the long-lived MCP adapter. */
 export const SESSION_TOOL_CONTRACTS = [
-    session("open_binary", "Open a local executable, application bundle, or Hopper database, replacing the active target only after validation. This launches Hopper and may show UI; call binary_overview after success.", z.object({ path: z.string().min(1) })),
-    session("close_binary", "Close the active Hopper-backed target and release its provider process. The operation is idempotent; call binary_session to verify the session is closed.", z.object({})),
-    session("binary_session", "Report whether a target is open and, when open, its canonical path, format, and kind. Use before analysis calls or target switches; this performs no analysis.", z.object({})),
-    session("export_evidence_bundle", "Return the session's deterministic Evidence v2 bundle without clearing it. Records are sorted by evidence ID, and array order carries no investigative meaning.", z.object({})),
-    session("import_evidence_bundle", "Validate and atomically merge a local Evidence v2 bundle supplied as data. Semantic IDs are recomputed; tampering, unsupported versions, conflicts, and ledger overflow reject the entire import.", z.object({ bundle: evidenceBundleSchema })),
-    session("capture_process_scenario", "Run one bounded process under a PTY using operator-approved executable and working roots. Requires approved: true on every call. Captures normalized terminal frames, sampled descendants, filesystem snapshots, and loopback HTTP/WebSocket replay. This launches a process and is disabled unless operator policy enables it; it is not a security sandbox.", processScenarioSchema),
+    session("open_binary", "Open a local executable, application bundle, archive, JavaScript, source map, plist, or Hopper database after validation. Providers start lazily: inventory_artifact does not launch Hopper; deep native operations may show Hopper UI.", z.object({ path: z.string().min(1) })),
+    session("close_binary", "Close the active target and every provider resource started for it. The operation is idempotent; call binary_session to verify the session is closed.", z.object({})),
+    session("binary_session", "Report provider identity, deterministic capability descriptors, and whether a target is open; open targets include canonical path, format, and kind. Use availability, effects, limits, and limitations before selecting analysis operations.", z.object({})),
+    session("export_evidence_bundle", "Return the session's deterministic Evidence v2 bundle, or atomically write it beneath an operator-approved root. Existing files require overwrite: true; records and manifests use canonical byte-stable ordering.", z.object({
+        path: z.string().min(1).optional(),
+        overwrite: z.boolean().default(false),
+    })),
+    session("import_evidence_bundle", "Read a bounded local JSON bundle beneath an operator-approved root, validate every Evidence v2 ID and canonical manifest, then atomically merge it. Imported content is data only and is never executed.", z.object({ path: z.string().min(1) })),
+    session("capture_process_scenario", "Run one bounded process under a PTY using operator-approved executable and working roots. Requires approved: true; unknown_registry_approved: true separately records capture residuals. Captures normalized terminal frames, descendants, filesystem snapshots, and loopback replay. Disabled unless operator policy enables it; not a security sandbox.", processScenarioSchema),
     session("compare_process_captures", "Compare two bounded process captures across terminal, exit, sampled process, filesystem, HTTP, and WebSocket evidence. Missing or truncated observations are never treated as equivalent.", z.object({
         left_evidence_id: z.string().regex(/^ev_[a-f0-9]{64}$/u),
         left: processCaptureSchema,
         right_evidence_id: z.string().regex(/^ev_[a-f0-9]{64}$/u),
         right: processCaptureSchema,
+        unknown_registry_approved: z
+            .literal(true)
+            .optional()
+            .describe("Explicit approval to record capture disagreement durably"),
+    })),
+    session("compare_artifacts", "Compare two bounded sets of inventory_artifact Evidence pages by logical occurrence path, content identity, metadata, and graph relations. Pages must share and satisfy their graph commitment; every delta cites both sets, and gaps yield truncated or unknown, never equivalence.", artifactComparisonInputSchema),
+    session("compare_functions", "Compare two explicit bounded sets of analyze_function Evidence pages across identity, exact provider text, calls, references, strings, and address-normalized CFG topology. Missing or provider-incompatible facets remain truncated or unknown; every conclusion cites both Evidence sets.", functionComparisonInputSchema),
+    session("compare_bundles", "Compare two canonical Evidence v2 bundles by exact record membership, explicit one-to-one observation pairs, and complete residual-unknown revision histories. Missing bundle members describe omission only, never behavioral equivalence; output is digest-anchored and deterministically paginated.", bundleComparisonInputSchema),
+    session("find_changed_behavior", "Aggregate validated process, artifact, and function comparison Evidence into a deterministic change report. Runtime observations remain distinct from static behavior candidates; missing or incomplete comparisons produce unresolved findings, never causal claims.", changedBehaviorInputSchema),
+    session("build_call_path", "Build bounded shortest-first direct-callee paths from explicit analyze_function Evidence groups using exact canonical addresses. Missing dossiers, incomplete callee pages, provider mixing, and depth frontiers remain unknown; every node and edge cites source Evidence.", callPathInputSchema),
+    session("correlate_static_and_runtime", "Evaluate explicit caller-declared hypotheses between exact static comparison findings and runtime comparison dimensions. Similar names or paths are never auto-matched, consistent cochange never proves causality, and unknown or truncated inputs remain unresolved.", staticRuntimeCorrelationInputSchema),
+    session("verify_reconstruction", "Verify a finite typed behavioral and structural specification against a canonical Evidence bundle. Pass means every declared claim has complete comparable authority—not global source equivalence; changed claims fail and missing, limited, or unresolved evidence stays unknown.", reconstructionVerificationInputSchema),
+    session("list_unknowns", "List current residual-unknown heads in deterministic ID order, with optional exact status, severity, and domain filters. This is read-only; unresolved, contradicted, and non-truth dispositions remain distinct.", z.object({
+        status: z
+            .enum(["open", "investigating", "blocked", "contradicted", "resolved"])
+            .optional(),
+        severity: z.enum(["low", "medium", "high", "critical"]).optional(),
+        domain: z.string().trim().min(1).max(100).optional(),
     })),
+    session("record_unknown", "Create one deterministic residual unknown and immutable mutation evidence. Requires approved: true, validates all evidence and relationship references, and rejects duplicate stable identity.", recordUnknownInputSchema),
+    session("update_unknown", "Append one immutable full-state revision and mutation evidence. Requires approved: true and exact expected_revision; stale concurrent writers fail instead of overwriting newer analysis.", updateUnknownInputSchema),
+    session("verify_unknown_resolution", "Revalidate the current residual-unknown head against live bundled evidence, exact authority/confidence/environment requirements, and revision integrity. Withdrawn and out-of-scope dispositions are not truth claims.", z.object({ unknown_id: z.string().regex(/^unk_[a-f0-9]{64}$/u) })),
 ];
 /**
  * Complete ordered public inventory used by registration and verification.
- * Keep this collection at 50 tools unless a deliberate contract change updates
+ * Keep this collection at 68 tools unless a deliberate contract change updates
  * snapshots, package verification, and real-Hopper verification together.
  */
 export const TOOL_CONTRACTS = [
     ...OFFICIAL_TOOL_CONTRACTS,
     ...ENHANCED_TOOL_CONTRACTS,
+    ...NATIVE_TOOL_CONTRACTS,
+    ...ARTIFACT_TOOL_CONTRACTS,
     ...SESSION_TOOL_CONTRACTS,
 ];

package/dist/contracts/toolOutputSchemas.js

@@ -1,21 +1,92 @@
 import { z } from "zod";
 import { evidenceSchema } from "../domain/evidence.js";
-import { processCaptureSchema } from "../domain/processCapture.js";
+import { processCaptureComparisonSchema, processCaptureSchema, } from "../domain/processCapture.js";
 import { evidenceBundleSchema } from "../domain/evidenceBundle.js";
-const resultOf = (schema) => evidenceSchema.omit({ result: true }).extend({ result: schema });
+import { residualUnknownSchema } from "../domain/residualUnknown.js";
+import { functionDossierSchema } from "../domain/hopperValues.js";
+import { demangleSwiftSchema, inspectMachoSchema, inspectPlistSchema, inspectSignatureSchema, listArchitecturesSchema, } from "../domain/nativeInspection.js";
+import { artifactExtractionResultSchema, artifactInventoryResultSchema, } from "../domain/artifactGraph.js";
+import { artifactComparisonResultSchema } from "../domain/artifactComparison.js";
+import { functionComparisonResultSchema } from "../domain/functionComparison.js";
+import { bundleComparisonResultSchema } from "../domain/bundleComparison.js";
+import { changedBehaviorResultSchema } from "../domain/changedBehavior.js";
+import { callPathResultSchema } from "../domain/callPath.js";
+import { staticRuntimeCorrelationResultSchema } from "../domain/staticRuntimeCorrelation.js";
+import { reconstructionVerificationResultSchema } from "../domain/reconstructionVerification.js";
+const resultOf = (schema) => evidenceSchema
+    .omit({ normalized_result: true })
+    .extend({ normalized_result: schema });
 const lifecycleResultOf = (schema) => z.object({ result: schema });
-const comparisonStatus = z.enum([
-    "unchanged",
-    "added",
-    "removed",
-    "changed",
-    "truncated",
-    "unknown",
+/** Resolve a required named output schema or reject contract drift. */
+export const requireOutputSchema = (schemas, name) => {
+    const schema = schemas[name];
+    if (schema === undefined)
+        throw new Error(`Missing output schema for ${name}`);
+    return schema;
+};
+const targetFormatSchema = z.enum([
+    "hopper",
+    "mach-o",
+    "elf",
+    "pe",
+    "zip",
+    "ipa",
+    "apk",
+    "asar",
+    "dmg",
+    "pkg",
+    "plist",
+    "javascript",
+    "source-map",
+]);
+const targetKindSchema = z.enum([
+    "executable",
+    "database",
+    "archive",
+    "artifact",
 ]);
+const providerCapability = z.object({
+    operation: z.string(),
+    available: z.boolean(),
+    reason: z.string().nullable(),
+    input_contract_version: z.number().int().min(1),
+    output_contract_version: z.number().int().min(1),
+    pagination: z.enum(["none", "offset", "cursor"]),
+    exhaustive: z.boolean(),
+    effects: z.object({
+        mutates_artifact: z.boolean(),
+        launches_process: z.boolean(),
+        may_show_ui: z.boolean(),
+        may_access_network: z.boolean(),
+        may_write_filesystem: z.boolean(),
+        changes_permissions: z.boolean(),
+        requires_root: z.boolean(),
+    }),
+    limits: z.object({
+        max_results: z.number().int().min(0).nullable(),
+        max_payload_bytes: z.number().int().min(0).nullable(),
+        timeout_ms: z.number().int().min(0).nullable(),
+    }),
+    limitations: z.array(z.string()),
+});
+const providerIdentity = z.object({
+    id: z.string(),
+    name: z.string(),
+    version: z.string().nullable(),
+});
+const sessionProvider = z.object({
+    provider: providerIdentity,
+    providers: z.array(providerIdentity),
+    capabilities: z.array(providerCapability),
+});
 const nullableText = z.string().nullable();
 const addressList = z.array(z.string());
 const addressedEntry = z.object({ address: z.string(), name: z.string() });
 const procedureIdentity = z.object({ address: z.string(), name: z.string() });
+const localVariable = z.object({
+    description: z.string(),
+    provenance: z.literal("hopper-public-python-api"),
+});
 const containingProcedureResolution = z.discriminatedUnion("found", [
     z.object({
         query_address: z.string(),
@@ -48,22 +119,31 @@ const pageOutput = z.object({
     next_offset: z.number().int().min(0).nullable(),
     has_more: z.boolean(),
 });
-const segmentOutput = resultOf(z.array(z.object({
+const searchPageOutput = pageOutput.extend({
+    items: z.array(z.object({
+        address: z.string(),
+        value: z.string(),
+        value_truncated: z.boolean(),
+    })),
+});
+const memoryRegionOutput = z.object({
     name: z.string(),
     start: z.string(),
     end: z.string(),
+    readable: z.boolean().nullable(),
     writable: z.boolean().nullable(),
     executable: z.boolean().nullable(),
     permissions: unavailable,
-    sections: z.array(z.object({ name: z.string(), start: z.string(), end: z.string() })),
-})));
+    provenance: z.literal("hopper-public-python-api"),
+});
+const segmentOutput = resultOf(z.array(memoryRegionOutput.extend({ sections: z.array(memoryRegionOutput) })));
 const procedureInfoOutput = resultOf(z.object({
     name: z.string(),
     entrypoint: z.string(),
     basicblock_count: z.number().int().min(0),
     length: z.number().min(0),
     signature: nullableText,
-    locals: z.array(z.json()),
+    locals: z.array(localVariable),
 }));
 const symbolDiscoveryOutput = (property) => resultOf(z.object({
     count: z.number().int().min(0),
@@ -73,54 +153,7 @@ const graphNode = z.union([
     z.object({ address: z.string(), calls: z.array(z.string()) }),
     z.object({ address: z.string(), error: z.string() }),
 ]);
-const referenceEdge = z.object({
-    source_address: z.string(),
-    target_address: z.string(),
-    source_procedure: procedureIdentity.nullable(),
-    target_procedure: procedureIdentity.nullable(),
-    kind: unavailable,
-});
-const referencedValue = z.object({
-    address: z.string(),
-    value: z.string(),
-    source_address: z.string(),
-});
-const functionDossierOutput = resultOf(z.object({
-    procedure: z.object({
-        address: z.string(),
-        name: z.string(),
-        signature: nullableText,
-        locals: z.array(z.json()),
-    }),
-    pseudocode: z.object({
-        text: z.string(),
-        total_chars: z.number().int().min(0),
-        returned_chars: z.number().int().min(0),
-        truncated: z.boolean(),
-        next_offset: z.number().int().min(0).nullable(),
-    }),
-    assembly: bounded(z.string()),
-    comments: bounded(z.object({
-        address: z.string(),
-        kind: z.enum(["comment", "inline"]),
-        text: z.string(),
-    })),
-    callers: bounded(procedureIdentity),
-    callees: bounded(procedureIdentity),
-    incoming_references: bounded(referenceEdge),
-    outgoing_references: bounded(referenceEdge),
-    referenced_strings: bounded(referencedValue),
-    referenced_names: bounded(referencedValue),
-    basic_blocks: bounded(z.object({
-        start: z.string(),
-        end: z.string(),
-        successors: z.array(z.string()),
-    })),
-    instruction_scan: z.object({
-        scanned: z.number().int().min(0),
-        truncated: z.boolean(),
-    }),
-}));
+const functionDossierOutput = resultOf(functionDossierSchema);
 /** Exact structured-content schemas for the direct Hopper operations. */
 export const officialOutputSchemas = {
     address_name: resultOf(nullableText),
@@ -158,8 +191,8 @@ export const officialOutputSchemas = {
     })),
     procedure_pseudo_code: resultOf(nullableText),
     resolve_containing_procedure: resultOf(containingProcedureResolution),
-    search_procedures: resultOf(z.record(z.string(), z.string())),
-    search_strings: resultOf(z.record(z.string(), z.string())),
+    search_procedures: resultOf(searchPageOutput),
+    search_strings: resultOf(searchPageOutput),
     set_address_name: resultOf(z.boolean()),
     set_addresses_names: resultOf(z.record(z.string(), z.boolean())),
     set_bookmark: resultOf(z.boolean()),
@@ -223,45 +256,86 @@ export const enhancedOutputSchemas = {
         residual_unknowns: z.array(z.string()),
     })),
 };
+/** Exact Evidence v2 schemas for provider-neutral native inspection. */
+export const nativeOutputSchemas = {
+    inspect_macho: resultOf(inspectMachoSchema),
+    inspect_signature: resultOf(inspectSignatureSchema),
+    inspect_plist: resultOf(inspectPlistSchema),
+    list_architectures: resultOf(listArchitecturesSchema),
+    demangle_swift: resultOf(demangleSwiftSchema),
+};
+/** Exact Evidence v2 schemas for provider-neutral artifact graph operations. */
+export const artifactOutputSchemas = {
+    inventory_artifact: resultOf(artifactInventoryResultSchema),
+    extract_artifact: resultOf(artifactExtractionResultSchema),
+};
 /** Exact structured-content schemas for target lifecycle operations. */
 export const sessionOutputSchemas = {
     open_binary: lifecycleResultOf(z.object({
         path: z.string(),
-        format: z.enum(["hopper", "mach-o", "elf", "pe"]),
-        kind: z.enum(["executable", "database"]),
+        format: targetFormatSchema,
+        kind: targetKindSchema,
         loaderArgs: z.array(z.string()),
         sha256: z.string().regex(/^[a-f0-9]{64}$/u),
         architecture: z.enum(["x86", "x86_64", "arm", "arm64"]).nullable(),
     })),
     close_binary: lifecycleResultOf(z.null()),
     binary_session: lifecycleResultOf(z.union([
-        z.object({ open: z.literal(false) }),
-        z.object({
+        sessionProvider.extend({ open: z.literal(false) }),
+        sessionProvider.extend({
             open: z.literal(true),
             path: z.string(),
-            format: z.enum(["hopper", "mach-o", "elf", "pe"]),
-            kind: z.enum(["executable", "database"]),
+            format: targetFormatSchema,
+            kind: targetKindSchema,
             sha256: z.string().regex(/^[a-f0-9]{64}$/u),
             architecture: z.enum(["x86", "x86_64", "arm", "arm64"]).nullable(),
         }),
     ])),
-    export_evidence_bundle: lifecycleResultOf(evidenceBundleSchema),
+    export_evidence_bundle: lifecycleResultOf(z.union([
+        evidenceBundleSchema,
+        z.object({
+            path: z.string(),
+            bytes: z.number().int().min(0),
+            records: z.number().int().min(0),
+        }),
+    ])),
     import_evidence_bundle: lifecycleResultOf(z.object({
         imported: z.number().int().min(0),
         total: z.number().int().min(0),
     })),
     capture_process_scenario: lifecycleResultOf(evidenceSchema
-        .omit({ result: true })
-        .extend({ result: processCaptureSchema })),
-    compare_process_captures: lifecycleResultOf(evidenceSchema.omit({ result: true }).extend({
-        result: z.object({
-            status: comparisonStatus,
-            terminal: comparisonStatus,
-            exit: comparisonStatus,
-            filesystem: comparisonStatus,
-            protocol: comparisonStatus,
-            process: comparisonStatus,
-            limitations: z.array(z.string()),
-        }),
+        .omit({ normalized_result: true })
+        .extend({ normalized_result: processCaptureSchema })),
+    compare_process_captures: lifecycleResultOf(evidenceSchema.omit({ normalized_result: true }).extend({
+        normalized_result: processCaptureComparisonSchema,
+    })),
+    compare_artifacts: lifecycleResultOf(evidenceSchema.omit({ normalized_result: true }).extend({
+        normalized_result: artifactComparisonResultSchema,
+    })),
+    compare_functions: lifecycleResultOf(evidenceSchema.omit({ normalized_result: true }).extend({
+        normalized_result: functionComparisonResultSchema,
+    })),
+    compare_bundles: lifecycleResultOf(evidenceSchema.omit({ normalized_result: true }).extend({
+        normalized_result: bundleComparisonResultSchema,
+    })),
+    find_changed_behavior: lifecycleResultOf(evidenceSchema.omit({ normalized_result: true }).extend({
+        normalized_result: changedBehaviorResultSchema,
+    })),
+    build_call_path: lifecycleResultOf(evidenceSchema.omit({ normalized_result: true }).extend({
+        normalized_result: callPathResultSchema,
+    })),
+    correlate_static_and_runtime: lifecycleResultOf(evidenceSchema.omit({ normalized_result: true }).extend({
+        normalized_result: staticRuntimeCorrelationResultSchema,
+    })),
+    verify_reconstruction: lifecycleResultOf(evidenceSchema.omit({ normalized_result: true }).extend({
+        normalized_result: reconstructionVerificationResultSchema,
+    })),
+    list_unknowns: lifecycleResultOf(z.array(residualUnknownSchema)),
+    record_unknown: lifecycleResultOf(residualUnknownSchema),
+    update_unknown: lifecycleResultOf(residualUnknownSchema),
+    verify_unknown_resolution: lifecycleResultOf(z.object({
+        valid: z.boolean(),
+        truthVerified: z.boolean(),
+        unknown: residualUnknownSchema,
     })),
 };

package/dist/contracts/unknownContractExamples.js

@@ -0,0 +1,33 @@
+/** Exact example inputs for residual-unknown lifecycle contracts. */
+export const UNKNOWN_CONTRACT_EXAMPLES = {
+    list_unknowns: {},
+    record_unknown: {
+        approved: true,
+        question: "Does this branch require an unavailable external service?",
+        severity: "medium",
+        domain: "protocol",
+        required_authority: "controlled-replay",
+        required_confidence: "observed",
+        required_environment: null,
+        recommended_probes: [
+            { operation: "capture_process_scenario", rationale: "Replay branch." },
+        ],
+        relationships: [],
+    },
+    update_unknown: {
+        approved: true,
+        unknown_id: `unk_${"0".repeat(64)}`,
+        expected_revision: 1,
+        status: "investigating",
+        severity: "medium",
+        supporting_evidence_ids: [],
+        contradicting_evidence_ids: [],
+        required_authority: "controlled-replay",
+        required_confidence: "observed",
+        required_environment: null,
+        recommended_probes: [],
+        relationships: [],
+        resolution: null,
+    },
+    verify_unknown_resolution: { unknown_id: `unk_${"0".repeat(64)}` },
+};