feat(sdk): complete Task 8 — capability mocks, local simulator, checkpoint inspector (#5)

Implement the three remaining Task 8 deliverables:

- Capability mocks (sdk/igor/mock/): pluggable MockBackend for native
  testing without WASM, deterministic clock/rand, log capture. Split
  hostcall wrappers into build-tagged files (WASM vs native).
- Local simulator (internal/simulator/): single-process WASM runner with
  deterministic hostcalls, per-tick replay verification, checkpoint
  round-trip verification. CLI flags: --simulate, --ticks, --verify,
  --deterministic, --seed.
- Checkpoint inspector (internal/inspector/): parse and display checkpoint
  files with hex dump, WASM hash verification. CLI flags:
  --inspect-checkpoint, --inspect-wasm.

Update docs: ROADMAP.md, IMPLEMENTATION_STATUS.md, README.md to reflect
Task 8 completion.

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: simonovic86

README.md

@@ -9,7 +9,7 @@ Igor is a decentralized execution runtime for autonomous software agents. It pro
 ## About This Repository
 
 **What:** Experimental infrastructure for autonomous agent survival  
-**Status:** Research-stage — Phase 3 (Autonomy) in progress. Capability membrane MVP complete, replay verification operational, agent SDK landed.
+**Status:** Research-stage — Phase 3 (Autonomy) in progress. Capability membrane, replay verification, agent SDK, capability mocks, local simulator, and checkpoint inspector complete. Multi-node mobility testing next.
 **Purpose:** Demonstrate that software can checkpoint, migrate, and self-fund execution
 
 **Read first:**

cmd/igord/main.go

@@ -13,11 +13,13 @@ import (
 
 	"github.com/simonovic86/igor/internal/agent"
 	"github.com/simonovic86/igor/internal/config"
+	"github.com/simonovic86/igor/internal/inspector"
 	"github.com/simonovic86/igor/internal/logging"
 	"github.com/simonovic86/igor/internal/migration"
 	"github.com/simonovic86/igor/internal/p2p"
 	"github.com/simonovic86/igor/internal/replay"
 	"github.com/simonovic86/igor/internal/runtime"
+	"github.com/simonovic86/igor/internal/simulator"
 	"github.com/simonovic86/igor/internal/storage"
 	"github.com/simonovic86/igor/pkg/budget"
 )
@@ -34,8 +36,27 @@ func main() {
 	verifyInterval := flag.Int("verify-interval", 0, "Ticks between self-verification passes (0 = use config default)")
 	replayMode := flag.String("replay-mode", "", "Replay verification mode: off, periodic, on-migrate, full (default: full)")
 	replayCostLog := flag.Bool("replay-cost-log", false, "Log replay compute duration for economic observability")
+	inspectCheckpoint := flag.String("inspect-checkpoint", "", "Path to checkpoint file to inspect")
+	inspectWASM := flag.String("inspect-wasm", "", "Optional WASM binary to verify against checkpoint hash")
+	simulate := flag.Bool("simulate", false, "Run agent in local simulator mode (no P2P)")
+	simTicks := flag.Int("ticks", 0, "Number of ticks to simulate (0 = until budget exhausted)")
+	simVerify := flag.Bool("verify", false, "Per-tick replay verification during simulation")
+	simDeterministic := flag.Bool("deterministic", false, "Use fixed clock and seeded rand for reproducible simulation")
+	simSeed := flag.Uint64("seed", 0, "Random seed for deterministic simulation")
 	flag.Parse()
 
+	// Checkpoint inspector — standalone, no config/P2P/engine needed
+	if *inspectCheckpoint != "" {
+		runInspector(*inspectCheckpoint, *inspectWASM)
+		return
+	}
+
+	// Local simulator — standalone, no config/P2P needed
+	if *simulate && *runAgent != "" {
+		runSimulator(*runAgent, *manifestPath, *budgetFlag, *simTicks, *simVerify, *simDeterministic, *simSeed)
+		return
+	}
+
 	// Create context
 	ctx, cancel := context.WithCancel(context.Background())
 	defer cancel()
@@ -354,3 +375,44 @@ func verifyNextTick(
 	}
 	return lastVerified
 }
+
+// runInspector parses and displays a checkpoint file.
+func runInspector(checkpointPath, wasmPath string) {
+	result, err := inspector.InspectFile(checkpointPath)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "Error: %v\n", err)
+		os.Exit(1)
+	}
+	if wasmPath != "" {
+		if verr := result.VerifyWASM(wasmPath); verr != nil {
+			fmt.Fprintf(os.Stderr, "Warning: %v\n", verr)
+		}
+	}
+	result.Print(os.Stdout)
+}
+
+// runSimulator executes an agent in local simulator mode (no P2P).
+func runSimulator(wasmPath, manifestPath string, budgetVal float64, ticks int, verify, deterministic bool, seed uint64) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	logger := logging.NewLogger()
+	cfg := simulator.Config{
+		WASMPath:      wasmPath,
+		ManifestPath:  manifestPath,
+		Budget:        budgetVal,
+		Ticks:         ticks,
+		Verify:        verify,
+		Deterministic: deterministic,
+		RandSeed:      seed,
+	}
+	result, err := simulator.Run(ctx, cfg, logger)
+	if err != nil {
+		logging.Error(logger, "Simulation failed", "error", err)
+		os.Exit(1)
+	}
+	simulator.PrintSummary(result, logger)
+	if len(result.Errors) > 0 {
+		os.Exit(1)
+	}
+}

