Skip to content

Investigation

Definition

An Investigation is Beacon's user-facing name for a cortex Insight. There is no separate "Investigation" object in storage — Beacon's Investigation model and the cortex InsightRoot document are two views of the same thing. This spec exists to describe the end-to-end journey, because the object crosses a service boundary that neither the cortex nor the Beacon spec captures alone: the analyst works in the Beacon SPA, Beacon's FastAPI backend proxies to cortex over MCP, and cortex persists the InsightRoot plus its append-only event ledger in Elasticsearch. For the object's own shape, lifecycle, and invariants, see product.insight; this spec covers the wire between Beacon and cortex and the places the two representations diverge.

Beacon side: beacon/frontend/src/app/core/models/investigations.models.ts and insight-root.model.ts, API in beacon/frontend/.../core/services/api.service.ts, proxy in beacon/beacon/routes/api.py. Cortex side: see product.insight.

Lifecycle

The authoritative lifecycle is the Insight status machine (draft → in_review → approved → published → archived), derived from the event ledger and auto-advanced on review decisions — see product.insight. Beacon's frontend renders a simpler view: InvestigationState = draft | curated | archived (investigations.models.ts:5) alongside a 5-state InsightStatus type. The 3-state Beacon view over the 5-state cortex truth is a known divergence (DES [Q1]).

Journey through the code

Beacon UI → /api/insights* → Beacon FastAPI proxy (get_cortex()) → cortex MCP tools → command functions → InsightRoot().update(...) + InsightEvent().update(...) → UDS → REST /insight_root, /insight, /insight/{uid}/timeline → ES (insight_root / insight_event aliases). The analyst's actions in Beacon (start an investigation, pin evidence, request review, attest) become cortex MCP tool calls; cortex appends events to the ledger and advances the heads; the investigation's current state is reconstructed by replaying insight_event entries. Beacon renders the Editions tab from the Insight's Editions and the evidence view from its pinned Blocks.

Data shape

The stored object is InsightRoot (see product.insight for the canonical fields). Beacon's Investigation view adds presentation-only fields: state, curation{cover_blocks, summary_md, block_viz}, evidence[], spec.blocks[], and conversation[] (investigations.models.ts:82). These have no direct cortex InsightRoot counterpart and appear to be a Beacon-side rendering layer over the DES ledger model.

Invariants

  • One object, two names. Beacon must not treat Investigation as a separate persisted entity; the system of record is the cortex InsightRoot and its event ledger.
  • All Insight invariants hold (append-only ledger, mandatory subject, gated closure) — see product.insight.

Open questions

  • Status vocabularies — Beacon's 3-state InvestigationState over cortex's 5-state truth; DES [Q1] still open.
  • Beacon-only fields — curation / spec / conversation may be a legacy Beacon shape predating the DES ledger model; their mapping to the InsightRoot is unclear.
  • Insight vs InsightRoot vs Investigation — the legacy insight object and InsightRoot.insight_ids[] muddy the three-way mapping; Beacon treats InsightRoot itself as "the investigation."

Realized by: component.cortex.decision-evidence, component.cortex.investigation-lifecycle