rea-agents 0.3.0 → 0.4.0

package/dist/contracts/investigationExamples.js

@@ -0,0 +1,118 @@
+import { compareFunctions } from "../domain/functionComparison.js";
+import { createEvidence } from "../domain/evidence.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { createEvidenceBundle } from "../domain/evidenceBundle.js";
+import { compareProcessCaptures, processCaptureSchema, } from "../domain/processCapture.js";
+import { FUNCTION_COMPARISON_EXAMPLE } from "./functionComparisonExample.js";
+import { EMPTY_PROCESS_CAPTURE_EXAMPLE } from "./processCaptureExample.js";
+const comparison = compareFunctions(FUNCTION_COMPARISON_EXAMPLE.left, FUNCTION_COMPARISON_EXAMPLE.right, 0, 100);
+export const FUNCTION_COMPARISON_EVIDENCE = createEvidence(undefined, {
+    id: "rea-function-comparison",
+    name: "REA function comparison",
+    version: "1",
+}, {
+    predicateType: "rea.function-comparison/v1",
+    operation: "compare_functions",
+    parameters: {
+        left_evidence_ids: [FUNCTION_COMPARISON_EXAMPLE.left.evidence_id],
+        right_evidence_ids: [FUNCTION_COMPARISON_EXAMPLE.right.evidence_id],
+        offset: 0,
+        limit: 100,
+    },
+    result: jsonValueSchema.parse(comparison),
+    confidence: "derived",
+    authority: "analyst-inference",
+    evidenceLinks: [
+        FUNCTION_COMPARISON_EXAMPLE.left.evidence_id,
+        FUNCTION_COMPARISON_EXAMPLE.right.evidence_id,
+    ],
+});
+const PROCESS_PROVIDER = {
+    id: "rea-process",
+    name: "REA deterministic process harness",
+    version: "1",
+};
+const capture = processCaptureSchema.parse(EMPTY_PROCESS_CAPTURE_EXAMPLE);
+const captureEvidence = (scenario) => createEvidence(undefined, PROCESS_PROVIDER, {
+    predicateType: "rea.process-capture/v2",
+    operation: "capture_process_scenario",
+    parameters: { scenario },
+    result: jsonValueSchema.parse(capture),
+    confidence: "observed",
+    authority: "controlled-replay",
+    environment: {
+        id: "fixture-linux",
+        platform: "linux",
+        architecture: "x86_64",
+        isolation: "container",
+    },
+});
+export const PROCESS_CAPTURE_REFERENCE = captureEvidence("reference");
+export const PROCESS_CAPTURE_RECONSTRUCTION = captureEvidence("reconstruction");
+export const PROCESS_COMPARISON_EVIDENCE = createEvidence(undefined, PROCESS_PROVIDER, {
+    predicateType: "rea.process-comparison/v1",
+    operation: "compare_process_captures",
+    parameters: {
+        left_evidence_id: PROCESS_CAPTURE_REFERENCE.evidence_id,
+        right_evidence_id: PROCESS_CAPTURE_RECONSTRUCTION.evidence_id,
+        left_normalization: capture.normalization,
+        right_normalization: capture.normalization,
+    },
+    result: jsonValueSchema.parse(compareProcessCaptures(capture, capture)),
+    confidence: "derived",
+    authority: "analyst-inference",
+    evidenceLinks: [
+        PROCESS_CAPTURE_REFERENCE.evidence_id,
+        PROCESS_CAPTURE_RECONSTRUCTION.evidence_id,
+    ],
+});
+/** Canonical inputs for comparison-composed investigation contracts. */
+export const INVESTIGATION_EXAMPLES = {
+    find_changed_behavior: { comparisons: [FUNCTION_COMPARISON_EVIDENCE] },
+    build_call_path: {
+        functions: [FUNCTION_COMPARISON_EXAMPLE.left],
+        start: { address: "0x1000" },
+        goal: { address: "0x1000" },
+    },
+    correlate_static_and_runtime: {
+        static_comparisons: [FUNCTION_COMPARISON_EVIDENCE],
+        runtime_comparisons: [PROCESS_COMPARISON_EVIDENCE],
+        mappings: [
+            {
+                static: {
+                    comparison_evidence_id: FUNCTION_COMPARISON_EVIDENCE.evidence_id,
+                    selector: { kind: "function", dimension: "pseudocode" },
+                },
+                runtime: {
+                    comparison_evidence_id: PROCESS_COMPARISON_EVIDENCE.evidence_id,
+                    dimension: "terminal",
+                },
+                side_alignment: "left_to_left",
+                hypothesis: {
+                    statement: "Static implementation changed without terminal change.",
+                    expected_pattern: "static_only",
+                },
+            },
+        ],
+    },
+    verify_reconstruction: {
+        specification: {
+            schema_version: 1,
+            name: "Terminal compatibility",
+            claims: [
+                {
+                    kind: "behavioral",
+                    claim_id: "terminal-output",
+                    title: "Terminal output remains equivalent",
+                    comparison_evidence_id: PROCESS_COMPARISON_EVIDENCE.evidence_id,
+                    dimension: "terminal",
+                },
+            ],
+        },
+        evidence_bundle: createEvidenceBundle([
+            PROCESS_CAPTURE_REFERENCE,
+            PROCESS_CAPTURE_RECONSTRUCTION,
+            PROCESS_COMPARISON_EVIDENCE,
+        ]),
+    },
+};

