Keeping the Failures In

docs/CAPABILITIES.md in this repo has one job: say what the code actually does, with the check that proves it, and say what it does not do just as plainly. Most capability documents drift toward the opposite habit almost immediately, because a document that only lists what works reads better and takes less effort to keep honest. The single most useful line in this one is the opposite kind: a flag that defaults to on, that a user could set expecting an effect, that has no effect at all on one of the two models this engine runs.

The flag that does nothing, and why nothing tells you

BARO_SPEC defaults to "1". Reading only that line, a reader would expect speculative decoding on by default. The actual gate in serve/engine.mojo is spec_env = MEGA_ALLOWED and getenv("BARO_SPEC","1")=="1", and MEGA_ALLOWED is False for the qwen35moe profile. Setting BARO_SPEC=1 on the MoE model has no effect, for a reason that has nothing to do with the flag: that model has no draft head at all, so there is nothing for the flag to turn on. The environment variable is read, checked, and its result is thrown away by the and, silently, on every request, forever, unless you go and read serve/engine.mojo yourself.

This is a specific case of a general failure this project has hit before in kernel work and named explicitly in its own rules: a parameter that is accepted and does nothing produces no error, no warning, and no different output shape. It just quietly runs the code path that would have run with the flag unset. The only way to know is to read the gate, not the flag's default, and the only reason this particular instance is documented rather than silently believed is that someone went and read the gate.

Two engines exist in this repo, qwen35 (dense) and qwen35moe, compiled from two hardcoded comptime profiles selected by BARO_MODEL. They share a great deal of code and diverge on exactly the axes that make a flag like BARO_SPEC model-dependent in a way its own name gives no hint of. A document that described BARO_SPEC once, at the top, as "speculative decoding, default on" would be true of the dense model and false of the MoE model in the same sentence.

A second instance: BARO_KVQ=int8, off by policy for a reason the flag doesn't state

The KV cache dtype flag, BARO_KVQ, defaults to f32. int8 is available and measured: decode after 32k context reaches 117.69 tok/s against 100.54 for f32, a 1.171x gain, with RULER niah_single scoring 100.0 at both 64k and 128k. It is off by default not because it failed a gate, but because it is a comptime -D build flag rather than a runtime default, and because serve/engine.mojo raises at compile time if the MoE profile is asked to build with a non-f32 KV type at all: the MoE megakernel writes f32 KV and int8 there is not merely unmeasured, it is a build error. BARO_STATE_SAVE additionally refuses to checkpoint when KV is int8, which the document is careful to call an unimplemented case, not a policy off-switch, because those two things want different fixes from a future reader.

This is a case the document's status vocabulary was built to handle precisely: DEFAULT-OFF means implemented but not on, with the reason named on the same line, never as a footnote. A reader who sees only "int8 KV: works" would reasonably try it on the MoE model and hit a compile error with no idea why; a reader who sees "dense-only, comptime flag, MoE raises at compile time because the megakernel writes f32 KV" knows exactly what will happen before trying it.

And a third: ternary kernels that are correct and reachable by nothing

kernels/matmul_ternary.mojo implements three ternary formats, Q2_B3, TQ1_0, and TQ2_0, each with a parity test that passes. serve/registry.mojo defines wrapper functions for all three. Neither serve/engine.mojo nor serve/spark.mojo calls any of them; a text search for the wrapper names in both files returns nothing. The document's own status word for this is PRESENT BUT UNUSED, distinct from both WORKS and DEFAULT-OFF, because neither of those is accurate: a DEFAULT-OFF feature is one a user could turn on and get a working result, and there is no path from any user-facing switch to these kernels at all. docs/ternary-quant-notes.md states the matching limit directly: correctness only, no throughput measured, and no throughput may be claimed for them without going through this project's own preregistration protocol first.

Three failure shapes, three different status words, on purpose: a flag that is silently overridden by another condition, a flag that is honestly off and explained, and code that exists with no way to reach it at all. Collapsing any two of these into the same label would lose exactly the information a reader needs to act correctly on each one.

The rule

A capability document that only lists what works has already made its first undocumented decision: which failures were worth mentioning. The rule here removes that decision by keeping all of them.

What counts as a line in this document and what does not

What counts: - A status word from the fixed vocabulary (WORKS, PARTIAL, DEFAULT-OFF, PRESENT BUT UNUSED, CLAIMED, FAILS, PARKED, KILLED, BROKEN), each meaning exactly one thing, with the check and its receipt path on the same line as the claim. - A limit stated as part of the capability itself, not as a footnote a reader can skip. PARTIAL entries name the limit inline, every time. - A number or verdict that was retracted or downgraded elsewhere in the repo's own record, carried through here with the same retraction, never quietly upgraded because it would read better.

What does not count: - A green build, a passing unit test, an HTTP 200, or an active process, standing in for a check that exercises the feature the way it is actually used. The document states this as one of its three inherited conventions directly. - A reference implementation's result taken at face value. The same cold-cache and parameter read-back discipline this repo applies to its own kernels applies to llama.cpp and any other baseline cited beside them; several gates in this project's history were found unpassable by their own reference arm. - A feature's intended design standing in for its measured behavior. Nothing appears in this document because it is planned, designed, or nearly finished; it appears with a check or it is marked unproven.

What it costs

Writing this document this way means every capability claim has to be re-derived from a real check rather than from what the feature was supposed to do, and every retraction from elsewhere in the repo has to be tracked down and carried over rather than left to age out quietly. It also means the document is, on its own terms, less flattering than a normal feature list: a reader's first honest impression of this engine from docs/CAPABILITIES.md includes a MoE model with no speculative decoding, a KV quantization mode that only half the engine can use, and three correctly-implemented kernel families that nothing calls. All three of those are true, and a document that hid any of them to read better would have hidden exactly the information most likely to save someone else an afternoon.

How to prove this wrong

Pick any line in docs/CAPABILITIES.md marked WORKS, DEFAULT-OFF, or PARTIAL, and run the check it names yourself: bench/moe-prefill-identity.sh for the batched MoE prefill claim, kernels/test_moe_rows.mojo for the row-batched kernel parity claim, or a direct read of serve/engine.mojo's spec_env line for the BARO_SPEC claim this post opens with. A result that contradicts the document is worth more to this project than one that confirms it, because a document whose claims nobody has tried to break is a document nobody has actually tested.

Provenance

docs/CAPABILITIES.md as read at main 2208bdb (2026-09-17), with the changes section current through ea57b60 (2026-09-19). Every commit cited in this post (ad327e8, 9cbb683, 92784e9, d684fb2, 0931e90, 80d4b2c) is one this repo's own document names beside the claim it supports, in amarbaro/mojo-baro. The int8 KV numbers are carried from docs/BASELINE.md, "int8 KV since 2026-09-17," verified rather than provisional.