Skip to content

docs: add Phase 2.5 (Protocol Foundation) roadmap and strategic reframe #32

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
simonovic86 merged 2 commits into from
Mar 27, 2026
Merged

docs: add Phase 2.5 (Protocol Foundation) roadmap and strategic reframe #32

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ac40d30
docs: add Phase 2.5 (Protocol Foundation) roadmap and strategic reframe
simonovic86 Mar 27, 2026
b6aa4b7
docs: fix Phase 2 status and lab binary name in roadmap
simonovic86 Mar 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions docs/IMPLEMENTATION_STATUS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -220,3 +220,15 @@ Last updated: 2026-03-15
| `LoadSidecarData` tests | Added | `pkg/manifest/parse_test.go` — explicit path, derived path, no file, non-WASM |
| CI: TinyGo before tests | Fixed | `.github/workflows/ci.yml` — WASM integration tests now run in CI |
| CI: test coverage reporting | Added | `.github/workflows/ci.yml` — `go test -coverprofile` + summary |

## Known Issues / Tech Debt

Discovered during project review (2026-03-27). None are blockers for current functionality; all should be addressed during Phase 2.5 or as standalone fixes.

| Issue | Severity | Location | Description |
|-------|----------|----------|-------------|
| Budget can go negative (RE-3 violation) | Medium | `internal/agent/instance.go` `Tick()` | Tick cost deduction `i.Budget -= costMicrocents` does not clamp to zero. A long tick can create budget debt before the next pre-tick check catches it. Fix: clamp `costMicrocents` to remaining budget before deduction. |
| `ParseCheckpointHeader` layering violation | Low | `internal/agent/instance.go` | Checkpoint header parsing (~80 lines of `encoding/binary`) lives in the agent package alongside WASM compilation and tick execution. Should be extracted to `pkg/checkpoint` so standalone tools (`igor-verify`) can parse headers without importing the full runtime. Phase 2.5 prerequisite. |
| Stringly-typed retry classification | Low | `internal/migration/retry.go` | Fatal error detection uses `strings.Contains` on error messages. If anyone rewords an error message, retry/fatal/ambiguous classification silently changes. Should use sentinel errors or typed error values. |
| Unchecked lease type assertion | Low | `internal/runner/research/research.go` | `instance.Lease.(*authority.Lease)` uses blank identifier for ok value. Wrong interface type silently produces nil, triggering "lease disabled" behavior instead of surfacing the mismatch. |
| Stale timeout comments | Low | Multiple files | Comments reference old 100ms tick timeout. Actual timeout is 15s (`internal/config/config.go` `TickTimeout`), changed to accommodate HTTP hostcalls. |
70 changes: 57 additions & 13 deletions docs/governance/ROADMAP.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
# Igor Roadmap

## Current Status: Product Phase 1 Complete
## Current Status: Product Phase 2.5 Next

Igor has completed its research foundation (**Phases 2–5**) and pivoted to product development. The runtime now supports **portable, infrastructure-independent agents** with DID identity, cryptographic lineage verification, and clean CLI workflows (`igord run`, `resume`, `verify`).
Igor has completed its research foundation (**Phases 2–5**) and product phases 1–2. The runtime supports **portable, infrastructure-independent agents** with DID identity, cryptographic lineage verification, effect-safe side effects, HTTP/payment hostcalls, and clean CLI workflows (`igord run`, `resume`, `verify`).

**Product Phase 1 (Portable Sovereign Agent)** is complete. **Product Phase 2 (Agent Self-Provisioning)** is next.
**Product Phase 1 (Portable Sovereign Agent)** and **Phase 2 (Agent Self-Provisioning)** feature work are complete. **Product Phase 2.5 (Protocol Foundation)** is next — making the checkpoint format, verifier, and effect primitives independently adoptable.
Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector Bot Mar 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Don't mark Phase 2 complete while goals remain open

This change marks Product Phase 2 as complete, but the same roadmap still shows an unfinished Phase 2 goal (Agent decides when to migrate). That contradiction makes planning ambiguous for anyone using this document to prioritize work, because it simultaneously signals "done" and "not done" for the same phase.

Useful? React with 👍 / 👎.


---

Expand Down Expand Up @@ -231,6 +231,31 @@ Igor's research foundation (Phases 2–5) proved that agents can checkpoint, mig

---

## Product Phase 2.5: Protocol Foundation

**Goal:** Make Igor's checkpoint format, verification tools, and effect primitives independently adoptable — before building more runtime features.

**Status:** Not started.

