# Vaked Ecosystem — Research Summary

> Executive overview for external researchers. Snapshot 2026-06-16.  
> Companion to `MASTER_RESEARCH_INDEX.md` (full catalog).  
> Companion to `CROSS_REFERENCE_MAP.md` (doc interconnect graph).

---

## What is Vaked?

Vaked is a flake-native **capability-graph language** for agentic, native, mesh-aware, parallel systems. It answers a single question: *what is the minimal, correct description of an agentic system that a machine can turn into a running, policy-enforced, observable deployment?*

A Vaked declaration compiles through a typed semantic graph into ordinary artifacts — Nix flakes, Zig daemon configs, eBPF policy manifests, OTel config, CrabCC indexes. The compilation target is not a container or a VM. It is a bare-metal NixOS host with a purpose-built OTP supervision plane running single-purpose Zig enforcement daemons.

**Mantra:** *Vaked declares. Nix materializes. OTP supervises. Zig enforces. eBPF testifies. CrabCC indexes. Surfaces reveal.*

---

## Architecture at a Glance

```
Vaked source (.vaked)
    │
    ▼
vakedc / vakedz (parse → check → lower)
    │
    ▼
typed semantic graph (LPG)
    │
    ▼
generated artifacts
    ├── flake.nix / NixOS modules      (Nix materializes)
    ├── Zig daemon configs             (Zig enforces)
    ├── eBPF policy manifests          (eBPF testifies)
    ├── OTel collector config
    ├── CrabCC indexes / catalogs      (CrabCC indexes)
    └── provenance.json               (reproducibility chain)
    │
    ▼
NixOS host (vakedos: EPYC 4345P)
    │
    ▼
OTP supervision plane → Zig enforcement daemons → eBPF evidence → operator surfaces
```

---

## Key Research Contributions

### 1. Capability Graph as Source of Truth

Vaked introduces the **capability graph** as the single typed declaration from which all infrastructure artifacts derive. There is no separate config language, no YAML sprawl, no drift between what's declared and what's deployed. The graph is typed (structural conformance, generics, POLA attenuation), deterministic (byte-identical lowering), and provenance-tracked (source hash → graph hash → artifact hash).

- Design: `docs/language/0001-language-manifesto.md`
- Grammar: `vaked/grammar/vaked-v0-plus.ebnf` (v0.3, 29 kinds)
- Type system: `docs/language/0011-type-system.md`
- Lowering: `docs/language/0012-lowering.md`

### 2. Compile-Time POLA (Principle of Least Authority)

The type system enforces POLA at compile time — not at runtime, not through linting, not through convention. Every capability a principal uses must be covered by a granted capability. Authority only decreases along delegation paths. This is **decidable** (always terminates) and **deterministic**.

- POLA rules: `docs/language/0011-type-system.md` §4–6
- Security model: `SECURITY.md`
- Threat model: `docs/language/THREAT_MODEL.md`

### 3. Deterministic, Hermetic Lowering

The lowering pass (graph → artifacts) is pure, total, and hermetic. Identical declarations produce byte-identical artifacts. Every compilation emits a `provenance.json` chaining source → graph → artifact hashes. This enables auditable infrastructure: given a deployed artifact, you can trace it back to the exact source that produced it.

- Lowering design: `docs/language/0012-lowering.md`
- Provenance: `docs/language/0012-lowering.md` §6.2
- MLIR lowering roadmap: `docs/language/0019–0024` (MLIR dialect + passes)

### 4. eBPF as the Evidence Layer

In Vaked's architecture, eBPF is not an optimization or a monitoring add-on. It is the **evidence layer** — the kernel is the single authoritative witness. If the kernel says it happened, it happened. eBPF policy manifests are generated from Vaked capability declarations, not hand-written.

- Membrane architecture: `docs/runtime/agent-guardd.md`
- eBPF daemon: `agent_guardd/`
- Security membranes paper: `docs/papers/vaked-security-membranes-architecture.md`

### 5. Wire Protocol for Capability Systems

HCP (Hyper-Capability Protocol) and Litany define a wire protocol purpose-built for capability-graph systems — not retrofitted from REST or gRPC. RFC series 0001–0007 covers the frame format, the wire description language (hcplang), multi-agent state dependency, control frames, transport, and post-quantum sealed images.

- RFCs: `protocol/rfcs/0001–0007`
- hcplang: `protocol/hcplang/grammar.ebnf`

### 6. Agent Fleet as a Capability System

The Vaked repo is itself operated by a fleet of ~10 AI agents running as GitHub Actions workflows. These agents are declared in Vaked, supervised by the OTP plane (planned), and their actions are testified to a hash-chained `eventd` ledger. The fleet is the first dogfooding target for the language.

- Fleet index: `VAKED_AGENTS.md`
- Agent designs: `vaked-agents/BACKLOG.md`
- SWE agent field: `docs/superpowers/specs/2026-06-13-swe-af-gha-runner-design.md`

### 7. 100k → 1M Worker Scalability (Verified)

The system has been verified at 100k concurrent workers (273ms avg parse time, deterministic) with a projected path to 1M. The scalability is a property of the compiler pipeline, not the runtime — the lowering pass is designed for deterministic fan-out.

