hivecode-mcp 0.7.0 → 0.11.0

package/lang-json.js

@@ -0,0 +1,184 @@
+// JSON language provider for ICR — the one provider where the guarantee is PERFECT,
+// because JSON.parse IS the real parser (no heuristics anywhere).
+//
+// JSON is the most-merged file type in a repository (package.json, tsconfig, lockfile
+// fragments, CI configs), and the classic line-merge failure is two sides editing
+// nearby keys — git conflicts or, worse, fuses into invalid JSON. ICR merges JSON as
+// DATA: value-wise 3-way merge, keyed by object path, so:
+//   • different keys edited on each side        -> clean merge, both kept
+//   • the SAME path changed differently         -> semantic conflict naming the path
+//     (surfaced as a machine-resolvable unit, so an agent judge can reconcile it)
+//   • one side deletes a key the other changed  -> conflict (delete vs change)
+//   • arrays: one-sided changes merge; both-sided changes merge when the edited
+//     regions are DISJOINT (prefix/suffix diff — appends, prepends, middle inserts);
+//     overlapping array edits are an honest conflict
+// Output is serialized with the file's own indentation style (detected from the base)
+// and preserves the trailing-newline convention, so diffs stay minimal.
+
+const isObj = (v) => v !== null && typeof v === 'object' && !Array.isArray(v)
+const eq = (x, y) => JSON.stringify(x) === JSON.stringify(y)
+
+// PRECISION SAFETY GATE. The data merge re-serializes the whole document, which means
+// every number goes through JS float64 — and that CORRUPTS values nobody touched:
+// 9007199254740993 (beyond 2^53) silently loses a digit; 1e999 becomes Infinity and
+// then `null`. Shipping a "clean" merge that corrupts untouched data is the cardinal
+// sin, so: scan every number literal (string-aware); if ANY cannot survive the
+// round-trip value-identically, refuse the data merge entirely — the engine falls back
+// to the safe line tier, which never rewrites untouched bytes. (Found by the
+// adversarial crucible, not by users — the way it should be.)
+function numbersSafe(src) {
+  const n = src.length
+  let i = 0
+  while (i < n) {
+    const c = src[i]
+    if (c === '"') { i++; while (i < n) { if (src[i] === '\\') { i += 2; continue } if (src[i] === '"') { i++; break } i++ } continue }
+    if (c === '-' || (c >= '0' && c <= '9')) {
+      let j = i + 1
+      while (j < n && /[0-9eE+.-]/.test(src[j])) j++
+      const tok = src.slice(i, j)
+      const v = Number(tok)
+      if (!Number.isFinite(v)) return false                                  // 1e999 → Infinity → null
+      if (Number.isInteger(v) && Math.abs(v) > Number.MAX_SAFE_INTEGER) return false // beyond 2^53
+      const digits = tok.replace(/[^0-9]/g, '').replace(/^0+/, '')
+      if (digits.length > 15 && !eq(Number(tok), Number(v.toPrecision(15)))) return false // >15 sig digits at risk
+      i = j; continue
+    }
+    i++
+  }
+  return true
+}
+
+// Detect the base file's indent unit ('  ', '    ', '\t', …). Defaults to two spaces.
+function detectIndent(src) {
+  const m = /\n([ \t]+)\S/.exec(src)
+  return m ? m[1] : '  '
+}
+
+// 3-way merge of two ARRAYS against base, by disjoint-region splice (the same
+// prefix/suffix discipline the engine's token merge uses, on JSON-equal elements).
+// Returns the merged array, or null for an overlapping (real) conflict.
+function mergeArray(base, a, b) {
+  const K = (arr) => arr.map((x) => JSON.stringify(x))
+  const diffRange = (B, O) => {
+    if (B.length === O.length && B.every((x, i) => x === O[i])) return null
+    let p = 0
+    const maxp = Math.min(B.length, O.length)
+    while (p < maxp && B[p] === O[p]) p++
+    let s = 0
+    while (s < B.length - p && s < O.length - p && B[B.length - 1 - s] === O[O.length - 1 - s]) s++
+    return { bStart: p, bEnd: B.length - s, oStart: p, oEnd: O.length - s }
+  }
+  const KB = K(base), ra = diffRange(KB, K(a)), rb = diffRange(KB, K(b))
+  if (!ra) return b
+  if (!rb) return a
+  if (ra.bStart < rb.bEnd && rb.bStart < ra.bEnd) return null // overlapping regions
+  if (ra.bStart === rb.bStart) return null                    // ambiguous same-point edits
+  const edits = [
+    { s: ra.bStart, e: ra.bEnd, ins: a.slice(ra.oStart, ra.oEnd) },
+    { s: rb.bStart, e: rb.bEnd, ins: b.slice(rb.oStart, rb.oEnd) },
+  ].sort((x, y) => y.s - x.s)
+  let out = base.slice()
+  for (const ed of edits) out.splice(ed.s, ed.e - ed.s, ...ed.ins)
+  return out
+}
+
+// Value-wise 3-way merge. Fills `conflicts` (path strings) and `resolvable`
+// ({key, base, ours, theirs} with pretty-printed values) on same-path clashes;
+// the merged value keeps BASE at conflicted paths (the engine refuses the whole
+// merge when conflicts exist, so nothing partial ever ships).
+function mergeVal(base, a, b, path, conflicts, resolvable) {
+  if (eq(a, b)) return a
+  if (eq(a, base)) return b
+  if (eq(b, base)) return a
+  if (isObj(base) && isObj(a) && isObj(b)) {
+    const out = {}
+    const keys = [...new Set([...Object.keys(base), ...Object.keys(a), ...Object.keys(b)])]
+    for (const k of keys) {
+      const p = path ? path + '.' + k : k
+      const inB = k in base, inA = k in a, inBb = k in b
+      if (inB && !inA && !inBb) continue                                     // deleted on both sides
+      if (inB && !inA) {                                                     // ours deleted it
+        if (eq(b[k], base[k])) continue                                      // theirs untouched -> deletion wins
+        conflicts.push(p); resolvable.push(resUnit(p, base[k], undefined, b[k])); continue
+      }
+      if (inB && !inBb) {                                                    // theirs deleted it
+        if (eq(a[k], base[k])) continue
+        conflicts.push(p); resolvable.push(resUnit(p, base[k], a[k], undefined)); continue
+      }
+      if (!inB && inA && inBb) {                                             // both added
+        if (eq(a[k], b[k])) { out[k] = a[k]; continue }
+        if (isObj(a[k]) && isObj(b[k])) { out[k] = mergeVal({}, a[k], b[k], p, conflicts, resolvable); continue }
+        conflicts.push(p); resolvable.push(resUnit(p, undefined, a[k], b[k])); continue
+      }
+      if (!inB) { out[k] = inA ? a[k] : b[k]; continue }                     // one side added
+      out[k] = mergeVal(base[k], a[k], b[k], p, conflicts, resolvable)       // present everywhere
+    }
+    return out
+  }
+  if (Array.isArray(base) && Array.isArray(a) && Array.isArray(b)) {
+    const m = mergeArray(base, a, b)
+    if (m) return m
+    conflicts.push(path || '(root)'); resolvable.push(resUnit(path || '(root)', base, a, b))
+    return base
+  }
+  conflicts.push(path || '(root)')                                            // scalar/shape clash
+  resolvable.push(resUnit(path || '(root)', base, a, b))
+  return base
+}
+
+const show = (v) => (v === undefined ? '(deleted)' : JSON.stringify(v, null, 2))
+const resUnit = (p, base, ours, theirs) => ({ key: 'json:' + p, base: show(base), ours: show(ours), theirs: show(theirs) })
+
+export const json = {
+  id: 'json',
+  exts: ['.json'],
+  parses: (src) => { try { JSON.parse(String(src == null ? '' : src)); return true } catch { return false } },
+  // The engine's whole-document tier: merge the file as parsed data.
+  mergeWhole: (base, a, b) => {
+    if (!numbersSafe(base) || !numbersSafe(a) || !numbersSafe(b)) return null // precision hazard → safe fallback, never corrupt
+    let B, A, Bb
+    try { B = JSON.parse(base); A = JSON.parse(a); Bb = JSON.parse(b) } catch { return null }
+    const conflicts = [], resolvable = []
+    const merged = mergeVal(B, A, Bb, '', conflicts, resolvable)
+    if (conflicts.length) return { conflicts, resolvable }
+    const nl = /\n$/.test(base) || /\n$/.test(a) ? '\n' : ''
+    return { text: JSON.stringify(merged, null, detectIndent(base)) + nl }
+  },
+  // Minimal unit view (whole document) so generic engine paths stay well-defined;
+  // real merging happens in mergeWhole above.
+  units: (src) => [{ key: 'doc', text: String(src), start: 0, end: String(src).length }],
+  declaredNames: () => new Set(),
+  // INTENT RESOLUTION for data: a conflicted unit's "text" is a rendering of a parsed
+  // VALUE, so a judge's reconciliation is applied by setting the value at the unit's
+  // path (key 'json:<path>'), not by string replacement. The reconciled string must
+  // itself be valid JSON ('(deleted)' removes the key). Returns the re-serialized
+  // document, or null when it can't apply — resolveMerge then falls back to the safe
+  // conflict, so a malformed judgment never ships.
+  applyResolution: (text, unit, reconciled) => {
+    if (!unit || typeof unit.key !== 'string' || !unit.key.startsWith('json:')) return null
+    if (!numbersSafe(text)) return null // same precision gate: never re-serialize a doc we'd corrupt
+    let doc, value
+    try { doc = JSON.parse(text) } catch { return null }
+    const del = String(reconciled).trim() === '(deleted)'
+    if (!del) { try { value = JSON.parse(reconciled) } catch { return null } }
+    const path = unit.key.slice(5)
+    if (path === '(root)' || path === '') {
+      if (del) return null
+      doc = value
+    } else {
+      const parts = path.split('.')
+      let cur = doc
+      for (let i = 0; i < parts.length - 1; i++) {
+        if (cur == null || typeof cur !== 'object') return null
+        if (!(parts[i] in cur)) cur[parts[i]] = {}
+        cur = cur[parts[i]]
+      }
+      if (cur == null || typeof cur !== 'object') return null
+      const leaf = parts[parts.length - 1]
+      if (del) delete cur[leaf]
+      else cur[leaf] = value
+    }
+    const nl = /\n$/.test(text) ? '\n' : ''
+    return JSON.stringify(doc, null, detectIndent(text)) + nl
+  },
+}

