2125_GCE/codex_lineage

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

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

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 ✓