- Benchmark: `scripts/benchmark-100k-scalability.py`
- Examples: `vaked/examples/swe-swarm-100k-workers-scalability.vaked`, `swe-swarm-1m-workers-scalability.vaked`
- Hardware spec: `docs/infrastructure/1M-SCALABILITY-HARDWARE-SPEC.md`

---

## Current Status (June 2026)

| Component | Status | Details |
|-----------|--------|---------|
| **Language (WP1)** | ✅ Done | Grammar v0.3, 29 kinds, EBNF complete |
| **Compiler — Python (WP2)** | ✅ Done | vakedc: parse → check → lower, stdlib-only |
| **Compiler — Zig** | 🟡 Early | vakedz v0.1.0: parser + JSON AST |
| **Wire Protocol (WP3)** | 🟡 RFCs | RFCs 0001–0007 drafted; impl starts Jun 24 |
| **Daemons (WP4)** | 🟡 Stubs | Python reference stubs for guardd, eventd, memoryd, sandboxd |
| **Materialization (WP6)** | ⬜ Planned | vakedos NixOS host defined; runtime TBD |
| **Agent Fleet** | 🟢 Live | 10 agents running on GitHub Actions |
| **Arxiv Paper (#103)** | 🟡 Finalizing | Target upload: July 1–8 |

---

## Research Domains & Entry Points

| Domain | Core question | Start here |
|--------|--------------|------------|
| **Language design** | What is the minimal description of an agentic system? | `docs/language/0001-language-manifesto.md` |
| **Type systems** | Can POLA be decided at compile time? | `docs/language/0011-type-system.md` |
| **Compilers** | How do you lower a capability graph to heterogeneous artifacts? | `docs/language/0012-lowering.md` |
| **MLIR** | Can MLIR dialects represent capability-graph topologies? | `docs/language/0019-mlir-vaked-dialect.md` |
| **Protocols** | What does a wire protocol for capability systems look like? | `protocol/rfcs/0001-hcp.md` |
| **eBPF** | Can kernel evidence replace trust in agent self-reports? | `docs/runtime/agent-guardd.md` |
| **Agent systems** | What happens when agents are capability-graph nodes? | `VAKED_AGENTS.md` |
| **Scalability** | Can a declarative compiler scale to 1M workers? | `docs/infrastructure/1M-SCALABILITY-HARDWARE-SPEC.md` |
| **Security** | What does compile-time POLA actually prevent? | `SECURITY.md` → `docs/language/THREAT_MODEL.md` |
| **Reproducibility** | Can infrastructure be provenance-tracked like software? | `docs/language/0012-lowering.md` §6.2 |

---

## Key Numbers

- **Grammar:** v0.3, 29 node/edge kinds
- **Compiler:** Python (vakedc) + Zig (vakedz), stdlib-only / no external deps
- **Parsers:** 2 (Python: PEG recursive descent; Zig: cache-native port)
- **Lowering targets:** 8 (flake.nix, Zig configs, eBPF manifests, OTel, CrabCC, RUNTIME.md, provenance.json, systemd stubs)
- **RFCs:** 7 (0001–0007, HCP through PQ-sealed images)
- **Reference daemons:** 4 Python stubs (guardd, eventd, memoryd, sandboxd)
- **Active agents:** 10 (ralph, pr-review, @vaked-ci, doc-keeper, yardmaster, telebot, label-tagger, provost, swe-af, social-post)
- **Verified scale:** 100k workers, 273ms avg parse, deterministic, projected 1M
- **Design docs:** 50+ (language series + specs + plans + decisions)
- **Test files:** 20+ spec tests with golden fixtures
- **Arxiv target:** July 1–8, 2026

---

## For Researchers New to the Project

1. **Read the manifesto** (`docs/language/0001-language-manifesto.md`) — it's 16 lines and captures the philosophy.
2. **Read the context** (`docs/context/PROJECT_CONTEXT.md`) — the canonical overview.
3. **Skim the grammar** (`vaked/grammar/vaked-v0-plus.ebnf`) — see what the language actually looks like.
4. **Read the type system paper** (`docs/language/0011-type-system.md`) — the core research contribution.
5. **Browse the examples** (`vaked/examples/`) — see real declarations (agent fields, supply chains, swarms).
6. **Check the timeline** (`docs/context/TIMELINE.md`) — what's real vs planned.

The full catalog of 120+ documentation artifacts is in `MASTER_RESEARCH_INDEX.md`.  
The cross-reference graph showing how docs interconnect is in `CROSS_REFERENCE_MAP.md`.

---

## Contact & Collaboration

- **Repo:** `peterlodri-sec/vaked-base` (GitHub)
- **Paper:** `docs/papers/vaked-language-v0.1.md` (arxiv target #103)
- **Roadmap:** `ROADMAP_2026-2027.md`
- **License:** See `LICENSE`

---

*This summary and its companion documents (`MASTER_RESEARCH_INDEX.md`, `CROSS_REFERENCE_MAP.md`) are part of the `docs/research/` package — a comprehensive research onboarding kit for the Vaked ecosystem.*