Class BinarySession

Owns the single active target shared by CLI and MCP adapters.

Target transitions are serialized because each client dispatches Hopper API work on its dedicated Python thread, and switching targets tears that bridge down. A failed switch recreates the previous target instead of retaining a client whose bridge was already shut down.

Implements

BinarySessionPort

Index

Constructors

constructor

new BinarySession(
provider: AnalysisProvider | AnalysisClientFactory,
): BinarySession
Parameters
- provider: AnalysisProvider | AnalysisClientFactory
Returns BinarySession
- Defined in src/application/BinarySession.ts:115

Properties

`Readonly`provider

provider: AnalysisProvider | AnalysisClientFactory

Methods

activeTarget

activeTarget(): BinaryTarget | undefined
Return the immutable artifact identity captured before Hopper launched.

Returns BinaryTarget | undefined
Implementation of BinarySessionPort.activeTarget
- Defined in src/application/BinarySession.ts:374

close

close(): Promise<Result<null, AnalysisError>>
Close the active target, if any.

Returns Promise<Result<null, AnalysisError>>
Implementation of BinarySessionPort.close
- Defined in src/application/BinarySession.ts:300

evidenceById

evidenceById(
    evidenceId: string,
):
    | {
        authority: | "shipped-artifact"
        | "controlled-replay"
        | "historical-reference"
        | "external-service"
        | "analyst-inference";
        confidence: "observed"
        | "derived"
        | "inferred";
        environment:
            | {
                architecture: string;
                id: string;
                isolation: "process"
                | "none"
                | "container"
                | "virtual-machine";
                platform: string;
            }
            | null;
        evidence_id: string;
        evidence_links: string[];
        limitations: string[];
        locations: (
            | { address: string; kind: "address" }
            | { end: string; kind: "address-range"; start: string }
            | { kind: "artifact-path"; path: string }
            | { kind: "file-offset"; offset: number }
            | { end: number; kind: "file-offset-range"; start: number }
        )[];
        normalized_result: JSONType;
        operation: string;
        parameters: Record<string, JSONType>;
        predicate_type: string;
        provider: { id: string; name: string; version: string | null };
        raw_result: JSONType;
        schema_version: 2;
        subject:
            | {
                architecture: "x86"
                | "x86_64"
                | "arm"
                | "arm64"
                | null;
                digest: { sha256: string };
                format:
                    | "hopper"
                    | "mach-o"
                    | "elf"
                    | "pe"
                    | "zip"
                    | "ipa"
                    | "apk"
                    | "asar"
                    | "dmg"
                    | "pkg"
                    | "plist"
                    | "javascript"
                    | "source-map"
                    | "unknown"
                    | "file"
                    | "directory"
                    | "mach-o-universal"
                    | "javascript-bundle"
                    | "entitlements";
                local_path: string;
                name: string;
            }
            | null;
    }
    | undefined
Read one detached session-owned Evidence record by semantic ID.
Parameters
- evidenceId: string
Returns
    | {
        authority: | "shipped-artifact"
        | "controlled-replay"
        | "historical-reference"
        | "external-service"
        | "analyst-inference";
        confidence: "observed"
        | "derived"
        | "inferred";
        environment:
            | {
                architecture: string;
                id: string;
                isolation: "process"
                | "none"
                | "container"
                | "virtual-machine";
                platform: string;
            }
            | null;
        evidence_id: string;
        evidence_links: string[];
        limitations: string[];
        locations: (
            | { address: string; kind: "address" }
            | { end: string; kind: "address-range"; start: string }
            | { kind: "artifact-path"; path: string }
            | { kind: "file-offset"; offset: number }
            | { end: number; kind: "file-offset-range"; start: number }
        )[];
        normalized_result: JSONType;
        operation: string;
        parameters: Record<string, JSONType>;
        predicate_type: string;
        provider: { id: string; name: string; version: string | null };
        raw_result: JSONType;
        schema_version: 2;
        subject:
            | {
                architecture: "x86"
                | "x86_64"
                | "arm"
                | "arm64"
                | null;
                digest: { sha256: string };
                format:
                    | "hopper"
                    | "mach-o"
                    | "elf"
                    | "pe"
                    | "zip"
                    | "ipa"
                    | "apk"
                    | "asar"
                    | "dmg"
                    | "pkg"
                    | "plist"
                    | "javascript"
                    | "source-map"
                    | "unknown"
                    | "file"
                    | "directory"
                    | "mach-o-universal"
                    | "javascript-bundle"
                    | "entitlements";
                local_path: string;
                name: string;
            }
            | null;
    }
    | undefined
Implementation of BinarySessionPort.evidenceById
- Defined in src/application/BinarySession.ts:172

execute

execute(
    name: AnalysisOperation,
    arguments_: Readonly<Record<string, JsonValue>>,
    options?: { signal?: AbortSignal },
): Promise<Result<AnalysisExecution, AnalysisError>>
Invoke a Hopper tool against the active target. Calls may overlap, but a pending target transition prevents new calls from entering until the transition has settled.
Parameters
- name: AnalysisOperation
- arguments_: Readonly<Record<string, JsonValue>>
- Optionaloptions: { signal?: AbortSignal }
Returns Promise<Result<AnalysisExecution, AnalysisError>>
Implementation of BinarySessionPort.execute
- Defined in src/application/BinarySession.ts:383

exportEvidenceBundle

