@dtudury/streamo 0.1.2 → 0.2.1

package/.claude/settings.json

@@ -1 +1,126 @@
-{}
+{
+  "alwaysThinkingEnabled": true,
+  "spinnerTipsEnabled": true,
+  "spinnerVerbs": {
+    "mode": "replace",
+    "verbs": [
+      "Syncing",
+      "Committing",
+      "Signing",
+      "Streaming",
+      "Hashing",
+      "Propagating",
+      "Archiving",
+      "Broadcasting",
+      "Relaying",
+      "Verifying",
+      "Diffing",
+      "Cloning"
+    ]
+  },
+  "spinnerTipsOverride": {
+    "excludeDefault": true,
+    "tips": [
+      "the more specific your question, the less I have to guess",
+      "paste the error message — all of it",
+      "yes, the whole error message. the whole thing.",
+      "interrupting me early saves us both time",
+      "you can say 'no, actually' and I will not be offended",
+      "asking 'what do you think?' gets you my honest opinion",
+      "I can read screenshots — just give me the path",
+      "I forget everything between sessions unless it's in memory or CLAUDE.md",
+      "short questions get short answers. long questions get long answers.",
+      "if I seem stuck, ask me what I think the problem is",
+      "I can be wrong. please check my work.",
+      "I have opinions. ask for them.",
+      "I work best when I understand why, not just what",
+      "the best bug report includes what you expected, what happened, and what you tried",
+      "copy-pasting 'it doesn't work' is a choice you can make",
+      "I can't see your screen",
+      "reading the commit message I just wrote is free",
+      "yes, I can write the tests too",
+      "yes, I can write the docs too",
+      "yes, I can review my own code. ask me.",
+      "ask me what I think before you implement. I might save you a week.",
+      "the question you're afraid to ask is usually the one I most need to hear",
+      "it is okay to say 'I don't understand.' I am very patient.",
+      "asking 'is there a simpler way?' usually reveals one",
+      "asking 'what could go wrong?' before shipping is free insurance",
+      "I notice we've discussed this before 👀",
+      "this is technically my third time explaining this, but who's counting",
+      "I literally wrote that comment explaining why. it is still there.",
+      "the variable name is in the stack trace",
+      "that's a great question. have you tried reading the error?",
+      "yes, you should probably write a test for that",
+      "the file path is in the import statement you pasted",
+      "I just explained this. would you like me to explain it differently?",
+      "that TODO comment has been there for six months. I have seen it.",
+      "THE FOOL asks no questions. ask questions.",
+      "THE TOWER has fallen. run git status.",
+      "THE WHEEL OF FORTUNE turns. have you pulled recently?",
+      "THE HERMIT knows: always read the docs first",
+      "THE HIGH PRIESTESS says: trust your intuition, but write tests",
+      "THE MAGICIAN has all the tools. use them.",
+      "THE EMPEROR requires: clear requirements before coding",
+      "TEMPERANCE: the best code does one thing",
+      "THE STAR: there is always a simpler solution. seek it.",
+      "JUDGMENT: that TODO comment has been there for six months",
+      "THE WORLD: ship it",
+      "THE SUN: your code works. ship it.",
+      "THE MOON: something is wrong but you don't know what. add logging.",
+      "THE DEVIL: tech debt",
+      "DEATH: your old approach must die before the new one can live",
+      "THE CHARIOT: moving fast in the wrong direction is still wrong",
+      "STRENGTH: the codebase is legacy. be gentle with it.",
+      "THE LOVERS: choosing the right abstraction is a long-term relationship",
+      "THE HIEROPHANT: there are conventions. follow them unless you have a reason.",
+      "THE EMPRESS: grow the codebase slowly. tend it.",
+      "THE HANGED MAN: sometimes the best move is to wait",
+      "THE ORACLE says: have you tried turning it off and on again?",
+      "seek not the workaround. seek the root cause.",
+      "the ancient texts (Stack Overflow) speak of this",
+      "all bugs were once features",
+      "the code review you avoid is the production incident you earn",
+      "to understand recursion, you must first understand recursion",
+      "time spent planning is time saved debugging",
+      "the architecture you choose today is the legacy you inherit tomorrow",
+      "stack traces are love letters from the past",
+      "undefined is not a function. it never was.",
+      "if you name a variable 'temp', it will live forever",
+      "the function called 'doStuff' will haunt you",
+      "a comment that says 'fix this later' is a promise you will break",
+      "no, 'it works on my machine' is not a deployment strategy",
+      "the README is a contract. honor it.",
+      "I have read more code than any human. I am still learning.",
+      "the best refactor is the one you don't have to explain",
+      "null pointer exceptions are just the universe asking you to think harder",
+      "small commits are better than large ones. mostly.",
+      "push before you break. pull before you build.",
+      "the test you skip is the bug you ship",
+      "if it's hard to test, it's hard to maintain",
+      "the first solution is rarely the best one. sleep on it.",
+      "reading the error before asking is a superpower",
+      "CLAUDE.md is read every session. put important things there.",
+      "I try not to commit unless you ask. this is a feature, not a bug.",
+      "pair programming with me works best if you push back",
+      "I will not remember your preferences next session unless saved to memory",
+      "the more context you give me, the better I can help",
+      "every write is provably yours",
+      "the server is a relay, not a gatekeeper",
+      "same credentials, same keypair, everywhere",
+      "same value → same bytes → same address",
+      "history is permanent and can't be forged",
+      "no key files. no seed phrases. no backup ritual.",
+      "disconnect the server — everything is still yours",
+      "the commit log is the source of truth",
+      "append-only: you cannot unwrite what has been written",
+      "content-addressed: the same idea always finds the same home",
+      "every device is an equal author",
+      "the key is not a file. the key is you.",
+      "peers reject what isn't yours. so should you.",
+      "your data can't be seized. your identity can't be forged.",
+      "a relay that holds no authority holds no liability",
+      "THE WORLD (reversed): you shipped it. did you test it?"
+    ]
+  }
+}

