CORVUS.md

# Corvus — Platform Blueprint v2.0

*Corvus · Platform Blueprint v2.0 · August 2026 · Confidential*
*Solo-track-owned document — AI Engineer reference, shared with SDE co-founder*

**This version supersedes v1.0 (June 2026).** Where they disagree, this document
reflects what was actually built and decided since — not what was originally planned.
Section 0 explains what changed and why, so nothing here reads as a silent reversal.

---

## 0. What changed since v1.0, and why

v1.0 was written pre-code, as a complete company blueprint. Since then Corvus went
through a real build (`PLAN.md`, Wave 1), a code review (`docs/code-review.md`, 28
verified findings), and a scoping pass specifically on the AI-reasoning side
(§7 below). The result is a narrower, more honest v2. Nothing in the pivot changes
the core thesis — it changes the plan for reaching it.

| v1.0 said | v2.0 says | Why |
|---|---|---|
| Salesforce + HubSpot + CSV connectors, bespoke MCP servers you write | **MCP-as-connectors**: reuse existing community MCP servers (Postgres-MCP first) | Writing and maintaining bespoke connectors was the single biggest scope item in v1.0. Existing MCP servers exist for most of this; Corvus's job is to be a good MCP *host*, not a connector author. |
| Railway / Fly.io → AWS at scale | **Self-host on Hetzner, staged in waves** | Chosen deliberately over "managed-first." Cheaper, and data-sovereignty positioning (§4) is stronger when Corvus's own infra is self-hosted, not merely BYOK at the model layer. |
| 6-layer stack incl. ClickHouse, S3, Vault, ~12 services from day one | **4 containers at MVP** (Postgres+pgvector, Redis, app, Caddy); ClickHouse/observability/MinIO are Wave 3 | Standing up 12 services before a product exists was identified as the exact trap the original blueprint warned against in its own risk section. Staged waves fix that. |
| Subagent orchestration, hooks system, episodic/semantic memory store | **Deferred, not cancelled.** Wave 1 ships one bounded reasoning loop (`ask.ts`, `MAX_TURNS = 8`) | Anthropic's own finding (§7.1) and Corvus's own build experience agree: the loop itself should stay simple. Complexity earns its place once the semantic layer under it is solid — not before. |
| CORVUS.md as a literal config file the harness parses at runtime | **CORVUS.md as this document** — a human/AI-readable blueprint, not a runtime artifact | The functional equivalent — the tenant's actual business definitions — now lives in the **Metric Registry** and **Entity Catalog** (§7.3–7.4), which is queryable and versioned, not a markdown file the harness re-parses per request. |
| "Cursor for business data," CFO/audit/compliance scope included | **Narrower**: sales/ops-facing BI, compliance explicitly cut | Kept from v1.0 — this one didn't change. Compliance-grade reporting has different liability and audit requirements than an ops manager asking about win rate; conflating them was correctly identified as scope creep. |
| One data source, live-call only | **Same for MVP** — canonical-table sync (a local warehouse) is explicitly Wave 2, gated on the Insight Feed needing it | Confirmed still correct: live-call MCP is fine for ad-hoc queries; it breaks for scheduled background scans and heavy aggregation, so sync is deferred until something actually needs it. |

The one-paragraph version: **v1.0 was the vision, correctly ambitious for a company
document. v2.0 is what two engineers can actually build and defend, in an order that
proves the trust story (§1) before anything else.**

---

## 1. What Corvus is

Corvus is a **multi-tenant business-intelligence harness**: a thin web app in front of
a harness core that takes a plain-English question from a business user — a sales VP,
an ops manager, not a developer — figures out what data it needs, fetches **verified**
numbers from the company's connected systems, and returns an answer with **citations
and a confidence level**.

**Tagline:** *Your data. Your model. Total clarity.*

**Positioning:** "Cursor for business data" — a serious professional tool a business
user can trust in front of leadership, in the register of Linear, Vercel, Stripe, or
Hex. Not a consumer AI chatbot.

**The one non-negotiable rule**, unchanged since v1.0 and the thing everything else in
this document exists to protect:

> **The AI model never computes numbers.** It calls a tool; the tool — deterministic,
> tested code — returns a verified number; the model only explains it.

A wrong number costs Corvus the customer instantly. Every architectural decision below
is in service of never presenting an unverified number as if it were verified.

---

## 2. The one loop that matters

> User connects **one** data source → asks a question in plain English →
> gets a **correct answer with a citation to the source rows** + a confidence level.

Everything else in this document is addition. This loop already works end-to-end in
the current build (`askCorvus()` in `src/harness/ask.ts`). Ship it to design partners,
let their real questions decide what's next.

