feat(faces): wire resolve_face into lint_file + add RattleScript distribution layer

- resolve_face now wired into all six file handlers (parse, check, eval,
  compile, fmt, lint) — extension-based face inference complete
- distributions/rattlescript/: thin Rust wrapper pre-injecting --face python,
  build.rs detects affinescript binary (env / PATH / monorepo sibling),
  justfile, examples (hello.rattle, ownership.rattle), README.adoc
- RattleScript name is clear — no prior projects (verified)
- Sync strategy: standalone repo uses affinescript as submodule;
  `just update-affinescript` bumps pointer on each release

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: hyperpolymath

bin/main.ml

@@ -59,6 +59,27 @@ let lex_file path =
     Format.eprintf "@[<v>%s:%d:%d: error: %s@]@." path pos.line pos.col msg;
     `Error (false, "Lexer error")
 
+(** Resolve the effective face, promoting Canonical → face-from-extension when
+    the file extension implies a specific face.  This means a user can run
+    [affinescript check hello.rattle] with no [--face] flag and get
+    Python-face automatically.  An explicit [--face canonical] overrides. *)
+let resolve_face face path =
+  match face with
+  | Affinescript.Face.Canonical ->
+    let ext =
+      try
+        let dot = String.rindex path '.' in
+        String.sub path (dot + 1) (String.length path - dot - 1)
+      with Not_found -> ""
+    in
+    (match ext with
+    | "rattle"    -> Affinescript.Face.Python     (* RattleScript *)
+    | "pyaff"     -> Affinescript.Face.Python
+    | "jsaff"     -> Affinescript.Face.Js
+    | "pseudoaff" -> Affinescript.Face.Pseudocode
+    | _           -> Affinescript.Face.Canonical)
+  | other -> other   (* explicit --face flag always wins *)
+
 (** Parse a file using the requested face. *)
 let parse_with_face (face : Affinescript.Face.face) path =
   match face with
@@ -93,6 +114,7 @@ let preview_pseudocode_transform path =
 
 (** Parse a file and print AST (no --json support). *)
 let parse_file (face : Affinescript.Face.face) path =
+  let face = resolve_face face path in
   try
     let prog = parse_with_face face path in
     Format.printf "%s@." (Affinescript.Ast.show_program prog);
@@ -109,6 +131,7 @@ let parse_file (face : Affinescript.Face.face) path =
 (** Type-check a file.  With [--json], emits a structured diagnostic
     report on stderr. *)
 let check_file face json path =
+  let face = resolve_face face path in
   if json then begin
     let diags = ref [] in
     let add d = diags := d :: !diags in
@@ -182,6 +205,7 @@ let check_file face json path =
 (** Evaluate a file with the interpreter.  With [--json], emits
     diagnostics on stderr instead of human-readable error text. *)
 let eval_file face json path =
+  let face = resolve_face face path in
   if json then begin
     let diags = ref [] in
     let add d = diags := d :: !diags in
@@ -264,6 +288,7 @@ let repl_cmd_fn () =
     compilation errors.  With [--wasm-gc], targets the WebAssembly GC
     proposal instead of WASM 1.0 linear memory. *)
 let compile_file face json wasm_gc path output =
+  let face = resolve_face face path in
   if json then begin
     let diags = ref [] in
     let add d = diags := d :: !diags in
@@ -380,6 +405,7 @@ let compile_file face json wasm_gc path output =
 (** Format a file.  Only canonical face is supported — non-canonical face
     formatting requires a reverse transform that is not yet implemented. *)
 let fmt_file face path =
+  let face = resolve_face face path in
   (match face with
   | Affinescript.Face.Python ->
     Format.eprintf "fmt --face python is not yet supported \
@@ -407,6 +433,7 @@ let fmt_file face path =
 (** Lint a file.  With [--json], emits lint diagnostics as structured
     JSON on stderr. *)
 let lint_file face json path =
+  let face = resolve_face face path in
   if json then begin
     let diags = ref [] in
     let add d = diags := d :: !diags in

distributions/rattlescript/Cargo.toml

@@ -0,0 +1,28 @@
+# SPDX-License-Identifier: PMPL-1.0-or-later
+# SPDX-FileCopyrightText: 2024-2026 Jonathan D.A. Jewell (hyperpolymath)
+
+[package]
+name        = "rattle"
+version     = "0.1.0"
+edition     = "2021"
+description = "Python-syntax AffineScript — write Python-style code, get affine resource guarantees"
+license     = "PMPL-1.0-or-later"
+authors     = ["Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>"]
+repository  = "https://github.com/hyperpolymath/rattlescript"
+keywords    = ["affinescript", "python-face", "wasm", "affine-types", "linear-types"]
+categories  = ["development-tools", "compilers"]
+
+[dependencies]
+# Pure Rust thin wrapper — no external dependencies.
+
+[build-dependencies]
+# build.rs detects or requires AFFINESCRIPT_BIN at compile time
+
+[[bin]]
+name = "rattle"
+path = "src/main.rs"
+
+[profile.release]
+opt-level = "z"
+lto       = true
+strip     = true

distributions/rattlescript/README.adoc

@@ -0,0 +1,142 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+// SPDX-FileCopyrightText: 2024-2026 Jonathan D.A. Jewell (hyperpolymath)
+= RattleScript
+:toc:
+:toc-placement: preamble
+
+Python-syntax AffineScript.
+Write code that looks like Python.
+Get affine resource guarantees, algebraic effects, and typed WASM out.
+
+---
+
+== What it is
+
+RattleScript is AffineScript with its Python face pre-selected.
+If you write Python, you already know most of the syntax.
+The compiler checks that your resources (files, sockets, tokens) are used
+*exactly as many times as you say* — and proves it at compile time.
+
+[source,python]
+----
+def greet(name: String) -> String:
+    "Hello, " + name + "!"
+
+def main() -> ():
+    let msg = greet("world")
+    IO.println(msg)
+----
+
+That's a valid `.rattle` file.  Run it:
+
+[source,bash]
+----
+rattle eval hello.rattle
+----
+
+== Why Python syntax?
+
+Because Python programmers deserve a sound type system.
+RattleScript is Python's more dangerous cousin — same comfortable whitespace-
+delimited blocks, but with teeth: no null pointer exceptions, no
+use-after-free, no data races, and no runtime surprises that the type
+checker already knows about.
+
+The mascot is a rattlesnake.  Python's more dangerous cousin.
+
+== Surface mappings
+
+[cols="1,1"]
+|===
+|Python surface |AffineScript equivalent
+
+|`def f(x: T) -> R:`   |`fn f(x: T) -> R { ... }`
+|`True` / `False`       |`true` / `false`
+|`None`                 |`()`
+|`and` / `or` / `not`  |`&&` / `\|\|` / `!`
+|`class Name:`          |`type Name`
+|`pass`                 |`()`
+|`import a.b`           |`use a::b;`
+|`from a import b`      |`use a::b;`
+|`if cond:` / `else:`   |`if cond { ... } else { ... }`
+|`for x in e:`          |`for x in e { ... }`
+|`match e:`             |`match e { ... }`
+|`# comment`            |`// comment`
+|===
+
+See `rattle preview-python-transform <file>` to inspect the full transform
+for any file.
+
+== Installation
+
+=== From source (monorepo dev)
+
+[source,bash]
+----
+# From nextgen-languages/affinescript root — build affinescript first:
+dune build
+
+# Then build the rattle wrapper:
+cd distributions/rattlescript
+just build
+# Binary at: target/debug/rattle
+----
+
+=== Installed release
+
+[source,bash]
+----
+just install
+# Installs rattle to ~/.cargo/bin
+----
+
+=== Standalone GitHub repo
+
+The standalone https://github.com/hyperpolymath/rattlescript[hyperpolymath/rattlescript]
+repo contains a pre-configured distribution with affinescript as a git
+submodule.  Use that for a self-contained checkout.
+
+== Usage
+
+[source,bash]
+----
+# Type-check a file
+rattle check hello.rattle
+
+# Evaluate
+rattle eval hello.rattle
+
+# Compile to WASM
+rattle compile hello.rattle
+
+# See the canonical AffineScript generated by the preprocessor
+rattle preview-python-transform hello.rattle
+
+# All affinescript subcommands work — --face python is pre-injected
+rattle lint hello.rattle
+rattle fmt hello.rattle
+----
+
+== Relationship to AffineScript
+
+RattleScript *is* AffineScript — same compiler, same type system, same WASM
+output.  The only difference is `--face python` is the default.
+
+The Python face lives in
+link:../../lib/python_face.ml[`lib/python_face.ml`] and the error vocabulary
+in link:../../lib/face.ml[`lib/face.ml`].  No compiler internals change when
+the face changes.
+
+== Sync strategy
+
+This directory (`distributions/rattlescript/`) lives inside the affinescript
+monorepo.  The standalone https://github.com/hyperpolymath/rattlescript[rattlescript]
+GitHub repo uses affinescript as a git submodule and contains only:
+
+* This `distributions/rattlescript/` content (copied at release time)
+* Branding assets
+* CI workflows
+
+`just update-affinescript` advances the submodule pointer after each
+affinescript release.  All language changes, face changes, and bug fixes
+come through that single submodule bump — no duplication.

