@aiwg/cli 2026.10.9 → 2026.10.10

package/tools/ralph-external/lib/provider-adapter.mjs

@@ -1,220 +1,14 @@
-/**
- * Provider Adapter Base Class for External Ralph Loop
- *
- * Defines the interface that all CLI provider adapters must implement.
- * Each adapter wraps a specific agentic coding CLI (claude, codex, etc.)
- * and handles binary resolution, argument construction, model mapping,
- * and output parsing.
- *
- * @implements Plan: Multi-Provider Support for External Ralph Loop
- */
-
 import { spawn } from 'child_process';
 import { importImpl } from '../../_resolve-impl.mjs';
 import { createWorkerHealthObserver, observeProviderHealthEvent } from './worker-health.mjs';
 
-/**
- * Thrown by {@link parseStrictWorkerJson} with a stable `code` so callers can
- * map a scan failure to a specific contract-violation message without
- * string-matching free-text.
- */
-class StrictJsonScanError extends Error {
-  constructor(code, message) {
-    super(message);
-    this.code = code;
-  }
-}
-
-/**
- * RFC 8259 JSON parser used on every strict worker-final path (JSONL lines,
- * `format: 'json'`, and the MCP `content[0].text`/top-level envelope) instead
- * of `JSON.parse`. `JSON.parse` silently keeps the LAST value when an object
- * repeats a member name — RFC 8259 §4 explicitly leaves this to the
- * implementation, and V8 picks "last wins". That lets a forged worker final
- * smuggle a second, hidden value past a first one: a trailing duplicate
- * `"status":"completed"` can overwrite an earlier `"status":"failed"`, or a
- * trailing duplicate `"type":"result"` can collapse a `"type":"message"`
- * framing envelope into a bogus result in one line (#2890 BLOCKER 1+2).
- *
- * This scanner tracks member names per object independently at every
- * nesting level (a sibling object may reuse a name the scanner already saw
- * in its parent or an earlier sibling) and rejects any object that repeats
- * one. Names are compared only after the scanner has fully decoded them —
- * resolving `\"`, other single-character escapes, and `\uXXXX` escapes
- * (including surrogate pairs, since JS string concatenation of two decoded
- * UTF-16 code units forms the pair automatically) — so an escape-obfuscated
- * collision (`"status"` vs `"status"`) is caught exactly like a literal
- * one. A non-colliding unknown key, escaped or not, is left for the existing
- * `additionalProperties: false` schema check to reject, unchanged.
- *
- * Nesting depth is bounded during the scan (not only afterward, by
- * `boundedJson()`'s post-parse walk) so pathological depth fails fast with a
- * clear `DEPTH` code instead of relying on a recursive-descent stack
- * overflow to be caught as a generic syntax error.
- *
- * @param {string} text - Decoded JSON text (already UTF-8 validated by the caller)
- * @param {number} maxDepth - Same bound as `WORKER_MAX_NESTING_DEPTH`; root value is depth 1
- * @returns {unknown}
- */
-function parseStrictWorkerJson(text, maxDepth) {
-  const length = text.length;
-  let index = 0;
-
-  function fail(code, message) {
-    throw new StrictJsonScanError(code, `${message} (offset ${index})`);
-  }
-
-  function skipWhitespace() {
-    while (index < length) {
-      const code = text.charCodeAt(index);
-      if (code === 0x20 || code === 0x09 || code === 0x0a || code === 0x0d) index += 1;
-      else break;
-    }
-  }
-
-  function parseValue(depth) {
-    skipWhitespace();
-    if (index >= length) fail('SYNTAX', 'Unexpected end of JSON input');
-    const code = text.charCodeAt(index);
-    if (code === 0x7b) return parseObject(depth);
-    if (code === 0x5b) return parseArray(depth);
-    if (code === 0x22) return parseString();
-    if (code === 0x2d || (code >= 0x30 && code <= 0x39)) return parseNumber();
-    if (text.startsWith('true', index)) { index += 4; return true; }
-    if (text.startsWith('false', index)) { index += 5; return false; }
-    if (text.startsWith('null', index)) { index += 4; return null; }
-    fail('SYNTAX', 'Unexpected token');
-  }
-
-  function parseObject(depth) {
-    if (depth > maxDepth) fail('DEPTH', 'Worker nesting depth exceeds bound');
-    index += 1; // {
-    const result = {};
-    const seen = new Set();
-    skipWhitespace();
-    if (text.charCodeAt(index) === 0x7d) { index += 1; return result; }
-    for (;;) {
-      skipWhitespace();
-      if (text.charCodeAt(index) !== 0x22) fail('SYNTAX', 'Expected object member name');
-      const key = parseString();
-      if (seen.has(key)) fail('DUPLICATE', `Duplicate object member name ${JSON.stringify(key)}`);
-      seen.add(key);
-      skipWhitespace();
-      if (text.charCodeAt(index) !== 0x3a) fail('SYNTAX', 'Expected colon after object member name');
-      index += 1;
-      // Define, never assign: assignment would invoke the inherited __proto__
-      // setter, hiding the member from own-key validation and diverging from
-      // JSON.parse, which creates an ordinary own property.
-      Object.defineProperty(result, key, { value: parseValue(depth + 1), enumerable: true, writable: true, configurable: true });
-      skipWhitespace();
-      const delimiter = text.charCodeAt(index);
-      if (delimiter === 0x2c) { index += 1; continue; }
-      if (delimiter === 0x7d) { index += 1; break; }
-      fail('SYNTAX', 'Expected , or } in object');
-    }
-    return result;
-  }
-
-  function parseArray(depth) {
-    if (depth > maxDepth) fail('DEPTH', 'Worker nesting depth exceeds bound');
-    index += 1; // [
-    const result = [];
-    skipWhitespace();
-    if (text.charCodeAt(index) === 0x5d) { index += 1; return result; }
-    for (;;) {
-      result.push(parseValue(depth + 1));
-      skipWhitespace();
-      const delimiter = text.charCodeAt(index);
-      if (delimiter === 0x2c) { index += 1; continue; }
-      if (delimiter === 0x5d) { index += 1; break; }
-      fail('SYNTAX', 'Expected , or ] in array');
-    }
-    return result;
-  }
-
-  function parseString() {
-    index += 1; // opening quote
-    let value = '';
-    for (;;) {
-      if (index >= length) fail('SYNTAX', 'Unterminated string');
-      const code = text.charCodeAt(index);
-      if (code === 0x22) { index += 1; return value; }
-      if (code === 0x5c) {
-        index += 1;
-        const escape = text[index];
-        if (escape === undefined) fail('SYNTAX', 'Unterminated escape sequence');
-        switch (escape) {
-          case '"': value += '"'; index += 1; break;
-          case '\\': value += '\\'; index += 1; break;
-          case '/': value += '/'; index += 1; break;
-          case 'b': value += '\b'; index += 1; break;
-          case 'f': value += '\f'; index += 1; break;
-          case 'n': value += '\n'; index += 1; break;
-          case 'r': value += '\r'; index += 1; break;
-          case 't': value += '\t'; index += 1; break;
-          case 'u': {
-            const hex = text.slice(index + 1, index + 5);
-            if (!/^[0-9a-fA-F]{4}$/.test(hex)) fail('SYNTAX', 'Invalid unicode escape');
-            // Decoded code unit is appended as-is; two consecutive decoded
-            // surrogate halves recombine into one character automatically
-            // through normal JS UTF-16 string concatenation.
-            value += String.fromCharCode(parseInt(hex, 16));
-            index += 5;
-            break;
-          }
-          default: fail('SYNTAX', 'Invalid escape sequence');
-        }
-      } else if (code < 0x20) {
-        fail('SYNTAX', 'Unescaped control character in string');
-      } else {
-        value += text[index];
-        index += 1;
-      }
-    }
-  }
-
-  function parseNumber() {
-    const start = index;
-    if (text.charCodeAt(index) === 0x2d) index += 1;
-    if (text.charCodeAt(index) === 0x30) {
-      index += 1;
-    } else if (text.charCodeAt(index) >= 0x31 && text.charCodeAt(index) <= 0x39) {
-      index += 1;
-      while (text.charCodeAt(index) >= 0x30 && text.charCodeAt(index) <= 0x39) index += 1;
-    } else fail('SYNTAX', 'Invalid number');
-    if (text.charCodeAt(index) === 0x2e) {
-      index += 1;
-      if (!(text.charCodeAt(index) >= 0x30 && text.charCodeAt(index) <= 0x39)) fail('SYNTAX', 'Invalid number fraction');
-      while (text.charCodeAt(index) >= 0x30 && text.charCodeAt(index) <= 0x39) index += 1;
-    }
-    if (text.charCodeAt(index) === 0x65 || text.charCodeAt(index) === 0x45) {
-      index += 1;
-      if (text.charCodeAt(index) === 0x2b || text.charCodeAt(index) === 0x2d) index += 1;
-      if (!(text.charCodeAt(index) >= 0x30 && text.charCodeAt(index) <= 0x39)) fail('SYNTAX', 'Invalid number exponent');
-      while (text.charCodeAt(index) >= 0x30 && text.charCodeAt(index) <= 0x39) index += 1;
-    }
-    return Number(text.slice(start, index));
-  }
-
-  const result = parseValue(1);
-  skipWhitespace();
-  if (index !== length) fail('SYNTAX', 'Unexpected trailing characters after JSON value');
-  return result;
-}
+import { parseStrictWorkerJson, StrictJsonScanError } from './strict-worker-json.mjs';
+import { classifySessionAttempt } from './session-attempt.mjs';
 
 const installedOwner = await importImpl(import.meta.url, 'models/worker-installation.mjs');
 export const { workerNegativeFixtureSuite, workerNegativeFixtureDigest, registerProvider, createProvider, listProviders, hasProvider } = installedOwner;
 
