Introduction - Aperio

Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Auto

Light

Rust

Coal

Navy

Ayu

Aperio

Introduction

Every language designed before 2023 was optimized for a single<br>tradeoff: minimize friction between human cognitive capacity<br>and machine execution. Assembly to C to managed runtimes to<br>DSLs were different points on the same line. In an LLM-driven<br>workflow, those languages don’t get cheaper to use — they get<br>more expensive. The cost just hides in the LLM’s token count,<br>its retry rate, and the latency it eats per turn. Pre-LLM<br>languages are a hidden tax in the LLM era.

Most of an LLM’s per-turn effort isn’t recalling syntax. It’s<br>translating between the user’s mental model of a system and<br>the language’s structural shape. A language whose primitives<br>don’t match how the system is thought about forces this<br>translation every turn, paying full cost each time.

Aperio is built on a different premise: there exists a<br>substrate-invariant structural model — a recursive hypergraph<br>of typed, lifecycled units called loci — that both human<br>reasoning and LLM reasoning operationalize when working with<br>systems.1 A language whose primitives are that<br>model collapses the translation layer. The mental model and the<br>code share a substrate.

What that looks like in practice

Pick a system you already have a mental model for: the<br>matchmaker behind a multiplayer game. In your head, the thing<br>is a service that holds a queue of waiting players, spawns a<br>match when enough are queued, and goes back to waiting.

Here’s that, in Aperio:

type Player { id: String; name: String; }<br>type MatchInfo { match_id: String; players: [Player]; }

topic JoinQueue { payload: Player; }<br>topic MatchReady { payload: MatchInfo; }

@form(vec)<br>locus Matchmaker {<br>params { target_size: Int = 4; }<br>capacity { heap waiting of Player; }<br>bus {<br>subscribe JoinQueue as on_join;<br>publish MatchReady;

fn on_join(p: Player) {<br>self.waiting.push(p);<br>if self.waiting.len() >= self.target_size {<br>MatchReady<br>Every clause of the mental-model description has a syntactic<br>home in the code, in roughly the order you thought about them:

“a service” → locus Matchmaker

“holds a queue of waiting players” →<br>capacity { heap waiting of Player; } (the @form(vec)<br>annotation gives it queue-like methods)

“receives players wanting matches” →<br>subscribe JoinQueue as on_join

“announces matches” → publish MatchReady

“when enough are queued” → the inline if

The structural correspondence is the point. The same<br>description in Go, Rust, or TypeScript expands into more<br>concerns: mutex selection, channel types, async/await<br>machinery, explicit lifecycle wiring, error-handling at every<br>channel boundary. Each of those is a translation an LLM has to<br>perform every turn. Aperio elides them because the language<br>commits to them at the structural layer.

The choice of @form(vec) here is itself a real design<br>decision, not an arbitrary one. @form(ring_buffer) gives the<br>same shape with a hard capacity ceiling and explicit<br>drop-on-full semantics; @form(hashmap) keyed by player id<br>gets you natural ID-based cancellation. Forms are how Aperio<br>exposes those choices — we cover them in Concepts .

See it on your own code

The matchmaker above is a constructed example. The claim is<br>testable on code you already have. In whatever LLM-coding tool<br>you use (Claude Code, Cursor,<br>whatever), drop this project’s<br>AGENTS.md<br>into the agent’s context, then ask it to re-read a module or<br>service from your existing codebase in terms of loci,<br>contracts, and bus topics .

What usually comes back is a structural decomposition that<br>matches your mental model of the system with surprising<br>accuracy — because the agent is using the same recursive locus<br>vocabulary you already use when reasoning about the code. The<br>friction you normally feel between how you think about this<br>system and what’s literally on the page largely disappears.

If the decomposition looks wrong or unhelpful, the thesis fails<br>for your codebase and that’s useful feedback — open an issue.<br>If it looks right, you’ve felt the structural correspondence<br>from the other direction: not by writing new Aperio code, but<br>by reading your existing code through the same lens.

More than a programming language

The structural model Aperio operationalizes isn’t<br>software-specific. The same recursive hypergraph organizes<br>coordination at every substrate the underlying research<br>program addresses: institutions, biological regulatory<br>networks, physical systems, cognitive architecture. Aperio’s<br>frontend is, in principle, a design language that can target<br>machinery in any of those substrates. The programming-language<br>form is the first instantiation, not the only one. (Held<br>lightly — the immediate work is the language itself.)

Status and shape

This is an experimental language. The compiler ships native<br>codegen via LLVM 18 and a tree-walking interpreter for...