@amritk/nish-x86_64-linux 0.17.0 → 0.20.0

package/std/json.ts

@@ -1,15 +1,17 @@
 /**
- * `std/json` — the value of one field of one flat JSON object.
+ * `std/json` — the value of a field, or of several, of one flat JSON object;
+ * and `JsonWriter`, which writes any JSON value into a byte buffer.
  *
- * It exists because the compiler's own machine-readable surface is JSON: under
- * `--json` every diagnostic is one flat object on a line of stdout, whose `code`
- * is a stable rule identifier (`AGENTS.md`, and `docs/wp12-release.md` for the
+ * The reader exists because the compiler's own machine-readable surface is
+ * JSON: under `--json` every diagnostic is one flat object on a line of
+ * stdout, whose `code` is a stable rule identifier (`AGENTS.md`, and `docs/wp12-release.md` for the
  * exit-code bands). A Nish program that reads that surface — a wrapper, an
  * editor plug-in, or `tests/nish/cli.ts`, which pins the contract — needs the
  * value of a named field and nothing else, and the language has no `JSON.parse`
  * to give it.
  *
- * So this is a **reader, not a parser**, and the difference is worth stating:
+ * So the reading half is a **reader, not a parser**, and the difference is
+ * worth stating:
  *
  *   - It answers **text**. A string field comes back with its escapes decoded
  *     and without its quotes; a number, a `true` or a `null` comes back as the
@@ -26,10 +28,10 @@
  *     whether the whole line was well-formed is asking a question this does not
  *     answer.
  *
- * There is one exported function on purpose. A `std/` module is compiled into
- * the program that imports it and the symbol namespace is flat
- * (`std/README.md`), so every name here is a name its importer cannot use: the
- * helpers are `json`-prefixed and the reader is the only export. Splitting a
+ * The reader is two exported functions, and few on purpose. A `std/` module
+ * is compiled into the program that imports it and the symbol namespace is
+ * flat (`std/README.md`), so every name here is a name its importer cannot
+ * use: every helper is `json`-prefixed or a method of `JsonWriter`. Splitting a
  * stream into lines and picking the ones that start with `{` is two calls the
  * caller already has — `splitLines` from `std/text` and `startsWith` — and
  * duplicating them here would cost more names than it saves.
@@ -46,6 +48,60 @@
  *       }
  *     }
  *
+ * `jsonField` scans from the start of the line on every call, so a caller that
+ * wants three fields of each line reads each line three times. `jsonFields`
+ * reads it once: `jsonFields(line, ["code", "line", "message"])` answers an
+ * array whose slot `k` is exactly what `jsonField(line, names[k])` answers —
+ * absent, first-of-a-duplicate and malformed input included — because the two
+ * share the step that reads one member (`jsonReadMember`) and stop at the same
+ * one. Its array goes back to the caller with the values in it, so a loop that
+ * calls it keeps its per-pass arena release, as one calling `jsonField` does;
+ * `jsonFields`' own comment says when that holds.
+ *
+ * **The writer** is for the other direction: a server's response body
+ * (WP34 N11, whose first caller is a TechEmpower `/json` entry writing
+ * `{"message":"Hello, World!"}` on every request). `JsonWriter` writes into a
+ * `u8[]` the caller owns and reuses, puts in every comma and colon itself,
+ * and allocates nothing per call except an `f64`'s digits, which it gives back
+ * before the call returns. What it writes is byte for byte what
+ * `JSON.stringify` writes for the same value: the seven short escapes and
+ * `\u00xx` below `0x20`, `/` and `0x7f` as themselves, integers as their
+ * digits, an `f64` as `String(v)` spells it with `-0` as `0`, and NaN and the
+ * infinities as `null`. `jsonStringifyString` is the same string rule
+ * answered as a string.
+ *
+ * **Two modes**, both off by default and both kept across `reset`, so a
+ * server sets them once. `setIndent(n)` and `setIndentTab()` write what
+ * `JSON.stringify(v, null, n)` and `JSON.stringify(v, null, "\t")` write:
+ * one member or element a line, `": "` after a key, an empty `{}` or `[]` on
+ * one line, and `n` clamped to 10. The indent is one byte stored as many times
+ * as the depth asks, so the indented text allocates no more than the minified
+ * one, and a `raw` fragment is copied as it is, not re-indented.
+ * `setStrict(true)` makes NaN and the infinities, which JSON cannot
+ * spell, the sticky `JSON_WRITE_NON_FINITE` instead of `null`: for a caller
+ * to whom a `null` where a number was due would be a silently corrupt record.
+ *
+ * **Misuse is a sticky code**, as in `nish/net/hpack`: never a panic, and no
+ * `Result` to carry on the hot path. The first call that cannot be honoured
+ * sets `failed` to a negative `JSON_WRITE_*` code — a value where a key is
+ * due, a key where a value is due, an unbalanced or mismatched `end*`,
+ * nesting past `JSON_WRITER_MAX_DEPTH`, a buffer with no room, a second
+ * top-level value, a bad `raw` window or `start`, a non-finite `f64` in strict
+ * mode — and every later call does nothing. A call that fails writes nothing
+ * past `buf.length` (a full buffer is checked before the bytes go in, never
+ * by the bounds check), so the caller writes the whole value, reads `failed`
+ * once at the end, and grows the buffer and retries or answers a 500. `complete()` says whether one
+ * whole value was written with every container closed.
+ *
+ * **A string is its bytes** (WP33 class C, `docs/wp33-round-trip.md` §3.2,
+ * the first row). The writer escapes by byte and copies every byte at or
+ * above `0x80`, so UTF-8 text comes out as the UTF-8 that `JSON.stringify`'s
+ * answer encodes to, and a string that is not UTF-8 — a lone `0xFF` — comes
+ * out raw, where no Node string could hold it in the first place. Under Node
+ * the same source reads UTF-16 units, which agree on ASCII and only there;
+ * `tests/link/std_json_writer` pins both edges natively, and its `node.ts`
+ * is the ASCII half that `tests/run.js` holds to `JSON.stringify` under Node.
+ *
  * Every offset here is a **byte** offset and every width is spelled, with each
  * length and byte a builtin answers read through `toI32` — `.length` and
  * `charCodeAt` answer `number`, which is `f64` under `--number-mode f64`, so the
@@ -53,14 +109,17 @@
  * (`docs/wp26-stdlib.md` §4).
  */
 
+const JSON_BACKSPACE: i32 = 8
 const JSON_TAB: i32 = 9
 const JSON_NEWLINE: i32 = 10
+const JSON_FORM_FEED: i32 = 12
 const JSON_CARRIAGE_RETURN: i32 = 13
 const JSON_SPACE: i32 = 32
 const JSON_QUOTE: i32 = 34
 const JSON_COMMA: i32 = 44
 const JSON_COLON: i32 = 58
 const JSON_BACKSLASH: i32 = 92
+const JSON_LETTER_U: i32 = 117
 const JSON_OPEN_BRACKET: i32 = 91
 const JSON_CLOSE_BRACKET: i32 = 93
 const JSON_OPEN_BRACE: i32 = 123
@@ -110,19 +169,74 @@ const jsonSkipBlank = (text: string, from: i32): i32 => {
   return i
 }
 
