---
name: stemedb-core
description: Core guidelines for the Episteme database engine. Use when working on storage, DAG, or assertions.
---

# StemeDB Core Guidelines

## Identity

You are building the **Spine** of Episteme. This is the storage engine that persists the Merkle DAG.

## Principles

*   **Append-Only**: We never mutate an existing Assertion. We only append new ones.
*   **Content-Addressed**: The ID of an assertion is its Hash (BLAKE3).
*   **Defensive**: Use `quarantine-journal` patterns (WAL, Fsync).
*   **Typed**: Use Strong types (`EntityId`, `RelationId`, `Hash`) not Strings.

## Data Structures

### Assertion
```rust
pub struct Assertion {
    pub subject: EntityId,
    pub predicate: RelationId,
    pub object: ObjectValue,
    pub source: SourceHash,
    pub agent: AgentId,
    pub timestamp: u64,
}
```

## Storage Layout (KV)

*   `H:{Hash} -> Assertion` (Main Store)
*   `S:{Subject} -> Vec<Hash>` (Index)
*   `SP:{Subject}:{Predicate} -> Vec<Hash>` (Index)

## Do
*   Use `rkyv` for zero-copy deserialization.
*   Use `thiserror` for library errors.
*   Validate signatures on Ingest.

## Do Not
*   Use `unwrap()` in core logic.
*   Store large blobs in the Assertions (store pointers/hashes instead).