flan/spec-memory.md

# Spec 1 — Ownership, containers, and copies

Status: **frozen**. Closes plan.org open decisions #6 and #10, and resolves the
contradiction between "value structs copy on assignment" and owning containers.
Everything else in the design references this vocabulary.

## The four container types

| Notation  | Layout            | Assignment | Owns storage | Allocator |
|-----------|-------------------|------------|--------------|-----------|
| `[n T]`   | n contiguous `T`  | copies     | no (inline)  | —         |
| `[T]`     | ptr + len         | copies the *view* | no    | —         |
| `(Vec T)` | ptr + len + cap   | **moves**  | yes          | stored    |
| `(Map K V)` | open-addressed, flat key/value arrays | **moves** | yes | stored |

- `[n T]` is a value. It lives wherever it is declared, copies on assignment and
  on pass-by-value, and is what `defconst colors [4 u32] ...` and
  `(defvar grid [rows [cols u32]] ...)` are.
- `[T]` is a **non-owning slice**: a borrowed window into a `[n T]`, a `(Vec T)`,
  or a literal in read-only memory. Copying a slice copies ptr+len, never the
  elements. A slice may be `const`-qualified; freeing through one is not possible
  because a slice has no allocator and no `cap`.
- `(Vec T)` and `(Map K V)` are **move-only**. Binding, passing, or returning one
  transfers ownership; the source binding is dead afterwards and using it is a
  compile error. There is no shallow copy, so there is no double free.

## Copying is always explicit

`(clone x)` produces an independent deep copy of a `Vec`/`Map` using the current
allocator; `(clone x alloc)` names one. Value types (`[n T]`, structs of value
types, primitives) need no `clone` — assignment already copies them.

A struct containing a `Vec` field is itself move-only. Ownership is structural,
not declared: a type is a value type iff all of its fields are.

## Borrowing

- `(as-slice v)` / `(as-slice v lo hi)` view a `Vec` or fixed array as `[T]`.
- A slice is invalidated by any operation that may reallocate the owner (`push`,
  `put`, `reserve`). This is **not checked** in the first implementation; dev
  builds carry a generation word on `Vec` and trap on use of a stale slice.
- Cross-referencing long-lived objects uses `(Handle a)` into a pool, never a
  raw pointer or slice. A stale handle is detectable.

## Taking an address

`(addr x)` yields `(Ptr T)` for any assignable place `x` — a local, a global, a
field, an element. The pointer is non-owning and does not extend anything's
lifetime, so `addr` of a local is only valid while that frame lives. This is the
same escape question as case 3 below and is checked by the same analysis; until
that analysis exists, `addr` of a local may not be stored or returned.

`addr` is how a value struct is shared mutably without an allocator — recursive
descent over a cursor, an entity passed down a call chain — and it is why
milestone 2 needs no heap at all.

## Places — what `set` accepts

A fixed set of assignable forms, not a `setf`-style extensible place mechanism:

```
(set x v)              ; a local or a defvar
(set (.field x) v)     ; struct field; x may be a struct, (Ptr S) or (Handle S)
(set (at a i ...) v)   ; fixed array, slice, or Vec element
(set (get m k) v)      ; map entry
(set (deref p) v)      ; whole-object store through a pointer
```

`.field` and `at` auto-deref exactly one pointer or handle level, which is what
makes `(set (.hp e) ...)` legal when `e : (Ptr Enemy)` and illegal when
`e : Enemy` bound by value.

**Mutating something you matched.** Pattern bindings bind *values*, so a matched
struct is a copy. To mutate in place, obtain a pointer first — the pointer is
visible in the type:

```
(match (resolve w h)          ; (Option (Ptr Enemy))
  (Some e) (set (.hp e) ...)  ; e : (Ptr Enemy), field access derefs
  None     ...)
```

`deref` yields a value; `resolve` yields a pointer. Both are overloaded on
`(Ptr a)` and `(Handle a)` and resolve at compile time.

## Generics

Parametric polymorphism is monomorphisation, with **no type classes and no
constraints**. The consequence is a hard rule:

> A type variable `a` supports only what every type supports: move, `clone`,
> field-free storage. It does **not** support `=`, `<`, `+`, `hash`, or `print`.

Anything else is passed in explicitly as a function value:

```
(defn largest [xs [a]  gt (Fn [a a] bool)] (Option a) ...)
```

Ordered/arithmetic operators over `a` are therefore rejected, not silently
instantiated. The alternatives — compile-time interfaces, or intrinsics
restricted to primitives — are deliberately deferred until the base checker is
stable (build sequence milestone 4).

Type arguments are **inferred at call sites** from the argument types; there is
no explicit instantiation syntax in the first implementation. A type variable
that appears only in the return type is therefore an error.

## Function values

Three cases, split by whether the value escapes the frame that made it.

**1. `(Fn [T1 T2] R)` — a plain function pointer.** No captured environment, no
allocation, C calling convention plus the implicit allocator argument. This is
what raylib callbacks, hot-reload indirection cells, and function *parameters*
use. A top-level `defn` is one, so `(largest hps >)` passes `>` at `i32`
directly. This is the only function type that may cross an FFI boundary or sit
in a reload cell.

**2. Non-escaping `fn` — captures by value into a stack environment.** A `fn`
whose value provably does not outlive the frame that created it gets an
environment allocated in that frame and captures the named locals **by value**
at the point of creation. No heap, no allocator, no lifetime question. This
covers essentially every lambda in practice:

- callbacks to `reduce` / `filter` / `each` / `map`, which consume them and return
- comparators passed to a function that does not store them
- `handler-bind` handler bodies

That last one is not a convenience. A handler must be able to see the enclosing
locals — `(fn [c] (push errors c) (invoke-restart 'skip-form))` capturing a local
`(Vec ParseError)` *is* the accumulation pattern, and conditions are not worth
building without it. Handlers are strictly non-escaping: the `handler-bind` frame
outlives every call to them.

Captured `Vec`/`Map` are captured **by pointer**, not moved, since the capture
does not outlive the owner. A non-escaping `fn` is therefore not itself an owner.

**3. Escaping closures — still open.** A `fn` stored in a struct, pushed into a
container, or returned needs a heap environment and an answer to "which allocator
owns it, and what happens when the frame arena resets". Not settled; see
plan.org open decisions. Escape analysis (open decision #4) is the same analysis
that classifies cases 2 and 3, so they are decided together.

**Early exit inside a `fn`.** `try`, `some`, and `return` in a `fn` body exit the
`fn`, not the enclosing function — a `fn` is a function. Code that wants to
propagate out of a loop uses an imperative loop form, not a callback.

## Allocators

The allocator is part of the calling convention (`context/allocator`,
`context/temp`). `Vec` and `Map` record the allocator they were created with, so
`free` and `clone` never need it named again. No core operation allocates
implicitly.