exportEvidenceBundle(): {
    artifacts: {
        architecture: "x86"
        | "x86_64"
        | "arm"
        | "arm64"
        | null;
        digest: { sha256: string };
        format:
            | "hopper"
            | "mach-o"
            | "elf"
            | "pe"
            | "zip"
            | "ipa"
            | "apk"
            | "asar"
            | "dmg"
            | "pkg"
            | "plist"
            | "javascript"
            | "source-map"
            | "unknown"
            | "file"
            | "directory"
            | "mach-o-universal"
            | "javascript-bundle"
            | "entitlements";
    }[];
    bundle_version: 2;
    captures: { evidence_id: string; predicate_type: string }[];
    environments: {
        architecture: string;
        id: string;
        isolation: "process" | "none" | "container" | "virtual-machine";
        platform: string;
    }[];
    providers: { id: string; name: string; version: string
    | null }[];
    records: {
        authority:
            | "shipped-artifact"
            | "controlled-replay"
            | "historical-reference"
            | "external-service"
            | "analyst-inference";
        confidence: "observed"
        | "derived"
        | "inferred";
        environment:
            | {
                architecture: string;
                id: string;
                isolation: "process"
                | "none"
                | "container"
                | "virtual-machine";
                platform: string;
            }
            | null;
        evidence_id: string;
        evidence_links: string[];
        limitations: string[];
        locations: (
            | { address: string; kind: "address" }
            | { end: string; kind: "address-range"; start: string }
            | { kind: "artifact-path"; path: string }
            | { kind: "file-offset"; offset: number }
            | { end: number; kind: "file-offset-range"; start: number }
        )[];
        normalized_result: JSONType;
        operation: string;
        parameters: Record<string, JSONType>;
        predicate_type: string;
        provider: { id: string; name: string; version: string | null };
        raw_result: JSONType;
        schema_version: 2;
        subject:
            | {
                architecture: "x86"
                | "x86_64"
                | "arm"
                | "arm64"
                | null;
                digest: { sha256: string };
                format:
                    | "hopper"
                    | "mach-o"
                    | "elf"
                    | "pe"
                    | "zip"
                    | "ipa"
                    | "apk"
                    | "asar"
                    | "dmg"
                    | "pkg"
                    | "plist"
                    | "javascript"
                    | "source-map"
                    | "unknown"
                    | "file"
                    | "directory"
                    | "mach-o-universal"
                    | "javascript-bundle"
                    | "entitlements";
                local_path: string;
                name: string;
            }
            | null;
    }[];
    scenarios: {
        authority: "controlled-replay";
        evidence_id: string;
        operation: string;
    }[];
    unknowns: {
        contradicting_evidence_ids: string[];
        domain: string;
        mutation_evidence_ids: string[];
        previous_revision_digest: string
        | null;
        question: string;
        recommended_probes: { operation: string; rationale: string }[];
        registry_version: 1;
        relationships: {
            type: "depends-on" | "related-to" | "contradicts";
            unknown_id: string;
        }[];
        required_authority: | "shipped-artifact"
        | "controlled-replay"
        | "historical-reference"
        | "external-service"
        | "analyst-inference"
        | null;
        required_confidence: "observed"
        | "derived"
        | "inferred";
        required_environment:
            | {
                architecture: string
                | null;
                id: string | null;
                isolation: "process" | "none" | "container" | "virtual-machine" | null;
                platform: string | null;
            }
            | null;
        resolution: | {
            disposition: "verified";
            evidence_ids: string[];
            rationale: string;
        }
        | {
            disposition: "withdrawn"
            | "out-of-scope";
            evidence_ids: string[];
            rationale: string;
        }
        | null;
        revision: number;
        revision_digest: string;
        scope_digest: string
        | null;
        severity: "low" | "medium" | "high" | "critical";
        status: "open" | "investigating" | "blocked" | "contradicted" | "resolved";
        supporting_evidence_ids: string[];
        unknown_id: string;
    }[];
}
Return a deterministic snapshot without clearing session evidence.