-/**
- * Whether the optional muse exec Ralph adapter is registered.
- * Enabled by default; set `AIWG_MUSE_RALPH_ENABLED` to `0`, `false`, `no`,
- * or `off` to disable the adapter without affecting
- * `aiwg use --provider muse` (the deploy/writer path lives in `src/` and
- * never consults this registry). See
- * `tools/ralph-external/lib/muse-adapter.mjs` (#230).
- *
- * @returns {boolean}
- */
+/** The optional Muse adapter is independent of provider deployment. */
 export function isMuseRalphEnabled() {
   const raw = String(process.env.AIWG_MUSE_RALPH_ENABLED ?? '').trim().toLowerCase();
   return !['0', 'false', 'no', 'off'].includes(raw);
@@ -661,24 +455,15 @@ export class ProviderAdapter {
     return null;
   }
 
-  /**
-   * Check if a capability is supported, and optionally log a warning.
-   *
-   * @param {string} capability - Capability name from ProviderCapabilities
-   * @param {string} [context] - Context for the warning message
-   * @returns {boolean}
-   */
+  classifySessionAttempt(request) {
+    return classifySessionAttempt(this, request);
+  }
+
   hasCapability(capability) {
     const caps = this.getCapabilities();
     return !!caps[capability];
   }
 
-  /**
-   * Log a capability warning when a feature is not supported.
-   *
-   * @param {string} capability - Capability name
-   * @param {string} feature - Human-readable feature description
-   */
   warnUnsupported(capability, feature) {
     if (!this.hasCapability(capability)) {
       console.warn(
@@ -687,52 +472,18 @@ export class ProviderAdapter {
     }
   }
 }
-
-// ============================================================================
-// Provider Registry & Factory
-// ============================================================================
-
 export async function loadInstalledWorkerAdapters(request) {
   await ensureProvidersRegistered();
   return installedOwner.loadInstalledWorkerAdapters(request);
 }
 
-// ============================================================================
-// Auto-register built-in providers on import
-// ============================================================================
-
-// Lazy imports to avoid circular dependencies - adapters register themselves
-// when their modules are loaded. We trigger that here.
+// Adapters register themselves; keep imports lazy to avoid registry cycles.
 async function registerBuiltinProviders() {
-  try {
-    await import('./claude-adapter.mjs');
-  } catch { /* ignore if not found */ }
-  try {
-    await import('./codex-adapter.mjs');
-  } catch { /* ignore if not found */ }
-  try {
-    await import('./opencode-adapter.mjs');
-  } catch { /* ignore if not found */ }
-  try {
-    await import('./factory-adapter.mjs');
-  } catch { /* ignore if not found */ }
-  try {
-    await import('./pi-adapter.mjs');
-    await import('./omp-adapter.mjs');
-  } catch { /* ignore if not found */ }
-  try {
-    await import('./deepseek-harness-adapter.mjs');
-  } catch { /* ignore if not found */ }
-  // #230: optional / post-experimental. Disabled via AIWG_MUSE_RALPH_ENABLED=0
-  // without affecting `aiwg use --provider muse`.
-  if (isMuseRalphEnabled()) {
-    try {
-      await import('./muse-adapter.mjs');
-    } catch { /* ignore if not found */ }
+  for (const name of ['claude', 'codex', 'opencode', 'factory', 'pi', 'omp', 'deepseek-harness',
+    ...(isMuseRalphEnabled() ? ['muse'] : [])]) {
+    try { await import(`./${name}-adapter.mjs`); } catch { /* Optional adapter unavailable. */ }
   }
 }
-
-// Run registration — store promise so callers can await it
 const _registrationPromise = registerBuiltinProviders();
 
 /**

package/tools/ralph-external/lib/session-attempt.mjs

@@ -0,0 +1,85 @@
+// Classify native continuation and retain the original execution assumptions.
+import { randomUUID } from 'node:crypto';
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { importImpl } from '../../_resolve-impl.mjs';
+
+const { qualificationDigest } = await importImpl(import.meta.url, 'models/qualification-digest.mjs');
+const validSession = value => typeof value === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9._:/-]{0,255}$/.test(value);
+
+export function changedBindings(original, current) {
+  if (!original) return [];
+  return [...new Set([...Object.keys(original), ...Object.keys(current)])].sort()
+    .filter(key => qualificationDigest(original[key] ?? null) !== qualificationDigest(current[key] ?? null))
+    .map(key => ({ binding: key, previous: original[key] ?? null, current: current[key] ?? null }));
+}
+
+export function classifySessionAttempt(adapter, { sessionId, original, current, sessionValid = true } = {}) {
+  const changes = changedBindings(original, current ?? {});
+  const requested = sessionId !== null && sessionId !== undefined;
+  const reason = !requested ? 'no-session' : !adapter.hasCapability('sessionResume') ? 'resume-unsupported'
+    : !validSession(sessionId) || !sessionValid || !original ? 'invalid-session'
+      : changes.length ? 'bindings-changed' : 'session-bound';
+  return { kind: reason === 'session-bound' ? 'continuation' : 'fresh', reason,
+    requestedSessionId: validSession(sessionId) ? sessionId : null,
+    changes, originalBindings: original ?? null, bindings: current ?? {} };
+}
+
+export function persistCycleAttempt(owner, state, outputDir, attempt) {
+  state.currentAttempt = attempt;
+  owner.stateManager.save(state);
+  writeFileSync(join(outputDir, 'session-attempt.json'), JSON.stringify(attempt, null, 2), { mode: 0o600 });
+}
+
+export function prepareNativeAttempt(owner, state, options) {
+  const adapter = owner.providerAdapter;
+  // Resolve again even when a requested continuation cannot be used.
+  const model = adapter.mapModel(options.model);
+  const prior = state.sessionBinding;
+  const sessionId = prior?.sessionId ?? (state.currentIteration > 1 ? state.sessionId : null);
+  const bindings = { provider: adapter.getName(), model, sessionId,
+    policyDigest: qualificationDigest({ budget: options.budget, maxTurns: options.maxTurns,
+      mcpConfig: options.mcpConfig, tools: options.tools, thinking: options.thinking,
+      workingDir: options.workingDir }) };
+  const attempt = { attemptId: randomUUID(), previousAttemptId: state.currentAttempt?.attemptId ?? null,
+    ...adapter.classifySessionAttempt({ sessionId, original: prior?.originalBindings,
+      current: bindings, sessionValid: prior?.valid === true }), status: 'prepared' };
+  // Only Claude/Muse accept a caller-created session id. Other CLIs must
+  // report a native id before it can be used for continuation.
+  const nativeId = attempt.kind === 'continuation' ? sessionId
+    : ['claude', 'muse'].includes(adapter.getName()) ? randomUUID() : null;
+  attempt.bindings.sessionId = nativeId;
+  persistCycleAttempt(owner, state, options.outputDir, attempt);
+  return { ...options, model, sessionId: nativeId, resumeSession: attempt.kind === 'continuation' ? nativeId : null,
+    attempt };
+}
+
+export function finishNativeAttempt(owner, state, options, result) {
+  let sessionId = options.sessionId;
+  let reportedId = null;
+  let conflictingSession = false;
+  let providerFailed = false;
+  // Session ids are accepted only from this attempt's captured provider output.
+  for (const line of String(result.stdoutBuffer ?? '').split('\n')) {
+    try {
+      const event = JSON.parse(line);
+      const observed = owner.providerAdapter.observeHealthEvent(event, { kind: 'stdout' }, {});
+      providerFailed ||= observed?.kind === 'error' || observed?.kind === 'terminal' && observed.success === false;
+      const candidate = observed?.sessionId ?? event.session_id ?? event.sessionId ?? event.stream?.id;
+      if (validSession(candidate)) {
+        conflictingSession ||= reportedId !== null && reportedId !== candidate
+          || options.resumeSession != null && options.resumeSession !== candidate;
+        reportedId = candidate;
+        sessionId = candidate;
+      }
+    } catch { /* Non-JSON stdout has no native session binding. */ }
+  }
+  const bindings = { ...options.attempt.bindings, sessionId };
+  const valid = result.exitCode === 0 && !result.timedOut && !providerFailed && !conflictingSession && validSession(sessionId);
+  state.sessionBinding = { sessionId, valid,
+    originalBindings: options.attempt.kind === 'continuation' ? options.attempt.originalBindings : bindings };
+  options.attempt.status = 'finished';
+  options.attempt.bindings = bindings;
+  persistCycleAttempt(owner, state, options.outputDir, options.attempt);
+  result.attempt = options.attempt;
+}

