GlyphRunner System
43887931cc
This commit includes the complete implementation of the GlyphRunner system:
SUBSYSTEMS CREATED:
1. xic_extensions (5 modules)
- gsz3_decompressor: Compression/decompression with checksum validation
- segment_runtime: Multi-segment execution with namespace merging
- execution_tracer: Execution tracing with event capture
- profiler: Lightweight segment profiling (duration, memory, counts)
- compressed_engine: High-level orchestration (simulate/execute modes)
2. gx_compiler (5 modules)
- segmenter: Deterministic source code segmentation
- compressor: GSZ3 compression wrapper
- manifest_builder: XIC/GX manifest generation
- gx_packer: Binary .gx file format (XIC header + manifest + payload)
- compiler: High-level compilation pipeline
3. runtime_executor (6 modules)
- gx_loader: .gx file loading and parsing
- execution_plan: Execution plan building from manifest
- context: Runtime execution context management
- runner: Core execution engine with tracing/profiling
- events: Runtime event system and event bus
- integration: High-level API (run_gx_with_summary)
4. gx_cli (5 modules)
- commands: Command implementations (compile, run, inspect, summary)
- parser: argparse-based argument parsing
- dispatcher: Command routing and execution
- main: CLI entry point with exception handling
5. codex_lineage (6 modules)
- lineage_model: Data structures (EpochInfo, ContributorInfo, etc.)
- epoch_mapper: Version string parsing (v1, v2.5-beta, etc.)
- contributor_index: In-memory contributor registry
- lineage_resolver: Manifest → CodexEntry resolution
- grammar_hooks: Human-readable report generation
- inspector: High-level .gx file inspection utility
INTEGRATION TESTS (7 test files)
- test_compile: Compilation pipeline tests
- test_run: Execution verification tests
- test_inspect: Inspection and manifest tests
- test_summary: Summary generation tests
- test_errors: Error handling and graceful failure
- test_determinism: Reproducibility and determinism
- run_all_tests: Master test runner
ARCHITECTURE HIGHLIGHTS:
✓ Zero circular imports
✓ Pure functions where possible
✓ Explicit error handling
✓ No global side effects
✓ Only stdlib dependencies
✓ Deterministic output
✓ Production-ready code
PIPELINE:
sample.py → [gx_compiler] → sample.gx (960 bytes, XIC format)
→ [runtime_executor] → Execution (6 segments)
→ [codex_lineage] → Human-readable lineage report
CLI COMMANDS:
gx compile <source.py> [-o output.gx]
gx run <file.gx>
gx inspect <file.gx>
gx summary <file.gx>
VERIFICATION:
✓ All 5 subsystems created and tested
✓ Full pipeline: compile → inspect → execute
✓ Codex lineage fully integrated with gx_cli
✓ 25+ integration test cases
✓ End-to-end testing successful
✓ No external dependencies beyond Python stdlib
Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
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 ✓
|