punkgo-watchdog

Creation Process Provenance — the first official example project built on PunkGo Kernel.

Watches a directory for file changes and submits them to the kernel, forming a verifiable creation trail backed by a Merkle append-only log.

When AI does everything for you, who proves you still exist?

---

What It Does

Every time you create, modify, or delete a file, watchdog captures the event — file path, SHA-256 hash, size — and submits it to PunkGo Kernel. The kernel stores each event in a totally-ordered log with Merkle tree proofs, making the entire history tamper-evident and independently verifiable.

This is Creation Process Provenance: not just proving a file exists, but proving when and how it came into being.

---

Quick Start

Prerequisites

Build PunkGo Kernel first (two binaries: punkgo-kerneld and punkgo-cli).

# Build kernel
cd punkgo-kernel
cargo build

# Build watchdog
cd punkgo-watchdog
cargo build

1. Start the kernel daemon

cd punkgo-kernel
cargo run --bin punkgo-kerneld

You should see output like:

INFO kernel bootstrapped state_dir="state"
INFO named pipe IPC server listening endpoint="\\.\pipe\punkgo-kernel"

The daemon creates a state/ directory for its SQLite database and logs.

2. Start watching

cd punkgo-watchdog
cargo run -- watch .

Watchdog auto-connects to the kernel, creates an actor, and starts monitoring:

[watchdog] connecting to kerneld at \\.\pipe\punkgo-kernel...
[watchdog] kerneld is healthy
[watchdog] actor 'watchdog' not found, creating...
[watchdog] actor 'watchdog' created
[watchdog] watching E:\my-project (debounce=500ms)

3. Edit files, observe the trail

echo "hello world" > test.txt

Watchdog reports in real time:

[create] test.txt  log#1 hash=a1b2c3d4e5f6a7b8…

Every file save is automatically recorded in the kernel.

4. View history

cargo run -- history

#      log      time                 event    target                         sha256
------------------------------------------------------------------------------------------
1      log#0    2026-02-20 06:30:12  create   test.txt                       a1b2c3d4e5f6a7b8…
2      log#1    2026-02-20 06:31:05  modify   src/main.rs                    e5f6a7b8c9d0e1f2…
3      log#2    2026-02-20 06:32:18  modify   src/ipc.rs                     c9d0e1f2a3b4c5d6…

Total: 3 records

5. Verify a file

cargo run -- verify test.txt