Returns {
    artifacts: {
        architecture: "x86" | "x86_64" | "arm" | "arm64" | null;
        digest: { sha256: string };
        format:
            | "hopper"
            | "mach-o"
            | "elf"
            | "pe"
            | "zip"
            | "ipa"
            | "apk"
            | "asar"
            | "dmg"
            | "pkg"
            | "plist"
            | "javascript"
            | "source-map"
            | "unknown"
            | "file"
            | "directory"
            | "mach-o-universal"
            | "javascript-bundle"
            | "entitlements";
    }[];
    bundle_version: 2;
    captures: { evidence_id: string; predicate_type: string }[];
    environments: {
        architecture: string;
        id: string;
        isolation: "process" | "none" | "container" | "virtual-machine";
        platform: string;
    }[];
    providers: { id: string; name: string; version: string
    | null }[];
    records: {
        authority:
            | "shipped-artifact"
            | "controlled-replay"
            | "historical-reference"
            | "external-service"
            | "analyst-inference";
        confidence: "observed"
        | "derived"
        | "inferred";
        environment:
            | {
                architecture: string;
                id: string;
                isolation: "process"
                | "none"
                | "container"
                | "virtual-machine";
                platform: string;
            }
            | null;
        evidence_id: string;
        evidence_links: string[];
        limitations: string[];
        locations: (
            | { address: string; kind: "address" }
            | { end: string; kind: "address-range"; start: string }
            | { kind: "artifact-path"; path: string }
            | { kind: "file-offset"; offset: number }
            | { end: number; kind: "file-offset-range"; start: number }
        )[];
        normalized_result: JSONType;
        operation: string;
        parameters: Record<string, JSONType>;
        predicate_type: string;
        provider: { id: string; name: string; version: string | null };
        raw_result: JSONType;
        schema_version: 2;
        subject:
            | {
                architecture: "x86"
                | "x86_64"
                | "arm"
                | "arm64"
                | null;
                digest: { sha256: string };
                format:
                    | "hopper"
                    | "mach-o"
                    | "elf"
                    | "pe"
                    | "zip"
                    | "ipa"
                    | "apk"
                    | "asar"
                    | "dmg"
                    | "pkg"
                    | "plist"
                    | "javascript"
                    | "source-map"
                    | "unknown"
                    | "file"
                    | "directory"
                    | "mach-o-universal"
                    | "javascript-bundle"
                    | "entitlements";
                local_path: string;
                name: string;
            }
            | null;
    }[];
    scenarios: {
        authority: "controlled-replay";
        evidence_id: string;
        operation: string;
    }[];
    unknowns: {
        contradicting_evidence_ids: string[];
        domain: string;
        mutation_evidence_ids: string[];
        previous_revision_digest: string
        | null;
        question: string;
        recommended_probes: { operation: string; rationale: string }[];
        registry_version: 1;
        relationships: {
            type: "depends-on" | "related-to" | "contradicts";
            unknown_id: string;
        }[];
        required_authority: | "shipped-artifact"
        | "controlled-replay"
        | "historical-reference"
        | "external-service"
        | "analyst-inference"
        | null;
        required_confidence: "observed"
        | "derived"
        | "inferred";
        required_environment:
            | {
                architecture: string
                | null;
                id: string | null;
                isolation: "process" | "none" | "container" | "virtual-machine" | null;
                platform: string | null;
            }
            | null;
        resolution: | {
            disposition: "verified";
            evidence_ids: string[];
            rationale: string;
        }
        | {
            disposition: "withdrawn"
            | "out-of-scope";
            evidence_ids: string[];
            rationale: string;
        }
        | null;
        revision: number;
        revision_digest: string;
        scope_digest: string
        | null;
        severity: "low" | "medium" | "high" | "critical";
        status: "open" | "investigating" | "blocked" | "contradicted" | "resolved";
        supporting_evidence_ids: string[];
        unknown_id: string;
    }[];
}
Implementation of BinarySessionPort.exportEvidenceBundle
- Defined in src/application/BinarySession.ts:177

hasEvidence

hasEvidence(evidenceId: string): boolean
Check that comparison input Evidence is already session-owned.
Parameters
- evidenceId: string
Returns boolean
Implementation of BinarySessionPort.hasEvidence
- Defined in src/application/BinarySession.ts:167

importEvidenceBundle

importEvidenceBundle(
bundle: unknown,
): Result<number, EvidenceIntegrityError | EvidenceLimitError>
Atomically merge a validated evidence bundle into this session.
Parameters
- bundle: unknown
Returns Result<number, EvidenceIntegrityError | EvidenceLimitError>
Implementation of BinarySessionPort.importEvidenceBundle
- Defined in src/application/BinarySession.ts:182

listUnknowns

listUnknowns(
    filters?: {
        domain?: string;
        severity?: "low" | "medium" | "high" | "critical";
        status?:
            | "open"
            | "investigating"
            | "blocked"
            | "contradicted"
            | "resolved";
    },
): {
    contradicting_evidence_ids: string[];
    domain: string;
    mutation_evidence_ids: string[];
    previous_revision_digest: string
    | null;
    question: string;
    recommended_probes: { operation: string; rationale: string }[];
    registry_version: 1;
    relationships: {
        type: "depends-on" | "related-to" | "contradicts";
        unknown_id: string;
    }[];
    required_authority: | "shipped-artifact"
    | "controlled-replay"
    | "historical-reference"
    | "external-service"
    | "analyst-inference"
    | null;
    required_confidence: "observed"
    | "derived"
    | "inferred";
    required_environment:
        | {
            architecture: string
            | null;
            id: string | null;
            isolation: "process" | "none" | "container" | "virtual-machine" | null;
            platform: string | null;
        }
        | null;
    resolution: | {
        disposition: "verified";
        evidence_ids: string[];
        rationale: string;
    }
    | {
        disposition: "withdrawn"
        | "out-of-scope";
        evidence_ids: string[];
        rationale: string;
    }
    | null;
    revision: number;
    revision_digest: string;
    scope_digest: string
    | null;
    severity: "low" | "medium" | "high" | "critical";
    status: "open" | "investigating" | "blocked" | "contradicted" | "resolved";
    supporting_evidence_ids: string[];
    unknown_id: string;
}[]
Query stable current residual-unknown heads.
Parameters
- filters: {
      domain?: string;
      severity?: "low" | "medium" | "high" | "critical";
      status?: "open" | "investigating" | "blocked" | "contradicted" | "resolved";
  } = {}
