README.md

AffineScript Wiki

A guide to learning and using AffineScript — a language with affine types, algebraic effects, and a typed-WebAssembly compilation target.

⚠️ Authoritative status lives in the repo, not this wiki. Where this wiki's prose implies broader maturity than the in-repo matrices state, the matrices win — see docs/CAPABILITY-MATRIX.adoc for live per-feature readiness and docs/TECH-DEBT.adoc for the coordination ledger. AffineScript is alpha today, with the CORE-01 borrow-checker work in progress (see issue #177).

Quick Navigation

Getting Started

• Introduction — What is AffineScript?
• Quick Start — Get productive with the CLI

📌 For setup instructions, the canonical source is the root README.adoc §"Getting Started" and the CONTRIBUTING.md §"Quick Start".

Language Reference

These pages cover the language surface as designed. For each feature, cross-reference the Capability Matrix to see whether it is enforced, works, partial, declared-but-unwired, or parse-only today.

• Lexical Structure — Tokens, literals, comments
• Types — Type system overview
• Patterns — Pattern matching
• Functions — Function definitions
• Ownership — Affine types and borrowing
• Effects — Algebraic effect system
• Traits — Type classes (currently partial)
• Modules — Module system
• Dependent Types — Indexed and refined types (currently parse-only)
• Row Polymorphism — Extensible records

Compiler

• Architecture Overview — Compiler pipeline
• Lexer — Lexical analysis
• Parser — Syntactic analysis
• Type Checker — Type inference and checking
• Borrow Checker — Ownership verification
• Code Generation — WASM backend

Tooling

• CLI Reference — Command-line interface
• REPL Guide — Interactive environment

Standard Library

• Overview — Library organisation

The standard library is AOT-coherent (per docs/CAPABILITY-MATRIX.adoc STDLIB-AOT). stdlib/json.affine and stdlib/dict.affine are live; the Http/Promise/IO surface is documented under STDLIB-01..05 in docs/TECH-DEBT.adoc.

Testing

• Testing Guide — Writing tests
• Property-Based Testing — QuickCheck-style testing

Canonical testing standards: docs/standards/TESTING.adoc.

Quick Links

Resource	Description
README.adoc	Project overview + Getting Started
docs/CAPABILITY-MATRIX.adoc	Authoritative per-feature readiness
docs/TECH-DEBT.adoc	Coordination ledger (CORE / STDLIB / INT / DOC)
docs/ECOSYSTEM.adoc	Spine + AS↔typed-wasm contract
docs/ROADMAP.adoc	Development roadmap
docs/specs/SPEC.adoc	Core language specification
examples/	Example programs
CONTRIBUTING.md	How to contribute

Language Features at a Glance

Ownership & Borrowing (enforced)

fn transfer(file: own File) -> own File {
  // file is owned, must be returned or consumed
  file
}

fn read_only(file: ref File) -> String {
  // file is borrowed immutably
  file.read_all()
}

fn modify(file: mut File) {
  // file is borrowed mutably
  file.write("data")
}

QTT (Quantitative Type Theory) semiring enforced on every check, compile, and eval invocation — see lib/quantity.ml. Linear arrows enforced. Borrow-graph validation + NLL last-use landed (CORE-01 parts 1–3 Slice A, see CAPABILITY-MATRIX).

Algebraic Effects (partial — interpreter complete; WasmGC dispatch via CPS in flight)

effect Ask[A] {
  fn ask() -> A
}

fn double_ask[A]() -{Ask[A]}-> (A, A) {
  (ask(), ask())
}

fn main() -{IO}-> Unit {
  let result = handle double_ask() {
    ask() -> resume(42)
  };
  print(result)  // (42, 42)
}

Pure/impure separation + effect polymorphism enforced in the typechecker. Handlers are interpreter-complete; WasmGC dispatch is the CPS-transform line (#225, closed end-to-end; #234 generalised the boundary recogniser).

Row Polymorphism (partial)

// Works on any record with 'name' field
fn greet[r](person: {name: String, ..r}) -> String {
  "Hello, " ++ person.name
}

// Can call with any matching record
greet({name: "Alice", age: 30})
greet({name: "Bob", role: "Admin", active: true})

Records + effect rows in typecheck/unify. Not fully exercised end-to-end yet.

Dependent Types (parse-only — not enforced)

// Length-indexed vectors — SYNTAX PARSES, but predicates do not
// reduce and there is no SMT/decision procedure. These types are
// not enforced at runtime today.
fn head[n: Nat, T](vec: Vec[n + 1, T]) -> T {
  vec[0]
}

This surface parses but has no semantics behind it yet — TRefined constructors exist in the AST but the typechecker does not reduce predicates or check refinements. See docs/CAPABILITY-MATRIX.adoc row "Dependent / refinement types".

Community

• GitHub: github.com/hyperpolymath/affinescript
• Issues: Report bugs and request features
• Discussions: Ask questions and share ideas

---

AffineScript — affine types + algebraic effects + typed-WebAssembly. Status (live): docs/CAPABILITY-MATRIX.adoc.