Lexicon

Persistence Port (Repository Pattern) for the Codex System.

Overview

The Lexicon class is an Abstract Base Class (ABC) that defines the formal contract for database engines. Any storage adapter (JSON, SQL, NoSQL) must implement these methods to ensure compatibility with the Codex core logic.

Key Responsibility: Decouple the domain logic from specific storage implementations, ensuring that data structures like Entry and Relation are handled consistently.

Persistence & Storage

save(entry: Entry) -> None

Saves or updates an entry. Performs an Upsert: if the ID already exists, the entry is overwritten. Adapters must ensure dataclass types are mapped correctly to the storage engine.

save_relation(relation: Relation) -> None

Persists a link between two entries. The implementation must prevent exact duplicates (same origin, destination, and type) if the database doesn't handle unique constraints natively.

Query & Retrieval

Method	Description
`get_by_id(id)`	Retrieves a unique entry by its UUID. Primary method for direct lookups.
`get_by_ids(list)`	Batch Query: Retrieves multiple entries. Must be optimized to avoid N+1 query issues.
`get_by_title(str)`	Exact title match. Used to validate uniqueness before creation.
`get_by_tag(str)`	Returns entries containing the specific tag in their tags list.
`get_by_category(str)`	Taxonomic filtering based on the specified category string.
`get_by_date_range(s, e)`	Chronological search for entries created between `start` and `end`.

Graph Navigation

get_in_relations(entry_id) -> List[Relation]

Retrieves incoming connections where to_id matches the provided ID. Returns an empty list if no matches are found.

get_out_relations(entry_id) -> List[Relation]

Retrieves outgoing connections where from_id matches. Essential for graph traversal from a source node.

check_relation(relation) -> bool

Verifies the existence of a link. Used for logical validation before attempting a save operation.

Deletion & Integrity

delete(entry_id: str) -> bool

Atomic Deletion (Manual Cascade): The adapter MUST ensure that when an entry is deleted:
1. All out_relations are removed.
2. All in_relations are removed.
3. The Entry object itself is deleted.

delete_relation(from_id, to_id, type) -> bool

Removes a specific link. If connection_type is omitted, it removes any relationship between the two IDs.