Covenant — the governed connection layer (runtime + premium console)

README.md

@@ -1,36 +1,80 @@
-This is a [Next.js](https://nextjs.org/) project bootstrapped with [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app).
+# Covenant
 
-## Getting Started
+**The governed connection layer.** One call that discovers, authorizes, executes, proves, and learns.
 
-First, run the development server:
+MCP asks what an agent *can* do. APIs *do* it. Neither makes the call itself accountable. Covenant fuses both into a single governed connection — and seals a cryptographic proof every time.
 
-```bash
-npm run dev
-# or
-yarn dev
-# or
-pnpm dev
-# or
-bun dev
+> The connection is the asset.
+
+---
+
+## What it is
+
+Covenant treats every agent→capability call as a **covenant**: a binding, verifiable agreement that runs through nine governed phases before any side effect happens, and leaves a tamper-evident proof behind.
+
+```
+agent (any model) ──▶ ◆ covenant · 9 governed phases ──▶ capability ──▶ ⛓ sealed proof → PGL
 ```
 
-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+### The 9-phase pipeline
 
-You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+| # | Phase | What it decides |
+|---|-------|-----------------|
+| 1 | Identity & Security | Resolve agent, verify **Ed25519** signature, reject replays |
+| 2 | Capability & Policy | Resolve capability, compose system/owner/runtime policies, compute effective permissions |
+| 3 | Safety & Anomaly | Score the call against behavioral baselines; quarantine on high severity |
+| 4 | Cost & Budget | Enforce per-agent budgets and overage policy |
+| 5 | Approval | Hold for M-of-N human quorum when required |
+| 6 | Execution | Invoke the capability, capture output |
+| 7 | Evidence & Proof | Seal a **SHA-256 hash-chained** evidence record (who/what/when/why/how) |
+| 8 | Audit & Compliance | Log, classify, set retention |
+| 9 | Response | Update trust, return the verdict + proof |
 
-This project uses [`next/font`](https://nextjs.org/docs/basic-features/font-optimization) to automatically optimize and load Inter, a custom Google Font.
+## This is real, not a mock
 
-## Learn More
+- **Real cryptography** — Ed25519 keypairs per agent, canonical request signing, signature verification, and a SHA-256 hash-chained evidence ledger (each record links to the previous; the chain is replayable). See `src/lib/covenant/crypto.ts`.
+- **Real policy engine** — three-tier composition (system → owner → runtime), conflict detection, deterministic resolution (system-wins, then most-restrictive), and live effective-permission calculation. See `src/lib/covenant/governance.ts`.
+- **Real safety** — statistical anomaly detection vs. behavioral baselines (request spikes via μ+3σ, new-capability access, off-hours, failure spikes), trust suppression, quarantine, and approval quorum. See `src/lib/covenant/safety.ts`.
+- **Real intelligence** — cost attribution + budgeting and a fused risk score (trust + anomalies + denials + budget pressure → threat level). See `src/lib/covenant/intelligence.ts`.
+- Fully typed TypeScript, **no `any`**.
 
-To learn more about Next.js, take a look at the following resources:
+## The interface
+
+The pipeline *is* the product. The app is an instrument panel, not a CRUD admin:
+
+- **Console** — build a call, sign it, and watch all nine phases decide it in real time; expand any phase to see its reasoning. Override toggles (tamper signature, bypass policy/safety/cost) let you see each gate's effect.
+- **Registry** — live capability discovery: "what can this agent do, right now?"
+- **Agents** — trust + fused risk per agent, with suspend control.
+- **Ledger** — the hash-chained evidence trail, with backward chain replay from any record.
+- **Governance** — policy composition with enable/disable toggles and a live effective-permissions probe.
+- **Safety** — anomaly feed and the quarantine queue with M-of-N approve/deny.
+
+## Run it
+
+```bash
+npm install
+npm run dev # http://localhost:3000
+npm run build # production build
+npm run lint # eslint
+```
 
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+The runtime seeds a realistic fleet (agents, capabilities, three-tier policies, cost models, baselines) and warms the ledger with signed traffic on first load, so every view is alive immediately.
 
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js/) - your feedback and contributions are welcome!
+## API
 
-## Deploy on Vercel
+| Method | Route | Purpose |
+|--------|-------|---------|
+| `POST` | `/api/request` | Sign + run a call through the pipeline |
+| `GET` | `/api/state` | Full runtime snapshot |
+| `GET` | `/api/discover/{agentId}` | Capability discovery (effective permissions) |
+| `GET` | `/api/compose?agent_id&capability_id` | Policy composition + effective permissions |
+| `GET` | `/api/pgl/{hash}` | Retrieve an evidence record |
+| `GET` | `/api/replay/{hash}` | Walk the hash chain backwards |
+| `POST` | `/api/quarantine/{id}` | Approve / deny a quarantined request |
+| `POST` | `/api/policy/{id}` | Enable / disable a policy |
+| `POST` | `/api/agent/{id}` | Toggle agent suspension |
+| `POST` | `/api/budget` | Set an agent's budget for a capability |
 
-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+## Stack
 
-Check out our [Next.js deployment documentation](https://nextjs.org/docs/deployment) for more details.
+Next.js 14 (App Router) · TypeScript · Tailwind CSS · Framer Motion · Node `crypto`. Part of the **Veklom** ecosystem.