docs/IMPLEMENTATION_STATUS.md

@@ -68,7 +68,7 @@ Last updated: 2026-03-03
 | Observation recording (CM-4) | Implemented | `internal/eventlog/eventlog.go` |
 | Manifest in migration package | Implemented | `pkg/protocol/messages.go` `ManifestData` |
 | Pre-migration capability check (CE-5) | Implemented | `internal/migration/service.go` `handleIncomingMigration` |
-| KV storage hostcalls | Not implemented | Roadmap Task 8+ |
+| KV storage hostcalls | Not implemented | Roadmap future task |
 | Network hostcalls | Not implemented | Roadmap Phase 3+ |
 
 ## Identity and Authority
@@ -95,3 +95,20 @@ Last updated: 2026-03-03
 | /tmp WASM write on target | Removed | Replaced by `agent.LoadAgentFromBytes` (no temp file) |
 | Replay data in migration package | Implemented | `internal/migration/replay.go` |
 | Staleness guard for replay data | Implemented | `internal/migration/replay.go` |
+
+## Agent SDK & Developer Experience
+
+| Aspect | Status | Code Reference |
+|--------|--------|----------------|
+| Agent SDK (Agent interface, hostcall wrappers) | Implemented | `sdk/igor/lifecycle.go`, `sdk/igor/hostcalls_wrappers_wasm.go` |
+| Build-tag split (WASM vs native) | Implemented | `sdk/igor/hostcalls_wrappers_wasm.go`, `sdk/igor/hostcalls_wrappers_stub.go` |
+| Capability mocks (MockBackend, Runtime) | Implemented | `sdk/igor/mock_backend.go`, `sdk/igor/mock/mock.go` |
+| Deterministic mock (fixed clock, seeded rand) | Implemented | `sdk/igor/mock/mock.go` `NewDeterministic` |
+| Local simulator (single-process WASM runner) | Implemented | `internal/simulator/simulator.go` |
+| Simulator deterministic hostcalls | Implemented | `internal/simulator/hostcalls.go` |
+| Simulator replay verification | Implemented | `internal/simulator/simulator.go` `verifyTick` |
+| Checkpoint inspector | Implemented | `internal/inspector/inspector.go` |
+| WASM hash verification in inspector | Implemented | `internal/inspector/inspector.go` `VerifyWASM` |
+| Agent template (Survivor example) | Implemented | `agents/example/` |
+| `--simulate` CLI flag | Implemented | `cmd/igord/main.go` |
+| `--inspect-checkpoint` CLI flag | Implemented | `cmd/igord/main.go` |

docs/governance/ROADMAP.md

@@ -13,9 +13,11 @@ Igor v0 has completed **Phase 2 (Survival)** and begun **Phase 3 (Autonomy)**.
 - ✅ **Task 4** - Migration protocol over libp2p
 - ✅ **Task 5** - Rent metering & runtime accounting
 - ✅ **Task 6** - Capability membrane MVP (clock/rand/log hostcalls, manifest, event log, deny-by-default)
+- ✅ **Task 7** - Replay engine (single-tick verification, configurable modes, sliding window)
+- ✅ **Task 8** - Agent SDK & developer experience (SDK, mocks, simulator, inspector, template)
 
 **Phase 2 result:** Agents can survive, migrate, and pay for execution.
