|
1 | 1 | # SPDX-License-Identifier: MPL-2.0 |
2 | 2 | # META.a2ml — Project meta-information |
3 | | -# Converted from META.scm on 2026-03-15 |
| 3 | +# Converted from META.scm on 2026-03-15; enriched 2026-06-12. |
| 4 | +# Architecture decisions, design rationale, governance. |
4 | 5 |
|
5 | 6 | [metadata] |
6 | 7 | project = "wokelang" |
7 | 8 | author = "Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>" |
8 | 9 | license = "MPL-2.0" |
9 | 10 | standard = "RSR 2026" |
| 11 | +version = "0.1.0" |
| 12 | +last-updated = "2026-06-12" |
| 13 | + |
| 14 | +[project-info] |
| 15 | +type = "monorepo" # library | binary | monorepo | service | website |
| 16 | +tagline = "A human-centered, consent-driven programming language" |
| 17 | +languages = ["rust", "ocaml"] |
| 18 | +primary-language = "rust" |
| 19 | + |
| 20 | +[implementation] |
| 21 | +primary = "Rust toolchain in src/" |
| 22 | +rust-components = "lexer, parser, typechecker, bytecode VM (compiler + machine), tree-walking interpreter, LSP (woke-lsp), DAP (woke-dap), formatter, linter, REPL, stdlib, codegen, ABI/FFI, security" |
| 23 | +rust-lib-tests = "173 passing" |
| 24 | +binaries = "woke, woke-lsp, woke-dap" |
| 25 | +ocaml-core = "core/ reference implementation: ocamllex lexer + menhir parser + evaluator (dune)" |
| 26 | + |
| 27 | +[architecture-decisions] |
| 28 | +adrs = [ |
| 29 | + { id = "ADR-001", title = "Rust is the primary toolchain; OCaml core is the reference", status = "accepted", date = "2026-03-15", |
| 30 | + rationale = "The production toolchain (lexer, parser, typechecker, VM, interpreter, LSP, DAP, tooling) is implemented in Rust under src/. A smaller OCaml implementation in core/ (ocamllex + menhir + evaluator) serves as an independent reference for the language semantics and an end-to-end cross-check. Both are first-class; the OCaml core grounds the e2e CI gate." }, |
| 31 | + { id = "ADR-002", title = "Consent / affine safety is the defining language feature", status = "accepted", date = "2026-03-15", |
| 32 | + rationale = "wokelang is human-centered and consent-driven: the type system discharges consent and affine-use obligations so users never reason about them manually. This is the architectural invariant the whole toolchain serves." }, |
| 33 | + { id = "ADR-003", title = "Echo types are the formal substrate for consent / affine safety", status = "accepted", date = "2026-06-12", |
| 34 | + rationale = "wokelang consumes hyperpolymath/echo-types (constructive Agda formalization of fiber-based structured loss) as the source of truth for the loss / consent reasoning. The frontier workstream integrates echo types into the typechecker, with an end-to-end, near-first-principles machine-checked proof narrative (Isabelle preferred) backing it." }, |
| 35 | + { id = "ADR-004", title = "Hyperpolymath Standard governance via thin-wrapper reusables", status = "accepted", date = "2026-06-12", |
| 36 | + rationale = "CI is 20 GitHub Actions workflows built on thin-wrapper reusable workflows from hyperpolymath/standards, plus a dogfooding gate (a2ml / k9 / empty-lint / groove / eclexiaiser), clusterfuzzlite fuzzing, and a hypatia security scan. Machine state lives only under .machine_readable/ (never the repo root)." }, |
| 37 | +] |
| 38 | + |
| 39 | +[development-practices] |
| 40 | +build-tool = "just" # Justfile at repo root; contractile.just for contracts |
| 41 | +rust-build = "cargo" |
| 42 | +ocaml-build = "dune" |
| 43 | +container-runtime = "podman" # Containerfile present |
| 44 | +ci-platform = "github-actions" |
| 45 | +package-manager = "guix" # guix.scm primary; flake.nix fallback |
| 46 | + |
| 47 | +[maintenance-axes] |
| 48 | +scoping-first = true |
| 49 | +execution-order = "axis-1 > axis-2 > axis-3" |
| 50 | +axis-1 = "must > intend > like" |
| 51 | +axis-2 = "corrective > adaptive > perfective" |
| 52 | +axis-3 = "systems > compliance > effects" |
| 53 | + |
| 54 | +[scoping] |
| 55 | +sources = "README, ROADMAP, status docs, maintenance checklist, CI/security docs" |
| 56 | +marker-scan = "TODO/FIXME/XXX/HACK/STUB/PARTIAL" |
| 57 | +proof-escape-scan = "believe_me/assert_total/sorry/Admitted/unsafeCoerce/Obj.magic" |
| 58 | + |
| 59 | +[axis-2-maintenance-rules] |
| 60 | +corrective-first = true |
| 61 | +adaptive-second = true |
| 62 | +adaptive-focus = "scope-change reconciliation, stale-reference removal, obsolete-work culling" |
| 63 | +perfective-third = true |
| 64 | +perfective-source = "axis-1 honest state after corrective/adaptive updates" |
| 65 | + |
| 66 | +[axis-3-audit-rules] |
| 67 | +audit-focus = "systems in place, documentation explains actual state, consent/affine-safety and security accounted for, observed effects reviewed" |
| 68 | +compliance-focus = "seams/compromises/exception register, bounded exceptions, anti-drift checks" |
| 69 | +drift-risk-example = "a single banned-language exception (e.g. ReScript/TypeScript) broadening into a policy violation" |
| 70 | +effects-evidence = "test-suite execution/results (Rust + OCaml e2e) and maintainer status dialogue/review" |
| 71 | + |
| 72 | +[design-rationale] |
| 73 | +summary = [ |
| 74 | + "wokelang is a human-centered, consent-driven language: the type system does the hard consent/affine-safety reasoning so users never have to.", |
| 75 | + "Rust under src/ is the production toolchain; the OCaml core/ is the independent reference implementation and e2e cross-check.", |
| 76 | + "Echo types (hyperpolymath/echo-types) are the formal substrate; the frontier is integrating them into the typechecker with a machine-checked Isabelle proof narrative.", |
| 77 | + "Governance follows the Hyperpolymath Standard: MPL-2.0, allowed/banned language policy, dogfooding gate, and machine state confined to .machine_readable/.", |
| 78 | +] |
0 commit comments