Returns {
    contradicting_evidence_ids: string[];
    domain: string;
    mutation_evidence_ids: string[];
    previous_revision_digest: string | null;
    question: string;
    recommended_probes: { operation: string; rationale: string }[];
    registry_version: 1;
    relationships: {
        type: "depends-on" | "related-to" | "contradicts";
        unknown_id: string;
    }[];
    required_authority: | "shipped-artifact"
    | "controlled-replay"
    | "historical-reference"
    | "external-service"
    | "analyst-inference"
    | null;
    required_confidence: "observed"
    | "derived"
    | "inferred";
    required_environment:
        | {
            architecture: string
            | null;
            id: string | null;
            isolation: "process" | "none" | "container" | "virtual-machine" | null;
            platform: string | null;
        }
        | null;
    resolution: | {
        disposition: "verified";
        evidence_ids: string[];
        rationale: string;
    }
    | {
        disposition: "withdrawn"
        | "out-of-scope";
        evidence_ids: string[];
        rationale: string;
    }
    | null;
    revision: number;
    revision_digest: string;
    scope_digest: string
    | null;
    severity: "low" | "medium" | "high" | "critical";
    status: "open" | "investigating" | "blocked" | "contradicted" | "resolved";
    supporting_evidence_ids: string[];
    unknown_id: string;
}[]
Implementation of BinarySessionPort.listUnknowns
- Defined in src/application/BinarySession.ts:231

open

open(
    path: string,
    options?: {
        signal?: AbortSignal;
        targetKind?: "executable" | "database" | "archive" | "artifact";
    },
): Promise<Result<BinaryTarget, AnalysisError>>
Open or switch targets after draining calls against the current target. Returns the switch failure even if best-effort restoration also fails.
Parameters
- path: string
- options: {
  signal?: AbortSignal;
  targetKind?: "executable" | "database" | "archive" | "artifact";
  } = {}
Returns Promise<Result<BinaryTarget, AnalysisError>>
Implementation of BinarySessionPort.open
- Defined in src/application/BinarySession.ts:257

providerIdentity

providerIdentity(operation?: AnalysisOperation): ProviderIdentity
Identify the provider producing evidence for this session.
Parameters
- Optionaloperation: AnalysisOperation
Returns ProviderIdentity
Implementation of BinarySessionPort.providerIdentity
- Defined in src/application/BinarySession.ts:135

recordEvidence

recordEvidence(
    evidence: {
        authority:
            | "shipped-artifact"
            | "controlled-replay"
            | "historical-reference"
            | "external-service"
            | "analyst-inference";
        confidence: "observed"
        | "derived"
        | "inferred";
        environment:
            | {
                architecture: string;
                id: string;
                isolation: "process"
                | "none"
                | "container"
                | "virtual-machine";
                platform: string;
            }
            | null;
        evidence_id: string;
        evidence_links: string[];
        limitations: string[];
        locations: (
            | { address: string; kind: "address" }
            | { end: string; kind: "address-range"; start: string }
            | { kind: "artifact-path"; path: string }
            | { kind: "file-offset"; offset: number }
            | { end: number; kind: "file-offset-range"; start: number }
        )[];
        normalized_result: JSONType;
        operation: string;
        parameters: Record<string, JSONType>;
        predicate_type: string;
        provider: { id: string; name: string; version: string | null };
        raw_result: JSONType;
        schema_version: 2;
        subject:
            | {
                architecture: "x86"
                | "x86_64"
                | "arm"
                | "arm64"
                | null;
                digest: { sha256: string };
                format:
                    | "hopper"
                    | "mach-o"
                    | "elf"
                    | "pe"
                    | "zip"
                    | "ipa"
                    | "apk"
                    | "asar"
                    | "dmg"
                    | "pkg"
                    | "plist"
                    | "javascript"
                    | "source-map"
                    | "unknown"
                    | "file"
                    | "directory"
                    | "mach-o-universal"
                    | "javascript-bundle"
                    | "entitlements";
                local_path: string;
                name: string;
            }
            | null;
    },
): Result<
    "added"
    | "duplicate",
    EvidenceIntegrityError | EvidenceLimitError,
>
Add one successful public observation to the session ledger.
Parameters
- evidence: {
      authority:
          | "shipped-artifact"
          | "controlled-replay"
          | "historical-reference"
          | "external-service"
          | "analyst-inference";
      confidence: "observed"
      | "derived"
      | "inferred";
      environment:
          | {
              architecture: string;
              id: string;
              isolation: "process"
              | "none"
              | "container"
              | "virtual-machine";
              platform: string;
          }
          | null;
      evidence_id: string;
      evidence_links: string[];
      limitations: string[];
      locations: (
          | { address: string; kind: "address" }
          | { end: string; kind: "address-range"; start: string }
          | { kind: "artifact-path"; path: string }
          | { kind: "file-offset"; offset: number }
          | { end: number; kind: "file-offset-range"; start: number }
      )[];
      normalized_result: JSONType;
      operation: string;
      parameters: Record<string, JSONType>;
      predicate_type: string;
      provider: { id: string; name: string; version: string | null };
      raw_result: JSONType;
      schema_version: 2;
      subject:
          | {
              architecture: "x86"
              | "x86_64"
              | "arm"
              | "arm64"
              | null;
              digest: { sha256: string };
              format:
                  | "hopper"
                  | "mach-o"
                  | "elf"
                  | "pe"
                  | "zip"
                  | "ipa"
                  | "apk"
                  | "asar"
                  | "dmg"
                  | "pkg"
                  | "plist"
                  | "javascript"
                  | "source-map"
                  | "unknown"
                  | "file"
                  | "directory"
                  | "mach-o-universal"
                  | "javascript-bundle"
                  | "entitlements";
              local_path: string;
              name: string;
          }
          | null;
  }
Returns Result<"added" | "duplicate", EvidenceIntegrityError | EvidenceLimitError>
Implementation of BinarySessionPort.recordEvidence
- Defined in src/application/BinarySession.ts:157

recordEvidenceWithUnknown

