BrainAnalysisLog is the canonical record of every Brain Agent query. It is how the L9 reasoning layer earns audit-grade reasoning out of a non-deterministic substrate: every numerical claim a brain makes ties back to a Tier 1 source row read at a specific timestamp, every proposed action carries a proposal_id that downstream actions inherit, and every output is reproducible with the same source data.
The architectural commitment in the v26 evaluation: brains never write canonical data, but every brain output must be traceable. BrainAnalysisLog is the mechanism. Three things it enables:
proposal_id lineage on every brain output enables exactly this: at quarter end, identify which downstream actions traced to brain proposals, and compare cohort outcomes to control.| Field | Type | Req | Notes |
|---|---|---|---|
analysis_id | UUID | REQ | Primary key. Generated at write. |
proposal_id | UUID | REQ | Stable identifier shared by every downstream action that traces to this analysis. Action records (in Tier 1 systems) carry this ID for retrospective cohorting. |
writer_agent_id | VARCHAR(16) | REQ | Which Brain Agent wrote this row. AGT-901 / AGT-902 / AGT-903. CHECK constraint enforces enum. |
invocation_path | ENUM | REQ | operator_query / narrative_job / play_refresh_batch / handoff_briefing / renewal_prep_batch / anomaly_explanation / board_prep_batch / strategic_retrospective_batch |
operator_user_id | UUID | opt | The human who initiated the query (NULL for AGT-704/AGT-603-invoked narrative jobs). |
account_id | UUID | opt | Populated for AGT-902 outputs (per-account scope). NULL for AGT-901 cross-account outputs and AGT-903 multi-quarter portfolio outputs. |
question | TEXT | REQ | The operator query verbatim, or the narrative-job prompt verbatim. Audit input. |
system_prompt_hash | VARCHAR(64) | REQ | SHA-256 of the system prompt used. Enables eval comparison across prompt versions. |
sources_read | JSONB | REQ | Array of {table_name, view_name, last_refresh_timestamp, row_count_consumed, source_index}. source_index is the citation key used in narrative_output (e.g., [src:1]). |
narrative_output | TEXT | REQ | The brain's prose response, with inline citations matching sources_read.source_index values. |
proposed_actions | JSONB | opt | Array of {action_type, target, lever, justification, confidence, proposal_id_chain}. Empty array if no actions proposed. action_type is from the proposed-action enum (see AGT-901/902 specs). |
confidence_flags | JSONB | REQ | Array of {claim_index, level, supporting_source_indices}. Levels: high_confidence / multi_source / inference / speculation. |
data_staleness_acknowledged | BOOL | REQ | TRUE if any source was stale at read time. Surfaced in narrative when TRUE. Hard CHECK: if TRUE, narrative_output must contain a staleness disclosure phrase. |
stale_sources | JSONB | opt | Array of source_index values that were stale. NULL when data_staleness_acknowledged = FALSE. |
model_used | VARCHAR(64) | REQ | Specific model identifier (e.g., claude-sonnet-4-6). Captured for cost tracking and eval reproducibility. |
input_tokens | INTEGER | REQ | Tokens passed to the model. |
output_tokens | INTEGER | REQ | Tokens generated by the model. |
cached_tokens | INTEGER | REQ | DEFAULT 0. Tokens served from prompt cache. Used to attribute cost and validate caching strategy. |
cost_usd_estimate | NUMERIC(10,4) | REQ | Computed at write time using model + token counts. Audit-stable; pricing changes do not retroactively alter historical cost records. |
account_synthesis_signature | VARCHAR(64) | opt | AGT-902 only: hash of (account_id, source_freshness_timestamps). Enables cache hit on repeat queries within freshness window. |
cache_hit | BOOL | REQ | DEFAULT FALSE. TRUE when output was returned from synthesis-signature cache without a fresh model call. |
response_time_ms | INTEGER | REQ | Wall-clock latency from invocation to row write. |
budget_exceeded | BOOL | REQ | DEFAULT FALSE. TRUE when query was truncated due to per-query budget cap. narrative_output explains the truncation. |
created_at | TIMESTAMPTZ | REQ | DEFAULT NOW(). |
| Element | Definition | Why |
|---|---|---|
| Primary key | analysis_id | Surrogate. |
| Index 1 | (proposal_id) | Cohort retrospective queries: find all analyses + downstream actions sharing a proposal_id. |
| Index 2 | (writer_agent_id, created_at DESC) | Per-brain operational queries (cost dashboard, eval batches). |
| Index 3 | (account_id, created_at DESC) WHERE account_id IS NOT NULL | Per-account analysis history for AGT-902 caching. |
| Index 4 | (operator_user_id, created_at DESC) WHERE operator_user_id IS NOT NULL | "Show me my recent brain queries." |
| Index 5 | (account_synthesis_signature) WHERE account_synthesis_signature IS NOT NULL | Synthesis-signature cache lookup for AGT-902. |
| Index 6 | (data_staleness_acknowledged, created_at) WHERE data_staleness_acknowledged = TRUE | Operations alert: how often are brains operating on stale data? |
| CHECK: writer_agent_id | writer_agent_id IN ('AGT-901','AGT-902','AGT-903') (extensible as new brains added) | Enforces the single-writer-identity contract. |
| CHECK: staleness disclosure | If data_staleness_acknowledged = TRUE, narrative_output must contain at least one occurrence of any staleness phrase from a configured list (e.g., 'stale', 'last refreshed', 'data may be out of date'). Enforced via trigger. | Hard rule: stale data without disclosure is a sev-2 incident. Trigger catches at write. |
| CHECK: source citations | Every [src:N] citation in narrative_output must reference a valid source_index in sources_read. Enforced via trigger. | Audit integrity. |
| CHECK: action enum | Each proposed_actions[].action_type must be in the action taxonomy enum for the row's writer_agent_id (AGT-901: draft_play / flag_coverage_gap / recommend_query_for_human / none; AGT-902: per AGT-902 spec; AGT-903: per AGT-903 spec — propose_* family + flag_strategic_risk / recommend_* / none). Enforced via JSON schema dispatched on writer_agent_id. | Brain cannot invent action types; each brain has its own taxonomy. |
| Append-only | UPDATE and DELETE blocked at row level via row-level security (RLS). Only INSERT permitted. | Audit integrity. |
When a brain's proposed action is accepted by a human and routed to a Tier 1 service for execution, the resulting Tier 1 record carries the proposal_id in a designated lineage column. This is the single mechanism that enables cohort-level brain attribution.
| Tier 1 service | Lineage field | Populated when |
|---|---|---|
| AGT-203 ABM Target Selection | ABMPlaybook.originating_proposal_id | A play promoted from SalesPlayLibrary → ABMPlaybook carries the brain's proposal_id from the draft |
| AGT-302 Cadence Coordinator | CadenceEventLog.originating_proposal_id | Sequences executing under a brain-co-designed play carry the proposal_id |
| AGT-503 Expansion Trigger | ExpansionLog.originating_proposal_id | Expansion plays initiated via brain proposal carry the proposal_id (alongside the existing 5-signal scoring) |
| AGT-603 QBR Prep | QBRLog.originating_proposal_id | QBR pull-forwards triggered by a brain proposal carry the proposal_id |
| AGT-405 Meeting Opportunity Prep | OpportunityBriefLog.originating_proposal_id | Briefs generated for brain-recommended meetings carry the proposal_id |
| AGT-504 Customer Communications | CommBriefLog.originating_proposal_id | Comms approved after brain recommendation carry the proposal_id |
originating_proposal_id column. Always nullable — actions taken without brain involvement carry NULL. Cohort retrospective queries filter on WHERE originating_proposal_id IS NOT NULL for the brain-influenced cohort.Every claim in narrative_output carries a confidence level. The brain's job is honest calibration — the human reading the output must be able to tell what the brain knows from what the brain is guessing.
| Level | Meaning | Eval threshold |
|---|---|---|
high_confidence | Direct citation of a Tier 1 source value. Single source supports the claim. | Should be ≥ 60% of claims in a typical output. |
multi_source | Multiple Tier 1 sources corroborate the claim. | Common in synthesis outputs — "usage up AND seat util up AND positive sentiment trajectory" pattern. |
inference | Reasoning beyond direct source. The brain combined inputs to draw a conclusion not literally present in any single source. | Should be ≤ 25% of claims. Watch for drift — inference-heavy outputs may signal sources are insufficient and brain is filling gaps. |
speculation | The brain explicitly marks where it's guessing. Used for forward-looking statements without telemetry support, or for hypotheses about external factors (competitive moves, customer org dynamics) not in any Tier 1 system. | AGT-901 / AGT-902: should be ≤ 10% of claims. AGT-903 exception: multi-quarter strategic reasoning involves more legitimate uncertainty — speculation may legitimately reach 25–30% of claims in option-set memos and strategic retrospectives. Brain is honest about what it doesn't know. |
| Tier | Window | Access |
|---|---|---|
| Hot | 0 to 90 days | Operational reads (brain caching, dashboards, eval batches) |
| Warm | 90 days to 18 months | Quarterly retrospectives, cohort analysis |
| Cold | 18 months to 7 years | Audit only. Required for any audit period covering brain-influenced actions. |
| Purge | > 7 years | Hard delete subject to legal hold check. |
| Role | Read access | Write access |
|---|---|---|
| Brain Agents (AGT-901, AGT-902) | Own writes only (for caching lookups via account_synthesis_signature) | Own rows only. Append-only. Each brain authenticates with its writer identity. |
| RevOps | Full read | None — cannot insert or modify rows. Read-only for cohort retrospective + ops dashboards. |
| Auditors (internal/external) | Full read on audit windows | None. |
| AM/CSM/AE | Read on rows where operator_user_id = self OR account_id IN (assigned_accounts) | None. |
| Other Tier 1 services | None — Tier 1 services do not read brain outputs | None. |