hivecode-mcp 0.14.0 → 0.14.2

package/lang-python.js

@@ -1,588 +1,588 @@
-// 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] === '.')
-}
-
-// --- scope-aware reference analysis ---------------------------------------------
-//
-// WHY THIS IS EXACT AND NOT ANOTHER HEURISTIC. Python binds by assignment: a name
-// assigned anywhere in a function body is local to that function for the WHOLE body, and
-// reading it before the assignment is an UnboundLocalError rather than a global read. So
-// a function that assigns `helper` cannot also be referring to a module-level `helper` —
-// the language forbids the mixed case. That is what makes subtracting local bindings safe
-// here, where a plain "does this name appear anywhere" check has to stay over-cautious.
-//
-// WHAT IT FIXES. usedIdentifiers reports every name it sees, so deleting a top-level
-// `helper` while some unrelated function happens to have a local named `helper` was
-// reported as ref:helper — a merge refused that was perfectly safe, falling back to line
-// merge with conflict markers. Common names (config, data, result, helper) trip this
-// constantly. Reproduced in test/scope-repro.mjs before this existed.
-//
-// THE DIRECTION THAT MATTERS. Missing a REAL reference would let ICR delete something
-// still in use — the one failure this library promises never to have — so every rule
-// below fails towards "still referenced":
-//   • module scope subtracts nothing, so top-level rebinding never hides a reference;
-//   • a nested def is its own scope, never folded into its parent's bindings;
-//   • a class body contributes no bindings at all (its names are attributes, invisible
-//     to methods), so they stay free;
-//   • `global`/`nonlocal` remove a name from the local set;
-//   • subscript and attribute targets (`a[i] = `, `a.b = `) bind nothing — `a` must
-//     already exist, so it stays a reference;
-//   • anything unrecognised is left free.
-const PY_KW = new Set(['False', 'None', 'True', 'and', 'as', 'assert', 'async', 'await',
-  'break', 'class', 'continue', 'def', 'del', 'elif', 'else', 'except', 'finally', 'for',
-  'from', 'global', 'if', 'import', 'in', 'is', 'lambda', 'nonlocal', 'not', 'or', 'pass',
-  'raise', 'return', 'try', 'while', 'with', 'yield'])
-
-const isName = (k) => /^[A-Za-z_]\w*$/.test(k) && !PY_KW.has(k)
-const OPEN = new Set(['(', '[', '{'])
-const CLOSE = new Set([')', ']', '}'])
-
-// A target position binds only a bare name. `a[i] = x` and `a.b = x` require `a` to exist
-// already, so they are reads, not bindings.
-function bareTargets(toks, from, to, out) {
-  for (let i = from; i < to; i++) {
-    const t = toks[i]
-    if (!isName(t.k)) continue
-    const prev = toks[i - 1] && toks[i - 1].k
-    const next = toks[i + 1] && toks[i + 1].k
-    if (prev === '.' || next === '.' || next === '[' || next === '(') continue
-    out.add(t.k)
-  }
-}
-
-// Names this statement binds in its own scope, and names it explicitly disowns.
-function stmtBindings(text) {
-  const bind = new Set(), disown = new Set()
-  const toks = lexTokens(text).filter((t) => t.k.trim() !== '')
-  const kw = toks.length ? toks[0].k : ''
-
-  if (kw === 'global' || kw === 'nonlocal') {
-    for (const t of toks.slice(1)) if (isName(t.k)) disown.add(t.k)
-    return { bind, disown }
-  }
-
-  if (kw === 'import' || kw === 'from') {
-    // `import a.b as c` binds c; `import a.b` binds a; `from m import x, y as z`.
-    const start = kw === 'from' ? toks.findIndex((t) => t.k === 'import') : 0
-    if (start >= 0) {
-      for (let i = start + 1; i < toks.length; i++) {
-        if (toks[i].k === 'as' && isName((toks[i + 1] || {}).k)) { bind.add(toks[i + 1].k); i++; continue }
-        // first segment of a dotted path, and only when not renamed by a later `as`
-        if (isName(toks[i].k) && (toks[i - 1] || {}).k !== '.' &&
-            (toks[i + 1] || {}).k !== '.' && (toks[i + 1] || {}).k !== 'as') bind.add(toks[i].k)
-        else if (isName(toks[i].k) && (toks[i + 1] || {}).k === '.' && kw === 'import') bind.add(toks[i].k)
-      }
-    }
-    return { bind, disown }
-  }
-
-  let depth = 0
-  for (let i = 0; i < toks.length; i++) {
-    const k = toks[i].k
-    if (OPEN.has(k)) { depth++; continue }
-    if (CLOSE.has(k)) { depth--; continue }
-
-    // `for <targets> in` — at any depth, so comprehensions bind too.
-    if (k === 'for') {
-      let j = i + 1
-      while (j < toks.length && toks[j].k !== 'in') j++
-      bareTargets(toks, i + 1, j, bind)
-      i = j
-      continue
-    }
-    // `with x as name`, `except E as name`
-    if (k === 'as' && isName((toks[i + 1] || {}).k)) { bind.add(toks[i + 1].k); i++; continue }
-
-    if (k !== '=') continue
-    const prev = (toks[i - 1] || {}).k
-    const next = (toks[i + 1] || {}).k
-    if (next === '=') { i++; continue }                       // ==
-    if (prev === '=' || prev === '!' || prev === '<' || prev === '>') continue
-    if (depth > 0) {
-      // Inside brackets `=` is a keyword argument, except for the walrus `:=`.
-      if (prev === ':' && isName((toks[i - 2] || {}).k)) bind.add(toks[i - 2].k)
-      continue
-    }
-    // Statement-level assignment: simple, augmented (`+=`, prev is an operator), or
-    // annotated (`x: int = 1`). Everything left of it is the target list.
-    bareTargets(toks, 0, i, bind)
-    break
-  }
-  return { bind, disown }
-}
-
-function refsIn(text, emit) {
-  for (const t of lexTokens(text)) if (isName(t.k) && isRefToken(text, t)) emit(t.k)
-}
-
-// Parameter names of a def header — used as bindings of the CHILD scope, and excluded
-// from the header's own references so a parameter is never mistaken for a free name.
-function defParams(header) {
-  const toks = lexTokens(header).filter((t) => t.k.trim() !== '')
-  const open = toks.findIndex((t) => t.k === '(')
-  if (open < 0) return new Set()
-  const params = new Set()
-  let depth = 0
-  for (let i = open; i < toks.length; i++) {
-    const k = toks[i].k
-    if (OPEN.has(k)) { depth++; continue }
-    if (CLOSE.has(k)) { depth--; if (depth === 0) break; continue }
-    if (depth !== 1 || !isName(k)) continue
-    const prev = (toks[i - 1] || {}).k
-    if (prev === '(' || prev === ',' || prev === '*' || prev === '**') params.add(k)
-  }
-  return params
-}
-
-// Split a def/class unit into the part evaluated in the ENCLOSING scope (decorators and
-// the header line — where default values and base classes live) and the body, which is
-// its own scope.
-function splitDeclUnit(text) {
-  const L = lines(text)
-  let h = 0
-  while (h < L.length && (L[h].blank || /^\s*@/.test(L[h].text))) h++
-  if (h >= L.length) return null
-  const head = L[h]
-  const isDef = HEAD.test(head.text), isCls = CLS.test(head.text)
-  if (!isDef && !isCls) return null
-  // A signature can span lines while its brackets are open.
-  let e = h
-  let depth = 0
-  do {
-    for (const ch of L[e].text) { if (OPEN.has(ch)) depth++; else if (CLOSE.has(ch)) depth-- }
-    e++
-  } while (e < L.length && depth > 0)
-  const header = text.slice(0, L[e - 1].end)
-  let b = e
-  while (b < L.length && L[b].blank) b++
-  const body = b < L.length ? text.slice(L[b].start) : ''
-  return { isDef, header, body, bodyIndent: b < L.length ? L[b].indent : 0 }
-}
-
-// Walk one scope's statements, descending through compound bodies (same scope) but
-// stopping at def/class (new scope).
-function scopeParts(code, base, onStmt, onDecl) {
-  for (const u of blocks(code, base)) {
-    const text = code.slice(u.start, u.end)
-    if (splitDeclUnit(text)) { onDecl(text); continue }
-    const L = lines(text)
-    let b = 1
-    while (b < L.length && L[b].blank) b++
-    if (b < L.length && L[b].indent > base) {
-      onStmt(text.slice(0, L[b].start))                    // the `if ...:` / `for ...:` head
-      scopeParts(text.slice(L[b].start), L[b].indent, onStmt, onDecl)
-    } else onStmt(text)
-  }
-}
-
-// `subtract` is false at module scope: a module-level rebinding must never hide a
-// reference to the declaration being deleted.
-function scopeFree(code, base, enclosing, free, subtract) {
-  const stmts = [], decls = []
-  scopeParts(code, base, (t) => stmts.push(t), (t) => decls.push(t))
-
-  const local = new Set(), disowned = new Set()
-  for (const t of stmts) {
-    const { bind, disown } = stmtBindings(t)
-    for (const n of bind) local.add(n)
-    for (const n of disown) disowned.add(n)
-  }
-  for (const t of decls) {
-    const s = splitDeclUnit(t)
-    const m = s && (s.header.match(HEAD) || s.header.match(CLS))
-    if (m) local.add(m[1])
-  }
-  for (const n of disowned) local.delete(n)
-
-  const bound = subtract ? new Set([...enclosing, ...local]) : new Set(enclosing)
-  for (const t of stmts) refsIn(t, (n) => { if (!bound.has(n)) free.add(n) })
-
-  for (const t of decls) {
-    const s = splitDeclUnit(t)
-    if (!s) continue
-    const params = s.isDef ? defParams(s.header) : new Set()
-    const declName = (s.header.match(HEAD) || s.header.match(CLS) || [])[1]
-    // Decorators, annotations and default values run in THIS scope.
-    refsIn(s.header, (n) => {
-      if (n === declName || params.has(n) || bound.has(n)) return
-      free.add(n)
-    })
-    if (!s.body) continue
-    // A class body contributes no bindings to anything nested inside it, so its methods
-    // are analysed against the enclosing scope only. `subtract: s.isDef` is the whole of
-    // that rule and it is load-bearing: with subtraction left on for a class, `helper = 9`
-    // at class level became a binding the methods inherited, and a real `helper()` call
-    // inside a method stopped being reported — a merge shipped with a dangling reference,
-    // caught by the safety case in test/scope-repro.mjs. Class attributes are reached as
-    // `self.helper` or `C.helper`, never as a bare name, so they must never shadow.
-    scopeFree(s.body, s.bodyIndent,
-              s.isDef ? new Set([...bound, ...params]) : bound, free, s.isDef)
-  }
-}
-
-// 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
-  },
-  // Scope-aware upgrade of the above — the engine prefers this for the dangling-reference
-  // check (icr.js). Names that resolve to a LOCAL binding are not reported, so a deleted
-  // top-level `helper` is no longer held hostage by an unrelated local of the same name.
-  // Kept alongside usedIdentifiers rather than replacing it: the approximate version is
-  // still the honest answer for anything this cannot resolve.
-  referencedFreeNames: (src) => {
-    const free = new Set()
-    scopeFree(String(src), 0, new Set(), free, false)
-    return free
-  },
-  // 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 }
-  },
-}
+// 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] === '.')
+}
+
+// --- scope-aware reference analysis ---------------------------------------------
+//
+// WHY THIS IS EXACT AND NOT ANOTHER HEURISTIC. Python binds by assignment: a name
+// assigned anywhere in a function body is local to that function for the WHOLE body, and
+// reading it before the assignment is an UnboundLocalError rather than a global read. So
+// a function that assigns `helper` cannot also be referring to a module-level `helper` —
+// the language forbids the mixed case. That is what makes subtracting local bindings safe
+// here, where a plain "does this name appear anywhere" check has to stay over-cautious.
+//
+// WHAT IT FIXES. usedIdentifiers reports every name it sees, so deleting a top-level
+// `helper` while some unrelated function happens to have a local named `helper` was
+// reported as ref:helper — a merge refused that was perfectly safe, falling back to line
+// merge with conflict markers. Common names (config, data, result, helper) trip this
+// constantly. Reproduced in test/scope-repro.mjs before this existed.
+//
+// THE DIRECTION THAT MATTERS. Missing a REAL reference would let ICR delete something
+// still in use — the one failure this library promises never to have — so every rule
+// below fails towards "still referenced":
+//   • module scope subtracts nothing, so top-level rebinding never hides a reference;
+//   • a nested def is its own scope, never folded into its parent's bindings;
+//   • a class body contributes no bindings at all (its names are attributes, invisible
+//     to methods), so they stay free;
+//   • `global`/`nonlocal` remove a name from the local set;
+//   • subscript and attribute targets (`a[i] = `, `a.b = `) bind nothing — `a` must
+//     already exist, so it stays a reference;
+//   • anything unrecognised is left free.
+const PY_KW = new Set(['False', 'None', 'True', 'and', 'as', 'assert', 'async', 'await',
+  'break', 'class', 'continue', 'def', 'del', 'elif', 'else', 'except', 'finally', 'for',
+  'from', 'global', 'if', 'import', 'in', 'is', 'lambda', 'nonlocal', 'not', 'or', 'pass',
+  'raise', 'return', 'try', 'while', 'with', 'yield'])
+
+const isName = (k) => /^[A-Za-z_]\w*$/.test(k) && !PY_KW.has(k)
+const OPEN = new Set(['(', '[', '{'])
+const CLOSE = new Set([')', ']', '}'])
+
+// A target position binds only a bare name. `a[i] = x` and `a.b = x` require `a` to exist
+// already, so they are reads, not bindings.
+function bareTargets(toks, from, to, out) {
+  for (let i = from; i < to; i++) {
+    const t = toks[i]
+    if (!isName(t.k)) continue
+    const prev = toks[i - 1] && toks[i - 1].k
+    const next = toks[i + 1] && toks[i + 1].k
+    if (prev === '.' || next === '.' || next === '[' || next === '(') continue
+    out.add(t.k)
+  }
+}
+
+// Names this statement binds in its own scope, and names it explicitly disowns.
+function stmtBindings(text) {
+  const bind = new Set(), disown = new Set()
+  const toks = lexTokens(text).filter((t) => t.k.trim() !== '')
+  const kw = toks.length ? toks[0].k : ''
+
+  if (kw === 'global' || kw === 'nonlocal') {
+    for (const t of toks.slice(1)) if (isName(t.k)) disown.add(t.k)
+    return { bind, disown }
+  }
+
+  if (kw === 'import' || kw === 'from') {
+    // `import a.b as c` binds c; `import a.b` binds a; `from m import x, y as z`.
+    const start = kw === 'from' ? toks.findIndex((t) => t.k === 'import') : 0
+    if (start >= 0) {
+      for (let i = start + 1; i < toks.length; i++) {
+        if (toks[i].k === 'as' && isName((toks[i + 1] || {}).k)) { bind.add(toks[i + 1].k); i++; continue }
+        // first segment of a dotted path, and only when not renamed by a later `as`
+        if (isName(toks[i].k) && (toks[i - 1] || {}).k !== '.' &&
+            (toks[i + 1] || {}).k !== '.' && (toks[i + 1] || {}).k !== 'as') bind.add(toks[i].k)
+        else if (isName(toks[i].k) && (toks[i + 1] || {}).k === '.' && kw === 'import') bind.add(toks[i].k)
+      }
+    }
+    return { bind, disown }
+  }
+
+  let depth = 0
+  for (let i = 0; i < toks.length; i++) {
+    const k = toks[i].k
+    if (OPEN.has(k)) { depth++; continue }
+    if (CLOSE.has(k)) { depth--; continue }
+
+    // `for <targets> in` — at any depth, so comprehensions bind too.
+    if (k === 'for') {
+      let j = i + 1
+      while (j < toks.length && toks[j].k !== 'in') j++
+      bareTargets(toks, i + 1, j, bind)
+      i = j
+      continue
+    }
+    // `with x as name`, `except E as name`
+    if (k === 'as' && isName((toks[i + 1] || {}).k)) { bind.add(toks[i + 1].k); i++; continue }
+
+    if (k !== '=') continue
+    const prev = (toks[i - 1] || {}).k
+    const next = (toks[i + 1] || {}).k
+    if (next === '=') { i++; continue }                       // ==
+    if (prev === '=' || prev === '!' || prev === '<' || prev === '>') continue
+    if (depth > 0) {
+      // Inside brackets `=` is a keyword argument, except for the walrus `:=`.
+      if (prev === ':' && isName((toks[i - 2] || {}).k)) bind.add(toks[i - 2].k)
+      continue
+    }
+    // Statement-level assignment: simple, augmented (`+=`, prev is an operator), or
+    // annotated (`x: int = 1`). Everything left of it is the target list.
+    bareTargets(toks, 0, i, bind)
+    break
+  }
+  return { bind, disown }
+}
+
+function refsIn(text, emit) {
+  for (const t of lexTokens(text)) if (isName(t.k) && isRefToken(text, t)) emit(t.k)
+}
+
+// Parameter names of a def header — used as bindings of the CHILD scope, and excluded
+// from the header's own references so a parameter is never mistaken for a free name.
+function defParams(header) {
+  const toks = lexTokens(header).filter((t) => t.k.trim() !== '')
+  const open = toks.findIndex((t) => t.k === '(')
+  if (open < 0) return new Set()
+  const params = new Set()
+  let depth = 0
+  for (let i = open; i < toks.length; i++) {
+    const k = toks[i].k
+    if (OPEN.has(k)) { depth++; continue }
+    if (CLOSE.has(k)) { depth--; if (depth === 0) break; continue }
+    if (depth !== 1 || !isName(k)) continue
+    const prev = (toks[i - 1] || {}).k
+    if (prev === '(' || prev === ',' || prev === '*' || prev === '**') params.add(k)
+  }
+  return params
+}
+
+// Split a def/class unit into the part evaluated in the ENCLOSING scope (decorators and
+// the header line — where default values and base classes live) and the body, which is
+// its own scope.
+function splitDeclUnit(text) {
+  const L = lines(text)
+  let h = 0
+  while (h < L.length && (L[h].blank || /^\s*@/.test(L[h].text))) h++
+  if (h >= L.length) return null
+  const head = L[h]
+  const isDef = HEAD.test(head.text), isCls = CLS.test(head.text)
+  if (!isDef && !isCls) return null
+  // A signature can span lines while its brackets are open.
+  let e = h
+  let depth = 0
+  do {
+    for (const ch of L[e].text) { if (OPEN.has(ch)) depth++; else if (CLOSE.has(ch)) depth-- }
+    e++
+  } while (e < L.length && depth > 0)
+  const header = text.slice(0, L[e - 1].end)
+  let b = e
+  while (b < L.length && L[b].blank) b++
+  const body = b < L.length ? text.slice(L[b].start) : ''
+  return { isDef, header, body, bodyIndent: b < L.length ? L[b].indent : 0 }
+}
+
+// Walk one scope's statements, descending through compound bodies (same scope) but
+// stopping at def/class (new scope).
+function scopeParts(code, base, onStmt, onDecl) {
+  for (const u of blocks(code, base)) {
+    const text = code.slice(u.start, u.end)
+    if (splitDeclUnit(text)) { onDecl(text); continue }
+    const L = lines(text)
+    let b = 1
+    while (b < L.length && L[b].blank) b++
+    if (b < L.length && L[b].indent > base) {
+      onStmt(text.slice(0, L[b].start))                    // the `if ...:` / `for ...:` head
+      scopeParts(text.slice(L[b].start), L[b].indent, onStmt, onDecl)
+    } else onStmt(text)
+  }
+}
+
+// `subtract` is false at module scope: a module-level rebinding must never hide a
+// reference to the declaration being deleted.
+function scopeFree(code, base, enclosing, free, subtract) {
+  const stmts = [], decls = []
+  scopeParts(code, base, (t) => stmts.push(t), (t) => decls.push(t))
+
+  const local = new Set(), disowned = new Set()
+  for (const t of stmts) {
+    const { bind, disown } = stmtBindings(t)
+    for (const n of bind) local.add(n)
+    for (const n of disown) disowned.add(n)
+  }
+  for (const t of decls) {
+    const s = splitDeclUnit(t)
+    const m = s && (s.header.match(HEAD) || s.header.match(CLS))
+    if (m) local.add(m[1])
+  }
+  for (const n of disowned) local.delete(n)
+
+  const bound = subtract ? new Set([...enclosing, ...local]) : new Set(enclosing)
+  for (const t of stmts) refsIn(t, (n) => { if (!bound.has(n)) free.add(n) })
+
+  for (const t of decls) {
+    const s = splitDeclUnit(t)
+    if (!s) continue
+    const params = s.isDef ? defParams(s.header) : new Set()
+    const declName = (s.header.match(HEAD) || s.header.match(CLS) || [])[1]
+    // Decorators, annotations and default values run in THIS scope.
+    refsIn(s.header, (n) => {
+      if (n === declName || params.has(n) || bound.has(n)) return
+      free.add(n)
+    })
+    if (!s.body) continue
+    // A class body contributes no bindings to anything nested inside it, so its methods
+    // are analysed against the enclosing scope only. `subtract: s.isDef` is the whole of
+    // that rule and it is load-bearing: with subtraction left on for a class, `helper = 9`
+    // at class level became a binding the methods inherited, and a real `helper()` call
+    // inside a method stopped being reported — a merge shipped with a dangling reference,
+    // caught by the safety case in test/scope-repro.mjs. Class attributes are reached as
+    // `self.helper` or `C.helper`, never as a bare name, so they must never shadow.
+    scopeFree(s.body, s.bodyIndent,
+              s.isDef ? new Set([...bound, ...params]) : bound, free, s.isDef)
+  }
+}
+
+// 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
+  },
+  // Scope-aware upgrade of the above — the engine prefers this for the dangling-reference
+  // check (icr.js). Names that resolve to a LOCAL binding are not reported, so a deleted
+  // top-level `helper` is no longer held hostage by an unrelated local of the same name.
+  // Kept alongside usedIdentifiers rather than replacing it: the approximate version is
+  // still the honest answer for anything this cannot resolve.
+  referencedFreeNames: (src) => {
+    const free = new Set()
+    scopeFree(String(src), 0, new Set(), free, false)
+    return free
+  },
+  // 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 }
+  },
+}