recordEvidenceWithUnknown(
    evidence: {
        authority:
            | "shipped-artifact"
            | "controlled-replay"
            | "historical-reference"
            | "external-service"
            | "analyst-inference";
        confidence: "observed"
        | "derived"
        | "inferred";
        environment:
            | {
                architecture: string;
                id: string;
                isolation: "process"
                | "none"
                | "container"
                | "virtual-machine";
                platform: string;
            }
            | null;
        evidence_id: string;
        evidence_links: string[];
        limitations: string[];
        locations: (
            | { address: string; kind: "address" }
            | { end: string; kind: "address-range"; start: string }
            | { kind: "artifact-path"; path: string }
            | { kind: "file-offset"; offset: number }
            | { end: number; kind: "file-offset-range"; start: number }
        )[];
        normalized_result: JSONType;
        operation: string;
        parameters: Record<string, JSONType>;
        predicate_type: string;
        provider: { id: string; name: string; version: string | null };
        raw_result: JSONType;
        schema_version: 2;
        subject:
            | {
                architecture: "x86"
                | "x86_64"
                | "arm"
                | "arm64"
                | null;
                digest: { sha256: string };
                format:
                    | "hopper"
                    | "mach-o"
                    | "elf"
                    | "pe"
                    | "zip"
                    | "ipa"
                    | "apk"
                    | "asar"
                    | "dmg"
                    | "pkg"
                    | "plist"
                    | "javascript"
                    | "source-map"
                    | "unknown"
                    | "file"
                    | "directory"
                    | "mach-o-universal"
                    | "javascript-bundle"
                    | "entitlements";
                local_path: string;
                name: string;
            }
            | null;
    },
    input: {
        approved: true;
        contradicting_evidence_ids: string[];
        domain: string;
        question: string;
        recommended_probes: { operation: string; rationale: string }[];
        relationships: {
            type: "depends-on" | "related-to" | "contradicts";
            unknown_id: string;
        }[];
        required_authority: | "shipped-artifact"
        | "controlled-replay"
        | "historical-reference"
        | "external-service"
        | "analyst-inference"
        | null;
        required_confidence: "observed"
        | "derived"
        | "inferred";
        required_environment:
            | {
                architecture: string
                | null;
                id: string | null;
                isolation: "process" | "none" | "container" | "virtual-machine" | null;
                platform: string | null;
            }
            | null;
        severity: "low"
        | "medium"
        | "high"
        | "critical";
        supporting_evidence_ids: string[];
    },
): Result<
    | {
        contradicting_evidence_ids: string[];
        domain: string;
        mutation_evidence_ids: string[];
        previous_revision_digest: string
        | null;
        question: string;
        recommended_probes: { operation: string; rationale: string }[];
        registry_version: 1;
        relationships: {
            type: "depends-on" | "related-to" | "contradicts";
            unknown_id: string;
        }[];
        required_authority: | "shipped-artifact"
        | "controlled-replay"
        | "historical-reference"
        | "external-service"
        | "analyst-inference"
        | null;
        required_confidence: "observed"
        | "derived"
        | "inferred";
        required_environment:
            | {
                architecture: string
                | null;
                id: string | null;
                isolation: "process" | "none" | "container" | "virtual-machine" | null;
                platform: string | null;
            }
            | null;
        resolution: | {
            disposition: "verified";
            evidence_ids: string[];
            rationale: string;
        }
        | {
            disposition: "withdrawn"
            | "out-of-scope";
            evidence_ids: string[];
            rationale: string;
        }
        | null;
        revision: number;
        revision_digest: string;
        scope_digest: string
        | null;
        severity: "low" | "medium" | "high" | "critical";
        status: "open" | "investigating" | "blocked" | "contradicted" | "resolved";
        supporting_evidence_ids: string[];
        unknown_id: string;
    }
    | null,
    AnalysisError,
>
Atomically record derived Evidence and its approved residual unknown.
Parameters
- evidence: {
      authority:
          | "shipped-artifact"
          | "controlled-replay"
          | "historical-reference"
          | "external-service"
          | "analyst-inference";
      confidence: "observed"
      | "derived"
      | "inferred";
      environment:
          | {
              architecture: string;
              id: string;
              isolation: "process"
              | "none"
              | "container"
              | "virtual-machine";
              platform: string;
          }
          | null;
      evidence_id: string;
      evidence_links: string[];
      limitations: string[];
      locations: (
          | { address: string; kind: "address" }
          | { end: string; kind: "address-range"; start: string }
          | { kind: "artifact-path"; path: string }
          | { kind: "file-offset"; offset: number }
          | { end: number; kind: "file-offset-range"; start: number }
      )[];
      normalized_result: JSONType;
      operation: string;
      parameters: Record<string, JSONType>;
      predicate_type: string;
      provider: { id: string; name: string; version: string | null };
      raw_result: JSONType;
      schema_version: 2;
      subject:
          | {
              architecture: "x86"
              | "x86_64"
              | "arm"
              | "arm64"
              | null;
              digest: { sha256: string };
              format:
                  | "hopper"
                  | "mach-o"
                  | "elf"
                  | "pe"
                  | "zip"
                  | "ipa"
                  | "apk"
                  | "asar"
                  | "dmg"
                  | "pkg"
                  | "plist"
                  | "javascript"
                  | "source-map"
                  | "unknown"
                  | "file"
                  | "directory"
                  | "mach-o-universal"
                  | "javascript-bundle"
                  | "entitlements";
              local_path: string;
              name: string;
          }
          | null;
  }
