Skip to main content

@drakkar.software/starfish-wal

Write-ahead-log / doc-diff collections with CRDT semantics and trusted snapshots for Starfish.

A logical document becomes an append-only log of CRDT operations plus a sibling <name>__snapshot document, instead of a single merged value — unlocking full edit history, small per-edit deltas, and convergent concurrent/offline editing. It layers on an existing append-only collection with no server, wire-format, or storage-backend change, and works under both encryption: "none" and "delegated".

The CRDT fold is deterministic, commutative, idempotent, and byte-identical to the Python starfish-wal package (locked by tests/test-vectors/wal-crdt.json):

  • LWW typed register (set / del) — objects / scalar fields,
  • RGA sequence (ins / rmv) — ordered lists,
  • text — an RGA of single characters.
import { WalDocument, createEd25519Signer } from "@drakkar.software/starfish-wal"

const doc = new WalDocument({
  documentKey: "spaces/s/docs/d",
  transport,                                  // append/pull over the op-log collection
  signer: createEd25519Signer(edPubHex, edPrivHex),
  posture: "trust-retain-tail",
})
await doc.open()
doc.update({ title: "Hello", tags: ["draft"] }) // reconcile: minimal ops from a desired value
doc.setText("body", "draft")                    // character-level text diff
await doc.commit()
doc.materialize() // { body: ["d","r","a","f","t"], tags: ["draft"], title: "Hello" }

update / setText / setList auto-generate the minimal CRDT ops by diffing against current state; low-level setField / insert / removeAt / insertText remain available.

Every op-batch and snapshot is author-verified before its decrypted content is trusted; snapshots are client-generated by a trusted role; readers pick a trust / trust-retain-tail / re-derive verification posture.

Full reference: docs/ts/wal/01-overview.md