+/**
+ * How many bytes of a string body the scanners read one at a time before they
+ * hand the rest to `jsonClosingQuote`. A key or a short value ends inside
+ * them, and for those a call into the runtime costs more than the bytes do.
+ */
+const JSON_INLINE_SCAN: i32 = 16
+
+/**
+ * The index of the closing quote of a string body that has run on past the
+ * bytes the scanners read one at a time, searching from `start`, a byte no
+ * backslash has taken; `-1` when no quote closes it.
+ *
+ * The body is not walked: `indexOf` jumps to the next quote, which is one
+ * `memchr` in the runtime, and the run of backslashes just before that quote
+ * says whether it is escaped. The byte before the run is not a backslash — at
+ * the latest it is the opening quote — so the run starts where an escape can:
+ * an odd run ends in a backslash that takes this quote, and an even one is
+ * pairs of `\\` that leave it alone. The run may reach back past `start`, and
+ * that changes nothing: what lies before `start` ends on a byte no escape took,
+ * so any backslashes there are whole pairs. An escaped quote moves the search
+ * one byte past it, and the next run's count stops at that quote, so every
+ * backslash is counted once.
+ *
+ * The byte loops stay in the scanners rather than in here: most strings end
+ * in them and never make this call.
+ */
+const jsonClosingQuote = (text: string, start: i32): i32 => {
+  const length: i32 = toI32(text.length)
+  if (start < 0) {
+    return -1
+  }
+  let quote: i32 = toI32(text.indexOf('"', start))
+  // `quote >= start` is false for the `-1` of a miss.
+  while (quote >= start && quote < length) {
+    // The count stops at the opening quote at the latest, so `j >= 0` always
+    // holds, and `j < length` does because `j` starts below `quote`; both are
+    // spelled out because the bounds proof reads neither from a decrement of a
+    // callee's answer.
+    let j: i32 = quote - 1
+    while (j >= 0 && j < length && toI32(text.charCodeAt(j)) === JSON_BACKSLASH) {
+      j -= 1
+    }
+    if (((quote - 1 - j) & 1) === 0) {
+      return quote
+    }
+    quote = toI32(text.indexOf('"', quote + 1))
+  }
+  return -1
+}
+
 /**
  * The index just past the string literal whose opening quote is at `at`, or `-1`
  * when the quote is never closed. A backslash takes the byte after it with it,
  * which is all a scanner needs to know about escapes: `\"` cannot end the
- * literal and `\\` cannot make the next quote an escape.
+ * literal and `\\` cannot make the next quote an escape. The first
+ * `JSON_INLINE_SCAN` bytes are read here and the rest searched by
+ * `jsonClosingQuote`; the step over an escape can take the cursor one past
+ * them, which is still a byte no backslash has taken.
  */
 const jsonEndOfString = (text: string, at: i32): i32 => {
   const length: i32 = toI32(text.length)
   if (at < 0) {
     return -1
   }
+  const stop: i32 = at + 1 + JSON_INLINE_SCAN < length ? at + 1 + JSON_INLINE_SCAN : length
   let i: i32 = at + 1
-  while (i < length) {
+  // `i < length` follows from `i < stop`, and is there for the bounds proof.
+  while (i < stop && i < length) {
     const code: i32 = toI32(text.charCodeAt(i))
     if (code === JSON_BACKSLASH) {
       i += 2
@@ -133,7 +247,11 @@ const jsonEndOfString = (text: string, at: i32): i32 => {
     }
     i += 1
   }
-  return -1
+  if (i >= length) {
+    return -1
+  }
+  const quote: i32 = jsonClosingQuote(text, i)
+  return quote < 0 ? -1 : quote + 1
 }
 
 /**
@@ -146,10 +264,13 @@ const jsonEndOfString = (text: string, at: i32): i32 => {
  * ends at the first byte that cannot be part of it, which is the comma, the
  * closer or the blank that follows.
  *
- * The string skip inside an object is a flag in the one loop rather than a call
- * to `jsonEndOfString` that moves the cursor to wherever it answers: a cursor
- * that only ever steps forward keeps the lower bound the bounds proof needs,
- * and one assigned a callee's answer does not.
+ * A string value goes through the same loop as a string inside an object, and
+ * ends where its closing quote leaves the loop at depth zero. Each string is
+ * read as `jsonEndOfString` reads one, its first `JSON_INLINE_SCAN` bytes a
+ * byte at a time and the rest searched by `jsonClosingQuote`, and the byte loop
+ * is written out here rather than called: a call to `jsonEndOfString` from
+ * a second site is one LLVM stops inlining into `jsonReadMember`, and a call
+ * per string is what a line of short strings feels most.
  */
 const jsonEndOfValue = (text: string, at: i32): i32 => {
   const length: i32 = toI32(text.length)
@@ -157,30 +278,47 @@ const jsonEndOfValue = (text: string, at: i32): i32 => {
     return -1
   }
   const first: i32 = toI32(text.charCodeAt(at))
-  if (first === JSON_QUOTE) {
-    return jsonEndOfString(text, at)
-  }
-  if (first === JSON_OPEN_BRACE || first === JSON_OPEN_BRACKET) {
+  if (first === JSON_QUOTE || first === JSON_OPEN_BRACE || first === JSON_OPEN_BRACKET) {
     let depth: i32 = 0
-    let inString: boolean = false
     let i: i32 = at
-    while (i < length) {
+    // `i >= 0` always holds — `i` starts at `at` and only moves forward — and
+    // is in the test because a long string moves `i` to where
+    // `jsonClosingQuote` answers, and a cursor assigned a callee's answer is
+    // one the bounds proof stops following.
+    while (i >= 0 && i < length) {
       const code: i32 = toI32(text.charCodeAt(i))
-      if (inString) {
-        // `jsonEndOfString`'s rule: a backslash takes the byte after it along.
-        if (code === JSON_BACKSLASH) {
-          i += 2
-          continue
+      if (code === JSON_QUOTE) {
+        const stop: i32 = i + 1 + JSON_INLINE_SCAN < length ? i + 1 + JSON_INLINE_SCAN : length
+        let j: i32 = i + 1
+        let close: i32 = -1
+        while (j < stop && j < length) {
+          const inner: i32 = toI32(text.charCodeAt(j))
+          if (inner === JSON_BACKSLASH) {
+            j += 2
+            continue
+          }
+          if (inner === JSON_QUOTE) {
+            close = j
+            break
+          }
+          j += 1
         }
-        if (code === JSON_QUOTE) {
-          inString = false
+        if (close < 0) {
+          if (j >= length) {
+            return -1
+          }
+          close = jsonClosingQuote(text, j)
+          if (close < 0) {
+            return -1
+          }
         }
-        i += 1
+        if (depth === 0) {
+          return close + 1
+        }
+        i = close + 1
         continue
       }
-      if (code === JSON_QUOTE) {
-        inString = true
-      } else if (code === JSON_OPEN_BRACE || code === JSON_OPEN_BRACKET) {
+      if (code === JSON_OPEN_BRACE || code === JSON_OPEN_BRACKET) {
         depth += 1
       } else if (code === JSON_CLOSE_BRACE || code === JSON_CLOSE_BRACKET) {
         depth -= 1
@@ -261,6 +399,37 @@ const jsonUtf8 = (code: i32): string => {
   return `${lead}${middle}${String.fromCharCode(JSON_UTF8_CONTINUATION + (code & JSON_UTF8_LOW_SIX))}`
 }
 
+/** The number of bytes `jsonUtf8(code)` answers. */
+const jsonUtf8Width = (code: i32): i32 => {
+  if (code < JSON_UTF8_TWO_BYTE_FLOOR) {
+    return 1
+  }
+  if (code < JSON_UTF8_THREE_BYTE_FLOOR) {
+    return 2
+  }
+  return 3
+}
+
+/**
+ * Byte `k` of the `width` bytes `jsonUtf8(code)` answers: its arithmetic, one
+ * byte at a time, for a caller that compares the bytes rather than keeps them.
+ */
+const jsonUtf8Byte = (code: i32, width: i32, k: i32): i32 => {
+  if (width === 1) {
+    return code
+  }
+  if (k === 0) {
+    if (width === 2) {
+      return JSON_UTF8_TWO_BYTE_LEAD + (code >> 6)
+    }
+    return JSON_UTF8_THREE_BYTE_LEAD + (code >> 12)
+  }
+  if (k === width - 1) {
+    return JSON_UTF8_CONTINUATION + (code & JSON_UTF8_LOW_SIX)
+  }
+  return JSON_UTF8_CONTINUATION + ((code >> 6) & JSON_UTF8_LOW_SIX)
+}
+
 /**
  * The bytes of `text[at..end)` with the JSON escapes decoded — the body of a
  * string literal, without its quotes.
@@ -273,7 +442,7 @@ const jsonUtf8 = (code: i32): string => {
  * reading of anything else.
  */
 const jsonUnescape = (text: string, at: i32, end: i32): string => {
-  // Both callers pass the inside of a literal `jsonEndOfString` found, so
+  // Both callers pass the inside of a literal the scanners found, so
   // `0 <= at` and `end <= text.length` always hold. Saying so here is what
   // proves every read below in range and drops the `substring` clamps.
   if (at < 0 || end > toI32(text.length)) {
@@ -343,6 +512,190 @@ const jsonUnescape = (text: string, at: i32, end: i32): string => {
   return parts.join("")
 }
 
+/** Whether byte `j` of `name` is `code`; an index past either end is not. */
+const jsonNameHas = (name: string, j: i32, code: i32): boolean =>
+  j >= 0 && j < toI32(name.length) && toI32(name.charCodeAt(j)) === code
+
+/**
+ * Whether `jsonUnescape(text, at, end)` would answer `name`, decided without
+ * building it.
+ *
+ * `jsonField` and `jsonFields` ask this of every key they walk past, and almost
+ * every answer is no, so the question is answered the way it is asked: the literal and `name`
+ * are walked together, each escape decoded where it stands, and the first byte
+ * that differs ends the walk. Every escape reads as `jsonUnescape` reads it —
+ * the short forms, a `\u` as the bytes `jsonUtf8` would build, a broken `\u`
+ * as the two bytes `\u`, a backslash with no letter after it as itself, and
+ * any other escape as the byte it escapes — so a key matches here exactly when
+ * its decoded text would.
+ */
+const jsonKeyEquals = (text: string, at: i32, end: i32, name: string): boolean => {
+  // `jsonUnescape`'s guard, for the same reason: every caller passes the
+  // inside of a key `jsonReadMember` found with `jsonEndOfString`.
+  if (at < 0 || end > toI32(text.length)) {
+    return false
+  }
+  let i: i32 = at
+  let j: i32 = 0
+  while (i < end) {
+    const code: i32 = toI32(text.charCodeAt(i))
+    if (code !== JSON_BACKSLASH) {
+      if (!jsonNameHas(name, j, code)) {
+        return false
+      }
+      i += 1
+      j += 1
+      continue
+    }
+    const letter: i32 = i + 1 < end ? toI32(text.charCodeAt(i + 1)) : 0
+    if (letter === JSON_LETTER_U) {
+      const point: i32 = jsonHex4(text, i + 2, end)
+      if (point < 0) {
+        if (!jsonNameHas(name, j, JSON_BACKSLASH) || !jsonNameHas(name, j + 1, JSON_LETTER_U)) {
+          return false
+        }
+        i += 2
+        j += 2
+        continue
+      }
+      const width: i32 = jsonUtf8Width(point)
+      let k: i32 = 0
+      while (k < width) {
+        if (!jsonNameHas(name, j + k, jsonUtf8Byte(point, width, k))) {
+          return false
+        }
+        k += 1
+      }
+      i += 6
+      j += width
+      continue
+    }
+    // Every other escape decodes to one byte.
+    let decoded: i32 = letter
+    if (letter === 110) {
+      decoded = JSON_NEWLINE
+    } else if (letter === 116) {
+      decoded = JSON_TAB
+    } else if (letter === 114) {
+      decoded = JSON_CARRIAGE_RETURN
+    } else if (letter === 98) {
+      decoded = JSON_BACKSPACE
+    } else if (letter === 102) {
+      decoded = JSON_FORM_FEED
+    } else if (letter === 0) {
+      decoded = JSON_BACKSLASH
+    }
+    if (!jsonNameHas(name, j, decoded)) {
+      return false
+    }
+    // A backslash with no letter after it is one byte of the literal and every
+    // other escape two. The steps are constants rather than a variable because
+    // a cursor moved by a variable is one the bounds proof stops following.
+    if (letter === 0) {
+      i += 1
+    } else {
+      i += 2
+    }
+    j += 1
+  }
+  return j === toI32(name.length)
+}
+
+/**
+ * Where one member of an object lies, as `jsonReadMember` found it: the inside
+ * of its key literal, its value, and the opening quote of the key after it.
+ *
+ * It is a class so that one step can answer the four offsets together, and
+ * each reader allocates exactly one, which never leaves the reader: that is
+ * what keeps it a stack slot rather than an arena allocation.
+ */
+class JsonMember {
+  keyAt: i32 = 0
+  keyEnd: i32 = 0
+  valueAt: i32 = 0
+  valueEnd: i32 = 0
+  /** The opening quote of the next key, or `-1` when no comma follows the value. */
+  next: i32 = -1
+}
+
+/**
+ * The opening quote of the first key of `object`, or `-1` when `object` does
+ * not start, past any blanks, with a `{`.
+ */
+const jsonFirstKey = (object: string): i32 => {
+  const length: i32 = toI32(object.length)
+  const i: i32 = jsonSkipBlank(object, 0)
+  if (i >= length || toI32(object.charCodeAt(i)) !== JSON_OPEN_BRACE) {
+    return -1
+  }
+  return jsonSkipBlank(object, i + 1)
+}
+
+/**
+ * Reads the member whose key's opening quote is at `at` into `member`, and
+ * answers whether there was one.
+ *
+ * This is the per-key step `jsonField` and `jsonFields` share, so they cannot
+ * disagree about where a member ends: `false` for anything that is not a key,
+ * a colon and a whole value in that order, which is the point at which both
+ * stop. A value need not be followed by a comma — a truncated object still
+ * answers the fields before the cut — so a missing one only sets `next` to
+ * `-1`, and the read that follows answers `false`.
+ */
+const jsonReadMember = (object: string, at: i32, member: JsonMember): boolean => {
+  const length: i32 = toI32(object.length)
+  // `jsonSkipBlank` never answers a negative index for a non-negative one, but
+  // the bounds proof does not look inside a callee, so every cursor it answers
+  // is tested for `i < 0` beside `i >= length`: the pair is what lets each read
+  // below go without a check.
+  if (at < 0 || at >= length || toI32(object.charCodeAt(at)) !== JSON_QUOTE) {
+    return false
+  }
+  const keyEnd: i32 = jsonEndOfString(object, at)
+  if (keyEnd < 0) {
+    return false
+  }
+  const colon: i32 = jsonSkipBlank(object, keyEnd)
+  if (colon < 0 || colon >= length || toI32(object.charCodeAt(colon)) !== JSON_COLON) {
+    return false
+  }
+  const valueAt: i32 = jsonSkipBlank(object, colon + 1)
+  const valueEnd: i32 = jsonEndOfValue(object, valueAt)
+  if (valueEnd < 0) {
+    return false
+  }
+  member.keyAt = at + 1
+  member.keyEnd = keyEnd - 1
+  member.valueAt = valueAt
+  member.valueEnd = valueEnd
+  const comma: i32 = jsonSkipBlank(object, valueEnd)
+  if (comma < 0 || comma >= length || toI32(object.charCodeAt(comma)) !== JSON_COMMA) {
+    member.next = -1
+  } else {
+    member.next = jsonSkipBlank(object, comma + 1)
+  }
+  return true
+}
+
+/**
+ * The text a member's value answers: a string unquoted and unescaped, anything
+ * else as the bytes it was written with.
+ */
+const jsonValueText = (object: string, member: JsonMember): string => {
+  const valueAt: i32 = member.valueAt
+  const valueEnd: i32 = member.valueEnd
+  // `jsonReadMember` only fills in a value `jsonEndOfValue` ended, which starts
+  // inside the object and never ends past it, so this changes no answer: it is
+  // the range the value's first byte and its `substring` are proved in.
+  if (valueAt < 0 || valueAt >= valueEnd || valueEnd > toI32(object.length)) {
+    return ""
+  }
+  if (toI32(object.charCodeAt(valueAt)) === JSON_QUOTE) {
+    return jsonUnescape(object, valueAt + 1, valueEnd - 1)
+  }
+  return object.substring(valueAt, valueEnd)
+}
+
 /**
  * The value of `name` in `object`, or `null` when the object does not have that
  * field.
@@ -358,45 +711,1034 @@ const jsonUnescape = (text: string, at: i32, end: i32): string => {
  * and it is the shape the compiler's `--json` line has.
  */
 export const jsonField = (object: string, name: string): string | null => {
-  const length: i32 = toI32(object.length)
-  let i: i32 = jsonSkipBlank(object, 0)
-  if (i >= length || toI32(object.charCodeAt(i)) !== JSON_OPEN_BRACE) {
-    return null
+  const member: JsonMember = new JsonMember()
+  let at: i32 = jsonFirstKey(object)
+  while (jsonReadMember(object, at, member)) {
+    // The key is compared where it stands rather than unescaped into a string
+    // first: every key before the one asked for is a no, and a no should not
+    // cost an allocation.
+    if (jsonKeyEquals(object, member.keyAt, member.keyEnd, name)) {
+      return jsonValueText(object, member)
+    }
+    at = member.next
   }
-  i = jsonSkipBlank(object, i + 1)
-  // `jsonSkipBlank` never answers a negative index for a non-negative one, but
-  // the bounds proof does not look inside a callee, so every cursor it answers
-  // is tested for `i < 0` beside `i >= length`: the pair is what lets each read
-  // below go without a check.
-  while (i >= 0 && i < length && toI32(object.charCodeAt(i)) === JSON_QUOTE) {
-    const keyEnd: i32 = jsonEndOfString(object, i)
-    if (keyEnd < 0) {
-      return null
-    }
-    const key: string = jsonUnescape(object, i + 1, keyEnd - 1)
-    i = jsonSkipBlank(object, keyEnd)
-    if (i < 0 || i >= length || toI32(object.charCodeAt(i)) !== JSON_COLON) {
-      return null
-    }
-    const valueAt: i32 = jsonSkipBlank(object, i + 1)
-    const valueEnd: i32 = jsonEndOfValue(object, valueAt)
-    // `jsonEndOfValue` answers `-1` for a `valueAt` outside the object and never
-    // answers past its end, so the last three tests change no answer: they are
-    // the range the value's first byte and its `substring` are proved in.
-    if (valueEnd < 0 || valueAt < 0 || valueAt >= length || valueEnd > toI32(object.length)) {
-      return null
-    }
-    if (key === name) {
-      if (toI32(object.charCodeAt(valueAt)) === JSON_QUOTE) {
-        return jsonUnescape(object, valueAt + 1, valueEnd - 1)
+  return null
+}
+
+/**
+ * The value of every one of `names` in `object`, in the order of `names`: slot
+ * `k` is exactly what `jsonField(object, names[k])` answers.
+ *
+ * It is for a caller that wants several fields of one line — a diagnostic's
+ * `code`, `line` and `message` — and would otherwise scan the line once per
+ * field. This scans it once, left to right, and stops as soon as every name has
+ * answered: a speed path and nothing more, since a slot is filled only once
+ * and reading on could change no answer. Each slot keeps the **first** field of its name, as `jsonField`
+ * does; a name asked for twice answers in both slots; and a malformed object
+ * answers in each slot what `jsonField` answers for that name, because both
+ * stop at the same member.
+ *
+ * The answer is a fresh array and the only allocation besides the values. Each
+ * value is stored into it by a plain `values[k] = text` statement, and the
+ * array is only stored into, tested and returned, so the values travel with
+ * the array: the call lets nothing else out (LANGUAGE.md, "Memory model", a
+ * value stored into an array that is returned with it). A loop calling this
+ * keeps its per-pass release on a line older than the pass, as `jsonField`'s
+ * does, and a `using a = arena()` block may hold the call. On a line built in
+ * the pass neither reader keeps the release (LANGUAGE.md, "Memory model").
+ * Reading `values` back, passing it to a function, or storing it anywhere
+ * before the return would undo this; `tests/link/std_json` pins the flat
+ * arena and the `using` block.
+ */
+export const jsonFields = (object: string, names: string[]): (string | null)[] => {
+  const count: i32 = toI32(names.length)
+  const values: (string | null)[] = new Array<string | null>(count)
+  const member: JsonMember = new JsonMember()
+  let missing: i32 = count
+  let at: i32 = jsonFirstKey(object)
+  while (missing > 0 && jsonReadMember(object, at, member)) {
+    // A value is built once per member however many names it answers, and
+    // only when one of them does.
+    let text: string | null = null
+    let k: i32 = 0
+    // Bounded by both lengths, which are the same, because the bounds proof
+    // follows each array by its own length and not by `count`.
+    while (k < toI32(values.length) && k < toI32(names.length)) {
+      if (values[k] === null && jsonKeyEquals(object, member.keyAt, member.keyEnd, names[k])) {
+        if (text === null) {
+          text = jsonValueText(object, member)
+        }
+        // Always true: the loop's own test. A call stands between it and the
+        // store, and a call is where the bounds proof forgets a length.
+        if (k < toI32(values.length)) {
+          values[k] = text
+        }
+        missing -= 1
       }
-      return object.substring(valueAt, valueEnd)
+      k += 1
     }
-    i = jsonSkipBlank(object, valueEnd)
-    if (i < 0 || i >= length || toI32(object.charCodeAt(i)) !== JSON_COMMA) {
-      return null
+    at = member.next
+  }
+  return values
+}
+
+// ---- The writer ---------------------------------------------------------------
+
+/** `JsonWriter.failed` while every call so far has been a well-formed write that fitted. */
+export const JSON_WRITE_OK: i32 = 0
+/** A value, an opener or a `raw` fragment, written in an object where a key is due. */
+export const JSON_WRITE_KEY_EXPECTED: i32 = -1
+/** `key` outside an object or straight after another key, or `endObject` straight after a key. */
+export const JSON_WRITE_VALUE_EXPECTED: i32 = -2
+/** `endObject` or `endArray` with no container open, or closing the other kind. */
+export const JSON_WRITE_UNBALANCED: i32 = -3
+/** A `beginObject` or `beginArray` that would nest deeper than `JSON_WRITER_MAX_DEPTH`. */
+export const JSON_WRITE_TOO_DEEP: i32 = -4
+/** A write that does not fit between the cursor and `buf.length`; nothing past `buf.length` is touched. */
+export const JSON_WRITE_FULL: i32 = -5
+/** A second value at the top level, after the first was written whole. */
+export const JSON_WRITE_DONE: i32 = -6
+/** A `raw` window outside its array, or a `start` outside the writer's buffer. */
+export const JSON_WRITE_BAD_WINDOW: i32 = -7
+/** An `f64` that is NaN or an infinity, written by a writer `setStrict(true)` made strict. */
+export const JSON_WRITE_NON_FINITE: i32 = -8
+
+/**
+ * How deep a writer nests objects and arrays. The kind of each open container
+ * is one bit of two `i32` fields inside the writer, so a nesting past it is
+ * `JSON_WRITE_TOO_DEEP` rather than a stack that grows.
+ */
+export const JSON_WRITER_MAX_DEPTH: i32 = 64
+/** The lowest bit, spelled `i32` so that `<<` has an `i32` on its left under `--number-mode f64` too. */
+const JSON_WRITER_BIT: i32 = 1
+/** The shift that moves a word's lowest bit to its highest, and its highest to its lowest with `>>>`. */
+const JSON_WRITER_TOP_BIT: i32 = 31
+/**
+ * The widest indent, in spaces: `JSON.stringify` clamps its `space` argument
+ * to 10, so a wider one writes what 10 writes. At `JSON_WRITER_MAX_DEPTH` it
+ * puts 640 bytes before a line's value, which is the most a line break costs.
+ */
+const JSON_WRITER_MAX_INDENT: i32 = 10
+
+const JSON_SLASH_B: i32 = 98
+const JSON_SLASH_F: i32 = 102
+const JSON_SLASH_N: i32 = 110
+const JSON_SLASH_R: i32 = 114
+const JSON_SLASH_T: i32 = 116
+const JSON_DIGIT_ZERO: i32 = 48
+const JSON_MINUS: i32 = 45
+const JSON_DECIMAL_BASE: i32 = 10
+const JSON_LOWER_A: i32 = 97
+
+/**
+ * The letter of the short escape for `code` — `"`, `\`, backspace, form feed,
+ * newline, carriage return or tab — or `0` when it has none.
+ */
+const jsonShortEscape = (code: i32): i32 => {
+  if (code === JSON_QUOTE || code === JSON_BACKSLASH) {
+    return code
+  }
+  if (code === JSON_NEWLINE) {
+    return JSON_SLASH_N
+  }
+  if (code === JSON_TAB) {
+    return JSON_SLASH_T
+  }
+  if (code === JSON_CARRIAGE_RETURN) {
+    return JSON_SLASH_R
+  }
+  if (code === JSON_BACKSPACE) {
+    return JSON_SLASH_B
+  }
+  if (code === JSON_FORM_FEED) {
+    return JSON_SLASH_F
+  }
+  return 0
+}
+
+/** One lower-case hex digit, as `JSON.stringify` writes the last two of a `\u00xx`. */
+const jsonHexByte = (nibble: i32): i32 =>
+  nibble < JSON_DECIMAL_BASE ? JSON_DIGIT_ZERO + nibble : JSON_LOWER_A + nibble - JSON_DECIMAL_BASE
+
+/** Whether byte `code` of a string goes inside the quotes as itself: JSON escapes only `"`, `\` and the bytes below a space. */
+const jsonIsPlainByte = (code: i32): boolean =>
+  code >= JSON_SPACE && code !== JSON_QUOTE && code !== JSON_BACKSLASH
+
+/**
+ * How many bytes byte `code` of a string takes inside the quotes: itself, a
+ * two-byte short escape, or the six bytes of `\u00xx`.
+ */
+const jsonEscapedWidth = (code: i32): i32 => {
+  if (jsonIsPlainByte(code)) {
+    return 1
+  }
+  return jsonShortEscape(code) !== 0 ? 2 : 6
+}
+
+/**
+ * A JSON text written into a byte buffer the caller owns: `buf[start ..)`,
+ * up to `buf.length`, with `end` the cursor. Every comma and colon is the
+ * writer's, so the caller says only what the value is:
+ *
+ *     const w = new JsonWriter(out, 0)
+ *     w.beginObject()
+ *     w.key("message")
+ *     w.string("Hello, World!")
+ *     w.endObject()
+ *     if (w.complete()) {
+ *       // out[0 .. w.end) is {"message":"Hello, World!"}
+ *     }
+ *
+ * No call allocates except `f64` (whose digits are a string the call
+ * releases before it returns) and `text`: a writer reset onto the same buffer
+ * for each request keeps `Arena.used()` flat, which `tests/link/std_json_writer`
+ * measures over 10,000 writes.
+ *
+ * Misuse is a sticky code, not a panic and not a `Result` (the module header
+ * has the policy). Once `failed` is negative every later call does nothing, so
+ * a caller writes the whole value and reads `failed` once at the end.
+ */
+export class JsonWriter {
+  buf: u8[]
+  start: i32 = 0
+  /** The cursor: the bytes written are `buf[start .. end)`. */
+  end: i32 = 0
+  /** `JSON_WRITE_OK`, or the first `JSON_WRITE_*` code a call hit. */
+  failed: i32 = 0
+  /** How many containers are open. */
+  depth: i32 = 0
+  /**
+   * The kinds of the open containers, one bit each, 1 for an object, as a
+   * stack 64 bits deep: the innermost is bit 0 of `objectsLow`, an opener
+   * shifts the pair left by one and a closer shifts it back. So the check
+   * before every value — is the innermost container an object? — is one
+   * `and` of one word, and costs the minified text nothing a cached copy
+   * would save. Two `i32` words rather than an `i64` or an array, so that a
+   * writer allocates nothing and the module still runs under Node, where an
+   * `i64` is a BigInt.
+   */
+  objectsLow: i32 = 0
+  objectsHigh: i32 = 0
+  /**
+   * What goes before the next key or element of the innermost container,
+   * one `JSON_WRITER_SEP_*`: nothing, a comma, and in an indented text a
+   * line break or a comma and a line break. The minified text tests it only
+   * where it would test a "comma due" flag, against 0 and 1, so the indented
+   * states cost it nothing; bit 1 is the indent and every step keeps it.
+   */
+  sep: i32 = 0
+  /**
+   * How many `indentByte`s each level of nesting puts at the start of a line,
+   * or `0` for the minified text. A mode, not a part of the text: `reset`
+   * keeps it, so a writer set up once writes every text the same way.
+   */
+  indentWidth: i32 = 0
+  /** The byte an indent is made of: a space, or a tab after `setIndentTab`. */
+  indentByte: i32 = 32
+  /** Whether a key has been written in the innermost object and its value is due. */
+  afterKey: boolean = false
+  /** Whether the top-level value has been written whole. */
+  done: boolean = false
+  /** Whether a NaN or infinite `f64` is `JSON_WRITE_NON_FINITE` rather than `null`. Kept by `reset`. */
+  strict: boolean = false
+
+  constructor(buf: u8[], start: i32) {
+    this.buf = buf
+    this.reset(buf, start)
+  }
+
+  /**
+   * Starts a new text at `buf[start ..)`, forgetting everything the last one
+   * wrote and every error it hit: what a server calls once per response, on
+   * the buffer it reuses. A `start` outside `buf` is `JSON_WRITE_BAD_WINDOW`.
+   */
+  reset(buf: u8[], start: i32): void {
+    this.buf = buf
+    this.start = start
+    this.end = start
+    this.depth = 0
+    this.objectsLow = 0
+    this.objectsHigh = 0
+    this.sep = this.indentWidth !== 0 ? JSON_WRITER_SEP_INDENTED : JSON_WRITER_SEP_NONE
+    this.afterKey = false
+    this.done = false
+    this.failed = start < 0 || start > toI32(buf.length) ? JSON_WRITE_BAD_WINDOW : JSON_WRITE_OK
+  }
+
+  /**
+   * Indents the text by `spaces` spaces a level, as `JSON.stringify(v, null,
+   * spaces)` does: each member and element on a line of its own, one space
+   * after a key's colon, and an empty `{}` or `[]` left on one line. `spaces`
+   * is clamped to 10 as `JSON.stringify` clamps it, and below 1 is the
+   * minified text, the default. A mode that `reset` keeps; set it before the
+   * text, since a change in the middle of one applies from the next byte.
+   */
+  setIndent(spaces: i32): void {
+    let width: i32 = spaces
+    if (width < 0) {
+      width = 0
+    } else if (width > JSON_WRITER_MAX_INDENT) {
+      width = JSON_WRITER_MAX_INDENT
     }
-    i = jsonSkipBlank(object, i + 1)
+    this.indentWidth = width
+    this.indentByte = JSON_SPACE
+    this.sep =
+      (this.sep & JSON_WRITER_SEP_COMMA) | (width !== 0 ? JSON_WRITER_SEP_INDENTED : JSON_WRITER_SEP_NONE)
   }
-  return null
+
+  /** Indents the text by one tab a level, as `JSON.stringify(v, null, "\t")` does. */
+  setIndentTab(): void {
+    this.indentWidth = 1
+    this.indentByte = JSON_TAB
+    this.sep = this.sep | JSON_WRITER_SEP_INDENTED
+  }
+
+  /**
+   * Whether an `f64` that is NaN or an infinity fails the text with
+   * `JSON_WRITE_NON_FINITE`, writing nothing, rather than being written as
+   * the `null` `JSON.stringify` writes. Off by default; a mode that `reset`
+   * keeps. Strict is for a caller to whom a `null` where a number was due is
+   * a corrupt record rather than a missing one.
+   */
+  setStrict(strict: boolean): void {
+    this.strict = strict
+  }
+
+  /** How many bytes have been written since `reset`. */
+  written(): i32 {
+    return this.end - this.start
+  }
+
+  /** Whether one whole value has been written, every container closed, and nothing failed. */
+  complete(): boolean {
+    return this.failed === JSON_WRITE_OK && this.done
+  }
+
+  /**
+   * The bytes written so far, `buf[start .. end)`, as a string. A convenience
+   * that allocates a byte at a time, for a caller that wants text rather than
+   * bytes; a server sends `buf` itself.
+   */
+  text(): string {
+    const buf: u8[] = this.buf
+    const parts: string[] = []
+    for (let k: i32 = this.start; k >= 0 && k < this.end && k < toI32(buf.length); k += 1) {
+      parts.push(String.fromCharCode(toI32(buf[k])))
+    }
+    return parts.join("")
+  }
+
+  beginObject(): void {
+    jsonWriterOpen(this, true, JSON_OPEN_BRACE)
+  }
+
+  endObject(): void {
+    if (this.sep === JSON_WRITER_SEP_COMMA_BREAK) {
+      jsonWriterCloseIndented(this, true, JSON_CLOSE_BRACE)
+    } else {
+      jsonWriterClose(this, true, JSON_CLOSE_BRACE)
+    }
+  }
+
+  beginArray(): void {
+    jsonWriterOpen(this, false, JSON_OPEN_BRACKET)
+  }
+
+  endArray(): void {
+    if (this.sep === JSON_WRITER_SEP_COMMA_BREAK) {
+      jsonWriterCloseIndented(this, false, JSON_CLOSE_BRACKET)
+    } else {
+      jsonWriterClose(this, false, JSON_CLOSE_BRACKET)
+    }
+  }
+
+  /** The next member's key, with the comma before it and the colon after it. */
+  key(name: string): void {
+    if (this.failed !== JSON_WRITE_OK) {
+      return
+    }
+    if (this.depth === 0 && this.done) {
+      this.failed = JSON_WRITE_DONE
+      return
+    }
+    if (!jsonWriterInObject(this) || this.afterKey) {
+      this.failed = JSON_WRITE_VALUE_EXPECTED
+      return
+    }
+    const sep: i32 = this.sep
+    if (sep !== JSON_WRITER_SEP_NONE) {
+      if (sep !== JSON_WRITER_SEP_COMMA) {
+        jsonWriterIndented(this, this.depth, name)
+        return
+      }
+      if (!jsonWriterPutByte(this, JSON_COMMA)) {
+        return
+      }
+    }
+    if (jsonWriterPutString(this, name) && jsonWriterPutByte(this, JSON_COLON)) {
+      this.afterKey = true
+    }
+  }
+
+  /** `s` quoted and escaped as `JSON.stringify` escapes it; every other byte goes through as itself. */
+  string(s: string): void {
+    if (jsonWriterValueDue(this) && jsonWriterPutString(this, s)) {
+      jsonWriterValueDone(this)
+    }
+  }
+
+  /**
+   * `key` for a name held as bytes, `bytes[off .. off + len)`, escaped exactly
+   * as `key` escapes a string of those bytes, and allocating nothing: what a
+   * caller that keeps its text in a byte buffer, such as `nish/json-value`'s
+   * `JsonDocument`, writes without making a string per key. A window outside
+   * `bytes` is `JSON_WRITE_BAD_WINDOW`, checked once, before anything is
+   * written.
+   */
+  keyBytes(bytes: u8[], off: i32, len: i32): void {
+    if (this.failed !== JSON_WRITE_OK) {
+      return
+    }
+    if (!jsonWriterWindowOk(this, bytes, off, len)) {
+      return
+    }
+    if (this.depth === 0 && this.done) {
+      this.failed = JSON_WRITE_DONE
+      return
+    }
+    if (!jsonWriterInObject(this) || this.afterKey) {
+      this.failed = JSON_WRITE_VALUE_EXPECTED
+      return
+    }
+    const sep: i32 = this.sep
+    const indented: boolean = sep !== JSON_WRITER_SEP_NONE && sep !== JSON_WRITER_SEP_COMMA
+    if (indented) {
+      if (!jsonWriterBreakBeforeKey(this)) {
+        return
+      }
+    } else if (sep === JSON_WRITER_SEP_COMMA && !jsonWriterPutByte(this, JSON_COMMA)) {
+      return
+    }
+    if (
+      jsonWriterPutBytes(this, bytes, off, len) &&
+      jsonWriterPutByte(this, JSON_COLON) &&
+      (!indented || jsonWriterPutByte(this, JSON_SPACE))
+    ) {
+      this.afterKey = true
+    }
+  }
+
+  /**
+   * `string` for text held as bytes, `bytes[off .. off + len)`: the same
+   * quotes and escapes, byte for byte, and no allocation. A window outside
+   * `bytes` is `JSON_WRITE_BAD_WINDOW`, checked once, before anything is
+   * written.
+   */
+  stringBytes(bytes: u8[], off: i32, len: i32): void {
+    if (this.failed !== JSON_WRITE_OK) {
+      return
+    }
+    if (!jsonWriterWindowOk(this, bytes, off, len)) {
+      return
+    }
+    if (jsonWriterValueDue(this) && jsonWriterPutBytes(this, bytes, off, len)) {
+      jsonWriterValueDone(this)
+    }
+  }
+
+  i32(v: i32): void {
+    if (jsonWriterValueDue(this) && jsonWriterPutDigits(this, v, -1)) {
+      jsonWriterValueDone(this)
+    }
+  }
+
+  /**
+   * One past `i32`'s range is ten digits, so the last digit is split off in
+   * `u32` and the nine before it are an `i32`'s.
+   */
+  u32(v: u32): void {
+    if (!jsonWriterValueDue(this)) {
+      return
+    }
+    // The largest `u32` whose digits fit an `i32`; a module constant cannot be a `u32`.
+    const i32Max: u32 = 2147483647
+    let written: boolean = false
+    if (v <= i32Max) {
+      written = jsonWriterPutDigits(this, toI32(v), -1)
+    } else {
+      const ten: u32 = 10
+      const last: u32 = v % ten
+      written = jsonWriterPutDigits(this, toI32((v - last) / ten), toI32(last))
+    }
+    if (written) {
+      jsonWriterValueDone(this)
+    }
+  }
+
+  /** The digits of `v`, the minimum included: the arithmetic stays on the negative side, where it fits. */
+  i64(v: i64): void {
+    if (jsonWriterValueDue(this) && jsonWriterPutDigits64(this, v)) {
+      jsonWriterValueDone(this)
+    }
+  }
+
+  /**
+   * `v` as `String(v)` spells it, which is `JSON.stringify`'s rule: the
+   * shortest digits that read back as `v`, `-0` as `0`, and `null` for NaN
+   * and both infinities, which JSON cannot spell — or, once `setStrict(true)`,
+   * `JSON_WRITE_NON_FINITE` for those three, with nothing written.
+   */
+  f64(v: f64): void {
+    // `v - v` is `0` for every finite `v`, and NaN for NaN and both infinities.
+    if (v - v !== toF64(0)) {
+      if (!this.strict) {
+        this.nullValue()
+      } else if (jsonWriterValueAllowed(this)) {
+        this.failed = JSON_WRITE_NON_FINITE
+      }
+    } else if (jsonWriterValueDue(this) && jsonWriterPutF64(this, v)) {
+      jsonWriterValueDone(this)
+    }
+  }
+
+  boolean(v: boolean): void {
+    if (jsonWriterValueDue(this) && jsonWriterPutText(this, v ? "true" : "false")) {
+      jsonWriterValueDone(this)
+    }
+  }
+
+  /** `null`. The method is not named `null`, which the parser refuses as a member name. */
+  nullValue(): void {
+    if (jsonWriterValueDue(this) && jsonWriterPutText(this, "null")) {
+      jsonWriterValueDone(this)
+    }
+  }
+
+  /**
+   * `bytes[off .. off + len)`, copied as it is and counted as one value: a
+   * fragment the caller encoded already, such as a cached object. Nothing in
+   * it is checked, so a fragment that is not one whole JSON value makes a
+   * text that is not JSON either. The bytes are copied front to back, so
+   * `bytes` is not the writer's own buffer at a window the copy overtakes.
+   * In an indented text the fragment goes in where a value would, after its
+   * line break and indent, but its own bytes are not re-indented: an object
+   * fragment stays on one line, where `JSON.stringify` would spread it out.
+   */
+  raw(bytes: u8[], off: i32, len: i32): void {
+    if (this.failed !== JSON_WRITE_OK) {
+      return
+    }
+    if (off < 0 || len < 0 || off > toI32(bytes.length) - len) {
+      this.failed = JSON_WRITE_BAD_WINDOW
+      return
+    }
+    if (!jsonWriterValueDue(this)) {
+      return
+    }
+    const buf: u8[] = this.buf
+    const at: i32 = this.end
+    if (at < 0 || at > toI32(buf.length) - len) {
+      this.failed = JSON_WRITE_FULL
+      return
+    }
+    for (let k: i32 = 0; k < len && off + k < toI32(bytes.length) && at + k < toI32(buf.length); k += 1) {
+      if (off + k >= 0 && at + k >= 0) {
+        buf[at + k] = bytes[off + k]
+      }
+    }
+    this.end = at + len
+    jsonWriterValueDone(this)
+  }
+}
+
+/** Whether the innermost open container is an object; `false` at the top level. */
+const jsonWriterInObject = (w: JsonWriter): boolean => (w.objectsLow & JSON_WRITER_BIT) !== 0
+
+/**
+ * Whether a value may be written now, with the comma before it written when
+ * one is due; `false`, with `failed` set, when the writer has failed, a key
+ * is due, or the top-level value is already whole.
+ */
+const jsonWriterValueDue = (w: JsonWriter): boolean => {
+  if (w.failed !== JSON_WRITE_OK) {
+    return false
+  }
+  if (w.depth === 0) {
+    if (w.done) {
+      w.failed = JSON_WRITE_DONE
+      return false
+    }
+    return true
+  }
+  if (w.afterKey) {
+    w.afterKey = false
+    return true
+  }
+  if (jsonWriterInObject(w)) {
+    w.failed = JSON_WRITE_KEY_EXPECTED
+    return false
+  }
+  // A comma is the common case, every element but the first, so it is
+  // tested first and costs the one compare a "comma due" flag would.
+  const sep: i32 = w.sep
+  if (sep === JSON_WRITER_SEP_COMMA) {
+    return jsonWriterPutByte(w, JSON_COMMA)
+  }
+  return sep === JSON_WRITER_SEP_NONE || jsonWriterIndented(w, w.depth, "")
+}
+
+/**
+ * `jsonWriterValueDue`'s checks without its writes: whether a value may be
+ * written now, with `failed` set to the misuse when not. Strict `f64` asks
+ * it before it fails a non-finite value, so a value where a key is due, or
+ * after the top-level value, keeps the code it has for every other value:
+ * the first misuse wins, and a non-finite value is reported only when it is
+ * the first thing wrong.
+ */
+const jsonWriterValueAllowed = (w: JsonWriter): boolean => {
+  if (w.failed !== JSON_WRITE_OK) {
+    return false
+  }
+  if (w.depth === 0 && w.done) {
+    w.failed = JSON_WRITE_DONE
+    return false
+  }
+  if (w.depth !== 0 && jsonWriterInObject(w) && !w.afterKey) {
+    w.failed = JSON_WRITE_KEY_EXPECTED
+    return false
+  }
+  return true
+}
+
+/** After a whole value: the next element needs a comma, and at the top level the text is done. */
+const jsonWriterValueDone = (w: JsonWriter): void => {
+  w.sep = w.sep | JSON_WRITER_SEP_COMMA
+  if (w.depth === 0) {
+    w.done = true
+  }
+}
+
+/** `beginObject` and `beginArray`: the opener, and a slot for the new container. */
+const jsonWriterOpen = (w: JsonWriter, object: boolean, opener: i32): void => {
+  if (w.failed === JSON_WRITE_OK && w.depth >= JSON_WRITER_MAX_DEPTH) {
+    w.failed = JSON_WRITE_TOO_DEEP
+    return
+  }
+  if (!jsonWriterValueDue(w) || !jsonWriterPutByte(w, opener)) {
+    return
+  }
+  const low: i32 = w.objectsLow
+  w.objectsHigh = (w.objectsHigh << JSON_WRITER_BIT) | (low >>> JSON_WRITER_TOP_BIT)
+  w.objectsLow = (low << JSON_WRITER_BIT) | (object ? JSON_WRITER_BIT : 0)
+  w.depth = w.depth + 1
+  w.sep = w.sep & JSON_WRITER_SEP_INDENTED
+}
+
+/** `endObject` and `endArray`: the closer, when the innermost container is of that kind and not waiting on a value. */
+const jsonWriterClose = (w: JsonWriter, object: boolean, closer: i32): void => {
+  if (w.failed !== JSON_WRITE_OK) {
+    return
+  }
+  if (w.depth === 0 || jsonWriterInObject(w) !== object) {
+    w.failed = JSON_WRITE_UNBALANCED
+    return
+  }
+  if (w.afterKey) {
+    w.failed = JSON_WRITE_VALUE_EXPECTED
+    return
+  }
+  if (jsonWriterPutByte(w, closer)) {
+    w.depth -= 1
+    const high: i32 = w.objectsHigh
+    w.objectsLow = (w.objectsLow >>> JSON_WRITER_BIT) | ((high & JSON_WRITER_BIT) << JSON_WRITER_TOP_BIT)
+    w.objectsHigh = high >>> JSON_WRITER_BIT
+    jsonWriterValueDone(w)
+  }
+}
+
+/**
+ * `endObject` and `endArray` for an indented container that holds anything,
+ * the one state whose closer goes on a line of its own: the line break one
+ * level out, after the checks `jsonWriterClose` makes, which it then makes
+ * again before it writes the closer. A separate entry, chosen by the `sep`
+ * test `end*` makes, rather than a branch inside `jsonWriterClose`, which
+ * stays `main`'s code and small enough for LLVM to inline into every `end*`.
+ */
+const jsonWriterCloseIndented = (w: JsonWriter, object: boolean, closer: i32): void => {
+  if (
+    w.failed === JSON_WRITE_OK &&
+    w.depth !== 0 &&
+    jsonWriterInObject(w) === object &&
+    !w.afterKey &&
+    !jsonWriterIndented(w, w.depth - 1, "")
+  ) {
+    return
+  }
+  jsonWriterClose(w, object, closer)
+}
+
+/** One byte at the cursor, or `JSON_WRITE_FULL` when the buffer has no room for it. */
+const jsonWriterPutByte = (w: JsonWriter, code: i32): boolean => {
+  const buf: u8[] = w.buf
+  const at: i32 = w.end
+  if (at < 0 || at >= toI32(buf.length)) {
+    w.failed = JSON_WRITE_FULL
+    return false
+  }
+  buf[at] = toU8(code)
+  w.end = at + 1
+  return true
+}
+
+/** `JsonWriter.sep` when nothing goes before the next key or element: the first in a minified container. */
+const JSON_WRITER_SEP_NONE: i32 = 0
+/** A comma goes first: the minified text after a key's value or an element. */
+const JSON_WRITER_SEP_COMMA: i32 = 1
+/** The indent bit, set in every state of an indented text; alone, a line break goes first. */
+const JSON_WRITER_SEP_INDENTED: i32 = 2
+/**
+ * A comma and a line break go first: an indented container after it holds
+ * anything, which is also when its closer goes on a line of its own, since
+ * an empty `{}` or `[]` closes on the line it opened on.
+ */
+const JSON_WRITER_SEP_COMMA_BREAK: i32 = 3
+
+/**
+ * Everything the indented text writes that the minified one does not: at
+ * `level` — the container's own depth before an element or a key, one less
+ * before its closer — the comma when one is due (never before a closer), a
+ * line break and the indent, then, before a key, the key `name` and `": "`.
+ * It answers whether the caller goes on to write its own bytes: yes for an
+ * element or a closer, no for a key, whose bytes are all written here.
+ *
+ * It is one function, reached only from the indented `JsonWriter.sep`
+ * states, and the minified text never calls it: `key`, `jsonWriterValueDue`
+ * and `jsonWriterClose` test `sep` where they tested a "comma due" flag.
+ * Whether it is placing a closer or a key is read from `level` and the
+ * innermost container rather than passed as a constant, so LLVM cannot fold
+ * the other cases away at a call and inline what is left there, which would
+ * grow those callers past what LLVM inlines into theirs and slow every
+ * minified write.
+ *
+ * The line break and its indent go in whole or, with `JSON_WRITE_FULL`, not
+ * at all; a comma before them may already be written when they do not fit,
+ * as a comma before a minified key may, so a full buffer always leaves a
+ * prefix of the text. The indent is `indentByte` stored `indentWidth *
+ * level` times with one `fill`, so a break allocates nothing however deep it
+ * is.
+ */
+const jsonWriterIndented = (w: JsonWriter, level: i32, name: string): boolean => {
+  const closing: boolean = level !== w.depth
+  if (!closing && w.sep === JSON_WRITER_SEP_COMMA_BREAK && !jsonWriterPutByte(w, JSON_COMMA)) {
+    return false
+  }
+  const buf: u8[] = w.buf
+  const at: i32 = w.end
+  const stop: i32 = at + 1 + w.indentWidth * level
+  if (at < 0 || stop > toI32(buf.length)) {
+    w.failed = JSON_WRITE_FULL
+    return false
+  }
+  buf[at] = toU8(JSON_NEWLINE)
+  buf.fill(toU8(w.indentByte), at + 1, stop)
+  w.end = stop
+  // A key is the one step that is neither a closer nor an array's element.
+  if (closing || !jsonWriterInObject(w)) {
+    return true
+  }
+  if (jsonWriterPutString(w, name) && jsonWriterPutByte(w, JSON_COLON) && jsonWriterPutByte(w, JSON_SPACE)) {
+    w.afterKey = true
+  }
+  return false
+}
+
+/** Whether `bytes[off .. off + len)` lies inside `bytes`, for `keyBytes` and `stringBytes`; `JSON_WRITE_BAD_WINDOW` when not. */
+const jsonWriterWindowOk = (w: JsonWriter, bytes: u8[], off: i32, len: i32): boolean => {
+  if (off < 0 || len < 0 || off > toI32(bytes.length) - len) {
+    w.failed = JSON_WRITE_BAD_WINDOW
+    return false
+  }
+  return true
+}
+
+/**
+ * The comma when one is due, a line break and the indent before a key of an
+ * indented object: `jsonWriterIndented`'s first half, for `keyBytes`, whose
+ * name is bytes rather than the string that function writes. It is a
+ * function of its own rather than a parameter of that one so that the
+ * string path, which every `key` takes, is left exactly as it was. Answers
+ * whether the key may follow; all of it or, with `JSON_WRITE_FULL`, none of
+ * the break.
+ */
+const jsonWriterBreakBeforeKey = (w: JsonWriter): boolean => {
+  if (w.sep === JSON_WRITER_SEP_COMMA_BREAK && !jsonWriterPutByte(w, JSON_COMMA)) {
+    return false
+  }
+  const buf: u8[] = w.buf
+  const at: i32 = w.end
+  const stop: i32 = at + 1 + w.indentWidth * w.depth
+  if (at < 0 || stop > toI32(buf.length)) {
+    w.failed = JSON_WRITE_FULL
+    return false
+  }
+  buf[at] = toU8(JSON_NEWLINE)
+  buf.fill(toU8(w.indentByte), at + 1, stop)
+  w.end = stop
+  return true
+}
+
+/**
+ * The bytes of `text`, which needs no escaping, at the cursor; all of them or,
+ * with `JSON_WRITE_FULL`, none.
+ */
+const jsonWriterPutText = (w: JsonWriter, text: string): boolean => {
+  const buf: u8[] = w.buf
+  const n: i32 = toI32(text.length)
+  const at: i32 = w.end
+  if (at < 0 || at > toI32(buf.length) - n) {
+    w.failed = JSON_WRITE_FULL
+    return false
+  }
+  for (let k: i32 = 0; k < n && at + k < toI32(buf.length); k += 1) {
+    if (at + k >= 0) {
+      buf[at + k] = toU8(text.charCodeAt(k))
+    }
+  }
+  w.end = at + n
+  return true
+}
+
+/**
+ * `s` as a JSON string at the cursor: the quotes, the seven short escapes,
+ * `\u00xx` for the other bytes below `0x20`, and every other byte as itself.
+ * That is `jsonQuote`'s rule in `src/strings.ts`, and `JSON.stringify`'s on a
+ * string that is ASCII. A byte at or above `0x80` is copied, so UTF-8 comes
+ * out as the UTF-8 `JSON.stringify` makes once it is encoded, and a byte that
+ * is not UTF-8 at all comes out raw (the module header says why).
+ *
+ * The cursor is a local and is stored back only when the whole string fits,
+ * so a `JSON_WRITE_FULL` moves nothing.
+ */
+const jsonWriterPutString = (w: JsonWriter, s: string): boolean => {
+  const buf: u8[] = w.buf
+  const cap: i32 = toI32(buf.length)
+  const n: i32 = toI32(s.length)
+  let at: i32 = w.end
+  if (at < 0 || at >= cap) {
+    w.failed = JSON_WRITE_FULL
+    return false
+  }
+  buf[at] = toU8(JSON_QUOTE)
+  at += 1
+  for (let i: i32 = 0; i < n; i += 1) {
+    const code: i32 = toI32(s.charCodeAt(i))
+    // A plain byte is almost every byte, and costs one test of the room.
+    // Each branch moves the cursor by a constant, which is what lets the
+    // bounds proof keep `at >= 0` from one byte to the next.
+    if (jsonIsPlainByte(code)) {
+      if (at >= cap) {
+        w.failed = JSON_WRITE_FULL
+        return false
+      }
+      buf[at] = toU8(code)
+      at += 1
+      continue
+    }
+    const letter: i32 = jsonShortEscape(code)
+    if (letter !== 0) {
+      if (at < 0 || at + 1 >= cap) {
+        w.failed = JSON_WRITE_FULL
+        return false
+      }
+      buf[at] = toU8(JSON_BACKSLASH)
+      buf[at + 1] = toU8(letter)
+      at += 2
+      continue
+    }
+    if (at < 0 || at + 5 >= cap) {
+      w.failed = JSON_WRITE_FULL
+      return false
+    }
+    buf[at] = toU8(JSON_BACKSLASH)
+    buf[at + 1] = toU8(JSON_LETTER_U)
+    buf[at + 2] = toU8(JSON_DIGIT_ZERO)
+    buf[at + 3] = toU8(JSON_DIGIT_ZERO)
+    buf[at + 4] = toU8(jsonHexByte(code >> 4))
+    buf[at + 5] = toU8(jsonHexByte(code & 15))
+    at += 6
+  }
+  if (at >= cap) {
+    w.failed = JSON_WRITE_FULL
+    return false
+  }
+  buf[at] = toU8(JSON_QUOTE)
+  w.end = at + 1
+  return true
+}
+
+/**
+ * `jsonWriterPutString` over `bytes[off .. off + len)`, a window the caller
+ * has checked: the same quotes and escapes, from the same three helpers, so
+ * the two write the same bytes for the same text. The loop is its own rather
+ * than shared with the string one, so that `string` and `key` keep the code
+ * they had.
+ */
+const jsonWriterPutBytes = (w: JsonWriter, bytes: u8[], off: i32, len: i32): boolean => {
+  const buf: u8[] = w.buf
+  const cap: i32 = toI32(buf.length)
+  let at: i32 = w.end
+  if (at < 0 || at >= cap) {
+    w.failed = JSON_WRITE_FULL
+    return false
+  }
+  buf[at] = toU8(JSON_QUOTE)
+  at += 1
+  const stop: i32 = off + len
+  for (let i: i32 = off; i >= 0 && i < stop && i < toI32(bytes.length); i += 1) {
+    const code: i32 = toI32(bytes[i])
+    if (jsonIsPlainByte(code)) {
+      if (at >= cap) {
+        w.failed = JSON_WRITE_FULL
+        return false
+      }
+      buf[at] = toU8(code)
+      at += 1
+      continue
+    }
+    const letter: i32 = jsonShortEscape(code)
+    if (letter !== 0) {
+      if (at < 0 || at + 1 >= cap) {
+        w.failed = JSON_WRITE_FULL
+        return false
+      }
+      buf[at] = toU8(JSON_BACKSLASH)
+      buf[at + 1] = toU8(letter)
+      at += 2
+      continue
+    }
+    if (at < 0 || at + 5 >= cap) {
+      w.failed = JSON_WRITE_FULL
+      return false
+    }
+    buf[at] = toU8(JSON_BACKSLASH)
+    buf[at + 1] = toU8(JSON_LETTER_U)
+    buf[at + 2] = toU8(JSON_DIGIT_ZERO)
+    buf[at + 3] = toU8(JSON_DIGIT_ZERO)
+    buf[at + 4] = toU8(jsonHexByte(code >> 4))
+    buf[at + 5] = toU8(jsonHexByte(code & 15))
+    at += 6
+  }
+  if (at >= cap) {
+    w.failed = JSON_WRITE_FULL
+    return false
+  }
+  buf[at] = toU8(JSON_QUOTE)
+  w.end = at + 1
+  return true
+}
+
+/**
+ * The decimal digits of `v`, then `suffix` as one more digit when it is not
+ * negative, at the cursor; all of them or, with `JSON_WRITE_FULL`, none.
+ *
+ * The digits are counted first and then written right to left, straight into
+ * the buffer. A negative `v` is never negated, so `-2147483648` needs no case
+ * of its own: each step takes the remainder, which is zero or negative, and
+ * divides what is left exactly. The exact division is also what keeps the
+ * step the same under Node, where `/` does not truncate.
+ */
+const jsonWriterPutDigits = (w: JsonWriter, v: i32, suffix: i32): boolean => {
+  let digits: i32 = 1
+  let rest: i32 = v
+  while (rest <= -JSON_DECIMAL_BASE || rest >= JSON_DECIMAL_BASE) {
+    rest = (rest - (rest % JSON_DECIMAL_BASE)) / JSON_DECIMAL_BASE
+    digits += 1
+  }
+  const sign: i32 = v < 0 ? 1 : 0
+  const extra: i32 = suffix >= 0 ? 1 : 0
+  const buf: u8[] = w.buf
+  const at: i32 = w.end
+  const width: i32 = sign + digits + extra
+  if (at < 0 || at > toI32(buf.length) - width) {
+    w.failed = JSON_WRITE_FULL
+    return false
+  }
+  if (sign === 1) {
+    buf[at] = toU8(JSON_MINUS)
+  }
+  if (extra === 1 && at + width - 1 < toI32(buf.length) && at + width - 1 >= 0) {
+    buf[at + width - 1] = toU8(JSON_DIGIT_ZERO + suffix)
+  }
+  rest = v
+  for (let k: i32 = at + sign + digits - 1; k >= at + sign && k >= 0 && k < toI32(buf.length); k -= 1) {
+    const digit: i32 = rest % JSON_DECIMAL_BASE
+    buf[k] = toU8(JSON_DIGIT_ZERO + (digit < 0 ? -digit : digit))
+    rest = (rest - digit) / JSON_DECIMAL_BASE
+  }
+  w.end = at + width
+  return true
+}
+
+/** `jsonWriterPutDigits` in 64 bits, for `i64`, whose minimum likewise needs no case of its own. */
+const jsonWriterPutDigits64 = (w: JsonWriter, v: i64): boolean => {
+  // Built with `toI64`: under Node an `i64` is a BigInt, and a bare `10` would
+  // stay a number that `%` and `/` refuse to mix with one.
+  const ten: i64 = toI64(10)
+  let digits: i32 = 1
+  let rest: i64 = v
+  while (rest <= -ten || rest >= ten) {
+    rest = rest / ten
+    digits += 1
+  }
+  const sign: i32 = v < 0 ? 1 : 0
+  const buf: u8[] = w.buf
+  const at: i32 = w.end
+  const width: i32 = sign + digits
+  if (at < 0 || at > toI32(buf.length) - width) {
+    w.failed = JSON_WRITE_FULL
+    return false
+  }
+  if (sign === 1) {
+    buf[at] = toU8(JSON_MINUS)
+  }
+  rest = v
+  for (let k: i32 = at + width - 1; k >= at + sign && k >= 0 && k < toI32(buf.length); k -= 1) {
+    const digit: i32 = toI32(rest % ten)
+    buf[k] = toU8(JSON_DIGIT_ZERO + (digit < 0 ? -digit : digit))
+    rest = rest / ten
+  }
+  w.end = at + width
+  return true
+}
+
+/**
+ * The digits `${v}` spells for a finite `v`, at the cursor. They are a string
+ * the runtime builds, and nothing holds it once its bytes are copied, so the
+ * function's automatic arena scope (LANGUAGE.md, "Memory model", item 2)
+ * gives it back before the call returns: a loop of `f64` writes keeps
+ * `Arena.used()` flat like every other write, and `tests/link/std_json_writer`
+ * measures it. The scope is the compiler's rather than a `using a = arena()`
+ * block because this module also runs under Node, which `tests/run.js` holds
+ * to `JSON.stringify`, and Node 22 does not parse `using`.
+ */
+const jsonWriterPutF64 = (w: JsonWriter, v: f64): boolean => jsonWriterPutText(w, `${v}`)
+
+/**
+ * `s` as `JSON.stringify(s)` writes it — quoted, with the escapes
+ * `JsonWriter.string` writes — as a string. A thin layer on the writer: it
+ * sizes a buffer to fit exactly, writes into it and reads it back. A string
+ * with nothing to escape skips the writer and is only quoted.
+ */
+export const jsonStringifyString = (s: string): string => {
+  const n: i32 = toI32(s.length)
+  let width: i32 = 2
+  for (let i: i32 = 0; i < n; i += 1) {
+    width += jsonEscapedWidth(toI32(s.charCodeAt(i)))
+  }
+  if (width === n + 2) {
+    return `"${s}"`
+  }
+  const w: JsonWriter = new JsonWriter(new Array<u8>(width), 0)
+  w.string(s)
+  return w.text()
 }