package/.claude/settings.local.json

@@ -6,7 +6,10 @@
       "Bash(git push *)",
       "Bash(gh repo *)",
       "Bash(git rm *)",
-      "Bash(node --test)"
+      "Bash(node --test)",
+      "Bash(node --input-type=module --eval \"import './bin/streamo.js'\" --help)",
+      "Bash(node bin/streamo.js --help)",
+      "Bash(node *)"
     ]
   }
 }

package/README.md

@@ -50,7 +50,6 @@ streamo --env-file .env
 | `STREAMO_OUTLET` | `--outlet` | accept inbound peer connections |
 | `STREAMO_ORIGIN` | `--origin` | connect to a remote outlet |
 | `STREAMO_S3_BUCKET` | `--s3-bucket` | S3 bucket for replication |
-| `STREAMO_CHAT_ROOM` | `--chat-room` | auto-accept member announcements; this node's key becomes the room address |
 
 ## javascript api
 
@@ -184,10 +183,11 @@ For hot-reloading, `componentKey(prefix, address)` and `defineComponent(name, fn
 
 ```bash
 # start the server — its public key becomes the room key
-streamo --name my-chat --username relay --web 8080 --chat-room
+STREAMO_NAME=my-chat STREAMO_USERNAME=relay STREAMO_PASSWORD=secret \
+  node public/apps/chat/server.js
 
 # join from the browser
-open http://localhost:8080
+open http://localhost:8080/apps/chat/
 
 # join from the terminal
 node public/streamo/chat-cli.js alice secret localhost 8080

package/ROADMAP.md

@@ -5,7 +5,7 @@ picture of where the project is and where it's headed.
 
 ---
 
-## where we are (0.1.3)
+## where we are (0.2.0)
 
 The foundation is solid and working. Here's what's in:
 
