Phantom v0.1.2-rc1 — Community Contributions & Tooling

Thank you to every contributor who helped improve Phantom since v0.1.1! 🚀

⭐ Enjoyed contributing to Phantom? Please consider dropping a Star on alok-108/phantom (top right) — it helps new contributors and Python developers discover the project!

What's Changed * docs: add Hindi README and quickstart (#34) by @Aaqibhafeezkhan in #41 * Automate contributor onboarding: /take, stale-claim sweep, PR labels, first-merge thanks by @alok-108 in #50 * fix(runtime): invoke event callbacks only once after handler errors by @Zhuyuyangyy in #65 * feat(cli): add --timeout option for host program in phantom run (#18) by @slopgobblercobbler in #38 * fix(runtime): preserve capability denial messages by @Vamsi-2581 in #63 * fix(parser): reject non-ASCII numeric syntax consistently by @Zhuyuyangyy in #66 * fix(encoding): escape supported string control characters by @Zhuyuyangyy in #67 * Fix source line counting to match Python by @Zhuyuyangyy in #68 * Test runtime initialization and handler errors by @Sinkleberg in #77 * Report malformed instruction lines; require inserted instructions to be readable (#45) by @alok-108 in #69 * Kill the whole process tree on host timeout; make verify verdicts trustworthy (#52, #53) by @alok-108 in #70 * Spell bidirectional controls as code points; keep hidden characters out of project source by @alok-108 in #73 * Opt-in capability policy and handler allow-list (#30, #31) by @alok-108 in #71 * mypy, property-based tests, coverage gate and a reusable GitHub Action (#26, #28, #29) by @alok-108 in #72 * Experimental VS Code extension: make the hidden layer visible (#36) by @alok-108 in #74 * docs: proposal 0001 (invariant.assert) and a current roadmap status by @alok-108 in #76 * Add meta.license instruction and update registries by @Kakacat-dot in #10 * Security: match instruction lines in linear time (ReDoS) (#78) by @alok-108 in #79 * Maintainer inbox: make waiting contributors visible and ping the maintainers by @alok-108 in #90 * Show parse errors in phantom inspect and exit 2 on them (#80) by @bh-official in #92 * fix(diagnostics): keep tabs in the caret prefix by @bfs2021 in #91 * fix(parser): drop a leading UTF-8 BOM so it cannot hide the first instruction by @namanraii in #93 * Percent-encode SARIF artifactLocation URIs (#55) by @namanraii in #94 * Reject non-UTF-8 source files with one clear error in every command (#54) by @namanraii in #95 * inbox: age CI approval requests and escalate them past a threshold by @alok-108 in #98 * [105] Add counter.reset instruction to reset a bounded counter by @Dikshant-Neupane in #111 * Add NO_COLOR support and --no-color flag for phantom diff (#104) by @Dikshant-Neupane in #112 * Add bash and zsh shell completion scripts (#103) by @Dikshant-Neupane in #117 * Add fish shell completion script (#108) by @Dikshant-Neupane in #116 * feat(cli): add quiet flag to check and run by @SahilDhonde-9 in #114 * Fix/py typed marker by @Yashvardhan0904 in #113 * Docs: Add worked example for --deny and --handlers-from (#88) by @ImNotThatPro in #115 * feat: add meta.tags instruction to record layer keyword tags (#122) by @Dikshant-Neupane in #126 * docs: add German Quickstart translation by @canakyuz in #124 * Add schema name and version to inspect JSON output by @Dikshant-Neupane in #127 * Escape control characters below U+0020 in encoded string arguments by @Dikshant-Neupane in #132 * Add placement options near:Class.method and main-guard (#4) by @Dikshant-Neupane in #133 * test: restore Unicode line separators in round-trip properties by @ANO3457 in #131 * Spanish documentation quickstart.md by @iescman2002 in #129 * fix(cli): validate UTF-8 upfront via read_source in cmd_run by @ANO3457 in #138 * Fix(CI): support paths containing space and muliline yaml inputs by @ImNotThatPro in #130 * verify: compare multiple argument and stdin cases by @Dikshant-Neupane in #144 * test: exercise the installed Python module entry point by @ANO3457 in #141 * feat(parser,runtime): add diagnostic.warn instruction (#119) by @ANO3457 in #140 * test: cover and document public grammar helpers by @ANO3457 in #139 * feat(ci): add pre-commit hook definitions by @Logic769 in #143 * feat(scripts): add nano syntax highlighting for the phantom instruction layer by @Logic769 in #142 * docs: add Brazilian Portuguese quickstart by @hanrry-dev in #125 * test: cover host subprocess launch errors by @Davinchigh in #155 * fix(diff): strip both CRLF and LF before ANSI reset in format_diff_colored (#147) by @ANO3457 in #158 * fix(sourcemap): do not fall back to default mappings when querying an explicit file (#149) by @ANO3457 in #159 * fix(encoding): reject unterminated decode blocks missing end markers (#150) by @ANO3457 in #160 * fix(encoding): preserve duplicate instructions within the same encoding layer in HybridCodec (#145) by @ANO3457 in #161 * fix(validator): report unclosed and stray zero-width block markers in audit_source (#148) by @ANO3457 in #162 * fix(runtime): restore sys.path after execute_host completes (#146) by @ANO3457 in #163 * feat(parser,runtime): add counter.decrement instruction (#118) by @ANO3457 in #164 * Adding sublime text syntax hightlighting by @ImNotThatPro in #157 * build(deps): bump actions/labeler from 5 to 7 by @dependabot[bot] in #180 * build(deps): bump actions/setup-node from 4 to 7 by @dependabot[bot] in #178 * build(deps): bump actions/github-script from 7 to 9 by @dependabot[bot] in #179 * fix: give verify's programs an empty stdin instead of Phantom's (#82) by @namanraii in #177 * fix(encoding): reject unterminated blocks in decode_source by @Rustaman1280 in #174 * fix(scripts): match the full semver in the sublime prefix rule by @bfs2021 in #175 * fix(syntax): highlight meta.tags in nano by @Golden007-prog in #176 * feat(scripts): add PowerShell tab completion script by @zheng-guannan577 in #186 * fix(cli): preserve positional arguments after '--' in subcommands (#165) by @ANO3457 in #187 * feat(scripts): add Emacs syntax highlighting major mode by @zheng-guannan577 in #188 * fix(generator): validate list types in parse_plan to prevent TypeError (#166) by @ANO3457 in #189 * docs: add French quickstart guide (docs/fr/QUICKSTART.md) by @abhirajadhikary06 in #193 * fix(parser): reject malformed and unrecognized string escape sequences (#181) by @ANO3457 in #191 * fix(validator): report unclosed and stray whitespace block markers in audit_source (#183) by @ANO3457 in #192 * fix(sourcemap): do not overwrite default line mappings with file-scoped mappings by @ANO3457 in #194 * fix(validator): prevent cascading errors when counter is created with invalid limit by @ANO3457 in #195 * fix(runtime): support positional-only parameters in event handlers (#167) by @ANO3457 in #197 * fix(runtime): scope cwd on sys.path during handler resolution by @zheng-guannan577 in #199 * fix(parser): fall back to source encoding for unmapped hybrid indices by @zheng-guannan577 in https://gi...