- input: {
      approved: true;
      contradicting_evidence_ids: string[];
      domain: string;
      question: string;
      recommended_probes: { operation: string; rationale: string }[];
      relationships: {
          type: "depends-on" | "related-to" | "contradicts";
          unknown_id: string;
      }[];
      required_authority: | "shipped-artifact"
      | "controlled-replay"
      | "historical-reference"
      | "external-service"
      | "analyst-inference"
      | null;
      required_confidence: "observed"
      | "derived"
      | "inferred";
      required_environment:
          | {
              architecture: string
              | null;
              id: string | null;
              isolation: "process" | "none" | "container" | "virtual-machine" | null;
              platform: string | null;
          }
          | null;
      severity: "low"
      | "medium"
      | "high"
      | "critical";
      supporting_evidence_ids: string[];
  }
Returns Result<
    | {
        contradicting_evidence_ids: string[];
        domain: string;
        mutation_evidence_ids: string[];
        previous_revision_digest: string
        | null;
        question: string;
        recommended_probes: { operation: string; rationale: string }[];
        registry_version: 1;
        relationships: {
            type: "depends-on" | "related-to" | "contradicts";
            unknown_id: string;
        }[];
        required_authority: | "shipped-artifact"
        | "controlled-replay"
        | "historical-reference"
        | "external-service"
        | "analyst-inference"
        | null;
        required_confidence: "observed"
        | "derived"
        | "inferred";
        required_environment:
            | {
                architecture: string
                | null;
                id: string | null;
                isolation: "process" | "none" | "container" | "virtual-machine" | null;
                platform: string | null;
            }
            | null;
        resolution: | {
            disposition: "verified";
            evidence_ids: string[];
            rationale: string;
        }
        | {
            disposition: "withdrawn"
            | "out-of-scope";
            evidence_ids: string[];
            rationale: string;
        }
        | null;
        revision: number;
        revision_digest: string;
        scope_digest: string
        | null;
        severity: "low" | "medium" | "high" | "critical";
        status: "open" | "investigating" | "blocked" | "contradicted" | "resolved";
        supporting_evidence_ids: string[];
        unknown_id: string;
    }
    | null,
    AnalysisError,
>
Implementation of BinarySessionPort.recordEvidenceWithUnknown
- Defined in src/application/BinarySession.ts:197

recordUnknown

recordUnknown(
    input: {
        approved: true;
        contradicting_evidence_ids: string[];
        domain: string;
        question: string;
        recommended_probes: { operation: string; rationale: string }[];
        relationships: {
            type: "depends-on" | "related-to" | "contradicts";
            unknown_id: string;
        }[];
        required_authority: | "shipped-artifact"
        | "controlled-replay"
        | "historical-reference"
        | "external-service"
        | "analyst-inference"
        | null;
        required_confidence: "observed"
        | "derived"
        | "inferred";
        required_environment:
            | {
                architecture: string
                | null;
                id: string | null;
                isolation: "process" | "none" | "container" | "virtual-machine" | null;
                platform: string | null;
            }
            | null;
        severity: "low"
        | "medium"
        | "high"
        | "critical";
        supporting_evidence_ids: string[];
    },
): Result<
    {
        contradicting_evidence_ids: string[];
        domain: string;
        mutation_evidence_ids: string[];
        previous_revision_digest: string
        | null;
        question: string;
        recommended_probes: { operation: string; rationale: string }[];
        registry_version: 1;
        relationships: {
            type: "depends-on" | "related-to" | "contradicts";
            unknown_id: string;
        }[];
        required_authority: | "shipped-artifact"
        | "controlled-replay"
        | "historical-reference"
        | "external-service"
        | "analyst-inference"
        | null;
        required_confidence: "observed"
        | "derived"
        | "inferred";
        required_environment:
            | {
                architecture: string
                | null;
                id: string | null;
                isolation: "process" | "none" | "container" | "virtual-machine" | null;
                platform: string | null;
            }
            | null;
        resolution: | {
            disposition: "verified";
            evidence_ids: string[];
            rationale: string;
        }
        | {
            disposition: "withdrawn"
            | "out-of-scope";
            evidence_ids: string[];
            rationale: string;
        }
        | null;
        revision: number;
        revision_digest: string;
        scope_digest: string
        | null;
        severity: "low" | "medium" | "high" | "critical";
        status: "open" | "investigating" | "blocked" | "contradicted" | "resolved";
        supporting_evidence_ids: string[];
        unknown_id: string;
    },
    AnalysisError,
>
Create an approved residual unknown and immutable mutation evidence.
Parameters
- input: {
      approved: true;
      contradicting_evidence_ids: string[];
      domain: string;
      question: string;
      recommended_probes: { operation: string; rationale: string }[];
      relationships: {
          type: "depends-on" | "related-to" | "contradicts";
          unknown_id: string;
      }[];
      required_authority: | "shipped-artifact"
      | "controlled-replay"
      | "historical-reference"
      | "external-service"
      | "analyst-inference"
      | null;
      required_confidence: "observed"
      | "derived"
      | "inferred";
      required_environment:
          | {
              architecture: string
              | null;
              id: string | null;
              isolation: "process" | "none" | "container" | "virtual-machine" | null;
              platform: string | null;
          }
          | null;
      severity: "low"
      | "medium"
      | "high"
      | "critical";
      supporting_evidence_ids: string[];
  }
