feat(faces): add Lucid + Cafe faces, unify on .affine + face pragma

Adds two new faces — LucidScript (PureScript-style) and CafeScripto
(CoffeeScript-style) — alongside the established Canonical / Rattle /
Jaffa / Pseudo. Every face shares the .affine extension and is
selected by an in-file `face:` pragma (or --face flag); deprecated
per-face extensions still work with a stderr warning.

- lib/face_pragma.ml: pragma detector covering all six brand names
  and their generic aliases.
- lib/lucid_face.ml, lib/cafe_face.ml: text transformers at parity
  depth with python_face / js_face / pseudocode_face.
- lib/face.ml: Lucid + Cafe variants plus error-vocabulary branches
  across all six format_*_for_face functions.
- bin/main.ml: parse_with_face, face_arg, fmt_file, preview-* cmds
  extended; resolve_face now does pragma-first dispatch.
- examples/faces/, tests/faces/, tools/run_face_transformer_tests.sh:
  six demo files, snapshot regression test, justfile recipes, and a
  CI step that catches transformer drift.
- README.adoc: face listing now names all six.

Known transformer gaps (each face's example sidesteps these and the
examples/faces/README.adoc tracks them) are deferred follow-up.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

.github/workflows/ci.yml

@@ -40,6 +40,9 @@ jobs:
       - name: Run codegen WASM tests
         run: opam exec -- ./tools/run_codegen_wasm_tests.sh
 
+      - name: Run face-transformer regression tests
+        run: opam exec -- ./tools/run_face_transformer_tests.sh
+
       - name: Check formatting
         run: opam exec -- dune build @fmt
 

README.adoc

@@ -76,12 +76,16 @@ On top of that core, the language supports _faces_: sugared surface syntaxes tha
 
 A face is not a separate language. It is a different presentation layer over the same core model.
 
-Examples include:
+The established faces are:
 
 - *AffineScript* — the canonical face
-- *JaffaScript* — a JavaScript-like face
-- *RattleScript* — a Python-like face
-- *PseudoScript* — a pseudocode-oriented face
+- *JaffaScript* — a JavaScript / TypeScript-like face
+- *RattleScript* — a Python-like face (also positioned as "Python for the web" via typed-wasm)
+- *PseudoScript* — a pseudocode-oriented face for CS pedagogy
+- *LucidScript* — a PureScript / Haskell-like face
+- *CafeScripto* — a CoffeeScript-like face
+
+Every face shares the canonical `.affine` file extension; the active face is selected by an optional `face:` pragma on the first comment line of the file (e.g. `# face: rattlescript`, `// face: jaffascript`, `-- face: lucidscript`), or by `--face NAME` on the CLI.
 
 This means people can bring familiarity from a language family they already love, while still entering a system with stronger guarantees around ownership, effects, state, and resource usage.
 
@@ -312,11 +316,15 @@ face syntax  ->  AffineScript core AST  ->  type/effect/ownership checks  ->  ba
 
 Examples:
 
-- JaffaScript lowers JavaScript-like syntax into the AffineScript core
+- JaffaScript lowers JavaScript / TypeScript-like syntax into the AffineScript core
 - RattleScript lowers Python-like syntax into the same core
 - PseudoScript lowers structured pedagogical pseudocode into the same core
+- LucidScript lowers PureScript / Haskell-like syntax into the same core
+- CafeScripto lowers CoffeeScript-like syntax into the same core
+
+Side-by-side examples for each face live under `examples/faces/`; you can preview the canonical lowering of any file with `affinescript preview-python` / `preview-js` / `preview-pseudocode` / `preview-lucid` / `preview-cafe`.
 
-So the question is not “which face is the real language?”  
+So the question is not “which face is the real language?”
 The answer is: the core semantics are the language; faces are entrances.
 
 == Backends and Targets

bin/main.ml

