# PunkGo Kernel
[](https://github.com/PunkGo/punkgo-kernel/actions/workflows/ci.yml)
[](https://crates.io/crates/punkgo-kernel)
> When AI does everything for you, who proves you still exist?
**PunkGo** is a local sovereignty compute kernel: giving individuals the inalienable right to write history on their own hardware.
## What Is This?
PunkGo implements the **Right to History** — the principle that every actor (human or agent) can spend energy to perform actions, commit results to verifiable world state, and leave an indelible trace.
The kernel is a single-writer, append-only event system built on three primitives:
<p align="center">
<img src="assets/world-model.svg" alt="PunkGo world model — Actor spends Energy to commit State" width="680">
</p>
## Architecture
```
punkgo-kernel/
bins/
punkgo-cli/ # CLI client (IPC over Unix socket / Windows named pipe)
crates/
punkgo-core/ # Core types: Actor, Energy, Action, Boundary, Consent
punkgo-kernel/ # Kernel engine + daemon binary (cargo install punkgo-kernel)
src/
audit.rs # Merkle tree, inclusion/consistency proofs, C2SP checkpoints
state/ # Persistence: ActorStore, EnergyLedger, EventLog, EnvelopeStore, BlobStore
runtime/ # 7-step submit pipeline, lifecycle, energy producer
daemon/ # punkgo-kerneld binary (IPC server + energy producer)
testkit.rs # Test utilities: temp state dirs, request builders
```
### Submit Pipeline
Every action goes through a **7-step pipeline**:
<p align="center">
<img src="assets/pipeline.svg" alt="PunkGo 7-step submit pipeline" width="680">
</p>
1. **Validate** — check actor status, boundary permissions, action well-formedness
2. **Quote** — compute energy cost for the action
3. **Reserve** — lock energy from actor's balance
4. **Validate Payload** — for `execute` actions, validate the actor-submitted result (PIP-002 §2)
5. **Settle** — finalize energy accounting
6. **Append** — write the committed event to the append-only log with cryptographic hash
7. **Receipt** — return a verifiable receipt (event ID, log index, event hash)
### Energy System
Energy is produced continuously, anchored to the machine's hardware compute power (INT8 TOPS). Each tick, energy is distributed proportionally among active **agents** based on their shares. Humans (including root) receive a one-time initial balance but do not participate in tick-based distribution. The kernel itself holds no energy (energy neutrality).
### Actor Model
- **Human** — unconditional existence, cannot be deleted or downgraded
- **Agent** — conditional existence, created by humans with declared purpose and bounded permissions
- Only humans can create agents (PIP-001 §5/§6)
- Agents require authorization envelopes with budget, checkpoint levels, and expiry
- Agents can be supervised via **hold rules** (`hold_on`) at envelope creation — matching actions are intercepted for Human judgment before execution (PIP-001 §11)
### Boundary Enforcement
Every actor declares `writable_targets` (glob pattern + action types) at creation time. Access is default-deny. Privileged targets (`system/*`, `ledger/*`) are restricted to root. Child actor boundaries must be a subset of their parent's boundary.
### Execute Submission (PIP-002)
The kernel is a **committer, not an executor**. For `execute` actions, the actor performs the execution externally and submits the result. The kernel validates the payload format and records the event.
The execute payload must contain:
| `input_oid` | `sha256:<64 hex>` | Reference to serialized input |
| `output_oid` | `sha256:<64 hex>` | Reference to serialized output |
| `exit_code` | integer | Process exit code |
| `artifact_hash` | `sha256:<64 hex>` | SHA-256 of raw output bytes |
| `output_bytes` | integer (optional) | Output size for IO cost calculation |
Energy cost: `25 + output_bytes / 256`. The kernel does not verify whether OID references point to actual content — it records what the actor claims, consistent with `mutate` behavior.
### Audit Trail
<p align="center">
<img src="assets/merkle-proof.svg" alt="PunkGo Merkle inclusion proof — 3 hashes prove 1 event in a tree of 8" width="680">
</p>
Every committed event is added to a Merkle tree (Google tlog algorithm). The proof is logarithmic: 3 hashes verify 1 event in 8; 20 hashes verify 1 event in a million.
- **Inclusion proof** — prove a specific event exists in the tree (RFC 6962)
- **Consistency proof** — prove the tree is append-only between two sizes (RFC 6962)
- **C2SP checkpoints** — signed tree heads compatible with Go's `sum.golang.org` and Sigstore Rekor
These proofs enable whitepaper invariants §3.5 (append-only provable) and §3.7 (independently verifiable). Any RFC 6962 verifier can audit PunkGo's log — no PunkGo software required.
**Trust model**: The current Merkle proofs guarantee **append-only integrity** — no silent deletion or modification. However, **a root operator with database access could theoretically rebuild the tree from scratch**. This is the "trust the operator" boundary: sufficient for local sovereignty (you trust your own hardware), but not for trustless third-party audit. **Future work will introduce cryptographic mechanisms to make history unforgeable even by root.**
## Quick Start
### Install from crates.io
```bash
cargo install punkgo-kernel
```
This installs the `punkgo-kerneld` daemon binary.
### Build from Source
Requires Rust 2024 edition (1.85+).
```bash
cargo build --workspace
cargo test --workspace
```
### Start the Kernel Daemon
```bash
punkgo-kerneld
# or from source:
cargo run --bin punkgo-kerneld
```
### Use the CLI
```bash
# Check kernel health
cargo run --bin punkgo-cli -- read health
# Create a new actor
cargo run --bin punkgo-cli -- seed-actor alice --energy 5000
# Check actor energy
cargo run --bin punkgo-cli -- read actor_energy --actor-id root
# Submit an action (JSON payload)
cargo run --bin punkgo-cli -- submit '{"actor_id":"root","action_type":"mutate","target":"workspace/hello","payload":{"msg":"world"}}'
# View recent events
cargo run --bin punkgo-cli -- read events --limit 5
# Query the audit trail
cargo run --bin punkgo-cli -- audit checkpoint
cargo run --bin punkgo-cli -- audit proof 0
```
## Tool Definitions
**[specs/kernel-tools.json](specs/kernel-tools.json)** — MCP-compatible tool definitions for all kernel operations. Machine-readable, no running kernel required. Covers Quote, Submit (all action types), and Read (all query kinds) with full input/output JSON schemas.
## Applications
- **[punkgo-jack](https://github.com/PunkGo/punkgo-jack)** — AI tool hook adapter: every tool call gets a cryptographic receipt
- **[punkgo-watchdog](https://github.com/PunkGo/punkgo-watchdog)** — real-time kernel monitor with terminal dashboard
## Governance
PunkGo is governed by two documents:
- **PIP-002: Execute Submission** ([EN](docs/PIP-002_EN.md) | [ZH](docs/PIP-002_ZH.md)) — actor executes, kernel records (supersedes PIP-001 §12)
All governance changes enter the event history (whitepaper §3, invariant 6).
New rules are introduced exclusively through **PIPs** (PunkGo Improvement Proposals) — they fill gaps in the whitepaper without overriding it.
## Design Philosophy
- **The kernel is a committer, not a judge** — it provides a single linearization point for actions, not moral authority
- **No a-priori restrictions** — design is opt-in, not pre-emptive
- **Append-only history** — errors are corrected by appending compensating events, never by rewriting
- **Hardware-anchored economics** — energy production is tied to physical compute, not arbitrary tokens
- **Right to History** — every individual can write to the world state through their own hardware
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for build instructions, code style, and how to propose PIPs.
## License
[MIT](LICENSE)