rea-agents 6.4.0 → 6.5.0

package/dist/contracts/reconstructionReadinessExample.js

@@ -1,6 +1,7 @@
 import { createEvidence } from "../domain/evidence.js";
 import { createEvidenceBundle } from "../domain/evidenceBundle.js";
 import { READINESS_REQUIRED_CHECKS, READINESS_STAGE_IDS, } from "../domain/reconstructionReadinessJourneyFindings.js";
+import { reconstructionObligationLedgerClosureDigest } from "../domain/reconstructionObligationLedgerIntegrity.js";
 const HASH = "a".repeat(64);
 const sourceEvidence = (variant) => createEvidence(undefined, {
     id: "rea-readiness-fixture",
@@ -59,6 +60,129 @@ const EVIDENCE_STATES = [
     "reviewed",
     "unknown",
 ];
+const READINESS_OBLIGATION_LEDGER = (() => {
+    const ledger = {
+        schema: "ReconstructionObligationLedger",
+        ledger_id: `rol_${HASH}`,
+        status: "ready",
+        coverage: {
+            status: "complete",
+        },
+        summary: {
+            total: 1,
+            required: 1,
+            verified: 1,
+            required_open: 0,
+            by_status: STATUSES.map((key) => ({
+                key,
+                count: key === "verified" ? 1 : 0,
+            })),
+            by_application_layer: LAYERS.map((key) => ({
+                key,
+                count: key === "process" ? 1 : 0,
+            })),
+            by_evidence_authority: EVIDENCE_STATES.map((key) => ({
+                key,
+                count: key === "observed" ? 1 : 0,
+            })),
+        },
+        reports: {
+            missing_owner_obligation_ids: [],
+            missing_verifier_obligation_ids: [],
+            contradicted_obligation_ids: [],
+            residual_unknown_ids: [],
+        },
+        ownership_graph: [
+            {
+                obligation_id: "obl.readiness",
+                module_path: "src/readiness.ts",
+                symbol: "runReadiness",
+            },
+        ],
+        dependency_graph: [],
+        obligations: [
+            {
+                obligation_id: "obl.readiness",
+                obligation_version: 1,
+                title: "Preserve the packaged readiness fixture lifecycle",
+                origin: "reviewed",
+                application_layer: "process",
+                family: "packaged-process-lifecycle",
+                target: {
+                    artifact_sha256: HASH,
+                    application_node_id: null,
+                    semantic_node_id: null,
+                    location: "/fixture",
+                },
+                authority_references: [
+                    {
+                        evidence_id: EVIDENCE_ID,
+                        authority: "controlled-replay",
+                        state: "observed",
+                        location: "/fixture",
+                    },
+                ],
+                source_state: "observed",
+                observed_cases: CASES.map((kind) => ({
+                    kind,
+                    evidence_id: EVIDENCE_ID,
+                    location: `/original/${kind}`,
+                })),
+                required: true,
+                required_case_kinds: [...CASES],
+                required_original_authority: "process",
+                required_fixture_authority: "packaged-process",
+                required_verifier_authority: "packaged-process",
+                requires_parser_type: false,
+                dependency_obligation_ids: [],
+                residual_unknown_ids: [],
+                unavailable_authority: [],
+                required_next_evidence: [],
+                binding: {
+                    obligation_id: "obl.readiness",
+                    owner: {
+                        module_path: "src/readiness.ts",
+                        symbol: "runReadiness",
+                        owner_sha256: HASH,
+                    },
+                    parser_type: null,
+                    original_cases: CASES.map((kind) => ({
+                        kind,
+                        evidence_id: EVIDENCE_ID,
+                        location: `/original/${kind}`,
+                    })),
+                    fixtures: CASES.map((kind) => ({
+                        fixture_id: `fixture.${kind}`,
+                        case_kind: kind,
+                        authority: "packaged-process",
+                        evidence_ids: [EVIDENCE_ID],
+                    })),
+                    verifier: {
+                        verifier_id: "verifier.readiness",
+                        claim_id: "claim.readiness",
+                        command: "npm run verify:readiness",
+                        authority: "packaged-process",
+                        status: "pass",
+                        result_evidence_id: EVIDENCE_ID,
+                        enumerated_obligation_ids: ["obl.readiness"],
+                        nondeterminism: {
+                            mode: "partial-order",
+                            specification: "Startup precedes teardown.",
+                        },
+                    },
+                },
+                status: "verified",
+                diagnostics: [],
+            },
+        ],
+        evidence_links: [EVIDENCE_ID],
+        limitations: [],
+    };
+    return {
+        ...ledger,
+        closure_digest: reconstructionObligationLedgerClosureDigest(ledger),
+    };
+})();
 /** Complete synthetic input shared by docs, tests, CLI, MCP, and verifier. */
 export const RECONSTRUCTION_READINESS_EXAMPLE = {
     identity: {
@@ -206,124 +330,7 @@ export const RECONSTRUCTION_READINESS_EXAMPLE = {
             evidence_ids: [EVIDENCE_ID, CONTRADICTING_SOURCE.evidence_id],
         },
     ],
-    obligation_ledger: {
-        schema: "ReconstructionObligationLedger",
-        ledger_id: `rol_${HASH}`,
-        closure_digest: HASH,
-        status: "ready",
-        coverage: {
-            status: "complete",
-        },
-        summary: {
-            total: 1,
-            required: 1,
-            verified: 1,
-            required_open: 0,
-            by_status: STATUSES.map((key) => ({
-                key,
-                count: key === "verified" ? 1 : 0,
-            })),
-            by_application_layer: LAYERS.map((key) => ({
-                key,
-                count: key === "process" ? 1 : 0,
-            })),
-            by_evidence_authority: EVIDENCE_STATES.map((key) => ({
-                key,
-                count: key === "observed" ? 1 : 0,
-            })),
-        },
-        reports: {
-            missing_owner_obligation_ids: [],
-            missing_verifier_obligation_ids: [],
-            contradicted_obligation_ids: [],
-            residual_unknown_ids: [],
-        },
-        ownership_graph: [
-            {
-                obligation_id: "obl.readiness",
-                module_path: "src/readiness.ts",
-                symbol: "runReadiness",
-            },
-        ],
-        dependency_graph: [],
-        obligations: [
-            {
-                obligation_id: "obl.readiness",
-                obligation_version: 1,
-                title: "Preserve the packaged readiness fixture lifecycle",
-                origin: "reviewed",
-                application_layer: "process",
-                family: "packaged-process-lifecycle",
-                target: {
-                    artifact_sha256: HASH,
-                    application_node_id: null,
-                    semantic_node_id: null,
-                    location: "/fixture",
-                },
-                authority_references: [
-                    {
-                        evidence_id: EVIDENCE_ID,
-                        authority: "controlled-replay",
-                        state: "observed",
-                        location: "/fixture",
-                    },
-                ],
-                source_state: "observed",
-                observed_cases: CASES.map((kind) => ({
-                    kind,
-                    evidence_id: EVIDENCE_ID,
-                    location: `/original/${kind}`,
-                })),
-                required: true,
-                required_case_kinds: [...CASES],
-                required_original_authority: "process",
-                required_fixture_authority: "packaged-process",
-                required_verifier_authority: "packaged-process",
-                requires_parser_type: false,
-                dependency_obligation_ids: [],
-                residual_unknown_ids: [],
-                unavailable_authority: [],
-                required_next_evidence: [],
-                binding: {
-                    obligation_id: "obl.readiness",
-                    owner: {
-                        module_path: "src/readiness.ts",
-                        symbol: "runReadiness",
-                        owner_sha256: HASH,
-                    },
-                    parser_type: null,
-                    original_cases: CASES.map((kind) => ({
-                        kind,
-                        evidence_id: EVIDENCE_ID,
-                        location: `/original/${kind}`,
-                    })),
-                    fixtures: CASES.map((kind) => ({
-                        fixture_id: `fixture.${kind}`,
-                        case_kind: kind,
-                        authority: "packaged-process",
-                        evidence_ids: [EVIDENCE_ID],
-                    })),
-                    verifier: {
-                        verifier_id: "verifier.readiness",
-                        claim_id: "claim.readiness",
-                        command: "npm run verify:readiness",
-                        authority: "packaged-process",
-                        status: "pass",
-                        result_evidence_id: EVIDENCE_ID,
-                        enumerated_obligation_ids: ["obl.readiness"],
-                        nondeterminism: {
-                            mode: "partial-order",
-                            specification: "Startup precedes teardown.",
-                        },
-                    },
-                },
-                status: "verified",
-                diagnostics: [],
-            },
-        ],
-        evidence_links: [EVIDENCE_ID],
-        limitations: [],
-    },
+    obligation_ledger: READINESS_OBLIGATION_LEDGER,
     operation_outcomes: [
         {
             sequence: 0,
@@ -393,7 +400,7 @@ export const RECONSTRUCTION_READINESS_EXAMPLE = {
         },
         {
             sequence: 1,
-            ledger_digest: HASH,
+            ledger_digest: READINESS_OBLIGATION_LEDGER.closure_digest,
             status: "ready",
             required_open: 0,
             newly_verified_obligation_ids: ["obl.readiness"],

package/dist/contracts/reverseEngineeringToolContracts.js

@@ -0,0 +1,52 @@
+import { z } from "zod";
+import { objdumpInputSchema, rizinInputSchema, } from "../domain/reverseEngineering.js";
+import { evidenceResultOf } from "./toolOutputSchemaPrimitives.js";
+import { toolContractMetadata } from "./toolEffects.js";
+const commandObservationSchema = z.strictObject({
+    stdout: z.string(),
+    stderr: z.string(),
+    exit_code: z.union([z.string(), z.number(), z.null()]),
+    signal: z.string().nullable(),
+    output_truncated: z.boolean(),
+    completion_status: z.enum(["complete", "unknown"]),
+    artifact_sha256_after: z
+        .string()
+        .regex(/^[a-f0-9]{64}$/u)
+        .nullable(),
+    artifact_changed: z.boolean().nullable(),
+});
+/** Caller-selected GNU objdump and Rizin observations. */
+export const REVERSE_ENGINEERING_TOOL_CONTRACTS = [
+    {
+        name: "inspect_with_objdump",
+        ...toolContractMetadata("inspect_with_objdump"),
+        kind: "native-provider",
+        description: "Run caller-selected GNU objdump inspection against a local artifact, or request operation=architectures without a path to list BFD targets advertised by the installed binary. Preserves decoded stdout and stderr inline with SHA-256 Evidence for artifact inspections, up to a shared 16 MiB combined limit; invalid UTF-8 bytes are represented by replacement characters and flagged in Evidence limitations. output_truncated reports output beyond that limit and completion_status is unknown if buffer enforcement terminated the process. The raw output is authoritative and REA does not claim a stable normalized format. DWARF does not follow local debug links by default. Set follow_debug_links to true to follow them; identities of external debug files are not bound to Evidence. REA clears DEBUGINFOD_URLS for objdump so DWARF processing does not make debuginfod network requests. Architecture output is subjectless and does not establish support for any artifact.",
+        inputSchema: objdumpInputSchema,
+        outputSchema: evidenceResultOf(commandObservationSchema),
+        examples: [
+            {
+                title: "Disassemble code sections",
+                input: { path: "/tmp/program", operation: "disassemble" },
+            },
+            {
+                title: "List advertised BFD targets",
+                input: { operation: "architectures" },
+            },
+        ],
+    },
+    {
+        name: "execute_rizin_command",
+        ...toolContractMetadata("execute_rizin_command"),
+        kind: "native-provider",
+        description: "Execute one caller-selected Rizin command against a local artifact using the Rizin CLI profile that suppresses user settings and scripts while retaining plugins. Preserves decoded stdout and stderr inline with SHA-256 Evidence, up to a shared 16 MiB combined limit; invalid UTF-8 bytes are represented by replacement characters and flagged in Evidence limitations. output_truncated reports output beyond that limit and completion_status is unknown if buffer enforcement terminated the process. Rizin commands and retained plugins can execute foreign code, mutate files, access the network, and read files outside the selected artifact; identities and contents of those external inputs are not bound to Evidence. Command effects depend on the Rizin command and loaded plugins; JSON is command-specific and raw output remains authoritative. In a shared MCP server, this admitted command closes any active binary-analysis session; after its effects have settled, call open_binary before further analysis. Close an active Ghidra session explicitly first.",
+        inputSchema: rizinInputSchema,
+        outputSchema: evidenceResultOf(commandObservationSchema),
+        examples: [
+            {
+                title: "Inspect binary information",
+                input: { path: "/tmp/program", command: "iI" },
+            },
+        ],
+    },
+];

package/dist/contracts/rizinDebugToolContracts.js

@@ -0,0 +1,96 @@
+import { z } from "zod";
+import { evidenceResultOf } from "./toolOutputSchemaPrimitives.js";
+import { toolContractMetadata } from "./toolEffects.js";
+const sessionId = z.string().uuid();
+const commandResult = z.strictObject({
+    command: z.string(),
+    output: z.string(),
+    output_scope: z.literal("command_and_interleaved_session_output"),
+    output_truncated: z.boolean(),
+    output_invalid_utf8: z.literal(true).optional(),
+    completion_status: z.enum(["complete", "unknown"]),
+    backend: z.string().nullable(),
+});
+/** Persistent Rizin debugger session contracts. */
+export const RIZIN_DEBUG_TOOL_CONTRACTS = [
+    {
+        name: "start_rizin_debug_session",
+        ...toolContractMetadata("start_rizin_debug_session"),
+        kind: "native-provider",
+        description: "Start a persistent Rizin debugger session using `-N` to suppress user settings and scripts while retaining plugins, `-0` for NUL framing, and `-d` with an optional caller-selected IO debugger backend. Requires a caller-selected Linux TTY for inferior stdout and stderr; the target may write directly to that terminal while running and after detach. REA verifies both destinations and `dbg.exitkills=false` before detaching. Backend and target capabilities depend on the installed build. The session lives in this REA MCP process. Persistent sessions require Linux `/proc` descriptor readback. In a shared MCP server, starting this session retires any active binary-analysis session; after target effects have settled, call open_binary before further analysis. Close an active Ghidra session explicitly first.",
+        inputSchema: z.strictObject({
+            path: z.string().min(1),
+            inferior_tty: z.string().min(1),
+            backend: z.string().min(1).optional(),
+        }),
+        outputSchema: z.strictObject({
+            session_id: sessionId,
+            backend: z.string().nullable(),
+        }),
+        examples: [
+            {
+                title: "Start Rizin debugger",
+                input: { path: "/tmp/program", inferior_tty: "/dev/pts/7" },
+            },
+        ],
+    },
+    {
+        name: "rizin_debug_command",
+        ...toolContractMetadata("rizin_debug_command"),
+        kind: "native-provider",
+        description: "Execute one unrestricted command in a persistent Rizin debugger session. Returns raw output inline with Evidence, including backend output interleaved before the completion marker. If the command exceeds the output or frame limit, `output_truncated` is true and `completion_status` is `unknown`; retained partial output is returned and the owned debugger session is stopped. Unsolicited frames already queued before the command make the session unavailable because correlation is ambiguous. Commands can access local files, shell, network, plugins, and target state; effects depend on the active backend and target. In a shared MCP server, this admitted command closes any active binary-analysis session; after its effects have settled, call open_binary before further analysis. Close an active Ghidra session explicitly first.",
+        inputSchema: z.strictObject({
+            session_id: sessionId,
+            command: z
+                .string()
+                .min(1)
+                .refine((value) => !/[\r\n]/u.test(value), "A single command line is required"),
+        }),
+        outputSchema: evidenceResultOf(commandResult),
+        examples: [
+            {
+                title: "Inspect debugger state",
+                input: {
+                    session_id: "00000000-0000-4000-8000-000000000001",
+                    command: "dr",
+                },
+            },
+        ],
+    },
+    {
+        name: "rizin_debug_session_status",
+        ...toolContractMetadata("rizin_debug_session_status"),
+        kind: "native-provider",
+        description: "Return observed lifecycle state and bounded recent NUL-framed output and process diagnostics for one Rizin debugger session; truncation fields report discarded data, and output_invalid_utf8 reports whether invalid UTF-8 has been observed in session frame bytes; recent output may contain replacement characters.",
+        inputSchema: z.strictObject({ session_id: sessionId }),
+        outputSchema: z.strictObject({
+            session_id: sessionId,
+            state: z.enum(["ready", "closed"]),
+            inferior_tty: z.string(),
+            recent_output: z.array(z.string()),
+            recent_output_truncated: z.boolean(),
+            diagnostics_truncated: z.boolean(),
+            output_invalid_utf8: z.boolean(),
+        }),
+        examples: [
+            {
+                title: "Check Rizin session",
+                input: { session_id: "00000000-0000-4000-8000-000000000001" },
+            },
+        ],
+    },
+    {
+        name: "close_rizin_debug_session",
+        ...toolContractMetadata("close_rizin_debug_session"),
+        kind: "native-provider",
+        description: "Close the REA-owned Rizin debugger only after verifying no inferior remains or detaching one with a verified caller-selected TTY output sink. A detached target may continue running and write to that TTY; target state is otherwise reported as unknown. REA never signals an inferior based on PID or path. In a shared MCP server, this admitted close retires any active binary-analysis session; after target effects have settled, call open_binary before further analysis. Close an active Ghidra session explicitly first.",
+        inputSchema: z.strictObject({ session_id: sessionId }),
+        outputSchema: z.strictObject({ target_state: z.literal("unknown") }),
+        examples: [
+            {
+                title: "Close Rizin debugger",
+                input: { session_id: "00000000-0000-4000-8000-000000000001" },
+            },
+        ],
+    },
+];

package/dist/contracts/rust/rustToolContracts.js

@@ -0,0 +1,20 @@
+import { inspectRustBinaryInputSchema, rustBinarySchema, } from "../../domain/rust/rustBinary.js";
+import { toolContractMetadata } from "../toolEffects.js";
+import { evidenceResultOf } from "../toolOutputSchemaPrimitives.js";
+/** Static Rust dependency metadata is independent of active native-analysis providers. */
+export const RUST_TOOL_CONTRACTS = [
+    {
+        name: "inspect_rust_binary",
+        ...toolContractMetadata("inspect_rust_binary"),
+        kind: "artifact-provider",
+        description: "Inspect the cargo-auditable crate dependency list embedded in an explicit local ELF, PE or thin Mach-O image. Returns the artifact SHA-256, the .dep-v0 section file offset and size, compressed and uncompressed sizes, format version, packages in their original order, the root package index, and dependency edges by index. Reads zlib-compressed JSON without installing Rust, opening a disassembler, executing the target, writing temporary files or accessing the network. A missing section is null metadata with a limitation and is not proof that the binary has no dependencies. A rustc commit hash is reported only as an inference when a /rustc/<40-hex>/ path is present in read-only data. Resource guards bound files to 256 MiB, dependency sections to 1 MiB, inflated JSON to the smaller of 8 MiB and 64 times the compressed size, and the complete report to 8 MiB. Malformed, unsupported and oversized inputs receive typed failures rather than partial success.",
+        inputSchema: inspectRustBinaryInputSchema,
+        outputSchema: evidenceResultOf(rustBinarySchema),
+        examples: [
+            {
+                title: "Inspect an embedded Rust dependency list",
+                input: { path: "/artifacts/application" },
+            },
+        ],
+    },
+];

package/dist/contracts/sessionLifecycleInputs.js

@@ -1,6 +1,7 @@
 import { isAbsolute } from "node:path";
 import { executableFormatHintSchema } from "../domain/dosCom.js";
 import { localPathStringSchema } from "../domain/localPath.js";
+import { binaryArchitectureSchema, rawBinaryEntryPointSchema, rawBinarySelectionError, } from "../domain/rawBinary.js";
 import { z } from "zod";
 import { analysisProviderSelectorSchema } from "./providerSelection.js";
 /** Caller-supplied analysis snapshot path; must name its destination absolutely. */
@@ -16,13 +17,44 @@ const binaryTargetPathSchema = localPathStringSchema
 })
     .describe("Absolute local filesystem path for the analysis target; relative paths are rejected.");
 /** Input contract for opening a target with an optional staged snapshot. */
-export const openBinaryInputSchema = z.strictObject({
+export const openBinaryInputSchema = z
+    .strictObject({
     path: binaryTargetPathSchema,
     format: executableFormatHintSchema
         .optional()
-        .describe("Explicit headerless DOS COM interpretation; omission preserves header-based detection"),
+        .describe("Explicit headerless interpretation: dos-com or raw-binary. Omission preserves header-based detection."),
+    architecture: binaryArchitectureSchema
+        .optional()
+        .describe("Caller-supplied CPU family. Required with format=raw-binary; rejected otherwise."),
+    entry_point: rawBinaryEntryPointSchema
+        .optional()
+        .describe("Caller-supplied load and entry address (0xhex). File offset 0 is mapped here. Required with format=raw-binary; rejected otherwise."),
     provider_id: analysisProviderSelectorSchema.optional(),
     snapshot_path: snapshotPathSchema.optional(),
+})
+    .superRefine((value, context) => {
+    const pairing = rawBinarySelectionError({
+        ...(value.format === undefined ? {} : { format: value.format }),
+        ...(value.architecture === undefined
+            ? {}
+            : { architecture: value.architecture }),
+        ...(value.entry_point === undefined
+            ? {}
+            : { entryPoint: value.entry_point }),
+    });
+    if (pairing === undefined)
+        return;
+    context.addIssue({
+        code: "custom",
+        path: value.format === "raw-binary"
+            ? value.architecture === undefined
+                ? ["architecture"]
+                : ["entry_point"]
+            : value.architecture === undefined
+                ? ["entry_point"]
+                : ["architecture"],
+        message: pairing,
+    });
 });
 /** Input contract for closing a target after an optional atomic snapshot. */
 export const closeBinaryInputSchema = z.strictObject({

package/dist/contracts/sessionToolContracts.js

@@ -37,7 +37,7 @@ export const exportEvidenceBundleInputSchema = z.strictObject({
 });
 /** 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, archive, JavaScript, source map, plist, or analysis database after validation. format=dos-com explicitly interprets 1..65280 headerless bytes as a DOS COM analysis image; omission preserves header-based detection. provider_id selects one deep provider or deterministic auto selection; the binding remains stable until close or an explicit switch, with no failure fallback. Reopening the same target and profile retains its active database and metadata edits. An optional analysis snapshot is imported atomically and must match the binary identity, concrete provider, and canonical analysis profile exactly; importing into a session with metadata mutations requires closing and reopening it first.", openBinaryInputSchema),
+    session("open_binary", "Open a local executable, application bundle, archive, JavaScript, source map, plist, or analysis database after validation. format=dos-com explicitly interprets 1..65280 headerless bytes as a DOS COM analysis image. format=raw-binary interprets headerless bytes with a required architecture and entry_point; file offset 0 maps at that address. Omission preserves header-based detection. provider_id selects one deep provider or deterministic auto selection; the binding remains stable until close or an explicit switch, with no failure fallback. Reopening the same target and profile retains its active database and metadata edits. An optional analysis snapshot is imported atomically and must match the binary identity, concrete provider, and canonical analysis profile exactly; importing into a session with metadata mutations requires closing and reopening it first.", openBinaryInputSchema),
     session("close_binary", "Drain earlier provider requests, optionally write a provider-neutral analysis snapshot atomically to the caller-supplied path, then close the active target and every provider resource started for it. Later provider requests wait until this lifecycle operation finishes. Existing files require explicit overwrite; a failed save leaves the session open so cached analysis is not lost. Metadata edits prevent immutable snapshot saves until the session is recreated; export_evidence_bundle preserves mutable observations before closing without a snapshot.", closeBinaryInputSchema),
     session("binary_session", "Report the complete current target, provider, capability availability, client-feature, analysis, and server-identity status without starting analysis.", binarySessionInputSchema),
     session("export_evidence_bundle", "Atomically write the session's deterministic Evidence bundle to the requested local path. Existing files require overwrite: true; records and manifests use canonical byte-stable ordering.", exportEvidenceBundleInputSchema),
@@ -51,7 +51,7 @@ export const SESSION_TOOL_CONTRACTS = [
     session("build_call_path", "Build every shortest direct-callee path inline from complete analyze_function Evidence records using exact canonical addresses. Missing dossiers and provider mixing remain unknown; every node and edge cites source Evidence.", callPathInputSchema),
     session("correlate_static_and_runtime", "Evaluate every explicit caller-declared hypothesis 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. Returns all correlations and their complete Evidence closure inline.", 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 every current residual-unknown head in deterministic ID order, with optional exact status, severity, and domain filters. Results are complete and inline. This is read-only; unresolved, contradicted, and non-truth dispositions remain distinct.", listUnknownsInputSchema),
+    session("list_unknowns", "List current residual-unknown heads in deterministic ID order, with optional exact status, severity, and domain filters. Results are complete inline by default; supply offset and limit to page the filtered order. total is the matching-head count and next_offset is null when the page exhausts the result. This is read-only; unresolved, contradicted, and non-truth dispositions remain distinct.", listUnknownsInputSchema),
     session("record_unknown", "Create one deterministic residual unknown and immutable mutation evidence. 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 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.", verifyUnknownResolutionInputSchema),

package/dist/contracts/sessionToolSchemas.js

@@ -41,6 +41,20 @@ export const listUnknownsInputSchema = z.strictObject({
         .optional(),
     severity: z.enum(["low", "medium", "high", "critical"]).optional(),
     domain: z.string().trim().min(1).optional(),
+    offset: z
+        .number()
+        .int()
+        .min(0)
+        .max(Number.MAX_SAFE_INTEGER)
+        .default(0)
+        .describe("Zero-based offset in the stable filtered unknown ID order."),
+    limit: z
+        .number()
+        .int()
+        .positive()
+        .max(Number.MAX_SAFE_INTEGER)
+        .optional()
+        .describe("Optional maximum number of heads to return. Omit to return every matching head from offset."),
 });
 /** Exact residual-unknown identity to revalidate. */
 export const verifyUnknownResolutionInputSchema = z.strictObject({

package/dist/contracts/signals/signalToolContracts.js

@@ -0,0 +1,40 @@
+import { inspectSignalDecodersInputSchema, signalDecodersSchema, } from "../../domain/signals/signalDecoders.js";
+import { decodeSignalRecordingInputSchema, signalRecordingSchema, } from "../../domain/signals/signalRecording.js";
+import { toolContractMetadata } from "../toolEffects.js";
+import { evidenceResultOf } from "../toolOutputSchemaPrimitives.js";
+export const SIGNAL_TOOL_CONTRACTS = [
+    {
+        name: "inspect_signal_decoders",
+        ...toolContractMetadata("inspect_signal_decoders"),
+        kind: "artifact-provider",
+        description: "Discover installed sigrok protocol decoders or inspect one decoder's channel/option help on Linux. Omit decoder to list ID/name pairs; supply its exact ID for literal help lines with source line numbers. query is a case-insensitive literal substring. Page matches with offset/limit (default 50; null returns all remaining). Reports tool identity, version, diagnostics and examined/matching coverage. Uses configured REA_SIGROK_COMMAND and prlimit; no recording, binary target, hardware scan or acquisition. Each call probes again; decoder modules are trusted, not fully fingerprinted. Use returned IDs/options with decode_signal_recording.",
+        inputSchema: inspectSignalDecodersInputSchema,
+        outputSchema: evidenceResultOf(signalDecodersSchema),
+        examples: [
+            { title: "Find installed UART decoders", input: { query: "uart" } },
+            {
+                title: "Read the installed UART baud-rate option",
+                input: { decoder: "uart", query: "baud" },
+            },
+        ],
+    },
+    {
+        name: "decode_signal_recording",
+        ...toolContractMetadata("decode_signal_recording"),
+        kind: "artifact-provider",
+        description: "Decode an existing local logic/signal recording on Linux with sigrok-cli 0.7.2 and util-linux prlimit. Supply decoder stack, channels and options explicitly; optionally select input format and annotation classes. Return 50 literal output lines by default, with line_offset/line_limit paging; line_limit:null requests all remaining lines. Output windows count display lines, not annotations or samples, and do not shorten decoding. Preserve selected text, sample ranges, stderr, source/tool identity and coverage inline. Configure absolute REA_SIGROK_COMMAND. File-only analysis; no hardware acquisition or device communication. Empty output does not prove absence of traffic.",
+        inputSchema: decodeSignalRecordingInputSchema,
+        outputSchema: evidenceResultOf(signalRecordingSchema),
+        examples: [
+            {
+                title: "Decode recorded UART RX bytes",
+                input: {
+                    path: "/artifacts/uart.vcd",
+                    input_format: "vcd",
+                    decoders: "uart:rx=RX:baudrate=9600",
+                    annotations: "uart=rx-data",
+                },
+            },
+        ],
+    },
+];

package/dist/contracts/sqlite/sqliteToolContracts.js

@@ -0,0 +1,36 @@
+import { inspectSqliteDatabaseInputSchema, sqliteDatabaseSchema, } from "../../domain/sqlite/sqliteDatabase.js";
+import { toolContractMetadata } from "../toolEffects.js";
+import { evidenceResultOf } from "../toolOutputSchemaPrimitives.js";
+/** Snapshot inspection is independent of any active native-analysis target. */
+export const SQLITE_TOOL_CONTRACTS = [
+    {
+        name: "inspect_sqlite_database",
+        ...toolContractMetadata("inspect_sqlite_database"),
+        kind: "artifact-provider",
+        description: "Inspect an explicit local SQLite database snapshot and its existing sibling WAL without modifying source files or opening a native analysis provider. Requires Node.js 24.x >=24.15 or 26+ with native DatabaseSync.limits support, checked by the worker. Returns observed Evidence with database/WAL SHA-256 and a compact schema inventory. Selecting an exact ordinary table expands only its schema and samples rows (default 20, subject to byte and worker resource limits). Select exact columns in the requested order to avoid unrelated or large values; schema_scope=database explicitly expands the whole schema; returned rows retain 64-bit integers, text bytes and blobs with explicit truncation. No arbitrary SQL, view or virtual-table execution, extension loading, database repair, encryption support or live-snapshot atomicity claim. At most two inspections per provider are admitted; occupied capacity is retryable. An isolated temporary copy and owned worker enforce input, value/record, SQL-statement, JSON-reply, JavaScript-heap and deadline limits; overall native heap is not capped. Supply a quiescent snapshot for coherent database/WAL evidence.",
+        inputSchema: inspectSqliteDatabaseInputSchema,
+        outputSchema: evidenceResultOf(sqliteDatabaseSchema),
+        examples: [
+            {
+                title: "Inspect a compact inventory of a local SQLite snapshot",
+                input: { path: "/artifacts/application.sqlite" },
+            },
+            {
+                title: "Read selected rows from an ordinary table",
+                input: {
+                    path: "/artifacts/application.sqlite",
+                    table: "settings",
+                    columns: ["key", "value"],
+                    row_limit: 20,
+                },
+            },
+            {
+                title: "Expand the complete stored schema",
+                input: {
+                    path: "/artifacts/application.sqlite",
+                    schema_scope: "database",
+                },
+            },
+        ],
+    },
+];