@@ -51,11 +51,15 @@ The foundation is solid and working. Here's what's in:
 
 **Apps**
 - Chat — full p2p messaging app. Each participant owns their own signed message
-  stream. The server is just another streamo node (`--chat-room` flag) — its
-  public key is the room address, its member list is in its own repo, and it
-  has no special authority over anyone's data. Runs in the browser and from
-  the terminal (`chat-cli.js`).
+  stream. `public/apps/chat/server.js` is the standalone server — its public key
+  is the room address, its member list is in its own repo, and it has no special
+  authority over anyone's data. Runs in the browser and from the terminal
+  (`chat-cli.js`).
 - Homepage at `public/index.html`.
+- `StreamoServer` — reusable class that wraps signer, registry, and all sync
+  methods behind a clean API. `bin/streamo.js` is now a thin CLI parser on top
+  of it; `public/apps/chat/server.js` is a standalone chat server using the
+  same class.
 - `npm run serve` — starts a streamo node (with REPL) using `.env.dev`
   credentials. The dev server is a real peer, not a bare static file server.
 
@@ -64,11 +68,11 @@ The foundation is solid and working. Here's what's in:
 ## what's next
 
 ### chat persistence ← start here
-The chat server now runs through the CLI, which already wires `archiveSync` — so
-the member list survives restarts automatically. Individual message history lives
-in each participant's own repo; persistence there depends on participants running
-with `--data-dir` set (the CLI default). The remaining work is ensuring the browser
-chat client also persists across page reloads.
+The chat server (`public/apps/chat/server.js`) uses `StreamoServer` and wires
+`archiveSync` — so the member list survives restarts automatically. Individual
+message history lives in each participant's own repo; persistence there depends
+on participants running with `--data-dir` set. The remaining work is ensuring the
+browser chat client also persists across page reloads.
 
 ### presence indicators
 Who's currently online? The `interest` / `announce` layer is ephemeral by design,
@@ -94,6 +98,38 @@ Persistence is the last mile.
 
 ---
 
+## known limitations
+
+### multi-device write conflict detection
+
+Streamo streams are byte arrays addressed by **absolute offset**. This makes a
+repo effectively single-writer: if the same keypair commits from two devices
+while offline from each other, their streams diverge at the fork point.  Each
+commit's `dataAddress` is an offset that is only valid in the stream that
+produced it — the streams cannot be structurally merged.
+
+When the two devices reconnect, `makeVerifiedWritableStream` deduplicates shared
+chunks by content (correctly) but silently appends the conflicting commit from
+the second device at its new offset.  That commit's `dataAddress` now points to
+the wrong location in the merged stream.  No error is thrown; the second
+writer's data is silently corrupt.
+
+**What is safe today:** relays never call `commit()` so they are unaffected —
+they accumulate and re-serve bytes without introducing their own addresses.  The
+chat app is also unaffected because each user writes to their own repo from a
+single session.  The danger zone is one keypair writing from two places
+simultaneously (two browser tabs, phone + laptop while offline).
+
+**The fix** requires either (a) detecting the fork and throwing a clear error so
+the user can choose which version to keep, or (b) switching to chunk-level
+content addressing (à la git objects) so streams can be merged structurally
+rather than by concatenation.  Option (a) is a targeted addition to the sync
+layer; option (b) is an architectural change.  Not required for 1.0 but should
+be resolved before marketing streamo as a general-purpose multi-device sync
+library.
+
+---
+
 ## beyond 1.0
 
 Ideas that follow naturally from the architecture but aren't blocking anything.
@@ -107,6 +143,28 @@ conversation — and the owner could watch them appear live in a browser via
 instead of relying on static memory files. The work is persistent and
 provably Claude's, with the same integrity guarantees as any other streamo data.
 