-**Phase 3 progress:** Agents interact through runtime-mediated hostcalls with observation recording.
+**Phase 3 progress:** Capability membrane, replay verification, and developer tooling complete. Multi-node mobility testing next.
 
 ---
 
@@ -60,18 +62,19 @@ Igor v0 has completed **Phase 2 (Survival)** and begun **Phase 3 (Autonomy)**.
 
 **Specs:** [REPLAY_ENGINE.md](../runtime/REPLAY_ENGINE.md)
 
-### Task 8: Agent SDK & Developer Experience
+### Task 8: Agent SDK & Developer Experience ✅
 
-**Objective:** Make agent authoring accessible with SDK and tooling.
+**Status:** Complete. Agent SDK, developer tooling, and testing infrastructure fully implemented.
 
-**Scope:**
-- Agent SDK (Go/TinyGo first) wrapping hostcall interface
-- Local simulator (single-process deterministic replay)
-- Capability mocks for testing
-- Agent template / starter project
-- Checkpoint inspector
+**Delivered:**
+- Agent SDK (`sdk/igor/`): `Agent` interface (Init, Tick, Marshal, Unmarshal), hostcall wrappers (ClockNow, RandBytes, Log, Logf), build-tag split for WASM and native builds
+- Capability mocks (`sdk/igor/mock/`): pluggable `MockBackend` for native testing without WASM, deterministic clock/rand, log capture
+- Local simulator (`internal/simulator/`): single-process WASM runner with deterministic hostcalls, per-tick replay verification, checkpoint round-trip verification
+- Checkpoint inspector (`internal/inspector/`): parse and display checkpoint files, WASM hash verification
+- Agent template (`agents/example/`): Survivor agent demonstrating SDK usage, hostcall patterns, and state serialization
+- CLI flags: `--simulate`, `--ticks`, `--verify`, `--deterministic`, `--seed`, `--inspect-checkpoint`, `--inspect-wasm`
 
-**Outcome:** Developers can build agents without manually managing WASM exports, memory, and hostcall signatures.
+**Outcome:** Developers can build agents without manually managing WASM exports, memory, and hostcall signatures. Agents can be tested natively with mocks or as compiled WASM in the simulator.
 
 ### Task 9: Multi-Node Mobility Testing
 
@@ -323,7 +326,7 @@ Igor development follows "done when it's done" philosophy:
 - Correctness over features
 - Learning over shipping
 
-Phase 3 began after Phase 2 validation. Task 6 is complete.
+Phase 3 began after Phase 2 validation. Tasks 6, 7, and 8 are complete.
 
 ---
 
@@ -434,9 +437,8 @@ Phase 2 is **validated** when:
 
 ## Next Immediate Steps
 
-With Phase 3 Tasks 6 (Capability Membrane) and 7 (Replay Engine) complete:
+With Phase 3 Tasks 6 (Capability Membrane), 7 (Replay Engine), and 8 (Agent SDK) complete:
 
-1. **Task 8: Agent SDK** - Hostcall wrappers, lifecycle helpers, developer experience
-2. **Task 9: Multi-Node Mobility Testing** - Chain migration, capability preservation
-3. **Hardening** - Bug fixes, test coverage, documentation accuracy
-4. **Extended testing** - Run agents with hostcalls for hours/days
+1. **Task 9: Multi-Node Mobility Testing** - Chain migration A → B → C → A, capability preservation, budget conservation
+2. **Hardening** - Bug fixes, test coverage, documentation accuracy
+3. **Extended testing** - Run agents with hostcalls for hours/days under load

internal/inspector/inspector.go

