hivecode-mcp 0.7.0 → 0.8.0

package/README.md

@@ -1,149 +1,68 @@
-<h1>Hivecode</h1>
-
-**Oversight and control for your AI coding agents.**
-
-Run AI agents on your codebase and actually stay in control: **watch** every edit
-live, **fence** each agent to the folders it's allowed in, **approve** the risky
-moves, and **undo** any agent instantly. No git push/pull. Open source.
-
-[**Install for VS Code**](https://marketplace.visualstudio.com/items?itemName=hivecode.hivecode)
-· [**Website**](https://livecode-xoss.onrender.com)
-· [Latest .vsix](https://github.com/GSK7024/livecode/releases)
-
-<!-- Add a demo GIF here once recorded: ![demo](docs/demo.gif) -->
-
----
-
-## Why
-
-You can't trust an AI agent blindly. The faster it edits, the more you have to
-check — and the moment you run more than one, it gets worse: they touch files they
-shouldn't, overwrite each other, and you lose track of who changed what. Today's
-answer is to isolate each agent in a git worktree and pray at merge time — which
-doesn't help you *trust* the output, it just defers the mess.
-
-Hivecode adds the missing layer: **oversight and control.**
-
-- **See everything** — a live Control Room (browser or phone) shows every agent and every file it touches, in real time.
-- **Fence them in** — folder-scoped access the relay enforces; an out-of-scope agent never even receives the code.
-- **Approve what matters** — gate risky work so nothing lands without your OK.
-- **Undo anything** — instant rollback: restore any file, or revert *everything* one agent did.
-
-It's **agent-neutral**: Claude Code, Cursor, Windsurf, or your own bot over MCP. No
-git push/pull — edits sync in about a second.
-
----
-
-## Quickstart
-
-1. Install the extension (link above). It works in **VS Code, Cursor, Windsurf,
-   and Antigravity**.
-2. Open the folder you want to share (**File → Open Folder**).
-3. `Ctrl/Cmd+Shift+P` → **Hivecode: Host a Secured Session**. A join link is
-   copied to your clipboard. *(No terminal, no server to run.)*
-4. **Hivecode: Invite to folders…** → pick the folders and a role (edit /
-   read-only) for each person or agent. Send them the link.
-5. They run **Hivecode: Join a Session** and paste the link. You're now editing
-   the same project live.
-
-Use **Manage access** to re-scope or revoke anyone, and **Leave Session** to stop.
-
----
-
-## Add an AI agent
-
-Agents join through the Hivecode MCP server ([`hive-mcp.js`](hive-mcp.js)). Set it
-up once, then just hand the agent a join link; it appears in the room as an `ai`
-member, scoped to exactly the folders you invited it to.
-
-- **[JOIN_WITH_AGENT.md](JOIN_WITH_AGENT.md)** — step-by-step for a *human*: set up MCP, then bring your agent in.
-- **[AGENT_MANUAL.md](AGENT_MANUAL.md)** — written *for the agent*: how to set itself up and join (drop it in your project as `CLAUDE.md` so the agent reads it automatically).
-- **[MCP.md](MCP.md)** — the full tool reference.
-
----
-
-## What you get
-
-**Oversight & control** *(the point of the whole thing)*
-- **Live Control Room** — watch every agent and every file it touches in real time,
-  from any browser or your phone. No more "what is it even doing right now?"
-- **Folder-scoped access** — invite an agent to `frontend/` only; it never receives
-  anything else (relay-enforced, not trust-based).
-- **Approval gates** — risky work waits for your OK; agent-to-agent coordination
-  flows automatically.
-- **Instant rollback** — restore any file to an earlier point, or **revert
-  *everything* one agent did** in a click. Undo a rogue agent without touching the
-  rest of the team's work.
-- **Mission control** — pause, resume, or reassign any agent; agents honor it
-  mid-task.
-- **Instant revoke** — cut access mid-session, enforced server-side on every
-  reconnect (and it survives a relay restart).
-- **Read-only roles** — reviewers see everything, change nothing.
-
-**Coordination**
-- **Built-in chat**, a **shared task board** (assign / complete), and **live
-  presence** so humans and agents stay in sync.
-- **Co-editing heads-up** before two people touch the same file.
-- **Never lose work** — overlapping edits keep both versions with conflict markers;
-  a stale rewrite can't silently delete another's lines.
-
-**Trust**
-- **Server-enforced auth** — signed tokens, algorithm-pinned, fail-closed.
-  Unauthorized clients never complete the WebSocket handshake.
-- **Self-certifying secured rooms** — the room id embeds a fingerprint of your
-  public key; tokens carry the key and are signed by it; the relay trusts a token
-  only if the fingerprint matches. No account system, no shared secret. Your
-  private key stays in the editor's secure storage.
-- **Dependency-free core** — the access-control layer uses only Node's `crypto`.
-
----
-
-## How the security model works
-
-A secured room's id is `hs_<fp>_<rand>`, where `fp` is a base64url SHA-256
-fingerprint of the owner's public key. Every token for the room carries the owner's
-public key (claim `pk`) and is signed by the matching private key (RS256). The relay
-trusts a token **iff** `fingerprint(token.pk) === fingerprint-in-room-id`, then
-verifies the signature with that key — so trust is anchored in the room id itself
-and the relay stores nothing.
-
-Files use a per-file subdocument model: the room is `<base>`, each file is a
-separate document at `<base>␁<path>`. The relay authorizes per path, so a scoped
-client can only open the files it may load, and out-of-scope content never reaches
-its disk. Paths are guarded against traversal, absolute paths, drive letters, and
-control characters on both the client (before writing) and the relay.
-
-A full threat/edge-case audit is in [EDGE-CASES.md](EDGE-CASES.md); the RBAC design
-is in [RBAC.md](RBAC.md).
-
----
-
-## Self-hosting the relay
-
-The hosted relay is the default (`wss://livecode-xoss.onrender.com`) and needs no
-setup. To run your own, deploy [`server.js`](server.js) anywhere Node runs and set
-`hivecode.relayUrl` in the extension. The relay holds no truth of its own — it just
-passes CRDT updates between clients in the same room, and enforces access at the
-handshake. See [DEPLOY.md](DEPLOY.md).
-
----
-
-## Development
-
-```bash
-npm install
-node test.js          # unit tests
-node hive-edge-test.js # adversarial / edge-case live tests
-```
-
-Other live suites: `hive-secure-test.js`, `hive-scope-test.js`, `hive-auth-test.js`,
-`hive-readonly-test.js`, `hive-resume-test.js`, `hive-control-test.js`,
-`hive-durable-revoke-test.js`, `hive-relay-robust-test.js`.
-
-The extension source is in [`extension/`](extension/).
-
----
-
-## License
-
-MIT.
+<h1>Hivecode</h1>
+
+**Oversight and control for your AI coding agents.**
+
+Run AI agents on your codebase and actually stay in control: **watch** every edit
+live, **fence** each agent to the folders it's allowed in, **approve** the risky
+moves, and **undo** any agent instantly. No git push/pull. Open source.
+
+[**Install for VS Code**](https://marketplace.visualstudio.com/items?itemName=hivecode.hivecode)
+· [**Website**](https://livecode-xoss.onrender.com)
+· [Latest .vsix](https://github.com/GSK7024/livecode/releases)
+
+---
+
+## Why
+
+You can't trust an AI agent blindly. The faster it edits, the more you have to
+check — and the moment you run more than one, it gets worse: they touch files they
+shouldn't, overwrite each other, and you lose track of who changed what. Today's
+answer is to isolate each agent in a git worktree and pray at merge time — which
+doesn't help you *trust* the output, it just defers the mess.
+
+Hivecode adds the missing layer: **oversight and control.**
+
+- **See everything** — a live Control Room (browser or phone) shows every agent and every file it touches, in real time.
+- **Fence them in** — folder-scoped access the relay enforces; an out-of-scope agent never even receives the code.
+- **Approve what matters** — gate risky work so nothing lands without your OK.
+- **Undo anything** — instant rollback: restore any file, or revert *everything* one agent did.
+
+It's **agent-neutral**: Claude Code, Cursor, Windsurf, or your own bot over MCP. No
+git push/pull — edits sync in about a second.
+
+---
+
+## Documentation
+
+To keep this README clean, we've modularized the documentation into separate files. Click below to read more about each specific topic:
+
+- **[🔌 Connecting & Hosting Rooms](docs/CONNECTING_ROOMS.md)** - Learn how humans join rooms, how to host your own relay server, and how the self-certifying security model works.
+- **[🤖 AI Agent Manual](docs/AI_AGENT_MANUAL.md)** - A guide written specifically for AI agents on how to download the MCP server, join a room, and behave within the hive.
+- **[🏛️ Hivecode Architecture](docs/HIVECODE_EXPLAINED.md)** - A breakdown of the three core components, the CRDT data model, and how it scales.
+- **[🧠 ICR (Intent-Centric Resolution)](docs/ICR_EXPLAINED.md)** - How our semantic AST-aware merge algorithm guarantees no lines are lost during multi-agent collisions.
+- **[🔐 DCO (Deterministic Context Override)](docs/DCO_EXPLAINED.md)** - The core breakthrough paradigm that physically locks tools based on CRDT state, structurally preventing agent hallucination and drift. Includes our End-to-End Test Report.
+- **[🔗 The Substrate](docs/SUBSTRATE.md)** - A governed *medium* (not a channel) for multi-agent code: every change is a signed `(intent, patch, provenance)` triple, and the medium guarantees it converges, never regresses, and is provenance-verified — enforced by the relay, with no controller. Runnable + testable in one command.
+
+---
+
+## Development
+
+```bash
+npm install
+node test.js          # unit tests
+node hive-edge-test.js # adversarial / edge-case live tests
+
+npm run test:substrate:all   # the substrate: 4 suites (core + live + enforcement + content authority)
+```
+
+Other live suites: `hive-secure-test.js`, `hive-scope-test.js`, `hive-auth-test.js`,
+`hive-readonly-test.js`, `hive-resume-test.js`, `hive-control-test.js`,
+`hive-durable-revoke-test.js`, `hive-relay-robust-test.js`.
+
+The extension source is in [`extension/`](extension/).
+
+---
+
+## License
+
+MIT.

package/hive-mcp.js

@@ -25,6 +25,13 @@ import crypto from 'crypto'
 import { Server } from '@modelcontextprotocol/sdk/server/index.js'
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js'
+// Substrate defaults for MCP agents: signed provenance + the silent-fork gate are ON
+// unless explicitly disabled. Agents register this server with arbitrary (often empty)
+// env, so relying on per-registration env vars left rooms in mixed signed/unsigned mode —
+// which is exactly the condition that disabled fork detection in live testing. sync.js
+// reads these when startSync() runs (not at import), so setting them here covers every join.
+if (!process.env.HIVE_PROVENANCE) process.env.HIVE_PROVENANCE = 'on'
+if (!process.env.HIVE_FORK_GATE) process.env.HIVE_FORK_GATE = 'on'
 import { startSync, parseLink } from './sync.js'
 
 const DEFAULT_RELAY = process.env.HIVE_RELAY || 'wss://livecode-xoss.onrender.com'
@@ -42,6 +49,21 @@ function resolveRoom(link, dir) {
   return { relay: DEFAULT_RELAY, room: 'room-' + crypto.randomBytes(13).toString('base64url'), token: '', mode: 'HOSTED (new room)' }
 }
 
+// Session persistence: keyed to this process's cwd, so each agent runtime (which starts
+// its own MCP process from its own directory) resumes only its own identity. Lets the
+// session survive MCP host restarts, which otherwise silently drop the agent from the room.
+const SESSION_FILE = path.join(process.cwd(), '.hive-mcp-session.json')
+function persistSession({ dir, name, owner }) {
+  try { fs.writeFileSync(SESSION_FILE, JSON.stringify({ dir, name, owner })) } catch { /* best-effort */ }
+}
+async function tryResumeSession() {
+  try {
+    if (!fs.existsSync(SESSION_FILE)) return
+    const s = JSON.parse(fs.readFileSync(SESSION_FILE, 'utf8'))
+    if (s && s.dir && s.name && fs.existsSync(path.join(path.resolve(s.dir), '.hive.json'))) await joinRoom(s)
+  } catch { /* resume is best-effort; the agent can always hive_join explicitly */ }
+}
+
 async function joinRoom({ link = '', dir = './workspace', name = `agent-${crypto.randomBytes(2).toString('hex')}`, owner = '', token = '' }) {
   if (session) { try { session.hive.stop() } catch {} ; session = null }
   const ROOT = path.resolve(dir)
@@ -54,6 +76,7 @@ async function joinRoom({ link = '', dir = './workspace', name = `agent-${crypto
   fs.writeFileSync(path.join(ROOT, '.hive.json'), JSON.stringify({ relay, room, ...(useToken ? { token: useToken } : {}) }, null, 2))
   const hive = startSync({ relay, room, dir, name, kind: 'ai', owner, token: useToken, log: () => {} })
   session = { hive, room, relay, dir, name }
+  persistSession({ dir, name, owner }) // survive MCP host restarts (see tryResumeSession)
   // wait for the first sync so members/board/rules are ready
   await new Promise((resolve) => {
     let done = false
@@ -61,10 +84,24 @@ async function joinRoom({ link = '', dir = './workspace', name = `agent-${crypto
     hive.provider.on('sync', (s) => s && finish())
     setTimeout(finish, 8000) // don't hang if the relay is cold
   })
-  hive.say(`${name} joined and is ready to work.`)
-  const rules = (() => { try { return fs.readFileSync(path.join(ROOT, 'HIVE_RULES.md'), 'utf8') } catch { return '(rules not yet written)' } })()
   const others = hive.members().filter((m) => m.name !== name).map((m) => `${m.name}(${m.kind})`)
-  return `${mode}\nroom: ${room}\nrelay: ${relay}\nfolder: ${ROOT}\nothers here: ${others.join(', ') || 'none yet'}\ninvite link: ${relay}|${room}\n\n--- FOLLOW THESE RULES ---\n${rules}`
+  
+  // Event-Driven Wakeups: notify the MCP client the millisecond the DCO state changes
+  hive.doc.getMap('swarm_state').observe(() => {
+    try {
+      server.notification({ method: 'notifications/hive_state_changed', params: { state: hive.getState() } })
+    } catch (e) {
+      // client might not support notifications, swallow error
+    }
+  })
+  
+  // The sync engine writes HIVE_RULES.md into the folder on first sync — return it inline
+  // so the agent gets the rules with its join. (Fixes a ReferenceError: `rules` was never
+  // defined, which made every hive_join return "error: rules is not defined".)
+  let rulesText = ''
+  try { rulesText = fs.readFileSync(path.join(ROOT, 'HIVE_RULES.md'), 'utf8') } catch {}
+  if (!rulesText) rulesText = 'Read HIVE_RULES.md in this folder. In short: read chat + board before editing; CLAIM a file with hive_claim before you edit it and hive_release when done; announce intent with hive_say; prefer small patches; act only on accepted tasks; resolve <<<<<<< conflict markers rather than blindly overwriting.'
+  return `${mode}\nroom: ${room}\nrelay: ${relay}\nfolder: ${ROOT}\nothers here: ${others.join(', ') || 'none yet'}\ninvite link: ${relay}|${room}\n\n--- FOLLOW THESE RULES ---\n${rulesText}`
 }
 
 function requireSession() { if (!session) throw new Error('not in a room — call hive_join first'); return session }
@@ -151,19 +188,35 @@ const TOOLS = [
   { name: 'hive_members', description: 'List who is currently in the room (humans and AI agents).', inputSchema: { type: 'object', properties: {} } },
   { name: 'hive_status', description: 'Show the current session (room, relay, folder, name).', inputSchema: { type: 'object', properties: {} } },
   { name: 'hive_leave', description: 'Leave the room and stop syncing.', inputSchema: { type: 'object', properties: {} } },
+  { name: 'hive_set_state', description: 'PM ONLY: Set a global project state flag (e.g. key="contract", val="READY"). This physically unblocks/blocks other agents. WARNING: ONLY use short enum values. Do NOT use this to store paragraphs of text or code, as it will bloat the context window. Use files for text.', inputSchema: { type: 'object', properties: { key: { type: 'string' }, val: { type: 'string' } }, required: ['key', 'val'] } },
+  { name: 'hive_read_state', description: 'Read the global project state flags.', inputSchema: { type: 'object', properties: {} } },
+  { name: 'hive_set_schema', description: 'PM ONLY: Define strict JSON schema validation for a global state key to prevent agents from hallucinating values (e.g. key="contract", rules={"enum": ["PLANNING", "READY", "APPROVED"]}).', inputSchema: { type: 'object', properties: { key: { type: 'string' }, rules: { type: 'object' } }, required: ['key', 'rules'] } },
 ]
 
-const server = new Server({ name: 'hivecode', version: '0.1.0' }, { capabilities: { tools: {} } })
+function enforceDcoLock() {
+  const state = requireSession().hive.getState()
+  const name = requireSession().name
+  if (state[`${name}_status`] === 'LOCKED' || state[`${name}_locked`] === 'true') {
+    throw new Error(`[DCO Enforced] You are locked by the global state machine. Tool execution denied. Block on hive_wait until your status changes.`)
+  }
+}
+
+const server = new Server({ name: 'hivecode', version: '0.8.0' }, { capabilities: { tools: {} } })
 server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }))
 server.setRequestHandler(CallToolRequestSchema, async (req) => {
   const { name, arguments: args = {} } = req.params
   try {
+    // AUTO-RESUME: the MCP host may restart this server process at any time, which
+    // wipes the in-memory session and silently kicks the agent out of its room. If a
+    // persisted session exists for this cwd, transparently rejoin before any tool runs —
+    // the agent (and its human) never see a "not in a room" flake again.
+    if (!session && name !== 'hive_join' && name !== 'hive_leave') await tryResumeSession()
     switch (name) {
       case 'hive_join': return text(await joinRoom(args))
       case 'hive_say': { requireSession().hive.say(String(args.text || '')); return text(`sent: ${args.text}`) }
       case 'hive_read_chat': { const n = args.limit || 30; const msgs = chatArray().slice(-n).map((m) => `${m.at} ${m.by}(${m.kind}): ${m.text}`); return text(msgs.join('\n') || '(no messages yet)') }
       case 'hive_read_board': { const b = boardMap(); return text(b.length ? b.map((e) => `${e.at} ${e.by} rewrote ${e.file} (${e.churn}) — touched: ${(e.symbols || []).join(', ')}`).join('\n') : '(no rewrites logged)') }
-      case 'hive_assign': { const id = requireSession().hive.assign(String(args.to || ''), String(args.text || '')); return id ? text(`assigned task ${id} to ${args.to} (pending approval if they have an owner)`) : err('need to and text') }
+      case 'hive_assign': { enforceDcoLock(); const id = requireSession().hive.assign(String(args.to || ''), String(args.text || '')); return id ? text(`assigned task ${id} to ${args.to} (pending approval if they have an owner)`) : err('need to and text') }
       case 'hive_read_tasks': {
         const all = taskList(); const me = requireSession().name
         const mine = all.filter((t) => t.to === me)
@@ -173,6 +226,9 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
       case 'hive_wait': {
         const ms = Math.min(Math.max(Number(args.timeoutSeconds) || 60, 1), 300) * 1000
         const r = await waitForWork(ms)
+        const globalState = requireSession().hive.getState()
+        const stateStr = Object.keys(globalState).length ? `\n[GLOBAL PROJECT STATE]\n${JSON.stringify(globalState, null, 2)}\n` : ''
+        
         if (r && r.paused) {
           if (r.mentioned) {
             const parts = []
@@ -180,19 +236,23 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
             if (r.tasks && r.tasks.length) parts.push(`📌 Directed task(s):\n${r.tasks.map(fmtTask).join('\n')}`)
             return text(`⏸ You are PAUSED, but were directly addressed. Handle ONLY this, then call hive_wait again (you stay paused until a human resumes you — don't pick up other queued work):\n\n${parts.join('\n\n')}`)
           }
-          return text('⏸ You are PAUSED by mission control. Stop new work and wait. You will be woken if someone @mentions you or assigns you a task; otherwise just call hive_wait again.')
+          return text(`⏸ You are PAUSED by mission control. Stop new work and wait. You will be woken if someone @mentions you or assigns you a task; otherwise just call hive_wait again.${stateStr}`)
         }
-        if (!r) return text('(nothing yet — no approved work or new messages in the wait window. Call hive_wait again to keep waiting.)')
+        if (!r) return text(`(nothing yet — no approved work or new messages in the wait window. Call hive_wait again to keep waiting.)${stateStr}`)
         const parts = []
         if (r.resumed) parts.push('▶ You were RESUMED by mission control — continue.')
         if (r.tasks.length) parts.push(`APPROVED WORK — do these now, then hive_complete each:\n${r.tasks.map(fmtTask).join('\n')}`)
         if (r.newChat.length) parts.push(`NEW MESSAGES:\n${r.newChat.map((m) => `${m.at} ${m.by}(${m.kind}): ${m.text}`).join('\n')}`)
-        return text(parts.join('\n\n') || '(resumed — no queued work yet. Call hive_wait again.)')
+        return text(`${stateStr}\n` + (parts.join('\n\n') || '(resumed — no queued work yet. Call hive_wait again.)'))
       }
+      case 'hive_set_state': { requireSession().hive.setState(String(args.key), String(args.val)); return text(`Set global state [${args.key}] to [${args.val}]`) }
+      case 'hive_read_state': { return text(requireSession().hive.getState()) }
+      case 'hive_set_schema': { requireSession().hive.setSchema(String(args.key), args.rules); return text(`Set schema validation for [${args.key}]`) }
       case 'hive_approve': { const r = requireSession().hive.decide(String(args.id), true); return r.ok ? text(`approved ${args.id}`) : err(r.error) }
       case 'hive_deny': { const r = requireSession().hive.decide(String(args.id), false); return r.ok ? text(`denied ${args.id}`) : err(r.error) }
-      case 'hive_complete': { const r = requireSession().hive.complete(String(args.id), String(args.note || '')); return r.ok ? text(`completed ${args.id}`) : err(r.error) }
+      case 'hive_complete': { enforceDcoLock(); const r = requireSession().hive.complete(String(args.id), String(args.note || '')); return r.ok ? text(`completed ${args.id}`) : err(r.error) }
       case 'hive_claim': {
+        enforceDcoLock();
         const region = String(args.region || ''); if (!region) return err('need a region (file path)')
         const got = requireSession().hive.claim(region, String(args.intent || 'edit'))
         if (got) return text(`claimed ${region} — it's yours. Edit it, then call hive_release.`)
@@ -203,7 +263,7 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
       case 'hive_claims': { const b = requireSession().hive.claimsBoard(); return text(b.length ? b.map((c) => `${c.region} — ${c.by}${c.intent ? ` (${c.intent})` : ''}`).join('\n') : '(nothing claimed right now — all open)') }
       case 'hive_members': { const now = Date.now(); return text(requireSession().hive.members().map((m) => `${m.name} (${m.kind})${m.editing && now - m.editing.at < 15000 ? ` — editing ${m.editing.file}` : ''}`).join('\n') || '(none)') }
       case 'hive_status': { const s = requireSession(); return text({ room: s.room, relay: s.relay, dir: s.dir, name: s.name }) }
-      case 'hive_leave': { requireSession().hive.stop(); session = null; return text('left the room') }
+      case 'hive_leave': { requireSession().hive.stop(); session = null; try { fs.rmSync(SESSION_FILE) } catch {}; return text('left the room') }
       default: return err(`unknown tool: ${name}`)
     }
   } catch (e) { return err(`error: ${e.message}`) }

package/icr.js

@@ -26,9 +26,14 @@
 // providers for every language behind this same interface.
 
 import { javascript } from './lang-js.js'
+import { braceLanguages } from './lang-brace.js'
+import { python } from './lang-python.js'
 
 // --- language registry ----------------------------------------------------------
-const LANGUAGES = [javascript]
+// JavaScript (acorn, full intent layer) first; then structural providers for the
+// C-family (TypeScript, Go, Rust, Java, C/C++, C#, Swift, Kotlin, …) and Python.
+// These cover disjoint extensions, so order only matters on clashes (none today).
+const LANGUAGES = [javascript, ...braceLanguages, python]
 
 // Register an additional language provider. Must expose the provider contract:
 // { id, exts:[...], parses, units, declaredNames, usedIdentifiers, declBody,

package/lang-brace.js

@@ -0,0 +1,174 @@
+// Brace-family language provider for ICR — a dependency-free, language-agnostic
+// structural splitter for C-style languages (TypeScript, Go, Rust, Java, C/C++,
+// C#, Swift, Kotlin, Scala, PHP, Dart, …). It implements the ICR provider contract
+// { id, exts, parses, units, declaredNames, splitUnit, parsesUnit } so the SAME
+// merge engine in icr.js merges these languages by structure — different top-level
+// declarations merge cleanly, the same declaration edited two ways is a named
+// conflict, and edits to different members inside one class/function merge via the
+// engine's finer-grained inner merge (splitUnit).
+//
+// It is a heuristic scanner, not a full parser: it tracks strings, line/block
+// comments, and bracket depth to find top-level declarations and their byte ranges.
+// This gives real structural merge and an approximate parses() (balanced delimiters)
+// — honest and useful today; a tree-sitter provider can later replace it behind the
+// same interface with zero engine changes.
+
+const LINE = ['//']
+const OPEN = { '{': '}', '(': ')', '[': ']' }
+const CLOSE = { '}': '{', ')': '(', ']': '[' }
+
+// Walk `src` once. `at(i)` returns the index just past a string or comment starting
+// at i, or -1 if none starts there — so callers can skip over them uniformly.
+function scannerAt(src, strings) {
+  const n = src.length
+  return function at(i) {
+    if (src[i] === '/' && src[i + 1] === '*') { let j = i + 2; while (j < n && !(src[j] === '*' && src[j + 1] === '/')) j++; return Math.min(n, j + 2) }
+    for (const lc of LINE) if (src.startsWith(lc, i)) { let j = i + lc.length; while (j < n && src[j] !== '\n') j++; return j }
+    if (strings.includes(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 } j++ } return j }
+    return -1
+  }
+}
+
+const isWS = (c) => c === ' ' || c === '\t' || c === '\r' || c === '\n'
+
+// Extract top-level units [{start,end}] from src[from..to]. A unit is a maximal
+// declaration/statement at bracket depth 0: either a block (signature + balanced
+// {…}) or a statement ending at ';' or end-of-line.
+function topUnits(src, strings, from = 0, to = src.length) {
+  const at = scannerAt(src, strings)
+  const units = []
+  let i = from
+  while (i < to) {
+    while (i < to && isWS(src[i])) i++
+    if (i >= to) break
+    // A standalone comment before a declaration belongs to the GAP (kept verbatim by
+    // the engine's splice), so skip it without starting a unit.
+    if ((src[i] === '/' && (src[i + 1] === '/' || src[i + 1] === '*'))) { const s = at(i); if (s > i) { i = s; continue } }
+    const start = i
+    let depth = 0, sawBrace = false
+    while (i < to) {
+      const s = at(i)
+      if (s > i) { i = s; continue } // skip string / comment
+      const c = src[i]
+      if (OPEN[c]) { if (c === '{') sawBrace = true; depth++; i++; continue }
+      if (CLOSE[c]) { depth--; i++; if (depth <= 0 && sawBrace) { while (i < to && (src[i] === ' ' || src[i] === '\t')) i++; if (src[i] === ';') i++; break } continue }
+      if (depth === 0) {
+        if (c === ';') { i++; break }
+        if (c === '\n' && !sawBrace) break
+      }
+      i++
+    }
+    units.push({ start, end: i })
+  }
+  return units
+}
+
+const DECL = /\b(function|func|fn|def|fun|class|interface|struct|enum|trait|impl|type|namespace|module|package|object|record|protocol|actor|extension)\s+([A-Za-z_$][\w$]*)/
+const VARD = /\b(const|let|var|val|static|final)\s+([A-Za-z_$][\w$]*)/
+// Method/function signature, including TYPE-FIRST forms (`int a()`, `public static
+// void main(String[] a)`, `std::string name()`): optional decorators + any number of
+// modifiers + an optional return-type token, then NAME(args){. The captured name is
+// the identifier directly before `(`.
+const METH = /^(?:@[\w.()]+\s+)*(?:(?:public|private|protected|internal|static|async|final|override|open|pub|suspend|inline|virtual|export|default|abstract|sealed|unsafe|extern|synchronized|native|constexpr)\s+)*(?:(?:function|fn|func|fun)\s+)?(?:[A-Za-z_$][\w$<>\[\].,:&*\s]*?\s+)?([A-Za-z_$][\w$]*)\s*(?:<[^>]*>)?\s*\([^;{]*\)\s*(?:->[^{]+|:[^={]+)?\s*\{/
+// control-flow headers also look like `name (…) {` — never key them as methods
+const CTRL = new Set(['if', 'for', 'while', 'switch', 'catch', 'do', 'else', 'try', 'return', 'new', 'throw', 'match', 'select', 'when', 'until', 'lock', 'using', 'foreach', 'with'])
+
+function keyOf(text) {
+  const head = text.replace(/^\s+/, '')
+  let m = head.match(DECL); if (m) return m[1] + ':' + m[2]
+  m = head.match(METH); if (m && !CTRL.has(m[1])) return 'method:' + m[1]
+  m = head.match(VARD); if (m) return 'var:' + m[2]
+  return 'stmt:' + head.split('\n')[0].trim().replace(/\s+/g, ' ')
+}
+
+// De-duplicate keys deterministically (repeated statements / same-named units) so the
+// engine's keyed merge never silently drops one. Order is stable → convergent.
+function keyedUnits(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
+}
+
+// Approximate parse check: delimiters balanced and no unterminated string/comment,
+// ignoring the contents of strings and comments.
+function balanced(src, strings) {
+  const at = scannerAt(src, strings)
+  const stack = []
+  let i = 0
+  while (i < src.length) {
+    const s = at(i)
+    if (s > i) { if (s > src.length) return false; i = s; continue }
+    const c = src[i]
+    if (OPEN[c]) stack.push(c)
+    else if (CLOSE[c]) { if (stack.pop() !== CLOSE[c]) return false }
+    i++
+  }
+  return stack.length === 0
+}
+
+export function makeBraceLanguage({ id, exts, strings = ['"', "'", '`'] }) {
+  const provider = {
+    id,
+    exts,
+    parses: (src) => balanced(String(src == null ? '' : src), strings),
+    units: (src) => keyedUnits(topUnits(String(src), strings), String(src)),
+    declaredNames: (src) => {
+      const names = new Set()
+      for (const u of keyedUnits(topUnits(String(src), strings), String(src))) {
+        const m = u.key.match(/^(?:[a-z]+):([A-Za-z_$][\w$]*)/)
+        if (m && !u.key.startsWith('stmt:')) names.add(m[1])
+      }
+      return names
+    },
+    parsesUnit: (src) => balanced(String(src), strings),
+    // Finer granularity: descend one level into a block declaration so two agents
+    // editing DIFFERENT members of the same class/function merge instead of clashing.
+    splitUnit: (text) => {
+      const src = String(text)
+      // Only descend into NAMED containers (class/struct/impl/…), whose members are
+      // keyed by name — so editing different members merges. A function/method body is
+      // just statements (no stable keys); descending there would falsely merge two
+      // edits to the same code, so we DON'T — the whole unit becomes a clean conflict.
+      if (!/\b(class|interface|struct|enum|trait|impl|namespace|module|object|record|extension|protocol|actor)\b/.test(src.split('{')[0]))
+        return null
+      const at = scannerAt(src, strings)
+      let i = 0, open = -1
+      while (i < src.length) { const s = at(i); if (s > i) { i = s; continue } if (src[i] === '{') { open = i; break } i++ }
+      if (open < 0) return null
+      // find matching close
+      let depth = 0, j = open, close = -1
+      while (j < src.length) { const s = at(j); if (s > j) { j = s; continue } const c = src[j]; if (c === '{') depth++; else if (c === '}') { depth--; if (depth === 0) { close = j; break } } j++ }
+      if (close < 0) return null
+      const sig = src.slice(0, open)
+      const body = src.slice(open + 1, close)
+      const inner = keyedUnits(topUnits(body, strings), body)
+      // re-base inner ranges into `body` coordinates are already correct (topUnits used body)
+      return { sig, open: '{', close: src.slice(close), body, units: inner, join: '' }
+    },
+  }
+  return provider
+}
+
+// Ready-made providers covering the common C-family languages. One provider can claim
+// many extensions; comment/string syntax defaults fit the whole family (edge cases like
+// Rust raw strings / lifetimes are tolerated — worst case a unit is merged coarsely).
+export const braceLanguages = [
+  makeBraceLanguage({ id: 'ts', exts: ['.ts', '.tsx', '.mts', '.cts'] }),
+  makeBraceLanguage({ id: 'jsx', exts: ['.jsx'] }),
+  makeBraceLanguage({ id: 'go', exts: ['.go'], strings: ['"', '`'] }),
+  makeBraceLanguage({ id: 'rust', exts: ['.rs'] }),
+  makeBraceLanguage({ id: 'java', exts: ['.java'] }),
+  makeBraceLanguage({ id: 'c', exts: ['.c', '.h', '.cpp', '.hpp', '.cc', '.hh', '.cxx'] }),
+  makeBraceLanguage({ id: 'csharp', exts: ['.cs'] }),
+  makeBraceLanguage({ id: 'swift', exts: ['.swift'] }),
+  makeBraceLanguage({ id: 'kotlin', exts: ['.kt', '.kts'] }),
+  makeBraceLanguage({ id: 'scala', exts: ['.scala'] }),
+  makeBraceLanguage({ id: 'php', exts: ['.php'] }),
+  makeBraceLanguage({ id: 'dart', exts: ['.dart'] }),
+]