@@ -0,0 +1,116 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell
+
+= Faces — Different Surfaces, Same Cube
+
+This directory contains the same logical "hello" program written once in each of the six established AffineScript faces. Every file:
+
+* uses the canonical `.affine` extension,
+* declares its face with a pragma on the first non-blank comment line (`# face: …`, `// face: …`, or `-- face: …`),
+* compiles to the same canonical AST and the same typed-wasm output.
+
+== The six files
+
+[cols="1,2,3"]
+|===
+| File | Face | Demonstrates
+
+| `hello-canonical.affine`
+| AffineScript (canonical)
+| The reference syntax — all other faces lower to this shape.
+
+| `hello-rattle.affine`
+| RattleScript (Python)
+| `def`, indentation blocks, `#` comments, `True`/`False`/`None`, `and`/`or`/`not`, `import a.b`.
+
+| `hello-jaffa.affine`
+| JaffaScript (JavaScript / TypeScript)
+| `function`, `const`/`let`, `import { x } from "m"`, `null`/`undefined`, `===`/`!==`.
+
+| `hello-pseudo.affine`
+| PseudoScript (pseudocode)
+| `function … do … end`, `set X to Y`, `output X`, `is`/`is not`, `yes`/`no`, `and`/`or`.
+
+| `hello-lucid.affine`
+| LucidScript (PureScript / Haskell)
+| `module … where`, dotted imports with `(name)` lists, `name :: Type` signatures, equation-style `f x = …`, `\x -> …` lambdas, `--` comments.
+
+| `hello-cafe.affine`
+| CafeScripto (CoffeeScript)
+| `#` and `###` comments, `->` / `=>` arrows, `@` shorthand, `unless`/`until`, postfix-if, `Yes`/`No`/`On`/`Off`.
+|===
+
+== See the lowering
+
+The `preview-*` debug commands run a face through its transformer and print the canonical AffineScript text it produces — no parsing, no type-checking, just the string-to-string transform.
+
+[source,bash]
+----
+# Show how RattleScript lowers
+affinescript preview-python  examples/faces/hello-rattle.affine
+
+# Show how JaffaScript lowers
+affinescript preview-js      examples/faces/hello-jaffa.affine
+
+# Show how PseudoScript lowers
+affinescript preview-pseudocode examples/faces/hello-pseudo.affine
+
+# Show how LucidScript lowers
+affinescript preview-lucid   examples/faces/hello-lucid.affine
+
+# Show how CafeScripto lowers
+affinescript preview-cafe    examples/faces/hello-cafe.affine
+----
+
+The output of each `preview-*` command is the same logical program in canonical AffineScript syntax, modulo whitespace and comment placement. Diffing two previews is a good way to see what each transformer actually does.
+
+== Parse-only verification
+
+To confirm a face file lowers to syntactically valid canonical AffineScript:
+
+[source,bash]
+----
+affinescript parse examples/faces/hello-rattle.affine
+----
+
+(The face is auto-detected from the pragma; pass `--face NAME` to force a specific face.)
+
+== Caveats
+
+* These examples demonstrate *surface syntax*. They are written to round-trip through their respective transformers (preview → canonical → parse) so the regression test in `tests/faces/` can catch drift, not to be full type-correct, runnable programs. That depends on what's in scope from `stdlib/`.
+* Span fidelity: error messages from non-canonical faces refer to the canonical-text form (post-transform), not the original face source. This is a known limitation of all face transformers, including the original three.
+* The examples deliberately avoid features each transformer can't yet handle. Known transformer gaps that the simpler examples sidestep:
++
+[cols="1,3"]
+|===
+| Face | Pending transformer work
+
+| Python (Rattle)
+| Bare assignment `x = y` is not yet auto-lifted to `let x = y` (the example uses explicit `let`); `import a.b` lowering does not produce the canonical `use a::b::{…};` brace form.
+
+| JS (Jaffa)
+| `import { x } from "module";` lowering has a string-stripping bug when the trailing `;` is present (the example avoids `import` entirely for now).
+
+| Pseudocode (Pseudo)
+| No automatic `;` between non-tail statements — examples use single-statement function bodies. Token substitutions can bleed into comment text (e.g. `or` → `\|\|` inside a `//` comment). `output X` lowers to `IO.println(X)` rather than canonical `println(X)`.
+
+| Lucid (PureScript)
+| Haskell-style currying calls `f x` are NOT converted to canonical `f(x)` — the example uses canonical paren syntax. Multi-clause definitions, `do`-notation, and `where`-block hoisting are deferred to AST-level rewrites.
+
+| Cafe (CoffeeScript)
+| List comprehensions, no-paren calls, splat / destructuring, and string interpolation are deferred to AST-level rewrites.
+|===
++
+These gaps are tracked as follow-up work; the regression test in this directory will catch drift in *what does work today*, and additional examples can be added once the corresponding transformer feature lands.
+
+== Adding a new face
+
+The architecture (ADR-010) makes adding a face mechanical:
+
+1. Add a variant to `lib/face.ml`'s `face` type.
+2. Write a `lib/<name>_face.ml` text transformer (model on `python_face.ml`, `js_face.ml`, `pseudocode_face.ml`, `lucid_face.ml`, or `cafe_face.ml`).
+3. Add error-vocabulary branches in `lib/face.ml`'s six `format_*_for_face` functions.
+4. Register in `bin/main.ml`: `parse_with_face` arm, `face_arg` enum entry, optional `preview-*` debug command.
+5. Add name aliases to `lib/face_pragma.ml`.
+
+No compiler internals change: the transformer outputs canonical text, which the existing pipeline (resolve → typecheck → borrow → quantity → codegen → tw_verify) processes unchanged.