package/dist/contracts/nativeToolContracts.js

@@ -0,0 +1,52 @@
+import { z } from "zod";
+import { nativeOutputSchemas } from "./toolOutputSchemas.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+const examples = {
+    inspect_macho: {},
+    inspect_signature: {},
+    inspect_plist: { relative_path: "Contents/Info.plist" },
+    list_architectures: {},
+    demangle_swift: { symbols: ["$s4Test3fooyyF"] },
+};
+const native = (name, description, inputSchema) => {
+    const outputSchema = nativeOutputSchemas[name];
+    if (outputSchema === undefined)
+        throw new Error(`Missing native output schema for ${name}`);
+    return {
+        name,
+        description,
+        kind: "native-provider",
+        inputSchema,
+        outputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        examples: [
+            {
+                title: `Example ${name.replaceAll("_", " ")} request`,
+                input: z
+                    .record(z.string(), jsonValueSchema)
+                    .parse(examples[name] ?? {}),
+            },
+        ],
+    };
+};
+/** Provider-neutral semantic operations backed initially by macOS utilities. */
+export const NATIVE_TOOL_CONTRACTS = [
+    native("inspect_macho", "Inspect Mach-O slices, load commands, imports, exports, dependencies, build metadata, segments, sections, permissions, and exact command provenance without launching Hopper.", z.object({})),
+    native("inspect_signature", "Inspect the active artifact's code-signing identity, hashes, authorities, requirements, entitlements, hardened-runtime state, and bounded command provenance.", z.object({})),
+    native("inspect_plist", "Parse a plist at a bounded relative path beneath the active artifact container. Symlink and traversal escapes are rejected; output is normalized JSON rather than plutil text.", z.object({
+        relative_path: z
+            .string()
+            .min(1)
+            .max(1_024)
+            .default("Contents/Info.plist"),
+    })),
+    native("list_architectures", "List thin or universal Mach-O slices with offsets, sizes, alignment, explicit coverage, and bounded native-tool provenance.", z.object({})),
+    native("demangle_swift", "Demangle an ordered bounded batch of Swift symbols without requiring Hopper. Each input returns demangled, unchanged, or invalid status.", z.object({
+        symbols: z.array(z.string().min(1).max(4_096)).min(1).max(500),
+    })),
+];

package/dist/contracts/processCaptureExample.js

