P1SCode Status And Scope

This page defines what P1SCode is today, what is preview, and what is not yet a contract.

M1 milestone (platform): On-image toolchain paths, fixture gate, and OS/session expectations for shippable P1SCode are spelled out in newdocs/p1scode-m1.md (P1Start repo root).

Current State (Apr/May 2026)

  • Effective build path: Python transpiler in SDK/p1sdk/p1sc.py

  • Rust lexer/parser/AST library (shared with on-device p1sc.elf): SDK/p1sdk/p1sc_syntax/ — host-tested against the same fixtures as the transpiler

  • On-device parser driver binary: apps/p1sc (depends on p1sc_syntax)

  • Generated build target: apps/p1scode_app/

The practical language behavior currently follows the transpiler path, not a unified compiler pipeline. p1sc_syntax is the convergence point for parse-level behavior; see p1scode-language-guide for a guide-style language introduction, and p1scode-toolchain-workflow for fixtures + JSON diagnostics.

Production / Supported

  • Building a subset of .p1s sources through the transpiler to a static Rust app target

  • Syscall-oriented scripting patterns mapped by transpiler rules

  • Internal experimentation for language surface design

  • On-device syntax check via /bin/p1sc.elf: lex+parse after import merge; --json-diagnostics compatible with the host array shape — see reference/p1scode-toolchain-workflow

Preview / In Progress

  • Aligning parser/transpiler semantic behavior into one contract (beyond shared p1sc_syntax + fixtures)

  • Richer structured diagnostics for transpile/type errors on the host driver (JSON check mode is stable; bridge/LSP mappings evolve)

  • Deeper language reference (full grammar, all builtins, examples per feature): not written yet; today’s truth is fixtures + template + p1sc_syntax + transpiler.

Not Yet Contract

  • Full standalone compiler pipeline with stable IR/typechecker

  • Stable package/module ecosystem

  • Compatibility guarantees across arbitrary language features

  • Complete doc parity between legacy HTML and Sphinx

Language Contract Goals (Near-Term)

  • One source of truth for grammar/AST behavior

  • Conformance fixtures (.p1s input and expected parse/transpile outputs)

  • Deterministic build flow without hardcoded machine paths

  • Clear interoperability guidance with SDK surfaces (p1std, p1window, cstd)

Documentation Source Rules

  • Canonical platform contracts: newdocs/

  • Structured reader docs: this Sphinx tree

  • Legacy HTML (documentation/p1scode.html, documentation/p1sdk.html) should be treated as historical unless explicitly synchronized.