docs: sweeping changes

- rewrite types section
- discuss scope
- discuss errors as effects
- fix interop misconceptions
- various smaller changes

7 files changed, 513 insertions, 270 deletions

diff --git a/docs/ERRORS.md b/docs/ERRORS.md
index cce29c1..665535f 100644
--- a/docs/ERRORS.md
+++ b/docs/ERRORS.md
@@ -1,83 +1,96 @@
 # Error Handling
 
-Puck's error handling is shamelessly stolen from Swift. It uses a combination of `Option`/`Result` types and `try`/`catch` statements, and leans somewhat on Puck's metaprogramming capabilities.
+Puck's error handling is heavily inspired syntactically by Swift and semantically by the underlying effects system. It uses a combination of monadic error handling and effectful error propagation, with much in the way of syntactic sugar for conversion between the two, and leans somewhat heavily on Puck's metaprogramming capabilities. In comparison to Rust, it is considerably more dynamic by default.
 
-There are several ways to handle errors in Puck. If the error is encoded in the type, one can:
+There are several ways to handle errors in Puck. If the error is encoded in the type (as an `Option` or `Result` type), one can:
 1. `match` on the error
 2. compactly match on the error with `if ... of`
 3. propagate the error with `?`
 4. throw the error with `!`
 
-If an error is thrown, one **must** explicitly handle (or disregard) it with a `try/catch` block or risk runtime failure. This method of error handling may feel more familiar to Java programmers.
+If the error is thrown (encoded as an effect), one can:
+1. ignore the error, propagating it up the call stack
+2. recover from the error in a `try` block
+3. convert the error to a `Result[T]` (monadic form)
 
-## Errors as Monads
+If an error is thrown, one *must* explicitly handle it at some level of the stack, or risk runtime failure. This method of error handling may feel more familiar to Java programmers. The compiler will warn on - but not enforce catching - such unhandled errors.
 
-Puck provides [`Option[T]`](std/default/options.pk) and a [`Result[T, E]`](std/default/results.pk) types, imported by default. These are `union` types and so must be pattern matched upon to be useful: but the standard library provides [a bevy of helper functions](std/default/results.pk).
+## Errors as monads
+
+Puck provides [`Option[T]`](std/default/options.pk) and a [`Result[T, E]`](std/default/results.pk) types, imported by default. These are `union` types under the hood and so must be pattern matched upon to be useful: but the standard library provides [a bevy of helper functions](std/default/results.pk).
 Two in particular are of note. The `?` operator unwraps a Result or propagates its error up a function call (and may only be used in type-appropriate contexts). The `!` operator unwraps an Option or Result directly or throws an exception in the case of None or Error.
 
 ```puck
-pub macro `?`[T, E](self: Result[T, E]) =
-  quote:
+pub macro ?[T, E](self: Result[T, E]) =
+  quote
     match `self`
-    of Okay(x): x
-    of Error(e): return Error(e)
+    of Okay(x) then x
+    of Error(e) then return Error(e)
 ```
 
 ```puck
-pub func `!`[T](self: Option[T]): T =
+pub func ![T](self: Option[T]): T =
   match self
-  of Some(x): x
-  of None: raise EmptyValue
+  of Some(x) then x
+  of None then raise "empty value"
 
-pub func `!`[T, E](self: Result[T, E]): T =
-  of Okay(x): x
-  of Error(e): raise e
+pub func ![T, E](self: Result[T, E]): T =
+  match self
+  of Okay(x) then x
+  of Error(e) then raise e
 ```
 
-The utility of the provided helpers in [`std.options`](std/default/options.pk) and [`std.results`](std/default/results.pk) should not be understated. While encoding errors into the type system may appear restrictive at first glance, some syntactic sugar goes a long way in writing compact and idiomatic code. Java programmers in particular are urged to give type-first errors a try, before falling back on unwraps and `try`/`catch`.
-
-A notable helpful type is the aliasing of `Result[T]` to `Result[T, ref Err]`, for when the particular error does not matter. This breaks `try`/`catch` exhaustion (as `ref Err` denotes a reference to *any* Error), but is particularly useful when used in conjunction with the propagation operator.
+The utility of the provided helpers in [`std.options`](std/default/options.pk) and [`std.results`](std/default/results.pk) should not be understated. While encoding errors into the type system may appear restrictive at first glance, some syntactic sugar goes a long way in writing compact and idiomatic code. Java programmers in particular are urged to give type-first errors a try, before falling back on unwraps and `try`/`with`.
 
-## Errors as Catchable Exceptions
+A notable helpful type is the aliasing of `Result[T]` to `Result[T, ref Err]`, for when the particular error does not matter. This breaks `match` exhaustion (as `ref Err` denotes a reference to *any* Error), but is particularly useful when used in conjunction with the propagation operator.
 
-Errors raised by `raise`/`throw` (or subsequently the `!` operator) must be explicitly caught and handled via a `try`/`catch`/`finally` statement.
-If an exception is not handled within a function body, the function must be explicitly marked as a throwing function via the `yeet` prefix (name to be determined). The compiler will statically determine which exceptions in particular are thrown from any given function, and enforce them to be explicitly handled or explicitly ignored.
+## Errors as checked exceptions
 
-Despite functioning here as exceptions: errors remain types. An error thrown from an unwrapped `Result[T, E]` is of type `E`. `catch` statements, then, may pattern match upon possible errors, behaving similarly to `of` branches.
+Some functions do not return a value but can still fail: for example, setters. This can make it difficult to do monadic error handling elegantly. One could return a `type Success[E] = Result[void, E]`, but such an approach is somewhat inelegant. Instead: we treat an `assert` within a function as having an *effect*: a possible failure, that can be handled and recovered from at any point in the call stack. If a possible exception is not handled within a function body, the function is implicitly marked by the compiler as throwing that exception.
 
 ```puck
-try
-  ...
-catch "Error" then
-  ...
-finally
-  ...
-```
+pub type list[T] = struct
+  data: ptr T
+  capacity: uint
+  length: uint
 