Phantom 0.1.1

A small release: the first two outside contributions, plus a lot of work on making the project easier to join.

What's new

• phantom diff --host-only compares only the Python layer of two files and prints nothing when the host code is unchanged. It reads the files only and never runs them. Thanks to @dbdefault (#40).
• Tests for phantom generate --stdin, the interactive prompts, the EOF fallback and remote consent, checked against deliberately broken code. Thanks to @jez-elijah (#39).
• A first-PR guide in CONTRIBUTING.md, a contributor guide for adding instructions, encodings and providers, issue and PR templates, ADRs, MAINTAINERS.md, RELEASING.md and a welcome workflow for first-time contributors.
• A terminal demo and a refreshed README, CITATION.cff, a dev container for Codespaces, and private vulnerability reporting.
• CI actions updated (checkout 7, setup-python 7); dev tool minimums raised for pytest and ruff.

Unchanged and worth knowing

• The language specification is still 0.1.0 and no instruction changed.
• Not verified: the Gemini provider against the live API, and macOS.
• Not on PyPI yet (the name phantom-lang belongs to another project). Install with pip install "git+https://github.com/hayagrivai-labs/phantom.git" or from the wheel below.
• Two pull requests (#38 run --timeout, #10 meta.license) are still waiting for requested changes and are not part of this release.

Open issues labelled good first issue and mentor available are the easiest way to contribute: https://github.com/hayagrivai-labs/phantom/issues

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 (--strict audit 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 run and phantom verify execute programs, and event.on handler paths import modules. Only run files you trust.
• phantom verify compares 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.