```mermaid
sequenceDiagram
    participant U as User (browser)
    participant R as /api/ask route (SDE)
    participant A as askCorvus() — ask.ts (AI)
    participant G as callModel() — gateway (SEAM)
    participant T as Tools — registry.ts (AI)
    participant S as Semantic Layer (AI, NEW — §7)
    participant C as MCP connectors (SDE)

    U->>R: "Which products are about to run out of stock?"
    R->>A: askCorvus(tenantId, question)
    A->>A: assemble tools = built-in + discover_metrics + MCP-discovered
    A->>G: callModel({tenantId, messages, tools})
    G-->>A: "I need to call discover_metrics, then calculate_kpi"
    A->>S: discover_metrics(query) → governed metric match
    A->>T: runTool(tenantId, call)
    T->>C: (if raw query) callMcpTool → real DB query
    C-->>T: real rows
    T-->>A: ToolResult { value, citation }
    A->>G: feed tool results back, call model again
    G-->>A: (repeat until no more tool calls)
    A-->>R: { answer, citations, confidence }
    R-->>U: rendered answer + "show me the data"
```

---

## 3. The stack, as built

```
Layer 1  Experience      Next.js web app (query box + answer + "show me the data")
Layer 2  API + Auth      Next.js API routes · Better Auth (multi-tenant) · JWT
Layer 3  Harness Core    Model Gateway · MCP Host · Tool Registry · Semantic Layer (NEW)
Layer 4  Connectors      Existing MCP servers (Postgres-MCP first; platform MCPs as needed)
Layer 5  Data            PostgreSQL + pgvector · Redis  (canonical tables added when sync is needed)
Layer 6  Infra           Hetzner VPS · Docker · Caddy (auto-TLS)
```

**Layer 3 is the moat**, same as v1.0 said — that part never changed. What changed is
*what's in it*. v1.0 imagined Context Engine + Semantic Layer + Agent Orchestrator +
Hooks + Memory as parallel systems built together. What's actually true a build cycle
later: the **Semantic Layer is the load-bearing piece**, and it should be built
deliberately, on top of a loop that's already proven simple and correct. §7 is the
current, concrete design for it — this is the piece v1.0 gestured at ("Business
Semantic Layer... build alongside first connector") but never fully specified.

### Model Gateway (BYOK)

Unchanged in principle from v1.0, real and shipped in code:

- `callModel(tenantId, messages, tools) → ModelCallResult` — the single door every
  provider call goes through (`src/harness/gateway/`).
- **BYOK is architectural, not a feature.** A tenant's own Anthropic/OpenAI key,
  encrypted at rest (AES-256-GCM, HKDF per-version keys), decrypted only inside the
  gateway. One managed default (Claude) for tenants without their own key.
- This remains the enterprise sales unlocker v1.0 identified: BYOK removes the
  procurement blocker, honors data-processing agreements for sensitive-data
  customers, and means Corvus never becomes obsolete as models improve — a tenant
  upgrades their own key.
- `ollama` provider exists but is dev/test only, gated behind
  `CORVUS_DEV_PROVIDER=ollama`, never in a production code path.

### MCP Host — Layer 3 as MCP *client*, Layer 4 as connectors

This is the single biggest architectural pivot from v1.0, and it's a simplification,
not a compromise:

- **What it buys:** no bespoke Salesforce/HubSpot/Odoo API integration to write or
  maintain. The model calls MCP tools through a standard interface. Corvus is
  architecturally the host/harness; MCP servers are the tool layer — exactly the
  positioning v1.0 wanted, achieved with far less code.
- **What it doesn't solve** (still true, still designed around): MCP servers are thin
  API wrappers returning raw data, not canonical schema — the semantic layer (§7) is
  still Corvus's to build. Most are live-call, not synced — fine for ad-hoc queries,
  blocks aggregation-heavy analytics and the Insight Feed until Wave 2 adds a sync
  layer. Corvus inherits each server's maintenance quality and auth model — vet,
  pin versions, keep a fallback.
- **The shortcut that made Postgres-first correct:** the most mature MCP server in
  existence is the Postgres MCP server, and self-hosted Odoo — common among Arab
  SMBs, and among Corvus's own early prospects (BeExpress, Sweet&Fit) — runs on
  Postgres. Point a read-only Postgres MCP server at the Odoo DB and skip the Odoo
  API entirely for MVP.
- **Security posture, hard-won and non-negotiable:** the community
  `@henkey/postgres-mcp-server` advertises 18 tools including arbitrary SQL and
  mutations, and does **not** block them without extra config — verified directly
  against a live instance, not assumed from docs. Corvus enforces its own tool
  allowlist at the host layer (`mcp/host.ts`) rather than trusting a connector's
  internal safety switch. Only `pg_execute_query` is allowlisted; its own handler
  independently rejects anything that isn't `SELECT`/`WITH`. This same
  don't-trust-the-connector discipline applies to every future MCP server added.

### Tool Registry — the trust primitive, unchanged

`query_source`, `calculate_kpi`, `compare_periods` — three deterministic tools. The
model never does math; tools return verified numbers with citations, the model
explains them. This is the actual moat, and it hasn't moved since v1.0 first stated
the rule.

---

## 4. What makes it defensible

Carried forward from v1.0, still the correct list, now field-tested:

- **The model never computes numbers** — only tested, deterministic code does.
  Competitors letting a model estimate a number are one hallucination from losing a
  customer's trust.
- **Every answer is cited** — a user can always see the underlying rows, not just
  trust a black box. `confidence` (`high`/`medium`/`low`) is scored honestly: no
  tool calls, a tool error, or hitting the reasoning-loop turn cap all suppress
  `"high"` — the system tells the truth about its own uncertainty rather than
  presenting every answer with false confidence.
- **BYOK** — cost control and data-handling comfort at the enterprise end; see §3.
- **Multi-tenant from day one** — every table has `tenant_id`; every query is scoped.
- **Data sovereignty**, elevated since v1.0: self-hosting Corvus's own infra (not
  just BYOK at the model layer) is the strongest differentiator against
  platform-native agentic BI (Oracle, SAP, Microsoft Fabric) and semantic-layer
  incumbents (Snowflake Cortex, Databricks, Looker/Gemini) — none of which offer a
  cross-platform, self-hosted, BYOK harness. This was validated in a competitive
  pass after v1.0 shipped: the "connect data to AI" premise is increasingly covered
  by incumbents; sovereignty over both the model *and* the infrastructure isn't.

