Corvid documentation

Corvid is a programming language where dangerous AI actions either compile with a proof or do not compile at all. The compiler reads approve, Grounded<T>, effect rows, and budget annotations the way other compilers read types, and it refuses to emit a binary if a tool call that should be gated by an approval is reachable without one.

The docs follow the Diataxis shape: tutorials, how-to guides, reference, explanation. Use whichever section matches what you are doing.

The Corvid Book — sequential learning

Read top to bottom to learn the language.

1. Why Corvid
2. Install
3. Quickstart
4. Tutorial: build a refund agent
5. Syntax basics
6. Types
7. Modules and imports
8. Effects
9. Approve
10. Grounded
11. Agents
12. Prompts
13. Errors and Result
14. Pattern matching
15. Project layout
16. Testing
17. Building and targets
18. Replay

Guides — task-focused how-to

• Backend — HTTP server, routes, middleware.
• Persistence — std.db, migrations, audit log.
• Jobs and schedules — durable runner, retries, DST cron.
• Auth and approvals — JWT, OAuth, approval product.
• Observability — OTel, lineage, redaction.
• Connectors — Gmail, Slack, MS365, etc.
• WASM target — browser, edge, wasmtime.
• FFI: Python — calling Python from Corvid.
• FFI: C/Rust — exposing Corvid as a cdylib.
• Editor and LSP — VS Code, Neovim, JetBrains.
• Debugging — common errors and how to fix them.
• Performance — what’s fast, what’s slow.

Recipes — small focused patterns

RAG, approval-gated tool, multi-step agent with checkpoints, provider routing, local model fallback, audit log per decision.

Reference — lookup material

• Grammar — formal EBNF.
• Lexer rules — continuation, brackets, triple-quoted.
• CLI reference — every corvid command.
• Compile-time guarantees — the registry.
• Inventions — full proof matrix.
• Inventions tour — short index.
• Standard library — per-module reference.
• Stdlib connectors — Gmail, Slack, etc.
• Reference apps — canonical examples.
• Core semantics — registry-derived spec.
• Package imports — package manager flow.

Migration — coming from another language

• From Python — for LangChain / DSPy refugees.

Operations — running Corvid in production

• Production checklist
• Receipts and signed builds
• Operator runbooks
• Production guide
• Observability conformance
• CI

Security — model and policy

• Security model — TCB, threat model, what’s defended.
• Stability contract — SemVer rules + v1.0 surface.

Internals — spec and implementation

• Effect spec — the formal effect algebra.
• Bundle format
• WASM ABI
• Host compliance
• Testing primitives
• Package manager scope

Help

• FAQ
• Glossary

Meta — project-level docs

• Project conventions
• Release policy
• Upgrade migrations
• Beta program
• Launch claim audit
• Claim inventory
• Launch rehearsal
• v1.0 demo script
• AI benchmarks
• Reference apps launch status

Phases — development records

Phase-by-phase dev records, audits, and refactor logs. These are historical engineering documents, not user-facing material. Browse phases/phase-NN-*.md for any phase mentioned in ROADMAP.md.