Add Subduction integration to automerge-repo

Integrates the Subduction sync engine
(github.com/inkandswitch/subduction) directly into the core
automerge-repo package as a new sync source alongside the legacy
StorageSubsystem + NetworkSubsystem path.

Why integrate rather than wrap: Subduction's sedimentree-based,
fingerprint-driven sync model needs hooks into document lifecycle
events that the existing DocumentSource interface already provides.
Folding it into core (under packages/automerge-repo/src/subduction/)
means consumers install one package and Wasm modules auto-init via
the fullfat entrypoint.

What lands in this commit:

- src/subduction/source.ts -- SubductionSource implements
  DocumentSource. Owns the per-doc SedimentreeEntry map, manages a
  throttled #save with a single-flight gate, derives fragment
  boundary requests, and drains commits via flush().
- src/subduction/storage.ts -- SubductionStorageBridge wraps any
  StorageAdapterInterface to implement Subduction's
  SedimentreeStorage. Tracks pending writes per SedimentreeId so
  awaitSettled(sids?) can be scoped.
- src/subduction/network.ts -- websocket-transport adapter for
  Subduction's Transport interface, with reconnect.
- src/subduction/helpers.ts -- DocumentId <-> SedimentreeId
  conversions (zero-pad 16-byte DocIds to 32-byte SedimentreeIds);
  automergeMeta() symbol-introspection helper to access Automerge's
  internal handle.
- Persistent and in-memory signers; isomorphic-ws transport.
- IDB batching + SharedWorker compatibility for browser usage.
- Ephemeral message support routed through Subduction so peers
  connected only via websocket still receive ephemerals.
- Examples (react-counter, react-todo, react-use-presence,
  svelte-counter, sync-server) ported to the new repo.
- Subduction-tagged npm dist-tag, Nix flake updates, .npmrc.

Includes the Subduction batching API hookup (commits/fragments
batched into a single round-trip on the wasm boundary) and
NetworkAdapterInterface.state for observing adapter state changes
from the bridge.

Squashed from 21 work-in-progress commits (initial port through
"Add NetworkAdapterInterface.state"); see refs/backup/subductionjs-
original-tip for the unsquashed history.

Author: expede

.npmrc

@@ -0,0 +1,2 @@
+tag=subduction
+publish-branch=subduction-on-the-refactor-expede2

examples/react-counter/package.json

@@ -2,7 +2,7 @@
   "name": "@automerge/automerge-repo-demo-counter",
   "repository": "https://github.com/automerge/automerge-repo/tree/master/examples/react-counter",
   "private": true,
