el/docs/architecture/capabilities.md

# El — Capabilities

**What the language can do, stated as capabilities rather than as code.**

This list is the unit of analysis. Each entry gets one question — *prove this
cannot be done with pure geometry* — and the answer determines whether it stays a
capability of the language or collapses into the manifold.

Draft, 2026-08-17. Ordered roughly from most-likely-geometry to most-likely-code.

**Status after measurement.** The list was audited against the implementation
the same day. 28 entries collapsed to 19 geometry + 3 code: serialization, text
encoding, network and emission are all *projection onto a basis* (row 18) —
the convention is the basis, never the act. Storage collapsed because
persistence has no caller. Concurrency collapsed because coordination is the
price of forgetting, not a capability. A fourth proof form was added,
**adversarial exactness**, and form 1 stopped being a valid verdict.

**The table answers CAN only.** SHOULD and COST resolve per *site*, not per
capability — `is_digit` and `is_letter` are one capability with opposite
answers, and comparison spans three cost tiers. See the notes below.

---

## The list

| # | Capability | What it means | First read |
|---|---|---|---|
| 1 | **Comparison** | is this the same as that; is this greater | zero distance / sign of a displacement |
| 2 | **Ordering** | arrange by a criterion | position along an axis |
| 3 | **Containment** | is this inside that; does this contain that | region membership |
| 4 | **Correspondence** | where does this occur in that; how much of this is in that | a match-strength field over a span |
| 5 | **Segmentation** | divide a whole into parts | boundaries at measured discontinuity |
| 6 | **Composition** | join parts into a whole | adjacency; one position with parts |
| 7 | **Classification** | what kind of thing is this | which region does it land in |
| 8 | **Naming / binding** | attach a name to a thing and find it again | an edge; retrieval is projection |
| 9 | **Collection** | many things held together, indexed, counted | a set of positions; cardinality; projection onto the i-th |
| 10 | **Iteration** | do something for each of many | traversal |
| 11 | **Arithmetic** | quantity, magnitude, combination | displacement algebra on a line |
| 12 | **Time** | when; how long; how often | a 1-D affine space — instants are points, durations displacements, rhythms phases on a circle |
| 13 | **Identity** | which one is this; are these two the same one | coincidence of position |
| 14 | **Selection / dispatch** | choose which behaviour applies | nearest region |
| 15 | **Transformation** | produce a thing from a thing | change of basis |
| 16 | **Grounding** | how well is this supported | the weight on an edge. Has no caller |
| 17 | **Learning** | get better at something | standing changing over time |
| 18 | **Projection** | render meaning onto a surface | change of basis onto a surface basis |
| 19 | **Transduction** | take a signal in | change of basis from a sensor basis |
| 20 | **Serialization** | write a value as bytes someone else will read | **convention** — the format was agreed |
| 21 | **Text encoding** | what bytes mean which characters | **convention** — UTF-8, ASCII, case tables |
| 22 | **Storage** | keep a thing past this moment | durability against a device that loses power |
| 23 | **Network** | send a thing to another machine | wire protocol + socket |
| 24 | **Process** | start, stop, signal, exit | the OS boundary |
| 25 | **Concurrency** | more than one thing at once | hardware and OS scheduling |
| 26 | **Memory** | hold representations while they are in use | the substrate that holds positions |
| 27 | **Secrecy** | prove authorship; hide content; verify integrity | **structurally excluded** — see below |
| 28 | **Emission** | write the surface out as bytes | the physical boundary |

---

## Notes on the boundary cases

**27 — Secrecy is the one capability geometry cannot hold, and the proof is not
form 1.** A cryptographic hash is a *deliberately structure-destroying* map: its
entire value is that near inputs land at maximally uncorrelated outputs. Geometry
is the claim that near things stay near. A manifold that approximated SHA-256
would *be* a break of SHA-256. Signature verification is the same: 0.99-valid is
invalid. And X25519 *is* geometry — a group on an elliptic curve — which is
precisely why it must be code, because its security is the *hardness of moving in
that geometry*.

This is a fourth proof form and it should be added to `geometry-vs-code.md`:
**adversarial exactness.** Where approximation is a break, geometry is excluded.

**20, 21 — Serialization and text encoding are convention all the way down**, but
only at the *edge*. The byte format is agreed; what is being written is not. Do not
let a geometric computation inherit a code verdict because its result gets
serialized.

**11, 12 — Arithmetic and time are the same capability.** Instants are points,
durations are displacements, point−point→vector, point+vector→point. The runtime
already implements this correctly as `el_instant_add_dur` / `el_duration_add`. That
it *also* implements a five-entry string→multiplier table beside it (`time_add`
with `"ms"/"sec"/"min"/"hour"/"day"`) is the residue.

**7 — Classification is the most-violated capability in the codebase.** Seven ASCII
range tables (`is_letter`, `is_digit`, `is_alphanumeric`, `is_whitespace`,
`is_punctuation`, `is_uppercase`, `is_lowercase`) that return false for every
non-ASCII byte. `str_count_letters` reports zero letters for `é`. The wrongness on
most of Unicode is the tell that a table is standing in for a region.

**4 — Correspondence appears five times.** `str_index_of`, `str_index_of_all`,
`str_last_index_of`, `str_count`, `str_find_chars` are five projections of one
match-strength field: first zero, all zeros, last zero, count of zeros, first
class-crossing. One relation, five functions.

**14 — Selection is the crux for the compiler.** `+` dispatching on AST node kind
is selection-by-enumeration where selection-by-position belongs.

**Correction, 2026-08-17, from measurement.** This entry previously also cited
`==` lowering to `str_eq` "unless both operand names are in a hardcoded int-name
set — a literal list of variable names treated as integers." That is **wrong**.
`__int_names` is populated from *type annotations* (`param["type"] == "Int"`,
`let x: Int`), which is primitive but legitimate type propagation, not an
enumeration of blessed variable names.

The real defect was one layer down: `is_int_call` held **35 hardcoded builtin
return types**, the same shape as the 19 temporal ones. Those moved to
`lang/tools/check/signatures.rel`.

And the mischaracterisation hid a live bug. Because the return types were never
consulted at a *binding* site, an unannotated `let` lost its type:

```el
let a = str_len("hello")     // no annotation
let b = str_len("hi")
let c = a + b                // → el_str_concat(a, b) on two integers
```

That compiled clean, ran, and printed nothing where it should print 7 — no error
at any layer. Present in the pre-change compiler, so pre-existing. Fixed by
taking an unannotated `let`'s type from what its initialiser returns; the data
was already required for dispatch and simply never read there.

**The general lesson, since it recurred all session:** the enumeration was real
but I had located it in the wrong place. Naming a defect from reading is a
hypothesis. Eight hours of reading this file did not surface the miscompilation;
moving the data out and running the result did.

---

## What this list is for

Each capability gets audited **once**, across every place it appears — not once per
file. The output is not a percentage. It is:

- which capabilities survive the question and stay in the language
- which collapse into the manifold
- and for each one that collapses, **every site it currently appears at**, because
  those sites are the residue and they are what gets deleted.

The line-count audit produced a map of where the residue sits. This produces a map
of **what it is**.