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.
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 | Thompson sampling, cost-quality frontier, ranking tiebreaker, 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) |
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/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
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/cascade.ts) — covered briefly inthompson-sampling.mdxbut 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.