**Strategic context:** Igor is a protocol, not a platform. The competitive moat is agent sovereignty (identity + lineage + portability), not durable execution. Durable execution platforms (Golem, Temporal, Restate) are potential deployment targets for Igor agents, not competitors. Adoption comes bottom-up through verification — publish the spec, ship the verifier, let verification pull developers toward the runtime. The analogy: the checkpoint format spec is JWT (RFC 7519), the standalone verifier is jwt.io, the Igor runtime is Auth0.

**Scope:**
- **Effects library extraction** (`igor.dev/effects`) — extract `sdk/igor/effects.go` + `encoding.go` as standalone Go module with zero Igor-specific dependencies. Blog post: "Crash-safe side effects in 200 lines." Tests bottom-up adoption thesis with minimal risk. (~1 day)
- **Checkpoint format spec** — formal one-page spec in `docs/runtime/CHECKPOINT_FORMAT.md`: byte-level offset table, signing domain construction, chain rule, DID encoding, version dispatch, reserved epoch fields, CID compatibility note. Language-agnostic — enables third-party implementations without reading Go code. (~1-2 days)
- **Standalone verifier** (`igor-verify`) — extract `ParseCheckpointHeader` from `internal/agent/instance.go` into `pkg/checkpoint` (fixes existing layering violation). Build zero-dependency binary: no wazero, no libp2p, no hostcalls (~5MB vs ~30MB). Bundle sample liquidation watcher history for zero-to-verification in 30 seconds. (~1-2 days)
- **Browser WASM verifier** — compile the verify path (`pkg/lineage/`, `pkg/identity/`, `pkg/checkpoint/`) to WASM via `GOOS=js GOARCH=wasm` (pure stdlib, no TinyGo needed). Embeddable in protocol dashboards: "agent lineage: verified, 847 checkpoints, no gaps." (~2-3 days)

**Binary model after this phase:**
- `igor` (renamed from `igord`) — agent operators — run, resume, verify, inspect
- `igor-verify` (new) — anyone verifying lineage — checkpoint parsing + chain verification only
- `igor-lab` (existing, unchanged) — protocol developers — migration, replay, leases, simulator
Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector Bot Mar 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Keep lab binary naming consistent in Phase 2.5 plan

The new binary model lists igor-lab as "existing, unchanged," but the current repo uses igord-lab; this makes the roadmap internally inconsistent and can misdirect users toward a non-existent executable name in scripts or docs. Please clarify whether the lab binary is also being renamed or should remain igord-lab.

Useful? React with 👍 / 👎.


**Design principle:** No configurability, no extension points, no generalization. Five operations and one rule. A fixed offset table. Green or red. "I understand this completely in 5 minutes."

**Outcome:** The checkpoint spec is an adoptable protocol artifact. The standalone verifier is the on-ramp. The effects library generates Go ecosystem mindshare. All three are independently valuable and create the conditions for runtime adoption — without requiring anyone to run a WASM agent first.

---

## Product Phase 3: Permanent Memory

**Goal:** Agents have tamper-evident, publicly verifiable life histories.
Expand Down Expand Up @@ -343,6 +368,14 @@ None. v0 is experimental. Things may be:
- ✅ Agent deploys itself to compute provider (mock)
- Agent decides when to migrate

### Product Phase 2.5 Goals

- Checkpoint format has a formal one-page spec (`docs/runtime/CHECKPOINT_FORMAT.md`)
- Effects library published as standalone Go module (`igor.dev/effects`)
- `igor-verify` binary verifies lineage chains with zero runtime dependencies
- Browser WASM verifier can parse and verify checkpoints
- Binary rename: `igord` → `igor`

---

## Timeline
Expand All @@ -354,7 +387,7 @@ Igor development follows "done when it's done" philosophy:
- Correctness over features
- Learning over shipping

Research phases (2–5) complete. Product Phase 2 in progress.
Research phases (2–5) complete. Product Phase 2 feature work complete. Phase 2.5 (Protocol Foundation) is next.

---

Expand All @@ -373,7 +406,7 @@ Igor v0 is experimental research software.
- Performance optimizations (premature)
- Production deployments (not ready)

Focus: Complete Product Phase 2 before expanding scope.
Focus: Complete Product Phase 2.5 (Protocol Foundation) before expanding scope.

---

Expand All @@ -382,9 +415,10 @@ Focus: Complete Product Phase 2 before expanding scope.
Agents will pick their own infrastructure. Igor makes them portable enough to do so.

- **Now:** Agents are portable digital objects with identity and verifiable history
- **Next:** Agents pay for their own compute and self-provision infrastructure
- **Next:** Checkpoint format spec, standalone verifier, and effects library enable verification-first adoption
- **Then:** Agents pay for their own compute; Golem/Temporal/Restate become deployment targets, not competitors
- **Later:** Agents have permanent, publicly verifiable memory on Arweave
- **Eventually:** A multi-language ecosystem of sovereign, immortal agents
- **Eventually:** A multi-language ecosystem of sovereign agents built on the Igor protocol

