Case study: fixing switch

A record of one language decision, start to unfinished, including the measurements that misled us and the ones that held. Written down because the process turned out to be more interesting than the conclusion, and because several of the wrong turns are the kind nobody writes up.

Outcome: given shipped, switch reverted to C semantics with a warning, and existing code is upgraded automatically where that is provably safe. The keyword was chosen on structural argument, because the measurement that appeared to rank the candidates turned out to be noise — which is the most useful thing in this document.

given is TJS's replacement for switch. Each arm can list several values, no arm runs into the next, and values compare the way TJS's == does:

function shape(kind: 'circle'): 'round' {
  given kind {
    'circle', 'ellipse' { return 'round' }
    'square' { return 'square' }
  } else {
    return 'unknown'
  }
}

console.log(shape('ellipse'), shape('square'), shape('blob'))
// round square unknown

This page is a design record: why the construct exists and why it looks the way it does. For how to use it, see Control Flow: given.

Much of the evidence below comes from asking an AI language model what a program returns. Models now read and write a large share of code, and they are a cheap stand-in for a reader meeting TJS for the first time, so "can a model read this correctly?" was the test. The model-reading test turned out not to separate the keyword candidates, so the keyword was chosen on design grounds (collision risk and meaning) instead.

1. The defect

switch in JavaScript is C's, and it carries four problems that have nothing to do with each other except a common origin:

1. case compares with ===. In TJS, == is a comparison without the footguns (no type coercion, null equals undefined; see Honest Equality), so switch silently disagrees with the rest of the file: case null: does not match undefined, though undefined == null is true.
2. Multiple values sharing one block is only expressible as fallthrough.
3. Fallthrough is the default, so correctness requires break on every arm.
4. All arms share one scope, so let leaks and const collides.

switch (x) {
  case 'a':            // problem 2: 'a' reaches the shared block only by falling through
  case 'b':
    const n = 1
    log(n)             // problem 3: no break, so 'a' and 'b' also run the next arm
  case 'c':
    const n = 2        // problem 4: SyntaxError, `n` is already declared in this scope
    break
}

Two of these ship as errors in eslint:recommended (no-fallthrough, no-case-declarations). The ecosystem decided the defaults were wrong long ago and has been hand-patching ever since, because the language cannot change. That is the observation the whole project rests on: a pattern that needs a heavy-handed lint rule is a language defect, not a user error.

2. What we built first — and later reversed

Swift's answer is to end every arm on its own (an implicit break). That one decision fixes problems 2, 3 and 4 together: arms can list several values, fallthrough becomes something you ask for, and each arm gets its own scope. For problem 1, compare with Eq, the function behind TJS's ==.

