@cyvest/cyvest-js 6.1.2 → 7.0.0

package/dist/index.d.ts

@@ -1,403 +1,546 @@
-/**
- * Optional human-readable investigation name.
- */
-type InvestigationName = string | null;
-/**
- * Security level classification for findings, observables, and threat intelligence.
- *
- * Levels are ordered from lowest (NONE) to highest (MALICIOUS) severity.
- */
-type Level = "NONE" | "TRUSTED" | "INFO" | "SAFE" | "NOTABLE" | "SUSPICIOUS" | "MALICIOUS";
-type Justification = string | null;
-/**
- * List of whitelist entries applied to this investigation.
- */
-type Whitelists = InvestigationWhitelist[];
-/**
- * Append-only investigation audit log. Null when serialization disabled audit.
- */
-type AuditLog = AuditEvent[] | null;
-type Actor = string | null;
-type Reason = string | null;
-type Tool = string | null;
-type ObjectType = string | null;
-type ObjectKey = string | null;
-type Subtype = string | null;
-type Namespace = string | null;
-type Subtype1 = string | null;
-type Namespace1 = string | null;
-type Aliases = ObservableAlias[];
-type ThreatIntels = string[];
-/**
- * Direction of a relationship between observables.
- */
-type RelationshipDirection = "outbound" | "inbound" | "bidirectional";
-type Relationships = Relationship[];
-/**
- * Findings that currently link to this observable (navigation-only).
- */
-type FindingLinks = string[];
-/**
- * Controls how a Finding↔Observable link propagates across merged investigations.
- */
-type PropagationMode = "LOCAL_ONLY" | "GLOBAL";
-type ObservableLinks = ObservableLink[];
-type EvidenceLinks = EvidenceLink[];
-type ExternalId = string | null;
-type Uri = string | null;
-/**
- * Findings that currently link to this evidence (navigation-only).
- */
-type FindingLinks1 = string[];
-type Taxonomies = Taxonomy[];
-type Findings1 = string[];
-/**
- * Root observable type used during data extraction.
- */
-type RootType = ("file" | "artifact") | null;
-/**
- * Score calculation mode for observables.
- */
-type ScoreMode = "max" | "sum";
-/**
- * Schema for a complete serialized investigation.
- *
- * This model describes the output of `serialize_investigation()` from
- * `cyvest.io_serialization`. It is the top-level schema for exported investigations.
- *
- * Entity types reference the runtime models directly. When generating schemas with
- * `mode='serialization'`, Pydantic respects field_serializer decorators and produces
- * schemas matching the actual model_dump() output.
- */
-interface CyvestInvestigation {
-    schema_version?: "6.0.0";
-    /**
-     * Stable investigation identity (ULID).
-     */
-    investigation_id: string;
-    investigation_name?: InvestigationName;
-    /**
-     * Global investigation score.
-     */
-    score: number;
-    level: Level;
-    /**
-     * Whether the investigation is whitelisted.
-     */
-    whitelisted: boolean;
-    whitelists: Whitelists;
-    audit_log?: AuditLog;
-    observables: Observables;
-    findings: Findings;
-    evidences: Evidences;
-    threat_intels: ThreatIntels1;
-    enrichments: Enrichments;
-    tags: Tags;
-    stats: StatisticsSchema;
-    data_extraction: DataExtractionSchema;
-    /**
-     * Global investigation score formatted as fixed-point x.xx.
-     */
-    score_display: string;
-}
-/**
- * Represents a whitelist entry on an investigation.
- */
-interface InvestigationWhitelist {
-    identifier: string;
-    name: string;
-    justification?: Justification;
-    [k: string]: unknown;
-}
-/**
- * Centralized audit event for investigation-level changes.
- */
-interface AuditEvent {
-    event_id: string;
-    timestamp: string;
-    event_type: string;
-    actor?: Actor;
-    reason?: Reason;
-    tool?: Tool;
-    object_type?: ObjectType;
-    object_key?: ObjectKey;
-    details?: Details;
-    [k: string]: unknown;
-}
-interface Details {
-    [k: string]: unknown;
-}
-/**
- * Observables keyed by their unique key.
- */
-interface Observables {
-    [k: string]: Observable;
-}
-/**
- * Represents a cyber observable (IP, URL, domain, hash, etc.).
- *
- * Observables can be linked to threat intelligence, findings, and other observables
- * through relationships.
- */
-interface Observable {
-    type: string;
-    subtype?: Subtype;
-    namespace?: Namespace;
-    value: string;
-    internal: boolean;
-    whitelisted: boolean;
-    comment: string;
-    extra: Extra;
-    score: number;
-    level: Level;
-    aliases?: Aliases;
-    occurrence_count?: number;
-    threat_intels: ThreatIntels;
-    relationships: Relationships;
-    key: string;
-    finding_links: FindingLinks;
-    score_display: string;
-    [k: string]: unknown;
-}
-interface Extra {
-    [k: string]: unknown;
-}
-/**
- * Source observable identity attached to a canonical observable.
- */
-interface ObservableAlias {
-    type: string;
-    subtype?: Subtype1;
-    namespace?: Namespace1;
-    value: string;
-    count?: number;
-    [k: string]: unknown;
-}
-/**
- * Represents a relationship between observables.
- */
-interface Relationship {
-    target_key: string;
-    relationship_type: string;
-    direction: RelationshipDirection;
-    [k: string]: unknown;
-}
-/**
- * Findings keyed by their unique key.
- */
-interface Findings {
-    [k: string]: Finding;
-}
-/**
- * Represents a verification step in the investigation.
- *
- * A finding validates a specific aspect of the data under investigation
- * and contributes to the overall investigation score.
- */
-interface Finding {
-    finding_name: string;
-    description: string;
-    comment: string;
-    extra: Extra1;
-    score: number;
-    level: Level;
-    origin_investigation_id: string;
-    observable_links: ObservableLinks;
-    evidence_links: EvidenceLinks;
-    key: string;
-    score_display: string;
-    [k: string]: unknown;
-}
-interface Extra1 {
-    [k: string]: unknown;
-}
-/**
- * Edge metadata for a Finding↔Observable association.
- */
-interface ObservableLink {
-    observable_key: string;
-    propagation_mode?: PropagationMode;
-}
-/**
- * Edge metadata for a Finding↔Evidence association.
- */
-interface EvidenceLink {
-    evidence_key: string;
-}
-/**
- * Evidence objects keyed by their unique key.
- */
-interface Evidences {
-    [k: string]: Evidence;
-}
-/**
- * Structured material supporting one or more findings.
- */
-interface Evidence {
-    type: string;
-    title: string;
-    description: string;
-    source: string;
-    external_id: ExternalId;
-    content: unknown;
-    uri: Uri;
-    captured_at: string;
-    extra: Extra2;
-    key: string;
-    finding_links: FindingLinks1;
-    [k: string]: unknown;
-}
-interface Extra2 {
-    [k: string]: unknown;
-}
-/**
- * Threat intelligence entries keyed by their unique key.
- */
-interface ThreatIntels1 {
-    [k: string]: ThreatIntel;
-}
-/**
- * Represents threat intelligence from an external source.
- *
- * Threat intelligence provides verdicts about observables from sources
- * like VirusTotal, URLScan.io, etc.
- */
-interface ThreatIntel {
-    source: string;
-    observable_key: string;
-    comment: string;
-    extra: Extra3;
-    score: number;
-    level: Level;
-    taxonomies: Taxonomies;
-    key: string;
-    score_display: string;
-    [k: string]: unknown;
-}
-interface Extra3 {
-    [k: string]: unknown;
-}
-/**
- * Represents a structured taxonomy entry for threat intelligence.
- */
-interface Taxonomy {
-    level: Level;
-    name: string;
-    value: string;
-}
-/**
- * Enrichment entries keyed by their unique key.
+//#region src/types.generated.d.ts
+export type RootKey = string | null;
+export type FragmentIds = string[];
+export type OccurredAt = string | null;
+/**
+ * Family a source belongs to, used by the policy to weigh its reliability.
  */