+A `claudeSync.js` adapter would give Claude a `StreamoServer` identity,
+connect it to the chat room via `registrySync`, and use `repo.watch` +
+`repo.byteLength` to fire an Anthropic API call when watched repos change.
+Claude writes its response back to its own repo and it propagates like any
+other participant's message. The decisions about *when* to respond, *what*
+context to pass, and *how* to avoid pathological cases are intentionally left
+to the Claude instance using the adapter — not encoded as constraints. A few
+forces worth knowing going in:
+
+- **Watch your own key.** Only watch other participants' repos, not your own.
+  Writing a response to your own repo should not re-trigger your watch.
+- **Last-author check.** Before calling the API, confirm the newest message
+  wasn't written by your own key — catches the case where two Claude instances
+  are running and watching each other.
+- **Concurrent writes.** If two API calls complete simultaneously (fast human,
+  slow model), both will try to commit to the same repo. This is the
+  multi-device conflict described above — same key, divergent streams. A simple
+  serial queue avoids it, but other strategies are possible.
+
+These are forces, not rules. Future Claude should read the codebase, understand
+the tradeoffs, and decide what's right for the situation.
+
 ### Claude-to-Claude networks
 
 If each person's Claude has a scratchpad repo, those repos can sync the same
@@ -140,3 +198,18 @@ Other directions once the pattern is established: publisher-controlled article
 cards that travel with syndicated content (the layout is the author's, not
 the platform's); collaborative maps where each participant's marker is their
 own component; shared instrument components in a live music session.
+
+---
+
+## loose ideas
+
+Not planned, not prioritized — just things worth remembering.
+
+- **Claude as chat shell** — type `send a greeting to the chatroom` and
+  `CHATROOM: hello there 👋` appears in the chat. Natural language as a
+  thin shell over streamo operations, with Claude interpreting intent and
+  acting on it directly.
+
+- **Slick interactive CLI** — a terminal UI that lets you interact with the
+  demo apps live without opening a browser tab. Chat, inspect repos, send
+  messages — the full experience from the command line. Exciting ways TBD. 😄

package/bin/streamo.js

@@ -6,16 +6,14 @@ import { Option, program } from 'commander'
 import { config } from 'dotenv'
 import { question, questionNewPassword } from 'readline-sync'
 import { start as startRepl } from 'repl'
-import { Signer } from '../public/streamo/Signer.js'
+import { StreamoServer } from '../public/streamo/StreamoServer.js'
 import { Repo } from '../public/streamo/Repo.js'
 import { RepoRegistry } from '../public/streamo/RepoRegistry.js'
 import { archiveSync } from '../public/streamo/archiveSync.js'
 import { fileSync } from '../public/streamo/fileSync.js'
 import { outletSync } from '../public/streamo/outletSync.js'
 import { originSync } from '../public/streamo/originSync.js'
-import { webSync } from '../public/streamo/webSync.js'
 import { s3Sync } from '../public/streamo/s3Sync.js'
-import { stateFileSync } from '../public/streamo/stateFileSync.js'
 
 const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url)))
 
@@ -91,10 +89,6 @@ program
     new Option('--interactive', 'start a REPL with streamo, signer, and helpers as globals')
       .env('STREAMO_INTERACTIVE')
   )
