Preserve structured diagnostics, source attribution, phase outcomes and revision context through compiler, Studio, LSP, MCP and JavaFX. Add project service discovery and resilient VS Code reconnection. Correct all eight reproduced PBS production failures in expression context, sibling executable bindings and nominal owner identity. Consolidate specs, lessons, immutable baseline evidence and the maintained source-to-guest qualification runner. Validation: required Gradle gate recorded 724 tests, with 711 passed and 13 skipped. Full corpus passed 168 compilation observations and 108 guest runs (104 successes and four deliberate faults); supplemental controls passed 42 compilations and 16 guest runs. TypeScript compilation, two Node discovery tests and discussion validation passed.
Specification Guide
Specifications live under this tree and are organized by contract owner:
| Owner | Canonical corpus | Responsibility |
|---|---|---|
compiler/general |
General compiler | Shared compilation, linking, typed handoff, emission and acceptance |
compiler/pbs |
PBS language | PBS source, semantics, SDK and frontend projections |
packer |
Packer | Assets, artifacts, packing and diagnostics |
studio |
Studio | Shell, workspaces, adapters and visual/automation integration |
New compiler languages receive their own corpus under compiler-languages/.
Shared compiler policy stays in compiler/; PBS is not the root for other domains.
Each domain README provides a chapter index and reading order. Numbered chapters are normative within their stated scope. Feature chapters own their detailed contracts; cross-cutting chapters reference those rules rather than maintaining competing versions. Write specifications and durable lessons in English.
The runtime repository owns PBX, ISA, admission and VM execution. Studio's VM architecture references and catalog mirrors retain their separate provenance and synchronization policy. Roadmaps describe cross-domain planning, not an alternative contract source.
The operational lifecycle is agenda -> decision -> plan -> implement -> lesson.
Keep its artifacts in discussion/ and use the local discussion CLI for state
transitions, validation and housekeeping. See repository instructions.
Navigation verification
Run python3 tools/documentation/verify.py from the repository root to check local
links and anchors. Pass --runtime ../runtime to also check provider references
against an available read-only runtime checkout. The byte-exact architecture/ISA
mirrors retain the link context of their runtime originals; the checker resolves
them there. Ordinary builds and installed documentation reads do not require that
checkout.