126 lines
3.4 KiB
Markdown
126 lines
3.4 KiB
Markdown
|
# 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 ✓
|