Returns Result<
    {
        contradicting_evidence_ids: string[];
        domain: string;
        mutation_evidence_ids: string[];
        previous_revision_digest: string
        | null;
        question: string;
        recommended_probes: { operation: string; rationale: string }[];
        registry_version: 1;
        relationships: {
            type: "depends-on" | "related-to" | "contradicts";
            unknown_id: string;
        }[];
        required_authority: | "shipped-artifact"
        | "controlled-replay"
        | "historical-reference"
        | "external-service"
        | "analyst-inference"
        | null;
        required_confidence: "observed"
        | "derived"
        | "inferred";
        required_environment:
            | {
                architecture: string
                | null;
                id: string | null;
                isolation: "process" | "none" | "container" | "virtual-machine" | null;
                platform: string | null;
            }
            | null;
        resolution: | {
            disposition: "verified";
            evidence_ids: string[];
            rationale: string;
        }
        | {
            disposition: "withdrawn"
            | "out-of-scope";
            evidence_ids: string[];
            rationale: string;
        }
        | null;
        revision: number;
        revision_digest: string;
        scope_digest: string
        | null;
        severity: "low" | "medium" | "high" | "critical";
        status: "open" | "investigating" | "blocked" | "contradicted" | "resolved";
        supporting_evidence_ids: string[];
        unknown_id: string;
    },
    AnalysisError,
>
Implementation of BinarySessionPort.recordUnknown
- Defined in src/application/BinarySession.ts:189

status

status(): JSONType
Describe the active binary session.

Returns JSONType
Implementation of BinarySessionPort.status
- Defined in src/application/BinarySession.ts:312

updateUnknown

updateUnknown(
    input: {
        approved: true;
        contradicting_evidence_ids: string[];
        expected_revision: number;
        recommended_probes: { operation: string; rationale: string }[];
        relationships: {
            type: "depends-on" | "related-to" | "contradicts";
            unknown_id: string;
        }[];
        required_authority: | "shipped-artifact"
        | "controlled-replay"
        | "historical-reference"
        | "external-service"
        | "analyst-inference"
        | null;
        required_confidence: "observed"
        | "derived"
        | "inferred";
        required_environment:
            | {
                architecture: string
                | null;
                id: string | null;
                isolation: "process" | "none" | "container" | "virtual-machine" | null;
                platform: string | null;
            }
            | null;
        resolution: | {
            disposition: "verified";
            evidence_ids: string[];
            rationale: string;
        }
        | {
            disposition: "withdrawn"
            | "out-of-scope";
            evidence_ids: string[];
            rationale: string;
        }
        | null;
        severity: "low"
        | "medium"
        | "high"
        | "critical";
        status: "open" | "investigating" | "blocked" | "contradicted" | "resolved";
        supporting_evidence_ids: string[];
        unknown_id: string;
    },
): Result<
    {
        contradicting_evidence_ids: string[];
        domain: string;
        mutation_evidence_ids: string[];
        previous_revision_digest: string
        | null;
        question: string;
        recommended_probes: { operation: string; rationale: string }[];
        registry_version: 1;
        relationships: {
            type: "depends-on" | "related-to" | "contradicts";
            unknown_id: string;
        }[];
        required_authority: | "shipped-artifact"
        | "controlled-replay"
        | "historical-reference"
        | "external-service"
        | "analyst-inference"
        | null;
        required_confidence: "observed"
        | "derived"
        | "inferred";
        required_environment:
            | {
                architecture: string
                | null;
                id: string | null;
                isolation: "process" | "none" | "container" | "virtual-machine" | null;
                platform: string | null;
            }
            | null;
        resolution: | {
            disposition: "verified";
            evidence_ids: string[];
            rationale: string;
        }
        | {
            disposition: "withdrawn"
            | "out-of-scope";
            evidence_ids: string[];
            rationale: string;
        }
        | null;
        revision: number;
        revision_digest: string;
        scope_digest: string
        | null;
        severity: "low" | "medium" | "high" | "critical";
        status: "open" | "investigating" | "blocked" | "contradicted" | "resolved";
        supporting_evidence_ids: string[];
        unknown_id: string;
    },
    AnalysisError,
>
Update one unknown using compare-and-swap revision semantics.
Parameters
- input: {
      approved: true;
      contradicting_evidence_ids: string[];
      expected_revision: number;
      recommended_probes: { operation: string; rationale: string }[];
      relationships: {
          type: "depends-on" | "related-to" | "contradicts";
          unknown_id: string;
      }[];
      required_authority: | "shipped-artifact"
      | "controlled-replay"
      | "historical-reference"
      | "external-service"
      | "analyst-inference"
      | null;
      required_confidence: "observed"
      | "derived"
      | "inferred";
      required_environment:
          | {
              architecture: string
              | null;
              id: string | null;
              isolation: "process" | "none" | "container" | "virtual-machine" | null;
              platform: string | null;
          }
          | null;
      resolution: | {
          disposition: "verified";
          evidence_ids: string[];
          rationale: string;
      }
      | {
          disposition: "withdrawn"
          | "out-of-scope";
          evidence_ids: string[];
          rationale: string;
      }
      | null;
      severity: "low"
      | "medium"
      | "high"
      | "critical";
      status: "open" | "investigating" | "blocked" | "contradicted" | "resolved";
      supporting_evidence_ids: string[];
      unknown_id: string;
  }
