[Incremental Research] 2026-02-19_09:35

modules/autobase.md

@@ -1,42 +1,158 @@
-# Autobase
+# Autobase v7.25.1 - Multi-Writer Event Sourcing Deep Dive
 
-## Overview
+## Introduction & Overview
 
-Multi-writer merge for Hypercores (event sourcing DAG linearization).
+Autobase is Holepunch's solution for multi-writer coordination: merges multiple Hypercores into a single, eventually consistent linear history via causal DAG linearization. Powers collaborative apps with quorum-signed checkpoints and deterministic views.
 
-**Key Features:**
-- Causal ordering
-- Quorum-signed checkpoints
-- Optimistic appends
-- View derivation (apply fn)
+**Version**: 7.25.1
+**GitHub**: [holepunchto/autobase](https://github.com/holepunchto/autobase)
+**Docs**: Integrated in Pear/Holepunch docs
+**Key Metrics**:
+- Event Sourcing DAG → Linearized View
+- Quorum Acks for convergence
+- Optimistic appends, encryption support
 
-Links: [GitHub](https://github.com/holepunchto/autobase)
+**Core Mechanics**:
+- **Writers Append**: Reference priors (DAG)
+- **Linearizer**: Topsort + checkpoints
+- **Views**: `apply(nodes, view, host)` – deterministic reducer
+- **Indexers**: Sign lengths for fast-forward
 
-## Architecture
+Used in collab editors, federated feeds, shared state.
+
+## Architecture Deep Dive
+
+DAG of writer nodes → Quorum-signed linear order → View appends.
+
+### Mermaid Flow
+```mermaid
+graph TD
+    subgraph \"Writers (Hypercores)\"
+        W1[Writer1] --> N1[Node: value + refs]
+        W2[Writer2] --> N2[Node]
+        W3[Writer3] --> N3[Node]
+    end
+    N1 --> L[Linearizer<br/>Topsort + Acks]
+    N2 --> L
+    N3 --> L
+    L --> C[Checkpoints<br/>Signed Length]
+    subgraph \"View (e.g. Hyperbee)\"
+        V[View Core] <-- A[apply(nodes)]
+    end
+    C --> FF[Fast-Forward]
+    H[Host: addWriter/ack/interrupt] -.-> L
+```
+
+**Node Structure** (compact-encoding):
+- `value`, `references[]` (causal deps), `from` (writer key)
+
+**Phases**:
+1. Append → DAG build
+2. Update → Fetch + linearize
+3. Apply → Reducer on view
+
+**Internals**: core-coupler for multi-core sync, index-encoder for proofs.
+
+## Full API Reference
+
+### Constructor
+```js
+const base = new Autobase(store, bootstrapKey, {
+  apply: async (nodes, view, host) => { ... },
+  open: (store, host) => store.get('view'),
+  optimistic: true,
+  encryptionKey,
+  wakeup: new ProtomuxWakeup()
+})
+```
+
+| Opt | Description |
+|-----|-------------|
+| `apply` | Reducer: process nodes, use host.addWriter() |
+| `open` | Factory: return view core (Hyperbee/etc) |
+| `optimistic` | Allow non-writers append w/ verification |
+
+### Properties & Ops
+| Property/Method | Notes |
+|-----------------|-------|
+| `base.view` | Derived core |
+| `base.length` / `signedLength` | System progress |
+| `await base.append(value)` | Add node |
+| `await base.update()` | Fetch/linearize |
+| `base.heads()` | Causal forks |
+| `base.hash()` | Merkle root |
+
+**Host Calls** (in apply):
+- `host.addWriter(key, {indexer: true})`
+- `host.ackWriter(key)` (optimistic)
+- `host.interrupt(reason)` (escape hatch)
+
+**Replication**: `base.replicate(conn)` via corestore.
+
+### Events
+- `update`: Post-apply
+- `interrupt(reason)`
+- `fast-forward(to, from)`
+- `is-indexer`, `writable`
+
+## Performance & Optimizations
+- **Big Batches**: `base.setBigBatches()` – Larger apply chunks
+- **Auto-Ack**: `ackInterval: 1000`
+- **Wakeups**: Protomux hints active writers
+- **FF**: Skip to signedLength
+
+**Scaling**: Quorum advances checkpoint → O(1) catchup.
+
+## Interconnections
+- **Views**: Hyperbee (CRDT state), Hypercore (logs)
+- **Discovery**: Hyperswarm on `discoveryKey`
+- **Encryption**: Per-base keys
+- **Stack**: Writers → Autobase → Hyperdrive/Hyperbee
 
 ```
 mermaid
 graph LR
-  A[Writer Append] --> B[DAG]
-  B --> C[Linearizer]
-  C --> D[View Apply]
+    Collab[Collab App] --> Autobase
+    Autobase --> Hyperbee[View]
+    Hyperbee --> Hyperswarm[Replicate]
 ```
 
-## API Highlights
+## Code Examples
 
+**Basic Collab Counter**:
 ```js
-const base = new Autobase(store, bootstrapKey, { apply, open })
-await base.append(data)
-await base.update()
+async function apply(nodes, view, host) {
+  for (const {value} of nodes) {
+    if (value.addWriter) {
+      await host.addWriter(value.addWriter)
+      continue
+    }
+    await view.append(value.delta) // Assume view is counter-log
+  }
+}
+
+const base = new Autobase(store, null, {apply, open: s => s.get('counter')})
+await base.append({delta: +1})
 ```
 
-## Dependencies
-- Hypercore (writers/views)
-
-## Use Cases
-- Collaborative editing
-- Multi-user DB
-- Federated feeds
+**Optimistic Chat**:
+```js
+async function apply(nodes, view, host) {
+  for (const n of nodes) {
+    const msg = n.value
+    if (!verifySig(msg.sender, msg)) continue // Verify
+    await host.ackWriter(n.from.key)
+    await view.append(msg.text)
+  }
+}
+```
 
 ## Limitations
-- Needs indexers for convergence
+- **Reordering**: Views must be deterministic (no side effects)
+- **Quorum Need**: Indexers must overlap for progress
+- **DAG Depth**: Long forks slow linearize
+
+## Advanced: Workshops
+- hyperdb-autobase-workshop: Migration patterns
+
+**Char Count**: ~4600