Phase 4: Tooling + developer experience

[hyperpolymath]

Tracking issue for Phase 4 of the production path. See docs/PRODUCTION-PATH.adoc §Phase 4.

Theme

The unglamorous phase. Necessary for adoption that doesn't depend on direct maintainer involvement.

Deliverables

• LSP server (twasm-lsp) — tree-sitter parsing (from Phase 1's Track A) → semantic analysis → diagnostics surfacing Phase 1's human-readable errors. Acceptance: completion, jump-to-definition, hover types, inline errors work in VS Code.
• Debugger integration — DWARF emission from codegen; gdb/lldb scripts for typed-wasm-aware inspection
• Editor plugins — VS Code (must-have), JetBrains, Neovim, Emacs, Helix, Zed
• Linguist registration — PR against github-linguist/linguist adding .twasm as nested under WebAssembly group; depends on tree-sitter grammar from Phase 1 + adoption evidence from Phase 2
• Package convention — likely "use wapm/wasi conventions, here are the metadata fields" rather than a bespoke package manager
• Documentation suite:
  • Getting-started tutorial
  • The 10 levels explained for working programmers (not type theorists)
  • Cookbook of patterns
  • ABI/FFI guide
  • Architecture deep-dive
  • Formal-proofs guide for the academically inclined
• Conference talks + papers — ICFP/POPL for the academic side; WebAssembly Summit / Wasm I/O for the practitioner side
• Real-world examples beyond the existing 6: multi-module workspaces, shared-memory cross-language demos

Gate to Phase 5

Someone outside the hyperpolymath ecosystem successfully ships something using typed-wasm without needing direct maintainer support.

Depends on

• Phase 3 complete — issue Phase 3: Runtime-side enforcement #51
• Tree-sitter grammar from Phase 1's Track A (already at v1 / PR tree-sitter: v1 grammar — parses examples/01-single-module.twasm end-to-end (zero ERROR nodes) #62; needs full EBNF parity)

Status when this issue closes

typed-wasm is a fully self-serve toolchain for outside adopters. The maintainer becomes optional for the typical user journey.

Next phase

• Phase 5 — Specification + standards: issue Phase 5: Specification + standards #53