Repository navigation
Rule persistence: deeper design consideration #241
Description
Background
Rules in Minigraf are session-scoped — they live in memory and are not persisted to the `.graph` file. This means every new REPL session (or agent restart) requires re-defining rules before running queries that use them.
The immediate friction is addressed by the `--init` flag (see related PR). This issue tracks the deeper question: should rules be persisted, and if so, how?
Options on the table
Option 1 — Rules as EAV facts
Store rules as `:minigraf/rule` facts in the `.graph` file. Rules become first-class data: bi-temporally versioned, queryable, loaded automatically on `db.open()`.
Pro: Single-file preserved. Rules are auditable across time. No new file format.
Con: Requires parsing stored strings at open time. Re-runs stratification on every open. Versioning problem: if application code evolves rules, persisted rules may conflict silently.
Option 2 — Sidecar init file (auto-loaded)
`corestore.rules` is auto-loaded alongside `corestore.graph`.
Pro: Clean code/data separation.
Con: Violates single-file philosophy.
Option 3 — Explicit save/load commands
`(save-rules)` / `(load-rules)` called deliberately by the user.
Pro: No implicit magic.
Con: Moves friction rather than eliminating it.
Option 4 — REPL `--init` flag (implemented)
`minigraf --file corestore.graph --init rules.datalog` sources a file before the interactive prompt. No storage-layer changes.
Pro: Best philosophy alignment. Zero implicit behavior. User controls exactly which rules are active. Works for both REPL and scripted agent startup.
Con: Doesn't help library API consumers (only REPL users).
Questions to resolve before committing to a deeper solution
- Should rule persistence be opt-in or automatic?
- How do we handle conflicts between persisted rules and rules defined in the current session?
- Does the library API (`db.execute()`) need a concept of "saved rules"?
- Is the versioning problem (stale persisted rules) acceptable or a blocker?
- Do rules belong in the `.graph` file at all, given that rules are code and facts are data?
Recommendation
Option 4 (`--init` flag) is the right immediate solution. Revisit this issue when there is a concrete use case that `--init` cannot satisfy.
Activity
adityamukho commentedon May 14, 2026
Note on Option 1 (rules as EAV facts) and multi-body rules:
If rules are stored as
:minigraf/rulefacts, the storage unit needs to be the complete definition for a predicate — all alternative bodies together — not individual(rule ...)forms. The current append-per-form model breaks down because there is no way to distinguish "adding the recursive case of an existing rule" from "redefining the rule entirely" without inspecting the session state.This means Option 1 is only cleanly implementable after the v2.0 multi-body syntax (Option A from the design discussion) is in place. A single
(rule ...)form that carries all alternative bodies is a self-contained unit that can be stored, retracted, and replaced atomically as a single EAV fact.In other words, the dependency order is: multi-body syntax first (v2.0), then rule persistence as EAV facts (potentially v2.x). Option 1 should not be attempted against the current single-body-per-form grammar.
adityamukho commentedon May 15, 2026
EAV persistence should remain a 2.0 goal.
docs: bring TEST_COVERAGE.md fully current (998 tests)