Design

The design record of serQ. docs/language.md describes the language as it is and docs/ir.md the IR as it is; this directory records why they have the shape they have, what is pushing them to change, and what the next shape is.

The IR is a living thing

The IR is never finished. It evolves with the requirements and keeps looking for a better solution. That is a working rule, not a slogan, and it unfolds into five items.

1. Selection pressure comes from verification. What asks the IR to change is not taste but what a check caught: the fifteen defects of docs/review.md §3, a path no oracle exercised, a statement Lean cannot write, a regime where the simulator is slow. A requirement is written in that form. "This program could produce this defect" is the requirement; "this concept makes that class impossible" is the solution.

2. Variation is an RFC; selection is done by the three consumers. A proposal is an issue (labels rfc, design), and the test it must pass is what the IR's three consumers gain. The interpreter: a wrong answer that is now impossible, or speed. Lean: a statement that can now be written, or an undefined behaviour that is gone. The oracle: a path that now agrees. And a fourth, the reader: a rule that disappears. A variation that answers none of the four is the charm of a paradigm, not the power of a tool. The verdict table of the frontend sketch applies that test.

3. The price is a handshake. One IR version moves serving-queue-theory's generator, the seven oracle IR files and the Lean fragment together. The version policy that identifies meaning rather than shape (#21) sets that price. The same shape with a different meaning is the most expensive change, because an old reader is silently wrong.

4. A decision keeps its reason. A decision can be reversed only if its "why" is recorded, so a rejected idea is recorded too, with its reason, in the self-critique section of the document that rejected it. That is so the same proposal is not argued twice.

5. Nothing goes extinct. Committed IR files must always be regenerable (make oracle-ir). An old program must compile through the new frontend to the same report (tests/ir.rs), and a change for which that is not possible says what changed in its release note.

How it evolves

what a check caught ──▶ RFC issue (Before/After, picture books)
                                │
   judged by the three consumers and the reader ◀──┘
                                │
   adopted ──▶ IR version (handshake) ──▶ docs/ir.md, docs/language.md updated
   rejected ──▶ the design document's self-critique, with the reason

The design criteria themselves (unambiguity, intention-revealing, policy in the program, checkability) are in CLAUDE.md and #8 and are not repeated here. This directory is the record of applying them.

Documents

Document	What	Status
Philosophy	What serQ is mathematically, and the principles by which its vocabulary grows	discussion of 2026-09-28
Frontend	Model / instance split, effects and handlers, the admission block, trait vocabulary, units. With two self-critiques and a verdict table	sketch, before issues
IR v4	Making the implicit static: moments, ownership, declared orders, integer ticks, the session automaton, step coalescing, progress checks	RFC #41
Subagents	A session that spawns sessions is not a tool call: endogenous arrivals, hold-and-wait, cross-session cache, Spawn/Join	review, for v4b
The KV transfer	Prefill/decode disaggregation as llm-d and the NIXL connector do it, in pull and push mode; release, load, transfer … from … to …; the reservation push mode still wants	IR v5, with examples/pd-disaggregation/llmd_pd.sq
Renewal arrivals	Finite open runs, execution deadlines, report times and first-arrival compatibility	IR v6, #108
Bandwidth sharing	A transfer holds the sender's and the receiver's link at once: Run.also, share maxmin or bottleneck, the flow solver	RFC #118, design before implementation
One admission	One spelling for one admission: hold … at admission (…) … cache; enter, admit if … fit where and keep retired, the serving name moved into a def	#136
Separate prefill/decode batches	Whole-batch isolation and waiting-prefill takeover using the existing serve policy	untagged IR v8 semantics
Waiting selection	Selection-time queue keys, elapsed wait and Ascend-style FCFS aging	IR v9
Queues	gateway, prefill, link and decode as roles of one queue that owns its pools, its stage and the entries holding a request's admission, allocation and service; what an entry may read; parse-time sugar; a link whose serve is its cost	RFC #72, with examples/pd-disaggregation/llmd_nixl_pull.sq
Explicit gateways	request gw; selects a gateway by name; predefined vocabulary and the proposed import boundary	PR #87 follow-up
The pull relation	A pod owns its nic; D pull P latency x share s; is a transfer's topology, mode and policy in one line, and a transfer without on its read	#200, parse-time sugar

A new design document adds a row to this table.