@dtudury/streamo 0.2.0 → 1.0.0

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/README.md

@@ -204,8 +204,7 @@ node --test public/streamo/Repo.test.js  # single file
 
 ## roadmap
 
-See [ROADMAP.md](./ROADMAP.md) for what's been built, what's next, and what we're
-aiming at for 1.0.
+See [ROADMAP.md](./ROADMAP.md) for what's been built and what's next.
 
 ## collaboration
 

package/ROADMAP.md

@@ -5,9 +5,9 @@ picture of where the project is and where it's headed.
 
 ---
 
-## where we are (0.2.0)
+## where we are (1.0.0)
 
-The foundation is solid and working. Here's what's in:
+The foundation is solid, tested, and shipped. Here's what's in:
 
 **Core data layer**
 - `Streamo` — reactive, content-addressed, append-only byte store with a
@@ -54,7 +54,8 @@ The foundation is solid and working. Here's what's in:
   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`).
+  (`chat-cli.js`). Message history persists across page reloads via server-side
+  archiving — rejoin with the same credentials and your history comes back.
 - 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
@@ -67,13 +68,6 @@ The foundation is solid and working. Here's what's in:
 
 ## what's next
 
-### chat persistence ← start here
-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,
 so presence is a heartbeat + timeout — announce yourself periodically, time out
@@ -86,15 +80,37 @@ real-world test of the UI layer.
 
 ---
 
-## toward 1.0
+---
+
+## known limitations
 
-One thing blocking a stable `1.0` claim:
+### multi-device write conflict detection
 
-1. **Chat persistence** — a chat app that loses history on restart isn't production-ready
+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.
 
-Chat signing is done. Components, keyed list reconciliation, SVG namespaces,
-`class` arrays/objects, and the CLI server unification are all done.
-Persistence is the last mile.
+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.
 
 ---
 
@@ -111,6 +127,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 +182,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": "1.0.0",
   "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()
+  })
 })