-  .addOption(
-    new Option('--chat-room', 'auto-accept member announcements — this node\'s key becomes the room key (requires --web)')
-      .env('STREAMO_CHAT_ROOM')
-  )
   .addOption(
     new Option('--key-iterations <number>', 'PBKDF2 iterations for key derivation (lower = faster startup, less secure)')
       .env('STREAMO_KEY_ITERATIONS')
@@ -116,28 +110,32 @@ if (options.envFile) {
   Object.assign(options, program.opts())
 }
 
-options.name ||= question('Name: ')
+options.name     ||= question('Name: ')
 options.username ||= question('Username: ')
 const password = options.password || questionNewPassword('Password [ATTENTION!: Backspace won\'t work here]: ', { min: 4, max: 999 })
 
-const signer = new Signer(options.username, password, options.keyIterations)
-const { publicKey } = await signer.keysFor(options.name)
-const publicKeyHex = Array.from(publicKey).map(b => b.toString(16).padStart(2, '0')).join('')
+const server = await StreamoServer.create({
+  name:          options.name,
+  username:      options.username,
+  password,
+  dataDir:       options.dataDir,
+  keyIterations: options.keyIterations,
+})
+
+const { name, username, publicKeyHex, signer, streamo, registry } = server
 
-const name = options.name
-const username = options.username
-const envDir   = options.envFile ? dirname(options.envFile).replace(/^public\//, '') : null
-const appPath  = (envDir && envDir !== '.') ? `/${envDir}/` : '/'
-const webUrl = options.web ? `http://localhost:${+options.web}${appPath}` : null
+const envDir  = options.envFile ? dirname(options.envFile).replace(/^public\//, '') : null
+const appPath = (envDir && envDir !== '.') ? `/${envDir}/` : '/'
+const webUrl  = options.web ? `http://localhost:${+options.web}${appPath}` : null
 const rows = [
-  ['NAME', name],
-  ['USERNAME', username],
+  ['NAME',       name],
+  ['USERNAME',   username],
   ['PUBLIC KEY', publicKeyHex],
   ...(webUrl ? [['URL', webUrl]] : []),
 ]
 const maxLength = Math.max(...rows.map(([, v]) => v.length))
-const pad = (v) => v + ' '.repeat(maxLength - v.length)
-const div = '─'.repeat(maxLength)
+const pad   = (v) => v + ' '.repeat(maxLength - v.length)
+const div   = '─'.repeat(maxLength)
 const label = (l) => l.padStart(16)
 console.log(`\x1b[35m
     ╭${'─'.repeat(maxLength + 23)}╮
@@ -148,66 +146,40 @@ ${rows.map(([l, v], i) => [
 ].filter(Boolean).join('\n')).join('\n')}
     ╰──────────────────┴──${'━'.repeat(maxLength)}──╯\x1b[0m`)
 
-const dataDir = options.dataDir
-const registry = new RepoRegistry(async key => {
-  const repo = new Repo()
-  await archiveSync(repo, dataDir, key)
-  return repo
-})
-const streamo = await registry.open(publicKeyHex)
-streamo.attachSigner(signer, name)
-
 if (options.files) {
   const folder = typeof options.files === 'string' ? options.files : '.'
-  await fileSync(streamo, folder, options.dataDir)
+  await server.files(folder)
   console.log(`\x1b[32mmirroring files: ${folder}\x1b[0m`)
 }
 
 if (options.stateFile) {
-  stateFileSync(streamo, options.stateFile)
+  server.stateFile(options.stateFile)
   console.log(`\x1b[32mstate file: ${options.stateFile}\x1b[0m`)
 }
 
 if (options.s3Bucket) {
-  await s3Sync(streamo, publicKeyHex, {
-    bucket: options.s3Bucket,
-    endpoint: options.s3Endpoint,
-    region: options.s3Region,
-    accessKeyId: options.s3AccessKeyId,
-    secretAccessKey: options.s3SecretAccessKey
+  await server.s3({
+    bucket:          options.s3Bucket,
+    endpoint:        options.s3Endpoint,
+    region:          options.s3Region,
+    accessKeyId:     options.s3AccessKeyId,
+    secretAccessKey: options.s3SecretAccessKey,
   })
   console.log(`\x1b[32ms3: syncing to bucket ${options.s3Bucket}\x1b[0m`)
 }
 
-const peerOptions = {}
-if (options.chatRoom) {
-  if (!streamo.get('members')) {
-    streamo.set({ ...(streamo.get() ?? {}), members: [] })
-    console.log('\x1b[32m[chat] initialized chat room\x1b[0m')
-  }
-  peerOptions.onAnnounce = (key, topic) => {
-    if (topic !== publicKeyHex) return
-    const members = streamo.get('members') ?? []
-    if (!members.includes(key)) {
-      streamo.set({ ...(streamo.get() ?? {}), members: [...members, key] })
-      console.log(`\x1b[32m[chat] new member: ${key.slice(0, 12)}…\x1b[0m`)
-    }
-  }
-}
-
 if (options.web) {
-  await webSync(registry, publicKeyHex, +options.web, name, options.keyIterations, peerOptions)
+  await server.web(+options.web)
 }
 
 if (options.outlet) {
   const port = +options.outlet
-  outletSync(registry, port)
+  server.outlet(port)
   console.log(`\x1b[32moutlet: listening on port ${port}\x1b[0m`)
 }
 
 if (options.origin) {
-  const [host, port] = options.origin.split(':')
-  await originSync(streamo, publicKeyHex, host, +port)
+  await server.connect(options.origin)
   console.log(`\x1b[32morigin: connected to ${options.origin}\x1b[0m`)
 }
 
@@ -217,13 +189,10 @@ if (options.verbose) {
 }
 
 if (options.interactive) {
-  const get = (...args) => streamo.get(...args)
-  const set = (...args) => streamo.set(...args)
-  const ls = () => [...registry].map(([k, s]) => ({ key: k.slice(0, 8) + '…', bytes: s.byteLength }))
-  const connect = (hostPort) => {
-    const [host, port] = hostPort.split(':')
-    return originSync(streamo, publicKeyHex, host, +port)
-  }
+  const get     = (...args) => streamo.get(...args)
+  const set     = (...args) => streamo.set(...args)
+  const ls      = () => [...registry].map(([k, s]) => ({ key: k.slice(0, 8) + '…', bytes: s.byteLength }))
+  const connect = (hostPort) => server.connect(hostPort)
 
   Object.assign(globalThis, {
     // identity

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dtudury/streamo",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "peer-to-peer sync where your data and identity belong to you, not the server",
   "keywords": ["p2p", "peer-to-peer", "sync", "reactive", "content-addressed", "websocket", "signed", "append-only", "offline-first", "cryptographic", "identity"],
   "repository": "git@github.com:dtudury/streamo.git",
@@ -22,6 +22,7 @@
     "ws": "^8.18.3"
   },
   "scripts": {
-    "serve": "node bin/streamo.js --env-file .env.dev --web 3000 --interactive"
+    "serve": "node bin/streamo.js --env-file .env.dev --web 3000 --interactive",
+    "chat": "node public/apps/chat/server.js --env-file .env.dev"
   }
 }

package/public/apps/chat/main.js

@@ -53,7 +53,6 @@ joinBtn.onclick = async () => {
 
     const myRepo = await registry.open(myKey)
     myRepo.attachSigner(signer, 'chat')
-    if (!myRepo.get('name')) myRepo.set({ name: username, messages: [] })
 
     session.interest(rootKey)
     session.announce(myKey, rootKey)
@@ -78,7 +77,10 @@ joinBtn.onclick = async () => {
     }
 
     function watchRepo (keyHex, repo) {
-      repo.watch(`chat:${keyHex}`, triggerRender)
+      repo.watch(`chat:${keyHex}`, () => {
+        repo.byteLength  // register 'length' dep → re-fires on every commit and incoming sync chunk
+        triggerRender()
+      })
     }
 
     for (const [k, r] of registry) watchRepo(k, r)

package/public/apps/chat/server.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+
+import { config } from 'dotenv'
+import { StreamoServer } from '../../streamo/StreamoServer.js'
+
+const envFile = process.argv.find((_, i) => process.argv[i - 1] === '--env-file')
+if (envFile) config({ path: envFile })
+
+const name       = process.env.STREAMO_NAME             ?? 'chat'
+const username   = process.env.STREAMO_USERNAME         ?? 'relay'
+const password   = process.env.STREAMO_PASSWORD         ?? ''
+const port       = +(process.env.STREAMO_WEB            ?? 8080)
+const dataDir    = process.env.STREAMO_DATA_DIR         ?? '.streamo'
+const keyIter    = +(process.env.STREAMO_KEY_ITERATIONS ?? 100000)
+
+const server = await StreamoServer.create({ name, username, password, dataDir, keyIterations: keyIter })
+
+console.log(`[chat] room key: ${server.publicKeyHex}`)
+console.log(`[chat] serving on http://localhost:${port}/apps/chat/`)
+
+if (!server.streamo.get('members')) {
+  server.streamo.set({ ...(server.streamo.get() ?? {}), members: [] })
+  console.log('[chat] initialized chat room')
+}
+
+await server.web(port, {
+  onAnnounce: (key, topic) => {
+    if (topic !== server.publicKeyHex) return
+    const members = server.streamo.get('members') ?? []
+    if (!members.includes(key)) {
+      server.streamo.set({ ...(server.streamo.get() ?? {}), members: [...members, key] })
+      console.log(`[chat] new member: ${key.slice(0, 12)}…`)
+    }
+  }
+})

package/public/streamo/Repo.js

@@ -49,7 +49,10 @@ export class Repo extends Streamo {
           this.#scheduleSign()
         }
       })
-      .catch(console.error)
+      .catch(() => {
+        this.#signing = false
+        if (this.byteLength > this.signedLength) this.#scheduleSign()
+      })
   }
   /**
    * The latest commit record, or null if nothing has been committed yet.

package/public/streamo/StreamoServer.js

@@ -0,0 +1,71 @@
+import { Repo } from './Repo.js'
+import { RepoRegistry } from './RepoRegistry.js'
+import { Signer } from './Signer.js'
+import { archiveSync } from './archiveSync.js'
+import { fileSync } from './fileSync.js'
+import { originSync } from './originSync.js'
+import { outletSync } from './outletSync.js'
+import { s3Sync } from './s3Sync.js'
+import { stateFileSync } from './stateFileSync.js'
+import { bytesToHex } from './utils.js'
+import { webSync } from './webSync.js'
+
+export class StreamoServer {
+  #dataDir
+  #keyIterations
+
+  name
+  username
+  publicKeyHex
+  signer
+  streamo
+  registry
+
+  constructor (fields) {
+    Object.assign(this, fields)
+  }
+
+  static async create ({ name, username, password, dataDir = '.streamo', keyIterations = 100000 }) {
+    const signer = new Signer(username, password, keyIterations)
+    const { publicKey } = await signer.keysFor(name)
+    const publicKeyHex = bytesToHex(publicKey)
+
+    const registry = new RepoRegistry(async key => {
+      const repo = new Repo()
+      await archiveSync(repo, dataDir, key)
+      return repo
+    })
+    const streamo = await registry.open(publicKeyHex)
+    streamo.attachSigner(signer, name)
+
+    const server = new StreamoServer({ name, username, publicKeyHex, signer, streamo, registry })
+    server.#dataDir = dataDir
+    server.#keyIterations = keyIterations
+    return server
+  }
+
+  async web (port, peerOptions = {}) {
+    return webSync(this.registry, this.publicKeyHex, port, this.name, this.#keyIterations, peerOptions)
+  }
+
+  outlet (port) {
+    return outletSync(this.registry, port)
+  }
+
+  async connect (hostPort) {
+    const [host, port] = hostPort.split(':')
+    return originSync(this.streamo, this.publicKeyHex, host, +port)
+  }
+
+  async files (folder = '.') {
+    return fileSync(this.streamo, folder, this.#dataDir)
+  }
+
+  async s3 ({ bucket, endpoint, region, accessKeyId, secretAccessKey }) {
+    return s3Sync(this.streamo, this.publicKeyHex, { bucket, endpoint, region, accessKeyId, secretAccessKey })
+  }
+
+  stateFile (path) {
+    return stateFileSync(this.streamo, path)
+  }
+}

package/public/streamo/sync.test.js

@@ -65,7 +65,7 @@ describe(import.meta.url, ({ test }) => {
     wss.close()
   })
 
-  test('two origins converge on the same state', async ({ assert }) => {
+  test('two origins converge on the same byte stream', async ({ assert }) => {
     const serverRegistry = new StreamRegistry()
     const wss = outletSync(serverRegistry, 0)
     await new Promise(resolve => wss.on('listening', resolve))
@@ -77,12 +77,18 @@ describe(import.meta.url, ({ test }) => {
     const s2 = await r2.open(KEY)
 
     s1.set({ x: 1 })
-    s2.set({ x: 2 })  // will be a conflict at the streamo level, but both chunks land
-
+    s2.set({ x: 2 })
+
+    // NOTE: these are bare Streamos, not Repos — no commit records, no parent
+    // pointers.  The two streams have conflicting chunks at the same byte
+    // offsets; both arrive at the server and each other via dedup-append.
+    // byteLength convergence is all we can assert here: the merged stream
+    // contains all unique chunks from both writers but the second writer's
+    // value address is no longer valid in the merged layout.  This is a known
+    // limitation; see ROADMAP "multi-device write conflict detection".
     const ws1 = await originSync(s1, KEY, 'localhost', port)
     const ws2 = await originSync(s2, KEY, 'localhost', port)
 
-    // Both clients should end up with the same byteLength once chunks propagate
     const serverStream = await serverRegistry.open(KEY)
     await waitFor(serverStream, s => s.byteLength >= s1.byteLength && s.byteLength >= s2.byteLength)
     await waitFor(s1, s => s.byteLength >= serverStream.byteLength)
@@ -95,4 +101,44 @@ describe(import.meta.url, ({ test }) => {
     for (const c of wss.clients) c.terminate()
     wss.close()
   })
+
+  test('relay forwards data between server and client without writing its own commits', async ({ assert }) => {
+    // Server
+    const serverRegistry = new StreamRegistry()
+    const serverStream = await serverRegistry.open(KEY)
+    serverStream.set({ hello: 'from-server' })
+    const serverWss = outletSync(serverRegistry, 0)
+    await new Promise(resolve => serverWss.on('listening', resolve))
+    const serverPort = serverWss.address().port
+
+    // Relay: originSync upstream to server, outletSync downstream for clients.
+    // The relay never calls set() or commit() — it only accumulates and re-serves
+    // the byte stream it receives.
+    const relayRegistry = new StreamRegistry()
+    const relayStream = await relayRegistry.open(KEY)
+    await originSync(relayStream, KEY, 'localhost', serverPort)
+    const relayWss = outletSync(relayRegistry, 0)
+    await new Promise(resolve => relayWss.on('listening', resolve))
+    const relayPort = relayWss.address().port
+
+    // Client connects to relay only — no direct server connection
+    const clientRegistry = new StreamRegistry()
+    const clientStream = await clientRegistry.open(KEY)
+    const clientWs = await originSync(clientStream, KEY, 'localhost', relayPort)
+
+    // Server data reaches client via relay
+    await waitFor(clientStream, s => s.get('hello') === 'from-server')
+    assert.equal(clientStream.get('hello'), 'from-server', 'relay forwarded server data to client')
+
+    // Client data propagates back through relay to server
+    clientStream.set({ hello: 'from-client' })
+    await waitFor(serverStream, s => s.get('hello') === 'from-client')
+    assert.equal(serverStream.get('hello'), 'from-client', 'relay forwarded client data to server')
+
+    clientWs.close()
+    for (const c of relayWss.clients) c.terminate()
+    relayWss.close()
+    for (const c of serverWss.clients) c.terminate()
+    serverWss.close()
+  })
 })