hermes-brain/projects/passepartout/architecture/design/the-symbolic-engine/abstract-fact-store-interface-modular-by-design.org

Abstract Fact Store Interface — Modular by Design

The fact store is accessed through an abstract API. The Merkle DAG (or any future backing store) is an implementation behind this interface, not a dependency that code throughout the system calls directly.

fact-assert    :: fact → store → (:admitted | :rejected | :flagged)
fact-query     :: (entity &key relation policy) → active-value-or-values
fact-history   :: (entity relation) → ordered chain of versioned facts
fact-snapshot  :: () → root-hash
fact-rollback  :: root-hash → store

Implementations behind the interface:

• Phase 1-4: ephemeral hash table with :timestamp and :parent-id pointers. No cryptographic hashing. No persistence.
• Phase 5: VivaceGraph + Merkle memory-object wrapper. Content-addressed, persistent, tamper-proof.

Future implementations that satisfy the same interface — an append-only write-ahead log, an immutable B-tree, a content-addressed triple store — can replace the backing store without changing any consumer. The archivist, Screamer, ACL2, and the planner call fact-assert and fact-query, not Merkle struct accessors or VivaceGraph traversal syntax.

This is not speculative modularity. The two-implementation migration (Phase 1-4 hash table → Phase 5 VivaceGraph + Merkle) is in the roadmap. If the interface leaks implementation details, the migration breaks. The interface must be designed, tested against both backends, and committed before Phase 1 ships.