@@ -0,0 +1,152 @@
+// Package inspector provides checkpoint file parsing and display.
+package inspector
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"fmt"
+	"io"
+	"os"
+
+	"github.com/simonovic86/igor/internal/agent"
+	"github.com/simonovic86/igor/pkg/budget"
+)
+
+// Result holds parsed checkpoint information.
+type Result struct {
+	Version         byte
+	Budget          int64
+	BudgetFormatted string
+	PricePerSecond  int64
+	PriceFormatted  string
+	TickNumber      uint64
+	WASMHash        [32]byte
+	WASMHashHex     string
+	StateSize       int
+	State           []byte
+	TotalSize       int
+	WASMVerified    *bool
+	WASMPath        string
+}
+
+// InspectFile parses a checkpoint file and returns structured results.
+func InspectFile(path string) (*Result, error) {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return nil, fmt.Errorf("read checkpoint: %w", err)
+	}
+	return Inspect(data)
+}
+
+// Inspect parses raw checkpoint bytes.
+func Inspect(data []byte) (*Result, error) {
+	budgetVal, price, tick, wasmHash, state, err := agent.ParseCheckpointHeader(data)
+	if err != nil {
+		return nil, fmt.Errorf("parse checkpoint: %w", err)
+	}
+
+	return &Result{
+		Version:         data[0],
+		Budget:          budgetVal,
+		BudgetFormatted: budget.Format(budgetVal),
+		PricePerSecond:  price,
+		PriceFormatted:  budget.Format(price),
+		TickNumber:      tick,
+		WASMHash:        wasmHash,
+		WASMHashHex:     hex.EncodeToString(wasmHash[:]),
+		StateSize:       len(state),
+		State:           state,
+		TotalSize:       len(data),
+	}, nil
+}
+
+// VerifyWASM checks if a WASM binary matches the checkpoint's stored hash.
+func (r *Result) VerifyWASM(wasmPath string) error {
+	wasmBytes, err := os.ReadFile(wasmPath)
+	if err != nil {
+		return fmt.Errorf("read WASM: %w", err)
+	}
+	hash := sha256.Sum256(wasmBytes)
+	verified := hash == r.WASMHash
+	r.WASMVerified = &verified
+	r.WASMPath = wasmPath
+	if !verified {
+		return fmt.Errorf("WASM hash mismatch: checkpoint=%s binary=%s",
+			r.WASMHashHex, hex.EncodeToString(hash[:]))
+	}
+	return nil
+}
+
+// Print writes a human-readable inspection report.
+func (r *Result) Print(w io.Writer) {
+	fmt.Fprintf(w, "Checkpoint Inspector\n")
+	fmt.Fprintf(w, "====================\n\n")
+	fmt.Fprintf(w, "Version:          %d (0x%02x)\n", r.Version, r.Version)
+	fmt.Fprintf(w, "Budget:           %s (%d microcents)\n", r.BudgetFormatted, r.Budget)
+	fmt.Fprintf(w, "Price/Second:     %s (%d microcents)\n", r.PriceFormatted, r.PricePerSecond)
+	fmt.Fprintf(w, "Tick Number:      %d\n", r.TickNumber)
+	fmt.Fprintf(w, "WASM Hash:        %s\n", r.WASMHashHex)
+	fmt.Fprintf(w, "Total Size:       %d bytes\n", r.TotalSize)
+	fmt.Fprintf(w, "Header Size:      57 bytes\n")
+	fmt.Fprintf(w, "State Size:       %d bytes\n", r.StateSize)
+
+	if r.WASMVerified != nil {
+		if *r.WASMVerified {
+			fmt.Fprintf(w, "WASM Verified:    YES (matches %s)\n", r.WASMPath)
+		} else {
+			fmt.Fprintf(w, "WASM Verified:    NO (mismatch with %s)\n", r.WASMPath)
+		}
+	}
+
+	if r.StateSize > 0 {
+		fmt.Fprintf(w, "\nState Hex Dump:\n")
+		limit := r.StateSize
+		if limit > 256 {
+			limit = 256
+		}
+		printHexDump(w, r.State[:limit])
+		if r.StateSize > 256 {
+			fmt.Fprintf(w, "  ... (%d more bytes)\n", r.StateSize-256)
+		}
+	}
+}
+
+// printHexDump writes a canonical hex dump (16 bytes per line).
+func printHexDump(w io.Writer, data []byte) {
+	for i := 0; i < len(data); i += 16 {
+		end := i + 16
+		if end > len(data) {
+			end = len(data)
+		}
+		row := data[i:end]
+
+		// Offset
+		fmt.Fprintf(w, "  %08x  ", i)
+
+		// Hex bytes
+		for j, b := range row {
+			fmt.Fprintf(w, "%02x ", b)
+			if j == 7 {
+				fmt.Fprint(w, " ")
+			}
+		}
+		// Pad remaining
+		for j := len(row); j < 16; j++ {
+			fmt.Fprint(w, "   ")
+			if j == 7 {
+				fmt.Fprint(w, " ")
+			}
+		}
+
+		// ASCII
+		fmt.Fprint(w, " |")
+		for _, b := range row {
+			if b >= 0x20 && b <= 0x7e {
+				fmt.Fprintf(w, "%c", b)
+			} else {
+				fmt.Fprint(w, ".")
+			}
+		}
+		fmt.Fprintln(w, "|")
+	}
+}