master-capability-record
Master Capability Record
This is the index of BrainstormRouter's load-bearing capabilities — what they do, where they live, and which architecture doc explains them in depth. Ship-log entries reference this record under the "Master Record" lockstep checklist.
The goal: if you're new to the codebase and need to know what the system actually does (vs what marketing claims), this is the file to read first.
> Query, don't read. This file is the _human_ fallback. Agents should query > GET /v1/capabilities (or MCP br_capabilities_query) — the machine-native, trust-scored > version of this record (source of truth: src/capability-graph/seed.ts).
Tier 0 — Agent substrate (identity, mesh, grants, custody)
The agent-orchestration foundation — historically omitted from this record, the exact "forgotten powers" the capability graph now surfaces first-class.
| Capability | Source | Notes |
|---|---|---|
| CAF agent identity (SPIFFE + CA + registry + kill switch) | src/security/caf/* (spiffe.ts, ca.ts, agent-registry.ts, revocation.ts, anomaly-engine.ts) | spiffe://brainstorm.internal/agent/{tenant}/{agent}; cryptographic revocation; anomaly trust |
| A2A mesh (authorized agent-to-agent proxy) | src/security/caf/a2a-proxy.ts, mesh-graph.ts, mesh-rbac.ts | resolve → RBAC authorize → hop-count → payload inspect → forward → record mesh-graph edge |
| Trust envelope (signed scoped grants + delegation chain) | src/security/trust-envelope/schema.ts, sign.ts, verify.ts | br_principal.parent_chain (delegation), br_budget (caps), br_scope — the mandate substrate |
| Credential custody (KMS-envelope BYOK vault + local keystore) | src/db/stores/tenant-provider-key-store.ts, src/security/local-keystore.ts, src/security/secrets.ts | per-tenant customer KMS via STS; resolveSecret() backend; server-side injection (never reveal) |
| Pi Engine (multi-turn agent runtime + tool exec) | src/agents/pi-embedded-runner/, bash-tools.exec-, apply-patch.ts | sandboxed tool execution with approval + abort |
| Grok Bot harness (Cursor-plugin MCP + always-on rules) | plugins/grok-bot/, .cursor-plugin/marketplace.json | Grok Bot uses BR as control plane (route/memory/budget); guide docs/guides/grok-bot.mdx |
Capability tiers
Each capability is tagged with a tier:
- Tier 1 — Hot path, every request: failures here are user-visible 5xx
- Tier 2 — Hot path, fraction of requests: failures degrade specific features
- Tier 3 — Background: failures eventually visible, not request-blocking
Tier 1 — Hot path, every request
| Capability | Source | Architecture doc | Notes |
|---|---|---|---|
| Request authentication (API key, JWT, mTLS) | src/api/middleware/auth.ts | hot-path.mdx | Redis cache hit → 0 DB connections; PR #204 folded tenant status into cache blob |
| Tenant context propagation | src/db/tenant-context.ts | tenant-isolation.mdx | Three layers: RLS, AsyncLocalStorage, query-builder enforcement |
| Provider routing (auto / explicit) | src/router/model-router.ts | thompson-sampling.mdx | Per-request auto = capability-matched auto-selector (model-auto-selector.ts: tier floor + learned quality − cost); Thompson-learned leaderboard; cost-quality frontier, strategy sort |
| Circuit breakers (per provider+model) | src/router/circuit-breaker.ts | circuit-breakers.mdx | Cross-task pub/sub recovery (PR #185); cold-start forcedOpen preservation (PR #201) |
| Budget enforcement | src/api/middleware/budget.ts | hot-path.mdx | 30s in-process tenant-limits cache (PR #203); pipelined recordSpend |
| Rate limiting (per agent / API key / IP) | src/api/middleware/rate-limit.ts, agent-limits.ts | hot-path.mdx | Pipelined Redis ops (PR #214); Redis dual-failure-mode coverage (PR #205) |
| Guardian intelligence (cost prediction, PII scan) | src/api/middleware/guardian.ts | guardian.mdx | LRU-bounded per-tenant Maps (PR #215) |
| Data-protection policy resolution | src/api/middleware/data-protection.ts | (TBD) | Resolves once after auth, before guardrails and the prompt cache; records only |
| Routing constraint enforcement | src/router/model-strategy.ts | (TBD) | checkEndpointConstraints — never relaxed, including on the starvation path |
| Evidence receipts | src/security/evidence-receipt.ts | (TBD) | evidenceMode: required withholds the completion (503) unless a receipt commits |
Tier 2 — Hot path, fraction of requests
| Capability | Source | Architecture doc | Notes |
|---|---|---|---|
| Semantic cache (in-memory + pgvector) | src/router/model-semantic-cache.ts | hot-path.mdx | Tenant-partitioned (PR #213); O(1) LRU eviction (PR #215) |
| Cost-optimizer cascade | src/router/model-cascade.ts | (TBD) | Routes to cheaper model on validity-confirmed completion |
| Community-tier rate limit | src/api/middleware/community-tier.ts | hot-path.mdx | Pipelined 5 Redis ops → 1 (PR #212) |
| Workspace file context injection | src/api/middleware/agent-context-injector.ts | tenant-isolation.mdx | agentId scoping + role-marker stripping (PR #208) |
| Prompt sanitizer | src/api/middleware/prompt-sanitizer.ts | tenant-isolation.mdx | Deny-list strip of role-override markers in workspace files |
| mTLS advisory enforcement | src/api/middleware/mtls-auth.ts | (TBD) | Advisory-by-default; flip to strict via gateway.tls.mtls.meshWritesEnforcement (PR #206) |
| Slack webhook | src/api/routes/admin.ts | hot-path.mdx | Per-IP rate limit BEFORE HMAC verify (PR #207) |
Tier 3 — Background
| Capability | Source | Architecture doc | Notes |
|---|---|---|---|
| Model performance tracking | src/router/intelligence/model-performance.ts | thompson-sampling.mdx | Batched multi-row INSERT on flush (PR #209) |
| Shadow comparator (Thompson vs static benchmarks) | src/router/intelligence/shadow-comparator.ts | thompson-sampling.mdx | Cross-task ZSET persistence; statistical significance pending n>=200 accrual |
| Forensic store (CAF anomaly evidence) | src/security/caf/forensic-store.ts | (TBD) | PR #184 fixed pg result-shape handling |
| Audit chain (tamper-evident operations log) | src/security/audit-chain.ts | (TBD) | Hash-chained append-only |
| Memory extraction queue | src/db/schema/memory-extraction.ts | extraction-queue.mdx | Cross-tenant worker; per-job tenant context for writes |
| Anomaly detection + kill-switch | src/security/caf/anomaly-engine.ts | (TBD) | LRU-bounded per-tenant Maps (PR #215) |
| Sentinel (provider health probing) | src/router/endpoint-sentinel.ts | circuit-breakers.mdx | Recovery-probe filter bypass (PR #187) |
Cross-cutting patterns
Patterns that apply across multiple capabilities, not specific to any single subsystem:
cache-hygiene.mdx—src/utils/lru-map.tsand the bounded-Map invariantredis-failure-modes.mdx— dual-mode coverage (getRedis() === undefined+ thrown ops)tenant-isolation.mdx— three layers + within-tenant agentId scoping
Router invariants (no dedicated doc yet)
Two rules the router must not violate. Both were violated in production before 2026-08-05, so they are recorded here rather than left implicit:
- Preferences degrade; constraints do not. Strategy, cost ceiling, priority,
circuit-breaker state and context window may all be relaxed when the candidate pool is starved. Provider allow/deny, required capabilities, data retention and region may not — relaxing a preference degrades service, relaxing a constraint breaks a promise. The relax path in model-router-select.ts previously worked by listing what to keep, which silently omitted every constraint added after it was written; checkEndpointConstraints is now the single definition, applied on all three narrowing paths.
- Compliance facts are attested, never inferred. Retention, training use and region are
properties of a specific provider ACCOUNT and product, not of a vendor, so they cannot be derived from a provider id. Every fact defaults to unknown, and an unknown fact satisfies no requirement. Detection (PII/DLP classification) may only ever _tighten_ a requirement — a regex miss is not proof that content is free of regulated data.
Capabilities NOT yet documented
The following exist in code but don't have a dedicated architecture doc yet (TBD entries above):
- Cost-optimizer cascade (
src/router/model-cascade.ts) — deserves its own doc on the validity-confirmed-fallback pattern - mTLS / CAF (Cryptographic Agent Framework) — has dedicated runbook at
docs/runbooks/mtls-policy.mdbut no architecture doc - Forensic store + audit chain — security docs at
docs/security/but no architecture doc on the CAF subsystem - Anomaly detection + kill-switch — referenced in security docs; deserves dedicated coverage
- Memory subsystem —
docs/concepts/memory.mdxexists at concept level but no architecture-level doc
Maintenance
This file is updated when:
- A new capability is added (the relevant ship-log entry should reference this file's row)
- An existing capability moves to a different file (update the source column)
- A new architecture doc is written for a previously-undocumented capability (move from "NOT yet documented" to a tier table, with the doc link)
If you're working on a substantive change to any Tier 1 or Tier 2 capability, your ship-log entry should reference both this record and the relevant architecture doc.