---

## 5. Who it's for

Unchanged from v1.0: operations- and sales-facing professionals at small/medium
businesses running a self-hosted, database-backed system (Odoo is the anchor case),
who currently wait on an analyst or don't ask the question at all because the
friction is too high. Validate with a small number of design partners before
expanding sources or customer base — v1.0's own instinct here ("talk to 20 business
users first... the three most painful questions they can't answer, that's your MVP
scope") held up and shaped the Wave 1 cut directly.

Global-first positioning, Arab market as the geographic wedge — not an Arab-only
product. Odoo depth + Arabic-language handling is the defensible niche *within* a
global addressable market, not the whole market.

---

## 6. Co-founder split

Unchanged in spirit from v1.0; updated to match what the codebase's own seam
(`src/harness/types.ts`) now encodes formally rather than just describing:

**AI Engineer (you) owns:**
- The reasoning loop (`ask.ts`) and confidence scoring
- The Tool Registry (`tools/registry.ts`) — specs + dispatch, deterministic bodies
- The Semantic Layer (§7 — Entity Catalog, Metric Registry, `discover_metrics`)
- Provider SDK integration inside the gateway (`gateway/providers/*.ts`)
- The eval suite (§7.5)

**Software Engineer (co-founder) owns:**
- Auth, multi-tenancy, the encrypted key vault, usage logging
- The MCP host's connection/transport machinery (`mcp/host.ts`) and each connector's
  launch/allowlist definition (`mcp/connectors/*.ts`)
- Database, migrations, infra (Docker, Caddy, Hetzner)
- The web app shell and every route around `askCorvus()`