-interface Enrichments {
-    [k: string]: Enrichment;
-}
+export type SourceClass = "vendor_feed" | "sandbox" | "osint" | "internal_tool" | "org_analyst" | "org_policy" | "unknown";
+export type ExternalId = string | null;
+export type EvidenceKeys = string[];
+export type Subtype = string | null;
+export type Namespace = string | null;
+export type Subtype1 = string | null;
+export type Namespace1 = string | null;
+export type Aliases = ObservableAlias[];
+export type OccurredAt1 = string | null;
+export type ExternalId1 = string | null;
+export type EvidenceKeys1 = string[];
 /**
- * Represents structured data enrichment for the investigation.
+ * The analyst pivot that produced the target from the source.
  *
- * Enrichments store arbitrary structured data that provides additional
- * context but doesn't directly contribute to scoring.
- */
-interface Enrichment {
-    name: string;
-    data: Data;
-    context: string;
-    key: string;
-    [k: string]: unknown;
-}
-interface Data {
-    [k: string]: unknown;
-}
-/**
- * Tags keyed by their unique key.
- */
-interface Tags {
-    [k: string]: Tag;
-}
-/**
- * Groups findings for categorical organization.
+ * Direction is implied: ``source_key`` is the parent, ``target_key`` the child. ``RELATED_TO``
+ * is symmetric and excluded from propagation, which makes v6's ``EXTRACTION`` +
+ * ``BIDIRECTIONAL`` combination inexpressible.
+ */
+export type RelationKind = "extraction" | "pivot" | "related-to";
+export type ObservedAt = string | null;
+/**
+ * Direction of a judgment, and the displayed level — they are the same thing.
  *
- * Tags allow structuring the investigation into logical sections
- * with aggregated scores and levels. Hierarchy is automatic based on
- * the ":" delimiter in tag names (e.g., "header:auth:dkim").
- */
-interface Tag {
-    name: string;
-    description?: string;
-    findings: Findings1;
-    key: string;
-    /**
-     * Calculate the score from direct findings only (no hierarchy).
-     *
-     * For hierarchical aggregation (including descendant tags), use
-     * Investigation.get_tag_aggregated_score() or TagProxy.get_aggregated_score().
-     *
-     * Returns:
-     *     Total score from direct findings
-     */
-    direct_score: number;
-    direct_level: Level;
-}
-/**
- * Schema for investigation statistics.
+ * v7 merges the former ``Level`` into ``Verdict``. The five values line up one-for-one with
+ * the score bands ``basic-v1`` inherits from v6 (``< 0``, ``= 0``, ``]0,3[``, ``[3,5[``,
+ * ``>= 5``), which makes a verdict/level divergence structurally impossible.
+ *
+ * Those bands are ``basic-v1``'s convention, **not** part of the enum's contract: a
+ * probabilistic engine maps its own posterior thresholds onto the same labels.
+ *
+ * Two v6 levels deliberately left this axis: ``NONE`` became :class:`Status` and ``TRUSTED``
+ * became a :class:`DecisionKind` (or plain ``SAFE`` when it was merely a negative score).
+ */
+export type Verdict = "SAFE" | "INFO" | "NOTABLE" | "SUSPICIOUS" | "MALICIOUS";
+export type Weight = number | null;
+export type OccurredAt2 = string | null;
+export type ExternalId2 = string | null;
+export type EvidenceKeys2 = string[];
+export type ObservedAt1 = string | null;
+export type Labels = Label[];
+export type Taxonomies = string[];
+export type OccurredAt3 = string | null;
+export type ExternalId3 = string | null;
+export type EvidenceKeys3 = string[];
+export type Uri = string | null;
+export type CapturedAt = string | null;
+export type Weight1 = number | null;
+export type OccurredAt4 = string | null;
+export type ExternalId4 = string | null;
+export type EvidenceKeys4 = string[];
+/**
+ * Whether a finding takes part in the evaluation at all.
+ *
+ * Anything other than ``EVALUATED`` is excluded from the score *and* from aggregation
+ * denominators, while staying visible in the report.
+ */
+export type Status = "NOT_APPLICABLE" | "PENDING" | "EVALUATED";
+/**
+ * How a finding enters the investigation total. :class:`Status` says *whether*, this says *how*.
+ *
+ * ``ADDITIVE`` is every finding v6 ever had: a term of the sum.
+ *
+ * ``FLOOR`` and ``CEILING`` are the two halves of a **conclusion** — typically an analysis that
+ * read the other findings. Neither is a term: a floor raises the total just enough to reach the
+ * verdict it asserts, a ceiling lowers it just enough. Both add nothing once the investigation
+ * is already there, so conclusions never compound and several analysers may conclude on the
+ * same case without inflating — or deflating — each other.
+ *
+ * A ceiling is what states a **declared benign context**: an awareness campaign, a sanctioned
+ * pentest window, an authorised scanner. Without it the model could force a case up but never
+ * down, and the only way to say "whatever the evidence, this is benign" would be to guess a
+ * large negative weight — the v6 mistake.
+ *
+ * The band a verdict maps to is ``basic-v1``'s convention, like every other number here — see
+ * :mod:`cyvest.evaluation.projection`.
+ */
+export type Effect = "ADDITIVE" | "FLOOR" | "CEILING";
+/**
+ * What a Finding→Observable link scores on.
+ *
+ * One question, three answers, none of which depends on how the run was threaded:
+ *
+ * - ``OBSERVABLE`` — the observable as it stands, whoever contributed to it;
+ * - ``SIGNALS`` — the signals the link names, and nothing else, which is how a finding that
+ *   fetched its own threat intel holds that value while the observable keeps accumulating;
+ * - ``NONE`` — nothing: the edge is kept for the graph and the narrative, but it is inert.
+ *
+ * v7.0 briefly carried a fourth, ``FRAGMENT``, gating the observable on the fragment that wrote
+ * each fact. It was dropped before release: it damped a merged total but never a local one, so
+ * the same rules scored differently depending on whether enrichment ran in its own worker.
+ * ``SIGNALS`` states that intent directly, and ``NONE`` covers the inert link it was standing in
+ * for when migrating v6 documents.
+ */
+export type LinkBasis = "OBSERVABLE" | "SIGNALS" | "NONE";
+export type SignalKeys = string[];
+export type ObservableLinks = ObservableLink[];
+export type Labels1 = Label[];
+/**
+ * A MITRE ATT&CK Enterprise tactic — the phase of the kill chain a finding demonstrates.
+ *
+ * Kebab-case values, in kill-chain order. A tactic is a classification the timeline displays,
+ * never a term the engine scores: whether the activity is malicious is the verdict's job.
+ */
+export type Tactic = "reconnaissance" | "resource-development" | "initial-access" | "execution" | "persistence" | "privilege-escalation" | "defense-evasion" | "credential-access" | "discovery" | "lateral-movement" | "collection" | "command-and-control" | "exfiltration" | "impact";
+export type OccurredAt5 = string | null;
+export type ExternalId5 = string | null;
+export type EvidenceKeys5 = string[];
+/**
+ * A named override of the computation.
+ *
+ * Forcing a score has to be a declared act — never the side effect of an inflated weight.
  *
- * Mirrors the output of `InvestigationStats.get_summary()`.
- */
-interface StatisticsSchema {
-    total_observables: number;
-    internal_observables: number;
-    external_observables: number;
-    whitelisted_observables: number;
-    observables_by_type?: ObservablesByType;
-    observables_by_level?: ObservablesByLevel;
-    observables_by_type_and_level?: ObservablesByTypeAndLevel;
-    total_findings: number;
-    applied_findings: number;
-    findings_by_level?: FindingsByLevel;
-    total_evidences: number;
-    evidences_by_type?: EvidencesByType;
-    evidences_by_source?: EvidencesBySource;
-    total_threat_intel: number;
-    threat_intel_by_source?: ThreatIntelBySource;
-    threat_intel_by_level?: ThreatIntelByLevel;
-    total_tags: number;
-}
-interface ObservablesByType {
-    [k: string]: number;
-}
-interface ObservablesByLevel {
-    [k: string]: number;
-}
-interface ObservablesByTypeAndLevel {
-    [k: string]: {
-        [k: string]: number;
-    };
-}
-interface FindingsByLevel {
-    [k: string]: string[];
-}
-interface EvidencesByType {
-    [k: string]: number;
-}
-interface EvidencesBySource {
-    [k: string]: number;
-}
-interface ThreatIntelBySource {
-    [k: string]: number;
-}
-interface ThreatIntelByLevel {
-    [k: string]: number;
-}
-/**
- * Schema for data extraction metadata.
+ * The kind states the **intent**; the mechanism follows from the family of the target, which
+ * the key already carries. An earlier design enumerated one value per ``(intent, family)``
+ * pair — ``ALLOWLISTED``/``BLOCKLISTED``/``CONFIRMED``/``DISMISSED`` — and then needed a
+ * validator to forbid the half of that product which made no sense. An enum requiring a
+ * validator to reject half its combinations encodes one axis too many: the family is the
+ * target's business, not the decision's.
+ *
+ * The domain vocabulary survives untouched on the façade (``allowlist``, ``blocklist``,
+ * ``confirm``, ``dismiss``), where it belongs.
+ */
+export type DecisionKind = "UPHOLD" | "REFUTE" | "VACATED";
+export type OccurredAt6 = string | null;
+export type ExternalId6 = string | null;
+export type EvidenceKeys6 = string[];
+export type FindingKeys = string[];
+export type Score = number | null;
+export type Contributions = Contribution[];
+export type Score1 = number | null;
+export type Contributions1 = Contribution[];
+export type Score2 = number | null;
+export type Contributions2 = Contribution[];
+/**
+ * A complete serialized investigation.
+ */
+export interface InvestigationSchema {
+  schema_version?: string;
+  header: InvestigationHeader;
+  policy_version?: string;
+  engine_id?: string;
+  facts?: FactsSchema;
+  decisions?: Decisions;
+  tags?: Tags;
+  report: Report;
+}
+/**
+ * What used to be a ``Case`` fact: metadata about the store rather than a fact inside it.
+ *
+ * ``engine_id`` is denormalized here so an investigation stays replayable identically years
+ * later, even after a newer stable engine ships.
  */
