braid-text 0.5.3 → 0.5.6

package/server.js

@@ -7,6 +7,19 @@ let Y = null
 try { Y = require('yjs') } catch(e) {}
 
 
+var all_subscriptions = new Set()
+
+// Converts this to a forced serialized function, that is only called one at a
+// time, and in order.  Even if the inner `fun` is async, it will guarantee
+// that the prior one is always finished before the next one is called.
+//
+// We use this to guarantee that updates are all sent in order, with the prior
+// one sent before the next one begins to send.
+function one_at_a_time(fun) {
+    var queue = Promise.resolve()
+    return (message) => queue = queue.then(() => fun(message))
+}
+
 function create_braid_text() {
     let braid_text = {
         verbose: false,
@@ -14,6 +27,7 @@ function create_braid_text() {
         length_cache_size: 10,
         meta_file_save_period_ms: 1000,
         debug_sync_checks: false,
+        simpletonSetTimeout: setTimeout,   // Can be customized for fuzz testing
         cache: {}
     }
 
@@ -22,35 +36,39 @@ function create_braid_text() {
         return Y
     }
 
+    braid_text.end_all_subscriptions = function() {
+        var subs = [...all_subscriptions]
+        for (var res of subs) res.end()
+    }
+
     let waiting_puts = 0
 
     let max_encoded_key_size = 240
 
-    braid_text.sync = async (a, b, options = {}) => {
+    // Bidirectional sync between a local resource and a remote server.
+    // Keeps them in sync by forwarding DT updates in both directions.
+    // Reconnects automatically on disconnect.
+    braid_text.sync = async (local_key, remote_url, options = {}) => {
         if (!options.merge_type) options.merge_type = 'dt'
 
-        // Support for same-type params removed for now,
-        // since it is unused, unoptimized,
-        // and not as well battle tested
-        if ((a instanceof URL) === (b instanceof URL))
-            throw new Error(`one parameter should be local string key, and the other a remote URL object`)
+        // ── Setup: identify local vs remote, prepare headers ──
 
-        // make a=local and b=remote (swap if not)
-        if (a instanceof URL) { let swap = a; a = b; b = swap }
+        if ((local_key instanceof URL) === (remote_url instanceof URL))
+            throw new Error(`one parameter should be local string key, and the other a remote URL object`)
 
-        // DEBUGGING HACK ID: L04LPFHQ1M -- INVESTIGATING DISCONNECTS
-        options.do_investigating_disconnects_log_L04LPFHQ1M?.(a, 'braid-text sync start')
+        // Normalize so local_key is the string, remote_url is the URL
+        if (local_key instanceof URL) { var swap = local_key; local_key = remote_url; remote_url = swap }
 
-        // Extract content type for proper Accept (GET) vs Content-Type (PUT) usage
+        // Split caller's headers into GET headers (Accept) vs PUT headers (Content-Type)
         var content_type
         var get_headers = {}
         var put_headers = {}
         if (options.headers) {
             for (var [k, v] of Object.entries(options.headers)) {
                 var lk = k.toLowerCase()
-                if (lk === 'accept' || lk === 'content-type') {
+                if (lk === 'accept' || lk === 'content-type')
                     content_type = v
-                } else {
+                else {
                     get_headers[k] = v
                     put_headers[k] = v
                 }
@@ -61,7 +79,13 @@ function create_braid_text() {
             put_headers['Content-Type'] = content_type
         }
 
-        var resource = (typeof a == 'string') ? await get_resource(a) : a
+        // ── Load the local resource and initialize the fork point ──
+        //
+        // The fork point is the most recent set of versions that both local
+        // and remote are known to share.  It's persisted in resource meta
+        // so reconnections don't start from scratch.
+
+        var resource = (typeof local_key == 'string') ? await get_resource(local_key) : local_key
         await ensure_dt_exists(resource)
 
         if (!resource.meta.fork_point && options.fork_point_hint) {
@@ -69,19 +93,19 @@ function create_braid_text() {
             resource.save_meta()
         }
 
+        // Given a version frontier, incorporate a new update (version + parents)
+        // to compute the new frontier.  Walks the DT version DAG if needed.
         function extend_frontier(frontier, version, parents) {
-            // special case:
-            // if current frontier has all parents,
-            //    then we can just remove those
-            //    and add version
             var frontier_set = new Set(frontier)
+            // Fast path: if the frontier contains all the update's parents,
+            // just swap them out for the new version
             if (parents.length &&
                 parents.every(p => frontier_set.has(p))) {
                 parents.forEach(p => frontier_set.delete(p))
                 for (var event of version) frontier_set.add(event)
                 frontier = [...frontier_set.values()]
             } else {
-                // full-proof approach..
+                // Slow path: walk the full DT history to compute the frontier
                 var looking_for = frontier_set
                 for (var event of version) looking_for.add(event)
 
@@ -104,70 +128,54 @@ function create_braid_text() {
             return frontier.sort()
         }
 
-        options.signal?.addEventListener('abort', () => {
-            // DEBUGGING HACK ID: L04LPFHQ1M -- INVESTIGATING DISCONNECTS
-            options.do_investigating_disconnects_log_L04LPFHQ1M?.(a, 'braid-text sync abort')
-        })
+        function extend_fork_point(update) {
+            resource.meta.fork_point =
+                extend_frontier(resource.meta.fork_point,
+                                update.version, update.parents)
+            resource.save_meta()
+        }
 
-        var local_first_put
-        var local_first_put_promise = new Promise(done => local_first_put = done)
+        // ── Reconnection wrapper ──
+        //
+        // Everything below runs inside reconnector(), which retries
+        // the entire connection on failure with backoff.
 
         reconnector(options.signal, (_e, count) => {
-            // DEBUGGING HACK ID: L04LPFHQ1M -- INVESTIGATING DISCONNECTS
-            options.do_investigating_disconnects_log_L04LPFHQ1M?.(a, 'braid-text handle_error: ' + _e)
-
             var delay = Math.min(count, 3) * 1000
-            console.log(`disconnected from ${b}, retrying in ${delay}ms`)
+            console.log(`disconnected from ${remote_url}, retrying in ${delay}ms`)
             return delay
         }, async (signal, handle_error) => {
-            // DEBUGGING HACK ID: L04LPFHQ1M -- INVESTIGATING DISCONNECTS
-            options.do_investigating_disconnects_log_L04LPFHQ1M?.(a, 'braid-text connect before on_pre_connect')
-
             if (options.on_pre_connect) await options.on_pre_connect()
             if (signal.aborted) return
 
-            // DEBUGGING HACK ID: L04LPFHQ1M -- INVESTIGATING DISCONNECTS
-            options.do_investigating_disconnects_log_L04LPFHQ1M?.(a, 'braid-text connect before fork-point stuff')
-
             try {
-                // fork-point
+                // ── Find the fork point ──
+                //
+                // The fork point tells us where to start syncing from.
+                // First check if the remote still has our saved fork point.
+                // If not, binary search through local history to find the
+                // latest version the remote recognizes.
+
                 async function check_version(version) {
-                    var r = await braid_fetch(b.href, {
-                        signal,
-                        method: "HEAD",
-                        version,
-                        headers: get_headers
+                    var r = await braid_fetch(remote_url.href, {
+                        signal, method: 'HEAD', version, headers: get_headers
                     })
                     if (signal.aborted) return
-
-                    if (!r.ok && r.status !== 309 && r.status !== 500)
+                    if (!r.ok && r.status !== 309 && r.status !== 404 && r.status !== 500)
                         throw new Error(`unexpected HEAD status: ${r.status}`)
                     return r.ok
                 }
 
-                function extend_fork_point(update) {
-                    resource.meta.fork_point =
-                        extend_frontier(resource.meta.fork_point,
-                            update.version, update.parents)
-                    resource.save_meta()
-                }
-
-                // see if remote has the fork point
                 if (resource.meta.fork_point &&
                     !(await check_version(resource.meta.fork_point))) {
                     if (signal.aborted) return
-
                     resource.meta.fork_point = null
                     resource.save_meta()
                 }
                 if (signal.aborted) return
 
-                // otherwise let's binary search for new fork point..
                 if (!resource.meta.fork_point) {
-
-                    // DEBUGGING HACK ID: L04LPFHQ1M -- INVESTIGATING DISCONNECTS
-                    options.do_investigating_disconnects_log_L04LPFHQ1M?.(a, 'braid-text fork-point binary search')
-
+                    // Binary search through local DT history
                     var bytes = resource.dt.doc.toBytes()
                     var [_, events, __] = braid_text.dt_parse([...bytes])
                     events = events.map(x => x.join('-'))
@@ -175,121 +183,87 @@ function create_braid_text() {
                     var min = -1
                     var max = events.length
                     while (min + 1 < max) {
-                        var i = Math.floor((min + max)/2)
+                        var i = Math.floor((min + max) / 2)
                         var version = [events[i]]
                         if (await check_version(version)) {
                             if (signal.aborted) return
-
                             min = i
                             resource.meta.fork_point = version
                         } else max = i
                     }
                 }
 
-                // local -> remote (with in_flight queue for concurrency control)
-                var q = []
-                var in_flight = new Map()
-                var max_in_flight = 10
-                var send_pump_lock = 0
-                var temp_acs = new Set()
-                signal.addEventListener('abort', () => {
-                    for (var t of temp_acs) t.abort()
-                })
+                // ── Local → Remote ──
+                //
+                // Subscribe to local changes (history since fork_point,
+                // then live updates) and forward each one to the remote
+                // server via PUT.  Up to 10 PUTs in flight for throughput.
 
-                async function send_out(update) {
-
-                    // DEBUGGING HACK ID: L04LPFHQ1M -- INVESTIGATING DISCONNECTS
-                    options.do_investigating_disconnects_log_L04LPFHQ1M?.(a, 'braid-text send_out')
+                var local_updates = []
+                var in_flight = 0
+                var max_in_flight = 10
 
-                    update.signal = signal
-                    update.dont_retry = true
-                    if (options.peer) update.peer = options.peer
-                    update.headers = put_headers
-                    var x = await braid_text.put(b, update)
+                // PUT a single update to the remote server.
+                // Extends the fork point on success so the next
+                // reconnection starts from where we left off.
+                async function send_to_remote(update) {
+                    var {response} = await braid_text.put(remote_url, {
+                        ...update,
+                        signal,
+                        dont_retry: true,
+                        peer: options.peer,
+                        headers: put_headers,
+                    })
                     if (signal.aborted) return
 
-                    // DEBUGGING HACK ID: L04LPFHQ1M -- INVESTIGATING DISCONNECTS
-                    options.do_investigating_disconnects_log_L04LPFHQ1M?.(a, 'braid-text send_out result: ' + x.ok)
-
-                    if (x.ok) {
-                        local_first_put()
+                    if (response.ok)
                         extend_fork_point(update)
-                    } else if (x.status === 401 || x.status === 403) {
+                    else if (response.status === 401 || response.status === 403)
                         await options.on_unauthorized?.()
-                    } else throw new Error('failed to PUT: ' + x.status)
+                    else
+                        throw new Error('failed to PUT: ' + response.status)
                 }
 
-                async function send_pump() {
-                    send_pump_lock++
-                    if (send_pump_lock > 1) return
-                    try {
-                        if (signal.aborted) return
-                        if (in_flight.size >= max_in_flight) return
-                        if (!q.length) {
-                            // Extend frontier based on in-flight updates
-                            var frontier = resource.meta.fork_point || []
-                            for (var u of in_flight.values())
-                                frontier = extend_frontier(frontier, u.version, u.parents)
-
-                            var temp_ac = new AbortController()
-                            temp_acs.add(temp_ac)
-                            var get_options = {
-                                signal: temp_ac.signal,
-                                parents: frontier,
-                                merge_type: 'dt',
-                                peer: options.peer,
-                                subscribe: u => u.version?.length && q.push(u)
-                            }
-                            await braid_text.get(a, get_options)
-                            await get_options.my_subscribe_chain
+                // Forward pending local updates to the remote,
+                // up to max_in_flight concurrent PUTs.
+                // When each PUT completes, check for more work.
+                function send_local_updates() {
+                    if (signal.aborted) return
+                    while (local_updates.length && in_flight < max_in_flight) {
+                        var update = local_updates.shift()
+                        if (!update.version?.length) continue
+                        in_flight++
+                        send_to_remote(update).then(() => {
                             if (signal.aborted) return
-                            temp_ac.abort()
-                            temp_acs.delete(temp_ac)
-                        }
-                        while (q.length && in_flight.size < max_in_flight) {
-                            let u = q.shift()
-                            if (!u.version?.length) continue
-                            in_flight.set(u.version[0], u)
-                            void (async () => {
-                                try {
-                                    await send_out(u)
-                                    if (signal.aborted) return
-                                    in_flight.delete(u.version[0])
-                                    setTimeout(send_pump, 0)
-                                } catch (e) { handle_error(e) }
-                            })()
-                        }
-                    } finally {
-                        if (send_pump_lock > 1) setTimeout(send_pump, 0)
-                        send_pump_lock = 0
+                            in_flight--
+                            if (local_updates.length) send_local_updates()
+                        }).catch(handle_error)
                     }
                 }
 
-                var a_ops = {
+                braid_text.get(local_key, {
                     signal,
                     merge_type: 'dt',
                     peer: options.peer,
+                    ...resource.meta.fork_point && {parents: resource.meta.fork_point},
                     subscribe: update => {
                         if (signal.aborted) return
                         if (update.version?.length) {
-                            q.push(update)
-                            send_pump()
+                            local_updates.push(update)
+                            send_local_updates()
                         }
                     }
-                }
-                if (resource.meta.fork_point)
-                    a_ops.parents = resource.meta.fork_point
-                braid_text.get(a, a_ops)
+                })
 
-                // remote -> local
-                var remote_res_done
-                var remote_res_promise = new Promise(done => remote_res_done = done)
-                var remote_res = null
+                // ── Remote → Local ──
+                //
+                // Subscribe to remote changes and apply them locally via .put().
+                // Requests DT binary encoding for efficiency.
 
-                // DEBUGGING HACK ID: L04LPFHQ1M -- INVESTIGATING DISCONNECTS
-                options.do_investigating_disconnects_log_L04LPFHQ1M?.(a, 'braid-text before GET/sub')
+                var remote_current_version = null
+                var remote_status = null
 
-                var b_ops = {
+                await braid_text.get(remote_url, {
                     signal,
                     dont_retry: true,
                     headers: { ...get_headers, 'Merge-Type': 'dt', 'accept-encoding': 'updates(dt)' },
@@ -297,33 +271,31 @@ function create_braid_text() {
                     peer: options.peer,
                     heartbeats: 120,
 
-                    // DEBUGGING HACK ID: L04LPFHQ1M -- INVESTIGATING DISCONNECTS
-                    heartbeat_cb: () => {
-                        options.do_investigating_disconnects_log_L04LPFHQ1M?.(a, 'got heartbeat')
+                    on_response: res => {
+                        remote_status = res.status
+                        remote_current_version = res.headers.get('current-version')
+                        options.on_res?.(res)
                     },
 
                     subscribe: async update => {
-
-                        // DEBUGGING HACK ID: L04LPFHQ1M -- INVESTIGATING DISCONNECTS
-                        options.do_investigating_disconnects_log_L04LPFHQ1M?.(a, 'braid-text got update')
-
-                        // Wait for remote_res to be available
-                        await remote_res_promise
                         if (signal.aborted) return
 
-                        // Check if this is a dt-encoded update
                         if (update.extra_headers?.encoding === 'dt') {
-                            var cv = remote_res.headers.get('current-version')
-                            await braid_text.put(a, {
+                            // DT binary: apply directly
+                            await braid_text.put(local_key, {
                                 body: update.body,
                                 transfer_encoding: 'dt',
                                 peer: options.peer
                             })
                             if (signal.aborted) return
-                            if (cv) extend_fork_point({ version: JSON.parse(`[${cv}]`), parents: resource.meta.fork_point || [] })
+                            if (remote_current_version) extend_fork_point({
+                                version: JSON.parse(`[${remote_current_version}]`),
+                                parents: resource.meta.fork_point || []
+                            })
                         } else {
+                            // Text patches: forward as-is
                             if (options.peer) update.peer = options.peer
-                            await braid_text.put(a, update)
+                            await braid_text.put(local_key, update)
                             if (signal.aborted) return
                             if (update.version) extend_fork_point(update)
                         }
@@ -332,33 +304,27 @@ function create_braid_text() {
                         options.on_disconnect?.()
                         handle_error(e)
                     }
-                }
-                // Handle case where remote doesn't exist yet - wait for local to create it
-                remote_res = await braid_text.get(b, b_ops)
+                })
                 if (signal.aborted) return
 
-                // DEBUGGING HACK ID: L04LPFHQ1M -- INVESTIGATING DISCONNECTS
-                options.do_investigating_disconnects_log_L04LPFHQ1M?.(a, 'braid-text after GET/sub: ' + remote_res?.status)
-
-                remote_res_done()
-                if (remote_res === null) {
-                    // Remote doesn't exist yet, wait for local to put something
-                    await local_first_put_promise
-                    return handle_error(new Error('try again'))
+                // If remote returned 404, reconnect with backoff
+                // (the resource might be created later by our local→remote PUTs)
+                if (remote_status === 404) {
+                    return handle_error(new Error('remote returned 404'))
                 }
-                options.on_res?.(remote_res)
-                // on_error will call handle_error when connection drops
             } catch (e) { handle_error(e) }
         })
     }
 
     braid_text.serve = async (req, res, options = {}) => {
         options = {
-            key: req.url.split('?')[0], // Default key
-            put_cb: (key, val, params) => { },  // Default callback when a PUT changes a key
-            ...options                  // Override with all options passed in
+            key: req.url.split('?')[0],
+            put_cb: (key, val, params) => { },
+            ...options
         }
 
+        // ── Setup: prepare the response and load the resource ──
+
         if (braid_text.cors !== false) braid_text.free_cors(res)
 
         function my_end(statusCode, x, statusText, headers) {
@@ -366,60 +332,61 @@ function create_braid_text() {
             res.end(x ?? '')
         }
 
-        let resource = null
+        var resource = null
         try {
             resource = await get_resource(options.key)
 
+            // Add braid protocol support to the req/res objects
             braidify(req, res)
             if (res.is_multiplexer) return
 
-            // Sort version arrays from external sources
             if (req.version) req.version.sort()
             if (req.parents) req.parents.sort()
         } catch (e) {
-            return my_end(500, "The server failed to process this request. The error generated was: " + e)
+            return my_end(500, 'The server failed to process this request. The error generated was: ' + e)
         }
 
-        let peer = req.headers["peer"]
+        // ── Cursors get their own content-type and are handled independently ──
+        if (await handle_cursors(resource, req, res)) return
 
-        // Implement Multiplayer Text Cursors
-        if (await handle_cursors(resource, req, res))
-            return
+        // ── Classify the request ──
 
-        let merge_type = req.headers["merge-type"]
-        if (!merge_type) merge_type = 'simpleton'
-        if (merge_type !== 'simpleton' && merge_type !== 'dt') return my_end(400, `Unknown merge type: ${merge_type}`)
+        var peer = req.headers['peer'],
+            merge_type = req.headers['merge-type'] || 'simpleton'
+        if (merge_type !== 'simpleton' && merge_type !== 'dt' && merge_type !== 'yjs')
+            return my_end(400, `Unknown merge type: ${merge_type}`)
 
-        // set default content type of text/plain
-        if (!res.getHeader('content-type')) res.setHeader('Content-Type', 'text/plain')
+        var is_read  = req.method === 'GET' || req.method === 'HEAD',
+            is_write = req.method === 'PUT' || req.method === 'POST' || req.method === 'PATCH',
+            is_head  = req.method === 'HEAD'
 
-        // no matter what the content type is,
-        // we want to set the charset to utf-8
-        const contentType = res.getHeader('Content-Type')
-        const parsedContentType = contentType.split(';').map(part => part.trim())
-        const charsetParam = parsedContentType.find(part => part.toLowerCase().startsWith('charset='))
-        if (!charsetParam)
-            res.setHeader('Content-Type', `${contentType}; charset=utf-8`)
-        else if (charsetParam.toLowerCase() !== 'charset=utf-8') {
-            // Replace the existing charset with utf-8
-            const updatedContentType = parsedContentType
-                .map(part => (part.toLowerCase().startsWith('charset=') ? 'charset=utf-8' : part))
-                .join('; ');
-            res.setHeader('Content-Type', updatedContentType);
-        }
+        // ── Ensure the response is labeled as utf-8 text ──
 
-        if (req.method == "OPTIONS") return my_end(200)
-
-        if (req.method == "DELETE") {
+        if (!res.getHeader('content-type')) res.setHeader('Content-Type', 'text/plain')
+        var ct = res.getHeader('Content-Type'),
+            ct_parts = ct.split(';').map(p => p.trim())
+        var charset = ct_parts.find(p => p.toLowerCase().startsWith('charset='))
+        if (!charset)
+            res.setHeader('Content-Type', `${ct}; charset=utf-8`)
+        else if (charset.toLowerCase() !== 'charset=utf-8')
+            res.setHeader('Content-Type', ct_parts
+                .map(p => p.toLowerCase().startsWith('charset=') ? 'charset=utf-8' : p)
+                .join('; '))
+
+        // ── Handle simple methods that don't need further processing ──
+
+        if (req.method === 'OPTIONS') return my_end(200)
+        if (req.method === 'DELETE') {
             await braid_text.delete(resource)
             return my_end(200)
         }
 
-        var get_current_version = () => ascii_ify(
-            resource.version.map(x => JSON.stringify(x)).join(", "))
+        var current_version = () => ascii_ify(
+            resource.version.map(x => JSON.stringify(x)).join(', '))
 
-        if (req.method == "GET" || req.method == "HEAD") {
-            // make sure we have the necessary version and parents
+        // ── Read state (with GET or HEAD) ──
+        if (is_read) {
+            // Validate requested versions exist
             var unknowns = []
             for (var event of (req.version || []).concat(req.parents || [])) {
                 var [actor, seq] = decode_version(event)
@@ -427,185 +394,212 @@ function create_braid_text() {
                     unknowns.push(event)
             }
             if (unknowns.length)
-                return my_end(309, '', "Version Unknown Here", {
+                return my_end(309, '', 'Version Unknown Here', {
                     Version: ascii_ify(unknowns.map(e => JSON.stringify(e)).join(', '))
                 })
 
-            if (!req.subscribe) {
-                res.setHeader("Accept-Subscribe", "true")
-
-                // Set headers based on request type
-                // Current-Version: always for dt encoding, or when version/parents present
-                if (req.headers['accept-transfer-encoding'] === 'dt' || req.version || req.parents) {
-                    res.setHeader("Current-Version", get_current_version())
-                }
-
-                // Merge-Type: only when version/parents present
-                if (req.version || req.parents) {
-                    res.setHeader("Merge-Type", merge_type)
-                }
-
-                // special case for HEAD asking for version/parents,
-                // to be faster by not reconstructing body
-                if (req.method === "HEAD" && (req.version || req.parents))
-                    return my_end(200)
-
-                let x = null
+            var has_parents = req.parents && req.parents.length > 0
+            var has_version = req.version && req.version.length > 0
+
+            if (req.subscribe && has_version)
+                return my_end(400, 'Version header is not allowed with Subscribe — use Parents instead')
+
+            var getting = {
+                subscribe: !!req.subscribe,
+                history:   (has_parents && v_eq(req.parents, resource.version)) ? false
+                         : has_parents ? 'since-parents'
+                         : (req.subscribe || req.parents || req.headers['accept-transfer-encoding']) ? 'up-to-version'
+                         : false,
+                transfer_encoding: req.headers['accept-transfer-encoding'],
+            }
+            getting.single_snapshot = !getting.subscribe && !getting.history
+
+            // Response headers
+            if (getting.subscribe && !res.hasHeader('editable'))
+                // BUG: This shouldn't be guarded behind "subscribe" because
+                // clients can also edit text without subscribing to it, just
+                // by doing PUTs and polling to see the updates to the state.
+                //
+                // But this should only be editable if the client can actually
+                // edit it, and so I am guessing that whoever wrote this might
+                // have been actually trying to guard something that happens
+                // to correlate with subscriptions, which is bogus, but needs
+                // to be thought through and fixed.
+                res.setHeader('Editable', 'true')
+            res.setHeader('Current-Version', current_version())
+            res.setHeader('Merge-Type', merge_type)
+            res.setHeader('Accept-Subscribe', 'true')
+
+            // HEAD: headers only, no body needed
+            if (is_head) {
+                // Always include the version of what would be returned
+                if (!getting.history)
+                    res.setHeader('Version', current_version())
+                return my_end(200)
+            }
+
+            if (!getting.subscribe) {
+                // ── One-shot read ──
                 try {
-                    x = await braid_text.get(resource, {
+                    var result = await braid_text.get(resource, {
                         version: req.version,
                         parents: req.parents,
-                        transfer_encoding: req.headers['accept-transfer-encoding']
+                        transfer_encoding: getting.transfer_encoding,
+                        full_response: true,
                     })
                 } catch (e) {
-                    return my_end(500, "The server failed to get something. The error generated was: " + e)
-                }
-
-                if (req.headers['accept-transfer-encoding'] === 'dt') {
-                    res.setHeader("X-Transfer-Encoding", 'dt')
-                    res.setHeader("Content-Length", x.body.length)
-                    return my_end(209, req.method === "HEAD" ? null : x.body, 'Multiresponse')
+                    return my_end(500, 'The server at ' + resource + ' failed: ' + e)
+                }
+
+                if (getting.transfer_encoding === 'dt') {
+                    res.setHeader('X-Transfer-Encoding', 'dt')
+                    res.setHeader('Content-Length', result.body.length)
+                    return my_end(209, result.body, 'Multiresponse')
+                } else if (Array.isArray(result)) {
+                    // Range of history: send as 209 Multiresponse
+                    res.startSubscription()
+                    for (var u of result)
+                        res.sendVersion({
+                            version: [u.version],
+                            parents: u.parents,
+                            patches: [{ unit: u.unit, range: u.range, content: u.content }],
+                        })
+                    return res.end()
                 } else {
-                    res.setHeader("Version", ascii_ify(x.version.map((x) => JSON.stringify(x)).join(", ")))
-                    var buffer = Buffer.from(x.body, "utf8")
-                    res.setHeader("Repr-Digest", get_digest(buffer))
-                    res.setHeader("Content-Length", buffer.length)
-                    return my_end(200, req.method === "HEAD" ? null : buffer)
+                    res.setHeader('Version', ascii_ify(result.version
+                                                       .map(v => JSON.stringify(v))
+                                                       .join(', ')))
+                    var buffer = Buffer.from(result.body, 'utf8')
+                    res.setHeader('Repr-Digest', get_digest(buffer))
+                    res.setHeader('Content-Length', buffer.length)
+                    return my_end(200, buffer)
                 }
             } else {
-                if (!res.hasHeader("editable")) res.setHeader("Editable", "true")
-                res.setHeader("Merge-Type", merge_type)
-                res.setHeader("Current-Version", get_current_version())
-                if (req.method == "HEAD") return my_end(200)
-
-                let options = {
-                    peer,
-                    version: req.version,
-                    parents: req.parents,
-                    merge_type,
-                    accept_encoding:
-                        req.headers['x-accept-encoding'] ??
-                        req.headers['accept-encoding'],
-                    subscribe: update => {
-
-                        // this is a sanity/rhobustness check..
-                        // ..this digest is checked on the client..
-                        if (update.version && v_eq(update.version, resource.version))
-                            update["Repr-Digest"] = get_digest(resource.val)
-
-                        if (update.patches && update.patches.length === 1) {
-                            update.patch = update.patches[0]
-                            delete update.patches
-                        }
-                        res.sendVersion(update)
-                    },
-                    write: (update) => res.write(update)
-                }
-
+                // ── Subscribe ──
+                all_subscriptions.add(res)
+                var aborter = new AbortController()
                 res.startSubscription({
                     onClose: () => {
-                        if (merge_type === "dt") resource.dt.clients.delete(options)
-                        else resource.dt.simpleton_clients.delete(options)
+                        all_subscriptions.delete(res)
+                        aborter.abort()
                     }
                 })
 
                 try {
-                    return await braid_text.get(resource, options)
+                    await braid_text.get(resource, {
+                        peer,
+                        version: req.version,
+                        parents: req.parents,
+                        merge_type,
+                        signal: aborter.signal,
+                        accept_encoding:
+                            req.headers['x-accept-encoding'] ??
+                            req.headers['accept-encoding'],
+                        subscribe: update => {
+                            // Add digest for integrity checking on the client
+                            if (update.version && v_eq(update.version, resource.version))
+                                update['Repr-Digest'] = get_digest(resource.val)
+
+                            // Collapse single-element patches array for HTTP
+                            if (update.patches && update.patches.length === 1) {
+                                update.patch = update.patches[0]
+                                delete update.patches
+                            }
+                            res.sendVersion(update)
+                        },
+                    })
+                    // Ensure headers are sent even if .get() didn't send
+                    // any initial data (e.g. subscribe when already current)
+                    res.flushHeaders()
                 } catch (e) {
-                    return my_end(500, "The server failed to get something. The error generated was: " + e)
+                    return my_end(500, 'The server failed to get something. The error generated was: ' + e)
                 }
+                return
             }
         }
 
-        if (req.method == "PUT" || req.method == "POST" || req.method == "PATCH") {
-            if (waiting_puts >= 100) {
-                console.log(`The server is busy.`)
-                return my_end(503, "The server is busy.")
-            }
+        // ── Write (PUT / POST / PATCH) ──
+        if (is_write) {
+            if (waiting_puts >= 100)
+                return my_end(503, 'The server is busy.')
 
             waiting_puts++
-            if (braid_text.verbose) console.log(`waiting_puts(after++) = ${waiting_puts}`)
-            let done_my_turn = (statusCode, x, statusText, headers) => {
+            var done_my_turn = (statusCode, x, statusText, headers) => {
                 waiting_puts--
-                if (braid_text.verbose) console.log(`waiting_puts(after--) = ${waiting_puts}`)
                 my_end(statusCode, x, statusText, headers)
             }
 
             try {
+                // Parse patches from request body
                 var patches = await req.patches()
-                for (let p of patches) p.content = p.content_text
+                for (var p of patches) p.content = p.content_text
 
-                let body = null
+                var body = null
                 if (patches[0]?.unit === 'everything') {
                     body = patches[0].content
                     patches = null
                 }
 
+                // Wait for parent versions to arrive (if needed)
                 if (req.parents) {
                     await ensure_dt_exists(resource)
                     await wait_for_events(
-                        options.key,
-                        req.parents,
+                        options.key, req.parents,
                         resource.dt.known_versions,
-                        // approximation of memory usage for this update
                         body != null ? body.length :
                             patches.reduce((a, b) => a + b.range.length + b.content.length, 0),
                         options.recv_buffer_max_time,
                         options.recv_buffer_max_space)
 
-                    // make sure we have the necessary parents now
                     var unknowns = []
                     for (var event of req.parents) {
                         var [actor, seq] = decode_version(event)
-                        if (!resource.dt.known_versions[actor]?.has(seq)) unknowns.push(event)
+                        if (!resource.dt.known_versions[actor]?.has(seq))
+                            unknowns.push(event)
                     }
                     if (unknowns.length)
-                        return done_my_turn(309, '', "Version Unknown Here", {
+                        return done_my_turn(309, '', 'Version Unknown Here', {
                             Version: ascii_ify(unknowns.map(e => JSON.stringify(e)).join(', ')),
                             'Retry-After': '1'
                         })
                 }
 
+                // Apply the edit
                 var old_val = resource.val
                 var old_version = resource.version
-                var put_patches = patches?.map(p => ({unit: p.unit,
-                                                      range: p.range,
-                                                      content: p.content})) || null
-                var {change_count} = await braid_text.put(
-                    resource,
-                    { peer, version: req.version, parents: req.parents, patches, body, merge_type }
-                )
+                var put_patches = patches?.map(p => ({
+                    unit: p.unit, range: p.range, content: p.content
+                })) || null
+
+                var {dt: {change_count}} = await braid_text.put(resource, {
+                    peer, version: req.version, parents: req.parents,
+                    patches, body, merge_type
+                })
 
-                // if Repr-Digest is set,
-                // and the request version is also our new current version,
-                // then verify the digest..
+                // Verify Repr-Digest if present
                 if (req.headers['repr-digest'] &&
                     v_eq(req.version, resource.version) &&
-                    req.headers['repr-digest'] !== get_digest(resource.val)) {
-                    console.log(`repr-digest mismatch!`)
-
-                    // we return a special 550 error code,
-                    // which simpleton will pick up on to stop retrying
-                    return done_my_turn(550, "repr-digest mismatch!")
-                }
+                    req.headers['repr-digest'] !== get_digest(resource.val))
+                    return done_my_turn(550, 'repr-digest mismatch!')
 
                 if (req.version?.length)
                     got_event(options.key, req.version[0], change_count)
-            
-                res.setHeader("Version", get_current_version())
 
-                options.put_cb(options.key, resource.val,
-                               {old_val, patches: put_patches,
-                                version: resource.version, parents: old_version})
+                res.setHeader('Version', current_version())
+
+                options.put_cb(options.key, resource.val, {
+                    old_val, patches: put_patches,
+                    version: resource.version, parents: old_version
+                })
             } catch (e) {
                 console.log(`${req.method} ERROR: ${e.stack}`)
-                return done_my_turn(500, "The server failed to apply this version. The error generated was: " + e)
+                return done_my_turn(500, 'The server failed to apply this version. The error generated was: ' + e)
             }
 
             return done_my_turn(200)
         }
 
-        throw new Error("unknown")
+        throw new Error('unknown method: ' + req.method)
     }
 
     braid_text.delete = async (key, options) => {
@@ -628,6 +622,42 @@ function create_braid_text() {
         await resource.delete()
     }
 
+    // Fetch from a remote braid-text server via HTTP
+    async function get_remote(url, options) {
+        if (!options) options = {}
+
+        var params = {
+            signal: options.signal,
+            subscribe: !!options.subscribe,
+            heartbeats: options.heartbeats ?? 120,
+            heartbeat_cb: options.heartbeat_cb
+        }
+        if (!options.dont_retry)
+            params.retry = (res) => res.status !== 404
+
+        for (var x of ['headers', 'parents', 'version', 'peer'])
+            if (options[x] != null) params[x] = options[x]
+
+        var res = await braid_fetch(url.href, params)
+
+        if (options.on_response) options.on_response(res)
+
+        if (res.status === 404) return ''
+
+        if (options.subscribe) {
+            res.subscribe(async update => {
+                // Convert binary to text, except for dt-encoded blobs
+                // which are passed through as-is for .sync() to handle
+                if (update.extra_headers?.encoding !== 'dt') {
+                    update.body = update.body_text
+                    if (update.patches)
+                        for (var p of update.patches) p.content = p.content_text
+                }
+                await options.subscribe(update)
+            }, e => options.on_error?.(e))
+        } else return await res.text()
+    }
+
     braid_text.get = async (key, options) => {
         if (options && options.version) {
             validate_version_array(options.version)
@@ -638,226 +668,198 @@ function create_braid_text() {
             options.parents.sort()
         }
 
-        if (key instanceof URL) {
-            if (!options) options = {}
+        if (key instanceof URL) return await get_remote(key, options)
 
-            var params = {
-                signal: options.signal,
-                subscribe: !!options.subscribe,
-                heartbeats: options.heartbeats ?? 120,
-                heartbeat_cb: options.heartbeat_cb
-            }
-            if (!options.dont_retry) {
-                params.retry = (res) => res.status !== 404
+        if (!options) options = {}
+
+        var resource = (typeof key == 'string') ? await get_resource(key) : key
+        var version = resource.version
+        var merge_type = options.range_unit === 'yjs-text' ? 'yjs'
+            : (options.merge_type || 'simpleton')
+        var has_parents = options.parents && options.parents.length > 0
+        var has_version = options.version && options.version.length > 0
+
+        if (options.subscribe && has_version)
+            throw new Error('version is not allowed with subscribe — use parents instead')
+
+        var getting = {
+            subscribe: !!options.subscribe,
+            // 'since-parents' = range of updates from parents to current
+            // 'up-to-version' = bring client up to current (from scratch)
+            // false = no history needed
+            history:   (has_parents && v_eq(options.parents, version)) ? false
+                     : has_parents ? 'since-parents'
+                     : (options.subscribe || options.parents || options.transfer_encoding) ? 'up-to-version'
+                     : false,
+            transfer_encoding: options.transfer_encoding,
+        }
+        getting.single_snapshot = !getting.subscribe && !getting.history
+
+        // Single snapshot: return the text (optionally at a specific version)
+        if (getting.single_snapshot) {
+            if (has_version) {
+                await ensure_dt_exists(resource)
+                return options.full_response
+                    ? { version: options.version, body: dt_get_string(resource.dt.doc, options.version) }
+                    : dt_get_string(resource.dt.doc, options.version)
             }
-            for (var x of ['headers', 'parents', 'version', 'peer'])
-                if (options[x] != null) params[x] = options[x]
+            return options.full_response ? { version, body: resource.val } : resource.val
+        }
 
-            var res = await braid_fetch(key.href, params)
+        // DT binary encoding: a transport optimization usable by any merge type.
+        // Returns raw DT bytes instead of text.
+        if (getting.history && !getting.subscribe && getting.transfer_encoding === 'dt') {
+            // TODO: move this into the dt/simpleton merge_type cases below
+            await ensure_dt_exists(resource)
+            // If requesting the current version, skip the version lookup
+            // (faster than asking DT about a version we already have)
+            var req_version = options.version
+            if (req_version && v_eq(req_version, version)) req_version = null
+
+            var bytes = null
+            if (req_version || options.parents) {
+                if (req_version) {
+                    var doc = dt_get(resource.dt.doc, req_version)
+                    bytes = doc.toBytes()
+                } else {
+                    bytes = resource.dt.doc.toBytes()
+                    var doc = Doc.fromBytes(bytes)
+                }
+                if (options.parents)
+                    bytes = doc.getPatchSince(
+                        dt_get_local_version(bytes, options.parents))
+                doc.free()
+            } else bytes = resource.dt.doc.toBytes()
+            return { body: bytes }
+        }
 
-            if (res.status === 404) return null
+        switch (merge_type) {
 
-            if (options.subscribe) {
-                res.subscribe(async update => {
-                    // Don't convert to text for initial dt-encoded body (no status)
-                    if (update.status) {
-                        update.body = update.body_text
-                        if (update.patches)
-                            for (var p of update.patches) p.content = p.content_text
-                    }
-                    await options.subscribe(update)
-                }, e => options.on_error?.(e))
+        case 'yjs':
+            await ensure_yjs_exists(resource)
 
-                return res
-            } else return await res.text()
-        }
+            // Send history (for both one-shot and subscribe)
+            if (getting.history) {
+                if (getting.history === 'since-parents')
+                    throw new Error('yjs-text from arbitrary parents not yet implemented')
 
-        if (!options) {
-            // if it doesn't exist already, don't create it in this case
-            if (!braid_text.cache[key]) return null
-            return (await get_resource(key)).val
-        }
+                var yjs_updates = braid_text.from_yjs_binary(
+                    Y.encodeStateAsUpdate(resource.yjs.doc))
 
-        let resource = (typeof key == 'string') ? await get_resource(key) : key
-        var version = resource.version
+                if (!getting.subscribe)
+                    return yjs_updates
 
-        if (!options.subscribe) {
-            // yjs-text range unit: return current text or full history
-            if (options.range_unit === 'yjs-text') {
-                await ensure_yjs_exists(resource)
-                if (options.parents && options.parents.length === 0) {
-                    // Full history: root + initialization patch
-                    var init_patches = [{
-                        unit: 'yjs-text',
-                        range: '(:)',
-                        content: resource.val
-                    }]
-                    return {
-                        version: ['999999999-' + (Math.max(0, [...resource.val].length - 1))],
-                        parents: [],
-                        patches: init_patches
-                    }
-                }
-                return { version, body: resource.val }
+                for (var u of yjs_updates)
+                    options.subscribe(u)
             }
 
-            if (options.transfer_encoding === 'dt') {
-                // optimization: if requesting current version
-                // pretend as if they didn't set a version,
-                // and let it be handled as the default
-                var op_v = options.version
-                if (op_v && v_eq(op_v, version)) op_v = null
-
-                var bytes = null
-                if (op_v || options.parents) {
-                    if (op_v) {
-                        var doc = dt_get(resource.dt.doc, op_v)
-                        bytes = doc.toBytes()
-                    } else {
-                        bytes = resource.dt.doc.toBytes()
-                        var doc = Doc.fromBytes(bytes)
-                    }
-                    if (options.parents) {
-                        bytes = doc.getPatchSince(
-                            dt_get_local_version(bytes, options.parents))
-                    }
-                    doc.free()
-                } else bytes = resource.dt.doc.toBytes()
-                return { body: bytes }
+            if (getting.subscribe) {
+                // Register for live updates
+                // NOTE: This stream mixes two version spaces:
+                //   update.version: DT version space (frontier after this edit)
+                //   update.patches[].version: Yjs version space (clientID-clock)
+                var client = {
+                    merge_type: 'yjs',
+                    peer: options.peer,
+                    send_update: one_at_a_time(options.subscribe),
+                    abort() { resource.yjs.clients.delete(client) },
+                }
+                resource.yjs.clients.add(client)
+                options.signal?.addEventListener('abort', () => client.abort())
             }
+            break
 
-            if (options.version || options.parents) {
-                    await ensure_dt_exists(resource)
-                    return {
-                        version: options.version || options.parents,
-                        body: dt_get_string(resource.dt.doc, options.version || options.parents)
-                    }
-                } else {
-                    return { version, body: resource.val }
-                }
-        } else {
-            // yjs-text subscribe: send full history first, then live updates
-            if (options.range_unit === 'yjs-text') {
-                await ensure_yjs_exists(resource)
+        case 'simpleton':
+            await ensure_dt_exists(resource)
 
-                // Send root
-                options.subscribe({version: [], parents: [], body: ""})
+            if (getting.history && !getting.subscribe)
+                return dt_get_patches(resource.dt.doc,
+                    getting.history === 'since-parents' ? options.parents : undefined)
 
-                // Send initialization patch
-                if (resource.val) {
-                    options.subscribe({
-                        version: ['999999999-' + (Math.max(0, [...resource.val].length - 1))],
-                        parents: [],
-                        patches: [{unit: 'yjs-text', range: '(:)', content: resource.val}]
-                    })
+            if (getting.subscribe) {
+                var client = {
+                    merge_type: 'simpleton',
+                    peer: options.peer,
+                    send_update: one_at_a_time(options.subscribe),
+                }
+
+                // Send initial history
+                if (getting.history === 'up-to-version')
+                    client.send_update({ version, parents: [], body: resource.val })
+                else if (getting.history === 'since-parents') {
+                    var from = options.version || options.parents
+                    var local_version = OpLog_remote_to_local(resource.dt.doc, from)
+                    if (local_version)
+                        client.send_update({
+                            version, parents: from,
+                            patches: get_xf_patches(resource.dt.doc, local_version)
+                        })
                 }
 
-                // Register for live updates
-                if (!resource.yjs_clients) resource.yjs_clients = new Set()
-                resource.yjs_clients.add(options)
-                options.signal?.addEventListener('abort', () =>
-                    resource.yjs_clients.delete(options))
-
-                return
+                client.abort = () => resource.simpleton.clients.delete(client)
+                resource.simpleton.clients.add(client)
+                options.signal?.addEventListener('abort', () => client.abort())
             }
+            break
 
-            options.my_subscribe_chain = Promise.resolve()
-            options.my_subscribe = (x) =>
-                options.my_subscribe_chain =
-                options.my_subscribe_chain.then(() =>
-                    options.subscribe(x))
-
-            if (options.merge_type != "dt") {
-                // Simpleton clients require DT
-                await ensure_dt_exists(resource)
-
-                let x = { version }
+        case 'dt':
+            await ensure_dt_exists(resource)
 
-                if (!options.parents && !options.version) {
-                    x.parents = []
-                    x.body = resource.val
-                    options.my_subscribe(x)
-                } else {
-                    x.parents = options.version ? options.version : options.parents
+            if (getting.history && !getting.subscribe)
+                return dt_get_patches(resource.dt.doc,
+                    getting.history === 'since-parents' ? options.parents : undefined)
 
-                    // only send them a version from these parents if we have these parents (otherwise we'll assume these parents are more recent, probably versions they created but haven't sent us yet, and we'll send them appropriate rebased updates when they send us these versions)
-                    let local_version = OpLog_remote_to_local(resource.dt.doc, x.parents)
-                    if (local_version) {
-                        x.patches = get_xf_patches(resource.dt.doc, local_version)
-                        options.my_subscribe(x)
-                    }
+            if (getting.subscribe) {
+                var client = {
+                    merge_type: 'dt',
+                    peer: options.peer,
+                    send_update: one_at_a_time(options.subscribe),
+                    accept_encoding_dt: !!options.accept_encoding?.match(/updates\s*\((.*)\)/)?.[1]?.split(',').map(x=>x.trim()).includes('dt'),
                 }
 
-                resource.dt.simpleton_clients.add(options)
-                options.signal?.addEventListener('abort', () =>
-                    resource.dt.simpleton_clients.delete(options))
-            } else {
-                // DT merge-type clients require DT
-                await ensure_dt_exists(resource)
-
-                if (options.accept_encoding?.match(/updates\s*\((.*)\)/)?.[1].split(',').map(x=>x.trim()).includes('dt')) {
-                    // optimization: if client wants past current version,
-                    //               send empty dt
-                    if (options.parents && v_eq(options.parents, version)) {
-                        options.my_subscribe({ encoding: 'dt', body: new Doc().toBytes() })
-                    } else {
+                // Send initial history
+                if (client.accept_encoding_dt) {
+                    if (!getting.history)
+                        client.send_update({ encoding: 'dt', body: new Doc().toBytes() })
+                    else {
                         var bytes = resource.dt.doc.toBytes()
-                        if (options.parents) {
+                        if (getting.history === 'since-parents') {
                             var doc = Doc.fromBytes(bytes)
                             bytes = doc.getPatchSince(
                                 dt_get_local_version(bytes, options.parents))
                             doc.free()
                         }
-                        options.my_subscribe({ encoding: 'dt', body: bytes })
+                        client.send_update({ encoding: 'dt', body: bytes })
                     }
                 } else {
-                    var updates = null
-                    if (!options.parents && !options.version) {
-                        options.my_subscribe({
-                            version: [],
-                            parents: [],
-                            body: "",
-                        })
+                    if (getting.history === 'up-to-version') {
+                        client.send_update({ version: [], parents: [], body: "" })
+                        var updates = dt_get_patches(resource.dt.doc)
+                    } else if (getting.history === 'since-parents')
+                        var updates = dt_get_patches(resource.dt.doc, options.parents || options.version)
+
+                    if (updates) {
+                        for (var u of updates)
+                            client.send_update({
+                                version: [u.version], parents: u.parents,
+                                patches: [{ unit: u.unit, range: u.range, content: u.content }],
+                            })
 
-                        updates = dt_get_patches(resource.dt.doc)
-                    } else {
-                        // Then start the subscription from the parents in options
-                        updates = dt_get_patches(resource.dt.doc, options.parents || options.version)
                     }
-
-                    for (let u of updates)
-                        options.my_subscribe({
-                            version: [u.version],
-                            parents: u.parents,
-                            patches: [{ unit: u.unit, range: u.range, content: u.content }],
-                        })
-
-                    // Output at least *some* data, or else chrome gets confused and
-                    // thinks the connection failed.  This isn't strictly necessary,
-                    // but it makes fewer scary errors get printed out in the JS
-                    // console.
-                    if (updates.length === 0) options.write?.("\r\n")
                 }
 
-                resource.dt.clients.add(options)
-                options.signal?.addEventListener('abort', () =>
-                    resource.dt.clients.delete(options))
+                client.abort = () => resource.dt.clients.delete(client)
+                resource.dt.clients.add(client)
+                options.signal?.addEventListener('abort', () => client.abort())
             }
+            break
         }
     }
 
-    // Deprecated: Use signal-based abort instead (pass signal in options to get())
-    braid_text.forget = async (key, options) => {
-        console.warn('braid_text.forget() is deprecated. Use signal-based abort instead.')
-        if (!options) throw new Error('options is required')
-
-        if (key instanceof URL) throw new Error('forget() does not support URLs. Use signal-based abort instead.')
-
-        let resource = (typeof key == 'string') ? await get_resource(key) : key
-
-        if (options.merge_type != "dt")
-            resource.dt.simpleton_clients.delete(options)
-        else resource.dt.clients.delete(options)
+    // Deprecated: Use client.abort() instead
+    braid_text.forget = async (key, client) => {
+        console.warn('braid_text.forget() is deprecated. Use client.abort() instead.')
+        if (client && client.abort) client.abort()
     }
 
     braid_text.put = async (key, options) => {
@@ -880,7 +882,7 @@ function create_braid_text() {
             for (var x of ['headers', 'parents', 'version', 'peer', 'body', 'patches'])
                 if (options[x] != null) params[x] = options[x]
 
-            return await braid_fetch(key.href, params)
+            return { response: await braid_fetch(key.href, params) }
         }
 
         let resource = (typeof key == 'string') ? await get_resource(key) : key
@@ -898,98 +900,30 @@ function create_braid_text() {
 
             let { version, parents, patches, body, peer } = options
 
-            // Raw Yjs binary update: apply directly to Y.Doc, sync to DT
+            // Yjs update: either raw binary (yjs_update) or yjs-text patches
+            var yjs_binary = null
+            var yjs_text_patches = null
             if (options.yjs_update) {
-                await ensure_yjs_exists(resource)
-
-                // Pre-sync check: DT and Yjs should agree before we start
-                if (braid_text.debug_sync_checks && resource.dt) {
-                    var pre_dt = resource.dt.doc.get()
-                    var pre_yjs = resource.yjs.text.toString()
-                    if (pre_dt !== pre_yjs) {
-                        console.error(`PRE-SYNC MISMATCH key=${resource.key}: DT="${pre_dt.slice(0,50)}" Yjs="${pre_yjs.slice(0,50)}"`)
-                    }
-                }
-
-                var prev_text = resource.yjs.text.toString()
-                var delta = null
-                var observer = (e) => { delta = e.changes.delta }
-                resource.yjs.text.observe(observer)
-                try {
-                    Y.applyUpdate(resource.yjs.doc,
-                        options.yjs_update instanceof Uint8Array ? options.yjs_update : new Uint8Array(options.yjs_update))
-                } finally {
-                    resource.yjs.text.unobserve(observer)
-                }
-
-                resource.val = resource.yjs.text.toString()
-
-                // Sync to DT if it exists
-                if (resource.dt && delta) {
-                    var text_patches = yjs_delta_to_patches(delta, prev_text)
-                    if (text_patches.length) {
-                        var syn_actor = `yjs-${Date.now()}-${Math.random().toString(36).slice(2)}`
-                        var syn_seq = 0
-                        var yjs_v_before = resource.dt.doc.getLocalVersion()
-                        // Patches are sequential (each relative to state after previous)
-                        // so no offset adjustment needed
-                        var dt_bytes = []
-                        var dt_ps = resource.version
-                        for (var tp of text_patches) {
-                            var tp_range = tp.range.match(/-?\d+/g).map(Number)
-                            var tp_del = tp_range[1] - tp_range[0]
-                            var syn_v = `${syn_actor}-${syn_seq}`
-                            if (tp_del) {
-                                dt_bytes.push(dt_create_bytes(syn_v, dt_ps, tp_range[0], tp_del, null))
-                                dt_ps = [`${syn_actor}-${syn_seq + tp_del - 1}`]
-                                syn_seq += tp_del
-                                syn_v = `${syn_actor}-${syn_seq}`
-                            }
-                            if (tp.content.length) {
-                                dt_bytes.push(dt_create_bytes(syn_v, dt_ps, tp_range[0], 0, tp.content))
-                                var cp_len = [...tp.content].length
-                                dt_ps = [`${syn_actor}-${syn_seq + cp_len - 1}`]
-                                syn_seq += cp_len
-                            }
-                        }
-                        for (var b of dt_bytes) resource.dt.doc.mergeBytes(b)
-                        resource.version = resource.dt.doc.getRemoteVersion().map(x => x.join("-")).sort()
-                        if (!resource.dt.known_versions[syn_actor]) resource.dt.known_versions[syn_actor] = new RangeSet()
-                        resource.dt.known_versions[syn_actor].add_range(0, syn_seq - 1)
-                        await resource.dt.save_delta(resource.dt.doc.getPatchSince(yjs_v_before))
-                    }
-                }
-
-                // Persist Yjs
-                if (resource.yjs.save_delta) await resource.yjs.save_delta(
-                    options.yjs_update instanceof Uint8Array ? options.yjs_update : new Uint8Array(options.yjs_update))
-
-                // Sanity check
-                if (braid_text.debug_sync_checks && resource.dt) {
-                    var dt_text = resource.dt.doc.get()
-                    var yjs_text = resource.yjs.text.toString()
-                    if (dt_text !== yjs_text) {
-                        console.error(`SYNC MISMATCH key=${resource.key}: DT text !== Y.Doc text`)
-                        console.error(`  DT:  ${dt_text.slice(0, 100)}... (${dt_text.length})`)
-                        console.error(`  Yjs: ${yjs_text.slice(0, 100)}... (${yjs_text.length})`)
-                    }
-                }
-
-                return { change_count: 1 }
+                yjs_binary = options.yjs_update instanceof Uint8Array
+                    ? options.yjs_update : new Uint8Array(options.yjs_update)
+            } else if (patches && patches.length && patches[0].unit === 'yjs-text') {
+                yjs_text_patches = patches
+                yjs_binary = braid_text.to_yjs_binary([{
+                    version: options.version?.[0],
+                    patches
+                }])
             }
 
-            // yjs-text patches: apply to Y.Doc, sync to DT
-            if (patches && patches.length && patches[0].unit === 'yjs-text') {
+            if (yjs_binary) {
                 await ensure_yjs_exists(resource)
 
-                // Convert yjs-text patches to binary and apply to Y.Doc
-                var binary = braid_text.to_yjs_binary(patches)
+                // Apply binary update to Y.Doc, capturing the delta
                 var prev_text = resource.yjs.text.toString()
                 var delta = null
                 var observer = (e) => { delta = e.changes.delta }
                 resource.yjs.text.observe(observer)
                 try {
-                    Y.applyUpdate(resource.yjs.doc, binary)
+                    Y.applyUpdate(resource.yjs.doc, yjs_binary)
                 } finally {
                     resource.yjs.text.unobserve(observer)
                 }
@@ -1000,12 +934,10 @@ function create_braid_text() {
                 if (resource.dt && delta) {
                     var text_patches = yjs_delta_to_patches(delta, prev_text)
                     if (text_patches.length) {
-                        // Generate a synthetic version for DT
                         var syn_actor = `yjs-${Date.now()}-${Math.random().toString(36).slice(2)}`
                         var syn_seq = 0
+                        var version_before_yjs_sync = resource.version
                         var yjs_v_before = resource.dt.doc.getLocalVersion()
-                        // Patches are sequential (each relative to state after previous)
-                        // so no offset adjustment needed
                         var dt_bytes = []
                         var dt_ps = resource.version
                         for (var tp of text_patches) {
@@ -1027,32 +959,48 @@ function create_braid_text() {
                         }
                         for (var b of dt_bytes) resource.dt.doc.mergeBytes(b)
                         resource.version = resource.dt.doc.getRemoteVersion().map(x => x.join("-")).sort()
-
-                        // Update known_versions for the synthetic versions
                         if (!resource.dt.known_versions[syn_actor]) resource.dt.known_versions[syn_actor] = new RangeSet()
                         resource.dt.known_versions[syn_actor].add_range(0, syn_seq - 1)
-
-                        await resource.dt.save_delta(resource.dt.doc.getPatchSince(yjs_v_before))
-
-                        // Broadcast to DT subscribers
-                        // TODO: broadcast to simpleton and dt clients
+                        await resource.dt.log.save(resource.dt.doc.getPatchSince(yjs_v_before))
+
+                        // Broadcast to simpleton and DT clients
+                        var xf = get_xf_patches(resource.dt.doc, yjs_v_before)
+                        for (let client of resource.simpleton.clients) {
+                            if (!peer || client.peer !== peer)
+                                await client.send_update({
+                                    version: resource.version,
+                                    parents: version_before_yjs_sync,
+                                    patches: xf
+                                })
+                        }
+                        for (let client of resource.dt.clients) {
+                            if (!peer || client.peer !== peer)
+                                await client.send_update(
+                                    client.accept_encoding_dt
+                                        ? { version: resource.version, parents: version_before_yjs_sync, body: resource.dt.doc.getPatchSince(yjs_v_before), encoding: 'dt' }
+                                    : { version: resource.version, parents: version_before_yjs_sync, patches: xf }
+                                )
+                        }
                     }
                 }
 
                 // Broadcast to yjs-text subscribers (skip sender)
-                if (resource.yjs_clients) {
-                    for (var client of resource.yjs_clients) {
-                        if (!peer || client.peer !== peer) {
-                            client.subscribe({
-                                version: resource.version,
-                                patches: patches
-                            })
+                if (resource.yjs) {
+                    // If we received yjs-text updates, reuse them; otherwise
+                    // derive them from the binary update
+                    var yjs_updates = yjs_text_patches
+                        ? [{version: options.version, patches: yjs_text_patches}]
+                        : braid_text.from_yjs_binary(yjs_binary)
+                    for (var yjs_update of yjs_updates) {
+                        for (var client of resource.yjs.clients) {
+                            if (!peer || client.peer !== peer)
+                                await client.send_update(yjs_update)
                         }
                     }
                 }
 
                 // Persist Yjs delta
-                if (resource.yjs.save_delta) await resource.yjs.save_delta(binary)
+                if (resource.yjs.log.save) await resource.yjs.log.save(yjs_binary)
 
                 // Sanity check
                 if (braid_text.debug_sync_checks && resource.dt) {
@@ -1065,7 +1013,7 @@ function create_braid_text() {
                     }
                 }
 
-                return { change_count: patches.length }
+                return { dt: { change_count: yjs_text_patches?.length || 1 } }
             }
 
             if (options.transfer_encoding === 'dt') {
@@ -1083,15 +1031,15 @@ function create_braid_text() {
                 resource.val = resource.dt.doc.get()
                 resource.version = resource.dt.doc.getRemoteVersion().map(x => x.join("-")).sort()
 
-                await resource.dt.save_delta(body)
+                await resource.dt.log.save(body)
 
                 // Notify non-simpleton clients with the dt-encoded update
                 var dt_update = { body, encoding: 'dt' }
-                await Promise.all([...resource.dt.clients].
-                    filter(client => !peer || client.peer !== peer).
-                    map(client => client.my_subscribe(dt_update)))
+                for (let client of resource.dt.clients)
+                    if (!peer || client.peer !== peer)
+                        await client.send_update(dt_update)
 
-                return { change_count: end_i - start_i + 1 }
+                return { dt: { change_count: end_i - start_i + 1 } }
             }
 
             // Text/DT patches require DT
@@ -1099,7 +1047,7 @@ function create_braid_text() {
 
             if (version && !version.length) {
                 console.log(`warning: ignoring put with empty version`)
-                return { change_count: 0 }
+                return { dt: { change_count: 0 } }
             }
             if (version && version.length > 1)
                 throw new Error(`cannot put a version with multiple ids`)
@@ -1145,12 +1093,13 @@ function create_braid_text() {
 
             // Nothing to do: e.g. PUT with empty body on an already-empty doc,
             // or patches that delete and insert zero characters.
-            if (change_count === 0) return { change_count }
+            if (change_count === 0) return { dt: { change_count } }
 
             version = version?.[0] || `${(is_valid_actor(peer) && peer) || Math.random().toString(36).slice(2, 7)}-${change_count - 1}`
 
             let v = decode_version(version)
             var low_seq = v[1] + 1 - change_count
+            if (low_seq < 0) throw new Error(`version seq ${v[1]} is too low for ${change_count} changes — use seq >= ${change_count - 1}`)
 
             // make sure we haven't seen this already
             var intersects_range = resource.dt.known_versions[v[0]]?.has(low_seq, v[1])
@@ -1172,7 +1121,7 @@ function create_braid_text() {
                 if (options.validate_already_seen_versions)
                     validate_old_patches(resource, `${v[0]}-${low_seq}`, parents, patches)
 
-                if (new_count <= 0) return { change_count }
+                if (new_count <= 0) return { dt: { change_count } }
 
                 change_count = new_count
                 low_seq = v[1] + 1 - change_count
@@ -1242,7 +1191,7 @@ function create_braid_text() {
                 xf_patches_relative.push(
                     xf.kind == "Ins"
                         ? { range: [xf.start, xf.start], content: xf.content }
-                        : { range: [xf.start, xf.end], content: "" }
+                    : { range: [xf.start, xf.end], content: "" }
                 )
             }
             var xf_patches = relative_to_absolute_patches(
@@ -1277,20 +1226,20 @@ function create_braid_text() {
                 resource.yjs.doc.off('update', yjs_update_handler)
 
                 // Broadcast to yjs-text subscribers
-                if (resource.yjs_clients && captured_yjs_update) {
-                    var yjs_patches = braid_text.from_yjs_binary(captured_yjs_update)
-                    for (var client of resource.yjs_clients) {
-                        if (!peer || client.peer !== peer) {
-                            client.subscribe({
-                                version: resource.version,
-                                patches: yjs_patches
-                            })
-                        }
-                    }
+                // NOTE: There are two universes of version IDs here -- DT and Yjs --
+                // and we are mixing them. The update-level .version is the DT frontier.
+                // Each patch's .version is a Yjs item ID (clientID-clock).
+                if (resource.yjs && captured_yjs_update) {
+                    var yjs_updates = braid_text.from_yjs_binary(captured_yjs_update)
+                    if (braid_text.verbose) console.log('DT→Yjs broadcast:', yjs_updates.length, 'updates to', resource.yjs.clients.size, 'yjs clients')
+                    for (var yjs_update of yjs_updates)
+                        for (var client of resource.yjs.clients)
+                            if (!peer || client.peer !== peer)
+                                await client.send_update(yjs_update)
                 }
 
                 // Persist Yjs delta
-                if (captured_yjs_update) await resource.yjs.save_delta(captured_yjs_update)
+                if (captured_yjs_update) await resource.yjs.log.save(captured_yjs_update)
 
                 // Sanity check
                 if (braid_text.debug_sync_checks) {
@@ -1312,37 +1261,30 @@ function create_braid_text() {
                 let patches = xf_patches
                 if (braid_text.verbose) console.log(JSON.stringify({ patches }))
 
-                for (let client of resource.dt.simpleton_clients) {
+                for (let client of resource.simpleton.clients) {
                     if (peer && client.peer === peer) {
-                        client.my_last_seen_version = [version]
+                        client.last_seen_version = [version]
                     }
 
                     function set_timeout(time_override) {
-                        if (client.my_timeout) clearTimeout(client.my_timeout)
-                        client.my_timeout = setTimeout(() => {
+                        if (client.timeout) clearTimeout(client.timeout)
+                        client.timeout = braid_text.simpletonSetTimeout(() => {
                             // if the doc has been freed, exit early
                             if (resource.dt.doc.__wbg_ptr === 0) return
 
                             let x = {
                                 version: resource.version,
-                                parents: client.my_last_seen_version
+                                parents: client.last_seen_version
                             }
-                            if (braid_text.verbose) console.log("rebasing after timeout.. ")
-                            if (braid_text.verbose) console.log("    client.my_unused_version_count = " + client.my_unused_version_count)
-                            x.patches = get_xf_patches(resource.dt.doc, OpLog_remote_to_local(resource.dt.doc, client.my_last_seen_version))
+                            x.patches = get_xf_patches(resource.dt.doc, OpLog_remote_to_local(resource.dt.doc, client.last_seen_version))
+                            client.send_update(x)
 
-                            if (braid_text.verbose) console.log(`sending from rebase: ${JSON.stringify(x)}`)
-                            client.my_subscribe(x)
-
-                            delete client.my_timeout
-                        }, time_override ?? Math.min(3000, 23 * Math.pow(1.5, client.my_unused_version_count - 1)))
+                            delete client.timeout
+                        }, time_override ?? Math.min(3000, 23 * Math.pow(1.5, client.unused_version_count - 1)))
                     }
 
-                    if (client.my_timeout) {
+                    if (client.timeout) {
                         if (peer && client.peer === peer) {
-                            // note: we don't add to client.my_unused_version_count,
-                            // because we're already in a timeout;
-                            // we'll just extend it here..
                             set_timeout()
                         }
                         continue
@@ -1351,37 +1293,30 @@ function create_braid_text() {
                     let x = { version: resource.version }
                     if (peer && client.peer === peer) {
                         if (!v_eq(resource.version, [version])) {
-                            // the resource has other changes beyond this
-                            // PUT, so the client is behind — start a
-                            // timeout to batch and rebase
-                            client.my_unused_version_count = (client.my_unused_version_count ?? 0) + 1
+                            client.unused_version_count = (client.unused_version_count ?? 0) + 1
                             set_timeout()
                             continue
                         } else {
-                            delete client.my_unused_version_count
+                            delete client.unused_version_count
                         }
 
-                        // this client already has this version,
-                        // so let's pretend to send it back, but not
-                        if (braid_text.verbose) console.log(`not reflecting back to simpleton`)
+                        // this client already has this version, don't reflect back
                         continue
                     } else {
                         x.parents = version_before
                         x.patches = patches
                     }
-                    if (braid_text.verbose) console.log(`sending: ${JSON.stringify(x)}`)
                     post_commit_updates.push([client, x])
                 }
             } else {
-                if (resource.dt.simpleton_clients.size) {
+                if (resource.simpleton.clients.size) {
                     let x = {
                         version: resource.version,
                         parents: version_before,
                         patches: xf_patches
                     }
-                    if (braid_text.verbose) console.log(`sending: ${JSON.stringify(x)}`)
-                    for (let client of resource.dt.simpleton_clients) {
-                        if (client.my_timeout) continue
+                    for (let client of resource.simpleton.clients) {
+                        if (client.timeout) continue
                         post_commit_updates.push([client, x])
                     }
                 }
@@ -1401,11 +1336,11 @@ function create_braid_text() {
                     post_commit_updates.push([client, x])
             }
 
-            await resource.dt.save_delta(resource.dt.doc.getPatchSince(v_before))
+            await resource.dt.log.save(resource.dt.doc.getPatchSince(v_before))
 
-            await Promise.all(post_commit_updates.map(([client, x]) => client.my_subscribe(x)))
+            for (let [client, x] of post_commit_updates) await client.send_update(x)
 
-            return { change_count }
+            return { dt: { change_count } }
         })
     }
 
@@ -1427,125 +1362,291 @@ function create_braid_text() {
         res.setHeader("Access-Control-Expose-Headers", "*")
     }
 
-    async function get_resource(key) {
-        let cache = braid_text.cache
-        if (!cache[key]) cache[key] = new Promise(async done => {
-            let resource = {key}
-            resource.dt = null
-            resource.yjs = null
-            resource.val = ""
-            resource.version = []
+    // ============================================================
+    // Resource setup helpers
+    // ============================================================
+
+    // Load resource meta from disk (JSON file at meta/[key])
+    async function setup_meta(resource) {
+        if (!braid_text.db_folder) {
             resource.meta = {}
             resource.save_meta = () => {}
-            resource.cursors = null
+            return
+        }
+        await db_folder_init()
+        var encoded = encode_filename(resource.key)
+        var meta_path = `${braid_text.db_folder}/meta/${encoded}`
+        try {
+            resource.meta = JSON.parse(await fs.promises.readFile(meta_path))
+        } catch (e) {
+            resource.meta = {}
+        }
+        var dirty = false, saving = false
+        resource.save_meta = async () => {
+            dirty = true
+            if (saving) return
+            saving = true
+            while (dirty) {
+                dirty = false
+                await atomic_write(meta_path, JSON.stringify(resource.meta),
+                                   `${braid_text.db_folder}/temp`)
+                await new Promise(done => setTimeout(done, braid_text.meta_file_save_period_ms))
+            }
+            saving = false
+        }
+    }
+
+    // Create a fresh DT backend object
+    function make_dt_backend() {
+        return {
+            doc: new Doc("server"),
+            known_versions: {},
+            length_at_version: create_simple_cache(braid_text.length_cache_size),
+            clients: new Set(),
+            log: { save: () => {} },
+        }
+    }
+
+    // Create a fresh Yjs backend object
+    function make_yjs_backend(channel) {
+        require_yjs()
+        var doc = new Y.Doc()
+        return {
+            doc,
+            text: doc.getText(channel),
+            channel,
+            clients: new Set(),
+            log: { save: () => {} },
+        }
+    }
+
+    // Rebuild DT version indexes from doc bytes
+    function rebuild_dt_indexes(resource) {
+        resource.dt.known_versions = {}
+        dt_get_actor_seq_runs([...resource.dt.doc.toBytes()], (actor, base, len) => {
+            if (!resource.dt.known_versions[actor])
+                resource.dt.known_versions[actor] = new RangeSet()
+            resource.dt.known_versions[actor].add_range(base, base + len - 1)
+        })
+    }
+
+    // Set up a write-ahead-plus-compated-state log for a backend (DT or Yjs).
+    // Loads existing data from disk via on_chunk callback.
+    // Provides resource[type].log.save(bytes) for future writes.
+    //
+    // File format: [key].[type].[N]
+    //   Each file: [4-byte len][chunk] [4-byte len][chunk] ...
+    //   First chunk sets compaction threshold (10x its size)
+    //   When file exceeds threshold, get_compacted() is called to write a fresh file
+    async function setup_compacting_log(resource, type, on_chunk, get_compacted) {
+        if (!braid_text.db_folder) {
+            resource[type].log = { save: () => {} }
+            return
+        }
+        await db_folder_init()
+        var encoded = encode_filename(resource.key)
+
+        var log = {
+            file_number: 0,
+            file_size: 0,
+            threshold: 0,
+            save: () => {},  // placeholder until fully initialized below
+        }
+        resource[type].log = log
+
+        // Load existing files
+        var files = (await get_files_for_key(resource.key, type))
+            .filter(x => x.match(/\.\d+$/))
+            .sort((a, b) => parseInt(a.match(/\d+$/)[0]) - parseInt(b.match(/\d+$/)[0]))
 
-            // Load DT data from disk if it exists
-            var has_dt_files = braid_text.db_folder
+        var loaded = false
+        for (var i = files.length - 1; i >= 0; i--) {
+            if (loaded) {
+                await fs.promises.unlink(files[i])
+                continue
+            }
+            try {
+                var data = await fs.promises.readFile(files[i])
+                var cursor = 0, first = true
+                while (cursor < data.length) {
+                    var chunk_size = data.readUInt32LE(cursor)
+                    cursor += 4
+                    on_chunk(data.slice(cursor, cursor + chunk_size))
+                    cursor += chunk_size
+                    if (first) { log.threshold = chunk_size * 10; first = false }
+                }
+                log.file_size = data.length
+                log.file_number = parseInt(files[i].match(/(\d+)$/)[1])
+                loaded = true
+            } catch (error) {
+                console.error(`Error loading ${files[i]}: ${error.message}`)
+                await fs.promises.unlink(files[i])
+            }
+        }
+
+        // Save function: append delta or compact with snapshot
+        log.save = (bytes) => within_fiber('log:' + resource.key + ':' + type, async () => {
+            log.file_size += bytes.length + 4
+            var filename = `${braid_text.db_folder}/${encoded}.${type}.${log.file_number}`
+
+            if (log.file_size < log.threshold) {
+                // Append with WAL-intent for crash safety
+                var len_buf = Buffer.allocUnsafe(4)
+                len_buf.writeUInt32LE(bytes.length, 0)
+                var append_data = Buffer.concat([len_buf, bytes])
+
+                var basename = require('path').basename(filename)
+                var intent_path = `${braid_text.db_folder}/wal-intent/${basename}`
+                var stat = await fs.promises.stat(filename)
+                var size_buf = Buffer.allocUnsafe(8)
+                size_buf.writeBigUInt64LE(BigInt(stat.size), 0)
+
+                await atomic_write(intent_path, Buffer.concat([size_buf, append_data]),
+                                   `${braid_text.db_folder}/temp`)
+                await fs.promises.appendFile(filename, append_data)
+                await fs.promises.unlink(intent_path)
+            } else {
+                // Compact: write full compaction to new file, delete old
+                log.file_number++
+                var snap = get_compacted()
+                var buffer = Buffer.allocUnsafe(4)
+                buffer.writeUInt32LE(snap.length, 0)
+
+                var new_filename = `${braid_text.db_folder}/${encoded}.${type}.${log.file_number}`
+                await atomic_write(new_filename, Buffer.concat([buffer, snap]),
+                                   `${braid_text.db_folder}/temp`)
+
+                log.file_size = 4 + snap.length
+                log.threshold = log.file_size * 10
+                try { await fs.promises.unlink(filename) } catch (e) {}
+            }
+        })
+    }
+
+    // ============================================================
+    // get_resource
+    // ============================================================
+
+    async function get_resource(key, options) {
+        var cache = braid_text.cache
+        if (!cache[key]) cache[key] = new Promise(async done => {
+            var resource = {
+                key,
+                dt: null,
+                yjs: null,
+                simpleton: { clients: new Set() },
+                val: '',
+                version: [],
+                cursors: null,
+                // Returns all subscriber clients across all merge types
+                clients() {
+                    var all = [...this.simpleton.clients]
+                    if (this.dt) all.push(...this.dt.clients)
+                    if (this.yjs) all.push(...this.yjs.clients)
+                    return all
+                },
+            }
+
+            // Always load meta first
+            await setup_meta(resource)
+
+            // Check what's on disk
+            var has_dt = braid_text.db_folder
                 && (await get_files_for_key(key, 'dt')).length > 0
-            if (has_dt_files) {
-                resource.dt = {
-                    doc: new Doc("server"),
-                    known_versions: {},
-                    save_delta: () => {},
-                    length_at_version: createSimpleCache(braid_text.length_cache_size),
-                    clients: new Set(),
-                    simpleton_clients: new Set(),
-                }
-                let { change, change_meta } = await file_sync(key,
-                    (bytes) => resource.dt.doc.mergeBytes(bytes),
-                    () => resource.dt.doc.toBytes(),
-                    (meta) => resource.meta = meta,
-                    () => resource.meta,
-                    'dt')
-
-                resource.dt.save_delta = change
-                resource.save_meta = change_meta
-
-                dt_get_actor_seq_runs([...resource.dt.doc.toBytes()], (actor, base, len) => {
-                    if (!resource.dt.known_versions[actor]) resource.dt.known_versions[actor] = new RangeSet()
-                    resource.dt.known_versions[actor].add_range(base, base + len - 1)
-                })
+            var has_yjs = braid_text.db_folder && Y
+                && (await get_files_for_key(key, 'yjs')).length > 0
+
+            // Get initializer spec if nothing on disk
+            var init = (has_dt || has_yjs) ? null : (
+                options?.initializer ? await options.initializer() : null
+            )
 
+            // --- Load from disk ---
+            if (has_dt) {
+                resource.dt = make_dt_backend()
+                await setup_compacting_log(resource, 'dt',
+                                           (bytes) => resource.dt.doc.mergeBytes(bytes),
+                                           () => resource.dt.doc.toBytes())
+                rebuild_dt_indexes(resource)
                 resource.val = resource.dt.doc.get()
                 resource.version = resource.dt.doc.getRemoteVersion().map(x => x.join("-")).sort()
-            } else if (braid_text.db_folder) {
-                // No DT files — still load meta
-                let { change, change_meta } = await file_sync(key,
-                    () => {},
-                    () => Buffer.alloc(0),
-                    (meta) => resource.meta = meta,
-                    () => resource.meta,
-                    'dt')
-                resource.save_meta = change_meta
-            }
-
-            // Load Yjs data from disk if it exists
-            var has_yjs_files = braid_text.db_folder && Y
-                && (await get_files_for_key(key, 'yjs')).length > 0
-            if (has_yjs_files) {
-                resource.yjs = {
-                    doc: new Y.Doc(),
-                    text: null,
-                    save_delta: () => {},
-                }
-                resource.yjs.text = resource.yjs.doc.getText('text')
-                let { change } = await file_sync(key,
-                    (bytes) => Y.applyUpdate(resource.yjs.doc, bytes),
-                    () => Y.encodeStateAsUpdate(resource.yjs.doc),
-                    () => {},
-                    () => ({}),
-                    'yjs')
-
-                resource.yjs.save_delta = change
-
+            }
+            if (has_yjs) {
+                var channel = resource.meta.yjs_channel || 'text'
+                resource.yjs = make_yjs_backend(channel)
+                await setup_compacting_log(resource, 'yjs',
+                                           (bytes) => Y.applyUpdate(resource.yjs.doc, bytes),
+                                           () => Y.encodeStateAsUpdate(resource.yjs.doc))
                 var yjs_text = resource.yjs.text.toString()
                 if (resource.dt) {
-                    // Both exist — sanity check they match
                     if (resource.val !== yjs_text) {
-                        console.error(`INIT MISMATCH key=${key}: DT text !== Yjs text`)
-                        console.error(`  DT:  ${resource.val.slice(0, 100)}... (${resource.val.length})`)
-                        console.error(`  Yjs: ${yjs_text.slice(0, 100)}... (${yjs_text.length})`)
+                        console.error(`INIT MISMATCH key=${key}: DT="${resource.val.slice(0,50)}" Yjs="${yjs_text.slice(0,50)}"`)
                     }
                 } else {
-                    // Yjs only — use its text as resource.val
                     resource.val = yjs_text
                 }
             }
 
-            // length_at_version cache is created as part of resource.dt when DT is initialized
+            // --- Initialize from external source (only when nothing on disk) ---
+            if (init) {
+                if (init.yjs) {
+                    var channel = (typeof init.yjs === 'object' && init.yjs.channel) || 'text'
+                    var history = typeof init.yjs === 'object' && init.yjs.history
+                    resource.yjs = make_yjs_backend(channel)
+                    resource.meta.yjs_channel = channel
+                    resource.save_meta()
+                    if (history) {
+                        Y.applyUpdate(resource.yjs.doc,
+                                      history instanceof Uint8Array ? history : new Uint8Array(history))
+                        resource.val = resource.yjs.text.toString()
+                    }
+                    await setup_compacting_log(resource, 'yjs',
+                                               (bytes) => Y.applyUpdate(resource.yjs.doc, bytes),
+                                               () => Y.encodeStateAsUpdate(resource.yjs.doc))
+                    await resource.yjs.log.save(Y.encodeStateAsUpdate(resource.yjs.doc))
+                }
+                if (init.dt) {
+                    var dt_history = typeof init.dt === 'object' && init.dt.history
+                    resource.dt = make_dt_backend()
+                    if (dt_history) {
+                        resource.dt.doc.mergeBytes(
+                            dt_history instanceof Uint8Array ? dt_history : new Uint8Array(dt_history))
+                    } else if (resource.val) {
+                        resource.dt.doc.mergeBytes(
+                            dt_create_bytes('999999999-0', [], 0, 0, resource.val))
+                    }
+                    rebuild_dt_indexes(resource)
+                    resource.version = resource.dt.doc.getRemoteVersion().map(x => x.join("-")).sort()
+                    if (!resource.val) resource.val = resource.dt.doc.get()
+                    await setup_compacting_log(resource, 'dt',
+                                               (bytes) => resource.dt.doc.mergeBytes(bytes),
+                                               () => resource.dt.doc.toBytes())
+                    await resource.dt.log.save(resource.dt.doc.toBytes())
+                }
+            }
+
+            // Sanity check
+            if (resource.dt && resource.yjs) {
+                var dt_text = resource.dt.doc.get()
+                var yjs_text = resource.yjs.text.toString()
+                if (dt_text !== yjs_text)
+                    console.error(`get_resource key=${key}: DT and Yjs disagree: DT="${dt_text.slice(0,50)}" Yjs="${yjs_text.slice(0,50)}"`)
+            }
 
-            // Add delete method to resource
+            // Delete method
             resource.delete = async () => {
                 if (resource.dt) resource.dt.doc.free()
                 if (resource.yjs) resource.yjs.doc.destroy()
-
-                // Remove from in-memory cache
                 delete braid_text.cache[key]
-
-                // Remove all files for this key from db_folder
                 if (braid_text.db_folder) {
-                    var files = await get_files_for_key(key)
-                    for (var file of files) {
-                        try {
-                            await fs.promises.unlink(file)
-                        } catch (e) {
-                            // File might not exist, that's ok
-                        }
-                    }
-
-                    // Remove meta file if it exists
+                    for (var file of await get_files_for_key(key))
+                        try { await fs.promises.unlink(file) } catch (e) {}
                     try {
-                        var encoded = encode_filename(key)
-                        await fs.promises.unlink(`${braid_text.db_folder}/meta/${encoded}`)
-                    } catch (e) {
-                        // Meta file might not exist, that's ok
-                    }
+                        await fs.promises.unlink(`${braid_text.db_folder}/meta/${encode_filename(key)}`)
+                    } catch (e) {}
                 }
-
-                // Remove from filename mapping
                 if (key_to_filename.has(key)) {
-                    var encoded = key_to_filename.get(key)
-                    ifilenames.delete(encoded.toLowerCase())
+                    ifilenames.delete(key_to_filename.get(key).toLowerCase())
                     key_to_filename.delete(key)
                 }
             }
@@ -1555,64 +1656,34 @@ function create_braid_text() {
         return await cache[key]
     }
 
+    // Internal: create DT backend on demand, synced from resource.val
     async function ensure_dt_exists(resource) {
         if (resource.dt) return
-        resource.dt = {
-            doc: new Doc("server"),
-            known_versions: {},
-            save_delta: () => {},
-            length_at_version: createSimpleCache(braid_text.length_cache_size),
-            clients: new Set(),
-            simpleton_clients: new Set(),
-        }
+        resource.dt = make_dt_backend()
         if (resource.val) {
-            // Seed DT with current text as a root insert
-            var bytes = dt_create_bytes(
-                `999999999-0`, [], 0, 0, resource.val)
-            resource.dt.doc.mergeBytes(bytes)
+            resource.dt.doc.mergeBytes(
+                dt_create_bytes('999999999-0', [], 0, 0, resource.val))
         }
+        rebuild_dt_indexes(resource)
         resource.version = resource.dt.doc.getRemoteVersion().map(x => x.join("-")).sort()
-
-        dt_get_actor_seq_runs([...resource.dt.doc.toBytes()], (actor, base, len) => {
-            if (!resource.dt.known_versions[actor]) resource.dt.known_versions[actor] = new RangeSet()
-            resource.dt.known_versions[actor].add_range(base, base + len - 1)
-        })
-
-        // Set up DT persistence if db_folder exists
-        if (braid_text.db_folder) {
-            let { change } = await file_sync(resource.key,
-                (bytes) => resource.dt.doc.mergeBytes(bytes),
-                () => resource.dt.doc.toBytes(),
-                () => {},
-                () => ({}),
-                'dt')
-            resource.dt.save_delta = change
-        }
+        await setup_compacting_log(resource, 'dt',
+                                   (bytes) => resource.dt.doc.mergeBytes(bytes),
+                                   () => resource.dt.doc.toBytes())
     }
 
-    async function ensure_yjs_exists(resource) {
+    // Internal: create Yjs backend on demand, synced from resource.val
+    async function ensure_yjs_exists(resource, options) {
         if (resource.yjs) return
-        require_yjs()
-        resource.yjs = {
-            doc: new Y.Doc(),
-            text: null,
-            save_delta: () => {},
-        }
-        resource.yjs.text = resource.yjs.doc.getText('text')
+        var channel = options?.channel || resource.meta?.yjs_channel || 'text'
+        resource.yjs = make_yjs_backend(channel)
         if (resource.val) {
             resource.yjs.text.insert(0, resource.val)
         }
-
-        // Set up Yjs persistence if db_folder exists
-        if (braid_text.db_folder) {
-            let { change } = await file_sync(resource.key,
-                (bytes) => Y.applyUpdate(resource.yjs.doc, bytes),
-                () => Y.encodeStateAsUpdate(resource.yjs.doc),
-                () => {},
-                () => ({}),
-                'yjs')
-            resource.yjs.save_delta = change
-        }
+        resource.meta.yjs_channel = channel
+        resource.save_meta()
+        await setup_compacting_log(resource, 'yjs',
+                                   (bytes) => Y.applyUpdate(resource.yjs.doc, bytes),
+                                   () => Y.encodeStateAsUpdate(resource.yjs.doc))
     }
 
     async function db_folder_init() {
@@ -1718,133 +1789,7 @@ function create_braid_text() {
         } catch (e) { return [] }    
     }
 
-    async function file_sync(key, process_delta, get_init, set_meta, get_meta, file_type) {
-        await db_folder_init()
-        let encoded = encode_filename(key)
-        file_type = file_type || 'dt'
-
-        if (encoded.length > max_encoded_key_size) throw new Error(`invalid key: too long (max ${max_encoded_key_size})`)
-
-        let currentNumber = 0
-        let currentSize = 0
-        let threshold = 0
-
-        // Read existing files and sort by numbers.
-        const files = (await get_files_for_key(key, file_type))
-            .filter(x => x.match(/\.\d+$/))
-            .sort((a, b) => parseInt(a.match(/\d+$/)[0]) - parseInt(b.match(/\d+$/)[0]))
-
-        // Try to process files starting from the highest number.
-        let done = false
-        for (let i = files.length - 1; i >= 0; i--) {
-            if (done) {
-                await fs.promises.unlink(files[i])
-                continue
-            }
-            try {
-                const filename = files[i]
-                if (braid_text.verbose) console.log(`trying to process file: ${filename}`)
-                const data = await fs.promises.readFile(filename)
-
-                let cursor = 0
-                let isFirstChunk = true
-                while (cursor < data.length) {
-                    const chunkSize = data.readUInt32LE(cursor)
-                    cursor += 4
-                    const chunk = data.slice(cursor, cursor + chunkSize)
-                    cursor += chunkSize
-
-                    if (isFirstChunk) {
-                        isFirstChunk = false
-                        threshold = chunkSize * 10
-                    }
-                    process_delta(chunk)
-                }
-
-                currentSize = data.length
-                currentNumber = parseInt(filename.match(/(\d+)$/)[1])
-                done = true
-            } catch (error) {
-                console.error(`Error processing file: ${files[i]}`)
-                await fs.promises.unlink(files[i])
-            }
-        }
-
-        var meta_filename = `${braid_text.db_folder}/meta/${encoded}`
-        var meta_dirty = null
-        var meta_saving = null
-        var meta_file_content = '{}'
-        try {
-            var meta_file_content = await fs.promises.readFile(meta_filename)
-        } catch (e) {}
-        set_meta(JSON.parse(meta_file_content))
-
-        return {
-            change: (bytes) => within_fiber('file:' + key, async () => {
-                if (!bytes) currentSize = threshold
-                else currentSize += bytes.length + 4 // we account for the extra 4 bytes for uint32
-                const filename = `${braid_text.db_folder}/${encoded}.${file_type}.${currentNumber}`
-                if (currentSize < threshold) {
-                    if (braid_text.verbose) console.log(`appending to db..`)
-
-                    let len_buf = Buffer.allocUnsafe(4)
-                    len_buf.writeUInt32LE(bytes.length, 0)
-                    let append_data = Buffer.concat([len_buf, bytes])
-
-                    let basename = require('path').basename(filename)
-                    let intent_path = `${braid_text.db_folder}/wal-intent/${basename}`
-                    let stat = await fs.promises.stat(filename)
-                    let size_buf = Buffer.allocUnsafe(8)
-                    size_buf.writeBigUInt64LE(BigInt(stat.size), 0)
-
-                    await atomic_write(intent_path, Buffer.concat([size_buf, append_data]),
-                        `${braid_text.db_folder}/temp`)
-                    await fs.promises.appendFile(filename, append_data)
-                    await fs.promises.unlink(intent_path)
-
-                    if (braid_text.verbose) console.log("wrote to : " + filename)
-                } else {
-                    try {
-                        if (braid_text.verbose) console.log(`starting new db..`)
-
-                        currentNumber++
-                        const init = get_init()
-                        const buffer = Buffer.allocUnsafe(4)
-                        buffer.writeUInt32LE(init.length, 0)
-
-                        const newFilename = `${braid_text.db_folder}/${encoded}.${file_type}.${currentNumber}`
-                        await atomic_write(newFilename, Buffer.concat([buffer, init]),
-                            `${braid_text.db_folder}/temp`)
-
-                        if (braid_text.verbose) console.log("wrote to : " + newFilename)
-
-                        currentSize = 4 + init.length
-                        threshold = currentSize * 10
-                        try {
-                            await fs.promises.unlink(filename)
-                        } catch (e) { }
-                    } catch (e) {
-                        if (braid_text.verbose) console.log(`e = ${e.stack}`)
-                    }
-                }
-            }),
-            change_meta: async () => {
-                meta_dirty = true
-                if (meta_saving) return
-                meta_saving = true
-
-                while (meta_dirty) {
-                    meta_dirty = false
-                    await atomic_write(meta_filename, JSON.stringify(get_meta()),
-                        `${braid_text.db_folder}/temp`)
-                    await new Promise(done => setTimeout(done,
-                        braid_text.meta_file_save_period_ms))
-                }
-
-                meta_saving = false
-            }
-        }
-    }
+    // (file_sync removed — replaced by setup_meta and setup_compacting_log above)
 
     async function wait_for_events(
         key,
@@ -2085,11 +2030,11 @@ function create_braid_text() {
                 let I = base_i + j
                 if (
                     j == len ||
-                    parentss[I].length != 1 ||
-                    parentss[I][0][0] != versions[I - 1][0] ||
-                    parentss[I][0][1] != versions[I - 1][1] ||
-                    versions[I][0] != versions[I - 1][0] ||
-                    versions[I][1] != versions[I - 1][1] + 1
+                        parentss[I].length != 1 ||
+                        parentss[I][0][0] != versions[I - 1][0] ||
+                        parentss[I][0][1] != versions[I - 1][1] ||
+                        versions[I][0] != versions[I - 1][0] ||
+                        versions[I][1] != versions[I - 1][1] + 1
                 ) {
                     for (; i < I; i++) {
                         let version = versions[i].join("-")
@@ -2110,8 +2055,8 @@ function create_braid_text() {
                                 parentss[og_i].map((x) => x.join("-")),
                                 op_run.fwd ?
                                     (op_run.content ?
-                                        op_run.start + (og_i - base_i) :
-                                        op_run.start) :
+                                     op_run.start + (og_i - base_i) :
+                                     op_run.start) :
                                     op_run.end - 1 - (i - base_i),
                                 op_run.content ? 0 : i - og_i + 1,
                                 content
@@ -2126,7 +2071,7 @@ function create_braid_text() {
 
     function dt_get_patches(doc, version = null) {
         if (version && v_eq(version,
-            doc.getRemoteVersion().map((x) => x.join("-")).sort())) {
+                            doc.getRemoteVersion().map((x) => x.join("-")).sort())) {
             // they want everything past the end, which is nothing
             return []
         }
@@ -2166,22 +2111,22 @@ function create_braid_text() {
                 let I = i + j
                 if (
                     (!op_run.content && op_run.fwd) ||
-                    j == len ||
-                    parentss[I].length != 1 ||
-                    parentss[I][0][0] != versions[I - 1][0] ||
-                    parentss[I][0][1] != versions[I - 1][1] ||
-                    versions[I][0] != versions[I - 1][0] ||
-                    versions[I][1] != versions[I - 1][1] + 1
+                        j == len ||
+                        parentss[I].length != 1 ||
+                        parentss[I][0][0] != versions[I - 1][0] ||
+                        parentss[I][0][1] != versions[I - 1][1] ||
+                        versions[I][0] != versions[I - 1][0] ||
+                        versions[I][1] != versions[I - 1][1] + 1
                 ) {
                     let s = op_run.fwd ?
                         (op_run.content ?
-                            start :
-                            op_run.start) :
+                         start :
+                         op_run.start) :
                         (op_run.start + (op_run.end - end))
                     let e = op_run.fwd ?
                         (op_run.content ?
-                            end :
-                            op_run.start + (end - start)) :
+                         end :
+                         op_run.start + (end - start)) :
                         (op_run.end - (start - op_run.start))
                     patches.push({
                         version: `${version[0]}-${version[1] + e - s - 1}`,
@@ -2391,19 +2336,19 @@ function create_braid_text() {
         return local_version
 
         function splice_out_range(a, s, e) {
-            if (!a?.length) return [];
-            let l = 0, r = a.length;
+            if (!a?.length) return []
+            var l = 0, r = a.length
             while (l < r) {
-                const m = Math.floor((l + r) / 2);
-                if (a[m] < s) l = m + 1; else r = m;
+                var m = Math.floor((l + r) / 2)
+                if (a[m] < s) l = m + 1; else r = m
             }
-            const i = l;
-            l = i; r = a.length;
+            var i = l
+            l = i; r = a.length
             while (l < r) {
-                const m = Math.floor((l + r) / 2);
-                if (a[m] <= e) l = m + 1; else r = m;
+                m = Math.floor((l + r) / 2)
+                if (a[m] <= e) l = m + 1; else r = m
             }
-            return a.splice(i, l - i);
+            return a.splice(i, l - i)
         }
     }
 
@@ -2623,11 +2568,11 @@ function create_braid_text() {
                         range: `[${xf.start}:${xf.start}]`,
                         content: xf.content,
                     }
-                    : {
-                        unit: "text",
-                        range: `[${xf.start}:${xf.end}]`,
-                        content: "",
-                    }
+                : {
+                    unit: "text",
+                    range: `[${xf.start}:${xf.end}]`,
+                    content: "",
+                }
             )
         }
         var result = relative_to_absolute_patches(patches)
@@ -2686,7 +2631,7 @@ function create_braid_text() {
                     resize(x, count_code_points(x.content))
                     resize(node, node.size - (start + del))
                 } else {
-                    node.content = node.content.slice(0, codePoints_to_index(node.content, start)) + p.content + node.content.slice(codePoints_to_index(node.content, start + del))
+                    node.content = node.content.slice(0, codepoints_to_index(node.content, start)) + p.content + node.content.slice(codepoints_to_index(node.content, start + del))
                     resize(node, count_code_points(node.content))
                 }
             } else {
@@ -2719,7 +2664,7 @@ function create_braid_text() {
                         resize(next, next.size - remaining)
                     } else {
                         next.del += node.size - start + middle_del
-                        next.content = p.content + next.content.slice(codePoints_to_index(next.content, remaining))
+                        next.content = p.content + next.content.slice(codepoints_to_index(next.content, remaining))
                         resize(node, start)
                         if (node.size == 0) avl.del(node)
                         resize(next, count_code_points(next.content))
@@ -2727,12 +2672,12 @@ function create_braid_text() {
                 } else {
                     if (next.content == null) {
                         node.del += middle_del + remaining
-                        node.content = node.content.slice(0, codePoints_to_index(node.content, start)) + p.content
+                        node.content = node.content.slice(0, codepoints_to_index(node.content, start)) + p.content
                         resize(node, count_code_points(node.content))
                         resize(next, next.size - remaining)
                     } else {
                         node.del += middle_del + next.del
-                        node.content = node.content.slice(0, codePoints_to_index(node.content, start)) + p.content + next.content.slice(codePoints_to_index(next.content, remaining))
+                        node.content = node.content.slice(0, codepoints_to_index(node.content, start)) + p.content + next.content.slice(codepoints_to_index(next.content, remaining))
                         resize(node, count_code_points(node.content))
                         resize(next, 0)
                         avl.del(next)
@@ -2884,23 +2829,21 @@ function create_braid_text() {
         return code_points;
     }
 
-    function index_to_codePoints(str, index) {
-        let i = 0
-        let c = 0
+    function index_to_codepoints(str, index) {
+        var i = 0, c = 0
         while (i < index && i < str.length) {
-            const charCode = str.charCodeAt(i)
-            i += (charCode >= 0xd800 && charCode <= 0xdbff) ? 2 : 1
+            var code = str.charCodeAt(i)
+            i += (code >= 0xd800 && code <= 0xdbff) ? 2 : 1
             c++
         }
         return c
     }
 
-    function codePoints_to_index(str, codePoints) {
-        let i = 0
-        let c = 0
-        while (c < codePoints && i < str.length) {
-            const charCode = str.charCodeAt(i)
-            i += (charCode >= 0xd800 && charCode <= 0xdbff) ? 2 : 1
+    function codepoints_to_index(str, codepoints) {
+        var i = 0, c = 0
+        while (c < codepoints && i < str.length) {
+            var code = str.charCodeAt(i)
+            i += (code >= 0xd800 && code <= 0xdbff) ? 2 : 1
             c++
         }
         return i
@@ -3016,12 +2959,12 @@ function create_braid_text() {
     var yjs_id_pattern = '(\\d+-\\d+)'
     var yjs_range_re = new RegExp(
         '^\\s*' +
-        '([\\(\\[])' +                        // open bracket: ( or [
-        '\\s*' + yjs_id_pattern + '?' +        // optional left ID
-        '\\s*:\\s*' +                          // colon separator
-        yjs_id_pattern + '?' + '\\s*' +        // optional right ID
-        '([\\)\\]])' +                         // close bracket: ) or ]
-        '\\s*$'
+            '([\\(\\[])' +                        // open bracket: ( or [
+            '\\s*' + yjs_id_pattern + '?' +        // optional left ID
+            '\\s*:\\s*' +                          // colon separator
+            yjs_id_pattern + '?' + '\\s*' +        // optional right ID
+            '([\\)\\]])' +                         // close bracket: ) or ]
+            '\\s*$'
     )
 
     function validate_yjs_patch(x) {
@@ -3123,48 +3066,60 @@ function create_braid_text() {
     // Convert a Yjs binary update to yjs-text range patches.
     // Decodes the binary without needing a Y.Doc.
     // Returns array of {unit: 'yjs-text', range: '...', content: '...'}
+    // Convert a Yjs binary update to an array of braid updates,
+    // each with a version and patches in yjs-text format.
     braid_text.from_yjs_binary = function(update) {
         require_yjs()
         var decoded = Y.decodeUpdate(
             update instanceof Uint8Array ? update : new Uint8Array(update))
-        var patches = []
+        var updates = []
 
-        // Convert inserted structs to yjs-text patches
+        // Each inserted struct becomes one update with one insert patch.
+        // GC'd structs (deleted items) have content.len but no content.str —
+        // we emit placeholder text since the delete set will remove it anyway.
         for (var struct of decoded.structs) {
-            if (!struct.content?.str) continue  // skip non-text items
+            var text = struct.content?.str
+            if (!text && struct.content?.len) text = '_'.repeat(struct.content.len)
+            if (!text) continue  // skip non-text items (e.g. format, embed)
             var id = struct.id
             var origin = struct.origin
             var rightOrigin = struct.rightOrigin
             var left = origin ? `${origin.client}-${origin.clock}` : ''
             var right = rightOrigin ? `${rightOrigin.client}-${rightOrigin.clock}` : ''
-            patches.push({
-                unit: 'yjs-text',
-                range: `(${left}:${right})`,
-                content: struct.content.str
+            updates.push({
+                version: [`${id.client}-${id.clock}`],
+                patches: [{
+                    unit: 'yjs-text',
+                    range: `(${left}:${right})`,
+                    content: text,
+                }]
             })
         }
 
-        // Convert delete set entries to yjs-text patches
+        // Each delete range becomes one update with one delete patch
         for (var [clientID, deleteItems] of decoded.ds.clients) {
             for (var item of deleteItems) {
                 var left = `${clientID}-${item.clock}`
                 var right = `${clientID}-${item.clock + item.len - 1}`
-                patches.push({
-                    unit: 'yjs-text',
-                    range: `[${left}:${right}]`,
-                    content: ''
+                updates.push({
+                    version: [`${clientID}-${item.clock}`],
+                    patches: [{
+                        unit: 'yjs-text',
+                        range: `[${left}:${right}]`,
+                        content: ''
+                    }]
                 })
             }
         }
 
-        return patches
+        return updates
     }
 
     // Convert yjs-text range patches to a Yjs binary update.
+    // Convert braid updates with yjs-text patches to a Yjs binary update.
     // This is the inverse of from_yjs_binary.
-    // Each insert patch needs a clientID and clock for the new item.
-    // These are passed as patch.id = {client, clock}.
-    braid_text.to_yjs_binary = function(patches) {
+    // Accepts an array of updates, each with {version, patches}.
+    braid_text.to_yjs_binary = function(updates) {
         require_yjs()
         var lib0_encoding = require('lib0/encoding')
         var encoder = new Y.UpdateEncoderV1()
@@ -3173,23 +3128,30 @@ function create_braid_text() {
         var inserts_by_client = new Map()
         var deletes_by_client = new Map()
 
-        for (var p of patches) {
-            var parsed = parse_yjs_range(p.range)
-            if (!parsed) throw new Error(`invalid yjs-text range: ${p.range}`)
-
-            if (p.content.length > 0) {
-                // Insert
-                if (!p.id) throw new Error('insert patch requires .id = {client, clock}')
-                var list = inserts_by_client.get(p.id.client) || []
-                list.push({ id: p.id, origin: parsed.left, rightOrigin: parsed.right, content: p.content })
-                inserts_by_client.set(p.id.client, list)
-            } else {
-                // Delete
-                if (!parsed.left) throw new Error('delete patch requires left ID')
-                var client = parsed.left.client
-                var list = deletes_by_client.get(client) || []
-                list.push({ clock: parsed.left.clock, len: parsed.right ? parsed.right.clock - parsed.left.clock + 1 : 1 })
-                deletes_by_client.set(client, list)
+        for (var update of updates) {
+            if (!update.patches) continue
+            for (var p of update.patches) {
+                var parsed = parse_yjs_range(p.range)
+                if (!parsed) throw new Error(`invalid yjs-text range: ${p.range}`)
+
+                if (p.content.length > 0) {
+                    // Insert — version on the update is the item ID as ["client-clock"]
+                    var v_str = Array.isArray(update.version) ? update.version[0] : update.version
+                    if (!v_str) throw new Error('insert update requires .version = ["client-clock"]')
+                    var v_parts = v_str.match(/^(\d+)-(\d+)$/)
+                    if (!v_parts) throw new Error('invalid update version: ' + v_str)
+                    var item_id = { client: parseInt(v_parts[1]), clock: parseInt(v_parts[2]) }
+                    var list = inserts_by_client.get(item_id.client) || []
+                    list.push({ id: item_id, origin: parsed.left, rightOrigin: parsed.right, content: p.content })
+                    inserts_by_client.set(item_id.client, list)
+                } else {
+                    // Delete
+                    if (!parsed.left) throw new Error('delete patch requires left ID')
+                    var client = parsed.left.client
+                    var list = deletes_by_client.get(client) || []
+                    list.push({ clock: parsed.left.clock, len: parsed.right ? parsed.right.clock - parsed.left.clock + 1 : 1 })
+                    deletes_by_client.set(client, list)
+                }
             }
         }
 
@@ -3345,35 +3307,23 @@ function create_braid_text() {
         return second_patches
     }
 
-    function createSimpleCache(size) {
-        const maxSize = size
-        const cache = new Map()
-
+    // Create a LRU cache.  It evicts stuff when it gets greater than `size` in LRU order.
+    function create_simple_cache(size) {
+        // This map will iterate over keys in the order they were inserted.
+        // Eviction will remove from the front of the map.
+        // So we want every delete() and set() operation to move a key/value to the end.
+        var map = new Map()
         return {
             put(key, value) {
-                if (cache.has(key)) {
-                    // If the key already exists, update its value and move it to the end
-                    cache.delete(key)
-                    cache.set(key, value)
-                } else {
-                    // If the cache is full, remove the oldest entry
-                    if (cache.size >= maxSize) {
-                        const oldestKey = cache.keys().next().value
-                        cache.delete(oldestKey)
-                    }
-                    // Add the new key-value pair
-                    cache.set(key, value)
-                }
+                map.delete(key)  // remove first so existing keys don't trigger eviction
+                if (map.size >= size) map.delete(map.keys().next().value)
+                map.set(key, value)
             },
-
             get(key) {
-                if (!cache.has(key)) {
-                    return null
-                }
-                // Move the accessed item to the end (most recently used)
-                const value = cache.get(key)
-                cache.delete(key)
-                cache.set(key, value)
+                if (!map.has(key)) return null
+                var value = map.get(key)
+                map.delete(key)
+                map.set(key, value)
                 return value
             },
         }
@@ -3441,7 +3391,7 @@ function create_braid_text() {
                 else {                                     //  - Array set
                     console.assert(slice_end >= 0, 'Index '+subpath+' is too small')
                     console.assert(slice_end <= curr_obj.length - 1,
-                                'Index '+subpath+' is too big')
+                                   'Index '+subpath+' is too big')
                     curr_obj[slice_end] = new_stuff
                 }
 
@@ -3465,16 +3415,15 @@ function create_braid_text() {
         add_range(low_inclusive, high_inclusive) {
             if (low_inclusive > high_inclusive) throw new Error('invalid range')
 
-            const startIndex = this._bs(mid => this.ranges[mid][1] >= low_inclusive - 1, this.ranges.length, true)
-            const endIndex = this._bs(mid => this.ranges[mid][0] <= high_inclusive + 1, -1, false)
+            var start_i = this._bs(mid => this.ranges[mid][1] >= low_inclusive - 1, this.ranges.length, true)
+            var end_i = this._bs(mid => this.ranges[mid][0] <= high_inclusive + 1, -1, false)
 
-            if (startIndex > endIndex) {
-                this.ranges.splice(startIndex, 0, [low_inclusive, high_inclusive])
-            } else {
-                const mergedLow = Math.min(low_inclusive, this.ranges[startIndex][0])
-                const mergedHigh = Math.max(high_inclusive, this.ranges[endIndex][1])
-                const removeCount = endIndex - startIndex + 1
-                this.ranges.splice(startIndex, removeCount, [mergedLow, mergedHigh])
+            if (start_i > end_i)
+                this.ranges.splice(start_i, 0, [low_inclusive, high_inclusive])
+            else {
+                var merged_low = Math.min(low_inclusive, this.ranges[start_i][0])
+                var merged_high = Math.max(high_inclusive, this.ranges[end_i][1])
+                this.ranges.splice(start_i, end_i - start_i + 1, [merged_low, merged_high])
             }
         }
 
@@ -3484,20 +3433,15 @@ function create_braid_text() {
             return index !== -1 && x <= this.ranges[index][1] && this.ranges[index]
         }
 
-        _bs(condition, defaultR, moveLeft) {
-            let low = 0
-            let high = this.ranges.length - 1
-            let result = defaultR
-            
-            while (low <= high) {
-                const mid = Math.floor((low + high) / 2)
+        _bs(condition, default_r, move_left) {
+            var lo = 0, hi = this.ranges.length - 1, result = default_r
+            while (lo <= hi) {
+                var mid = Math.floor((lo + hi) / 2)
                 if (condition(mid)) {
                     result = mid
-                    if (moveLeft) high = mid - 1
-                    else low = mid + 1
+                    if (move_left) hi = mid - 1; else lo = mid + 1
                 } else {
-                    if (moveLeft) low = mid + 1
-                    else high = mid - 1
+                    if (move_left) lo = mid + 1; else hi = mid - 1
                 }
             }
             return result
@@ -3653,8 +3597,13 @@ function create_braid_text() {
     }
 
     braid_text.get_resource = get_resource
-    braid_text.ensure_dt_exists = ensure_dt_exists
-    braid_text.ensure_yjs_exists = ensure_yjs_exists
+
+    // Returns the number of connected subscribers for a resource
+    braid_text.subscriber_count = async function(key) {
+        if (!braid_text.cache[key]) return 0
+        var resource = await braid_text.cache[key]
+        return resource.clients().length
+    }
 
     braid_text.db_folder_init = db_folder_init
     braid_text.encode_filename = encode_filename
@@ -3813,8 +3762,13 @@ async function handle_cursors(resource, req, res) {
         } else {
             var subscriber = {peer, res}
             cursors.subscribe(subscriber)
+            all_subscriptions.add(res)
             res.startSubscription({
-                onClose: () => cursors.unsubscribe(subscriber)
+                onClose: () => {
+                    all_subscriptions.delete(res)
+                    cursors.subscribers.delete(subscriber)
+                    setTimeout(() => cursors.unsubscribe(subscriber), 0)
+                }
             })
             res.sendUpdate({ body: JSON.stringify(cursors.snapshot()) })
         }