# Codex Lineage System

Metadata and lineage tracking for GlyphRunner GX files.

## Modules

### lineage_model.py
Core data structures for lineage information:
- **EpochInfo**: Version and stability information (major, minor, stability)
- **ContributorInfo**: Contributor metadata (name, registration time, contribution count)
- **SegmentLineage**: Segment metadata (id, line ranges, byte ranges)
- **CodexEntry**: Complete lineage entry (source, version, epoch, contributor, segments)

All models support:
- `to_dict()` — serialize to JSON-compatible dict
- `from_dict(data)` — deserialize from dict

### epoch_mapper.py
Parse epoch strings into structured EpochInfo.

Supports:
- "v1" → major=1, minor=0, stability=stable
- "v2.5-beta" → major=2, minor=5, stability=beta
- "v3-experimental" → major=3, minor=0, stability=experimental

**Export**: `parse_epoch(epoch_str: str) -> EpochInfo`

### contributor_index.py
In-memory contributor registry with contribution counting.

**Exports**:
- `register_contributor(name: str) -> ContributorInfo`
- `get_contributor(name: str) -> Optional[ContributorInfo]`
- `list_contributors() -> List[ContributorInfo]`

### lineage_resolver.py
Resolve lineage information from a GX manifest.

**Export**: `resolve_lineage(manifest: Dict[str, Any]) -> CodexEntry`

Pipeline:
1. Extract source file, type, version, origin from manifest
2. Parse epoch (from manifest.epoch field)
3. Register contributor (from manifest.contributor field)
4. Parse segments from manifest.codex_lineage.segments
5. Return CodexEntry with all information

### grammar_hooks.py
Generate human-readable lineage reports.

**Exports**:
- `summarize_lineage(entry: CodexEntry) -> str` — full report
- `describe_segment(segment: SegmentLineage) -> str` — single segment description

### inspector.py
High-level utility for inspecting .gx files.

**Export**: `inspect_gx(path: str) -> str`

Pipeline:
1. Read .gx file from disk
2. Validate magic bytes (XIC)
3. Parse manifest JSON
4. Resolve lineage via lineage_resolver
5. Generate report via grammar_hooks
6. Return multi-line report string

## Integration

### With gx_cli
```python
from codex_lineage.inspector import inspect_gx

# In gx_cli/commands.py
def cmd_inspect(gx_path: str) -> int:
    try:
        report = inspect_gx(gx_path)
        print(report)
        return 0
    except Exception as e:
        print(f"Error: {e}", file=sys.stderr)
        return 1
```

### With manifest
Codex lineage system works with manifests produced by gx_compiler:
- Expects `codex_lineage.segments` array
- Expects `epoch` field (version identifier)
- Expects `contributor` field (contributor name)
- Handles missing fields gracefully

## Architecture

- **Pure functions**: epoch_mapper, grammar_hooks
- **Stateful module**: contributor_index (in-memory registry)
- **Data classes**: All models in lineage_model
- **No external deps**: Standard library only
- **No circular imports**: Modules depend downward only

## Example Usage

```python
from codex_lineage.lineage_resolver import resolve_lineage
from codex_lineage.grammar_hooks import summarize_lineage

# Get manifest from .gx file
manifest = load_gx("file.gx")[0]

# Resolve lineage
entry = resolve_lineage(manifest)

# Generate report
print(summarize_lineage(entry))
```

## Testing

All tests pass:
- Module imports ✓
- Epoch parsing ✓
- Contributor registration ✓
- Lineage resolution ✓
- Report generation ✓
- Model serialization ✓
- Real .gx file inspection ✓