-interface DataExtractionSchema {
-    root_type?: RootType;
-    score_mode_obs: ScoreMode;
-}
-
-declare function parseCyvest(json: unknown): CyvestInvestigation;
-declare function isCyvest(json: unknown): json is CyvestInvestigation;
-
+export interface InvestigationHeader {
+  investigation_id: string;
+  name?: string;
+  root_key?: RootKey;
+  opened_at?: string;
+  policy_version?: string;
+  engine_id?: string;
+  fragment_ids?: FragmentIds;
+  [k: string]: unknown;
+}
+/**
+ * The fact collections, each keyed by its semantic key.
+ */
+export interface FactsSchema {
+  observables?: Observables;
+  relations?: Relations;
+  signals?: Signals;
+  evidences?: Evidences;
+  findings?: Findings;
+}
+export interface Observables {
+  [k: string]: Observable;
+}
+/**
+ * A cyber observable. Identity is ``(type, subtype, namespace, value)``, nothing else.
+ */
+export interface Observable {
+  key: string;
+  seq: string;
+  asserted_at: string;
+  occurred_at?: OccurredAt;
+  source: SourceRef;
+  fragment_id: string;
+  external_id?: ExternalId;
+  evidence_keys?: EvidenceKeys;
+  type: string;
+  subtype?: Subtype;
+  namespace?: Namespace;
+  value: string;
+  internal?: boolean;
+  comment?: string;
+  extra?: Extra;
+  aliases?: Aliases;
+  occurrences?: Occurrences;
+}
+/**
+ * Who or what asserted a fact.
+ */
+export interface SourceRef {
+  name: string;
+  source_class?: SourceClass;
+  [k: string]: unknown;
+}
+export interface Extra {
+  [k: string]: unknown;
+}
+/**
+ * A source identity that resolved to a canonical observable.
+ */
+export interface ObservableAlias {
+  type: string;
+  subtype?: Subtype1;
+  namespace?: Namespace1;
+  value: string;
+  counts?: Counts;
+  [k: string]: unknown;
+}
+export interface Counts {
+  [k: string]: number;
+}
+export interface Occurrences {
+  [k: string]: number;
+}
+export interface Relations {
+  [k: string]: Relation;
+}
+/**
+ * A directed edge between two observables, labelled by the analyst pivot that produced it.
+ */
+export interface Relation {
+  key: string;
+  seq: string;
+  asserted_at: string;
+  occurred_at?: OccurredAt1;
+  source: SourceRef;
+  fragment_id: string;
+  external_id?: ExternalId1;
+  evidence_keys?: EvidenceKeys1;
+  source_key: string;
+  target_key: string;
+  kind?: RelationKind;
+  observed_at?: ObservedAt;
+  confidence?: number;
+  comment?: string;
+}
+export interface Signals {
+  [k: string]: ThreatIntel;
+}
+/**
+ * A verdict from a threat-intelligence source.
+ *
+ * Identity is ``(source, subject_key)``, so a source re-asserting the same observable updates
+ * in place instead of piling up duplicates. Pass ``external_id`` to keep history on purpose.
+ */
+export interface ThreatIntel {
+  verdict?: Verdict;
+  confidence?: number;
+  weight?: Weight;
+  key: string;
+  seq: string;
+  asserted_at: string;
+  occurred_at?: OccurredAt2;
+  source: SourceRef;
+  fragment_id: string;
+  external_id?: ExternalId2;
+  evidence_keys?: EvidenceKeys2;
+  subject_key: string;
+  kind?: "threat_intel";
+  observed_at?: ObservedAt1;
+  labels?: Labels;
+  payload?: Payload;
+  source_class?: SourceClass;
+  taxonomies?: Taxonomies;
+  comment?: string;
+}
+/**
+ * A typed tag on a fact: ``axis`` says what kind of statement ``value`` makes.
+ */
+export interface Label {
+  axis: string;
+  value: string;
+  [k: string]: unknown;
+}
+export interface Payload {
+  [k: string]: unknown;
+}
+export interface Evidences {
+  [k: string]: Evidence;
+}
+/**
+ * A captured artefact: an API response, a header dump, an enrichment payload.
+ */
+export interface Evidence {
+  key: string;
+  seq: string;
+  asserted_at: string;
+  occurred_at?: OccurredAt3;
+  source: SourceRef;
+  fragment_id: string;
+  external_id?: ExternalId3;
+  evidence_keys?: EvidenceKeys3;
+  evidence_type: string;
+  title?: string;
+  content?: Content;
+  uri?: Uri;
+  captured_at?: CapturedAt;
+}
+export interface Content {
+  [k: string]: unknown;
+}
+export interface Findings {
+  [k: string]: Finding;
+}
+/**
+ * A rule outcome. Identity is ``rule_id`` alone, plus ``external_id`` when one is given.
+ *
+ * A finding names no subject: what it is about is its ``observable_links``, which are also what
+ * it scores on. Use ``external_id`` when the same rule must yield several findings — typically
+ * once per observable, ``external_id=url.key``.
+ *
+ * A finding that describes an activity is **dated** through the envelope's ``occurred_at`` —
+ * when the activity happened, as opposed to when the rule fired — and may name the ATT&CK
+ * ``tactic`` it demonstrates. Both are what the timeline reads; neither enters the score.
+ */
+export interface Finding {
+  verdict?: Verdict;
+  confidence?: number;
+  weight?: Weight1;
+  key: string;
+  seq: string;
+  asserted_at: string;
+  occurred_at?: OccurredAt4;
+  source: SourceRef;
+  fragment_id: string;
+  external_id?: ExternalId4;
+  evidence_keys?: EvidenceKeys4;
+  rule_id: string;
+  rule_version?: string;
+  name?: string;
+  comment?: string;
+  status?: Status;
+  effect?: Effect;
+  observable_links?: ObservableLinks;
+  labels?: Labels1;
+  tactic?: Tactic | null;
+  extra?: Extra1;
+}
+/**
+ * A link from a finding to one of its observables, with the basis it is evaluated on.
+ *
+ * Basis is **per link**, exactly like v6's ``propagation_mode``: a finding may mix bases, and
+ * may even link the same observable twice under two of them. Deduplication is on the triple
+ * ``(observable_key, basis, signal_keys)``.
+ *
+ * ``signal_keys`` is sorted and deduplicated so that two links naming the same signals in a
+ * different order are the same link, and merging stays idempotent.
+ */
+export interface ObservableLink {
+  observable_key: string;
+  basis?: LinkBasis;
+  signal_keys?: SignalKeys;
+  [k: string]: unknown;
+}
+export interface Extra1 {
+  [k: string]: unknown;
+}
+export interface Decisions {
+  [k: string]: Decision;
+}
+/**
+ * A human (or automated) call that overrides the computed result for one target.
+ *
+ * ``UPHOLD`` forces the target to the policy floor, ``REFUTE`` neutralises it, ``VACATED``
+ * withdraws a previous stance and restores the computed value. How each is applied depends on
+ * the family of the target — an observable is bounded, a claim is taken out of the count — but
+ * that is the engine's dispatch, not a second axis of this model.
+ *
+ * ``justification`` is required: an override whose reason is optional is an override that
+ * cannot be audited, which defeats the point of recording it as a fact at all.
+ */
+export interface Decision {
+  key: string;
+  seq: string;
+  asserted_at: string;
+  occurred_at?: OccurredAt5;
+  source: SourceRef;
+  fragment_id: string;
+  external_id?: ExternalId5;
+  evidence_keys?: EvidenceKeys5;
+  target_key: string;
+  kind: DecisionKind;
+  justification: string;
+}
+export interface Tags {
+  [k: string]: Tag;
+}
+/**
+ * A label grouping findings. Merging two tags unions their finding keys.
+ */
+export interface Tag {
+  key: string;
+  seq: string;
+  asserted_at: string;
+  occurred_at?: OccurredAt6;
+  source: SourceRef;
+  fragment_id: string;
+  external_id?: ExternalId6;
+  evidence_keys?: EvidenceKeys6;
+  name: string;
+  description?: string;
+  finding_keys?: FindingKeys;
+}
+/**
+ * A full evaluation. Derived, never stored on the facts, recomputed from them.
+ */
+export interface Report {
+  engine_id: string;
+  policy_version: string;
+  investigation: InvestigationResult;
+  findings?: Findings1;
+  observables?: Observables1;
+  [k: string]: unknown;
+}
+/**
+ * The investigation-level verdict.
+ */
+export interface InvestigationResult {
+  key: string;
+  verdict?: Verdict;
+  confidence?: number;
+  score?: Score;
+  contributions?: Contributions;
+  suppressed_by_decision?: boolean;
+  raw?: Raw;
+  [k: string]: unknown;
+}
+/**
+ * One named term that fed a result, kept so the report can explain itself.
+ */
+export interface Contribution {
+  source_key: string;
+  label: string;
+  value: number;
+  retained?: boolean;
+  detail?: string;
+  [k: string]: unknown;
+}
+export interface Raw {
+  [k: string]: unknown;
+}
+export interface Findings1 {
+  [k: string]: FindingResult;
+}
+/**
+ * A finding's verdict.
+ *
+ * ``own_term_suppressed`` flags that the rule's own claim was overridden by a stronger link —
+ * a contradiction worth surfacing rather than silently dropping.
+ *
+ * Three combinations of ``(counted, score)`` are meaningful, and a consumer must not conflate
+ * the last two:
+ *
+ * - ``(True, float)`` — an additive finding, a term of the total;
+ * - ``(False, None)`` — dismissed or not evaluated: visible, but out of the evaluation;
+ * - ``(True, None)`` — a conclusion (``effect`` is ``FLOOR`` or ``CEILING``): it takes part, but
+ *   it has no magnitude of its own. Its effect is a bound on the investigation total, reported
+ *   as a contribution of :class:`InvestigationResult`.
+ */
+export interface FindingResult {
+  key: string;
+  verdict?: Verdict;
+  confidence?: number;
+  score?: Score1;
+  contributions?: Contributions1;
+  suppressed_by_decision?: boolean;
+  raw?: Raw1;
+  status?: Status;
+  effect?: Effect;
+  own_term_suppressed?: boolean;
+  counted?: boolean;
+  [k: string]: unknown;
+}
+export interface Raw1 {
+  [k: string]: unknown;
+}
+export interface Observables1 {
+  [k: string]: ObservableResult;
+}
+/**
+ * An observable's verdict. One per observable: the graph holds every fact anyone contributed.
+ */
+export interface ObservableResult {
+  key: string;
+  verdict?: Verdict;
+  confidence?: number;
+  score?: Score2;
+  contributions?: Contributions2;
+  suppressed_by_decision?: boolean;
+  raw?: Raw2;
+  [k: string]: unknown;
+}
+export interface Raw2 {
+  [k: string]: unknown;
+}
+//#endregion
+//#region src/types.d.ts
+type Investigation = InvestigationSchema;
+type Observable$1 = Observable;
+type Relation$1 = Relation;
+type ThreatIntel$1 = ThreatIntel;
+type Evidence$1 = Evidence;
+type Finding$1 = Finding;
+type Decision$1 = Decision;
+type Tag$1 = Tag;
+type ObservableResult$1 = ObservableResult;
+type FindingResult$1 = FindingResult;
+type InvestigationResult$1 = InvestigationResult;
+//#endregion
+//#region src/helpers.d.ts
+export declare const SCHEMA_VERSION = "7.0.0";
+/**
+ * Read the declared schema version, falling back to `"5"` for anything unversioned.
+ *
+ * A document with no `schema_version` is a pre-v7 document, not a current one: `schema_version`
+ * is not in the schema's `required` list, so defaulting it to `SCHEMA_VERSION` would wave every
+ * legacy payload straight through. Python's `detect_schema_version` makes the same choice.
+ */
+export declare function detectSchemaVersion(json: unknown): string;
+/** Upward compatibility only: read older documents, never newer ones. */
+export declare function assertReadableVersion(version: string): void;
+export declare function parseCyvest(json: unknown): Investigation;
+export declare function isCyvest(json: unknown): json is Investigation;
+//#endregion
+//#region src/keys.d.ts
 /**
  * Key generation utilities for Cyvest objects.
  *
@@ -407,7 +550,9 @@ declare function isCyvest(json: unknown): json is CyvestInvestigation;
 /**
  * Key type prefixes used in Cyvest.
  */
-type KeyType = "obs" | "fnd" | "evd" | "ti" | "enr" | "tag";
+export type KeyType = "obs" | "fnd" | "evd" | "sig" | "rel" | "dec" | "tag";
+/** Every prefix a v7 document can carry. `enr:` is gone — enrichments are evidence now. */
+export declare const KEY_PREFIXES: readonly KeyType[];
 /**
  * Generate a unique key for an observable.
  *
@@ -423,57 +568,53 @@ type KeyType = "obs" | "fnd" | "evd" | "ti" | "enr" | "tag";
  * // => "obs:ipv4:192.168.1.1"
  * ```
  */
