---

purpose: State backend specifications for persisting OpenProse execution state across sessions — filesystem, in-context, SQLite, and PostgreSQL related:

• ../SKILL.md
• ../prose.md
• ../forme.md
• ../primitives/README.md
• ../guidance/README.md glossary: State Backend: A persistence layer the VM uses to store the append-only receipt ledger and the canonical per-node world-model across sessions Canonical World-Model: The single content-addressable artifact (a directory by default) holding a node's maintained truth; deterministically serialized and fingerprinted on commit; the source of record Derived Projection: A SQL/vector/dashboard index built FROM the canonical world-model for query; rebuildable, never the truth

---

state

Specifications for the state backends available to OpenProse systems. Each backend trades off latency, durability, and query power.

Load this file before every prose run, then load exactly one backend spec. The filesystem backend is the default and the normative reference for source and run layout.

All durable backend paths are relative to <openprose-root>. Native repositories use the repository root, attached repositories use repo/.agents/prose, and user-global work uses ~/.agents/prose.

Backend Selection

Situation	Backend Spec	Notes
No explicit backend	filesystem.md	Default durable backend
User/source/host requests in-context state	in-context.md	Ephemeral; no durable run directory guarantee
User/source/host requests SQLite	sqlite.md	Durable local database; requires sqlite3
User/source/host requests PostgreSQL	postgres.md	Durable networked database; requires configured PostgreSQL

The truth is canonical; everything else is a projection

The load-bearing invariant for every backend: the canonical world-model is a single content-addressable artifact — by default a directory of files — that is deterministically serialized and fingerprinted on commit. SQLite tables, PostgreSQL rows, vector indices, and dashboards are derived projections of that canonical truth, never the truth itself. A render may query a projection by reference (e.g. a SQL index over a million-row truth), but the canonical artifact remains the source of record, and the fingerprint is always computed over the canonical serialization — never over a projection.

A backend is therefore two layers:

1. Canonical store — holds the per-node world-model artifact, produces a deterministic canonical serialization (stable file ordering, path/encoding normalization), and content-addresses each committed version. This is what gets fingerprinted.
2. Derived projections (optional) — query/retrieval indices the backend maintains from the canonical truth for fast lookup. Rebuildable at any time from the canonical artifact; never canonical themselves.

Durable Run Envelope

Durable backends create one receipt directory under <openprose-root>/runs/{id}/. Before reporting success, every durable backend writes:

• compiled intent: the topology world-model (nodes/edges/wake-sources) + per-node canonicalizers + postcondition validators, or a minimal function activation record for single-call runs
• root.prose.md: snapshot of the invoked source
• sources/: snapshots of referenced source files

Backend-specific storage begins after that envelope:

Backend	Ledger (receipts)	Canonical world-model	Derived projections
Filesystem	vm.log.md + receipts/	world-model/{node}/ directory (deterministically serialized, content-addressed)	none by default; an optional index is rebuildable
SQLite	state.db receipt-ledger tables	canonical artifact blobs keyed by ContentAddress, with version chain	SQL tables for query (a projection, not the truth)
PostgreSQL	PostgreSQL receipt-ledger tables	canonical artifact objects keyed by ContentAddress, with version chain	SQL rows + optional vector index for query (projections, not the truth)

Persistent alternate backends still use the same <openprose-root>, *.prose.md source conventions, run IDs, compiled intent, root.prose.md, source snapshots, and state/ durable cross-run namespace; they keep the append-only receipt ledger and the canonical world-model versioning, and add their SQL/vector indices as derived projections. In-context state keeps the same conventions but holds the canonical world-model and ledger in conversation history — still canonical, just ephemeral.

Contents

• filesystem.md — file-based state; the normative reference for the canonical world-model artifact layout, deterministic serialization, and the receipt ledger
• in-context.md — ephemeral state held in the LLM context window; canonical world-model + ledger live in conversation history, lost when the session ends
• sqlite.md — SQLite-backed persistence; receipt ledger + content-addressed world-model versioning, with SQL as a derived query projection
• postgres.md — PostgreSQL-backed persistence; the same ledger + world-model versioning for multi-agent and multi-host systems, with SQL/vector projections for query