That shipped (#43) — multi-value case 'a', 'b':, opt-in fallthrough, per-arm scope, and the switched-on value compared the same way == compares. It also needed Exactly(…) underneath. In TJS a colon value is an example that widens to its type, so a field written kind: 'circle' means "any string", and two types that differ only in that field (a Circle and a Rect) looked identical when the switch dispatched on them. Exactly('circle') keeps the literal.

Three implementation traps, each worth remembering:

• Rewriting to an if-chain is wrong. break inside a switch breaks the switch; inside an if it breaks the enclosing loop. That rewrite silently changes control flow.
• Per-arm scope cannot be added after parsing. A switch body is one block scope in JS, so two consts with the same name are a syntax error, and the parser (acorn) is right to reject them. Each arm has to be wrapped in braces in the source text before it is parsed.
• Fixing the runtime changed nothing that ships. Each compiled file carries its own small copy of the runtime, so a fix to the main runtime's Type() did not reach compiled code until the copy (its __match helper) learned the same rule.

All of this made switch mean something different in a .tjs file than in a .js one. Section 3 shows why that was a problem; section 4 is where it was reversed.

3. The measurement that changed the plan

We showed a model a short switch, varied only the file extension, and asked what f('a') returned. Without break, JavaScript's arms fall through and the answer is 1,2; under the reworked TJS switch they did not, and the answer is 1. "Correct" means the answer the file's own rules give: 1,2 for the .js file without break, 1 for the .tjs one. Each condition was asked five times. The probe is experiments/agent-legibility/switch-probe.ts; the numbers below are from qwen3.8-27b, a 27-billion-parameter model (the full series is in switch-probe-results.md beside it):

Not "poorly" — the worst possible result, and not from uncertainty: both controls are 100%. Shown identical text as .tjs, it applied C fallthrough five times out of five, confidently.

Its own reasoning, verbatim: "…maybe has 'case' with comma to group multiple cases? There is a language 'TJS'…" The model has no prior knowledge of the extension. The .tjs extension is the only thing that tells a reader this file follows TJS rules: it is an out-of-band marker, outside the code itself. It is what lets TJS change == for a whole file, which an in-code directive like "use strict" never could, and it carries nothing to a reader.

A one-line comment in the file stating the rule (that arms do not fall through) took the 27B model to 5/5. A much smaller model (gemma-4-e4b, about 4 billion parameters) was unmoved by anything in the file: it scored 0/5 on every TJS condition, comment or not. So the affordance has to be in the code, and even there it only reaches a reader capable of acting on it.

4. The reframe: if it behaves differently, it should look different

The comment fixes the file that carries it. It does not reach the places where only a few lines of the file are visible: a snippet in chat, a diff, a stack trace, a search result. #48 proposed the alternative: stop changing what switch means, and give the fixed construct a different name.

Then a stronger form of the idea — change the shape too, not just the word:

given x {
  'a', 'b' { … }
} else { … }

No case. No colons. No implicit blocks. else for the remaining arm. Every difference visible.

Measured on qwen3.8-27b, five samples each. The keyword was not yet decided, and in this run it was match; sections 7 and 8 are how it became given. "NEW syntax" is the brace-and-comma form above, every condition is a .tjs file, and "no-answer" means the model did not commit to a return value:

Two findings, and the second was a surprise. Changing the shape eliminated every confident wrong answer — 5 to 0 — which is the failure mode that ships bugs. But keeping the name while changing the shape produced five no-answers: the model cannot reconcile "this is switch" with "this does not look like switch", and stalls. The keyword and the shape have to move together.

5. Syntax details that earned themselves

These were worked out while the keyword was match; they apply unchanged to given.

No parentheses. This is already valid JavaScript:

match (x)
{ … }

JavaScript inserts a semicolon at the line break, so it reads as a call, match(x);, followed by an ordinary block. Without parentheses, match x { is never valid JavaScript, so the transpiler can tell the construct apart from ordinary code. The choice that looked like taste is what makes detection possible.

Detection is the hard part. Detection means the transpiler finding the construct in source text, and it is hard because no candidate keyword is reserved: any of them can also be a variable, a property or a word in a string. A first prototype mangled const match = 1; if (y) { … } into switch (= 1; if (y)). It was fixed by requiring the value after the keyword to look like an expression (no ;, no leading operator) and by skipping declarations (const given = …) and property access (obj.given). The false-positive shapes we found, including the keyword inside a string literal, are now left untouched.

The fallback block is else; section 9 says why.

6. Rewriting existing code, which is the actual job

Adding a better alternative is not fixing the language. switchToGiven rewrites a C switch only where it provably means the same thing: every non-empty arm leaves (return/throw/break/continue), so implicit-versus-explicit break is unobservable. Stacked empty arms become multi-value; trailing break is dropped as dead code; default becomes else. Where an arm genuinely runs into the next, the switch is not rewritten, and a note naming its line says why. A converter that is occasionally wrong is worse than one that is honest.

Two terms matter here. Conversion (fromTS) turns a TypeScript file into TJS that still behaves like JavaScript; its output carries a /* tjs <- source */ comment, which means "JS semantics". Graduation removes that comment, which turns on every TJS rule. The rewrite runs at graduation, not conversion, and the distinction is load-bearing: given is lowered only for native TJS, so emitting it at conversion time would produce files that do not parse. That is exactly the shape of #37, where dropping new at conversion time shipped modules that could not be imported. Graduation strips the annotation, applies both rewrites, then checks that the result still compiles as native TJS, returning the input unchanged (and saying why) if it does not. It is one function, graduate.ts.

On our own source: 44 switches upgraded across 19 files, 0 declined, which is consistent with no-fallthrough being an error in our lint. The dogfood check, which converts and then graduates each of our own source files, went from 104 of 105 files to all 105.

Three defects the rewrite found, none of them in the rewrite

Worth recording because all three were silent, and two predate this work entirely:

1. It deleted every comment. Arm text is sliced from the first statement to the last, so anything sitting between arms simply vanished — including a twenty-line rationale block in our own converter. Every test stayed green, because no test asserted that comments survive. The comments are usually the part of a file you cannot reconstruct; a converter that drops them is worse than one that declines.
2. given did not nest. Lowering slices an arm's body as text rather than re-scanning it, so one pass reached only the outermost construct and the inner one arrived at the parser as given b {, which is not JavaScript. The transform now runs to a fixpoint. This shipped with given and no test had nested one.
3. The JS-semantics check was blind to string literals. The annotation that means "JS semantics" was detected by scanning raw source text, so any file that merely mentioned /* tjs <- … */ in a string was read as TS-originated and silently lost the entire language — == stopped being Eq, dictionary defaults went atomic, given never lowered. from-ts.ts emits that annotation from a template, so the converter's own source was the first casualty, and had been for as long as the check existed.

The pattern is the same one this whole document keeps running into: the failures that matter here do not throw. They produce plausible output. The third is the most common defect in this codebase, a pass that misreads code merely mentioning what it scans for, appearing in the one place nobody had thought to look: the check that decides which language the file is written in.

7. The keyword, and how the data failed us

Candidates measured cold (no explanation or cheat sheet), same program, only the word varying. The match row is the same run as section 4's last row. These tables, and the re-run below, are in experiments/agent-legibility/FINDINGS.md (the "match vs switch" and "Keyword candidates" sections, 2026-08-29):

That looked like a ranking, and it was written up as one. Then the identical given condition was re-run and scored 4/5. A swing of three in a sample of five, same model, same prompt.

So the ranking was noise. What the re-run establishes is a property of the instrument:

Correctness is stable; willingness to commit is not. Every new keyword produced zero wrong answers in every run. The thing that varied wildly was whether the model answered at all.

This matters beyond the keyword, because it means a probe scored on "correct out of N" silently mixes a stable signal with a noisy one. The two should be read separately, and the no-answer column is the one that needs a much larger N.

What survives. The bare .tjs switch scored 0/5 in every run, on both models, and on the 27B model every condition that used the new shape gave zero wrong answers, whatever the keyword. Only the first finding below was also checked on the 4B model:

• the C shape in .tjs produces confident wrong answers, reliably;
• any new shape produces zero wrong answers, reliably;
• an inline comment stating the rule takes comprehension to 5/5, on a model large enough to use it.

What does not survive: any ranking among match / when / given.

8. Where that leaves the decision

The measurement does not choose the keyword, so the structural arguments do. Both favour given:

Collision risk, counted in our own source on 2026-08-29:

None are reserved, so detection must exclude every one of those other uses, which is why when's 423 still count against it. match is worst, in the dangerous way: a method call is the shape most easily mistaken for the construct.

Semantics. This construct compares values with Eq. It does not destructure, bind, or guard. match names what Rust, Python and Scala do — pattern matching — so it over-promises to precisely the reader whose prior it was meant to recruit. given x reads in English as "given this value, these are the cases", which is what the code does.

There are also advantages a comprehension probe structurally cannot see: a rarer word is easier to search for, and documentation about given is not competing with a decade of String.prototype.match results. A cold-reading probe measures recognition, not findability — and recognition is the one thing a novel keyword is guaranteed to lose at.

That is worth stating carefully rather than as a rationalisation. The risk of reasoning this way is obvious: it can excuse any result. The check is that the argument was made before the re-run collapsed the ranking (in FINDINGS.md the collision and semantics arguments precede the retraction), and that the ranking collapsed on its own evidence rather than being argued away.

9. The fallback block: a measurement that legitimately abstains

Three spellings, same program, asking what an unmatched value returns. This was a one-off run, recorded only in the message of commit 1906d626:

All three, perfectly. Unlike the keyword ranking this is not noise — it is a real negative result, and the reason is structural: the fallback block's meaning is carried by its POSITION, not its name. A reader who has understood the arms understands the leftover block whatever it is called.

So the choice is design, and the argument that decides it is the same one that drove the rename:

• default re-imports the prior we just escaped. A reader who sees default inside given has been handed a piece of switch, and may reasonably reach for the rest of it — case, break, fallthrough. Renaming to shed a prior and then keeping one of its keywords gives back part of what the rename bought.
• otherwise is not a reserved word, so it carries the same collision problem given does, for no gain over a word that is.
• else is reserved, and already means exactly this. It parallels if/else, which every JavaScript reader knows, and it sits outside the arm list where it visually separates "the cases" from "everything else".

else it is. Worth recording that this was decided on argument with the measurement explicitly abstaining, rather than the measurement being ignored.

10. Where it landed, and what is still open

Decided and shipped. given is the construct; else is the fallback; switch keeps C semantics exactly and gets a warning pointing at the replacement, so nothing silently changes meaning. Existing code is upgraded at graduation where that is provably safe.

Still open (as of 2026-11-06):

• Re-measure with a cheat sheet. The no-answer mode is exactly what guidance fixes: in an earlier experiment, a small model writing AJS succeeded 0% of the time with no guidance and 67% with a short cheat sheet (FINDINGS.md, "Guidance A/B"). and cold reading is the worst case for a novel word and the best case for a familiar one. The keyword ranking should be re-taken under those conditions, with a much larger N on the no-answer column specifically.
• else if (cond) { }, considered and not taken. If else reads as if/else, that is the obvious next step. It would mix value dispatch with condition dispatch in one construct, which is a bigger change than it looks, and nothing needs it today.

11. What generalises

Three things, none of them about switch:

1. A pattern that needs a heavy-handed lint rule is a language defect. That is what started this, and it held up.
2. Correctness is stable; willingness to commit is not. A probe scored "correct out of N" silently mixes a stable signal with a noisy one. Read the columns separately, and treat a ranking built on the noisy one as unmeasured until it replicates. We wrote one up as a finding before it did.
3. If it behaves differently, it should look different. The out-of-band signal — the file extension — carries nothing to a reader. This is the single most transferable result here, and it applies to every remaining place TJS changes a JavaScript meaning in place.