# BranchPy v0.8.8 — History System Sample Data

This directory contains sample configuration, snapshots, and JSONL examples for the History System.

## Files

### `sample_config.json`
Complete configuration template for history settings including:
- Stack capacity and retention policies
- Auto-snapshot triggers
- Snapshot compression settings
- Governance integration

**Usage:**
```bash
# Copy to your project
cp sample_config.json /path/to/project/.branchpy/config.json

# Or merge into existing config
```

---

### `sample_history.jsonl`
Example JSONL history file showing:
- Stack header with capacity
- Multiple undo actions with full metadata
- Correlation IDs for governance tracking
- Stack footer

**Format:**
```jsonl
{"type": "stack_header", "timestamp": "...", "capacity": 100}
{"type": "undo_action", "data": {...}}
{"type": "undo_action", "data": {...}}
{"type": "stack_footer", "timestamp": "..."}
```

**Location:** `.branchpy/history/history.jsonl`

---

### `sample_snapshot.json`
Complete project snapshot example containing:
- CFG structure (nodes, edges with semantics)
- Stats 2.x data (variables with usages)
- Governance log entries
- Asset validation results
- SHA-256 integrity hash

**Structure:**
```json
{
  "snapshot_id": "snap_YYYYMMDD_HHMMSS_hash",
  "metadata": {...},
  "cfg": {"nodes": [...], "edges": [...]},
  "stats": {"variables": {...}, "summary": {...}},
  "governance": [...],
  "assets": {"results": [...], "summary": {...}},
  "sha256": "..."
}
```

**Location:** `.branchpy/history/snapshots/{snapshot_id}.json`

---

### `sample_governance_event.json`
Example governance event for ACTION_APPLIED showing:
- Event type and correlation ID
- Actor and timestamp
- Full operation context
- Snapshot references
- Performance metrics

**Usage in Governance Panel:**
Filter by correlation ID to see all related events for a history operation.

---

## Testing with Sample Data

### 1. Manual Stack Creation

```bash
# Create history directory
mkdir -p .branchpy/history/snapshots

# Copy sample files
cp sample_history.jsonl .branchpy/history/history.jsonl
cp sample_snapshot.json .branchpy/history/snapshots/snap_20251105_152412_def456.json

# Test CLI
bpy history show
```

### 2. Snapshot Integrity Verification

```python
from branchpy.core.history import Snapshot
import hashlib
import json

# Load sample snapshot
with open('sample_snapshot.json', 'r') as f:
    snapshot = json.load(f)

# Verify hash
snapshot_copy = {k: v for k, v in snapshot.items() if k != 'sha256'}
computed_hash = hashlib.sha256(
    json.dumps(snapshot_copy, sort_keys=True).encode()
).hexdigest()

assert snapshot['sha256'] == computed_hash
print("✅ Snapshot integrity verified")
```

### 3. Governance Event Correlation

```bash
# View all events for a correlation ID
bpy governance query --correlation-id uuid-12345-67890-abcdef

# Expected output:
# - ACTION_APPLIED (AnalyzeProject)
# - Any subsequent UNDONE/RESTORED events
```

---

## Customization

### Adjust Capacity

Edit `sample_config.json`:
```json
{
  "history": {
    "capacity": 50  // Reduce for smaller projects
  }
}
```

### Enable Compression

```json
{
  "history": {
    "snapshot_compression": {
      "enabled": true,
      "threshold_kb": 512,
      "algorithm": "gzip"
    }
  }
}
```

### Custom Snapshot Triggers

```json
{
  "history": {
    "auto_snapshot": true,
    "snapshot_on_analyze": true,
    "snapshot_on_validate": false,  // Disable
    "snapshot_on_replace": true
  }
}
```

---

## Integration Tests

Use sample data for integration testing:

```python
import pytest
from branchpy.core.history import HistoryPersistence, Snapshot

def test_load_sample_history():
    """Test loading sample history JSONL."""
    persistence = HistoryPersistence("/path/to/project")
    
    # Copy sample to test location
    # ... (setup code)
    
    stack = persistence.load_stack()
    assert stack is not None
    assert len(stack.undo_stack) == 3
    assert stack.undo_stack[0].operation == "AnalyzeProject"

def test_load_sample_snapshot():
    """Test loading sample snapshot."""
    snapshot = Snapshot.load(
        "/path/to/project", 
        "snap_20251105_152412_def456"
    )
    
    assert snapshot["snapshot_id"] == "snap_20251105_152412_def456"
    assert "cfg" in snapshot
    assert "stats" in snapshot
    assert "sha256" in snapshot
```

---

## See Also

- [History System Internals](../../../docs/v0.9.0/Core/History/history_internals.md)
- [CLI Commands Reference](../../../docs/v0.9.0/CLI/commands/history.md)
- [VS Code History Panel Guide](../../../docs/v0.9.0/Dashboard/history_panel.md)

---

**Version:** v0.8.8  
**Last Updated:** 2025-11-05