File:       test.txt
Size:       12 bytes
Current:    sha256=a1b2c3d4e5f6a7b8…
On-chain:   sha256=a1b2c3d4e5f6a7b8… (log#0, 2026-02-20 06:30:12)
Status:     VERIFIED -- file matches on-chain record
Proof:      inclusion proof valid (tree_size=3, path_len=2)

After modifying the file:

Status:     MODIFIED -- file changed since last on-chain record

6. Check status

cargo run -- status

Actor:          watchdog
Status:         active
Energy:              999955
Events:         3 submitted (of 5 total in kernel)
Last activity:  2026-02-20 06:32:18
Watched files:  3 unique paths tracked

7. Export provenance package

cargo run -- export --output proof.json

Generates a self-contained JSON proof package with all events and Merkle inclusion proofs:

[export] exporting 3 events with proofs...
Exported 3 events to proof.json
File size: 2048 bytes

8. Stop

Press Ctrl+C in the watchdog terminal:

[watchdog] shutting down...
[watchdog] total events submitted: 42

Pending events are flushed before exit.

---

Command Reference

punkgo-watchdog watch <dir> [options]     Watch directory for file changes
punkgo-watchdog history [--limit <n>]     List change records from kernel
punkgo-watchdog verify <file>             Verify file integrity against on-chain record
punkgo-watchdog status                    Actor state overview
punkgo-watchdog export [--output <f>]     Export provenance package with Merkle proofs
punkgo-watchdog help                      Show help

Global Options

Option	Default	Description
--endpoint <pipe>	\\.\pipe\punkgo-kernel (Win) / state/punkgo.sock (Unix)	IPC endpoint
--actor-id <id>	watchdog	Actor ID for submissions

watch Options

Option	Default	Description
--debounce <ms>	500	Debounce delay in milliseconds

history Options

Option	Default	Description
--limit <n> / -n <n>	50	Show last N records

export Options

Option	Default	Description
--output <file> / -o <file>	punkgo-provenance.json	Output file path

---

.punkgoignore

Create a .punkgoignore file in the watched directory (gitignore-style syntax):

# Build artifacts
dist/
build/

# Temporary files
*.tmp
*.swp
*.log

# IDE
.idea/
.vscode/

Built-in ignores (always active): .git/, target/, node_modules/, .punkgoignore

---

Data Model

Submission Format

Each file change is submitted to the kernel as a mutate action:

• target: workspace/watchdog/<relative-path> (e.g. workspace/watchdog/src/main.rs)
• payload:

{
  "event": "modify",
  "path": "src/main.rs",
  "sha256": "e3b0c44298fc1c14...",
  "size": 1234
}

Field	Description
event	create / modify / delete
path	Path relative to watched directory (forward slashes)
sha256	SHA-256 hash of file contents (null on delete)
size	File size in bytes (null on delete)

Kernel Storage

The kernel's EventRecord stores the full target and payload (similar to Ethereum storing complete calldata). Watchdog maintains no local cache — all data is queried from the kernel on demand.

This means:

• history pulls events from the kernel and parses file info from payload
• verify pulls the latest matching event and compares the current file's SHA-256
• export pulls all events and requests a Merkle inclusion proof for each

Provenance Package Format

The export command generates a self-contained JSON proof package:

{
  "version": "1.0",
  "actor_id": "watchdog",
  "exported_at": "1740045600000",
  "checkpoint": { "..." },
  "total_events": 3,
  "events": [
    {
      "log_index": 0,
      "event_hash": "a1b2c3...",
      "timestamp": "1740045600000",
      "file": {
        "path": "src/main.rs",
        "event": "create",
        "sha256": "e3b0c4...",
        "size": 1234
      },
      "proof": {
        "tree_size": 3,
        "inclusion_path": ["hash1", "hash2"]
      }
    }
  ]
}

Anyone with this JSON and the kernel's checkpoint public key can independently verify the existence and integrity of every record.

---

Architecture

File system changes
    | notify (cross-platform: FSEvents / inotify / ReadDirectoryChangesW)
    v
punkgo-watchdog (debounce 500ms)
    | IPC (line-delimited JSON over named pipe / unix socket)
    v
punkgo-kerneld (7-step submit pipeline)
    |
    v
SQLite (totally-ordered event log + Merkle tree + energy ledger)

Watchdog is a lightweight kernel client — it does not modify kernel code, communicates only through the IPC protocol, and maintains no local state.

Source Layout

src/
├── main.rs        Entry point + CLI argument parsing (5 subcommands)
├── ipc.rs         IPC client (submit / read / health check)
├── watcher.rs     watch command (file monitoring + debounce + submission)
├── ignore.rs      .punkgoignore rule loading and matching
├── time.rs        Shared timestamp formatting utilities
├── history.rs     history subcommand
├── verify.rs      verify subcommand
├── status.rs      status subcommand
└── export.rs      export subcommand

---

Cross-Platform Support

Platform	File Watching	IPC
Windows	ReadDirectoryChangesW	Named Pipe (\\.\pipe\punkgo-kernel)
macOS	FSEvents	Unix Socket (state/punkgo.sock)
Linux	inotify	Unix Socket (state/punkgo.sock)

Platform selection is automatic via #[cfg(windows)] / #[cfg(unix)] at compile time.

---

Testing

cargo test

61 unit tests covering:

• File event classification (classify)
• SHA-256 hashing (hash_file)
• Path mapping (make_target)
• Payload construction (build_payload — including delete, empty file, and vanished-file edge cases)
• .punkgoignore rule loading and matching (built-in + custom rules)
• Timestamp formatting (format_timestamp / days_to_date / is_leap)
• Directory resolution (resolve_dir)

All tests run without a kernel daemon.

---

Using with punkgo-cli

All watchdog data lives in the kernel. You can also query it directly with punkgo-cli:

# List events submitted by watchdog
punkgo-cli read events --actor-id watchdog

# List all events
punkgo-cli read events

# Verify a record's inclusion proof
punkgo-cli audit proof <log-index>

# Check watchdog actor's energy balance
punkgo-cli read actor_energy --actor-id watchdog

# View kernel statistics
punkgo-cli read stats

---

License

MIT