Repository navigation
Phantom 0.1.0
First release of Phantom: ordinary Python plus a structured instruction layer embedded in comments (or whitespace / zero-width blocks), applied by phantom run. Stock python file.py does not execute the instruction layer.
Implemented
- Seven instructions:
event.declare,event.on,diagnostic.note,counter.create,counter.increment,meta.author,meta.version. - Formal grammar (SPECIFICATION.md), typed immutable IR, lexer, parser, validator, diagnostics with caret context, SARIF export.
- Encodings: comment (recommended); whitespace, zero-width Unicode and hybrid are experimental (fragile under formatters/normalisation).
- CLI:
check,inspect,run,generate,diff,verify(--strictaudit for invisible/bidirectional characters). - Runtime: instructions applied at initialisation, lifecycle events (
phantom.pre_execute,phantom.post_execute,phantom.shutdown), bounded counters, capability model, host run as a subprocess. - Optional LLM-assisted generator: validated plan, insert-only transformer, stale-patch rejection, AST-equality host-preservation check, separate candidate file, offline
--plan-file.
Verified
- 204 tests pass; ruff clean; CI green on Python 3.10-3.13, Ubuntu and Windows; wheel installs and runs in a clean venv.
Not verified / not included
- The Gemini provider has not been run against the live API (tested with a fake SDK only).
- macOS is untested.
- No sandbox:
phantom runandphantom verifyexecute programs, andevent.onhandler paths import modules. Only run files you trust. phantom verifycompares one run; it is not a proof of equivalence.- Phantom C is a long-term research vision (docs/research/PHANTOM_C.md), not implemented. No claim of undetectable execution or of defeating security products.
See CHANGELOG.md and docs/RESEARCH_STATUS.md.