neuron-technologies/el
3
0
Fork 0
Code Issues 4 Pull Requests Actions Packages Projects Releases 5 Wiki Activity

track the architecture docs

Browse Source 
They were written outside git, so the reasoning that produces the design
had no history and no way to be superseded. capabilities.md and
geometry-vs-code.md are both known stale at this commit; they are tracked
as-is so the corrections are visible as movement rather than as a rewrite.
This commit is contained in:
bigmerge
2026-08-17 04:34:32 -05:00
parent addd51209f
commit 409bf57341
6 changed files with 821 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture/capabilities.md
+102
View File
@@ -0,0 +1,102 @@
# 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. Not yet audited. Ordered roughly from most-likely-geometry to
most-likely-code.
---
## 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
and `==` lowering to `str_eq` unless both operand names are in a hardcoded int-name
set are both selection-by-enumeration where selection-by-position belongs.
---
## 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**.