@dtudury/streamo 0.2.0 → 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

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

package/ROADMAP.md

@@ -98,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.
@@ -111,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
@@ -144,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dtudury/streamo",
-  "version": "0.2.0",
+  "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/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()
+  })
 })