reverseport 0.0.0-stage → 1.2.0

package/dist/contracts/reconstructionReadinessExample.js

@@ -0,0 +1,438 @@
+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",
+    name: "REA readiness fixture",
+    version: "1",
+}, {
+    predicateType: "rea.reconstruction-readiness-fixture",
+    operation: "run_reconstruction_readiness_fixture",
+    parameters: { variant },
+    result: { passed: true, variant },
+    confidence: "observed",
+    authority: "controlled-replay",
+});
+const SOURCE = sourceEvidence("authority");
+const CONTRADICTING_SOURCE = sourceEvidence("contradiction");
+const EVIDENCE_ID = SOURCE.evidence_id;
+const CASES = [
+    "positive",
+    "negative",
+    "malformed",
+    "cancellation",
+    "teardown",
+];
+const FIXTURES = [
+    "native",
+    "javascript-cli",
+    "electron",
+    "incomplete-reconstruction",
+    "broken-runtime",
+];
+const STATUSES = [
+    "unowned",
+    "characterized",
+    "implemented",
+    "verified",
+    "contradicted",
+    "blocked",
+    "out-of-scope",
+    "unknown",
+];
+const LAYERS = [
+    "cli",
+    "protocol",
+    "electron",
+    "persistence",
+    "process",
+    "runtime",
+    "packaging",
+    "native-abi",
+    "application",
+    "other",
+];
+const EVIDENCE_STATES = [
+    "candidate",
+    "observed",
+    "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: {
+        cli_version: "2.4.0",
+        server_version: "2.4.0",
+        catalog_digest: HASH,
+        skill_digest: HASH,
+        versions: [
+            {
+                component: "rea-cli",
+                version: "2.4.0",
+                digest: HASH,
+                state: "current",
+                remediation: null,
+            },
+            {
+                component: "rea-server",
+                version: "2.3.0",
+                digest: "b".repeat(64),
+                state: "stale",
+                remediation: "Restart the connected MCP server.",
+            },
+            {
+                component: "rea-server",
+                version: "2.4.0",
+                digest: HASH,
+                state: "current",
+                remediation: null,
+            },
+        ],
+        providers: [
+            {
+                provider_id: "javascript-application",
+                version: "1",
+                digest: HASH,
+                state: "available",
+                reason_code: null,
+            },
+            {
+                provider_id: "broken-runtime-probe",
+                version: null,
+                digest: null,
+                state: "broken-host",
+                reason_code: "host-runtime-linker-failure",
+            },
+        ],
+    },
+    client: {
+        name: "synthetic-mcp-client",
+        version: "1",
+        negotiated_capabilities: ["elicitation", "progress", "resources"],
+    },
+    capabilities: [
+        {
+            capability_id: "analyze-javascript-application",
+            available: true,
+            bounded: true,
+            side_effect: "reads-target",
+            authority_scopes: ["investigation-input"],
+            limits: [{ name: "max-ast-nodes", value: 2_000_000, unit: "count" }],
+            unavailable_reason: null,
+        },
+    ],
+    fixtures: FIXTURES.map((kind) => ({
+        fixture_id: `fixture.${kind}`,
+        kind,
+        artifact_sha256: HASH,
+        environment_id: "environment.synthetic",
+        deliberate_faults: [`fault.${kind}`],
+    })),
+    workflow_candidates: FIXTURES.map((kind) => ({
+        fixture_id: `fixture.${kind}`,
+        workflow_id: `workflow.${kind}`,
+        provider_id: kind === "broken-runtime" ? null : `provider.${kind}`,
+        selected: true,
+        invoked: true,
+        compatibility: "compatible",
+        reason_code: "compatible-artifact-family",
+    })),
+    grants: [
+        {
+            grant_id: "grant.denied",
+            scope: "process-capture",
+            decision: "denied",
+            launched_process: false,
+            evidence_ids: [EVIDENCE_ID],
+        },
+        {
+            grant_id: "grant.session",
+            scope: "process-capture",
+            decision: "granted",
+            launched_process: true,
+            evidence_ids: [EVIDENCE_ID],
+        },
+    ],
+    evidence_bundle: createEvidenceBundle([SOURCE, CONTRADICTING_SOURCE]),
+    comparisons: [
+        {
+            comparison_id: "comparison.concurrent",
+            verdict: "equivalent",
+            schedule_semantics: "partial-order",
+            concurrent: true,
+            truncated: false,
+            unavailable_authority: false,
+            unstable: false,
+            deliberate_divergence_ref: null,
+            divergence_refs: [],
+            contradiction_ids: [],
+            evidence_ids: [EVIDENCE_ID],
+        },
+        {
+            comparison_id: "comparison.divergence",
+            verdict: "different",
+            schedule_semantics: "finite-traces",
+            concurrent: true,
+            truncated: false,
+            unavailable_authority: false,
+            unstable: false,
+            deliberate_divergence_ref: "/events/primary",
+            divergence_refs: ["/events/primary"],
+            contradiction_ids: [],
+            evidence_ids: [EVIDENCE_ID],
+        },
+        {
+            comparison_id: "comparison.contradicted",
+            verdict: "unknown",
+            schedule_semantics: "finite-traces",
+            concurrent: false,
+            truncated: false,
+            unavailable_authority: false,
+            unstable: false,
+            deliberate_divergence_ref: null,
+            divergence_refs: [],
+            contradiction_ids: ["contradiction.artifact"],
+            evidence_ids: [EVIDENCE_ID],
+        },
+    ],
+    contradictions: [
+        {
+            contradiction_id: "contradiction.artifact",
+            declared_sha256: HASH,
+            observed_sha256: "b".repeat(64),
+            policy: "record-and-continue",
+            affected_comparison_ids: ["comparison.contradicted"],
+            evidence_ids: [EVIDENCE_ID, CONTRADICTING_SOURCE.evidence_id],
+        },
+    ],
+    obligation_ledger: READINESS_OBLIGATION_LEDGER,
+    operation_outcomes: [
+        {
+            sequence: 0,
+            operation: "inspect-artifact",
+            surface: "cli",
+            call_kind: "valid",
+            expected_success: true,
+            cli_exit_code: 0,
+            mcp_status: null,
+            error_code: null,
+            recovered: false,
+            evidence_ids: [EVIDENCE_ID],
+        },
+        {
+            sequence: 1,
+            operation: "inspect-artifact",
+            surface: "mcp",
+            call_kind: "valid",
+            expected_success: true,
+            cli_exit_code: null,
+            mcp_status: "success",
+            error_code: null,
+            recovered: false,
+            evidence_ids: [EVIDENCE_ID],
+        },
+        {
+            sequence: 2,
+            operation: "capture-process",
+            surface: "cli",
+            call_kind: "permission",
+            expected_success: false,
+            cli_exit_code: 2,
+            mcp_status: null,
+            error_code: "permission-required",
+            recovered: true,
+            evidence_ids: [EVIDENCE_ID],
+        },
+        {
+            sequence: 3,
+            operation: "capture-process",
+            surface: "mcp",
+            call_kind: "permission",
+            expected_success: false,
+            cli_exit_code: null,
+            mcp_status: "non-success",
+            error_code: "permission-required",
+            recovered: true,
+            evidence_ids: [EVIDENCE_ID],
+        },
+    ],
+    cleanup: [
+        {
+            run_id: "run.cancelled",
+            cancelled: true,
+            owned_resources_remaining: 0,
+            diagnostic_evidence_ids: [EVIDENCE_ID],
+        },
+    ],
+    closure_history: [
+        {
+            sequence: 0,
+            ledger_digest: "b".repeat(64),
+            status: "open",
+            required_open: 1,
+            newly_verified_obligation_ids: [],
+            evidence_ids: [EVIDENCE_ID],
+        },
+        {
+            sequence: 1,
+            ledger_digest: READINESS_OBLIGATION_LEDGER.closure_digest,
+            status: "ready",
+            required_open: 0,
+            newly_verified_obligation_ids: ["obl.readiness"],
+            evidence_ids: [EVIDENCE_ID],
+        },
+    ],
+    delegation_checks: [
+        {
+            candidate_id: "candidate.reconstructed",
+            delegates_to_authority: false,
+            evidence_ids: [EVIDENCE_ID],
+        },
+    ],
+    replay: {
+        expected_source_digest: null,
+        deterministic: true,
+        tamper_detected: true,
+        stale_input_detected: true,
+        evidence_ids: [EVIDENCE_ID],
+    },
+    stages: READINESS_STAGE_IDS.map((stageId) => ({
+        stage_id: stageId,
+        required: true,
+        status: "pass",
+        capability_issue: null,
+        next_action: null,
+        evidence_ids: [EVIDENCE_ID],
+        checks: READINESS_REQUIRED_CHECKS[stageId].map((checkId) => ({
+            check_id: checkId,
+            status: "pass",
+            detail: `Synthetic conformance proved ${checkId}.`,
+            evidence_ids: [EVIDENCE_ID],
+        })),
+    })),
+};