package/tools/ralph-external/lib/strict-worker-json.mjs

@@ -0,0 +1,190 @@
+// Parse bounded worker JSON without accepting duplicate object keys.
+/**
+ * Thrown by {@link parseStrictWorkerJson} with a stable `code` so callers can
+ * map a scan failure to a specific contract-violation message without
+ * string-matching free-text.
+ */
+export class StrictJsonScanError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+
+/**
+ * RFC 8259 JSON parser used on every strict worker-final path (JSONL lines,
+ * `format: 'json'`, and the MCP `content[0].text`/top-level envelope) instead
+ * of `JSON.parse`. `JSON.parse` silently keeps the LAST value when an object
+ * repeats a member name — RFC 8259 §4 explicitly leaves this to the
+ * implementation, and V8 picks "last wins". That lets a forged worker final
+ * smuggle a second, hidden value past a first one: a trailing duplicate
+ * `"status":"completed"` can overwrite an earlier `"status":"failed"`, or a
+ * trailing duplicate `"type":"result"` can collapse a `"type":"message"`
+ * framing envelope into a bogus result in one line (#2890 BLOCKER 1+2).
+ *
+ * This scanner tracks member names per object independently at every
+ * nesting level (a sibling object may reuse a name the scanner already saw
+ * in its parent or an earlier sibling) and rejects any object that repeats
+ * one. Names are compared only after the scanner has fully decoded them —
+ * resolving `\"`, other single-character escapes, and `\uXXXX` escapes
+ * (including surrogate pairs, since JS string concatenation of two decoded
+ * UTF-16 code units forms the pair automatically) — so an escape-obfuscated
+ * collision (`"status"` vs `"status"`) is caught exactly like a literal
+ * one. A non-colliding unknown key, escaped or not, is left for the existing
+ * `additionalProperties: false` schema check to reject, unchanged.
+ *
+ * Nesting depth is bounded during the scan (not only afterward, by
+ * `boundedJson()`'s post-parse walk) so pathological depth fails fast with a
+ * clear `DEPTH` code instead of relying on a recursive-descent stack
+ * overflow to be caught as a generic syntax error.
+ *
+ * @param {string} text - Decoded JSON text (already UTF-8 validated by the caller)
+ * @param {number} maxDepth - Same bound as `WORKER_MAX_NESTING_DEPTH`; root value is depth 1
+ * @returns {unknown}
+ */
+export function parseStrictWorkerJson(text, maxDepth) {
+  const length = text.length;
+  let index = 0;
+
+  function fail(code, message) {
+    throw new StrictJsonScanError(code, `${message} (offset ${index})`);
+  }
+
+  function skipWhitespace() {
+    while (index < length) {
+      const code = text.charCodeAt(index);
+      if (code === 0x20 || code === 0x09 || code === 0x0a || code === 0x0d) index += 1;
+      else break;
+    }
+  }
+
+  function parseValue(depth) {
+    skipWhitespace();
+    if (index >= length) fail('SYNTAX', 'Unexpected end of JSON input');
+    const code = text.charCodeAt(index);
+    if (code === 0x7b) return parseObject(depth);
+    if (code === 0x5b) return parseArray(depth);
+    if (code === 0x22) return parseString();
+    if (code === 0x2d || (code >= 0x30 && code <= 0x39)) return parseNumber();
+    if (text.startsWith('true', index)) { index += 4; return true; }
+    if (text.startsWith('false', index)) { index += 5; return false; }
+    if (text.startsWith('null', index)) { index += 4; return null; }
+    fail('SYNTAX', 'Unexpected token');
+  }
+
+  function parseObject(depth) {
+    if (depth > maxDepth) fail('DEPTH', 'Worker nesting depth exceeds bound');
+    index += 1; // {
+    const result = {};
+    const seen = new Set();
+    skipWhitespace();
+    if (text.charCodeAt(index) === 0x7d) { index += 1; return result; }
+    for (;;) {
+      skipWhitespace();
+      if (text.charCodeAt(index) !== 0x22) fail('SYNTAX', 'Expected object member name');
+      const key = parseString();
+      if (seen.has(key)) fail('DUPLICATE', `Duplicate object member name ${JSON.stringify(key)}`);
+      seen.add(key);
+      skipWhitespace();
+      if (text.charCodeAt(index) !== 0x3a) fail('SYNTAX', 'Expected colon after object member name');
+      index += 1;
+      // Define, never assign: assignment would invoke the inherited __proto__
+      // setter, hiding the member from own-key validation and diverging from
+      // JSON.parse, which creates an ordinary own property.
+      Object.defineProperty(result, key, { value: parseValue(depth + 1), enumerable: true, writable: true, configurable: true });
+      skipWhitespace();
+      const delimiter = text.charCodeAt(index);
+      if (delimiter === 0x2c) { index += 1; continue; }
+      if (delimiter === 0x7d) { index += 1; break; }
+      fail('SYNTAX', 'Expected , or } in object');
+    }
+    return result;
+  }
+
+  function parseArray(depth) {
+    if (depth > maxDepth) fail('DEPTH', 'Worker nesting depth exceeds bound');
+    index += 1; // [
+    const result = [];
+    skipWhitespace();
+    if (text.charCodeAt(index) === 0x5d) { index += 1; return result; }
+    for (;;) {
+      result.push(parseValue(depth + 1));
+      skipWhitespace();
+      const delimiter = text.charCodeAt(index);
+      if (delimiter === 0x2c) { index += 1; continue; }
+      if (delimiter === 0x5d) { index += 1; break; }
+      fail('SYNTAX', 'Expected , or ] in array');
+    }
+    return result;
+  }
+
+  function parseString() {
+    index += 1; // opening quote
+    let value = '';
+    for (;;) {
+      if (index >= length) fail('SYNTAX', 'Unterminated string');
+      const code = text.charCodeAt(index);
+      if (code === 0x22) { index += 1; return value; }
+      if (code === 0x5c) {
+        index += 1;
+        const escape = text[index];
+        if (escape === undefined) fail('SYNTAX', 'Unterminated escape sequence');
+        switch (escape) {
+          case '"': value += '"'; index += 1; break;
+          case '\\': value += '\\'; index += 1; break;
+          case '/': value += '/'; index += 1; break;
+          case 'b': value += '\b'; index += 1; break;
+          case 'f': value += '\f'; index += 1; break;
+          case 'n': value += '\n'; index += 1; break;
+          case 'r': value += '\r'; index += 1; break;
+          case 't': value += '\t'; index += 1; break;
+          case 'u': {
+            const hex = text.slice(index + 1, index + 5);
+            if (!/^[0-9a-fA-F]{4}$/.test(hex)) fail('SYNTAX', 'Invalid unicode escape');
+            // Decoded code unit is appended as-is; two consecutive decoded
+            // surrogate halves recombine into one character automatically
+            // through normal JS UTF-16 string concatenation.
+            value += String.fromCharCode(parseInt(hex, 16));
+            index += 5;
+            break;
+          }
+          default: fail('SYNTAX', 'Invalid escape sequence');
+        }
+      } else if (code < 0x20) {
+        fail('SYNTAX', 'Unescaped control character in string');
+      } else {
+        value += text[index];
+        index += 1;
+      }
+    }
+  }
+
+  function parseNumber() {
+    const start = index;
+    if (text.charCodeAt(index) === 0x2d) index += 1;
+    if (text.charCodeAt(index) === 0x30) {
+      index += 1;
+    } else if (text.charCodeAt(index) >= 0x31 && text.charCodeAt(index) <= 0x39) {
+      index += 1;
+      while (text.charCodeAt(index) >= 0x30 && text.charCodeAt(index) <= 0x39) index += 1;
+    } else fail('SYNTAX', 'Invalid number');
+    if (text.charCodeAt(index) === 0x2e) {
+      index += 1;
+      if (!(text.charCodeAt(index) >= 0x30 && text.charCodeAt(index) <= 0x39)) fail('SYNTAX', 'Invalid number fraction');
+      while (text.charCodeAt(index) >= 0x30 && text.charCodeAt(index) <= 0x39) index += 1;
+    }
+    if (text.charCodeAt(index) === 0x65 || text.charCodeAt(index) === 0x45) {
+      index += 1;
+      if (text.charCodeAt(index) === 0x2b || text.charCodeAt(index) === 0x2d) index += 1;
+      if (!(text.charCodeAt(index) >= 0x30 && text.charCodeAt(index) <= 0x39)) fail('SYNTAX', 'Invalid number exponent');
+      while (text.charCodeAt(index) >= 0x30 && text.charCodeAt(index) <= 0x39) index += 1;
+    }
+    return Number(text.slice(start, index));
+  }
+
+  const result = parseValue(1);
+  skipWhitespace();
+  if (index !== length) fail('SYNTAX', 'Unexpected trailing characters after JSON value');
+  return result;
+}
+