diff --git a/spec/CRG-PROFILE.adoc b/spec/CRG-PROFILE.adoc new file mode 100644 index 00000000..a1201396 --- /dev/null +++ b/spec/CRG-PROFILE.adoc @@ -0,0 +1,244 @@ +// SPDX-License-Identifier: PMPL-1.0-or-later +// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) + += CRG-PROFILE — AffineScript +:toc: left +:toclevels: 2 + +[cols="1,3"] +|=== +| Field | Value + +| Language | AffineScript +| Repository | https://github.com/hyperpolymath/affinescript +| Current CRG Grade | *D* (X \| F \| E \| D \| C \| B \| A) +| Assessed | 2026-05-28 +| Assessor | Jonathan D.A. Jewell +| CRG Spec Version | 2.2 +| ARG Profile | spec/ARG-PROFILE.adoc +| TRG Profile | spec/TRG-PROFILE.adoc +| FRG Profile | spec/FRG-PROFILE.adoc +|=== + +== About this profile + +This profile applies the *CRG v2.2 (STRICT)* baseline to AffineScript +released components. AffineScript ships its primary compiler binary +plus four named sub-components with their own package surfaces and +versioning. None has yet reached v1.0 or independent external-target +validation, so the worst-of-released grade is *D*. + +CRG = *D*. The full chain of axes: + +* ARG: *D* +* TRG: *E* (this is the gating axis at present; see TRG-PROFILE) +* FRG: *E* +* CRG: *D* (this profile) +* RSR: assessed elsewhere + +== Released components + +A *released component* is any unit of work this repository publishes +under its own name + version: crate, library, binary, plugin, schema, +or vendored artefact. Each is graded independently against CRG. + +The list below is the complete published surface as of 2026-05-28. + +[cols="2,1,3,4", options="header"] +|=== +| Component | Grade | Release stage | Evidence + +| `affinescript` (opam, OCaml) v0.1.1 +| *D* +| Pre-alpha +| Primary compiler driver + library. `bin/main.ml`, `lib/*.ml`. 309 e2e cases + 17 lexer cases passing. Dune build + opam package. No external-target validation. + +| `affinescript-runtime` (Rust crate) v0.1.0 +| *D* +| Pre-alpha +| `runtime/Cargo.toml`. Unpublished on crates.io. Used by `affinescript-vite` consumers. + +| `affinescript-vite` (npm) v0.1.0 +| *D* +| Pre-alpha +| `affinescript-vite/package.json`. Vite plugin for browser builds. Self-declared CRG-C at `affinescript-vite/docs/governance/CRG-CRITERIA.adoc`; this profile downgrades to D pending the v2.2 STRICT deep-annotation evidence. + +| `@affinescript/pixijs` (npm) v0.1.0 +| *D* +| Pre-alpha +| `affinescript-pixijs/package.json`. PixiJS FFI binding. No published v1.0; idaptik pilot at `idaptik` is the only known consumer. + +| `affinescriptiser` (Rust crate) v0.1.0 +| *D* +| Pre-alpha +| `affinescriptiser/Cargo.toml`. Self-declared CRG-C at `affinescriptiser/docs/governance/CRG-CRITERIA.adoc`; same downgrade rationale as `affinescript-vite`. + +| `affinescript-dom`, `affinescript-tea`, `affinescript-deno-test` +| *E* +| Pre-alpha +| Sub-projects with their own infrastructure but no own version + release semantics yet. Listed here for completeness, not graded at D. +|=== + +== Per-component evidence (deep) + +CRG §4.5+ (grade C onward) requires *deep per-file + per-directory +annotation*. The current self-claims at C for `affinescript-vite` and +`affinescriptiser` do not yet meet this clause under v2.2 STRICT. +References: + +* `affinescript-vite/docs/governance/CRG-CRITERIA.adoc` — claimed C + under earlier CRG version; needs re-audit under v2.2 STRICT +* `affinescriptiser/docs/governance/CRG-CRITERIA.adoc` — same status +* `affinescript-vite/AUDIT.adoc` — hard audit posture declaration + +For the primary `affinescript` compiler, no deep CRG audit exists yet. + +== Grade rationale + +[cols="2,1,4", options="header"] +|=== +| Grade clause (CRG §4) | Met? | Evidence + +| *E1 — At least one test exists* +| YES +| `test/test_lexer.ml` (17 cases), `test/test_e2e.ml` (309 cases over 80 fixtures), `alcotest` framework. + +| *E2 — Failures documented* +| YES +| Failures surface via `alcotest` reports; per-fixture failure modes documented in `TECH-DEBT.adoc`. + +| *D1 — Test matrix documented* +| YES +| `CAPABILITY-MATRIX.adoc` documents the per-feature × per-backend matrix surface. + +| *D2 — Scope documented* +| YES +| `README.md` + `EXPLAINME.adoc` + `TOPOLOGY.adoc` describe the project scope. + +| *D3 — RSR compliance* +| PARTIAL +| RSR baseline is present (LICENSE, CONTRIBUTING, CoC, SECURITY); RSR audit cadence + per-RSR-level evidence not yet stated. + +| *C1 — Dogfooded* +| PARTIAL +| AffineScript builds the `affinescript-vite` + `affinescript-pixijs` consumer tooling; the `idaptik` pilot uses `@affinescript/pixijs`. The compiler itself is OCaml, not AffineScript — so the project is *not yet self-hosting*. + +| *C2 — CI green* +| YES +| CI per `.github/workflows/`; greens visible at https://github.com/hyperpolymath/affinescript/actions. + +| *C3 — Deep annotation (per-file + per-dir)* +| NO +| No `audits/audit-.md` per CRG §4.5 + TRG §3. This is the gating gap. + +| *B1 — ≥6 diverse external targets* +| NO +| External target list: `idaptik` (pixijs binding) is the only known live consumer; `affinescript-vite` consumers are self-developed; no third-party adoption. + +| *B2 — Issues fed back from external use* +| NO +| Closed-issue trail has internal-reporter labels only. + +| *A1 — Confirmed real-world value, no harm* +| NO +| No external feedback corpus. + +| *VeriSimDB attestation (grade C+)* +| NO +| AffineScript is not yet `DECLARE`'d to VeriSimDB. +|=== + +== Language-specific tightening (this profile only) + +For AffineScript, the following additional CRG obligations apply at +the stated grades: + +* *Grade C tightening:* The stdlib `stdlib/` (24 modules) MUST have a + per-module audit document, *and* every released wrapper module + (`affinescript-vite`, `affinescript-pixijs`) MUST have a borrow-check + fixture suite covering the typical use cases. +* *Grade B tightening:* `affinescript` MUST be self-hosting (the + compiler driver MUST be written in AffineScript), OR a published + rationale MUST explain why OCaml is the strategic implementation + language indefinitely. +* *Grade A tightening:* Registered VeriSimDB instance + public health + check + at least one third-party-maintained release of an + AffineScript library. + +These tightenings are *additional* to the baseline — none of the +baseline evidence is waived. + +== What is NOT yet met (honest gaps) + +* *No deep per-component CRG audit*. Each released component needs + its own `audits/audit-.md`. +* *Self-hosting status undecided*. AffineScript is implemented in + OCaml + Rust; this is fine for grade D but blocks the language- + specific B tightening above. +* *No published downstream consumers* beyond first-party tooling. + ARG-C and CRG-C both stall on this clause without a credible + external adoption story. +* *VeriSimDB attestation absent*. Needed for grade C onward. + +== Path to next grade (*C*) + +* Write `audits/audit-affinescript.md` covering the compiler driver, + with per-file CRG v2.2 STRICT annotations. (~2-3 weeks) +* Write per-sub-component audits for `affinescript-runtime`, + `affinescript-vite`, `@affinescript/pixijs`, `affinescriptiser`. + Re-audit the existing C-claims under v2.2 STRICT — either + promote to C with the new evidence or document the residual gaps. + (~3-4 weeks) +* Land VeriSimDB attestation for AffineScript. (~1 week given + VeriSimDB infrastructure is in place) +* Land RSR-level statement (gate for D3 hardening). + +*Realistic timeline estimate:* 6-8 weeks from current state. + +== Path to grade beyond that (*B*) + +* Sustain ≥6 diverse external targets (third-party libraries, + applications, or bindings). The `idaptik` pilot is one; the + AffineScript bindings roadmap (`docs/bindings-roadmap.adoc`) + enumerates the candidate surfaces. +* Establish issue-feedback pipeline with external reporters. +* Either become self-hosting (B-tightening above) or publish the + rationale for OCaml strategic implementation. + +*Realistic timeline estimate:* 6-12 months from C. + +== Demotion risk + +* *Lowest:* A single released sub-component (e.g. `affinescript-vite`) + CI flips to red and stays red across a release window. +* *Medium:* Test corpus regresses (e.g. `test_e2e.ml` pass-count + drops below historical floor without compensating new coverage). +* *Catastrophic:* A released component found to cause harm in a + consumer project — would force F. + +== Iteration history + +[cols="1,1,4", options="header"] +|=== +| Date | Grade | Notes + +| 2026-05-28 | D | Initial CRG-PROFILE per CRG v2.2 STRICT. Two sub-components (`affinescript-vite`, `affinescriptiser`) have prior self-declared C; this profile downgrades to D pending v2.2 STRICT deep-annotation evidence. +|=== + +== Review cycle + +* *Routine:* Reassess on every release cycle (per CRG §6.3). +* *Immediate:* Reassess within 7 days of any released-component + regression. +* *VeriSimDB drift alert:* Reassess within 24 hours of any drift + alert from VeriSimDB on this language's released components. + +== Footer + +Run `just crg-badge` in this repo to generate the shields.io badge +for the README. + +This profile is itself a VCL-total proposition. Its content is +`DECLARE`'d to VeriSimDB on each commit. Drift between the claimed +grade above and the underlying evidence surfaces as a grade-stale +alert. diff --git a/spec/TRG-PROFILE.adoc b/spec/TRG-PROFILE.adoc new file mode 100644 index 00000000..8f68a26c --- /dev/null +++ b/spec/TRG-PROFILE.adoc @@ -0,0 +1,226 @@ +// SPDX-License-Identifier: PMPL-1.0-or-later +// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) + += TRG-PROFILE — AffineScript +:toc: left +:toclevels: 2 + +[cols="1,3"] +|=== +| Field | Value + +| Language | AffineScript +| Repository | https://github.com/hyperpolymath/affinescript +| Current TRG Grade | *E* (X \| F \| E \| D \| C \| B \| A) +| Assessed | 2026-05-28 +| Assessor | Jonathan D.A. Jewell +| TRG Spec Version | 1.0 +| ARG Profile | spec/ARG-PROFILE.adoc +| FRG Profile | spec/FRG-PROFILE.adoc +| CRG Profile | spec/CRG-PROFILE.adoc +|=== + +== About this profile + +This profile applies the *TRG v1.0* baseline to AffineScript. The +working toolchain is substantial — OCaml/Menhir compiler with ~23 +backends, REPL, LSP subset, ~309 end-to-end test cases, sublanguage +toolchain `affinescriptiser`, integration crates (`affinescript-runtime`, +`affinescript-vite`, `@affinescript/pixijs`) — but several MUST +components per TRG §3 are *absent or undocumented as canonical +artefacts*, which gates the overall grade at *E*. Specifically: + +* M5 *operational/denotational semantics document* is scattered across + TECH-DEBT.adoc + CAPABILITY-MATRIX.adoc with no canonical file. +* B1 *intermediate representation* is implicit (AST lowering to WASM + bytecode); no documented IR-format SoT with invariants. +* T4 *formatter* exists as a stubbed `formatter.ml` with the `.mli` + disabled — not production-ready. +* T9 *pipeline orchestrator* runs implicitly through dune build rules; + no discrete orchestrator artefact. + +The chain of axes: + +* ARG: *D* (pragmatic — working compiler, narrow adopter base) +* TRG: *E* (this profile) +* FRG: *E* (no mechanised proofs; design rationale documented) +* CRG: *D* (per spec/CRG-PROFILE.adoc; no released v1.0 components) +* RSR: assessed elsewhere + +Cross-axis rule: ARG ≤ TRG holds (TRG = E ⇒ ARG ≤ E; current ARG-D +is *over* the floor and is sustainable until grade C is sought — +ARG-C would require TRG ≥ C per ARG §1.1). + +== Component grades + +The toolchain decomposes into components drawn from TRG §3. Each +component is graded independently against the four-tier audit format +of TRG §4 (Must / Should / Could / Aspirational → grades E / D / C / B). +The overall TRG grade is the *worst* of any MUST component. + +=== Front-end (TRG §3.1) + +[cols="1,3,1,4", options="header"] +|=== +| # | Component | Grade | Evidence + +| F1 | Grammar / Syntax | *D* | `lib/parser.mly` (Menhir grammar, functional SoT). No standalone `.ebnf` / `.pest` / `.peg` artefact — Menhir is itself the SoT; gating to grade C requires extracting an audit-friendly `.ebnf` view. +| F2 | Lexer / Tokeniser | *C* | `lib/lexer.ml` (sedlex). `test/test_lexer.ml` — 17 dedicated lexer tests. +| F3 | Parser | *C* | Menhir-generated from `parser.mly`. `test/test_e2e.ml` — 309+ end-to-end cases across 80 fixtures. +| F4 | AST | *C* | `lib/ast.ml` (~10.7K lines, comprehensive variant types). Invariants ad-hoc in comments; no separate invariants doc. +| F5 | Macro expander | N/A | AffineScript has no macros. +| F6 | Import resolver / Modules | *D* | `lib/module_loader.ml`. No explicit cycle-detection regression suite. +| F7 | Diagnostics / Errors | *C* | `lib/error.ml`, `lib/error_formatter.ml`. Structured JSON-output mode supported. +|=== + +=== Middle-end (TRG §3.2) + +[cols="1,3,1,4", options="header"] +|=== +| # | Component | Grade | Evidence + +| M1 | Semantic analyser | *C* | `lib/resolve.ml`. Name resolution + scoping. Covered by `test_e2e.ml`. +| M2 | Type checker | *C* | `lib/typecheck.ml` (~76.5K lines, bidirectional H-M-style with unification). Covered by extensive e2e suite. +| M3 | Type-checker oracle | N/A | AffineScript is not a verified language (no proof obligations bound to a prover); see FRG-PROFILE.adoc. +| M4 | Proof dispatcher | N/A | Same reason as M3. +| M5 | Semantics document | *E* | Scattered across TECH-DEBT.adoc + CAPABILITY-MATRIX.adoc; *no canonical semantics document*. This is the load-bearing TRG-baseline gap. +|=== + +=== Back-end (TRG §3.3) + +[cols="1,3,1,4", options="header"] +|=== +| # | Component | Grade | Evidence + +| B1 | Intermediate representation | *E* | Implicit lowering: AST → backend-specific output. *No explicit IR with documented invariants*. Gates the overall grade. +| B2 | Code generator (per backend) | *D* | `lib/codegen.ml` (~120K lines, primary WASM target); plus per-backend modules: C, CUDA, FAUST, Gleam, Julia, Lean, LLVM, Lua, Metal, MLIR, Nickel, OCaml, ONNX, OpenCL, Protobuf, ReScript, Rust, SPIR-V, Verilog, WGSL, Why3, Bash, Deno, Node, GC. WASM is well-tested; the 22+ minor targets vary widely in coverage. +| B3 | Backend registry | *D* | `lib/backends.ml`. Registry exists; backend-conformance test corpus is partial. +| B4 | Linker / JIT / eval | *C* | `lib/wasm_encode.ml`, `lib/wasm_gc_encode.ml`. WASM binary encoding well-exercised by e2e suite. +| B5 | ABI / FFI surface | *D* | Multiple FFI modules: `cafe_face.ml`, `js_face.ml`, `python_face.ml`, etc. Sub-projects `affinescript-pixijs`, `affinescript-vite` (with Zig FFI in `ffi/zig/src/`). Idris2 ABI surface not yet declared. +| B6 | Runtime | *D* | `lib/wasi_runtime.ml` + Rust crate `affinescript-runtime` (`runtime/Cargo.toml`, v0.1.0). +|=== + +=== Tool surface (TRG §3.4) + +[cols="1,3,1,4", options="header"] +|=== +| # | Component | Grade | Evidence + +| T1 | Compiler driver | *C* | `bin/main.ml` (~86.8K lines). Subcommands: `lex`, `parse`, `check`, `eval`, `verify`, `interface`, `verify-boundary`, `repl`, `tea-bridge`, `router-bridge`, `cs-bridge`. +| T2 | Interpreter | *C* | `lib/interp.ml` (~42.6K lines). Tree-walk interpreter, exercised by `test_e2e.ml`. +| T3 | REPL | *D* | `lib/repl.ml`. Smoke-test coverage exists; no LSP-grade integration tests. +| T4 | Formatter | *X* | `lib/formatter.ml` is a stub; `.mli.disabled` excludes it from the public interface. Not production-ready. +| T5 | LSP server | *D* | `lib/lsp_server.ml`. LSP 3.17 subset (hover, definition, completion, diagnostics). Invoked as `affinescript server --stdio`. +| T6 | Debugger | N/A | Absent. SHOULD per TRG §3.4; not blocking grade E. +| T7 | Package manager | *D* | No bespoke package manager; relies on opam (OCaml), npm (`affinescript-vite`, `@affinescript/pixijs`), Cargo (`affinescript-runtime`, `affinescriptiser`). +| T8 | Standard library | *C* | `stdlib/` — 24 modules: Core, Result, Collections, Dict, Effects, Grammar, Http, IO, JSON, Math, Network, Option, Prelude, String, Testing, Traits, plus external bindings (Ajv, Crypto, Deno, Sqlite, Vscode). +| T9 | Pipeline orchestrator | *D* | Implicit via dune + Justfile recipes; no discrete pipeline-orchestrator artefact. +|=== + +== Language-specific tightening (this profile only) + +TRG §1.1 permits per-language tightening. For AffineScript, the +following additional obligations apply at the stated grades: + +* *Grade D tightening:* Type checker MUST reject every test case in + the borrow-check + affinity test fixtures (currently in + `test/test_e2e.ml`); regression on any rejection is a MUST-row + failure. +* *Grade C tightening:* The 23-backend matrix MUST have a published + conformance report listing pass/fail per backend per fixture; today + only WASM has full coverage, with the others ranging D-X. +* *Grade B tightening:* AffineScript MUST publish a paradigm + conformance document showing borrow-check coverage of at least + one canonical type-system surface (e.g. Rust's NLL test corpus or + equivalent). + +These tightenings are *additional* to the baseline — none of the +baseline evidence is waived. + +== Canonical Proof Suite extension + +N/A. AffineScript is not a verified language at the TRG-baseline level +(see M3/M4 above). FRG = E reflects the same status. A future verified +profile (e.g. AffineScript-Verified) would extend this section. + +== What is NOT yet met (honest gaps) + +Gating gaps for grade *D*: + +* *M5 canonical semantics document* — operational and denotational + semantics scattered across TECH-DEBT + CAPABILITY-MATRIX; no + `docs/semantics.adoc`. Required at baseline grade E. +* *B1 explicit IR* — no documented IR format with invariants. Implicit + AST-direct-to-backend lowering. Required at baseline grade E. +* *T4 formatter* — `formatter.ml` stubbed; either complete the + formatter or formally drop the SHOULD by declaring T4 absent with + justification per TRG §3. + +Gating gaps for grade *C* (assuming D is reached): + +* Backend conformance matrix not published. +* No per-backend audit documents under `audits/audit-codegen-*.md`. +* AST invariants not extracted into a separate doc. +* No published proof-suite extension. + +== Path to next grade (*D*) + +* Write `docs/semantics.adoc` consolidating the scattered semantics + prose into one canonical operational + denotational document. + (~1-2 weeks) +* Extract or document the implicit IR: name it (`AscIr`?), describe + its invariants, ship a `docs/ir.adoc`. (~1-2 weeks) +* Decide T4: either ship the formatter (~3-4 weeks) or document the + absence per TRG §3. + +*Realistic timeline estimate:* 4-6 weeks once prioritised. + +== Path to grade beyond that (*C*) + +* Publish per-backend conformance report covering all 22+ codegen + targets. +* Author per-component audit documents under `audits/`. +* Lift `test_e2e.ml` from a monolithic test file into per-component + audit-aligned test buckets. +* Achieve dogfooding: AffineScript MUST be used as the primary + language for at least one downstream artefact (the existing + `affinescript-vite` + `affinescript-pixijs` qualifies, but needs + AUDIT.adoc updates). + +*Realistic timeline estimate:* 3-6 months from D. + +== Demotion risk + +* *Lowest:* WASM backend regression flag flips to red, dropping B2 to + X for the load-bearing backend. +* *Medium:* Type-checker unsoundness found that the 309 e2e cases + don't catch, dropping M2 to D. +* *Catastrophic:* Bidirectional H-M unification found to be unsound, + dropping M2 to X and the toolchain to X. + +== Iteration history + +[cols="1,1,4", options="header"] +|=== +| Date | Grade | Notes + +| 2026-05-28 | E | Initial TRG assessment per TRG v1.0. Gating items: M5 absent, B1 implicit, T4 stubbed. +|=== + +== Review cycle + +* *Routine:* Reassess on every release cycle (per TRG §8). +* *Immediate:* Reassess within 7 days of any MUST-component + regression. +* *VeriSimDB drift alert:* Reassess within 24 hours of any drift + alert from VeriSimDB on this toolchain's attestations. + +== Footer + +Run `just trg-badge` in this repo to generate the shields.io badge for +the README. + +This profile is itself a VCL-total proposition. Its content is +`DECLARE`'d to VeriSimDB on each commit. Drift between the claimed +grade above and the underlying evidence surfaces as a grade-stale +alert.