---

Expand Down Expand Up @@ -414,22 +448,32 @@ Igor builds on ideas from:

Igor is **not novel**. It combines existing ideas in a specific way to explore autonomous agent survival.

**Competitive positioning:** Golem Cloud, Temporal, and Restate provide durable execution platforms. Igor's differentiator is agent-owned identity, cryptographic lineage, and true portability — the agent is a protocol-level entity, not a platform deployment. These platforms are potential deployment targets for Igor agents, not competitors. Igor answers "who IS the agent?" while they answer "where does the agent run?"

---

## Open Questions

1. **Can agents practically self-provision infrastructure?** (Akash/Golem integration complexity)
2. **Is the checkpoint format efficient enough for large agent state?** (MB+ state sizes)
3. **Will developers adopt the Igor SDK over simpler alternatives?** (DX matters)
1. **Can the checkpoint format spec gain adoption independently of the runtime?** (The JWT analogy test — does verification pull people toward the protocol?)
2. **Is the checkpoint format efficient enough for large agent state?** (MB+ state sizes; content-addressed external storage pointers as escape hatch)
3. **Will DeFi teams adopt igor-verify for agent lineage proofs before the full runtime?** (Bottom-up adoption test)
4. **Is WASM overhead acceptable for latency-sensitive agents?** (not for HFT, but for long-running?)
5. **Can two-tier storage (local + Arweave) work without slowing the critical path?**
6. **What hostcalls do agents actually need?** (HTTP, storage, payments — what else?)
7. **Should Golem/Temporal/Restate be treated as deployment targets rather than competitors?** (Protocol-not-platform thesis)

---

## Next Immediate Steps

Product Phase 2 in progress. HTTP hostcall, effect model, wallet_pay, x402buyer, and deployer demos delivered. Next:
Product Phase 2 feature work complete. Protocol foundation is next — verification-first adoption.

1. **Effects library extraction** — standalone Go module at `igor.dev/effects` (~1 day)
2. **Checkpoint format spec** — formal spec in `docs/runtime/CHECKPOINT_FORMAT.md` (~1-2 days)
3. **Standalone verifier** (`igor-verify`) — zero-dependency lineage verification binary (~1-2 days)
4. **Browser WASM verifier** — checkpoint verification compiled to WASM (~2-3 days)

Then:

1. **Self-migration** — agent decides when and where to move based on price/performance
2. **Real compute provider** — replace mock with Akash or Golem integration
5. **Self-migration** — agent decides when and where to move based on price/performance
6. **Real compute provider** — Akash or Golem as deployment targets (not competitors)
10 changes: 10 additions & 0 deletions docs/philosophy/VISION.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -90,6 +90,16 @@ Igor is an experiment in providing capabilities that autonomous software increas

The development philosophy is minimal and iterative. Igor v0 implements only what is necessary to demonstrate survival and migration. It fails loudly when invariants are violated rather than attempting graceful degradation. It prioritizes correctness over performance, clarity over optimization.

## Igor as Protocol

Igor is a protocol, not a platform. Durable execution platforms — Golem Cloud, Temporal, Restate — answer "where does the agent run?" Igor answers a different question: "who IS the agent?" The competitive moat is agent sovereignty: agent-owned identity (DID), cryptographic lineage (signed checkpoint chain), and true portability (the checkpoint file IS the agent). These platforms are potential deployment targets for Igor agents, not competitors. An Igor agent could run on Golem today, Akash tomorrow, and bare metal next week, with the same DID and unbroken lineage across all three.

The adoption model follows verification, not runtime adoption. Trust primitives spread bottom-up — people verify before they run. The checkpoint format spec is the adoptable artifact (like JWT's RFC 7519). The standalone verifier is the on-ramp (like jwt.io — paste a token, see it decoded). The Igor runtime is one implementation of the protocol (like Auth0 is one implementation of JWT-based auth). Publish the spec, ship the verifier, let verification pull developers toward the runtime.

The initial audience is DeFi. This community already thinks in DIDs, signed proofs, and "don't trust the platform." Provable agent uptime and integrity — "agent lineage: verified, 847 checkpoints, no gaps" — solves a problem DeFi has today and currently addresses with trust-me-bro operator reputation. Agent-owned identity and cryptographic lineage are table stakes in this context, not novel features.

---

Igor exists because the gap between what software can do (execute autonomously) and what software can survive (infrastructure failure) has become untenable for emerging autonomous systems. The technologies needed to solve this have matured to the point where exploration becomes feasible.

Whether autonomous software survival matters in practice can only be answered through building systems that embody these capabilities and observing what emerges.
Loading