-  "version": "2.6.0-alpha.0",
+  "version": "2.6.0-subduction.7",
   "type": "module",
   "scripts": {
     "dev": "vite --open",

examples/react-counter/src/main.tsx

@@ -9,13 +9,21 @@ import {
   IndexedDBStorageAdapter,
   RepoContext,
 } from "@automerge/react"
+// @ts-ignore — initSync is not in the type declarations but is exported at runtime
+import { initSync } from "@automerge/automerge-subduction/slim"
+// @ts-ignore — wasm-base64 has no type declarations
+import { wasmBase64 } from "@automerge/automerge-subduction/wasm-base64"
 
-// We run the network & storage in a separate file and the tabs themselves are stateless and lightweight.
-// This means we only ever create one websocket connection to the sync server, we only do our writes in one place
-// (no race conditions) and we get local real-time sync without the overhead of broadcast channel.
-// The downside is that to debug any problems with the sync server you'll need to find the shared-worker and inspect it.
-// In Chrome-derived browsers the URL is chrome://inspect/#workers. In Firefox it's about:debugging#workers.
-// In Safari it's Develop > Show Web Inspector > Storage > IndexedDB > automerge-repo-demo-counter.
+// Initialize Subduction Wasm before constructing the Repo
+initSync(Uint8Array.from(atob(wasmBase64), c => c.charCodeAt(0)))
+
+// We run the network & storage in a SharedWorker so we only create one
+// Subduction WebSocket connection to the sync server and get local
+// real-time sync via MessageChannel without BroadcastChannel overhead.
+//
+// To debug the shared worker:
+//   Chrome: chrome://inspect/#workers
+//   Firefox: about:debugging#workers
 
 const sharedWorker = new SharedWorker(
   new URL("./shared-worker.ts", import.meta.url),
@@ -42,12 +50,27 @@ declare global {
 const rootDocUrl = `${document.location.hash.substring(1)}`
 let handle
 if (isValidAutomergeUrl(rootDocUrl)) {
-  handle = await repo.find(rootDocUrl)
+  // The SharedWorker connection may not be ready yet, so retry find()
+  // until the document becomes available.
+  const MAX_RETRIES = 10
+  const RETRY_MS = 500
+  for (let attempt = 0; ; attempt++) {
+    try {
+      handle = await repo.find(rootDocUrl)
+      break
+    } catch {
+      if (attempt >= MAX_RETRIES)
+        throw new Error(
+          `Document ${rootDocUrl} unavailable after ${MAX_RETRIES} retries`
+        )
+      await new Promise(r => setTimeout(r, RETRY_MS))
+    }
+  }
 } else {
   handle = repo.create<{ count: number }>({ count: 0 })
 }
 const docUrl = (document.location.hash = handle.url)
-window.handle = handle // we'll use this later for experimentation
+window.handle = handle
 window.repo = repo
 
 ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(

examples/react-counter/src/shared-worker.ts

@@ -12,27 +12,31 @@ self.addEventListener("connect", (e: MessageEvent) => {
 // even if the event arrives first.
 // Ideally Chrome would fix this upstream but this isn't a terrible hack.
 const repoPromise = (async () => {
-  const { Repo } = await import("@automerge/automerge-repo")
-  const { IndexedDBStorageAdapter } = await import(
-    "@automerge/automerge-repo-storage-indexeddb"
-  )
-  const { WebSocketClientAdapter } = await import(
-    "@automerge/automerge-repo-network-websocket"
+  const { Repo, IndexedDBStorageAdapter, MessageChannelNetworkAdapter } =
+    await import("@automerge/react")
+
+  // @ts-ignore — initSync is not in the type declarations but is exported at runtime
+  const { initSync } = await import("@automerge/automerge-subduction/slim")
+  // @ts-ignore — wasm-base64 has no type declarations
+  const { wasmBase64 } = await import(
+    "@automerge/automerge-subduction/wasm-base64"
   )
-  return new Repo({
-    storage: new IndexedDBStorageAdapter(),
-    network: [new WebSocketClientAdapter("ws://sync.automerge.org")],
-    peerId: ("shared-worker-" + Math.round(Math.random() * 10000)) as any,
-    sharePolicy: async peerId => peerId.includes("storage-server"),
-  })
+  initSync(Uint8Array.from(atob(wasmBase64), (c: string) => c.charCodeAt(0)))
+
+  return {
+    repo: new Repo({
+      storage: new IndexedDBStorageAdapter(),
+      subductionWebsocketEndpoints: ["wss://subduction.sync.inkandswitch.com"],
+      peerId: ("shared-worker-" + Math.round(Math.random() * 10000)) as any,
+      sharePolicy: async peerId => peerId.includes("storage-server"),
+    }),
+    MessageChannelNetworkAdapter,
+  }
 })()
 
 async function configureRepoNetworkPort(port: MessagePort) {
-  const repo = await repoPromise
+  const { repo, MessageChannelNetworkAdapter } = await repoPromise
 
-  const { MessageChannelNetworkAdapter } = await import(
-    "@automerge/automerge-repo-network-messagechannel"
-  )
   // be careful to not accidentally create a strong reference to port
   // that will prevent dead ports from being garbage collected
   repo.networkSubsystem.addNetworkAdapter(

examples/react-todo/package.json

@@ -2,7 +2,7 @@
   "name": "@automerge/automerge-repo-demo-todo",
   "repository": "https://github.com/automerge/automerge-repo/tree/master/examples/react-todo",
   "private": true,
-  "version": "2.6.0-alpha.0",
+  "version": "2.6.0-subduction.7",
   "type": "module",
   "scripts": {
     "dev": "vite --open",

examples/react-todo/src/main.tsx

@@ -1,12 +1,14 @@
 import {
-  DocHandle,
   Repo,
   isValidAutomergeUrl,
-  BroadcastChannelNetworkAdapter,
-  WebSocketClientAdapter,
   IndexedDBStorageAdapter,
   RepoContext,
+  BroadcastChannelNetworkAdapter,
 } from "@automerge/react"
+// @ts-ignore — initSync is not in the type declarations but is exported at runtime
+import { initSync } from "@automerge/automerge-subduction/slim"
+// @ts-ignore — wasm-base64 has no type declarations
+import { wasmBase64 } from "@automerge/automerge-subduction/wasm-base64"
 
 import React, { Suspense } from "react"
 import { ErrorBoundary } from "react-error-boundary"
@@ -15,17 +17,17 @@ import { App } from "./App.js"
 import { State } from "./types.js"
 import "./index.css"
 
+// Initialize Subduction Wasm before constructing the Repo
+initSync(Uint8Array.from(atob(wasmBase64), c => c.charCodeAt(0)))
+
 const repo = new Repo({
-  network: [
-    new BroadcastChannelNetworkAdapter(),
-    new WebSocketClientAdapter("ws://localhost:3030"),
-  ],
   storage: new IndexedDBStorageAdapter("automerge-repo-demo-todo"),
+  subductionWebsocketEndpoints: ["wss://subduction.sync.inkandswitch.com"],
 })
 
 declare global {
   interface Window {
-    handle: DocHandle<unknown>
+    handle: any
     repo: Repo
   }
 }
@@ -38,7 +40,7 @@ if (isValidAutomergeUrl(rootDocUrl)) {
   handle = repo.create<State>({ todos: [] })
 }
 const docUrl = (document.location.hash = handle.url)
-window.handle = handle // we'll use this later for experimentation
+window.handle = handle
 window.repo = repo
 
 ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(

examples/react-use-presence/package.json

@@ -1,6 +1,6 @@
 {
   "name": "automerge-use-awareness-example-project",
-  "version": "2.6.0-alpha.0",
+  "version": "2.6.0-subduction.7",
   "private": true,
   "repository": "https://github.com/automerge/automerge-repo/tree/master/examples/react-use-presence",
   "type": "module",

examples/react-use-presence/src/App.tsx

@@ -18,7 +18,7 @@ export function App({ url }: { url: AutomergeUrl }) {
   const newCount = localState?.count
   const count = doc?.count ?? 0
 
-  const peers = peerStates.getStates()
+  const peers = peerStates.peers
 
   return (
     <div>
@@ -48,7 +48,7 @@ export function App({ url }: { url: AutomergeUrl }) {
       </div>
       <div>
         Peer states:
-        {Object.values(peers).map(state => (
+        {peers.map(state => (
           <span
             key={state.peerId}
             style={{ backgroundColor: "silver", marginRight: "2px" }}
@@ -79,7 +79,7 @@ export function App({ url }: { url: AutomergeUrl }) {
           {
             doc,
             localState,
-            peerStates: Object.values(peers),
+            peerStates: peers,
           },
           null,
           2

examples/react-use-presence/src/main.tsx

@@ -4,14 +4,20 @@ import { App } from "./App"
 import {
   Repo,
   isValidAutomergeUrl,
-  BroadcastChannelNetworkAdapter,
   IndexedDBStorageAdapter,
   RepoContext,
 } from "@automerge/react"
+// @ts-ignore — initSync is not in the type declarations but is exported at runtime
+import { initSync } from "@automerge/automerge-subduction/slim"
+// @ts-ignore — wasm-base64 has no type declarations
+import { wasmBase64 } from "@automerge/automerge-subduction/wasm-base64"
+
+// Initialize Subduction Wasm before constructing the Repo
+initSync(Uint8Array.from(atob(wasmBase64), c => c.charCodeAt(0)))
 
 const repo = new Repo({
   storage: new IndexedDBStorageAdapter("use-awareness-example"),
-  network: [new BroadcastChannelNetworkAdapter()],
+  subductionWebsocketEndpoints: ["wss://subduction.sync.inkandswitch.com"],
 })
 
 const rootDocUrl = `${document.location.hash.substring(1)}`

examples/react-use-presence/vite.config.js

@@ -4,6 +4,9 @@ import wasm from "vite-plugin-wasm"
 
 export default defineConfig({
   plugins: [react(), wasm()],
+  build: {
+    target: "esnext",
+  },
   worker: {
     plugins: () => [wasm()],
   },