**Together:** the seam itself (`types.ts` — `callModel`, `askCorvus`, `ToolResult`,
`Citation`) — v1.0's "shared schema" instinct was right; what changed is that it's
now a committed TypeScript file both tracks build against and can't change solo,
not a conceptual agreement. Same discipline applies to any future shared file
(flagged explicitly in `docs/ai-track-guide.md §8` — "Don't touch" isn't a wall,
it's "that's a conversation, not a solo edit").

---

## 7. The Semantic Layer — the piece v1.0 gestured at, specified for real

This is new since v1.0 and is the direct answer to two questions asked while
researching what Corvus still needs on the AI side: how Anthropic's own data team
gets self-service analytics to ~95% automated accuracy, and how WrenAI's open
"context layer" makes text-to-SQL governed instead of merely plausible.

### 7.1 The finding

Corvus already has the right foundation: the model never computes, tools do, every
answer is cited. What's missing is the layer that tells the model **what's queryable
in the first place** before it calls a tool — and this is not a hypothetical gap.
Anthropic's internal data-science team frames analytics accuracy as *"a context and
verification problem, not a code generation issue,"* and names three failure modes:
**concept↔entity ambiguity**, **staleness**, and **retrieval failure**. Independently,
dbt Labs' 2026 benchmark found semantic-layer grounding lifts text-to-SQL accuracy
from 90.0%→98.2% and 84.1%→100% across two frontier models, and that **schema/semantic
failures — not syntax — account for ~81% of text-to-SQL errors**. WrenAI's whole
premise (an open "context layer" — governed models, definitions, and memory beneath
generation) is the open-source expression of the same finding.

Corvus's current `kpi/schema.ts` allowlist (`ENTITIES`, `fields`, `numericFields`) is
**already a primitive semantic layer** — it's just one entity deep (`deals`) and
disconnected from how the model discovers what exists (KPI names are currently a
string baked into a tool description). This already broke once, concretely: the model
hallucinated `pipeline_coverage`, a KPI that was never real, because nothing told it
otherwise. The fix is to grow the existing primitive, not build something new beside it.

### 7.2 Shape of the change

```
BEFORE (Wave 1)                          AFTER (v2)
─────────────────                        ──────────
ask.ts                                   ask.ts
 └─ buildTools(tenantId)                  └─ buildTools(tenantId)
     └─ 6 hardcoded KPI names                 └─ Semantic Layer
        as a string in a                          ├─ Entity Catalog   (grows ENTITIES
        tool description                          │   into a real, browsable model)
                                                    ├─ Metric Registry  (grows KpiDefinition
                                                    │   into versioned, governed metrics)
                                                    ├─ discover_metrics tool (NEW)
                                                    └─ Business Glossary / synonyms (NEW)
```

The seam does not change. This is additive: a layer between `buildTools()` and the
model, plus one new tool that lets the model *ask what exists* instead of Corvus
guessing what to cram into a description string.

### 7.3 Entity Catalog

Extends `EntitySpec` (not a rewrite — the validation logic in `kpi/schema.ts` stays):
`displayName`, `description`, `grain`, `fieldDescriptions`, approved `relationships`
only, and `source: { connectorId, syncedAt }` for provenance. Hand-authored or
Claude-drafted-then-human-approved — **never model-inferred at query time**. Anthropic
tried auto-generating definitions with an LLM from raw tables; it *"produced
plausible-looking definitions that encoded the very ambiguities [they] were trying to
eliminate"* — net negative on their evals. Generate the documentation with Claude; a
human owns the definition.

### 7.4 Metric Registry

Grows `KpiDefinition` + `kpi/engine.ts` — same structured formula, same allowlisted,
parameterized execution, no free-form SQL, ever. Adds: mandatory `displayName`/
`description` (the only thing the model sees when discovering a metric), append-only
**versioning** (editing `win_rate` creates `win_rate@2`, doesn't mutate `win_rate@1` —
the direct fix for the staleness failure mode), `synonyms[]` populated from real
question logs, and `asOf` freshness carried into `Citation` — the smallest version of
Anthropic's "provenance footer" that fits Corvus's existing types.

### 7.5 `discover_metrics` — the highest-leverage single change

Replaces cramming every KPI name into `calculate_kpi`'s description. Modeled on
WrenAI's discover→select→execute flow and Anthropic's "agent is structurally required
to hit the semantic layer first":

```ts
{
  name: "discover_metrics",
  description:
    "Search the tenant's governed metric catalog by keyword or business concept " +
    "before calculating anything. ALWAYS call this before calculate_kpi if you are " +
    "not certain a metric name is exact — do not guess a plausible-sounding name.",
  inputSchema: { type: "object", properties: { query: { type: "string" } }, required: ["query"] },
}
```

Keyword/synonym match over the Metric Registry — same shape as Mercer's BM25+LSH
entity retrieval, smaller corpus, no vector DB needed at Corvus's current scale.
`calculate_kpi`'s description shrinks back to static; one line added to `ask.ts`'s
system prompt: *"Always try discover_metrics or an existing KPI before calling
query_source directly."* This is what lets Corvus scale past a handful of KPIs
without the tool description growing unboundedly.

### 7.6 What this explicitly does not include yet

Matching the same "write it down so it stops nagging you" discipline `PLAN.md` uses:
no vector DB (Anthropic's own ablation found raw-corpus retrieval moved accuracy
*less than a point*, even with the right answer present and read); no adversarial-
reviewer sub-agent (+6% accuracy for +32% tokens/+72% latency — a real lever, wrong
priority before a design partner); no dashboard generation / WrenAI's "Deploy" beat;
no cross-connector joins; no automated correction-harvesting agent — a manual weekly
`QueryLog` review does this until question volume justifies automating it.

### 7.7 Validation — the part that doesn't exist yet

Today Corvus has one signal the reasoning loop works: a 6-question smoke test run
once. Minimum viable eval, sized correctly for a two-person team:

- **~20–30 golden Q&A pairs per tenant/domain** (diminishing returns past a few
  dozen per topic, and that ceiling drops with each model generation — don't
  over-invest).
- **Pinned to seeded, deterministic data**, never live — the exact trap Anthropic
  calls out: *"an eval written against live data goes stale the moment the
  underlying number moves."*
- **Wired into `test:integration`**, not optional — any PR touching `kpi/schema.ts`,
  `kpi/engine.ts`, or the semantic layer re-runs it.
- **Assert confidence tiers, not just correctness** — a wrong-but-confident answer
  is the actual product risk Corvus exists to prevent; the eval set should test for
  that directly, not just for the right KPI name.

### 7.8 Security posture — extends, never relaxes, the existing discipline

`discover_metrics` and the Entity Catalog are read-only, tenant-scoped metadata
lookups — same `tenant_id` scoping as every query in `kpi/engine.ts`, no new attack
surface. Governance stays **compile-time**: `validateConditions` runs before any SQL
is built, re-checked even for a stored definition — the Entity Catalog must preserve
that ordering, never introduce a "generate SQL, then check" path. `query_source`
remains the only raw-query tool, still routed through the same MCP allowlist
discipline as §3's MCP Host section. Growing the catalog makes `query_source` *safer*
to use — it does not add a new way to reach the database.

---

## 8. Build sequence

Where §0's cut narrowed *what* to build, this is *what order*, current as of this
version:

1. ~~Hetzner Wave 1, Model Gateway, MCP host, Tool Registry, reasoning loop~~ — **done**,
   verified via `test:integration` and `smoke:kpi-selection`.
2. **Auth / real multi-tenancy** (SDE) — the one blocker left before "ship to 5
   design partners."
3. **Entity Catalog schema + migration** — backfill the existing `deals` entity;
   zero behavior change, just structure (§7.3).
4. **Metric Registry additions** — versioning, synonyms, mandatory descriptions on
   the 6 seeded KPIs (§7.4).
5. **`discover_metrics` tool** — the actual reasoning-loop change (§7.5).
6. **Golden eval set**, wired into CI — before KPI #7 is added, not after (§7.7).
7. **Ship to 5 design partners.** Their questions decide the second data source,
   which KPIs get added next, and which synonyms the Metric Registry actually needs
   — not a roadmap guess.

**Not now** (unchanged from `PLAN.md`, still correct): microservices, ClickHouse,
self-hosted observability, MinIO, the Insight Feed, a Chrome extension, a Slack bot,
multi-platform joins, 3+ connectors, Hijri calendar, Arabic generation, a Report
Builder, a public API, Stripe/billing.

---

## 9. Risks worth tracking

Carried forward from v1.0, amended where the semantic layer changes the picture:

- **A wrong answer is an instant-churn event** — unchanged as the central design
  constraint. The semantic layer (§7) is a direct mitigation, not a new risk: it
  closes the concept↔entity ambiguity gap that's the *dominant* real-world failure
  mode for this category of system (~81% of text-to-SQL errors, per §7.1).
- **Semantic layer maintenance becomes its own ongoing cost** as KPI/entity count
  grows — this is the trade Anthropic's team also made, and their mitigation
  (colocate definition + doc changes in the same PR, enforced by review discipline)
  is adopted directly in the `corvus-semantic-layer` skill referenced in §7.
- **MCP server quality/maintenance** — still not fully in Corvus's control. Mitigate:
  vet + pin versions, keep the CSV/Postgres fallback, never trust a connector's
  internal safety switch (§3).
- **No local warehouse while live-call MCP is the only path** — blocks
  aggregation-heavy analytics and the Insight Feed. Mitigate: canonical-table sync
  is explicitly Wave 2, gated on having a concrete reason to build it.
- **Self-host ops tax** — every service is a potential 2am page. Mitigate: staged
  waves (§0), automated backups, no service added without a reason.

---

*Corvus · Platform Blueprint v2.0 · August 2026 · Confidential*
*Reflects the actual state of the build as of Wave 1 completion + the semantic-layer
scoping pass. Supersedes v1.0 in full; v1.0 remains available as historical record
of the original company-level vision.*