@@ -0,0 +1,25 @@
+/** Minimal valid process capture used only in public contract examples. */
+export const EMPTY_PROCESS_CAPTURE_EXAMPLE = {
+    schema_version: 2,
+    normalization: {
+        paths: true,
+        pids: true,
+        ports: true,
+        time_bucket_ms: 10,
+        patterns: [],
+    },
+    frames: [],
+    exit: { code: 0, signal: null, reason: "exited" },
+    process_samples: [],
+    protocol_events: [],
+    files_before: [],
+    files_after: [],
+    filesystem_effects: [],
+    truncated: false,
+    limitations: [],
+    residual_unknowns: [],
+    cleanup: {
+        owned_process_group: "verified",
+        temporary_root: "removed",
+    },
+};

package/dist/contracts/toolContractExamples.js

@@ -0,0 +1,69 @@
+import { EMPTY_PROCESS_CAPTURE_EXAMPLE } from "./processCaptureExample.js";
+import { UNKNOWN_CONTRACT_EXAMPLES } from "./unknownContractExamples.js";
+import { ARTIFACT_COMPARISON_EXAMPLE } from "./artifactComparisonExample.js";
+import { FUNCTION_COMPARISON_EXAMPLE } from "./functionComparisonExample.js";
+import { INVESTIGATION_EXAMPLES } from "./investigationExamples.js";
+/** Canonical examples for contracts whose required inputs have no defaults. */
+export const TOOL_EXAMPLE_OVERRIDES = {
+    ...UNKNOWN_CONTRACT_EXAMPLES,
+    ...INVESTIGATION_EXAMPLES,
+    goto_address: { address: "0x1000" },
+    procedure_address: { procedure: "main" },
+    procedure_assembly: { procedure: "main" },
+    procedure_callees: { procedure: "main" },
+    procedure_callers: { procedure: "main" },
+    procedure_info: { procedure: "main" },
+    procedure_references: { procedure: "main" },
+    procedure_pseudo_code: { procedure: "main" },
+    resolve_containing_procedure: { address: "0x1000" },
+    search_procedures: { pattern: "main" },
+    search_strings: { pattern: "authorization failed" },
+    set_address_name: { address: "0x1000", name: "entry" },
+    set_addresses_names: { names: { "0x1000": "entry" } },
+    set_bookmark: { address: "0x1000" },
+    set_comment: { address: "0x1000", comment: "validated entry point" },
+    set_current_document: { document: "fixture" },
+    set_inline_comment: { address: "0x1000", comment: "calls parser" },
+    unset_bookmark: { address: "0x1000" },
+    get_call_graph: { address: "0x1000" },
+    find_xrefs_to_name: { name: "malloc" },
+    analyze_function: { procedure: "main" },
+    trace_feature: { query: "license" },
+    open_binary: { path: "/tmp/fixture" },
+    import_evidence_bundle: { path: "evidence.json" },
+    capture_process_scenario: {
+        approved: true,
+        executable: "/usr/bin/true",
+        working_directory: "/tmp",
+    },
+    compare_process_captures: {
+        left_evidence_id: `ev_${"0".repeat(64)}`,
+        left: EMPTY_PROCESS_CAPTURE_EXAMPLE,
+        right_evidence_id: `ev_${"1".repeat(64)}`,
+        right: EMPTY_PROCESS_CAPTURE_EXAMPLE,
+    },
+    compare_artifacts: ARTIFACT_COMPARISON_EXAMPLE,
+    compare_functions: FUNCTION_COMPARISON_EXAMPLE,
+    compare_bundles: {
+        left: {
+            bundle_version: 2,
+            artifacts: [],
+            providers: [],
+            environments: [],
+            scenarios: [],
+            captures: [],
+            unknowns: [],
+            records: [],
+        },
+        right: {
+            bundle_version: 2,
+            artifacts: [],
+            providers: [],
+            environments: [],
+            scenarios: [],
+            captures: [],
+            unknowns: [],
+            records: [],
+        },
+    },
+};

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,
 ];