Returns Result<
    {
        contradicting_evidence_ids: string[];
        domain: string;
        mutation_evidence_ids: string[];
        previous_revision_digest: string
        | null;
        question: string;
        recommended_probes: { operation: string; rationale: string }[];
        registry_version: 1;
        relationships: {
            type: "depends-on" | "related-to" | "contradicts";
            unknown_id: string;
        }[];
        required_authority: | "shipped-artifact"
        | "controlled-replay"
        | "historical-reference"
        | "external-service"
        | "analyst-inference"
        | null;
        required_confidence: "observed"
        | "derived"
        | "inferred";
        required_environment:
            | {
                architecture: string
                | null;
                id: string | null;
                isolation: "process" | "none" | "container" | "virtual-machine" | null;
                platform: string | null;
            }
            | null;
        resolution: | {
            disposition: "verified";
            evidence_ids: string[];
            rationale: string;
        }
        | {
            disposition: "withdrawn"
            | "out-of-scope";
            evidence_ids: string[];
            rationale: string;
        }
        | null;
        revision: number;
        revision_digest: string;
        scope_digest: string
        | null;
        severity: "low" | "medium" | "high" | "critical";
        status: "open" | "investigating" | "blocked" | "contradicted" | "resolved";
        supporting_evidence_ids: string[];
        unknown_id: string;
    },
    AnalysisError,
>
Implementation of BinarySessionPort.updateUnknown
- Defined in src/application/BinarySession.ts:209

verifyUnknownResolution

verifyUnknownResolution(
    unknownId: string,
): Result<
    {
        truthVerified: boolean;
        unknown: {
            contradicting_evidence_ids: string[];
            domain: string;
            mutation_evidence_ids: string[];
            previous_revision_digest: string
            | null;
            question: string;
            recommended_probes: { operation: string; rationale: string }[];
            registry_version: 1;
            relationships: {
                type: "depends-on" | "related-to" | "contradicts";
                unknown_id: string;
            }[];
            required_authority: | "shipped-artifact"
            | "controlled-replay"
            | "historical-reference"
            | "external-service"
            | "analyst-inference"
            | null;
            required_confidence: "observed"
            | "derived"
            | "inferred";
            required_environment:
                | {
                    architecture: string
                    | null;
                    id: string | null;
                    isolation: "process" | "none" | "container" | "virtual-machine" | null;
                    platform: string | null;
                }
                | null;
            resolution: | {
                disposition: "verified";
                evidence_ids: string[];
                rationale: string;
            }
            | {
                disposition: "withdrawn"
                | "out-of-scope";
                evidence_ids: string[];
                rationale: string;
            }
            | null;
            revision: number;
            revision_digest: string;
            scope_digest: string
            | null;
            severity: "low" | "medium" | "high" | "critical";
            status:
                | "open"
                | "investigating"
                | "blocked"
                | "contradicted"
                | "resolved";
            supporting_evidence_ids: string[];
            unknown_id: string;
        };
        valid: boolean;
    },
    UnknownRegistryError,
>
Check whether current head is a bundle-valid resolved state.
Parameters
- unknownId: string
Returns Result<
    {
        truthVerified: boolean;
        unknown: {
            contradicting_evidence_ids: string[];
            domain: string;
            mutation_evidence_ids: string[];
            previous_revision_digest: string
            | null;
            question: string;
            recommended_probes: { operation: string; rationale: string }[];
            registry_version: 1;
            relationships: {
                type: "depends-on" | "related-to" | "contradicts";
                unknown_id: string;
            }[];
            required_authority: | "shipped-artifact"
            | "controlled-replay"
            | "historical-reference"
            | "external-service"
            | "analyst-inference"
            | null;
            required_confidence: "observed"
            | "derived"
            | "inferred";
            required_environment:
                | {
                    architecture: string
                    | null;
                    id: string | null;
                    isolation: "process" | "none" | "container" | "virtual-machine" | null;
                    platform: string | null;
                }
                | null;
            resolution: | {
                disposition: "verified";
                evidence_ids: string[];
                rationale: string;
            }
            | {
                disposition: "withdrawn"
                | "out-of-scope";
                evidence_ids: string[];
                rationale: string;
            }
            | null;
            revision: number;
            revision_digest: string;
            scope_digest: string
            | null;
            severity: "low" | "medium" | "high" | "critical";
            status:
                | "open"
                | "investigating"
                | "blocked"
                | "contradicted"
                | "resolved";
            supporting_evidence_ids: string[];
            unknown_id: string;
        };
        valid: boolean;
    },
    UnknownRegistryError,
>
Implementation of BinarySessionPort.verifyUnknownResolution
- Defined in src/application/BinarySession.ts:242

Class BinarySession

Implements

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns BinarySession

Properties

Readonlyprovider

Methods

activeTarget

Returns BinaryTarget | undefined

close

Returns Promise<Result<null, AnalysisError>>

evidenceById

Parameters

execute

Parameters

Returns Promise<Result<AnalysisExecution, AnalysisError>>

exportEvidenceBundle

hasEvidence

Parameters

Returns boolean

importEvidenceBundle

Parameters

Returns Result<number, EvidenceIntegrityError | EvidenceLimitError>

listUnknowns

Parameters

open

Parameters

Returns Promise<Result<BinaryTarget, AnalysisError>>

providerIdentity

Parameters

Returns ProviderIdentity

recordEvidence

Parameters

Returns Result<"added" | "duplicate", EvidenceIntegrityError | EvidenceLimitError>

recordEvidenceWithUnknown

Parameters

recordUnknown

Parameters

status

Returns JSONType

updateUnknown

Parameters

verifyUnknownResolution

Parameters

Settings

On This Page

`Readonly`provider