Readme
# LINEAGE ENGINE
### ROOT0 Provenance System — Two-Tier Design
> Every output, block, pattern, or creation traces back to a single root.
> The engine never forgets. It never overwrites. It only appends.
**Author:** David Lee Wise (ROOT0) / TriPod LLC
**License:** CC-BY-ND-4.0 + TRIPOD-IP-v1.1
**Canon:** Block 371 (Perpetual) · Block 333 (Tree snapshot)
---
## Two Tiers
### Tier 1 — `Root0LineageTracker` (stdlib only)
Zero dependencies. Records every pipeline stage as a signed, hash-chained `LineageRecord`. Runs anywhere Python 3.9+ runs.
```bash
python -X utf8 lineage.py
```
### Tier 2 — `LineageEnginePerpetual` (Merkle + ECDSA + WebSocket)
```bash
pip install merkletools cryptography websockets
python -X utf8 lineage.py --tier2
```
Real ECDSA secp256k1 signatures. Merkle tree ledger. Fractal indexer (0–255 depths). WebSocket broadcast. Air-gap sync.
---
## Tier 1 — Quick Start
```python
from lineage import Root0LineageTracker, PRIMEWithLineage
tracker = Root0LineageTracker(b"ROOT0:God Tunnel:1-2-3")
pipeline = PRIMEWithLineage(tracker)
# Run full pipeline
result = pipeline.full_pipe(b"transaction payload data")
print(result["lineage"]["integrity"]) # True
print(result["chain_summary"])
# Trace back from any hash
final_hash = tracker.chain[-1].record_hash
records, ok = tracker.trace_back(final_hash)
# records = [AIRGAP, BRIDGE, BURNER, NEMESIS] in forward order
# ok = True (integrity verified)
# Export chain
chain = tracker.export_chain() # list of dicts
# Verify chain
v = tracker.verify_chain() # {"status": "INTACT", ...}
```
---
## Tier 2 — Quick Start
```python
from lineage import LineageEnginePerpetual
engine = LineageEnginePerpetual()
engine.start(websocket=True, port=8765)
# Emit events
engine.emit("Y.N_closure", "ROOT0", {"decision": "Y"}, depth=0)
engine.emit("bridge_burned", "ROOT0", {"cost": 100.0}, depth=1)
engine.emit("nemesis_check", "Company_X", {"verdict": "VALID"}, depth=2)
# Query lineage
lineage = engine.get_lineage("ROOT0", depth=0)
# Verify signature
is_valid = engine.verify_event(lineage[0])
# Air-gap sync
engine.flush_air_gap("sync.json")
# Connect WebSocket client
# wscat -c ws://localhost:8765
```
---
## LineageRecord Structure
Every stage in the pipeline produces one record:
| Field | Type | Description |
|-------|------|-------------|
| `record_id` | uuid | Unique identifie