Why We Rebuilt
Last Updated: April 2026 Scope: Release-companion explainer for the world-model rebuild (INK-839 and the epics underneath it).
This page is the plain-language version of the rebuild story for readers who come in at the release boundary and want to know what changed and why. It is deliberately narrative; the normative documents are the Codex world-model surface and the ADRs at docs/ADR/. Read this page to orient; read those to work.
The short version
Three things changed together:
- The agent runtime moved out of Rust. The Rust agent harness is gone. The runtime is now a LangGraph sidecar in Python, reached through MCP. The Rust core owns the domain and the workspace database; it no longer owns the agent loop.
- The skill system lost its compilation pipeline. DSPy is gone. Skills are workspace-scoped portable packages; a runtime subagent (the Skill Composer) turns a skill package plus a request into a prompt and a subgraph shape on each invocation.
- The world model became explicit. Origin, lifecycle, derivation, deviation, retroactive revision, and the submit boundary are first-class primitives with dedicated pages, decisions, and ADRs. The product was always trying to be a world-model tool; now the architecture names it as one.
Everything else — the sidecar security posture, the four-tier memory, the capability model extension to the World Agent — follows from those three moves.
Why the runtime moved out of Rust
The agent harness started as a Rust-native loop. The bet was that keeping the runtime in-process with the domain would simplify coordination — the agent would dispatch tools the same way the Tauri command layer did, and every capability check would happen in one language.
That bet held for the first pass. It stopped holding once the ecosystem around LLM agent graphs matured in Python. The constraints that pushed the rewrite:
- Graph frameworks are Python-native. LangGraph, the nearest-fit substrate, does not have a Rust equivalent at parity. Rebuilding graph primitives in Rust was possible; it was not a good use of the team.
- Provider SDKs are Python-first. The LLM provider surface moves quickly. Waiting for Rig’s integrations to catch up with each new provider feature was a regular blocker.
- DSPy lost the argument. The compilation pipeline assumed we wanted compiled, traced modules. Once the Skill Composer subagent shape landed, runtime composition was strictly better for our case — it kept skills portable, kept prompts legible, and removed an entire build step.
The ADR for the move is ADR-016: World Runtime on LangGraph; it carries the record of the retired Rust harness.
What stayed in Rust: the domain, the submit boundary, the SQLite-backed workspace, the MCP server hosting tools, the capability system, the sync engine, the event log, the task runner. Everything that is about the world or the workspace lives on the Rust side. Everything that is about driving an LLM graph lives in the Python sidecar. The only shim between them is the MCP surface and the tool registration metadata — a narrow IPC by design.
Why DSPy and the skill-compilation pipeline left
The original skill system used DSPy to compile skill templates into executable modules, with a registry of pre-compiled
artifacts persisted in a separate agents.db and a skill_artifacts table. Three things made that model wrong for us
over time:
- Skills are not trained modules. They are bundles of prompt, tool orchestration, and supporting resources that the worldbuilder or a third-party author composes and ships. Compiling them obscured what was inside and made them less portable.
- The pre-compiled artifact was a caching concern dressed as a core mechanism. If a runtime composition step is cheap enough (and it is, because the skill package is already structured), caching adds complexity without commensurate benefit.
- Sandbox hardening was a separate problem. ADR-021 separates the sandbox from the agent runtime entirely. The sandbox is now a capability — a Wasmtime-hosted CPython executor reached through MCP — not a runtime layer.
DSPy itself was not the problem — only its use as a skill compiler. It returns in v0.4.0 in a different role: the LLM programming layer inside the agent runtime, where DSPy Signatures replace hand-written prompt strings. See ADR-022: DSPy as the LLM Programming Layer.
The new skill subsystem lives in three Codex pages:
- Skill System — what a skill is and where it sits.
- Skill Composer — the runtime-composition subagent.
- Skill Storage — entity shape, schema, permissions, sync.
Skills are explicitly workspace-scoped, not world content (decision D31). They do not get provenance treatment; they are portable tools.
Why the world model became explicit
The earlier product docs described Inklings as a PKM tool with agent assistance. That framing was accurate on the surface and wrong in the center. What we were actually building — what the invariants, the write path, the candidate-content treatment, and the agent’s role all kept pointing at — was a world-model tool. The rebuild names it.
The primitives now have dedicated canonical pages under systems/world/:
- Three zones — private, candidate, canonical — describe the epistemic layering of the world.
- Two stored provenance axes (origin, lifecycle) plus two derived signals (weight, standing) describe where content came from and how settled it is.
- Derivation links and deviation records are stored relations and record-type entities that capture the connective tissue and the conflicts.
- Retroactive revision is the flag-and-review mechanism for pulling older canonical content back under scrutiny.
- The submit boundary is the single domain invariant every write routes through. It is not a layer; it is the invariant that makes the above primitives coherent.
The ADRs covering this surface are ADR-017 through ADR-021.
The World Agent is a participant inside this world, not a service attached to it. It has the same capability-scoped surfaces the worldbuilder has, reached through MCP. One workspace is one world is one agent.
What retired
A short list so readers hitting a stale reference know where it went:
| Retired concept | Replaced by | Canonical reference |
|---|---|---|
| Rust agent harness | LangGraph sidecar runtime | agent-core-system, ADR-016 |
| DSPy skill compilation pipeline | Runtime composition via Skill Composer subagent | skill-system, skill-composer |
agents.db as separate file | Consolidated into workspace inklings.db | database-schema |
skill_artifacts table | Skill packages; no pre-compiled artifact | skill-storage |
AGENTS.md durable-context file | Four-tier agent memory via MCP tools | agent-memory-system |
| VFS / FUSE projection | SQLite is the sole source of truth | ADR-013 |
| Hub-and-spoke agent coordination | LangGraph subgraph dispatch | agent-core-system |
| PKM / note-taking framing | World-model framing | systems/world/index, getting-started |
What it was not
A few things this rebuild was deliberately not:
- Not a data migration. ADR-020 makes the rebuild a single cutover. No workspace upgrader ships with this release. Existing dev workspaces should be reset.
- Not a drop-in port of another project’s patterns. We borrowed concepts and reshaped them for our domain. Attribution to upstream frameworks is limited to the ones we actually import (LangGraph, Wasmtime, DSPy-as-retired).
- Not a UI overhaul. The editor, the page surface, the sidebar, the command palette — all the same. The change is underneath.
- Not a marketing repositioning. Product positioning is handled on the marketing surface (epic E13). The Codex and this page describe the technical shape.
Where to read next
- Getting Started — the orientation page for both worldbuilders reading the Codex and contributors setting up the codebase.
- systems/world/index — the canonical entry point for the world-model surface.
- systems/world/worked-example — the fiction-author magic-system walkthrough that touches every primitive.
- Voice Guide — the naming and cross-link conventions the Codex follows, including why we call the agent the World Agent.
- ADR Index — the full index of architecture decisions, including status markers for the ones this rebuild superseded.
Was this page helpful?
Thanks for your feedback!