package/lang-python.js

@@ -0,0 +1,360 @@
+// Python language provider for ICR — indentation-based structural splitter.
+// Implements the ICR provider contract { id, exts, parses, units, declaredNames,
+// splitUnit, parsesUnit } so the shared merge engine merges Python by structure:
+// top-level defs/classes/statements are units keyed by name; editing different
+// methods of the same class merges via splitUnit. Heuristic (tracks #-comments,
+// triple-quoted and normal strings, bracket depth) — not a full parser; parses()
+// is an approximate balanced-delimiter check.
+
+function scannerAt(src) {
+  const n = src.length
+  return function at(i) {
+    if (src[i] === '#') { let j = i + 1; while (j < n && src[j] !== '\n') j++; return j }
+    for (const q of ['"""', "'''"]) if (src.startsWith(q, i)) { let j = i + 3; while (j < n && !src.startsWith(q, j)) { if (src[j] === '\\') j++; j++ } return Math.min(n, j + 3) }
+    if (src[i] === '"' || src[i] === "'") { const q = src[i]; let j = i + 1; while (j < n) { if (src[j] === '\\') { j += 2; continue } if (src[j] === q) { j++; break } if (src[j] === '\n') break; j++ } return j }
+    return -1
+  }
+}
+
+// Line records: { start, end (incl newline), indent, blank, text }
+function lines(src) {
+  const out = []
+  let i = 0
+  while (i < src.length) {
+    let e = src.indexOf('\n', i); if (e < 0) e = src.length; else e = e + 1
+    const raw = src.slice(i, e)
+    const trimmed = raw.replace(/\r?\n$/, '')
+    let indent = 0; while (indent < trimmed.length && (trimmed[indent] === ' ' || trimmed[indent] === '\t')) indent++
+    const blank = trimmed.trim() === '' || trimmed.trim().startsWith('#')
+    out.push({ start: i, end: e, indent, blank, text: raw })
+    i = e
+  }
+  return out
+}
+
+const HEAD = /^\s*(?:async\s+def|def)\s+([A-Za-z_]\w*)/
+const CLS = /^\s*class\s+([A-Za-z_]\w*)/
+// Continuation clauses of a COMPOUND statement. They are not independent statements —
+// an `else:` only means something relative to its `if`/`for`/`try` — so blocks() must
+// attach them to the preceding unit. Keying them separately let two sides' restructured
+// if/else halves interleave into adjacent dangling `else:` blocks (ConGra, transformers
+// file_utils.py: output had `else:` twice in a row — ast-invalid, heuristics blind).
+const COMPOUND_CONT = /^\s*(?:else\b|elif\b|except\b|finally\b)/
+
+function keyOf(text) {
+  let m = text.match(HEAD); if (m) return 'def:' + m[1]
+  m = text.match(CLS); if (m) return 'class:' + m[1]
+  return 'stmt:' + text.split('\n')[0].trim().replace(/\s+/g, ' ')
+}
+
+// Split src into units whose heads sit at exactly `base` indentation. A def/class
+// head owns the following blank + more-indented lines (its body). A run of leading
+// @decorator lines attaches to the head that follows. Everything else is a
+// one-logical-line statement (continued while bracket depth > 0).
+function blocks(src, base = 0) {
+  const L = lines(src)
+  const at = scannerAt(src)
+  const units = []
+  let i = 0
+  // find bracket depth over a line range (to keep continued statements together)
+  const bracketDelta = (s, e) => {
+    let d = 0, k = s
+    while (k < e) { const j = at(k); if (j > k) { k = j; continue } const c = src[k]; if (c === '(' || c === '[' || c === '{') d++; else if (c === ')' || c === ']' || c === '}') d--; k++ }
+    return d
+  }
+  while (i < L.length) {
+    while (i < L.length && L[i].text.trim() === '') i++ // skip ONLY pure blank lines, NOT comments
+    if (i >= L.length) break
+    if (L[i].indent !== base) { // stray deeper line (shouldn't happen at top) — treat as its own stmt
+      const s = L[i].start; let e = L[i].end; i++
+      units.push({ start: s, end: e })
+      continue
+    }
+    const start = L[i].start
+    // consume leading decorators
+    let isDecorator = /^\s*@/.test(L[i].text)
+    while (i < L.length && L[i].indent === base && /^\s*@/.test(L[i].text)) i++
+    const headIdx = i
+    const head = i < L.length ? L[i] : null
+    if (head && (HEAD.test(head.text) || CLS.test(head.text) || isDecorator)) {
+      // a block: consume the header line, then its body (blank or deeper-indented lines)
+      i++ // header line
+      while (i < L.length && (L[i].blank || L[i].indent > base)) i++
+      // Trailing PURE-BLANK lines are GAP text, not part of the unit — if the unit owned
+      // them, appending a new unit after the last one would mutate the last unit's text
+      // and raise a false same-key conflict (found by multilang fuzz). Trailing comments
+      // stay attached (comment-attachment convention).
+      let last = i - 1
+      while (last > headIdx && L[last].text.trim() === '') last--
+      units.push({ start, end: L[last].end })
+    } else if (head) {
+      // simple statement: consume continued lines while bracket depth remains open
+      let e = head.end, depth = bracketDelta(head.start, head.end); i++
+      while (i < L.length && (depth > 0 || /\\\s*$/.test(L[i - 1].text.replace(/\r?\n$/, '')))) { depth += bracketDelta(L[i].start, L[i].end); e = L[i].end; i++ }
+      // COMPOUND statement (if/for/while/try/with/else/…): the logical line ends with ':',
+      // so this header OWNS its indented body — one unit, like def/class. Without this the
+      // body lines become stray per-line units and the clause structure can't survive a
+      // structured merge coherently.
+      const logicalEndsColon = (() => {
+        const at = scannerAt(src)
+        let lastC = '', k = start
+        while (k < e) { const j = at(k); if (j > k) { if (src[k] !== '#') lastC = 's'; k = Math.min(e, j); continue } const c = src[k]; if (c !== ' ' && c !== '\t' && c !== '\r' && c !== '\n') lastC = c; k++ }
+        return lastC === ':'
+      })()
+      if (logicalEndsColon) {
+        const bodyHead = i - 1
+        while (i < L.length && (L[i].blank || L[i].indent > base)) i++
+        let last = i - 1
+        while (last > bodyHead && L[last].text.trim() === '') last--
+        e = L[last].end
+      }
+      // Continuation clause (else/elif/except/finally): not an independent statement —
+      // extend the PREVIOUS unit so the whole compound statement is one mergeable unit.
+      if (COMPOUND_CONT.test(head.text) && units.length) units[units.length - 1].end = e
+      else units.push({ start, end: e })
+    }
+  }
+  return units
+}
+
+function keyed(raw, src) {
+  const seen = new Map(), out = []
+  for (const u of raw) {
+    const text = src.slice(u.start, u.end)
+    let k = keyOf(text)
+    const c = (seen.get(k) || 0) + 1; seen.set(k, c)
+    if (c > 1) k += '#' + c
+    out.push({ key: k, text, start: u.start, end: u.end })
+  }
+  return out
+}
+
+function balanced(src) {
+  const at = scannerAt(src)
+  const stack = []
+  const pair = { ')': '(', ']': '[', '}': '{' }
+  let i = 0
+  while (i < src.length) {
+    const j = at(i); if (j > i) { if (j > src.length) return false; i = j; continue }
+    const c = src[i]
+    if (c === '(' || c === '[' || c === '{') stack.push(c)
+    else if (pair[c]) { if (stack.pop() !== pair[c]) return false }
+    i++
+  }
+  return stack.length === 0
+}
+
+// INDENTATION validity — the half of Python syntax that delimiter balance cannot see.
+// Walks LOGICAL lines (joining bracket continuations, backslash continuations, and
+// multi-line strings) and enforces Python's block rules: a line ending with ':' must
+// open a deeper-indented block; an indent may only appear after such an opener; every
+// dedent must land on an indent level already on the stack. This is what lets parses()
+// refuse a merge that spliced statements into the wrong block — balance alone passes it.
+// The first line's indent is taken as the baseline so unit fragments validate too.
+function indentsOk(src) {
+  const at = scannerAt(src)
+  const n = src.length
+  let stack = null // [indent levels]; seeded from the first logical line
+  let i = 0, prevOpened = false
+  while (i < n) {
+    let indent = 0
+    while (i < n && (src[i] === ' ' || src[i] === '\t')) { indent++; i++ }
+    if (i >= n) break
+    if (src[i] === '\r' || src[i] === '\n') { i++; continue }              // blank line
+    if (src[i] === '#') { i = Math.min(n, at(i)); continue }               // comment-only line
+    if (stack == null) stack = [indent]                                     // baseline (fragment-friendly)
+    if (prevOpened) {
+      if (indent <= stack[stack.length - 1]) return false                   // ':' promised a block; none came
+      stack.push(indent)
+    } else if (indent > stack[stack.length - 1]) {
+      return false                                                          // indent without an opener
+    } else if (indent < stack[stack.length - 1]) {
+      while (stack.length > 1 && stack[stack.length - 1] > indent) stack.pop()
+      if (stack[stack.length - 1] !== indent) return false                  // dedent to a level never opened
+    }
+    // scan to the end of this LOGICAL line (brackets, backslash, strings span physical lines)
+    let depth = 0, last = ''
+    while (i < n) {
+      const j = at(i)
+      if (j > i) { if (src[i] !== '#') last = 's'; i = Math.min(n, j); continue } // string counts as content; comment doesn't
+      const c = src[i]
+      if (c === '(' || c === '[' || c === '{') depth++
+      else if (c === ')' || c === ']' || c === '}') depth--
+      if (c === '\n') {
+        if (depth > 0 || last === '\\') { if (last === '\\') last = ''; i++; continue } // continuation
+        i++; break
+      }
+      if (c !== ' ' && c !== '\t' && c !== '\r') last = c
+      i++
+    }
+    prevOpened = last === ':'
+  }
+  return !prevOpened // must not end still promising a block
+}
+
+// Generic lexer for the token-level inner merge + the intent layer. Identifiers,
+// numbers, whole strings are tokens; comments live in the gaps (a comment-only edit
+// is a no-op at this tier, same contract as the JS provider).
+function lexTokens(src) {
+  const at = scannerAt(src)
+  const out = []
+  const n = src.length
+  let i = 0
+  while (i < n) {
+    const c = src[i]
+    if (c === ' ' || c === '\t' || c === '\r' || c === '\n') { i++; continue }
+    const j = at(i)
+    if (j > i) {
+      if (c === '#') { i = j; continue }                                    // comment → gap
+      out.push({ start: i, end: j, k: src.slice(i, j) }); i = j; continue   // string → one token
+    }
+    if (/[A-Za-z_]/.test(c)) { let e = i + 1; while (e < n && /\w/.test(src[e])) e++; out.push({ start: i, end: e, k: src.slice(i, e) }); i = e; continue }
+    if (/[0-9]/.test(c)) { let e = i + 1; while (e < n && /[\w.]/.test(src[e])) e++; out.push({ start: i, end: e, k: src.slice(i, e) }); i = e; continue }
+    out.push({ start: i, end: i + 1, k: c }); i++
+  }
+  return out
+}
+
+// Token stream for the token-level MERGE tier, in an indentation language. Unlike
+// lexTokens (used by the intent layer, where whitespace is noise), this emits a NEWLINE
+// token for every real line break — a statement boundary. Without it a token splice can
+// weld two statements onto one physical line (`x = f(y)if z:`), which balance+indent
+// checks read as a single logical line and wrongly accept — a parse-guarantee violation
+// found by the ConGra corpus (ast.parse rejects it). With newlines as tokens, any spliced
+// run that crosses a line carries its break, so statements can never fuse. Newlines inside
+// strings/comments stay inside those tokens; a bare `\n` between brackets is still emitted
+// (harmless: it only ever makes the token diff finer, never coarser).
+function lexTokensNL(src) {
+  const at = scannerAt(src)
+  const out = []
+  const n = src.length
+  let i = 0, depth = 0, contBackslash = false
+  while (i < n) {
+    const c = src[i]
+    if (c === '\n') {
+      // Emit a NEWLINE token only at a real statement boundary: not inside brackets, not
+      // after a line-continuation backslash. Inside brackets a newline is insignificant
+      // (like whitespace) — emitting it there corrupts multi-line-call token interleaving.
+      if (depth === 0 && !contBackslash) out.push({ start: i, end: i + 1, k: '\n' })
+      contBackslash = false; i++; continue
+    }
+    if (c === ' ' || c === '\t' || c === '\r') { i++; continue }
+    const j = at(i)
+    if (j > i) {
+      contBackslash = false
+      if (c === '#') { i = j; continue }
+      out.push({ start: i, end: j, k: src.slice(i, j) }); i = j; continue
+    }
+    if (c === '\\') { contBackslash = true; i++; continue }
+    contBackslash = false
+    if (c === '(' || c === '[' || c === '{') depth++
+    else if (c === ')' || c === ']' || c === '}') { if (depth > 0) depth-- }
+    if (/[A-Za-z_]/.test(c)) { let e = i + 1; while (e < n && /\w/.test(src[e])) e++; out.push({ start: i, end: e, k: src.slice(i, e) }); i = e; continue }
+    if (/[0-9]/.test(c)) { let e = i + 1; while (e < n && /[\w.]/.test(src[e])) e++; out.push({ start: i, end: e, k: src.slice(i, e) }); i = e; continue }
+    out.push({ start: i, end: i + 1, k: c }); i++
+  }
+  return out
+}
+
+// Reference-position identifier (not attribute access `.name`)?
+function isRefToken(src, t) {
+  if (!/^[A-Za-z_]\w*$/.test(t.k)) return false
+  let p = t.start - 1
+  while (p >= 0 && (src[p] === ' ' || src[p] === '\t')) p--
+  return !(p >= 0 && src[p] === '.')
+}
+
+// PER-STATEMENT bracket nesting — the soundness backstop the whole-file `balanced()`
+// (global) and `indentsOk()` (indentation) both miss. A token merge can splice a result
+// that is GLOBALLY balanced yet LOCALLY mis-nested: side A reformats `f(x)` to span lines
+// and a concurrent edit detaches the `)`, so `( ... { ... )` lands in one statement and a
+// stray `)` balances the count elsewhere. In VALID Python every logical statement is
+// independently balanced AND properly nested, so we check exactly that: segment the token
+// stream at depth-0 NEWLINE tokens (which lexTokensNL only emits between statements) and
+// require each segment's brackets to nest correctly. Sound — it never rejects valid Python
+// — and it closes the token-merge corruption class the ConGra corpus exposed via ast.parse.
+function stmtBracketsOk(src) {
+  const pair = { ')': '(', ']': '[', '}': '{' }
+  let stack = []
+  for (const t of lexTokensNL(src)) {
+    if (t.k === '\n') { if (stack.length) return false; continue } // statement boundary: must be closed
+    if (t.k === '(' || t.k === '[' || t.k === '{') stack.push(t.k)
+    else if (pair[t.k]) { if (stack.pop() !== pair[t.k]) return false }
+  }
+  return stack.length === 0
+}
+
+export const python = {
+  id: 'python',
+  exts: ['.py', '.pyi'],
+  parses: (src) => { const s = String(src == null ? '' : src); return balanced(s) && stmtBracketsOk(s) && indentsOk(s) },
+  parsesUnit: (src) => { const s = String(src); return balanced(s) && indentsOk(s) },
+  units: (src) => keyed(blocks(String(src), 0), String(src)),
+  declaredNames: (src) => {
+    const names = new Set()
+    for (const u of keyed(blocks(String(src), 0), String(src))) {
+      const m = u.key.match(/^(?:def|class):([A-Za-z_]\w*)/)
+      if (m) names.add(m[1])
+    }
+    return names
+  },
+  // --- intent layer (heuristic but honest): dangling refs, rename, token merge ---
+  // Every identifier used in reference position (skips `.attribute` access). Approximate
+  // and OVER-inclusive — which only makes the dangling check MORE cautious: a deleted-
+  // but-still-referenced def/class is surfaced as a conflict, never shipped broken.
+  usedIdentifiers: (src) => {
+    src = String(src)
+    const used = new Set()
+    for (const t of lexTokens(src)) if (isRefToken(src, t)) used.add(t.k)
+    return used
+  },
+  // The def/class text with its own name excluded, so renamed twins compare equal.
+  // trimEnd(): a unit owns its trailing blank lines, and splicing can change how many
+  // survive — trailing whitespace must not defeat the rename match.
+  declBody: (src, name) => {
+    src = String(src)
+    for (const u of keyed(blocks(src, 0), src)) {
+      const m = u.key.match(/^(?:def|class):([A-Za-z_]\w*)/)
+      if (!m || m[1] !== name) continue
+      return u.text.replace(name, '').trimEnd()
+    }
+    return null
+  },
+  // Rewrite reference-position uses of oldName (never `.oldName` attribute access).
+  // The engine only accepts the rewrite if the result still passes parses().
+  renameRefs: (src, oldName, newName) => {
+    src = String(src)
+    const spots = []
+    for (const t of lexTokens(src)) if (t.k === oldName && isRefToken(src, t)) spots.push(t)
+    let out = src
+    for (const t of spots.reverse()) out = out.slice(0, t.start) + newName + out.slice(t.end)
+    return out
+  },
+  // Finest granularity: token stream for the token-level inner merge. NEWLINE-aware
+  // (lexTokensNL) so a token splice can never weld two statements onto one line — the
+  // parse guarantee holds even where the indentation heuristic alone would be fooled.
+  tokenize: (src) => lexTokensNL(String(src)),
+  // Descend into a class/def body so two agents editing DIFFERENT methods merge.
+  splitUnit: (text) => {
+    const src = String(text)
+    const L = lines(src)
+    let h = 0; while (h < L.length && (L[h].blank || /^\s*@/.test(L[h].text))) h++
+    if (h >= L.length) return null
+    // Only descend into a CLASS (named methods → mergeable). A def body is bare
+    // statements with no stable keys; descending would falsely merge two edits to the
+    // same function, so we don't — same-def edits become a clean conflict instead.
+    if (!CLS.test(L[h].text)) return null
+    const headEnd = L[h].end
+    // body = everything after the header line; its base indent is the first body line's indent
+    let b = h + 1; while (b < L.length && L[b].blank) b++
+    if (b >= L.length) return null
+    const bodyIndent = L[b].indent
+    const sig = src.slice(0, headEnd)
+    const body = src.slice(headEnd)
+    const inner = keyed(blocks(body, bodyIndent), body)
+    // spliceable: inner units carry byte ranges in `body`, so the engine rebuilds the
+    // class body by splicing merged methods back in — comments/blank lines between
+    // methods survive verbatim instead of being reflowed by a join.
+    return { sig, open: '', close: '', body, units: inner, join: '', spliceable: true }
+  },
+}