Brain-Ready Views — Contract & Catalog

Layer 9 dependency · Per-service projections of Tier 1 canonical tables, optimized for LLM consumption · Owned by the underlying Tier 1 service · Read-only from L9 perspective · The load-bearing piece of the brain layer's read contract

Tier 1 → Tier 2 contract Specced · v30 (v37 strategy extension) 30 views catalogued Tier 1 service owners (per-view)

Why this document exists. The L9 brain specs (AGT-901, AGT-902, AGT-903) reference brain-ready views — MetricsCalc.brain_view, UsageMeteringLog.account_brain_view, the per-account composite view, and the v37 strategy_brain_view extensions — as the read contract between Tier 2 brains and Tier 1 services. This document is where the views actually get defined: which fields, which aggregation, which freshness window, which token budget. Without this, none of the three brain agents can actually run.

v37 update: AGT-903 Strategy Brain (specced v37, build deferred) introduces a new contract obligation on 10 Tier 1 services to ship strategy_brain_view extensions — longer time windows (4–12 trailing quarters), cohort axes where applicable, and outcome-correlation projections. Cataloged in the new AGT-903 section below.

Purpose

A brain-ready view is a precomputed projection of a Tier 1 service's canonical table, optimized for consumption by LLM-native callers. The brain doesn't read raw canonical tables — it reads brain-ready views. This decoupling is what keeps brain calls cost-bounded (10× input compression typical) and contract-stable (brain prompt changes don't require service schema changes, and vice-versa).

Owned by the underlying Tier 1 service. AGT-702 owns MetricsCalc.brain_view; AGT-501 owns CustomerHealthLog.account_brain_view. The brain layer is a consumer of these views — never a writer. View definitions can change only via the service owner's spec process, with v-bump and changelog ripple.

The brain-ready view contract

Every brain-ready view must define the following:

Element	What it captures
Source table	The canonical Tier 1 table the view projects from. Single source per view; no cross-table joins inside one view (unless explicitly composite, e.g., AGT-902's account composite).
Owning service	The Tier 1 service responsible for view maintenance. Same service that owns the source table.
Projection rule	Which fields survive into the view, plus any computed/aggregated fields. Typical compression: top-N rows by relevance, aggregate stats over the rest.
Filter rule	Row scope. For per-account views: `WHERE account_id = ?`. For top-N views: `ORDER BY priority_metric DESC LIMIT N`. Always parameterized.
Refresh cadence	How often the view is recomputed. Most views: daily batch. Some: event-driven (e.g., on canonical table write). Brain reads `last_refresh_timestamp` from view metadata to detect staleness.
Staleness threshold	Max time since last refresh before brain treats data as stale. View-specific based on the underlying source's volatility. Brain surfaces staleness in BrainAnalysisLog when threshold exceeded.
Token budget	Max tokens the view can produce when serialized for LLM input. Hard cap; views that exceed truncate with a flag.
Used by	Which brains (and occasionally services) consume the view. AGT-901, AGT-902, or both.
Backwards compatibility	View additions are non-breaking; field removals are breaking and require coordinated brain prompt updates.

Compression discipline — why views, not raw tables

Per the v26 architecture cost model, "aggressively summarize Tier 1 inputs into brain-ready views" was one of three high-leverage cost tactics. The expected compression ratio is 10× or better — brain reads ~30K tokens per query instead of ~300K from raw tables. Three patterns achieve compression:

Top-N + aggregate. Top 20 rows by salience, plus aggregate stats over the full population. Used for cross-population views (Opportunities, Accounts, etc.).
Time-windowed slice. Trailing 90 days at daily granularity, or trailing 12 months at monthly granularity. Used for time-series views (UsageMeteringLog, MetricsCalc).
Per-account composite. One row per account, joining 11 sources at the row level. Used by AGT-902 to bound input to a single account's full picture.

Composition without query expansion. The composite view is precomputed (denormalized) per-account at refresh time, not constructed via 11 joins at brain query time. This is why the AGT-902 cost model works — one read, ~30K tokens, instead of 11 reads at variable cost.

Staleness model — how brains detect stale views

Every brain-ready view exposes two metadata fields the brain reads on every invocation:

{
  "view_metadata": {
    "last_refresh_timestamp": "2026-05-01T14:23:11Z",
    "staleness_threshold_hours": 24,
    "is_stale": false   // computed: NOW() - last_refresh_timestamp > threshold
  },
  ...rest of view payload
}

The brain reads is_stale first. If TRUE, the brain sets data_staleness_acknowledged = TRUE in BrainAnalysisLog and surfaces the staleness in narrative_output. Brain may proceed with caveats but must not estimate values from stale data — per the staleness recognition hard requirement (100%, eval-enforced).

If last_refresh_timestamp is missing entirely (view-metadata bug or first-run), brain treats as maximally stale and refuses to produce a confident output. Loud failure beats silent fabrication.

AGT-901 Pipeline Brain — 9 brain-ready views

Cross-account / cross-segment views. Each view exposes a top-N + aggregate pattern over the canonical source. Refresh cadence is daily by default; specific views may go faster.

View	Source	Owner	Projection	Refresh	Stale >	Tokens
`MetricsCalc.brain_view` 901	MetricsCalc	AGT-702	Magic Number, NRR, GRR, R40 variants, CAC Payback — current snapshot + trailing 4Q trend by segment. Plan-vs-actual delta.	On MetricsCalc snapshot (monthly + quarterly)	2 business days post month close	~3K
`Opportunities.brain_view` 901	Opportunities	AGT-401	Top 20 at-risk deals by ACV × (100 - health_score). Aggregate stats over rest: count by stage, mean ACV, win-rate trailing 4Q.	Daily	24h	~4K
`ForecastLog.brain_view` 901	ForecastLog	AGT-402	Current bottoms-up forecast + delta vs prior week + 3-component breakdown (new logo / renewal / expansion). Reference top-down (AGT-404) for divergence flag.	Weekly (per AGT-402 cadence)	7 days	~2K
`Accounts.brain_view` 901	Accounts	AGT-201	Tier distribution by segment + vertical. ICP score percentile bands. Recent rescore activity (trailing 30 days). Sample of recent T1 nominations.	Daily	24h	~3K
`AccountPriorityScore.brain_view` 901	AccountPriorityScore	AGT-206	Composite score distribution by segment. Queue freshness stats (oldest unworked T1, mean days-since-update). Top 30 highest-priority accounts with rep assignment status.	Daily	24h	~3K
`CapacityPlan.brain_view` 901	CapacityPlan, HiringPlan, TerritoryDefinitions	AGT-105	Deployed eRep + ramp-status by segment. Open territories with quarter-of-impact. Hiring pipeline status. Coverage ratios.	Weekly	7 days	~2K
`WinLossLog.brain_view` 901	WinLossLog	AGT-703	Trailing 4Q top loss reasons by segment + vertical. Competitive displacement trend. Rep-aggregate win rate vs benchmark (manager-level only, no individual). Forecast bias trend.	Monthly (lightweight refresh weekly)	3 business days post month close	~3K
`CadenceEventLog.brain_view` 901	CadenceEventLog	AGT-303	Sequence performance by template + segment (meeting rate, reply rate, suppression rate). Top suppression reasons. Active play execution status (post-v27 ripple: includes `play_id` aggregation).	Weekly	7 days	~3K
`VoCSynthesisLog.brain_view` 901	VoCSynthesisLog	AGT-604	Trailing 90-day customer themes (top 10). Competitive mention frequency. Sentiment trajectory by segment. Open feedback loops to L0 / L2.	Monthly synthesis (weekly digest)	14 days	~2K

AGT-901 may read multiple views per query. Total token budget per query bounded by 50K input cap (per AGT-901 spec). 9 views × ~3K avg = 27K, leaving headroom for the question + system prompt.

AGT-902 Account Brain — per-account composite view

AGT-902 reads a single composite view scoped to one account. The composite is precomputed (denormalized) per-account at refresh time, joining 11 source views at the row level. The brain does not see 11 separate queries — it sees one structured snapshot.

Composite view shape

{
  "view_metadata": {
    "last_refresh_timestamp": "ISO 8601",
    "staleness_threshold_hours": 24,
    "is_stale": false,
    "stale_components": []   // populated when individual sub-views are stale
  },
  "account_id": "uuid",
  "components": {
    "customer_health": { ... },        // per CustomerHealthLog.account_brain_view
    "churn_risk": { ... },             // per ChurnRiskLog.account_brain_view
    "expansion_signals": { ... },      // per ExpansionLog.account_brain_view
    "usage_metering": { ... },         // per UsageMeteringLog.account_brain_view
    "opportunities": { ... },          // per Opportunities.account_brain_view
    "conversation_intel": { ... },     // per ConvIntelligence.account_brain_view
    "qbr_history": { ... },            // per QBRLog.account_brain_view
    "onboarding": { ... },             // per OnboardingLog.account_brain_view
    "implementation": { ... },         // per TechnicalMilestoneLog.account_brain_view
    "payment_health": { ... },         // per PaymentEventLog.account_brain_view
    "account_root": { ... }            // per Accounts.account_brain_view
  }
}

Per-component staleness: each sub-view has its own refresh cadence and staleness threshold. The composite's stale_components array lists which sub-views are stale. The brain may proceed with fresh components and surface specific stale dimensions in narrative.

11 sub-view component definitions

Component	Source	Owner	Projection	Refresh	Stale >	Tokens
`customer_health` 902	CustomerHealthLog	AGT-501	Current score + 90d trend at weekly granularity + 7-dimension breakdown + ConvIntelligence adjustment + payment modifier state.	Daily (matches AGT-501 cadence)	24h	~2K
`churn_risk` 902	ChurnRiskLog	AGT-502	Current tier (Critical/High/Medium/Low) + renewal proximity multiplier state + top 3 risk drivers + 30d tier transition history.	Daily	24h	~1.5K
`expansion_signals` 902	ExpansionLog	AGT-503	Open expansion plays + 5-signal scoring breakdown + suppression history + trailing 90d signal events.	Event-driven on threshold breach + daily batch	24h	~2K
`usage_metering` 902	UsageMeteringLog	AGT-804 (ingestion service writes)	Trailing 90d consumption per SKU at daily granularity. Trailing 90d seat utilization at daily granularity. Overage event log. Filtered to `audit_status IN (verified, pending_recon)`.	Per UsageMeteringLog production schema (event-driven on metering period close)	48h (longer than other views to absorb late-arrival)	~5K (largest sub-view)
`opportunities` 902	Opportunities	AGT-401	Open opportunities for the account + per-opp health trend (30d) + stage history + most recent forecast category.	Daily	24h	~3K
`conversation_intel` 902	ConvIntelligence	AGT-407	Trailing 90d call summaries with `call_owner_role` filter capability. Sentiment trajectory (per role). Top objection patterns (per role). Unaddressed showstoppers list. Stakeholder expansion signals.	Per-call (on transcript receipt)	14 days (calls are infrequent for some accounts; staleness threshold longer than for high-frequency views)	~4K
`qbr_history` 902	QBRLog	AGT-603	QBR history for the account: dates, attendees, outcomes, open commitments, action item status. Most recent QBR's expansion/churn flags.	Event-driven on QBR completion	Last QBR + 100 days (if no QBR recorded in 100 days, marked stale-by-absence)	~2K
`onboarding` 902	OnboardingLog	AGT-601	Current onboarding stage (if active) or completion date (if completed). MAP status. Comp hold status (if active per AGT-104 integration). Day-1 health flag history.	Daily during active onboarding; static post-completion	24h during active; n/a post-completion	~1K
`implementation` 902	TechnicalMilestoneLog	AGT-602	Milestones list (6 standard) with completion + customer_sign_off status. Open technical risks. Active IE assignment.	Event-driven on milestone updates	14 days (milestones move infrequently)	~1.5K
`payment_health` 902	PaymentEventLog	AGT-803	Current payment_health_status (Current/Overdue/Failed/Suspended). Recent payment events (30d). AGT-501 modifier state.	Event-driven on payment state changes + daily batch	24h	~1K
`account_root` 902	Accounts, TerritoryDefinitions, RepActivity	AGT-201 (root)	Account demographics. AE/CSM/AM assignment with rotation history (30d). Contract terms summary (start, end, total_contract_value, sku composition). ICP tier + score breakdown. Territory assignment.	Daily	24h	~2K

Composite total: ~25K tokens typical, ~30K worst case for an account with high-volume ConvIntelligence and dense usage history. Within AGT-902's 35K input budget per spec. Account synthesis signature caching (per AGT-902 spec) hits the cache for repeat queries within freshness window — saves cost on iterative meeting-prep workflows.

AGT-903 Strategy Brain — 10 strategy view extensions

Multi-quarter portfolio reasoning. Each strategy_brain_view extension differs from its AGT-901 sibling by (a) longer time window (4–12 trailing quarters vs current period), (b) cohort axis where applicable (signup-quarter cohorts on AGT-501, AGT-503), and (c) outcome-correlation projections (e.g., ICP score × realized LTV on AGT-201). Refresh cadence is at most quarterly — strategic reasoning operates on durable trends, not week-over-week noise.

v37 contract obligation on 10 Tier 1 services. Each owning service ships its strategy view extension independently — incremental rollout supported. AGT-903 declines on any missing or stale view rather than estimating from raw rows (per AGT-903 spec failure-mode discipline: refusal cost ≈ one tool call, not a full analysis).

View	Source	Owner	Projection	Refresh	Stale >	Tokens
`MetricsCalc.strategy_brain_view` 903	MetricsCalc	AGT-702	Magic Number / NRR / GRR / R40 (3 variants) / CAC Payback by segment + vertical + cohort, trailing 8–12 quarters. Plan-vs-actual delta history. Multi-quarter trajectory smoothing.	Quarterly (post month-3 close)	10 business days post quarter close	~5K
`WinLossLog.strategy_brain_view` 903	WinLossLog	AGT-703	Loss-reason evolution + competitive mention frequency + forecast-bias evolution by segment, trailing 8 quarters. Multi-quarter pattern surfaces (not week-over-week noise).	Quarterly	10 business days post quarter close	~4K
`CustomerHealthLog.cohort_brain_view` 903	CustomerHealthLog	AGT-501	Cohort retention curves by signup quarter / segment / vertical / ICP tier. Trailing 8 cohorts at quarterly granularity. Late-cohort projections fed by TOOL-013 cohort retention forecaster (when available).	Quarterly	10 business days post quarter close	~5K
`Accounts.icp_outcome_brain_view` 903	Accounts	AGT-201	Correlation of 6-dimension ICP score to realized LTV / NRR / churn / win-rate, by signup-quarter cohort. Per-dimension correlation breakdown — supports propose_icp_revision use case (which dimensions correlate most strongly with realized outcomes?).	Quarterly	10 business days post quarter close	~4K
`MarketAssumptions.strategy_brain_view` 903	MarketAssumptions	AGT-205	TAM / SAM / SOM by product family + vertical + segment with current penetration. Includes annual TAM refresh + quarterly SAM update lineage. Source for vertical-entry sizing (per AGT-903 propose_vertical_entry).	Quarterly (TAM annually, SAM quarterly per AGT-205)	30 days (vertical sizing changes infrequently)	~3K
`VoCSynthesisLog.strategy_brain_view` 903	VoCSynthesisLog	AGT-604	Trailing 8-quarter theme evolution + competitive theme evolution. Cross-vertical theme heat-map. Multi-quarter shifts in customer narrative (not weekly digest noise).	Quarterly	30 days	~3K
`CapacityPlan.strategy_brain_view` 903	CapacityPlan	AGT-105	Deployed eRep + ramp + utilization trajectory by segment, trailing 8 quarters. Hiring plan vs actual. Productivity per eRep / per loaded HC / per loaded GTM+Mktg HC across multi-quarter window.	Quarterly (monthly cadence available; quarterly snapshot taken)	10 business days post quarter close	~3K
`QuotaPlanLog.strategy_brain_view` 903	QuotaPlanLog	AGT-101	Quota attainment distribution + bias by segment, trailing 8 quarters. Coverage ratio history. Amendment frequency + amendment reasons over time. Supports propose_segment_redefinition + propose_capacity_reallocation reasoning.	Quarterly	10 business days post quarter close	~3K
`ExpansionLog.strategy_brain_view` 903	ExpansionLog	AGT-503	Expansion realization rate + cohort upsell trajectory by segment, trailing 8 quarters. Play-type retrospective (which expansion plays converted, which didn't). Land-and-expand bet measurement.	Quarterly	10 business days post quarter close	~3K
`TopDownForecast.strategy_brain_view` 903	TopDownForecast	AGT-404	Top-down vs bottoms-up reconciliation across trailing 4–8 quarters + segment-level decomposition. Forecast-vs-actual variance history. Multi-quarter forecast bias and structural gaps.	Quarterly (per AGT-404 cohort-conversion model)	10 business days post quarter close	~3K

AGT-903 query budget: 10 strategy views × ~3.6K avg ≈ 36K tokens typical. Within AGT-903's 200K input budget per spec — leaves ample headroom for question, system prompt, and multi-turn iteration during CRO review. Per-view stale-flag propagates to data_staleness_acknowledged on BrainAnalysisLog same as AGT-901 / AGT-902.

Refresh cadence is quarterly, not daily. Strategic reasoning operates on durable multi-quarter trends. Daily refresh would be expensive without changing the answer to "should we enter this vertical?" or "is the ICP rubric still predicting outcomes?" The 10-business-days post quarter close window covers month-end finance reconciliation and AGT-702 / AGT-703 quarterly snapshots — by then all upstream data is settled.

Tier 3 tool dependency. Two strategy views depend on Tier 3 cognition for forward projections: CustomerHealthLog.cohort_brain_view may call TOOL-013 (Cohort Retention Forecaster) for late-cohort projections; vertical-entry analysis on Accounts.icp_outcome_brain_view may call TOOL-014 (Segment-LTV Decomposer) for LTV decomposition by segment / vertical / ICP tier. Both tools specced v37, not yet prototyped. AGT-903 build is gated on these.

Backwards compatibility & change management

Change type	Compatibility	Process
Add a new field to a view	Non-breaking	Service owner updates view spec; brain may or may not consume the new field. No coordinated deploy required.
Remove a field from a view	Breaking	Service owner ripple-audits brain prompts (AGT-901, AGT-902, any service consumers). Coordinated deploy: brain prompt updates ship before view field removal.
Change projection rule (e.g., top-20 → top-10)	Possibly breaking	If brain prompt depends on the count, breaking. If just a sample, non-breaking. Service owner judgment + ripple audit.
Change refresh cadence to faster	Non-breaking	Brains read fresher data. No prompt impact. Cost may increase if cadence affects compute.
Change refresh cadence to slower	Possibly breaking	Staleness threshold may need adjustment. Coordinated change with brain spec.
Change staleness threshold	Non-breaking but auditable	Service owner adjusts threshold; brain reads new threshold from view metadata. Logged in changelog.

View definitions are versioned alongside the owning service. The brain_view_contracts_hash field on BrainEvalLog (per v28 spec) detects when view contracts change between eval runs — triggers a re-eval before brain promotion.

Implementation patterns

Three implementation patterns work; service owners pick the simplest that meets the cadence + freshness requirement:

Pattern	When to use	Example
Materialized view	Source table is large; view is read-heavy; refresh cadence ≥ daily.	Most AGT-901 views (MetricsCalc, Accounts, Opportunities, AccountPriorityScore, CapacityPlan).
Compute on read with cache	Source table is small or read-rare; freshness matters.	QBRLog (event-driven, low volume), TechnicalMilestoneLog.
Precomputed denormalized snapshot	Composite views requiring joins across many sources.	AGT-902's per-account composite. Refresh job runs daily, writes the full per-account snapshot to a separate table; brain queries the snapshot table directly.

The composite pattern is what makes AGT-902 cost-bounded. Constructing the composite at brain query time would require 11 reads per query, blowing both latency and token budget. Precomputed denormalized snapshots are the operationally correct choice.

Eval linkage

Brain-ready views are part of the brain eval contract. The Brain Eval Question Catalog includes 5 deliberately stale-fixture questions; each tests staleness recognition for a specific view. Eval reviewers verify that view_metadata.is_stale = TRUE propagates through to BrainAnalysisLog.data_staleness_acknowledged = TRUE.

If a view spec changes between eval runs, the brain_view_contracts_hash on BrainEvalLog detects the change and forces a re-eval before brain promotion to production.

Cost of maintaining brain-ready views

Cost component	Estimate
Materialized view storage (10 views)	Negligible — views are small (most < 5K rows of compressed projection).
Daily refresh compute (10 views)	Modest — runs on existing data warehouse; piggybacks on existing AGT-XXX nightly jobs.
Per-account composite refresh (AGT-902)	Higher — runs per active account. For 10K accounts, daily refresh compute is real but bounded.
Storage of denormalized composite snapshot	~10KB per account snapshot × 10K accounts = 100MB. Trivial.
View-driven brain cost reduction	10× vs raw-table reads. Saves ~$200/month in brain token spend at expected volumes.

Net effect: views save more in brain token spend than they cost in compute + storage. The economics are favorable; the architectural correctness is the bigger win.

Brain-Ready Views · Contract & Catalog · Tier 1 → Tier 2 contract · Schema v30 + v37 strategy extension
Owners: per-view, the underlying Tier 1 service. Brain layer is read-only consumer.
30 views catalogued: 9 cross-population (AGT-901), 11 per-account components (AGT-902 composite), 10 strategy view extensions (AGT-903, v37). Total view payload bounded ~50K tokens for AGT-901, ~30K for AGT-902, ~36K typical for AGT-903.
Companion: AGT-901 Pipeline Brain · AGT-902 Account Brain · AGT-903 Strategy Brain · BrainAnalysisLog · StrategyRecommendationLog · BrainEvalLog
This is the load-bearing piece of the brain layer's read contract. Without these views formally defined, the three brain agents are theory.