package/dist/contracts/sessionLifecycleInputs.js

@@ -0,0 +1,63 @@
+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. */
+const snapshotPathSchema = localPathStringSchema
+    .refine(isAbsolute, {
+    message: "snapshot_path must be an absolute local filesystem path (for example /tmp/rea/analysis.json or C:\\rea\\analysis.json)",
+})
+    .describe("Absolute local filesystem path for the analysis snapshot; relative paths are rejected.");
+/** Caller-supplied analysis target path; must name the target absolutely. */
+const binaryTargetPathSchema = localPathStringSchema
+    .refine(isAbsolute, {
+    message: "path must be an absolute local filesystem path (for example /tmp/fixture.bin or C:\\analysis\\fixture.bin)",
+})
+    .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({
+    path: binaryTargetPathSchema,
+    format: executableFormatHintSchema
+        .optional()
+        .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({
+    snapshot_path: snapshotPathSchema.optional(),
+    overwrite: z.boolean().default(false),
+});

package/dist/contracts/sessionStatusContract.js

@@ -0,0 +1,17 @@
+import { z } from "zod";
+import { isAbsolute } from "node:path";
+import { localPathStringSchema } from "../domain/localPath.js";
+/** Optional expectations used to compare the live session with its caller. */
+export const binarySessionInputSchema = z.strictObject({
+    expected_package_version: z.string().min(1).optional(),
+    expected_catalog_digest: z
+        .string()
+        .regex(/^[a-f0-9]{64}$/u)
+        .optional(),
+    expected_server_path: localPathStringSchema
+        .refine(isAbsolute, {
+        message: "expected_server_path must be an absolute local filesystem path (for example /opt/rea/dist/main.js)",
+    })
+        .describe("Absolute local filesystem path expected for the running server; relative paths are rejected.")
+        .optional(),
+});

package/dist/contracts/sessionToolContracts.js

@@ -0,0 +1,61 @@
+import { z } from "zod";
+import { isAbsolute } from "node:path";
+import { localPathStringSchema } from "../domain/localPath.js";
+import { artifactComparisonInputSchema } from "../domain/artifactComparison.js";
+import { bundleComparisonInputSchema } from "../domain/bundleComparison.js";
+import { callPathInputSchema } from "../domain/callPathSchemas.js";
+import { changedBehaviorInputSchema } from "../domain/changedBehavior.js";
+import { functionComparisonInputSchema } from "../domain/functionComparisonSchemas.js";
+import { processScenarioSchema } from "../domain/process/processScenario.js";
+import { recordUnknownInputSchema, updateUnknownInputSchema, } from "../domain/residualUnknown.js";
+import { reconstructionVerificationInputSchema } from "../domain/reconstructionVerificationSchemas.js";
+import { staticRuntimeCorrelationInputSchema } from "../domain/staticRuntimeCorrelation.js";
+import { sessionOutputSchemas } from "./toolOutputSchemaGroups.js";
+import { requireOutputSchema } from "./toolOutputSchemaPrimitives.js";
+import { closeBinaryInputSchema, openBinaryInputSchema, } from "./sessionLifecycleInputs.js";
+import { binarySessionInputSchema } from "./sessionStatusContract.js";
+import { addressContextInputSchema, importEvidenceBundleInputSchema, listUnknownsInputSchema, navigationContextInputSchema, processComparisonInputSchema, getEvidenceBundleInputSchema, verifyUnknownResolutionInputSchema, } from "./sessionToolSchemas.js";
+import { examplesFor } from "./toolContractHelpers.js";
+import { toolContractMetadata } from "./toolEffects.js";
+const session = (name, description, inputSchema) => ({
+    name,
+    ...toolContractMetadata(name),
+    description,
+    kind: "session",
+    inputSchema,
+    outputSchema: requireOutputSchema(sessionOutputSchemas, name),
+    examples: examplesFor(name, inputSchema),
+});
+/** Session-owned Evidence bundle export options. */
+export const exportEvidenceBundleInputSchema = z.strictObject({
+    path: localPathStringSchema
+        .refine(isAbsolute, {
+        message: "path must be an absolute local filesystem path (for example /tmp/rea/evidence.json or C:\\rea\\evidence.json)",
+    })
+        .describe("Absolute local filesystem path for the exported evidence bundle; relative paths are rejected."),
+    overwrite: z.boolean().default(false),
+});
+/** 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. 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),
+    session("import_evidence_bundle", "Read the JSON bundle at the supplied local path, validate every Evidence ID and canonical manifest, then atomically merge it. Imported content is data only and is never executed.", importEvidenceBundleInputSchema),
+    session("capture_process_scenario", "Run one caller-selected command under a PTY and return process capture Evidence with residual unknowns. The renderer admits at most 1,000,000 combined terminal cells, computed as columns × (rows + scrollback); every resize uses the selected scrollback and must fit the same budget. Supply a smaller terminal shape when that product is too large; dimensions are never clamped. A command name resolves through the inherited PATH; the working directory defaults to the caller's current directory; host environment variables are inherited with scenario overrides. Environment keys cannot contain '=' or NUL, and REA_PROCESS_RUN_ID is reserved for process ownership. Filesystem snapshots are opt-in through filesystem_observation_paths. A positive finalization_ms makes a timeout or idle deadline send SIGTERM to the captured root through its start identity, keep observing, and send SIGKILL once after the interval; exit.finalization records each attempt with its delivery result and the observed exit, and cancellation still ends the run at once. The target runs with the current user's permissions; this is not a security sandbox.", processScenarioSchema),
+    session("compare_process_captures", "Compare two compatible process capture observations across terminal, interaction, lifecycle, process, filesystem, command-shim, HTTP, and WebSocket evidence. Optional trace_spec validates exact events against an explicit partial order or finite trace language; concurrency is never inferred from timestamps or broad sorting. Missing, journal-free, or truncated observations are never treated as equivalent.", processComparisonInputSchema),
+    session("compare_artifacts", "Compare complete artifact inventories by logical occurrence path, content identity, metadata, and graph relations. Pass the inventory Evidence nested in each inspect_artifact result as left and right. Every delta cites both inputs, and gaps yield truncated or unknown, never equivalence. Returns every change inline.", artifactComparisonInputSchema),
+    session("compare_functions", "Compare two explicit sets of analyze_function Evidence 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 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 returns every change inline.", bundleComparisonInputSchema),
+    session("find_changed_behavior", "Aggregate validated process and artifact comparison Evidence. Runtime observations remain distinct from static behavior candidates; missing or incomplete comparisons produce unresolved findings, never causal claims. Returns every finding inline.", changedBehaviorInputSchema),
+    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("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),
+    session("get_evidence_bundle", "Return every retained Evidence record and residual unknown as a complete canonical bundle by default. detail=summary discovers retained records without copying or transferring their payloads; optionally filter by exact Evidence ID, operation, target SHA-256, analysis-profile digest or canonical native procedure address. Metadata distinguishes complete record retention from native value-flow truncation or unavailable/unknown coverage. Use a discovered evidence_id with inspect_analysis_view without restarting a provider. Filters apply only to summary delivery. Call with detail: summary first; the complete bundle can be very large.", getEvidenceBundleInputSchema),
+    session("get_navigation_context", "Return the selected document, current address, and containing/current procedure in one provider-neutral result. The result reflects sequential provider observations, not an atomic cursor snapshot; a cursor outside any procedure returns procedure: null.", navigationContextInputSchema),
+    session("inspect_address_context", "Inspect one explicit reproducible address for its analyzed name, containing procedure, regular and inline comments, and matching bookmarks. Each unsupported facet returns a typed unavailable outcome; use xrefs, assembly, or pseudocode for those deeper views.", addressContextInputSchema),
+];

package/dist/contracts/sessionToolSchemas.js

@@ -0,0 +1,51 @@
+import { z } from "zod";
+import { isAbsolute } from "node:path";
+import { localPathStringSchema } from "../domain/localPath.js";
+import { processTraceSpecificationSchema } from "../domain/process/processTraceSpecification.js";
+import { evidenceSchema } from "../domain/evidence.js";
+import { prefixedDigestSchema } from "./../domain/digests.js";
+import { evidenceRecordFiltersSchema } from "../domain/evidenceRecordSummary.js";
+/** Complete retained Evidence, or selected discovery metadata without payloads. */
+export const getEvidenceBundleInputSchema = z.strictObject({
+    detail: z
+        .enum(["complete", "summary"])
+        .default("complete")
+        .describe("complete (default) returns every record inline and can be very large; summary lists retained records without payloads — call it first"),
+    filters: evidenceRecordFiltersSchema.optional(),
+});
+/** Optional document selection for volatile navigation context. */
+export const navigationContextInputSchema = z.strictObject({
+    document: z.string().min(1).optional(),
+});
+/** Explicit reproducible address context query. */
+export const addressContextInputSchema = z.strictObject({
+    address: z.string().min(1),
+    document: z.string().min(1).optional(),
+});
+/** Session-owned Evidence bundle import options. */
+export const importEvidenceBundleInputSchema = z.strictObject({
+    path: localPathStringSchema
+        .refine(isAbsolute, {
+        message: "path must be an absolute local filesystem path (for example /tmp/evidence.json or C:\\rea\\evidence.json)",
+    })
+        .describe("Absolute local filesystem path for the evidence bundle to import; relative paths are rejected."),
+});
+/** Evidence references for deterministic process comparison. */
+export const processComparisonInputSchema = z.strictObject({
+    left: evidenceSchema,
+    right: evidenceSchema,
+    trace_spec: processTraceSpecificationSchema.optional(),
+    max_capture_age_ms: z.number().int().nonnegative().optional(),
+});
+/** Residual-unknown list filters. */
+export const listUnknownsInputSchema = z.strictObject({
+    status: z
+        .enum(["open", "investigating", "blocked", "contradicted", "resolved"])
+        .optional(),
+    severity: z.enum(["low", "medium", "high", "critical"]).optional(),
+    domain: z.string().trim().min(1).optional(),
+});
+/** Exact residual-unknown identity to revalidate. */
+export const verifyUnknownResolutionInputSchema = z.strictObject({
+    unknown_id: prefixedDigestSchema("unk"),
+});