distributions/rattlescript/build.rs

@@ -0,0 +1,50 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+// SPDX-FileCopyrightText: 2024-2026 Jonathan D.A. Jewell (hyperpolymath)
+
+//! build.rs — detect or require the `affinescript` binary path.
+//!
+//! Checks, in order:
+//! 1. `AFFINESCRIPT` env var (explicit override)
+//! 2. `affinescript` on PATH (standard install)
+//! 3. Sibling build output `../../_build/default/bin/main.exe` (monorepo dev)
+//!
+//! The resolved path is baked in as the `AFFINESCRIPT_BIN` compile-time env.
+
+use std::env;
+use std::path::Path;
+
+fn main() {
+    println!("cargo:rerun-if-env-changed=AFFINESCRIPT");
+
+    let bin = if let Ok(p) = env::var("AFFINESCRIPT") {
+        p
+    } else if which_affinescript() {
+        "affinescript".to_string()
+    } else {
+        // Monorepo dev path: distributions/rattlescript/ → ../../_build/...
+        let manifest = env::var("CARGO_MANIFEST_DIR").unwrap();
+        let dev_path = Path::new(&manifest)
+            .join("../../_build/default/bin/main.exe")
+            .canonicalize()
+            .ok()
+            .map(|p| p.to_string_lossy().into_owned());
+
+        match dev_path {
+            Some(p) => p,
+            None => {
+                // Fall back to the name — will fail at runtime with a clear message.
+                "affinescript".to_string()
+            }
+        }
+    };
+
+    println!("cargo:rustc-env=AFFINESCRIPT_BIN={bin}");
+}
+
+fn which_affinescript() -> bool {
+    std::process::Command::new("which")
+        .arg("affinescript")
+        .output()
+        .map(|o| o.status.success())
+        .unwrap_or(false)
+}

