Skip to content

Commit 9851215

Browse files
docs(faces): record established faces and same-cube grounding
## What Docs-only. Fixes staleness in `docs/specs/faces.adoc` surfaced while grounding the faces work, and records the grounded same-cube finding. ## Changes - **Active Faces table** now includes **LucidScript** (PureScript/Haskell) and **CafeScripto** (CoffeeScript) — both ship as established faces (`lib/lucid_face.ml`, `lib/cafe_face.ml`; see `examples/faces/README.adoc` and the brand repos), but the table previously listed only Canonical/Python/JS/Pseudocode. - **CoffeeScript-face** retitled from "Roadmap (strategic priority)" to **SHIPPED as CafeScripto** (design notes kept as history); only **ActionScript-face** remains on the roadmap. - New **Brand-surface repos** table (face → brand repo → transformer). - New **Same-cube grounding** section recording `invariant-path`'s `verify-same-cube.sh` + the grounded result. ## The grounded finding (worth a transformer-consistency issue) Built the compiler and ran the verifier (457-test suite green, per-face snapshot net 6/6 green). On the `greet` corpus the six faces compile to **two** wasm modules — `{canonical, jaffa, cafe}` vs `{rattle, pseudo, lucid}` — because the transformers disagree on **trailing-statement lowering** (statement `{ println(x); }` vs tail-expression `{ println(x) }`). Observationally identical, **not byte-identical wasm**. Making the transformers agree would give byte-level same-cube. (Informational: the verifier upgrade lives in `hyperpolymath/invariant-path#33`.) 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01KPG9mEQXFyA3k7NWAzMNMr --- _Generated by [Claude Code](https://claude.ai/code/session_01KPG9mEQXFyA3k7NWAzMNMr)_
1 parent 58dc2a0 commit 9851215

1 file changed

Lines changed: 54 additions & 4 deletions

File tree

docs/specs/faces.adoc

Lines changed: 54 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
// SPDX-License-Identifier: MPL-2.0
22
// SPDX-FileCopyrightText: 2024-2026 Jonathan D.A. Jewell (hyperpolymath)
33
= AffineScript Faces — Design & Implementation Reference
4+
Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
45
:toc: macro
56
:toclevels: 2
67
:source-highlighter: rouge
@@ -71,15 +72,64 @@ The compiler is face-agnostic throughout. The two face-aware layers are:
7172
| `--face pseudocode` or `--face pseudo`
7273
| `.pseudoaff`
7374
| Beta (2026-04-11)
75+
76+
| Lucid (PureScript / Haskell)
77+
| `--face lucid`
78+
| `.lucidaff`
79+
| Beta (2026-06)
80+
81+
| Cafe (CoffeeScript)
82+
| `--face cafe` or `--face coffee`
83+
| `.cafeaff`
84+
| Beta (2026-06)
85+
|===
86+
87+
=== Brand-surface repos
88+
89+
Each non-canonical face has a brand-surface repo — examples, community docs,
90+
migration guides, and a `bin/<face>` shim that injects `--face`. The compiler,
91+
type checker, borrow checker, and codegen live only here in affinescript; the
92+
brand repos carry no compiler.
93+
94+
[cols="1,2,2", options="header"]
7495
|===
96+
| Face | Brand repo | Transformer
97+
98+
| RattleScript (Python) | `hyperpolymath/rattlescript` | `lib/python_face.ml`
99+
| JaffaScript (JS / TS) | `hyperpolymath/jaffascript` | `lib/js_face.ml`
100+
| PseudoScript (pseudocode) | `hyperpolymath/pseudoscript` | `lib/pseudocode_face.ml`
101+
| LucidScript (PureScript) | `hyperpolymath/lucidscript` | `lib/lucid_face.ml`
102+
| CafeScripto (CoffeeScript) | `hyperpolymath/cafescripto` | `lib/cafe_face.ml`
103+
|===
104+
105+
=== Same-cube grounding
106+
107+
The "different faces, same cube" claim is grounded by
108+
`hyperpolymath/invariant-path` (the `faces` profile + `scripts/verify-same-cube.sh`),
109+
which compiles one program written in every face to typed-wasm and compares the
110+
modules. Per-face snapshot stability is covered separately by
111+
`tools/run_face_transformer_tests.sh` (currently 6/6 green).
112+
113+
*Known transformer-consistency item (grounded 2026-06-18):* on the `greet`
114+
corpus the six faces compile to *two* wasm modules — `{canonical, jaffa, cafe}`
115+
vs `{rattle, pseudo, lucid}` — because the transformers disagree on
116+
trailing-statement lowering (statement `{ println(x); }` vs tail-expression
117+
`{ println(x) }`). The programs are observationally identical (same output,
118+
same unit return) but the wasm is not byte-identical. Making the transformers
119+
agree on trailing-statement lowering would yield byte-level same-cube.
75120

76121
== Roadmap Faces
77122

78-
These faces are on the roadmap but have not been designed in detail. The
79-
face architecture makes implementation cheap once the surface mapping is
80-
settled; the bottleneck is design, not code.
123+
ActionScript-face remains on the roadmap (CoffeeScript has since shipped as
124+
CafeScripto — see Active Faces above). The face architecture makes
125+
implementation cheap once the surface mapping is settled; the bottleneck is
126+
design, not code.
127+
128+
=== CoffeeScript-face — SHIPPED as CafeScripto
81129

82-
=== CoffeeScript-face (strategic priority)
130+
NOTE: This face is now *established* (`lib/cafe_face.ml`, `--face cafe`; see the
131+
Active Faces table and `hyperpolymath/cafescripto`). The design notes below are
132+
retained as historical reference; only ActionScript-face remains on the roadmap.
83133

84134
*Rationale:* CoffeeScript has a loyal displaced community that never loved
85135
JavaScript and were forced away when the ecosystem moved on. Their syntax

0 commit comments

Comments
 (0)