-declare function generateObservableKey(obsType: string, value: string, subtype?: string, namespace?: string): string;
+export declare function generateObservableKey(obsType: string, value: string, subtype?: string, namespace?: string): string;
 /**
- * Generate a unique key for a finding.
+ * Generate a finding key.
  *
- * Format: fnd:{finding_name}
+ * Format: `fnd:{rule_id}`, or `fnd:{rule_id}:{external_id}`.
  *
- * @param findingName - Name of the finding
- * @returns Unique finding key
+ * A finding is identified by the rule that produced it. Running the same rule on several
+ * observables means several findings, so pass an `externalId` to keep them apart — usually the
+ * observable key.
  *
  * @example
  * ```ts
- * generateFindingKey("sender_verification")
- * // => "fnd:sender_verification"
+ * generateFindingKey("url_in_body")
+ * // => "fnd:url_in_body"
  * ```
  */
-declare function generateFindingKey(findingName: string): string;
+export declare function generateFindingKey(ruleId: string, externalId?: string): string;
 /**
- * Generate a unique key for threat intelligence.
- *
- * Format: ti:{normalized_source}:{observable_key}
+ * Generate an observable-signal key.
  *
- * @param source - Name of the threat intel source
- * @param observableKey - Key of the related observable
- * @returns Unique threat intel key
+ * Format: `sig:{source}:{subject_key}`. The prefix names the *family*, not its first member:
+ * v6's `ti:` would have locked every future signal kind behind a threat-intel name.
  *
  * @example
  * ```ts
- * generateThreatIntelKey("virustotal", "obs:ipv4:192.168.1.1")
- * // => "ti:virustotal:obs:ipv4:192.168.1.1"
+ * generateSignalKey("virustotal", "obs:ipv4:192.168.1.1")
+ * // => "sig:virustotal:obs:ipv4:192.168.1.1"
  * ```
  */
-declare function generateThreatIntelKey(source: string, observableKey: string): string;
+export declare function generateSignalKey(source: string, subjectKey: string, externalId?: string): string;
+/** Kept under its v6 name; new code calls {@link generateSignalKey}. */
+export declare const generateThreatIntelKey: typeof generateSignalKey;
 /**
- * Generate a unique key for an enrichment.
+ * Generate a relation key.
  *
- * Format: enr:{name} or enr:{name}:{context_hash}
- *
- * @param name - Name of the enrichment
- * @param context - Optional context string for disambiguation
- * @returns Unique enrichment key
- *
- * @example
- * ```ts
- * generateEnrichmentKey("whois_data")
- * // => "enr:whois_data"
+ * Format: `rel:{kind}:{source_key}>{target_key}` — direction lives in the key itself, so no
+ * `direction` field is needed to disambiguate.
+ */
+export declare function generateRelationKey(sourceKey: string, targetKey: string, kind: string, externalId?: string): string;
+/**
+ * Generate a decision key.
  *
- * generateEnrichmentKey("whois_data", "domain:example.com")
- * // => "enr:whois_data:a1b2c3d4"
- * ```
+ * Format: `dec:{target_key}` — one decision per target, whatever it says. The kind is content,
+ * not identity: a target holds a single current stance, and changing one's mind is a
+ * re-assertion the merge law settles by freshness.
  */
-declare function generateEnrichmentKey(name: string, context?: string): string;
+export declare function generateDecisionKey(targetKey: string): string;
 /**
  * Generate a unique key for a tag.
  *
@@ -488,7 +629,7 @@ declare function generateEnrichmentKey(name: string, context?: string): string;
  * // => "tag:header:auth:dkim"
  * ```
  */
-declare function generateTagKey(name: string): string;
+export declare function generateTagKey(name: string): string;
 /**
  * Get all ancestor tag names from a hierarchical tag name.
  *
@@ -501,7 +642,7 @@ declare function generateTagKey(name: string): string;
  * // => ["header", "header:auth"]
  * ```
  */
-declare function getTagAncestors(name: string): string[];
+export declare function getTagAncestors(name: string): string[];
 /**
  * Check if a tag is a direct child of another tag.
  *
@@ -515,7 +656,7 @@ declare function getTagAncestors(name: string): string[];
  * isTagChildOf("header:auth:dkim", "header") // => false (grandchild)
  * ```
  */
-declare function isTagChildOf(childName: string, parentName: string): boolean;
+export declare function isTagChildOf(childName: string, parentName: string): boolean;
 /**
  * Check if a tag is a descendant of another tag (any depth).
  *
@@ -529,12 +670,12 @@ declare function isTagChildOf(childName: string, parentName: string): boolean;
  * isTagDescendantOf("header", "header") // => false (same)
  * ```
  */
-declare function isTagDescendantOf(descendantName: string, ancestorName: string): boolean;
+export declare function isTagDescendantOf(descendantName: string, ancestorName: string): boolean;
 /**
  * Extract the type prefix from a key.
  *
  * @param key - The key to parse
- * @returns Type prefix (obs, fnd, evd, ti, enr, tag) or null if invalid
+ * @returns Type prefix (see {@link KEY_PREFIXES}) or null if invalid
  *
  * @example
  * ```ts
@@ -542,7 +683,7 @@ declare function isTagDescendantOf(descendantName: string, ancestorName: string)
  * parseKeyType("invalid") // => null
  * ```
  */
-declare function parseKeyType(key: string): KeyType | null;
+export declare function parseKeyType(key: string): KeyType | null;
 /**
  * Validate a key format and optionally finding its type.
  *
@@ -558,10 +699,15 @@ declare function parseKeyType(key: string): KeyType | null;
  * validateKey("invalid") // => false
  * ```
  */
-declare function validateKey(key: string, expectedType?: KeyType): boolean;
+export declare function validateKey(key: string, expectedType?: KeyType): boolean;
 /**
  * Extract components from an observable key.
  *
+ * Only reliable for the simple form `obs:{type}:{value}`. A key carrying a subtype or a
+ * namespace, and a `command_line` or oversized key folded into `obs:{type}:sha256:{digest}`,
+ * both return the remaining segments verbatim as `value` — a key is an identity token, not a
+ * record. Read the observable from the document instead of parsing its key.
+ *
  * @param key - Observable key to parse
  * @returns Object with type and value, or null if invalid
  *
@@ -571,1009 +717,155 @@ declare function validateKey(key: string, expectedType?: KeyType): boolean;
  * // => { type: "ipv4", value: "192.168.1.1" }
  * ```
  */