distributions/rattlescript/examples/hello.rattle

@@ -0,0 +1,13 @@
+# SPDX-License-Identifier: PMPL-1.0-or-later
+# SPDX-FileCopyrightText: 2024-2026 Jonathan D.A. Jewell (hyperpolymath)
+
+# RattleScript — Hello World
+# This is a .rattle file (Python-face AffineScript).
+# You can also use .pyaff if you prefer.
+
+def greet(name: String) -> String:
+    "Hello, " + name + "!"
+
+def main() -> ():
+    let msg = greet("world")
+    IO.println(msg)

distributions/rattlescript/examples/ownership.rattle

@@ -0,0 +1,21 @@
+# SPDX-License-Identifier: PMPL-1.0-or-later
+# SPDX-FileCopyrightText: 2024-2026 Jonathan D.A. Jewell (hyperpolymath)
+
+# RattleScript — Ownership demo
+# Python programmers: this looks familiar, but the compiler tracks
+# *who owns what* so you never get null-pointer surprises.
+
+def consume_token(@linear token: Token) -> Receipt:
+    # token is used exactly once here — the compiler proves it
+    process(token)
+
+def safe_divide(a: Int, b: Int) -> Option[Int]:
+    if b == 0:
+        None
+    else:
+        Some(a / b)
+
+def show_result(result: Option[Int]) -> ():
+    match result:
+        Some(n) => IO.println("Result: " + Int.to_string(n))
+        None    => IO.println("Division by zero — handled, not crashed")

distributions/rattlescript/justfile

@@ -0,0 +1,46 @@
+# SPDX-License-Identifier: PMPL-1.0-or-later
+# SPDX-FileCopyrightText: 2024-2026 Jonathan D.A. Jewell (hyperpolymath)
+
+# RattleScript distribution justfile.
+# Most work lives in the parent affinescript justfile.
+# This file handles the thin Rust wrapper binary only.
+
+default:
+    just --list
+
+# Build the rattle binary (dev mode, uses sibling _build/)
+build:
+    cargo build
+
+# Build optimised release binary
+release:
+    cargo build --release
+
+# Run the example
+run-hello:
+    cargo run -- eval examples/hello.rattle
+
+# Check example typechecks
+check-hello:
+    cargo run -- check examples/hello.rattle
+
+# Show the Python-face transform for the hello example
+preview-hello:
+    cargo run -- preview-python-transform examples/hello.rattle
+
+# Run all examples
+check-examples:
+    cargo run -- check examples/hello.rattle
+    cargo run -- check examples/ownership.rattle
+
+# Install rattle binary to ~/.cargo/bin
+install:
+    cargo install --path .
+
+# Bump AffineScript submodule pointer (called by CI after affinescript releases)
+update-affinescript:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    git -C ../.. submodule update --remote
+    git add ../..
+    git commit -m "chore(affinescript): advance pointer to latest release"