-This creates a distinction between two types of error handling, working in sync: functional error handling with [Option](https://en.wikipedia.org/wiki/Option_type) and [Result](https://en.wikipedia.org/wiki/Result_type) types, and object-oriented error handling with [catchable exceptions](https://en.wikipedia.org/wiki/Exception_handling). These styles may be swapped between with minimal syntactic overhead. Libraries, however, should universally use `Option`/`Result`, as this provides the best support for both styles.
-
-<!-- [nullable types](https://en.wikipedia.org/wiki/Nullable_type)?? -->
+@[safe]
+pub func set[T](self: list[T], i: uint, val: T) =
+  if i > self.length then
+    raise IndexOutOfBounds
+  self.data.set(offset = i, val)
 
-## Errors and Void Functions
+var foo = ["Hello", "world"]
+foo.set(0, "Goodbye") # set can panic
+# this propagates an IndexOutOfBounds effect up the call stack.
+```
 
-Some functions do not return a value but can still fail: for example, setters.
-This can make it difficult to do monadic error handling elegantly: one could return a `Result[void, E]`, but...
+Despite functioning here as exceptions: errors remain types. An error thrown from an unwrapped `Result[T, E]` is of type `E`. `with` statements, then, may pattern match upon possible errors, behaving semantically and syntactically similarly to `of` branches: though notably not requiring exhaustion.
 
 ```puck
-pub func set[T](self: list[T], i: uint, val: T) =
-  if i > self.length then
-    raise IndexOutOfBounds
-  self.data.raw_set(offset = i, val)
+try
+  foo.set(0, "Goodbye")
+with IndexOutOfBounds(index) then
+  dbg "Index out of bounds at {}".fmt(index)
+  panic
+finally
+  ...
 ```
 
-## Unrecoverable Exceptions
+This creates a distinction between two types of error handling, working in sync: functional error handling with [Option](https://en.wikipedia.org/wiki/Option_type) and [Result](https://en.wikipedia.org/wiki/Result_type) types, and [object-oriented error handling](https://en.wikipedia.org/wiki/Exception_handling) with [algebraic effects](...). These styles may be swapped between with minimal syntactic overhead. It is up to libraries to determine which classes of errors are exceptional and best given the effect treatment and which should be explicitly handled monadically. Libraries should tend towards using `Option`/`Result` as this provides the best support for both styles (thanks to the `!` operator).
+
+## Unrecoverable exceptions
 
 There exist errors from which a program can not reasonably recover. These are the following:
-- `Assertation Failure`: a call to an `assert` function has returned false at runtime.
+- `Assertation Failure`: a call to an unhandled `assert` function has returned false at runtime.
 - `Out of Memory`: the executable is out of memory.
 - `Stack Overflow`: the executable has overflowed the stack.
 - any others?
 
-They are not recoverable, but the user should be aware of them as possible failure conditions.
+They are not recoverable, and not handled within the effects system, but the user should be aware of them as possible failure conditions.
+
+---
 
-References: [Error Handling in Swift](https://docs.swift.org/swift-book/documentation/the-swift-programming-language/errorhandling)
+References
+- [Error Handling in Swift](https://docs.swift.org/swift-book/documentation/the-swift-programming-language/errorhandling)
+- [Algebraic Effects for the rest of us](https://overreacted.io/algebraic-effects-for-the-rest-of-us/)
diff --git a/docs/INTEROP.md b/docs/INTEROP.md
index 7eaed5f..91d4679 100644
--- a/docs/INTEROP.md
+++ b/docs/INTEROP.md
@@ -4,30 +4,52 @@
 
 A major goal of Puck is _minimal-overhead language interoperability_ while maintaining type safety.
 
+## The problems of interop
+
 There are three issues that complicate language interop:
-1. Conflicting memory management systems, i.e. Boehm GC vs. reference counting
+1. The language of communication, i.e. the C ABI.
 2. Conflicting type systems, i.e. Python vs. Rust
-3. The language of communication, i.e. the C ABI.
+3. Conflicting memory management systems, i.e. tracing / reference counting vs. ownership
+
+For the first, Puck is being written at the same time as the crABI ABI spec is in development. crABI promises a C-ABI-compatible, cross-language ABI spec: which would *dramatically* simplify the task of linking to object files produced by other languages (so long as languages actually conform to the ABI). It is being led by the Rust language team, and both Nim and Swift developers have expressed interest in it, which bodes quite well for its future.
+
+For the second, Puck has a type system of similar capability to that of Rust, Nim, and Swift: and thus interop with those languages should be a straightforward exchange of types. Its type system is strictly more powerful than that of Python or C, and so interop requires additional help. Its type system is equally as powerful as but somewhat orthogonal to Java's, and so interop will be a little more difficult.
+
+For the third: Puck uses what amounts to a combination of ownership and reference counting: and thus it is exchangeable in this regard with Rust. Nim and Swift, by contrast, use reference counting: which is not directly compatible with ownership, as attempting to use an owned type as a GC'd reference will immediately lead to a use-after-free. Puck may have to explore some form of gradual typing at linking-time to accommodate making its functions available for use. Using functions from GC'd languages, however, is perfectly doable with the `refc` type: though this may necessitate copying object graphs over the call boundary.
 
-For the first, Puck uses what amounts to a combination of ownership and reference counting: and thus it is exchangeable in this regard with Nim (same system), Rust (ownership), Swift (reference counting), and many others. (It should be noted that ownership systems are broadly compatible with reference counting systems).
+There is additional significant work being put into the use of Wasm as a language runtime. Wasm allows for - among other things - the *sharing* of garbage collectors, which means that any garbage-collected language compiling to it can simply use the primitive `refc` type to denote a garbage-collected reference. This does not, however, immediately work off the bat with ownership: as ownership necessitates certain invariants that garbage collection does not preserve. There is active research into fixing this: notably RichWasm, which retrofits a structural type system with ownership atop Wasm. Such extensions necessitate the runtime environment to implement them, however, and so Puck may have to explore some form of gradual typing for the broader Wasm ecosystem.
 
-For the second, Puck has a type system of similar capability to that of Rust, Nim, and Swift: and thus interop with those languages should be straightforward for the user. Its type system is strictly more powerful than that of Python or C, and so interop requires additional help. Its type system is equally as powerful as but somewhat orthogonal to Java's, and so interop is a little more difficult.
+## Usability
 
-For the third, Puck is being written at the same time as the crABI ABI spec is in development. crABI promises a C-ABI-compatible, cross-language ABI spec, which would *dramatically* simplify the task of linking to object files produced by other languages. It is being led by the Rust language team, and both the Nim and Swift teams have expressed interest in it, which bodes quite well for its future.
+```puck
+use std.io
+use rust.os.linux
+use nim.os.sleep
+...
+```
+
+Languages often focus on interop from purely technical details. This *is* very important: but typically little thought is given to usability (and often none can be, for necessity of compiler support), and so using foreign function interfaces very much feel like using *foreign* function interfaces. Puck attempts to change that.
+
+```puck
+@[form(this-function)]
+pub func this_function() = ...
+```
+
+A trivial concern is that identifiers are not always the same across languages: for example, in Racket `this-function` is a valid identifier, while in Puck the `-` character is disallowed outright. Matters of convention are issues, too: in Puck, `snake_case` is preferred for functions and `PamelCase` for types, but this is certainly not always the case. Puck addresses this at an individual level by attributes allowing for rewriting: and at a language level by consistent rewrite rules.
 
-Languages often focus on interop from purely technical details. This *is* very important: but typically no thought is given to usability (and often none can be, for necessity of compiler support), and so using foreign function interfaces very much feel like using *foreign* interfaces. Puck attempts to change that.
 
 ...todo...
 
+---
+
 Existing systems to learn from:
 - [The Rust ABI](https://doc.rust-lang.org/reference/abi.html)
-- https://www.hobofan.com/rust-interop/
+- [rust-interop](https://www.hobofan.com/rust-interop/)
 - [CBindGen](https://github.com/eqrion/cbindgen)
-- https://github.com/chinedufn/swift-bridge
-- https://kotlinlang.org/docs/native-c-interop.html
-- https://github.com/crackcomm/rust-lang-interop
-- https://doc.rust-lang.org/reference/abi.html
-- https://doc.rust-lang.org/reference/items/functions.html#extern-function-qualifier
+- [swift-bridge](https://github.com/chinedufn/swift-bridge)
+- [Kotlin C interop](https://kotlinlang.org/docs/native-c-interop.html)
+- [rust-lang-interop](https://github.com/crackcomm/rust-lang-interop)
+- [extern in Rust](https://doc.rust-lang.org/reference/items/functions.html#extern-function-qualifier)
 - [NimPy](https://github.com/yglukhov/nimpy)
 - [JNim](https://github.com/yglukhov/jnim)
 - [Futhark](https://github.com/PMunch/futhark)
diff --git a/docs/METAPROGRAMMING.md b/docs/METAPROGRAMMING.md
index a8675b2..17e65a0 100644
--- a/docs/METAPROGRAMMING.md
+++ b/docs/METAPROGRAMMING.md
@@ -1,17 +1,19 @@
 # Metaprogramming
 
-Puck has rich metaprogramming support, heavily inspired by Nim. Many features that would have to be at the compiler level in most languages (error propagation `?`, `std.fmt.print`, `async`/`await`) are instead implemented as macros within the standard library.
+Puck has rich metaprogramming support, heavily inspired by Nim. Many features that would have to be at the compiler level in most languages (error propagation `?`, `std.fmt.print`, `?`, `!`, `->` type sugar, `=>` closure sugar, `async`/`await`) are instead implemented as macros within the standard library.
+
+Macros take in fragments of the AST within their scope, transform them with arbitrary compile-time code, and spit back out transformed AST fragments to be injected and checked for validity. This is similar to what the Lisp family of languages do. It has a number of benefits: there is no separate metaprogramming language, it is syntactically and semantically hygienic, and the underlying framework can be reused for all kinds of compile-time code execution.
 
-Macros take in fragments of the AST within their scope, transform them with arbitrary compile-time code, and spit back out transformed AST fragments to be injected and checked for validity. This is similar to what Nim and the Lisp family of languages do.
 By keeping an intentionally minimal AST, some things not possible to express in literal code may be expressible in the AST: in particular, bindings can be injected in many places they could not be injected in ordinarily. (A minimal AST also has the benefit of being quite predictable.)
 
-Macros may not change Puck's syntax: the syntax is flexible enough. Code is syntactically checked (parsed), but *not* semantically checked (typechecked) before being passed to macros. This may change in the future<!-- (to require arguments to be semantically correct)-->. Macros have the same scope as other routines, that is:
+Macros may not change Puck's syntax: the syntax is flexible enough. They have the same scope as other routines, that is:
 
 **function scope**: takes the arguments within or following a function call
 ```puck
 macro print(params: varargs) =
+  var res = Call("write", [stdout])
   for param in params do
-    result.add(quote(stdout.write(`params`.str)))
+    res.params.add(param)
 
 print(1, 2, 3, 4)
 print "hello", " ", "world", "!"
@@ -28,11 +30,11 @@ my_macro
   4
 ```
 
-**operator scope**: takes one or two parameters either as a postfix (one parameter) or an infix (two parameters) operator
+**operator scope**: takes one or two parameters either as an infix (two parameters) or a postfix (one parameter) operator
 ```puck
+# operators are restricted to punctuation
 macro +=(a, b) =
-  quote
-    `a` = `a` + `b`
+  Call("=", [a, Call("+", [a, b])])
 
 a += b
 ```
@@ -43,12 +45,12 @@ Similarly, macros always return an `Expr` to be injected into the abstract synta
 ```puck
 ```
 
-As macros operate at compile time, they may not inspect the *values* that their parameters evaluate to. However, parameters may be marked with `static[T]`: in which case they will be treated like parameters in functions: as values. (note static parameters may be written as `static[T]` or `static T`.) There are many restrictions on what might be `static` parameters. Currently, it is constrained to literals i.e. `1`, `"hello"`, etc, though this will hopefully be expanded to any function that may be evaluated statically in the future.
+As macros operate at compile time, they may not inspect the *values* that their parameters evaluate to. However, parameters may be marked `const`: in which case they will be treated like parameters in functions: as values. (note constant parameters may be written as `const[T]` or `const T`.)
 
 ```puck
 macro ?[T, E](self: Result[T, E]) =
   quote
-    match self
+    match `self`
     of Okay(x) then x
     of Error(e) then return Error(e)
 
@@ -56,7 +58,7 @@ func meow: Result[bool, ref Err] =
   let a = stdin.get()?
 ```
 
-The `quote` macro is special. It takes in literal code and returns that code **as the AST**. Within quoted data, backticks may be used to break out in order to evaluate and inject arbitrary code: though the code must evaluate to an expression of type `Expr`. <!-- Variables (of type `Expr`) may be *injected* into the literal code by wrapping them in backticks. This reuse of backticks does mean that defining new operators is impossible within quoted code. -->
+The `quote` macro is special. It takes in literal code and returns that code **as the AST**. Within quoted data, backticks may be used to break out in order to evaluate and inject arbitrary code: though the code must evaluate to an expression of type `Expr`. Thus, quoting is *structured*: one cannot simply quote any arbitrary section. Quoting is very powerful: most macros are implemented using it.
 
 ```puck
 ```
@@ -66,4 +68,4 @@ The `Expr` type is available from `std.ast`, as are many helpers, and combined t
 ```puck
 ```
 
-Construction of macros can be difficult: and so several helpers are provided to ease debugging. The `Debug` and `Display` interfaces are implemented for abstract syntax trees: `dbg` will print a representation of the passed syntax tree as an object, and `print` will print a best-effort representation as literal code. Together with `quote` and optionally with `static`, these can be used to quickly get the representation of arbitrary code.
+Construction of macros can be difficult: and so several helpers are provided to ease debugging. The `Debug` and `Display` interfaces are implemented for abstract syntax trees: `dbg` will print a representation of the passed syntax tree as an object, and `print` will print a best-effort representation as literal code. Together with `quote` and optionally with `const`, these can be used to quickly get the representation of arbitrary code.
diff --git a/docs/MODULES.md b/docs/MODULES.md
index 938e47e..eeed58b 100644
--- a/docs/MODULES.md
+++ b/docs/MODULES.md
@@ -4,35 +4,67 @@
 
 Puck has a first-class module system, inspired by such expressive designs in the ML family.
 
-## Using Modules
+## What are modules?
 
 ```puck
+pub mod stack =
+  pub type Stack[T] = class
+    init(static type Self): Stack[T]
+    push(mut Self, val: T)
+    pop(mut Self): T?
+    peek(lent Self): lent T?
+
+  pub mod list =
+    type ListStack[T] = list[T]
+
+    pub func init[T](self: static type ListStack[T]): Stack[T] = []
+    pub func push[T](self: mut ListStack[T], val: T) = self.push(T)
+    pub func pop[T](self: mut ListStack[T]): T? = self.pop
+    pub func peek[T](self: lent ListStack[T]): lent T? =
+      if self.len == 0 then None else Some(self.last)
+
+use stack.list
+
+let a = ListStack[int].init
+print a.len # error: unable to access method on private type outside its module
+
+a.push(5)
+print a.pop # Some(5)
 ```
 
-Modules package up code for use by others. Identifiers known at compile time may be part of a *module signature*: these being constants, functions, macros, types, and other modules themselves. They may be made accessible to external users by prefixing them with the `pub` keyword. Files are modules, named with their filename. The `mod` keyword followed by an identifier and an indented block of code explicitly defines a module, inside of the current module. Modules are first class: they may be bound to constants (having the type `: mod`) and publicly exported, or bound to local variables and passed into functions for who knows what purpose.
+Modules package up code for use by others. Identifiers known at compile time may be part of a module: these being constants, functions, macros, types, and other modules themselves. Such identifiers may be made accessible outside of the module by prefixing them with the `pub` keyword.
+
+Importantly, *files* are implicitly modules, public and named with their filename. The `mod` keyword followed by an identifier and an indented block of code explicitly defines a module, inside of the current module. Modules are first class: they may be bound to constants (having the type `: mod`) and publicly exported, or bound to local variables and passed into functions for who knows what purpose.
 
-The `use` keyword lets you use other modules. The `use` keyword imports public symbols from the specified module into the current scope *unqualified*. This runs contrary to expectations coming from most other languages: from Python to Standard ML, the standard notion of an "import" usually puts the imported symbols behind another symbol to avoid "polluting the namespace". As Puck is strongly typed and allows overloading, however, the author sees no reason for namespace pollution to be of concern. These unqualified imports have the added benefit of making uniform function call syntax more widely accessible. It is inevitable that identifier conflicts will exist on occasion, of course: when this happens, the compiler will force qualification (this then does restrict uniform function call syntax).
+## Using modules
+
+The `use` keyword lets you use other modules.
+
+The `use` keyword imports public symbols from the specified module into the current scope *unqualified*. This runs contrary to expectations coming from most other languages: from Python to Standard ML, the standard notion of an "import" puts the imported symbols behind another symbol to avoid "polluting the namespace". As Puck is strongly typed and allows overloading, however, we see no reason for namespace pollution to be of concern. These unqualified imports have the added benefit of making *uniform function call syntax* more widely accessible. It is inevitable that identifier conflicts will exist on occasion, of course: when this happens, the compiler will force qualification (this then does restrict uniform function call syntax). We discuss this more later.
+
+Nonetheless, if qualification of imports is so desired, an alternative approach is available - binding a module to a constant. Both the standard library and external libraries are available behind identifiers without use of `use`: `std` and `lib`, respectively. (FFI and local modules will likely use more identifiers, but this is not hammered out yet.) A submodule - for example, `std.net` - may be bound in a constant as `const net = std.net`, providing all of the modules' public identifiers for use, as fields of the constant `net`. We will see this construction to be extraordinarily helpful in crafting high-level public APIs for libraries later on.
 
 ```puck
+use std.[logs, test]
+use lib.crypto, lib.http
 ```
 
-Nonetheless, if qualification of imports is so desired, an alternative approach is available - binding a module to a constant. Both the standard library and external libraries are available behind identifiers without use of `use`: `std` and `lib`, respectively. (FFI and local modules will likely use more identifiers, but this is not hammered out yet.) A submodule - for example, `std.net` - may be bound in a constant as `const net = std.net`, providing all of the modules' public identifiers for use, as fields of the constant `net`. We will see this construction to be extraordinarily helpful in crafting high-level public APIs for libraries later on.
+Multiple modules can be imported at once. The standard namespaces deserve more than a passing mention. There are several of these: `std` for the standard library, `lib` for all external libraries, `pkg` for the top-level namespace of a project, `this` for the current containing module... In addition: there are a suite of *language* namespaces, for FFI - `rust`, `nim`, and `swift` preliminarily - that give access to libraries from other languages. Recall that imports are unqualified - so `use std` will allow use of the standard library without the `std` qualifier (not recommended: several modules have common names), and `use lib` will dump the name of every library it can find into the global namespace (even less recommended).
 
-Multiple modules can be imported at once, i.e. `use std.[logs, tests]`, `use lib.crypto, lib.http`. The standard namespaces (`std`, `lib`) deserve more than a passing mention. There are several of these: `std` for the standard library, `lib` for all external libraries, `crate` for the top-level namespace of a project (subject to change), `this` for the current containing module (subject to change)... In addition: there are a suite of *language* namespaces, for FFI - `rust`, `nim`, and `swift` preliminarily - that give access to libraries from other languages. Recall that imports are unqualified - so `use std` will allow use of the standard library without the `std` qualifier (not recommended: several modules have common names), and `use lib` will dump every library it can find into the global namespace (even less recommended). 
 
 ## Implicit Modules
 
-A major goal of Puck's module system is to allow the same level of expressiveness as the ML family, while cutting down on the extraneous syntax and boilerplate needed to do so. As such, access modifiers are written directly inline with their declaration, and the file system structure is reused to form an implicit module system for internal use. This - particularly the former - *limits* the structure a module can expose at first glance, but we will see later that interfaces recoup much of this lost specificity.
+A major goal of Puck's module system is to allow the same level of expressiveness as the ML family, while cutting down on the extraneous syntax and boilerplate needed to do so. As such, access modifiers are written directly inline with their declaration, and the file system structure is reused to form an implicit module system for internal use. This - particularly the former - *limits* the structure a module can expose at first glance, but we will see later that classes recoup much of this lost specificity.
 
-We mentioned that the filesystem forms an implicit module structure. This begets a couple of design choices. Module names **must** be lowercase, for compatibility with case-insensitive filesystems. Both a file and a folder with the same name can exist. Files within the aforementioned folder are treated as submodules of the aforementioned file. This again restricts the sorts of module structures we can build, but we will again see later that this restriction can be bypassed.
+We mentioned that the filesystem forms an implicit module structure. This begets a couple of design choices. Module names **must** be lowercase, for compatibility with case-insensitive filesystems. Both a file and a folder with the same name can exist. Files within the aforementioned folder are treated as submodules of the aforementioned file. This again restricts the sorts of module structures we can build, but we will see later that this restriction can be bypassed.
 
-The `this` and `crate` modules are useful for this implicit structure...
+The `this` and `pkg` modules are useful for this implicit structure...
 
-## Defining Interfaces
+## Defining interfaces
 
 ...
 
-## Defining an External API
+## Defining an external API
 
 The filesystem provides an implicit module structure, but it may not be the one you want to expose to users.
 
diff --git a/docs/OVERVIEW.md b/docs/OVERVIEW.md
index 1c19000..344f72e 100644
--- a/docs/OVERVIEW.md
+++ b/docs/OVERVIEW.md
@@ -22,17 +22,16 @@ Type annotations on variables and other bindings follow the name of the binding
 Variables are conventionally written in `snake_case`. Types are conventionally written in `PascalCase`.
 The type system is comprehensive, and complex enough to warrant delaying full coverage of until the end. Some basic types are of note, however:
 - `int`, `uint`: signed and unsigned integers
-  - `i8`/`i16`/`i32`/`i64`/`i128`: their fixed-size counterparts
-  - `u8`/`u16`/`u32`/`u64`/`u128`: their fixed-size counterparts
+  - `i[\d+]`, `u[\d+]`: arbitrary fixed-size counterparts
 - `float`, `decimal`: floating-point numbers
   - `f32`/`f64`/`f128`: their fixed-size counterparts
   - `dec64`/`dec128`: their fixed-size counterparts
 - `byte`: an alias to `u8`, representing one byte
-- `chr`: an alias to `u32`, representing one Unicode character
+- `char`: an alias to `u32`, representing one Unicode character
 - `bool`: defined as `union[false, true]`
-- `array[T, S]`: primitive fixed-size (`S`) arrays
+- `array[T, size]`: primitive fixed-size arrays
 - `list[T]`: dynamic lists
-- `str`: mutable strings. internally a `list[byte]`, externally a `list[chr]`
+- `str`: mutable strings. internally a `list[byte]`, externally a `list[char]`
 - `slice[T]`: borrowed "views" into the three types above
 
 Comments are declared with `#` and run until the end of the line.
@@ -45,7 +44,7 @@ Taking cues from the Lisp family of languages, any expression may be commented o
 ```puck
 ```
 
-Functions are declared with the `func` keyword. They take an (optional) list of generic parameters (in brackets), an (optional) list of parameters (in parentheses), and **must** be annotated with a return type if they return a type. Every function parameter must be annotated with a type. Their type may optionally be prefixed with either `lent`, `mut` or `static`: denoting an immutable or mutable borrow (more on these later), or a *static* type (known to the compiler at compile time, and usable in `const` exprs). Generic parameters may each be optionally annotated with a type functioning as a _constraint_.
+Functions are declared with the `func` keyword. They take an (optional) list of generic parameters (in brackets), an (optional) list of parameters (in parentheses), and **must** be annotated with a return type if they return a type. Every function parameter must be annotated with a type. Their type may optionally be prefixed with either `lent`, `mut` or `const`: denoting an immutable or mutable borrow (more on these later), or a *constant* type (known to the compiler at compile time, and usable in `const` exprs). Generic parameters may each be optionally annotated with a type functioning as a _constraint_.
 
 <!-- Functions, constants, types, and modules may be optionally prefixed with a `pub` modifier denoting visibility outside the current scope / module. More on the module system later. -->
 
@@ -76,18 +75,18 @@ Boolean logic and integer operations are standard and as one would expect out of
 - integer division is expressed with the keyword `div` while floating point division uses `/`
 - `%` is absent and replaced with distinct modulus and remainder operators
 - boolean operators are bitwise and also apply to integers and floats
-- more operators are available via the standard library
+- more operators are available via the standard library (`exp` and `log`)
 
 The above operations are performed with *operators*, special functions that take a prefixed first argument and (often) a suffixed second argument. Custom operators may be implemented, but they must consist of only a combination of the symbols `=` `+` `-` `*` `/` `<` `>` `@` `$` `~` `&` `%` `|` `!` `?` `^` `\` for the purpose of keeping the grammar context-free. They are are declared identically to functions.
 
-Term (in)equality is expressed with the `==` and `!=` operators. Type equality is expressed with `is`. Subtyping relations may be queried with `of`, which has the additional property of introducing new bindings in the current scope (more on this in the [types document](TYPES.md)). <!-- Membership of collections is expressed with `in`, and is overloaded for most types. -->
+Term (in)equality is expressed with the `==` and `!=` operators. Type equality is expressed with `is`. Subtyping relations may be queried with `of`, which has the additional property of introducing new bindings to the current scope in certain contexts (more on this in the [types document](TYPES.md)).
 
 ```puck
 let phrase: str = "I am a string! Wheeee! ✨"
-for c in phrase:
+for c in phrase do
   stdout.write(c) # I am a string! Wheeee! ✨
-for b in phrase.bytes():
-  stdout.write(b.chr) # Error: cannot convert between u8 and chr
+for b in phrase.bytes() do
+  stdout.write(b.char) # Error: cannot convert from byte to char
 print phrase.last() # ✨
 ```
 
@@ -98,9 +97,9 @@ String concatenation uses a distinct `&` operator rather than overloading the `+
 ```puck
 ```
 
-Basic conditional control flow uses standard `if`/`elif`/`else` statements. The `when` statement provides a compile-time `if`. It also takes `elif` and `else` branches and is syntactic sugar for an `if` statement within a `static` block (more on those later).
+Basic conditional control flow uses standard `if`/`elif`/`else` statements. The `when` statement provides a compile-time `if`. It also takes `elif` and `else` branches and is syntactic sugar for an `if` statement within a `const` expression (more on those later).
 
-All values in Puck must be handled, or explicitly discarded. This allows for conditional statements and many other control flow constructs to function as *expressions*, and evaluate to a value, when an unbound value is left at the end of each of their branches' scopes. This is particularly relevant for *functions*, where it is often idiomatic to omit an explicit `return` statement. There is no attempt made to differentiate without context, and so expressions and statements often look identical in syntax.
+All values in Puck must be handled, or explicitly discarded. This allows for conditional statements and many other control flow constructs to function as *expressions*: and evaluate to a value when an unbound value is left at the end of each of their branches' scopes. This is particularly relevant for *functions*, where it is often idiomatic to omit an explicit `return` statement. There is no attempt made to differentiate without context, and so expressions and statements often look identical in syntax.
 
 ```puck
 ```
@@ -118,11 +117,11 @@ type Result[T] = Result[T, ref Err]
 func may_fail: Result[T] = ...
 ```
 
-Error handling is done via a fusion of functional `Option`/`Result` types and imperative `try`/`catch` statements, with much syntactic sugar. Functions may `raise` errors, but by convention should return `Option[T]` or `Result[T, E]` types instead. The compiler will note functions that `raise` errors, and force explicit qualification of them via `try`/`catch` statements.
+Error handling is done via a fusion of functional monadic types and imperative exceptions, with much syntactic sugar. Functions may `raise` exceptions, but by convention should return `Option[T]` or `Result[T, E]` types instead: these may be handled in `match` or `if`/`of` statements. The compiler will track functions that `raise` errors, and warn on those that are not handled explicitly via `try`/`with` statements.
 
 A bevy of helper functions and macros are available for `Option`/`Result` types, and are documented and available in the `std.options` and `std.results` modules (included in the prelude by default). Two in particular are of note: the `?` macro accesses the inner value of a `Result[T, E]` or propagates (returns in context) the `Error(e)`, and the `!` accesses the inner value of an `Option[T]` / `Result[T, E]` or raises an error on `None` / the specific `Error(e)`. Both operators take one parameter and so are postfix. The `?` and `!` macros are overloaded and additionally function on types as shorthand for `Option[T]` and `Result[T]` respectively.
 
-The utility of the `?` macro is readily apparent to anyone who has written code in Rust or Swift. The utility of the `!` function is perhaps less so obvious. These errors raised by `!`, however, are known to the compiler: and they may be comprehensively caught by a single or sequence of `catch` statements. This allows for users used to a `try`/`catch` error handling style to do so with ease, with only the need to add one additional character to a function call.
+The utility of the `?` macro is readily apparent to anyone who has written code in Rust or Swift. The utility of the `!` function is perhaps less so obvious. These errors raised by `!`, however, are known to the compiler: and they may be comprehensively caught by a single or sequence of `catch` statements. This allows for users used to a `try`/`with` error handling style to do so with ease, with only the need to add one additional character to a function call.
 
 More details may be found in [error handling overview](ERRORS.md).
 
@@ -179,9 +178,7 @@ More details may be found in the [modules document](MODULES.md).
 ```puck
 ```
 
-Compile-time programming may be done via the previously-mentioned `const` keyword and `when` statements: or via `const` *blocks*. All code within a `const` block is evaluated at compile-time and all assignments and allocations made are propagated to the compiled binary as static data.
-
-Further compile-time programming may be done via metaprogramming: compile-time manipulation of the abstract syntax tree. The macro system is complex, and a description may be found in the [metaprogramming document](METAPROGRAMMING.md). <!-- todo -->
+Compile-time programming may be done via the previously-mentioned `const` keyword and `when` statements: or via `const` *blocks*. All code within a `const` block is evaluated at compile-time and all assignments and allocations made are propagated to the compiled binary as static data. Further compile-time programming may be done via macros: compile-time manipulation of the abstract syntax tree. The macro system is complex, and a description may be found in the [metaprogramming document](METAPROGRAMMING.md/).
 
 ## Async System and Threading
 
@@ -213,7 +210,9 @@ foo( # this is usually elided
 )
 ```
 
-Puck copies Rust-style ownership near verbatim. `&T` corresponds to `lent T`, `&mut T` to `mut T`, and `T` to `T`: with `T` implicitly convertible to `lent T` and `mut T` at call sites. A major goal of Puck is for all lifetimes to be inferred: there is no overt support for lifetime annotations, and it is likely code with strange lifetimes will be rejected before it can be inferred. (Total inference, however, *is* a goal.) Another major difference is the consolidation of `Box`, `Rc`, `Arc`, `Cell`, `RefCell` into just two (magic) types: `ref` and `refc`. `ref` takes the role of `Box`, and `refc` both the role of `Rc` and `Arc`: while `Cell` and `RefCell` are disregarded. The underlying motivation for compiler-izing these types is to make deeper compiler optimizations accessible: particularly with `refc`, where the existing ownership framework is used to eliminate counts. Details on memory safety, references and pointers, and deep optimizations may be found in the [memory management overview](MEMORY_MANAGEMENT.md).
+Puck copies Rust-style ownership near verbatim. `&T` corresponds to `lent T`, `&mut T` to `mut T`, and `T` to `T`: with `T` implicitly convertible to `lent T` and `mut T` at call sites. A major goal of Puck is for all lifetimes to be inferred: there is no overt support for lifetime annotations, and it is likely code with strange lifetimes will be rejected before it can be inferred. (Total inference, however, *is* a goal.)
+
+Another major difference is the consolidation of `Box`, `Rc`, `Arc`, `Cell`, `RefCell` into just two (magic) types: `ref` and `refc`. `ref` takes the role of `Box`, and `refc` both the role of `Rc` and `Arc`: while `Cell` and `RefCell` are disregarded. The underlying motivation for compiler-izing these types is to make deeper compiler optimizations accessible: particularly with `refc`, where the existing ownership framework is used to eliminate counts. Details on memory safety, references and pointers, and deep optimizations may be found in the [memory management overview](MEMORY_MANAGEMENT.md).
 
 ## Types System
 
diff --git a/docs/SYNTAX.md b/docs/SYNTAX.md
index 6561acb..4e57b04 100644
--- a/docs/SYNTAX.md
+++ b/docs/SYNTAX.md
@@ -1,6 +1,228 @@
 # Syntax: A Casual and Formal Look
 
-> ! This section is **incomplete**. Proceed with caution.
+## Call Syntax
+
+There is little difference between a function, macro, and operator call. There are only a few forms such calls can take, too, though notably more than most other languages (due to, among other things, uniform function call syntax): hence this section.
+
+```
+# The standard, unambiguous call.
+routine(1, 2, 3, 4)
+# The method call syntax equivalent.
+1.routine(2, 3, 4)
+# A block-based call. This is only really useful for macros taking in a body.
+routine
+  1
+  2
+  3
+  4
+# A parentheses-less call. This is only really useful for `print` and `dbg`.
+# Only valid at the start of a line.
+routine 1, 2, 3, 4
+```
+
+Binary operators have some special rules.
+
+```
+# Valid call syntaxes for binary operators. What can constitute a binary
+# operator is constrained for parsing's sake. Whitespace is optional.
+1 + 2
+1+2
++ 1, 2 # Only valid at the start of a line. Also, don't do this.
++(1, 2)
+```
+
+As do unary operators.
+
+```
+# The standard call for unary operators. Postfix.
+1?
+?(1)
+```
+
+Method call syntax has a number of advantages: notably that it can be *chained*: acting as a natural pipe operator. Redundant parenthesis can also be omitted.
+
+```
+# The following statements are equivalent:
+foo.bar.baz
+foo().bar().baz()
+baz(bar(foo))
+baz
+  bar
+    foo
+baz bar(foo)
+baz foo.bar
+```
+
+## Indentation Rules
+
+The tokens `=`, `then`, `do`, `of`, `else`, `block`, `const`, `block X`, and `X` (where `X` is an identifier) are *scope tokens*. They denote a new scope for their associated expressions (functions/macros/declarations, control flow, loops). The tokens `,`, `.` (notably not `...`), and all default binary operators (notably not `not`) are *continuation tokens*. An expression beginning or ending in one of them would always be a syntactic error.
+
+Line breaks are treated as the end of a statement, with several exceptions.
+
+```puck
+pub func foo() =
+  print "Hello, world!"
+  print "This is from a function."
+
+pub func inline_decl() = print "Hello, world!"
+```
+
+Indented lines following a line ending in a *scope token* are treated as belonging to a new scope. That is, indented lines following a line ending in a scope token form the body of the expression associated with the scope token.
+
+Indentation is not obligatory after a scope token. However, this necessarily constrains the body of the associated expression to one line: no lines following will be treated as an extension of the body, only the expression associated with the original scope token. (This may change in the future.)
+
+```puck
+pub func foo(really_long_parameter: ReallyLongType,
+another_really_long_parameter: AnotherReallyLongType) = # no indentation! this is ok
+  print really_long_parameter # this line is indented relative to the first line
+  print really_long_type
+```
+
+Lines following a line ending in a *continuation token* (and, additionally `not` and `(`) are treated as a continuation of that line and can have any level of indentation (even negative). If they end in a scope token, however, the following lines must be indented relative to the indentation of the previous line.
+
+```puck
+let really_long_parameter: ReallyLongType = ...
+let another_really_long_parameter: AnotherReallyLongType = ...
+
+really_long_parameter
+  .foo(another_really_long_parameter) # some indentation! this is ok
+```
+
+Lines *beginning* in a continuation token (and, additionally `)`), too, are treated as a continuation of the previous line and can have any level of indentation. If they end in a scope token, the following lines must be indented relative to the indentation of the previous line.
+
+```puck
+pub func foo() =
+  print "Hello, world!"
+pub func bar() = # this line is no longer in the above scope.
+  print "Another function declaration."
+```
+
+Dedented lines *not* beginning or ending with a continuation token are treated as no longer in the previous scope, returning to the scope of the according indentation level.
+
+```puck
+if cond then this
+else that
+
+match cond
+of this then ...
+of that then ...
+```
+
+A line beginning with a scope token is treated as attached to the previous expression.
+
+```
+# Technically allowed. Please don't do this.
+let foo
+= ...
+
+if cond then if cond then this
+else that
+
+for i
+in iterable
+do ...
+
+match foo of this then ...
+of that then ...
+
+match foo of this
+then ...
+of that then ...
+```
+
+This *can* lead to some ugly possibilities for formatting that are best avoided.
+
+```
+# Much preferred.
+
+let foo =
+  ...
+let foo = ...
+
+if cond then
+  if cond then
+    this
+else that
+if cond then
+  if cond then this
+else that
+
+for i in iterable do
+  ...
+for i in iterable do ...
+
+match foo
+of this then ...
+of that then ...
+```
+
+The indentation rules are complex, but the effect is such that long statements can be broken *almost* anywhere.
+
+## Expression Rules
+
+First, a word on the distinction between *expressions* and *statements*. Expressions return a value. Statements do not. That is all.
+
+There are some syntactic constructs unambiguously recognizable as statements: all declarations, modules, and `use` statements. There are no syntactic constructs unambiguously recognizable as expressions. As calls returning `void` are treated as statements, and expressions that return a type could possibly return `void`, there is no explicit distinction between expressions and statements made in the parser: or anywhere before type-checking.
+
+Expressions can go almost anywhere. Our indentation rules above allow for it.
+
+```
+# Some different formulations of valid expressions.
+
+if cond then
+  this
+else
+  that
+
+if cond then this
+else that
+
+if cond
+then this
+else that
+
+if cond then this else that
+
+let foo =
+  if cond then
+    this
+  else
+    that
+```
+
+```
+# Some different formulations of *invalid* expressions.
+# These primarily break the rule that everything following a scope token
+# (ex. `=`, `do`, `then`) not at the end of the line must be self-contained.
+
+let foo = if cond then
+    this
+  else
+    that
+
+let foo = if cond then this
+  else that
+
+let foo = if cond then this
+else that
+
+# todo: how to handle this?
+if cond then if cond then that
+else that
+
+# shrimple
+if cond then
+  if cond then that
+else that
+
+# this should be ok
+if cond then this
+else that
+
+match foo of
+this then ...
+of that then ...
+```
 
 ## Reserved Keywords
 
@@ -8,26 +230,25 @@ The following keywords are reserved:
 - variables: `let` `var` `const`
 - control flow: `if` `then` `elif` `else`
 - pattern matching: `match` `of`
-- error handling: `try` `catch` `finally`
+- error handling: `try` `with` `finally`
 - loops: `while` `do` `for` `in`
 - blocks: `loop` `block` `break` `continue` `return`
 - modules: `pub` `mod` `use` `as`
 - functions: `func` `varargs`
-- metaprogramming: `macro` `quote` `static` `when`
+- metaprogramming: `macro` `quote` `when`
 - ownership: `lent` `mut` `ref` `refc`
-- types: `type` `distinct` `struct` `tuple` `union` `enum` `class`
-- reserved:
-  - `impl` `object` `interface` `concept` `auto` `empty` `effect` `case`
-  - `suspend` `resume` `spawn` `pool` `thread` `closure`
-  - `cyclic` `acyclic` `sink` `move` `destroy` `copy` `trace` `deepcopy`
+- types: `type` `struct` `tuple` `union` `enum` `class`
+
+The following keywords are not reserved, but liable to become so.
+- `impl` `object` `interface` `concept` `auto` `effect` `case`
+- `suspend` `resume` `spawn` `pool` `thread` `closure` `static`
+- `cyclic` `acyclic` `sink` `move` `destroy` `copy` `trace` `deepcopy`
 
 The following identifiers are in use by the standard prelude:
 - logic: `not` `and` `or` `xor` `shl` `shr` `div` `mod` `rem`
 - logic: `+` `-` `*` `/` `<` `>` `<=` `>=` `==` `!=` `is`
 - async: `async` `await`
-- types: `int` `uint` `float`
-  - `i8` `i16` `i32` `i64` `i128`
-  - `u8` `u16` `u32` `u64` `u128`
+- types: `int` `uint` `float` `i\d+` `u\d+`
   - `f32` `f64` `f128`
   - `dec64` `dec128`
 - types: `bool` `byte` `char` `str`
@@ -51,7 +272,8 @@ The following punctuation is taken:
 - `""` (strings)
 - `''` (chars)
 - ``` `` ``` (unquoting)
-- unused: `~` `$` `%`
+- unused on qwerty: `~` `%` `^` `$`
+  - perhaps leave `$` unused. but `~`, `%`, and `^` totally could be...
 
 ## A Formal Grammar
 
@@ -99,8 +321,8 @@ PRINT ::= LETTER | DIGIT | OPR |
 ```
 Value ::= Int | Float | String | Char | Array | Tuple | Struct
 Array  ::= '[' (Expr (',' Expr)*)? ']'
-Tuple  ::= '(' (Ident ':')? Expr (',' (Ident ':')? Expr)* ')'
-Struct ::= '{' Ident ':' Expr (',' Ident ':' Expr)* '}'
+Tuple  ::= '(' (Ident '=')? Expr (',' (Ident '=')? Expr)* ')'
+Struct ::= '{' Ident '=' Expr (',' Ident '=' Expr)* '}'
 ```
 
 ### Variables
@@ -109,8 +331,8 @@ Decl  ::= Let | Var | Const | Func | Type
 Let   ::= 'let' Pattern (':' Type)? '=' Expr
 Var   ::= 'var' Pattern (':' Type)? ('=' Expr)?
 Const ::= 'pub'? 'const' Pattern (':' Type)? '=' Expr
-Pattern ::= Char | String | Number | Float | Ident | '(' Pattern (',' Pattern)* ')'
-            Ident '(' Pattern (',' Pattern)* ')'
+Pattern ::= (Ident ('as' Ident)?) | Char | String | Number | Float |
+            Ident? '(' Pattern (',' Pattern)* ')'
 ```
 
 ### Declarations
@@ -121,20 +343,20 @@ Generics   ::= '[' Ident (':' Type)? (',' Ident (':' Type)?)* ']'
 Parameters ::= '(' Ident (':' Type)? (',' Ident (':' Type)?)* ')'
 ```
 
-All arguments to functions must have a type. This is resolved at the semantic level, however.
-(Arguments to macros may lack types. This signifies a generic node.)
+All arguments to functions must have a type. This is resolved at the semantic level, however. (Arguments to macros may lack types. This signifies a generic node.)
 
 ### Types
 ```
 TypeDecl ::= 'pub'? 'type' Ident Generics? '=' Type
-Type     ::= TypeStruct | TypeTuple | TypeEnum | TypeUnion | TypeClass |
-             (Modifier* (Type | ('[' Type ']')))
+Type     ::= TypeStruct | TypeTuple | TypeEnum | TypeUnion | SugarUnion |
+             TypeClass | (Modifier* (Type | ('[' Type ']')))
 TypeStruct ::= 'struct' ('[' Ident ':' Type (',' Ident ':' Type)* ']')?
 TypeUnion  ::= 'union'  ('[' Ident ':' Type (',' Ident ':' Type)* ']')?
+SugarUnion ::= '(' Ident ':' Type (',' Ident ':' Type)* ')'
 TypeTuple  ::= 'tuple' ('[' (Ident ':')? Type (',' (Ident ':')? Type)* ']')?
 TypeEnum   ::= 'enum'  ('[' Ident ('=' Expr)? (',' Ident ('=' Expr)?)* ']')?
 TypeClass  ::= 'class' ('[' Signature (',' Signature)* ']')?
-Modifier   ::= 'distinct' | 'ref' | 'refc' | 'ptr' | 'lent' | 'mut' | 'static'
+Modifier   ::= 'ref' | 'refc' | 'ptr' | 'lent' | 'mut' | 'const'
 Signature  ::= Ident Generics? ('(' Type (',' Type)* ')')? (':' Type)?
 ```
 
@@ -150,13 +372,13 @@ While  ::= 'while' Expr 'do' Body
 For    ::= 'for' Pattern 'in' Expr 'do' Body
 Loop   ::= 'loop' Body
 Block  ::= 'block' Ident? Body
-Static ::= 'static' Body
+Const  ::= 'const' Body
 Quote  ::= 'quote' QuoteBody
 ```
 
 ## Modules
 ```
-Mod ::= 'pub'? 'mod' Ident Body
+Mod ::= 'pub'? 'mod' Ident '=' Body
 Use ::= 'use' Ident ('.' Ident)* ('.' ('[' Ident (',' Ident)* ']'))?
 ```
 
@@ -170,14 +392,17 @@ Opr ::= '=' | '+' | '-' | '*' | '/' | '<' | '>' |
 ```
 
 ## Calls and Expressions
+
+This section is (quite) inaccurate due to complexities with respect to significant indentation. Heed caution.
+
 ```
 Call ::= Ident ('[' Call (',' Call)* ']')? ('(' (Ident '=')? Call (',' (Ident '=')? Call)* ')')? |
          Ident Call (',' Call)* |
          Call Operator Call? |
          Call Body
-Expr ::= Let | Var | Const | Func | Type | Mod | Use | Block | Static |
-         For | While | Loop | If | When | Try | Match | Call
-Body ::= Expr | (Expr (';' Expr)*)
+Stmt ::= Let | Var | Const | Func | Type | Mod | Use | Expr
+Expr ::= Block | Const | For | While | Loop | If | When | Try | Match | Call
+Body ::= (Stmt ';')* Expr
 ```
 
 ---
diff --git a/docs/TYPES.md b/docs/TYPES.md
index 17d5d6a..5ea320a 100644
--- a/docs/TYPES.md
+++ b/docs/TYPES.md
@@ -8,23 +8,22 @@ Puck has a comprehensive static type system, inspired by the likes of Nim, Rust,
 
 Basic types can be one-of:
 - `bool`: internally an enum.
-- `int`: integer number. x bits of precision by default. <!-- - overflow into bigints for safety and ease of cryptographical code. -->
+- `int`: integer number. x bits of precision by default.
   - `uint`: same as `int`, but unsigned for more precision.
-  - `i8`, `i16`, `i32`, `i64`, `i128`: specified integer size
-  - `u8`, `u16`, `u32`, `u64`, `u128`: specified integer size
+  - `i[\d+]`, `u[\d+]`: arbitrarily sized integers
 - `float`: floating-point number.
   - `f32`, `f64`: specified float sizes
-- `decimal`: precision decimal number. <!-- https://en.wikipedia.org/wiki/IEEE_754 -->
+- `decimal`: precision decimal number.
   - `dec32`, `dec64`, `dec128`: specified decimal sizes
 - `byte`: an alias to `u8`.
-- `char`: a distinct alias to `u32`. For working with Unicode. <!-- - these are *packed* when part of a string: and so indexing directly into a string is a no-op. string access is O(n), swift-style. -->
-- `str`: a string type. mutable. internally a byte-array: externally a char-array.
-- `void`: an internal type designating the absence of a value. often elided. <!-- - possibly, the empty tuple. then would `empty` be better? or `unit`? -->
-- `never`: a type that denotes functions that do not return. distinct from returning nothing. <!-- - the bottom type. -->
+- `char`: an alias to `u32`. For working with Unicode.
+- `str`: a string type. mutable. packed: internally a byte-array, externally a char-array.
+- `void`: an internal type designating the absence of a value. often elided.
+- `never`: a type that denotes functions that do not return. distinct from returning nothing.
 
 `bool` and `int`/`uint`/`float` and siblings (and subsequently `byte` and `char`) are all considered **primitive types** and are _always_ copied (unless passed as mutable). More on when parameters are passed by value vs. passed by reference can be found in the [memory management document](MEMORY_MANAGEMENT.md).
 
-Primitive types combine with `str`, `void`, and `never` to form **basic types**. `void` and `never` will rarely be referenced by name: instead, the absence of a type typically implicitly denotes one or the other. Still, having a name is helpful in some situations.
+Primitive types, alongside `str`, `void`, and `never`, form **basic types**. `void` and `never` will rarely be referenced by name: instead, the absence of a type typically implicitly denotes one or the other. Still, having a name is helpful in some situations.
 
 ### integers
 
@@ -37,7 +36,7 @@ Strings are:
 - internally a byte array
 - externally a char (four bytes) array
 - prefixed with their length and capacity
-- automatically resize like a list
+- automatically resize
 
 They are also quite complicated. Puck has full support for Unicode and wishes to be intuitive, performant, and safe, as all languages wish to be. Strings present a problem that much effort has been expended on in (primarily) Swift and Rust to solve.
 
@@ -48,9 +47,9 @@ Abstract types, broadly speaking, are types described by their *behavior* rather
 ### iterable types
 
 Iterable types can be one-of:
-- `array[S, T]`: Fixed-size arrays. Can only contain one type `T`. Of a fixed size `S` and cannot grow/shrink, but can mutate. Initialized in-place with `[a, b, c]`.
-- `list[T]`: Dynamic arrays. Can only contain one type `T`. May grow/shrink dynamically. Initialized in-place with `[a, b, c]`. (this is the same as arrays!) <!-- Disambiguated from arrays in much the same way uints are disambiguated from ints. -->
-- `slice[T]`: Slices. Used to represent a "view" into some sequence of elements of type `T`. Cannot be directly constructed: they are **unsized**. Cannot grow/shrink, but their elements may be accessed and mutated. As they are underlyingly a reference to an array or list, they **must not** outlive the data they reference: this is non-trivial, and so slices interact in complex ways with the memory management system. <!-- possible syntax sugar: `[T]` -->
+- `array[T, size]`: Fixed-size arrays. Can only contain one type `T`. Of a fixed size `size` and cannot grow/shrink, but can mutate. Initialized in-place with `[a, b, c]`.
+- `list[T]`: Dynamic arrays. Can only contain one type `T`. May grow/shrink dynamically. Initialized in-place with `[a, b, c]`. (this is the same as arrays!)
+- `slice[T]`: Slices. Used to represent a "view" into some sequence of elements of type `T`. Cannot be directly constructed: they are **unsized**. Cannot grow/shrink, but their elements may be accessed and mutated. As they are underlyingly a reference to an array or list, they **must not** outlive the data they reference: this is non-trivial, and so slices interact in complex ways with the memory management system.
 - `str`: Strings. Described above. They are alternatively treated as either `list[byte]` or `list[char]`, depending on who's asking. Initialized in-place with `"abc"`.
 
 These iterable types are commonly used, and bits and pieces of compiler magic are used here and there (mostly around initialization, and ownership) to ease use. All of these types are some sort of sequence: and implement the `Iter` interface, and so can be iterated (hence the name).
@@ -77,12 +76,12 @@ These are monomorphized into more specific functions at compile-time if needed.
 
 Parameter types can be one-of:
 - mutable: `func foo(a: mut str)`: Marks a parameter as mutable (parameters are immutable by default). Passed as a `ref` if not one already.
-- static: `func foo(a: static str)`: Denotes a parameter whose value must be known at compile-time. Useful in macros, and with `when` for writing generic code.
+- constant: `func foo(a: const str)`: Denotes a parameter whose value must be known at compile-time. Useful in macros, and with `when` for writing generic code.
 - generic: `func foo[T](a: list[T], b: T)`: The standard implementation of generics, where a parameter's exact type is not listed, and instead statically dispatched based on usage.
 - constrained: `func foo(a: str | int | float)`: A basic implementation of generics, where a parameter can be one-of several listed types. The only allowed operations on such parameters are those shared by each type. Makes for particularly straightforward monomorphization. <!-- - Separated with the bitwise or operator `|` rather than the symbolic or `||` or a raw `or` to give the impression that there isn't a corresponding "and" operation (the `&` operator is preoccupied with strings). -->
 - functions: `func foo(a: (int, int) -> int)`: First-class functions. All functions are first class - function declarations implicitly have this type, and may be bound in variable declarations. However, the function *type* is only terribly useful as a parameter type.
 - slices: `func foo(a: slice[...])`: Slices of existing lists, strings, and arrays. Generic over length. These are references under the hood, may be either immutable or mutable (with `mut`), and interact non-trivially with Puck's [ownership system](MEMORY_MANAGEMENT.md).
-- interfaces: `func foo(a: Stack[int])`: Implicit typeclasses. More in the [interfaces section](#interfaces).
+- classes: `func foo(a: Stack[int])`: Implicit typeclasses. More in the [classes section](#classes).
   - ex. for above: `type Stack[T] = interface[push(mut Self, T); pop(mut Self): T]`
 - built-in interfaces: `func foo(a: struct)`: Included, special interfaces for being generic over [advanced types](#advanced-types). These include `struct`, `tuple`, `union`, `enum`, `interface`, and others.
 
@@ -93,39 +92,40 @@ Several of these parameter types - specifically, slices, functions, and interfac
 Functions can take a _generic_ type, that is, be defined for a number of types at once:
 
 ```puck
-func add[T](a: list[T], b: T) =
-  return a.add(b)
+# fully generic. monomorphizes based on usage.
+func add[T](a: list[T], b: T) = a.push(b)
 
-func length[T](a: T) =
-  return a.len # monomorphizes based on usage.
-  # lots of things use .len, but only a few called by this do.
-  # throws a warning if exported for lack of specitivity.
+# constrained generics. restricts possible operations to the intersection
+# of defined methods on each type.
+func length[T](a: str | list[T]) =
+  a.len # both strings and lists have a `len` method
 
-func length(a: str | list) =
-  return a.len
+# alternative formulation: place the constraint on a generic parameter.
+# this ensures both a and b are of the *same* type.
+func add[T: int | float](a: T, b: T) = a + b
 ```
 
-The syntax for generics is `func`, `ident`, followed by the names of the generic parameters in brackets `[T, U, V]`, followed by the function's parameters (which may then refer to the generic types).
-Generics are replaced with concrete types at compile time (monomorphization) based on their usage in function calls within the main function body.
+The syntax for generics is `func`, `ident`, followed by the names of the generic parameters in brackets `[T, U, V]`, followed by the function's parameters (which may then refer to the generic types). Generics are replaced with concrete types at compile time (monomorphization) based on their usage in function calls within the main function body.
 
 Constrained generics have two syntaxes: the constraint can be defined directly on a parameter, leaving off the `[T]` box, or it may be defined within the box as `[T: int | float]` for easy reuse in the parameters.
 
-Other constructions like modules and type declarations themselves may also be generic.
+Other constructions like type declarations themselves may also be generic over types. In the future, modules also may be generic: whether that is to be over types or over other modules is to be determined.
 
 ## Reference Types
 
-Types are typically constructed by value on the stack. That is, without any level of indirection: and so type declarations that recursively refer to one another, or involve unsized types (notably including parameter types), would not be allowed. However, Puck provides two avenues for indirection.
+Types are typically constructed by value on the stack. That is, without any level of indirection: and so type declarations that recursively refer to one another, or involve unsized types (notably including parameter types), would not be allowed. However, Puck provides several avenues for indirection.
 
 Reference types can be one-of:
-- `ref T`: An automatically-managed reference to type `T`. This is a pointer of size `uint` (native).
-- `ptr T`: A manually-managed pointer to type `T`. (very) unsafe. The compiler will yell at you.
+- `ref T`: An owned reference to a type `T`. This is a pointer of size `uint` (native).
+- `refc T`: A reference-counted reference to a type `T`. This allows escaping the borrow checker.
+- `ptr T`: A manually-managed pointer to a type `T`. (very) unsafe. The compiler will yell at you.
 
 ```puck
 type BinaryTree = ref struct
   left: BinaryTree
   right: BinaryTree
 
-type AbstractTree[T] = interface
+type AbstractTree[T] = class
   func left(self: Self): Option[AbstractTree[T]]
   func right(self: Self): Option[AbstractTree[T]]
   func data(self: Self): T
@@ -142,71 +142,77 @@ type UnsafeTree = struct
 
 The `ref` prefix may be placed at the top level of type declarations, or inside on a field of a structural type. `ref` types may often be more efficient when dealing with large data structures. They also provide for the usage of unsized types (functions, interfaces, slices) within type declarations.
 
-The compiler abstracts over `ref` types to provide optimization for reference counts: and so a distinction between `Rc`/`Arc`/`Box` is not needed. Furthermore, access implicitly dereferences (with address access available via `.addr`), and so a `*` dereference operator is also not needed. Much care has been given to make references efficient and safe, and so `ptr` should be avoided if at all possible. The compiler will yell at you if you use it (or any other unsafe features).
+The compiler abstracts over `ref` types to provide optimization for reference counts: and so a distinction between `Rc`/`Arc`/`Box` is not needed. Furthermore, access implicitly dereferences (with address access available via `.addr`), and so a `*` dereference operator is also not needed.
 
-The implementation of `ref` is delved into in further detail in the [memory management document](MEMORY_MANAGEMENT.md).
+
+Much care has been given to make references efficient and safe, and so `ptr` should be avoided if at all possible. They are only usable inside functions explicitly marked with `#[safe]`.
+
+The implementations of reference types are delved into in further detail in the [memory management document](MEMORY_MANAGEMENT.md).
 
 ## Advanced Types
 
-The `type` keyword is used to declare aliases to custom data types. These types are *algebraic*: they function by composition. Algebraic data types can be one-of:
+The `type` keyword is used to declare aliases to custom data types. These types are *algebraic*: they function by *composition*. Such *algebraic data types* can be one-of:
 - `struct`: An unordered, named collection of types. May have default values.
 - `tuple`: An ordered collection of types. Optionally named.
 - `enum`: Ordinal labels, that may hold values. Their default values are their ordinality.
 - `union`: Powerful matchable tagged unions a la Rust. Sum types.
-- `interface`: Implicit typeclasses. User-defined duck typing.
+- `class`: Implicit type classes. User-defined duck typing.
+
+All functions defined on the original type carry over. If this is not desired, the newtype paradigm is preferred: declaring a single-field `struct` and copying function declarations over.
 
-There also exist `distinct` types: while `type` declarations define an alias to an existing or new type, `distinct` types define a type that must be explicitly converted to/from. This is useful for having some level of separation from the implicit interfaces that abound.
+Types may be explicitly to and from via the `Coerce` and `Convert` classes and provided `from` and `to` functions.
 
 ### structs
 
 Structs are an *unordered* collection of named types.
 
-They are declared with `struct[identifier: Type, ...]` and initialized with brackets: `{field: "value", another: 500}`.
+They are declared with `struct[identifier: Type, ...]` and initialized with brackets: `{ field = "value", another = 500}`. Structs are *structural*: while the type system is fundamentally nominal, and different type declarations are treated as distinct, a struct object initialized with `{}` is usable in any context that expects a struct with the same fields.
 
 ```puck
-type LinkedNode[T] = struct
-  previous, next: Option[ref LinkedNode[T]]
+type LinkedNode[T] = ref struct
+  previous: Option[LinkedNode[T]]
+  next: Option[LinkedNode[T]]
   data: T
 
-let node = {
-  previous: None, next: None
-  data: 413
+let node = { # inferred type: LinkedNode[int], from prints_data call
+  previous = None, next = None
+  data = 413
 }
 
 func pretty_print(node: LinkedNode[int]) =
   print node.data
-  if node.next of Some(node):
+  if node.next of Some(node) then
     node.pretty_print()
 
 # structural typing!
 prints_data(node)
 ```
 
-Structs are *structural* and so structs composed entirely of fields with the same signature (identical in name and type) are considered *equivalent*.
-This is part of a broader structural trend in the type system, and is discussed in detail in the section on [subtyping](#subtyping).
-
 ### tuples
 
 Tuples are an *ordered* collection of either named and/or unnamed types.
 
-They are declared with `tuple[Type, identifier: Type, ...]` and initialized with parentheses: `(413, "hello", value: 40000)`. Syntax sugar allows for them to be declared with `()` as well.
+They are declared with `tuple[Type, identifier: Type, ...]` and initialized with parentheses: `(413, "hello", value: 40000)`. Syntactic sugar allows for them to be declared with `()` as well.
 
-They are exclusively ordered - named types within tuples are just syntax sugar for positional access. Passing a fully unnamed tuple into a context that expects a tuple with a named parameter is allowed so long as the types line up in order.
+They are exclusively ordered - named types within tuples are just syntactic sugar for positional access. Passing a fully unnamed tuple into a context that expects a tuple with a named parameter is allowed (so long as the types line up).
 
 ```puck
 let grouping = (1, 2, 3)
 
-func foo: tuple[string, string] = ("hello", "world")
+func foo: tuple[str, str] = ("hello", "world")
+dbg grouping.foo # prints '("hello", "world")'
+
+func bar(a: (str, str)) = a.1
+dbg grouping.bar # prints '"world"'
 ```
 
-Tuples are particularly useful for "on-the-fly" types. Creating type aliases to tuples is discouraged - structs are generally a better choice for custom type declarations.
+Tuples are particularly useful for "on-the-fly" types. Creating type declarations to tuples is discouraged - structs are generally a better choice, as they are fully named, support default values, and may have their layout optimized by the compiler.
 
 ### enums
 
 Enums are *ordinal labels* that may have *associated values*.
 
-They are declared with `enum[Label, AnotherLabel = 4, ...]` and are never initialized (their values are known statically).
-Enums may be accessed directly by their label, and are ordinal and iterable regardless of their associated value. They are useful in collecting large numbers of "magic values", that would otherwise be constants.
+They are declared with `enum[Label, AnotherLabel = 4, ...]` and are never initialized (their values are known statically). Enums may be accessed directly by their label, and are ordinal and iterable regardless of their associated value. They are useful in collecting large numbers of "magic values" that would otherwise be constants.
 
 ```puck
 type Keys = enum
@@ -249,21 +255,21 @@ use std.tables
 
 func eval(context: mut HashTable[Ident, Value], expr: Expr): Result[Value]
   match expr
-  of Literal(value): Okay(value)
-  of Variable(ident):
+  of Literal(value) then Okay(value)
+  of Variable(ident) then
     context.get(ident).err("Variable not in context")
-  of Application(body, arg):
+  of Application(body, arg) then
     if body of Abstraction(param, body as inner_body):
       context.set(param, context.eval(arg)?) # from std.tables
       context.eval(inner_body)
-    else:
+    else
       Error("Expected Abstraction, found {}".fmt(body))
   of Conditional(condition, then_case, else_case):
-    if context.eval(condition)? == "true":
+    if context.eval(condition)? == "true" then
       context.eval(then_case)
     else:
       context.eval(else_case)
-  of expr:
+  of expr then
     Error("Invalid expression {}".fmt(expr))
 ```
 
@@ -271,54 +277,55 @@ The match statement takes exclusively a list of `of` sub-expressions, and checks
 
 The `of` *operator* is similar to the `is` operator in that it queries type equality, returning a boolean. However, unbound identifiers within `of` expressions are bound to appropriate values (if matched) and injected into the scope. This allows for succinct handling of `union` types in situations where `match` is overkill.
 
-Each branch of a match expression can also have a *guard*: an arbitrary conditional that must be met in order for it to match. Guards are written as `where cond` and immediately follow the last pattern in an `of` branch, preceding the colon.
+Each branch of a match expression can also have a *guard*: an arbitrary conditional that must be met in order for it to match. Guards are written as `where cond` and immediately follow the last pattern in an `of` branch, preceding `then`.
 
-### interfaces
+### classes
 
-Interfaces can be thought of as analogous to Rust's traits, without explicit `impl` blocks and without need for the `derive` macro. Types that have functions fulfilling the interface requirements implicitly implement the associated interface.
+Classes can be thought of as analogous to Rust's traits: without explicit `impl` blocks and without need for the `derive` macro. Types that have functions defined on them fulfilling the class requirements implicitly implement the associated class.
 
-The `interface` type is composed of a list of function signatures that refer to the special type `Self` that must exist for a type to be valid. The special type `Self` is replaced with the concrete type at compile time in order to typecheck. They are declared with `interface[signature, ...]`.
+The `class` type is composed of a list of function signatures that refer to the special type `Self` that must exist for a type to be valid. The special type `Self` is replaced with the concrete type at compile time in order to typecheck. They are declared with `class[signature, ...]`.
 
 ```puck
-type Stack[T] = interface
+type Stack[T] = class
   push(self: mut Self, val: T)
   pop(self: mut Self): T
-  peek(self: Self): T
+  peek(self: lent Self): lent T
 
 func takes_any_stack(stack: Stack[int]) =
-  # only stack.push, stack.pop, and stack.peek are available methods
+  # only stack.push, stack.pop, and stack.peek are available, regardless of the concrete type passed
 ```
 
-Differing from Rust, Haskell, and many others, there is no explicit `impl` block. If there exist functions for a type that satisfy all of an interface's signatures, it is considered to match and the interface typechecks. This may seem strange and ambiguous - but again, static typing and uniform function call syntax help make this a more reasonable design. The purpose of explicit `impl` blocks in ex. Rust is three-fold: to provide a limited form of uniform function call syntax; to explicitly group together associated code; and to disambiguate. UFCS provides for the first, the module system provides for the second, and the third is proposed to not matter.
-
-Interfaces cannot be constructed because they are **unsized**. They serve purely as a list of valid operations on a type within a context: no information about their memory layout is relevant. The concrete type fulfilling an interface is known at compile time, however, and so there are no issues surrounding interfaces as parameters, just when attempted to be used as (part of) a concrete type. They can be used as part of a concrete type with *indirection*, however: `type Foo = struct[a: int, b: ref interface[...]]` is perfectly valid.
-
-Interfaces also *cannot* extend or rely upon other interfaces in any way. There is no concept of an interface extending an interface. There is no concept of a parameter satisfying two interfaces. In the author's experience, while such constructions are powerful, they are also an immense source of complexity, leading to less-than-useful interface hierarchies seen in languages like Java, and yes, Rust.
-
-Instead, if one wishes to form an interface that *also* satisfies another interface, they must include all of the other interface's associated functions within the new interface. Given that interfaces overwhelmingly only have a handful of associated functions, and if you're using more than one interface you *really* should be using a concrete type, the hope is that this will provide explicitness.
-
-<!-- While functions are the primary way of performing operations on types, they are not the only way, and listing all explicitly can be painful - instead, it can be desired to be able to *associate a type* and any field access or existing functions on that type with the interface. todo: i have not decided on the syntax for this yet. -->
-
-Interfaces compose with [modules](MODULES.md) to offer fine grained access control.
-
-<!-- todo: I have not decided whether the names of parameters is / should be relevant, or enforcable, or present. I'm leaning towards them not being present. But if they are enforcable, it makes it harder to implicitly implement the wrong interface. Design notes to consider: https://blog.rust-lang.org/2015/05/11/traits.html -->
-
-### type aliases and distinct types
-
-Any type can be declared as an *alias* to a type simply by assigning it to such. All functions defined on the original type carry over, and functions expecting one type may receive the other with no issues.
+Differing from Rust, Haskell, and many others, there is no explicit `impl` block. If there exist functions for a type that satisfy all of a class's signatures, it is considered to match and the class typechecks. This may seem strange and ambiguous - but again, static typing and uniform function call syntax help make this a more reasonable design. The purpose of explicit `impl` blocks in ex. Rust is three-fold: to provide a limited form of uniform function call syntax; to explicitly group together associated code; and to disambiguate. UFCS provides for the first, the module system provides for the second, and type-based disambiguation provides for the third, with such information exposed to the user via the language server protocol.
 
 ```puck
-type Float = float
+type Set[T] = class
+  in(lent Self, T): bool
+  add(mut Self, T)
+  remove(mut Self, T): Option[T]
+
+type Foo = struct
+  a: int
+  b: ref Set[int] # indirection: now perfectly valid
 ```
 
-It is no more than an alias. When explicit conversion between types is desired and functions carrying over is undesired, `distinct` types may be used.
+Classes cannot be constructed, as they are **unsized**. They serve purely as a list of valid operations on a type: no information about their memory layout is relevant. The *concrete type* fulfilling a class is known at compile time, however, and so there are no issues surrounding the use of classes as parameters, just when attempted to be used as (part of) a concrete type in ex. a struct. They can be used with *indirection*, however: as references are sized (consisting of a memory address).
 
 ```puck
-type MyFloat = distinct float
-let foo: MyFloat = MyFloat(192.68)
+## The Display class. Any type implementing `str` is printable.
+## Any type that is Display must necessarily also implement Debug.
+pub type Display = class
+  str(Self): str
+  dbg(Self): str
+
+## The Debug class. Broadly implemented for every type with compiler magic.
+## Types can (and should) override the generic implementations.
+pub type Debug = class
+  dbg(Self): str
 ```
 
-Types then must be explicitly converted via constructors.
+Classes also *cannot* extend or rely upon other classes in any way, nor is there any concept of a parameter satisfying two classes. In the author's experience, while such constructions are powerful, they are also an immense source of complexity, leading to less-than-useful hierarchies seen in languages like Java, and yes, Rust. Instead, if one wishes to form an class that *also* satisfies another class, they must name a new class that explicitly includes all of the other class's associated functions. Given that classes in Puck overwhelmingly only have a small handful of associated functions, and if you're using more than one class you *really* should be using a concrete type: the hope is that this will provide for explicitness and reduce complexity.
+
+Classes compose well with [modules](MODULES.md) to offer fine grained access control.
 
 ## Errata
 
@@ -338,10 +345,10 @@ But always explicitly initializing types is syntactically verbose, and so most t
 - `set[T]`, `table[T, U]`: `{}`
 - `tuple[T, U, ...]`: `(default values of its fields)`
 - `struct[T, U, ...]`: `{default values of its fields}`
-- `enum[One, Two, ...]`: `<first label>`
+- `enum[One, Two, ...]`: **disallowed**
 - `union[T, U, ...]`: **disallowed**
 - `slice[T]`, `func`: **disallowed**
-- `ref`, `ptr`: **disallowed**
+- `ref`, `refc`, `ptr`: **disallowed**
 
 For unions, slices, references, and pointers, this is a bit trickier. They all have no reasonable "default" for these types *aside from* null.
 Instead of giving in, the compiler instead disallows any non-initializations or other cases in which a default value would be inserted.
@@ -350,72 +357,15 @@ todo: consider user-defined defaults (ex. structs)
 
 ### signatures and overloading
 
-Puck supports *overloading* - that is, there may exist multiple functions, or multiple types, or multiple modules, so long as they have the same *signature*.
-The signature of a function / type / module is important. Interfaces, among other constructs, depend on the user having some understanding of what the compiler considers to be a signature.
-So, it is stated here explicitly:
-- The signature of a function is its name and the *types* of each of its parameters, in order. Optional parameters are ignored. Generic parameters are ???
+Puck supports *overloading* - that is, there may exist multiple functions, or multiple types, or multiple modules, with the same name - so long as they have a different *signature*.
+The signature of a function/type/module is important. Classes, among other constructs, depend on the user having some understanding of what the compiler considers to be a signature. So we state it here explicitly:
+- The signature of a function is its name and the *types* of each of its parameters, in order, ignoring optional parameters. Generic parameters are ???
   - ex. ...
 - The signature of a type is its name and the number of generic parameters.
   - ex. both `Result[T]` and `Result[T, E]` are defined in `std.results`
 - The signature of a module is just its name. This may change in the future.
 
-### subtyping
+### structural subtyping
 
 Mention of subtyping has been on occasion in contexts surrounding structural type systems, particularly the section on distinct types, but no explicit description of what the subtyping rules are have been given.
 
-Subtyping is the implicit conversion of compatible types, usually in a one-way direction. The following types are implicitly convertible:
-- `uint` ==> `int`
-- `int` ==> `float`
-- `uint` ==> `float`
-- `string` ==> `list[char]` (the opposite no, use `pack`)
-- `array[T; n]` ==> `list[T]`
-- `struct[a: T, b: U, ...]` ==> `struct[a: T, b: U]`
-- `union[A: T, B: U]` ==> `union[A: T, B: U, ...]`
-
-### inheritance
-
-Puck is not an object-oriented language. Idiomatic design patterns in object-oriented languages are harder to accomplish and not idiomatic here.
-
-But, Puck has a number of features that somewhat support the object-oriented paradigm, including:
-- uniform function call syntax
-- structural typing / subtyping
-- interfaces
-
-```puck
-type Building = struct
-  size: struct[length, width: uint]
-  color: enum[Red, Blue, Green]
-  location: tuple[longitude, latitude: float]
-
-type House = struct
-  size: struct[length, width: uint]
-  color: enum[Red, Blue, Green]
-  location: tuple[longitude, latitude: float]
-  occupant: str
-
-func init(_: type[House]): House =
-  { size: {length, width: 500}, color: Red
-    location: (0.0, 0.0), occupant: "Barry" }
-
-func address(building: Building): str =
-  let number = int(building.location.0 / building.location.1).abs
-  let street = "Logan Lane"
-  return number.str & " " & street
-
-# subtyping! methods!
-print House.init().address()
-
-func address(house: House): str =
-  let number = int(house.location.0 - house.location.1).abs
-  let street = "Logan Lane"
-  return number.str & " " & street
-
-# overriding! (will warn)
-print address(House.init())
-
-# abstract types! inheritance!
-type Addressable = interface for Building
-  func address(self: Self)
-```
-
-These features may *compose* into code that closely resembles its object-oriented counterpart. But make no mistake! Puck is static first and functional somewhere in there: dynamic dispatch and the like are not accessible (currently).