diff --git a/README.adoc b/README.adoc index b60e688..8431b7c 100644 --- a/README.adoc +++ b/README.adoc @@ -1,207 +1,84 @@ // SPDX-License-Identifier: MPL-2.0 -// SPDX-FileCopyrightText: 2024-2026 Jonathan D.A. Jewell +// Copyright (c) 2026 Jonathan D.A. Jewell <6759885+hyperpolymath@users.noreply.github.com> -= My: Progressive AI-Native Language += my-lang +:author: Jonathan D.A. Jewell <6759885+hyperpolymath@users.noreply.github.com> +:revdate: 2026-05-26 -image:https://img.shields.io/badge/OpenSSF-Best_Practices-green?logo=opensourcesecurity[OpenSSF Best Practices,link="https://www.bestpractices.dev/en/projects/new?repo_url=https://github.com/hyperpolymath/my-lang"] -image:https://img.shields.io/badge/License-PMPL--1.0-indigo.svg[License: PMPL-1.0,link="https://github.com/hyperpolymath/palimpsest-license"] -image:https://api.thegreenwebfoundation.org/greencheckimage/github.com[Green Web,link="https://www.thegreenwebfoundation.org/green-web-check/?url=github.com"] +> This README replaces an earlier stub that incorrectly stated the +> repository had been moved. *This is the canonical +> `hyperpolymath/my-lang`.* +`my-lang` is the *next-generation language* working project — a +multi-dialect surface for the hyperpolymath language stack. It is one +of two flagship language experiments in the estate (the other being +link:https://github.com/hyperpolymath/affinescript[`affinescript`]). -:toc: macro -:toclevels: 2 -:icons: font -:source-highlighter: rouge +== What's in here -[.lead] -*Let learning unfold. Let types guard. Let agents compose.* +`crates/`:: +Rust crates implementing the compiler / interpreter layers. -Progressive-disclosure programming language with first-class AI integration—four dialects scaling from visual blocks to agentic orchestration. +`dialects/`:: +Per-dialect surface-syntax definitions. The `my-lang` umbrella admits +multiple surface dialects sharing a common semantic core. -''' +`conformance/`:: +Conformance tests — programs that any compliant `my-lang` implementation +must accept (or reject) identically. -toc::[] +`examples/`:: +Worked examples covering each dialect, suitable as a learning +reference and CI smoke-test. -== Who This Is For +`docs/`:: +Design notes, language-reference drafts, and ADRs (Architecture Decision +Records). -[cols="1,3"] -|=== -|*Me-curious* |Educators seeking visual programming that secretly teaches affine types and reversible computation -|*Solo practitioners* |Developers wanting Rust-level safety with Python-level approachability—human-first, AI-assisted -|*Duet partners* |Teams exploring balanced human-AI pair programming with explicit collaboration protocols -|*Ensemble conductors* |Architects orchestrating multi-agent systems with neurosymbolic grammar extensions -|=== +`frontier-practices/`:: +Forward-looking experiments — things that may become part of the +language but are not yet stable. -== The Four Dialects - -My is not four languages—it is one language with *progressive reveal*. Concepts introduced as playful metaphors in Me unmask their CS foundations as learners advance. - -[cols="1,1,2,2"] -|=== -|Dialect |Stage |Mode |Core Insight - -|*Me* -|Visual (ages 8-12) -|Blockly-like drag-and-drop -|Resources as colored tokens; affine types as "use once" rules - -|*Solo* -|Text (ages 13+) -|Human-first, AI-assists -|Explicit affine/linear types, checkpoint/rollback, cut operators - -|*Duet* -|Collaborative -|Balanced co-creation -|Two-party protocols, neurosymbolic extensions - -|*Ensemble* -|Orchestration -|AI-leads, human-refines -|Full agentic composition, Newtonian spectrum agents -|=== - -== Why My? - -[source,my] ----- -// Type-safe AI with effect tracking -fn summarize(text: String) -> AI { - ai query { - prompt: "Summarize concisely" - context: text - model: claude - } -} - -// Affine types prevent resource bugs -fn transfer(affine token: Token) -> Result { - checkpoint save_state { - let result = process(move token); // must move, can't copy - if !result.is_ok() { - rollback save_state; - } - return result; - } -} - -// Cut operator for parser commitment -fn parse(input: String) -> Expr { - match input { - "(" => { let e = parse_nested(); !; expect(")"); e }, - _ => parse_simple() - } -} ----- - -=== Technical Differentiators - -[cols="2,3"] -|=== -|*AI as First-Class Citizen* |Native `ai!` expressions, typed `AI` return values, prompt templates with effect tracking -|*Progressive Safety* |Optional affine/linear types—start simple, add safety constraints as complexity grows -|*Reversible Computation* |Checkpoint/rollback at language level, not library level -|*Prolog-Heritage Parsing* |Cut operator (`!`) for committed choice in recursive descent -|*Neurosymbolic Bridge* |Duet dialect enables explicit symbolic-neural protocol boundaries -|=== - -== Quick Start +== Quickstart [source,bash] ---- -# Clone and build -git clone https://github.com/hyperpolymath/my-lang +git clone git@github.com:hyperpolymath/my-lang.git cd my-lang -cargo build --release - -# Run the REPL -cargo run -- repl - -# Run a program -cargo run -- run examples/hello.my - -# Build a static site with My SSG -cd my-ssg && cargo run -- new my-blog ----- - -== Architecture +just build # builds the workspace (Rust) +just test # runs unit + conformance tests ---- -my-lang/ -├── src/ # Core language (Rust) -│ ├── lexer.rs -│ ├── parser.rs -│ ├── checker.rs # Type checker with AI support -│ └── interpreter.rs -├── my-ssg/ # Static site generator -├── docs/wiki/ # Full documentation -├── solo-dialect/ # OCaml reference (Solo mode) -└── grammar.ebnf # Formal specification ----- - -== Ecosystem Integration - -My participates in the *poly-mcp* constellation: -[cols="1,2"] -|=== -|https://github.com/hyperpolymath/poly-ssg-mcp[poly-ssg-mcp] |MCP hub for static site generators—My SSG exposes `my_init`, `my_build`, `my_serve` -|https://github.com/hyperpolymath/poly-container-mcp[poly-container-mcp] |Multi-runtime container management -|https://github.com/hyperpolymath/poly-iac-mcp[poly-iac-mcp] |Infrastructure-as-code MCP servers -|=== +== Architectural authority -My SSG is one satellite in the broader poly-ssg ecosystem alongside Eclipse (Pony), Tyrano (TypeScript→ReScript migration), and others. +* link:ANCHOR.scope-arrest.2026-01-01.Jewell.scm[`ANCHOR.scope-arrest.*`] + — the scope-arrest anchor file enumerating what `my-lang` will and + will not be. +* link:AUTHORITY_STACK.mustfile-nickel.scm[`AUTHORITY_STACK.mustfile-nickel.scm`] + — the cross-cutting authority stack for the design. -== Newtonian Spectrum - -In Ensemble mode, seven specialized agents—colored by Newton's spectrum—orchestrate compilation and execution: - -[cols="1,2,2"] -|=== -|Color |Role |Solo Foundation - -|Red |Performance (hot paths) |Optimized parser -|Orange |Concurrency (async) |Async/await runtime -|Yellow |Contracts (safety) |Affine type tracking -|Green |Config (schema) |Structured AST -|Blue |Audit (trace) |Checkpoint system -|Indigo |Comptime (meta) |Compile-time evaluation -|Violet |Governance (policy) |Mode declarations -|=== +These two files are the source-of-truth for "is `X` in scope for +`my-lang`?" — consult them before opening a feature request. == Status -[cols="3,2"] -|=== -|Component |Status - -|Solo dialect — *language machinery* (lexer, parser, type checker, interpreter, REPL) |Complete -|Solo dialect — *runtime standard library* |In Progress (Phase 2) -|AI Runtime (mock) |Complete -|My SSG |Complete -|Duet dialect |In Development -|Ensemble dialect |Planned -|Native compiler |Planned -|=== - -[NOTE] -==== -"Complete" for the Solo dialect means the *language machinery* — lexer, parser, -type checker, tree-walking interpreter, and REPL — is feature-complete and can -run arbitrary Solo programs. - -It does *not* mean the *runtime standard library* is finished. The stdlib is -delivered as native builtins and is being filled in under Phase 2 (file I/O, -`env_args`, `format`, and string-keyed maps have landed; JSON and date -primitives are next). Live status is tracked in the GitHub issues, not in this -table — see the Phase-2 stdlib tracker (`#45`) and its sub-issues. -==== +* **Licence**: MPL-2.0. (Migrated from PMPL-1.0-or-later 2026-05-26 per + the estate licence-debt audit, hyperpolymath/standards#196.) +* **Maturity**: design-iteration. Working compiler exists; surface and + semantics still settling. Per the maintainer's memory entry + `my-lang-37-shipped-rest-parked`, item #37 has shipped and several + follow-ups (`#38-#41`) are artefact-blocked. +* **Audit findings**: see `docs/tech-debt-2026-05-26.md` if present + (added by the 2026-05-26 estate tech-debt scan). -== License +== Contributing -MPL-2.0 (Palimpsest License)—see link:LICENSE[LICENSE]. +See link:CONTRIBUTING.adoc[CONTRIBUTING.adoc] (or +link:CONTRIBUTING.md[CONTRIBUTING.md]). GPG-signed commits required. -''' +== Companion repositories -[quote] -A language that grows with you—from visual tokens to agentic ensembles. +* link:https://github.com/hyperpolymath/standards[`hyperpolymath/standards`] — canonical estate-wide standards. +* link:https://github.com/hyperpolymath/affinescript[`hyperpolymath/affinescript`] — sibling language project; differing design intent. +* link:https://github.com/hyperpolymath/typed-wasm[`hyperpolymath/typed-wasm`] — the typed-wasm backend `my-lang` shares with `affinescript`.