examples/faces/README.adoc

@@ -0,0 +1,23 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell
+#
+# CafeScripto face. Distinctive features exercised: `#` line comments,
+# `###` block comments, paren-arrow `(args) -> body`, bare-arrow `-> body`,
+# Yes/No/On/Off literal aliases.
+# face: cafescripto
+
+###
+  All other CoffeeScript surface conveniences — postfix-if, @ shorthand,
+  `unless`/`until`, list comprehensions, no-paren calls — are documented
+  in examples/faces/README.adoc with their current support status.
+###
+
+effect IO {
+  fn println(s: String) -> ();
+}
+
+fn main() -{IO}-> () {
+  let greeting = "Hello, CafeScripto!";
+  let ready = Yes;
+  println(greeting);
+}

examples/faces/hello-cafe.affine

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell
+//
+// Canonical face — the AffineScript reference syntax. All other faces in
+// this directory lower to this same shape via their respective transformers.
+// face: canonical
+
+effect IO {
+  fn println(s: String) -> ();
+}
+
+fn main() -{IO}-> () {
+  let greeting = "Hello, AffineScript!";
+  println(greeting);
+}

examples/faces/hello-canonical.affine

@@ -0,0 +1,16 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell
+//
+// JaffaScript face. Distinctive features exercised: `function` keyword,
+// `const`/`let` bindings (let lowers to let mut), brace-delimited
+// blocks, `===` equality.
+// face: jaffascript
+
+effect IO {
+  fn println(s: String) -> ();
+}
+
+function main() -{IO}-> () {
+  const greeting = "Hello, JaffaScript!";
+  println(greeting);
+}

examples/faces/hello-jaffa.affine

@@ -0,0 +1,19 @@
+-- SPDX-License-Identifier: AGPL-3.0-or-later
+-- SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell
+--
+-- LucidScript face. Distinctive features exercised: module declaration
+-- with `where`, type signatures kept as comments, equation-style
+-- function definitions, `--` line comments. (The unit-parameter idiom
+-- `main () = …` lowers to canonical `fn main() { … }`. Function
+-- application uses canonical paren syntax `f(x)` rather than Haskell
+-- currying `f x` — see examples/faces/README.adoc.)
+-- face: lucidscript
+
+module Hello where
+
+effect IO {
+  fn println(s: String) -> ();
+}
+
+main :: -{IO}-> ()
+main () = println("Hello, LucidScript!")

examples/faces/hello-lucid.affine

@@ -0,0 +1,17 @@
+-- SPDX-License-Identifier: AGPL-3.0-or-later
+-- SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell
+--
+-- PseudoScript face. Distinctive features exercised:
+-- function ... do ... end blocks, `--` Haskell/SQL-style comments.
+-- (Note: pseudocode-face does not yet auto-insert statement separators,
+-- so this minimal demo keeps each function body to a single expression.
+-- See examples/faces/README.adoc for a list of pending transformer gaps.)
+-- face: pseudoscript
+
+effect IO {
+  fn println(s: String) -> ();
+}
+
+function main() -{IO}-> () do
+    println("Hello, PseudoScript!")
+end

examples/faces/hello-pseudo.affine

@@ -0,0 +1,14 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell
+#
+# RattleScript face. Distinctive features exercised: `def` keyword,
+# indentation as block delimiter, `#` line comments, `True/False/None`
+# literals, `and/or/not` boolean keywords, `:` block opener.
+# face: rattlescript
+
+effect IO:
+    fn println(s: String) -> ();
+
+def main() -{IO}-> ():
+    let greeting = "Hello, RattleScript!"
+    println(greeting)