trugs-store 2.0.0

Graph storage backends for TRUGS specifications — InMemory, PostgreSQL, JSON file persistence. Native TRUGS 2.0 (core_v2.0.0) support: LEVEL_PREFIX hierarchy validation, inheritance stamping, canonical re-emit.

trugs-store

Graph storage backends for TRUGS specifications — InMemory, PostgreSQL, JSON file persistence.

trugs-store is the shared persistence layer for all TRUGS tooling. Every tool that reads or writes .trug.json files goes through this package. It supports JSON file storage for development and PostgreSQL for production scale.

As of 2.0.0, trugs-store natively supports TRUGS 2.0 (core_v2.0.0): vocabulary dispatch on a TRUG's declared capabilities.vocabularies, LEVEL_PREFIX hierarchy validation, inheritance stamping, and canonical re-emit on save. v1 TRUGs (core_v1.0.0, project_v1) continue to validate unchanged — the upgrade is purely additive.

Install

pip install trugs-store

# With PostgreSQL support:
pip install trugs-store[postgres]

Quick Example

from trugs_store import InMemoryGraphStore, JsonFilePersistence

# Load a .trug.json file
persistence = JsonFilePersistence()
store = persistence.load("folder.trug.json")

# Query
print(store.node_count())
print(store.find_nodes(type="FUNCTION"))

# Validate against TRUGS CORE rules
violations = store.validate_graph()
for v in violations:
    print(f"{v.severity}: {v.rule} — {v.message}")

Architecture

Component	What it does
GraphStore protocol	PEP 544 structural interface — 22 methods across 8 categories
InMemoryGraphStore	Dict-backed store — O(1) node lookup, O(degree) edge access
PostgresGraphStore	SQL-backed store — indexed queries, transactional writes, COPY bulk insert
JsonFilePersistence	Load/save .trug.json files to/from InMemoryGraphStore
PostgresPersistence	Load/save graphs to/from PostgreSQL
Dual-write bridge	write_trug() / read_trug() — writes JSON + optionally PostgreSQL

Basic Usage

Load and query a TRUG

from trugs_store import JsonFilePersistence

p = JsonFilePersistence()
store = p.load("folder.trug.json")

# Find all FUNCTION nodes
functions = store.find_nodes(type="FUNCTION")

# Traverse outgoing edges from a node
for node, edge, depth in store.traverse("root", direction="outgoing", max_depth=2):
    print(f"  {'  ' * depth}{node['id']} via {edge['relation']}")

Create a graph in memory

from trugs_store import InMemoryGraphStore

store = InMemoryGraphStore()
store.set_metadata("name", "my_graph")
store.set_metadata("version", "1.0.0")

store.add_node({"id": "root", "type": "FOLDER", "properties": {},
                "parent_id": None, "contains": [], "metric_level": "KILO_FOLDER",
                "dimension": "main"})
store.add_node({"id": "child", "type": "DOCUMENT", "properties": {},
                "parent_id": None, "contains": [], "metric_level": "BASE_DOCUMENT",
                "dimension": "main"}, parent_id="root")
store.add_edge({"from_id": "root", "to_id": "child", "relation": "REFERENCES"})

print(store.node_count())  # 2
print(store.get_children("root"))  # [child node]

Validate a graph

violations = store.validate_graph()
if violations:
    for v in violations:
        print(f"{v.severity}: {v.rule} on {v.node_id} — {v.message}")
else:
    print("Graph is valid.")

Documentation

• Package boundary: BOUNDARY.md — what STORE owns vs what TRUGS-TOOLS owns, and the deliberate two-validator split (structural vs CORE-16)
• TRUGS Specification: TRUGS-LLC/TRUGS — protocol, language, validator
• GraphStore Protocol: SPEC_844_graphstore_protocol.py — full PEP 544 interface
• TRUG Graph Index: folder.trug.json — machine-readable structure of this repo
• Dark Code Standard: TRUGS-LLC/TRUGS/REFERENCE/STANDARD_dark_code_compliance.md

Status

Version: 2.0.0 (TRUGS 2.0 native — first release with core_v2.0.0 support; lockstep with trugs-tools/trugs-folder 2.0.0) Phase: Beta License: Apache 2.0 — TRUGS LLC