Skip to content

PunkGo/punkgo-kernel

Repository files navigation

PunkGo Kernel

CI crates.io

Every AI action gets a receipt.

A local sovereignty compute kernel — append-only event system with cryptographic audit trails. The kernel is a committer, not a judge: it provides a single linearization point for actions and verifiable proofs, not moral authority.

PunkGo trust layers — Merkle ordering, Ed25519 identity, TSA time binding

Trust Layers

Each layer adds a guarantee the layer below cannot provide:

Layer Provides Proves
Merkle Ordering + integrity "this event is in the tree, the tree is append-only"
Ed25519 Identity binding "this kernel instance signed this checkpoint"
TSA Time binding "this checkpoint existed before time T"

A root operator with database access could rebuild the tree — this is the single-machine trust boundary. TSA (via punkgo-jack) adds time binding: you cannot backdate a timestamped checkpoint.

Quick Start

cargo install punkgo-kernel    # installs punkgo-kerneld daemon
punkgo-kerneld                 # start the kernel

Pair with punkgo-jack for AI tool integration:

cargo install punkgo-jack
punkgo-jack setup claude-code  # install hooks into Claude Code
# every tool call now gets a cryptographic receipt

How It Works

Every action goes through a 7-step pipeline — validate, quote energy, reserve, check payload, settle, append to Merkle tree, return receipt.

PunkGo 7-step submit pipeline

The receipt contains an event ID, log index, and cryptographic hash. Third parties can verify any event with an RFC 6962 inclusion proof — 3 hashes verify 1 event in 8; 20 hashes verify 1 event in a million.

Evolution

Version What changed Spec
v0.5.1 Windows daemon.addr flock fix (separate lock from info) CHANGELOG
v0.5.0 Ed25519 checkpoint signing, trust layer architecture PIP-003
v0.4.0 Per-PID IPC, single-instance guard, --replace CHANGELOG
v0.3.0 Energy starvation fix, Windows IPC fix CHANGELOG
v0.2.0 Execute submission — kernel commits, agent executes PIP-002
v0.1.0 Energy + Actors + Boundaries + Consent + Merkle audit PIP-001

Ecosystem

  • punkgo-jack — AI tool hook adapter (Claude Code, Cursor). Every tool call gets a receipt + optional RFC 3161 TSA timestamp
  • punkgo-watchdog — real-time kernel monitor with terminal dashboard

Documentation

Document Description
Whitepaper (ZH) Foundational axioms, world model, 7 invariants
PIP-001 (ZH) Energy, actors, boundaries, consent
PIP-002 (ZH) Execute submission
PIP-003 (ZH) Checkpoint authentication
Architecture Crate structure, pipeline, IPC
Tool Definitions MCP-compatible JSON schemas

Design Philosophy

  • Committer, not judge — single linearization point, not moral authority
  • No a-priori restrictions — opt-in design, not pre-emptive
  • Append-only — errors corrected by compensating events, never rewriting
  • Hardware-anchored — energy tied to physical compute (INT8 TOPS)

License

MIT