Under the hood: the run store
Use this page while debugging Foundry storage. For daily work, start with Run a story or Troubleshooting.
Ownership and recovery
The ledger owns run facts. Projections rebuild views from recorded events. A controller holds a lease and uses a fencing token on writes. A newer lease invalidates stale controller writes. Inspect the code and evidence when lease or integrity errors repeat.
Effects and publication
Effect reservations record an operation before external work occurs. Completion records the result digest. Reusing a completed effect with a different result causes a conflict. Artifact publication compares the expected predecessor digest and records revision lineage.
Profiles and checkpoints
Generation 2 trusts the committed profiles.toml. Older overlays remain hash-pinned to their original baselineRef. The gate verifies testResultDigest against the recorded result. Checkpoint approval must match an emitted request.
Immutable plans and Git references
Resume uses the original plan snapshot. Editing an overlay during execution does not change the sealed plan. Git reference updates use compare-and-set checks so an unexpected branch head causes a refusal.
Integrity boundary
These checks detect inconsistent writes and stale controllers. The store does not resist a local operator who edits the store consistently. Treat operating-system access to Foundry Home as access to the underlying run state.
Internal failures
| Code | Meaning |
|---|---|
LEASE_HELD | Another controller owns the lease. |
FENCED | A newer lease superseded this controller. |
EFFECT_COMPLETION_CONFLICT | One effect received conflicting completion digests. |
SCHEMA_TOO_NEW | This binary does not read the store schema. |
INTEGRITY | An integrity or relationship check failed. |
SQLITE_FLOOR | The runtime’s SQLite version is below the required floor. |
Preserve evidence and use the compatible release when investigating these failures. Operator error codes contains actionable checkout and run fixes.