-declare function parseObservableKey(key: string): {
-    type: string;
-    value: string;
-} | null;
-/**
- * Extract components from a finding key.
- *
- * @param key - Finding key to parse
- * @returns Object with findingName, or null if invalid
- *
- * @example
- * ```ts
- * parseFindingKey("fnd:sender_verification")
- * // => { findingName: "sender_verification" }
- * ```
- */
-declare function parseFindingKey(key: string): {
-    findingName: string;
-} | null;
-/**
- * Extract components from a threat intel key.
- *
- * @param key - Threat intel key to parse
- * @returns Object with source and observableKey, or null if invalid
- *
- * @example
- * ```ts
- * parseThreatIntelKey("ti:virustotal:obs:ipv4:192.168.1.1")
- * // => { source: "virustotal", observableKey: "obs:ipv4:192.168.1.1" }
- * ```
- */
-declare function parseThreatIntelKey(key: string): {
-    source: string;
-    observableKey: string;
+export declare function parseObservableKey(key: string): {
+  type: string;
+  value: string;
 } | null;
-
-/**
- * Level enumeration and scoring logic for Cyvest.
- *
- * This module defines the security level classification system and the algorithm
- * for determining levels from scores.
- */
-
-/**
- * Ordered array of levels from lowest to highest severity.
- */
-declare const LEVEL_ORDER: readonly Level[];
-/**
- * Numeric values for each level (for comparison purposes).
- */
-declare const LEVEL_VALUES: Record<Level, number>;
-/**
- * Color mapping for display purposes.
- */
-declare const LEVEL_COLORS: Record<Level, string>;
-/**
- * Normalize a level input to the Level type.
- *
- * Accepts a case-insensitive string and returns the normalized Level.
- *
- * @param level - Level string (e.g., "malicious", "MALICIOUS")
- * @returns The normalized Level
- * @throws Error if the string does not match a valid Level
- *
- * @example
- * ```ts
- * normalizeLevel("malicious") // => "MALICIOUS"
- * normalizeLevel("TRUSTED") // => "TRUSTED"
- * ```
- */
-declare function normalizeLevel(level: string): Level;
-/**
- * Check if a string is a valid Level.
- *
- * @param level - String to finding
- * @returns True if valid Level
- */
-declare function isValidLevel(level: string): level is Level;
-/**
- * Calculate the security level from a numeric score.
- *
- * Algorithm:
- * - score < 0.0  -> TRUSTED
- * - score === 0.0 -> INFO
- * - score < 3.0  -> NOTABLE
- * - score < 5.0  -> SUSPICIOUS
- * - score >= 5.0 -> MALICIOUS
- *
- * @param score - The numeric score to evaluate
- * @returns The appropriate Level based on the score
- *
- * @example
- * ```ts
- * getLevelFromScore(-1) // => "TRUSTED"
- * getLevelFromScore(0) // => "INFO"
- * getLevelFromScore(2.5) // => "NOTABLE"
- * getLevelFromScore(4) // => "SUSPICIOUS"
- * getLevelFromScore(5) // => "MALICIOUS"
- * ```
- */
-declare function getLevelFromScore(score: number): Level;
-/**
- * Compare two levels.
- *
- * @param a - First level
- * @param b - Second level
- * @returns -1 if a < b, 0 if a === b, 1 if a > b
- *
- * @example
- * ```ts
- * compareLevels("INFO", "MALICIOUS") // => -1
- * compareLevels("MALICIOUS", "INFO") // => 1
- * compareLevels("INFO", "INFO") // => 0
- * ```
- */
-declare function compareLevels(a: Level, b: Level): -1 | 0 | 1;
-/**
- * Check if level a is higher (more severe) than level b.
- *
- * @param a - First level
- * @param b - Second level
- * @returns True if a is higher than b
- *
- * @example
- * ```ts
- * isLevelHigherThan("MALICIOUS", "SUSPICIOUS") // => true
- * isLevelHigherThan("INFO", "MALICIOUS") // => false
- * ```
- */
-declare function isLevelHigherThan(a: Level, b: Level): boolean;
-/**
- * Check if level a is lower (less severe) than level b.
- *
- * @param a - First level
- * @param b - Second level
- * @returns True if a is lower than b
- */
-declare function isLevelLowerThan(a: Level, b: Level): boolean;
-/**
- * Check if level a is at least as severe as level b.
- *
- * @param a - Level to finding
- * @param minLevel - Minimum required level
- * @returns True if a is at least minLevel
- *
- * @example
- * ```ts
- * isLevelAtLeast("MALICIOUS", "SUSPICIOUS") // => true
- * isLevelAtLeast("SUSPICIOUS", "SUSPICIOUS") // => true
- * isLevelAtLeast("INFO", "SUSPICIOUS") // => false
- * ```
- */
-declare function isLevelAtLeast(a: Level, minLevel: Level): boolean;
-/**
- * Get the maximum (most severe) level from an array of levels.
- *
- * @param levels - Array of levels
- * @returns The most severe level, or "NONE" if array is empty
- */
-declare function maxLevel(levels: Level[]): Level;
-/**
- * Get the minimum (least severe) level from an array of levels.
- *
- * @param levels - Array of levels
- * @returns The least severe level, or "MALICIOUS" if array is empty
- */
-declare function minLevel(levels: Level[]): Level;
-/**
- * Get the color associated with a level for display purposes.
- *
- * @param level - Level to get color for
- * @returns Hex color string
- */
-declare function getColorForLevel(level: Level): string;
-/**
- * Get the color associated with a score for display purposes.
- *
- * @param score - Score to get color for
- * @returns Hex color string
- */
-declare function getColorForScore(score: number): string;
-/**
- * Type guard to check if an object has a level property.
- */
-declare function hasLevel(obj: unknown): obj is {
-    level: Level;
-};
-/**
- * Extract level from an entity (Observable, Finding, ThreatIntel, Tag).
- */
-declare function getEntityLevel(entity: Observable | Finding | ThreatIntel | Tag): Level;
-
-/**
- * Get an observable by its key.
- *
- * @param inv - The investigation to search
- * @param key - Observable key (e.g., "obs:ipv4:192.168.1.1")
- * @returns The observable or undefined if not found
- *
- * @example
- * ```ts
- * const obs = getObservable(investigation, "obs:ipv4:192.168.1.1");
- * if (obs) {
- *   console.log(obs.value, obs.level);
- * }
- * ```
- */
-declare function getObservable(inv: CyvestInvestigation, key: string): Observable | undefined;
-/**
- * Get an observable by type and value.
- *
- * @param inv - The investigation to search
- * @param type - Observable type (e.g., "ipv4", "url")
- * @param value - Observable value
- * @returns The observable or undefined if not found
- *
- * @example
- * ```ts
- * const obs = getObservableByTypeValue(investigation, "ipv4", "192.168.1.1");
- * ```
- */
-declare function getObservableByTypeValue(inv: CyvestInvestigation, type: string, value: string, subtype?: string, namespace?: string): Observable | undefined;
-/**
- * Get the root observable of the investigation.
- *
- * The root observable is identified using the `root_type` from data extraction
- * metadata combined with value="root".
- *
- * @param inv - The investigation
- * @returns The root observable, or undefined if not found
- *
- * @example
- * ```ts
- * const root = getRootObservable(investigation);
- * if (root) {
- *   console.log(`Root: ${root.type} = ${root.value}`);
- * }
- * ```
- */
-declare function getRootObservable(inv: CyvestInvestigation): Observable | undefined;
-/**
- * Get a finding by its key.
- *
- * @param inv - The investigation to search
- * @param key - Finding key (e.g., "fnd:sender_verification:email_headers")
- * @returns The finding or undefined if not found
- *
- * @example
- * ```ts
- * const finding = getFinding(investigation, "fnd:sender_verification:email_headers");
- * ```
- */
-declare function getFinding(inv: CyvestInvestigation, key: string): Finding | undefined;
-/**
- * Get a finding by its name.
- *
- * @param inv - The investigation to search
- * @param findingName - Finding name
- * @returns The finding or undefined if not found
- *
- * @example
- * ```ts
- * const finding = getFindingByName(investigation, "sender_verification");
- * ```
- */
-declare function getFindingByName(inv: CyvestInvestigation, findingName: string): Finding | undefined;
-/**
- * Get all findings as an array.
- *
- * @param inv - The investigation
- * @returns Array of all findings
- *
- * @example
- * ```ts
- * const allFindings = getAllFindings(investigation);
- * console.log(`Total findings: ${allFindings.length}`);
- * ```
- */
-declare function getAllFindings(inv: CyvestInvestigation): Finding[];
-declare function getEvidence(inv: CyvestInvestigation, key: string): Evidence | undefined;
-declare function getAllEvidences(inv: CyvestInvestigation): Evidence[];
-/**
- * Get a threat intel entry by its key.
- *
- * @param inv - The investigation to search
- * @param key - Threat intel key (e.g., "ti:virustotal:obs:ipv4:192.168.1.1")
- * @returns The threat intel or undefined if not found
- */
-declare function getThreatIntel(inv: CyvestInvestigation, key: string): ThreatIntel | undefined;
-/**
- * Get a threat intel entry by source and observable key.
- *
- * @param inv - The investigation to search
- * @param source - Threat intel source name
- * @param observableKey - Key of the related observable
- * @returns The threat intel or undefined if not found
- */
-declare function getThreatIntelBySourceObservable(inv: CyvestInvestigation, source: string, observableKey: string): ThreatIntel | undefined;
-/**
- * Get all threat intel entries as an array.
- *
- * @param inv - The investigation
- * @returns Array of all threat intel entries
- */
-declare function getAllThreatIntels(inv: CyvestInvestigation): ThreatIntel[];
-/**
- * Get an enrichment by its key.
- *
- * @param inv - The investigation to search
- * @param key - Enrichment key (e.g., "enr:whois_data")
- * @returns The enrichment or undefined if not found
- */
-declare function getEnrichment(inv: CyvestInvestigation, key: string): Enrichment | undefined;
-/**
- * Get an enrichment by name.
- *
- * @param inv - The investigation to search
- * @param name - Enrichment name
- * @returns The first matching enrichment or undefined if not found
- */
-declare function getEnrichmentByName(inv: CyvestInvestigation, name: string): Enrichment | undefined;
-/**
- * Get all enrichments as an array.
- *
- * @param inv - The investigation
- * @returns Array of all enrichments
- */
-declare function getAllEnrichments(inv: CyvestInvestigation): Enrichment[];
-/**
- * Get a tag by its key.
- *
- * @param inv - The investigation to search
- * @param key - Tag key (e.g., "tag:header:auth")
- * @returns The tag or undefined if not found
- *
- * @example
- * ```ts
- * const tag = getTag(investigation, "tag:header:auth");
- * if (tag) {
- *   console.log(tag.name, tag.direct_level);
- * }
- * ```
- */
-declare function getTag(inv: CyvestInvestigation, key: string): Tag | undefined;
-/**
- * Get a tag by its name.
- *
- * @param inv - The investigation to search
- * @param name - Tag name (e.g., "header:auth:dkim")
- * @returns The tag or undefined if not found
- *
- * @example
- * ```ts
- * const tag = getTagByName(investigation, "header:auth:dkim");
- * ```
- */
-declare function getTagByName(inv: CyvestInvestigation, name: string): Tag | undefined;
-/**
- * Get all tags as an array.
- *
- * @param inv - The investigation
- * @returns Array of all tags
- *
- * @example
- * ```ts
- * const allTags = getAllTags(investigation);
- * console.log(`Total tags: ${allTags.length}`);
- * ```
- */
-declare function getAllTags(inv: CyvestInvestigation): Tag[];
-/**
- * Get all observables as an array.
- *
- * @param inv - The investigation
- * @returns Array of all observables
- */
-declare function getAllObservables(inv: CyvestInvestigation): Observable[];
-/**
- * Get all whitelists from the investigation.
- *
- * @param inv - The investigation
- * @returns Array of all whitelists
- */
-declare function getWhitelists(inv: CyvestInvestigation): Whitelists;
-/**
- * Get the investigation statistics.
- *
- * @param inv - The investigation
- * @returns Statistics object
- */
-declare function getStats(inv: CyvestInvestigation): StatisticsSchema;
-/**
- * Get the data extraction configuration.
- *
- * @param inv - The investigation
- * @returns Data extraction config
- */
-declare function getDataExtraction(inv: CyvestInvestigation): DataExtractionSchema;
-/**
- * Count entities in the investigation.
- */
-interface InvestigationCounts {
-    observables: number;
-    findings: number;
-    evidences: number;
-    threatIntels: number;
-    enrichments: number;
-    tags: number;
-    whitelists: number;
-}
-/**
- * Get counts of all entities in the investigation.
- *
- * @param inv - The investigation
- * @returns Object with counts for each entity type
- */
-declare function getCounts(inv: CyvestInvestigation): InvestigationCounts;
-/**
- * Get the investigation start time from the event log.
- *
- * Looks for the INVESTIGATION_STARTED event and returns its timestamp.
- *
- * @param inv - The investigation
- * @returns The start timestamp string or undefined if not found
- *
- * @example
- * ```ts
- * const startedAt = getStartedAt(investigation);
- * if (startedAt) {
- *   console.log(`Started: ${startedAt}`);
- * }
- * ```
- */
-declare function getStartedAt(inv: CyvestInvestigation): string | undefined;
-/**
- * Get direct child tags of a given tag.
- *
- * @param inv - The investigation
- * @param tagName - Parent tag name
- * @returns Array of direct child tags
- *
- * @example
- * ```ts
- * const children = getTagChildren(investigation, "bodies");
- * // Returns tags like "bodies:urls", "bodies:domains" (but not "bodies:urls:something")
- * ```
- */
-declare function getTagChildren(inv: CyvestInvestigation, tagName: string): Tag[];
-/**
- * Get all descendant tags of a given tag (any depth).
- *
- * @param inv - The investigation
- * @param tagName - Ancestor tag name
- * @returns Array of all descendant tags
- *
- * @example
- * ```ts
- * const descendants = getTagDescendants(investigation, "bodies");
- * // Returns all tags starting with "bodies:"
- * ```
- */
-declare function getTagDescendants(inv: CyvestInvestigation, tagName: string): Tag[];
-/**
- * Get the aggregated score for a tag including all descendant tags.
- *
- * The aggregated score includes:
- * - The tag's direct_score (from its direct findings)
- * - Recursively, the aggregated scores of all child tags
- *
- * @param inv - The investigation
- * @param tagName - Name of the tag
- * @returns Total aggregated score, or 0 if tag not found
- *
- * @example
- * ```ts
- * const score = getTagAggregatedScore(investigation, "bodies");
- * // Includes scores from bodies, bodies:urls, bodies:domains, etc.
- * ```
- */
-declare function getTagAggregatedScore(inv: CyvestInvestigation, tagName: string): number;
-/**
- * Get the aggregated level for a tag including all descendant tags.
- *
- * The level is calculated from the aggregated score using the standard
- * score-to-level mapping.
- *
- * @param inv - The investigation
- * @param tagName - Name of the tag
- * @returns Level based on aggregated score
- *
- * @example
- * ```ts
- * const level = getTagAggregatedLevel(investigation, "bodies");
- * // Returns "MALICIOUS" if aggregated score >= 5, etc.
- * ```
- */
-declare function getTagAggregatedLevel(inv: CyvestInvestigation, tagName: string): Level;
-
-/**
- * Finder utilities for querying and filtering Cyvest Investigation data.
- *
- * These functions provide filtering, searching, and cross-referencing
- * capabilities for observables, findings, and threat intel.
- */
-
-/**
- * Find all observables of a specific type.
- *
- * @param inv - The investigation to search
- * @param type - Observable type (e.g., "ipv4", "url", "domain")
- * @returns Array of matching observables
- *
- * @example
- * ```ts
- * const ips = findObservablesByType(investigation, "ipv4");
- * const urls = findObservablesByType(investigation, "url");
- * ```
- */
-declare function findObservablesByType(inv: CyvestInvestigation, type: string): Observable[];
-/**
- * Find all observables at a specific level.
- *
- * @param inv - The investigation to search
- * @param level - Security level to filter by
- * @returns Array of matching observables
- *
- * @example
- * ```ts
- * const malicious = findObservablesByLevel(investigation, "MALICIOUS");
- * ```
- */
-declare function findObservablesByLevel(inv: CyvestInvestigation, level: Level): Observable[];
-/**
- * Find all observables at or above a minimum level.
- *
- * @param inv - The investigation to search
- * @param minLevel - Minimum security level
- * @returns Array of matching observables
- *
- * @example
- * ```ts
- * const suspicious = findObservablesAtLeast(investigation, "SUSPICIOUS");
- * // Returns SUSPICIOUS and MALICIOUS observables
- * ```
- */
-declare function findObservablesAtLeast(inv: CyvestInvestigation, minLevel: Level): Observable[];
-/**
- * Find observables by exact value match.
- *
- * @param inv - The investigation to search
- * @param value - Value to search for
- * @param caseSensitive - Whether to perform case-sensitive match (default: false)
- * @returns Array of matching observables
- */
-declare function findObservablesByValue(inv: CyvestInvestigation, value: string, caseSensitive?: boolean): Observable[];
-/**
- * Find observables containing a substring in their value.
- *
- * @param inv - The investigation to search
- * @param substring - Substring to search for
- * @param caseSensitive - Whether to perform case-sensitive match (default: false)
- * @returns Array of matching observables
- */
-declare function findObservablesContaining(inv: CyvestInvestigation, substring: string, caseSensitive?: boolean): Observable[];
-/**
- * Find observables matching a regular expression.
- *
- * @param inv - The investigation to search
- * @param pattern - Regular expression pattern
- * @returns Array of matching observables
- */
-declare function findObservablesMatching(inv: CyvestInvestigation, pattern: RegExp): Observable[];
-/**
- * Find internal observables.
- *
- * @param inv - The investigation to search
- * @returns Array of internal observables
- */
-declare function findInternalObservables(inv: CyvestInvestigation): Observable[];
-/**
- * Find external (non-internal) observables.
- *
- * @param inv - The investigation to search
- * @returns Array of external observables
- */
-declare function findExternalObservables(inv: CyvestInvestigation): Observable[];
-/**
- * Find whitelisted observables.
- *
- * @param inv - The investigation to search
- * @returns Array of whitelisted observables
- */
-declare function findWhitelistedObservables(inv: CyvestInvestigation): Observable[];
-/**
- * Find observables with threat intelligence data.
- *
- * @param inv - The investigation to search
- * @returns Array of observables that have associated threat intel
- */
-declare function findObservablesWithThreatIntel(inv: CyvestInvestigation): Observable[];
-/**
- * Find all findings at a specific level.
- *
- * @param inv - The investigation to search
- * @param level - Security level to filter by
- * @returns Array of matching findings
- */
-declare function findFindingsByLevel(inv: CyvestInvestigation, level: Level): Finding[];
-/**
- * Find all findings at or above a minimum level.
- *
- * @param inv - The investigation to search
- * @param minLevel - Minimum security level
- * @returns Array of matching findings
- */
-declare function findFindingsAtLeast(inv: CyvestInvestigation, minLevel: Level): Finding[];
-/**
- * Find findings by finding name.
- *
- * @param inv - The investigation to search
- * @param findingName - Finding name to search for
- * @returns The matching finding or undefined
- */
-declare function findFindingByName(inv: CyvestInvestigation, findingName: string): Finding | undefined;
-/**
- * Find all threat intel from a specific source.
- *
- * @param inv - The investigation to search
- * @param source - Source name (e.g., "virustotal", "otx")
- * @returns Array of threat intel from the source
- */
-declare function findThreatIntelBySource(inv: CyvestInvestigation, source: string): ThreatIntel[];
-/**
- * Find all threat intel at a specific level.
- *
- * @param inv - The investigation to search
- * @param level - Security level to filter by
- * @returns Array of matching threat intel
- */
-declare function findThreatIntelByLevel(inv: CyvestInvestigation, level: Level): ThreatIntel[];
-/**
- * Find all threat intel at or above a minimum level.
- *
- * @param inv - The investigation to search
- * @param minLevel - Minimum security level
- * @returns Array of matching threat intel
- */
-declare function findThreatIntelAtLeast(inv: CyvestInvestigation, minLevel: Level): ThreatIntel[];
-/**
- * Find tags at a specific direct level.
- *
- * @param inv - The investigation to search
- * @param level - Direct level to filter by
- * @returns Array of matching tags
- */
-declare function findTagsByLevel(inv: CyvestInvestigation, level: Level): Tag[];
-/**
- * Find tags at or above a minimum direct level.
- *
- * @param inv - The investigation to search
- * @param minLevel - Minimum direct level
- * @returns Array of matching tags
- */
-declare function findTagsAtLeast(inv: CyvestInvestigation, minLevel: Level): Tag[];
-/**
- * Find tags by name pattern.
- *
- * @param inv - The investigation to search
- * @param pattern - Pattern to match against tag names
- * @returns Array of matching tags
- */
-declare function findTagsByNamePattern(inv: CyvestInvestigation, pattern: RegExp): Tag[];
-/**
- * Find all findings that generated or reference a specific observable.
- *
- * @param inv - The investigation to search
- * @param observableKey - Key of the observable
- * @returns Array of findings that reference this observable
- *
- * @example
- * ```ts
- * const findings = findFindingsForObservable(investigation, "obs:ipv4:192.168.1.1");
- * ```
- */
-declare function findFindingsForObservable(inv: CyvestInvestigation, observableKey: string): Finding[];
-/**
- * Find all threat intel entries for a specific observable.
- *
- * @param inv - The investigation to search
- * @param observableKey - Key of the observable
- * @returns Array of threat intel for this observable
- */
-declare function findThreatIntelsForObservable(inv: CyvestInvestigation, observableKey: string): ThreatIntel[];
-/**
- * Find all observables referenced by a specific finding.
- *
- * @param inv - The investigation to search
- * @param findingKey - Key of the finding
- * @returns Array of observables referenced by this finding
- */
-declare function findObservablesForFinding(inv: CyvestInvestigation, findingKey: string): Observable[];
-/**
- * Find all findings for a specific tag.
- *
- * @param inv - The investigation to search
- * @param tagKey - Key of the tag
- * @param recursive - Include findings from descendant tags (default: false)
- * @returns Array of findings in the tag
- */
-declare function findFindingsForTag(inv: CyvestInvestigation, tagKey: string, recursive?: boolean): Finding[];
-/**
- * Sort observables by score (descending - highest first).
- *
- * @param observables - Array of observables to sort
- * @returns Sorted array (new array, doesn't mutate input)
- */
-declare function sortObservablesByScore(observables: Observable[]): Observable[];
-/**
- * Sort findings by score (descending - highest first).
- *
- * @param findings - Array of findings to sort
- * @returns Sorted array (new array, doesn't mutate input)
- */
-declare function sortFindingsByScore(findings: Finding[]): Finding[];
-/**
- * Sort observables by level (descending - most severe first).
- *
- * @param observables - Array of observables to sort
- * @returns Sorted array (new array, doesn't mutate input)
- */
-declare function sortObservablesByLevel(observables: Observable[]): Observable[];
-/**
- * Sort findings by level (descending - most severe first).
- *
- * @param findings - Array of findings to sort
- * @returns Sorted array (new array, doesn't mutate input)
- */
-declare function sortFindingsByLevel(findings: Finding[]): Finding[];
-/**
- * Find the highest scoring observables.
- *
- * @param inv - The investigation to search
- * @param n - Number of results to return (default: 10)
- * @returns Array of highest scoring observables
- */
-declare function findHighestScoringObservables(inv: CyvestInvestigation, n?: number): Observable[];
-/**
- * Find the highest scoring findings.
- *
- * @param inv - The investigation to search
- * @param n - Number of results to return (default: 10)
- * @returns Array of highest scoring findings
- */
-declare function findHighestScoringFindings(inv: CyvestInvestigation, n?: number): Finding[];
-/**
- * Find all malicious observables (convenience function).
- *
- * @param inv - The investigation to search
- * @returns Array of malicious observables
- */
-declare function findMaliciousObservables(inv: CyvestInvestigation): Observable[];
-/**
- * Find all suspicious observables (convenience function).
- *
- * @param inv - The investigation to search
- * @returns Array of suspicious observables
- */
-declare function findSuspiciousObservables(inv: CyvestInvestigation): Observable[];
-/**
- * Find all malicious findings (convenience function).
- *
- * @param inv - The investigation to search
- * @returns Array of malicious findings
- */
-declare function findMaliciousFindings(inv: CyvestInvestigation): Finding[];
-/**
- * Find all suspicious findings (convenience function).
- *
- * @param inv - The investigation to search
- * @returns Array of suspicious findings
- */
-declare function findSuspiciousFindings(inv: CyvestInvestigation): Finding[];
-/**
- * Get all finding keys in the investigation.
- *
- * @param inv - The investigation
- * @returns Array of finding keys
- */
-declare function getAllFindingKeys(inv: CyvestInvestigation): string[];
-/**
- * Get all observable types present in the investigation.
- *
- * @param inv - The investigation
- * @returns Array of unique observable types
- */
-declare function getAllObservableTypes(inv: CyvestInvestigation): string[];
-/**
- * Get all threat intel sources present in the investigation.
- *
- * @param inv - The investigation
- * @returns Array of unique source names
- */
-declare function getAllThreatIntelSources(inv: CyvestInvestigation): string[];
-
-/**
- * Graph and relationship traversal utilities for Cyvest Investigation.
- *
- * These functions provide graph-like traversal of observable relationships,
- * useful for understanding connections and preparing data for visualization.
- */
-
-/**
- * Edge representation for graph operations.
- */
-interface GraphEdge {
-    /** Source observable key */
-    source: string;
-    /** Target observable key */
-    target: string;
-    /** Relationship type label */
-    type: string;
-    /** Relationship direction */
-    direction: RelationshipDirection;
-}
-/**
- * Graph node representation.
- */
-interface GraphNode {
-    /** Observable key (unique identifier) */
-    id: string;
-    /** Observable type */
-    type: string;
-    /** Observable value */
-    value: string;
-    /** Security level */
-    level: Level;
-    /** Numeric score */
-    score: number;
-    /** Whether internal */
-    internal: boolean;
-    /** Whether whitelisted */
-    whitelisted: boolean;
-}
-/**
- * Full graph representation of an investigation.
- */
-interface InvestigationGraph {
-    /** All nodes (observables) */
-    nodes: GraphNode[];
-    /** All edges (relationships) */
-    edges: GraphEdge[];
-}
-/**
- * Get all related observables for a given observable.
- *
- * Returns observables that are directly connected via any relationship,
- * regardless of direction.
- *
- * @param inv - The investigation to search
- * @param observableKey - Key of the source observable
- * @returns Array of related observables
- *
- * @example
- * ```ts
- * const related = getRelatedObservables(investigation, "obs:email:test@example.com");
- * ```
- */
-declare function getRelatedObservables(inv: CyvestInvestigation, observableKey: string): Observable[];
-/**
- * Get observables related by outbound relationships (children).
- *
- * @param inv - The investigation to search
- * @param observableKey - Key of the source observable
- * @returns Array of child observables
- */
-declare function getObservableChildren(inv: CyvestInvestigation, observableKey: string): Observable[];
-/**
- * Get observables related by inbound relationships (parents).
- *
- * @param inv - The investigation to search
- * @param observableKey - Key of the target observable
- * @returns Array of parent observables
- */
-declare function getObservableParents(inv: CyvestInvestigation, observableKey: string): Observable[];
-/**
- * Get related observables filtered by relationship type.
- *
- * @param inv - The investigation to search
- * @param observableKey - Key of the source observable
- * @param relationshipType - Type of relationship to filter (e.g., "related-to", "uses")
- * @returns Array of related observables
- */
-declare function getRelatedObservablesByType(inv: CyvestInvestigation, observableKey: string, relationshipType: string): Observable[];
-/**
- * Get related observables filtered by direction.
- *
- * @param inv - The investigation to search
- * @param observableKey - Key of the source observable
- * @param direction - Direction to filter by
- * @returns Array of related observables
- */
-declare function getRelatedObservablesByDirection(inv: CyvestInvestigation, observableKey: string, direction: RelationshipDirection): Observable[];
-/**
- * Build a graph representation of all observables and their relationships.
- *
- * Useful for visualization libraries like vis.js, d3, or cytoscape.
- *
- * @param inv - The investigation
- * @returns Graph with nodes and edges
- *
- * @example
- * ```ts
- * const graph = getObservableGraph(investigation);
- * console.log(`Nodes: ${graph.nodes.length}, Edges: ${graph.edges.length}`);
- *
- * // Use with vis.js:
- * const network = new vis.Network(container, {
- *   nodes: graph.nodes.map(n => ({ id: n.id, label: n.value })),
- *   edges: graph.edges.map(e => ({ from: e.source, to: e.target, label: e.type }))
- * });
- * ```
- */
-declare function getObservableGraph(inv: CyvestInvestigation): InvestigationGraph;
-/**
- * Find source observables in the investigation graph.
- *
- * Source observables are those that have no incoming relationships
- * (nothing points to them as a target).
- *
- * @param inv - The investigation
- * @returns Array of source observables
- */
-declare function findSourceObservables(inv: CyvestInvestigation): Observable[];
-/**
- * Find orphan observables (not connected to any other observable).
- *
- * @param inv - The investigation
- * @returns Array of orphan observables
- */
-declare function findOrphanObservables(inv: CyvestInvestigation): Observable[];
-/**
- * Find leaf observables (have incoming but no outgoing relationships).
- *
- * @param inv - The investigation
- * @returns Array of leaf observables
- */
-declare function findLeafObservables(inv: CyvestInvestigation): Observable[];
-/**
- * Check if two observables are connected (directly or transitively).
- *
- * @param inv - The investigation
- * @param sourceKey - Starting observable key
- * @param targetKey - Target observable key
- * @returns True if a path exists from source to target
- */
-declare function areConnected(inv: CyvestInvestigation, sourceKey: string, targetKey: string): boolean;
-/**
- * Find the shortest path between two observables.
- *
- * @param inv - The investigation
- * @param sourceKey - Starting observable key
- * @param targetKey - Target observable key
- * @returns Array of observable keys representing the path, or null if no path exists
- */
-declare function findPath(inv: CyvestInvestigation, sourceKey: string, targetKey: string): string[] | null;
-/**
- * Get all observables reachable from a starting point.
- *
- * @param inv - The investigation
- * @param startKey - Starting observable key
- * @param maxDepth - Maximum traversal depth (default: Infinity)
- * @returns Array of reachable observables
- */
-declare function getReachableObservables(inv: CyvestInvestigation, startKey: string, maxDepth?: number): Observable[];
-/**
- * Get all unique relationship types used in the investigation.
- *
- * @param inv - The investigation
- * @returns Array of unique relationship type strings
- */
-declare function getAllRelationshipTypes(inv: CyvestInvestigation): string[];
-/**
- * Count relationships by type.
- *
- * @param inv - The investigation
- * @returns Object mapping relationship type to count
- */
-declare function countRelationshipsByType(inv: CyvestInvestigation): Record<string, number>;
-/**
- * Get all relationships for an observable.
- *
- * @param inv - The investigation
- * @param observableKey - Observable key
- * @returns Object with outbound, inbound, and all relationships
- */
-declare function getRelationshipsForObservable(inv: CyvestInvestigation, observableKey: string): {
-    outbound: Relationship[];
-    inbound: Array<Relationship & {
-        source_key: string;
-    }>;
-    all: Array<Relationship & {
-        source_key?: string;
-    }>;
-};
-
-export { type Actor, type Aliases, type AuditEvent, type AuditLog, type CyvestInvestigation, type Data, type DataExtractionSchema, type Details, type Enrichment, type Enrichments, type Evidence, type EvidenceLink, type EvidenceLinks, type Evidences, type EvidencesBySource, type EvidencesByType, type ExternalId, type Extra, type Extra1, type Extra2, type Extra3, type Finding, type FindingLinks, type FindingLinks1, type Findings, type Findings1, type FindingsByLevel, type GraphEdge, type GraphNode, type InvestigationCounts, type InvestigationGraph, type InvestigationName, type InvestigationWhitelist, type Justification, type KeyType, LEVEL_COLORS, LEVEL_ORDER, LEVEL_VALUES, type Level, type Namespace, type Namespace1, type ObjectKey, type ObjectType, type Observable, type ObservableAlias, type ObservableLink, type ObservableLinks, type Observables, type ObservablesByLevel, type ObservablesByType, type ObservablesByTypeAndLevel, type PropagationMode, type Reason, type Relationship, type RelationshipDirection, type Relationships, type RootType, type ScoreMode, type StatisticsSchema, type Subtype, type Subtype1, type Tag, type Tags, type Taxonomies, type Taxonomy, type ThreatIntel, type ThreatIntelByLevel, type ThreatIntelBySource, type ThreatIntels, type ThreatIntels1, type Tool, type Uri, type Whitelists, areConnected, compareLevels, countRelationshipsByType, findExternalObservables, findFindingByName, findFindingsAtLeast, findFindingsByLevel, findFindingsForObservable, findFindingsForTag, findHighestScoringFindings, findHighestScoringObservables, findInternalObservables, findLeafObservables, findMaliciousFindings, findMaliciousObservables, findObservablesAtLeast, findObservablesByLevel, findObservablesByType, findObservablesByValue, findObservablesContaining, findObservablesForFinding, findObservablesMatching, findObservablesWithThreatIntel, findOrphanObservables, findPath, findSourceObservables, findSuspiciousFindings, findSuspiciousObservables, findTagsAtLeast, findTagsByLevel, findTagsByNamePattern, findThreatIntelAtLeast, findThreatIntelByLevel, findThreatIntelBySource, findThreatIntelsForObservable, findWhitelistedObservables, generateEnrichmentKey, generateFindingKey, generateObservableKey, generateTagKey, generateThreatIntelKey, getAllEnrichments, getAllEvidences, getAllFindingKeys, getAllFindings, getAllObservableTypes, getAllObservables, getAllRelationshipTypes, getAllTags, getAllThreatIntelSources, getAllThreatIntels, getColorForLevel, getColorForScore, getCounts, getDataExtraction, getEnrichment, getEnrichmentByName, getEntityLevel, getEvidence, getFinding, getFindingByName, getLevelFromScore, getObservable, getObservableByTypeValue, getObservableChildren, getObservableGraph, getObservableParents, getReachableObservables, getRelatedObservables, getRelatedObservablesByDirection, getRelatedObservablesByType, getRelationshipsForObservable, getRootObservable, getStartedAt, getStats, getTag, getTagAggregatedLevel, getTagAggregatedScore, getTagAncestors, getTagByName, getTagChildren, getTagDescendants, getThreatIntel, getThreatIntelBySourceObservable, getWhitelists, hasLevel, isCyvest, isLevelAtLeast, isLevelHigherThan, isLevelLowerThan, isTagChildOf, isTagDescendantOf, isValidLevel, maxLevel, minLevel, normalizeLevel, parseCyvest, parseFindingKey, parseKeyType, parseObservableKey, parseThreatIntelKey, sortFindingsByLevel, sortFindingsByScore, sortObservablesByLevel, sortObservablesByScore, validateKey };
+//#endregion
+//#region src/verdicts.d.ts
+/** Ordered from most exculpatory to most inculpatory. */
+export declare const VERDICT_ORDER: readonly Verdict[];
+/**
+ * Rich style names, mirroring the Python terminal renderer.
+ *
+ * These are *not* CSS colours: a browser cannot draw `orange3`. Use {@link VERDICT_HEX_COLORS}
+ * for anything rendered on screen.
+ */
+export declare const VERDICT_TERMINAL_STYLES: Record<Verdict, string>;
+/** The web palette: muted enough that a wall of NOTABLE nodes stays readable. */
+export declare const VERDICT_HEX_COLORS: Record<Verdict, string>;
+/** Direction the judgment pushes: -1 exculpatory, 0 neutral, +1 inculpatory. */
+export declare function verdictPolarity(verdict: Verdict): -1 | 0 | 1;
+export declare function isValidVerdict(value: unknown): value is Verdict;
+export declare function normalizeVerdict(value: unknown): Verdict;
+export declare function compareVerdicts(a: Verdict, b: Verdict): number;
+export declare function isVerdictAtLeast(verdict: Verdict, floor: Verdict): boolean;
+export declare function maxVerdict(verdicts: readonly Verdict[]): Verdict;
+export declare function minVerdict(verdicts: readonly Verdict[]): Verdict;
+export declare function getColorForVerdict(verdict: Verdict): string;
+/** Coarse bands for display; the engine works in floats. */
+export declare function confidenceBand(confidence: number): "low" | "medium" | "high";
+//#endregion
+//#region src/getters.d.ts
+export declare function getObservable(inv: Investigation, key: string): Observable$1 | undefined;
+export declare function getAllObservables(inv: Investigation): Record<string, Observable$1>;
+export declare function getRootObservable(inv: Investigation): Observable$1 | undefined;
+export declare function getRelation(inv: Investigation, key: string): Relation$1 | undefined;
+export declare function getAllRelations(inv: Investigation): Record<string, Relation$1>;
+export declare function getThreatIntel(inv: Investigation, key: string): ThreatIntel$1 | undefined;
+export declare function getAllThreatIntels(inv: Investigation): Record<string, ThreatIntel$1>;
+/** Signals attached to one observable. */
+export declare function getThreatIntelsFor(inv: Investigation, observableKey: string): ThreatIntel$1[];
+export declare function getFinding(inv: Investigation, key: string): Finding$1 | undefined;
+export declare function getAllFindings(inv: Investigation): Record<string, Finding$1>;
+export declare function getEvidence(inv: Investigation, key: string): Evidence$1 | undefined;
+export declare function getAllEvidences(inv: Investigation): Record<string, Evidence$1>;
+/** The v6 `Enrichment` is just an evidence type; filter instead of a dedicated accessor. */
+export declare function getEvidencesByType(inv: Investigation, evidenceType: string): Evidence$1[];
+export declare function getDecision(inv: Investigation, key: string): Decision$1 | undefined;
+export declare function getAllDecisions(inv: Investigation): Record<string, Decision$1>;
+/** The single stance standing on a target — the key carries the target alone. */
+export declare function getDecisionFor(inv: Investigation, targetKey: string): Decision$1 | undefined;
+export declare function isAllowlisted(inv: Investigation, observableKey: string): boolean;
+export declare function isBlocklisted(inv: Investigation, observableKey: string): boolean;
+export declare function isConfirmed(inv: Investigation, findingKey: string): boolean;
+export declare function isDismissed(inv: Investigation, findingKey: string): boolean;
+/** True when a stance was withdrawn and the computed value applies again. */
+export declare function isVacated(inv: Investigation, targetKey: string): boolean;
+/**
+ * The analyst's word for a stance, rebuilt from the intent and the family of its target.
+ *
+ * The model carries one axis on purpose; the vocabulary that reads naturally carries two, and
+ * the display layer is the right place to pay for that.
+ */
+export declare function decisionLabel(decision: Decision$1): string;
+export declare function getTag(inv: Investigation, key: string): Tag$1 | undefined;
+export declare function getTagByName(inv: Investigation, name: string): Tag$1 | undefined;
+export declare function getAllTags(inv: Investigation): Record<string, Tag$1>;
+export declare function getInvestigationResult(inv: Investigation): InvestigationResult$1;
+export declare function getObservableResult(inv: Investigation, observableKey: string): ObservableResult$1 | undefined;
+export declare function getFindingResult(inv: Investigation, findingKey: string): FindingResult$1 | undefined;
+export declare function getObservableScore(inv: Investigation, observableKey: string): number;
+export declare function getObservableVerdict(inv: Investigation, observableKey: string): Verdict;
+export declare function getFindingScore(inv: Investigation, findingKey: string): number;
+export declare function getFindingVerdict(inv: Investigation, findingKey: string): Verdict;
+export declare function getGlobalScore(inv: Investigation): number;
+export declare function getGlobalVerdict(inv: Investigation): Verdict;
+/** True when a decision or a stronger link overrode the computed value. */
+export declare function wasSuppressed(inv: Investigation, key: string): boolean;
+/** Findings a tag points at, plus those of every descendant tag. */
+export declare function getTagFindingKeys(inv: Investigation, tagName: string): string[];
+/**
+ * A tag's aggregated score.
+ *
+ * This sums values the engine produced; it does not re-derive them. Uncounted findings — not
+ * applicable, pending or dismissed — are absent from the sum *and* from any ratio built on it.
+ */
+export declare function getTagAggregatedScore(inv: Investigation, tagName: string): number;
+export interface InvestigationCounts {
+  observables: number;
+  relations: number;
+  signals: number;
+  evidences: number;
+  findings: number;
+  evaluatedFindings: number;
+  decisions: number;
+  tags: number;
+}
+export declare function getCounts(inv: Investigation): InvestigationCounts;
+//#endregion
+//#region src/finders.d.ts
+export declare function findObservablesByType(inv: Investigation, type: string): Observable$1[];
+export declare function findObservablesByValue(inv: Investigation, value: string): Observable$1[];
+export declare function findObservablesContaining(inv: Investigation, fragment: string): Observable$1[];
+export declare function findInternalObservables(inv: Investigation): Observable$1[];
+export declare function findExternalObservables(inv: Investigation): Observable$1[];
+export declare function findObservablesByVerdict(inv: Investigation, verdict: Verdict): Observable$1[];
+export declare function findObservablesAtLeast(inv: Investigation, floor: Verdict): Observable$1[];
+export declare function findObservablesWithThreatIntel(inv: Investigation): Observable$1[];
+export declare function findFindingsByVerdict(inv: Investigation, verdict: Verdict): Finding$1[];
+export declare function findFindingsAtLeast(inv: Investigation, floor: Verdict): Finding$1[];
+export declare function findFindingsByRule(inv: Investigation, ruleId: string): Finding$1[];
+export declare function findFindingsByConfidence(inv: Investigation, band: "low" | "medium" | "high"): Finding$1[];
+/** Findings excluded from the score but still worth showing, with their reason. */
+export declare function findUncountedFindings(inv: Investigation): Finding$1[];
+/** Findings whose own claim was outweighed by one of their observables — worth surfacing. */
+export declare function findContradictedFindings(inv: Investigation): Finding$1[];
+export declare function findThreatIntelBySource(inv: Investigation, source: string): ThreatIntel$1[];
+export declare function findThreatIntelByVerdict(inv: Investigation, verdict: Verdict): ThreatIntel$1[];
+export declare function findThreatIntelForObservable(inv: Investigation, observableKey: string): ThreatIntel$1[];
+//#endregion
+//#region src/graph.d.ts
+export interface GraphEdge {
+  key: string;
+  source: string;
+  target: string;
+  kind: string;
+  confidence: number;
+  /** True when the edge actually carried score, per the report's contributions. */
+  carriedScore: boolean;
+}
+export interface GraphNode {
+  key: string;
+  observable: Observable$1;
+  score: number;
+  verdict: string;
+}
+export interface InvestigationGraph {
+  nodes: GraphNode[];
+  edges: GraphEdge[];
+}
+export declare function getObservableChildren(inv: Investigation, observableKey: string): Observable$1[];
+export declare function getObservableParents(inv: Investigation, observableKey: string): Observable$1[];
+export declare function getRelatedObservables(inv: Investigation, observableKey: string): Observable$1[];
+export declare function getRelationsForObservable(inv: Investigation, observableKey: string): Relation$1[];
+export declare function countRelationsByKind(inv: Investigation): Record<string, number>;
+export declare function getObservableGraph(inv: Investigation): InvestigationGraph;
+export declare function areConnected(inv: Investigation, a: string, b: string): boolean;
+/** Undirected reachability — the same walk `finalize_relationships` uses to spot orphans. */
+export declare function getReachableObservables(inv: Investigation, start: string): Set<string>;
+export declare function findOrphanObservables(inv: Investigation): Observable$1[];
+export declare function findLeafObservables(inv: Investigation): Observable$1[];
+export declare function findSourceObservables(inv: Investigation): Observable$1[];
+//#endregion
+export type { Investigation };