dignity.js 0.7.0 → 0.8.0

package/docs/assets/playground-demos.js

@@ -144,8 +144,10 @@ const bob = new DignityP2P({ nodeId: 'bob', networkAdapter: new InMemoryNetworkA
 helpers.track(alice, bob);
 
 let received = null;
-bob.on('directmessage', (event) => {
-  received = event.payload;
+bob.on('message', (event) => {
+  if (event.senderId === 'alice' && event.type === 'chat') {
+    received = event.payload;
+  }
 });
 
 await alice.start();
@@ -321,11 +323,13 @@ const rotationResult = await revokeAndRotateIdentity({
 await alice.start();
 await bob.start();
 
+await alice.adoptDerivedIdentityKeyPair(gen1, { generation: 1 });
 bob.registerPeerPublicKey('alice', keyPairToPublicBundle(gen1), { generation: 1 });
 log('bob gen before:', bob.getPeerIdentityGeneration('alice'));
 
-await alice.adoptDerivedIdentityKeyPair(rotationResult.nextKeyPair, { generation: 2 });
+// Broadcast while alice still signs with gen-1 keys; then adopt gen-2 locally.
 await alice.broadcastIdentityRotation(rotationResult.rotation, { broadcastScope: 'identity:alice' });
+await alice.adoptDerivedIdentityKeyPair(rotationResult.nextKeyPair, { generation: 2 });
 await helpers.sleep(50);
 
 log('bob gen after:', bob.getPeerIdentityGeneration('alice'));
@@ -334,5 +338,61 @@ log('keys upgraded:', bob.getPeerIdentityState('alice')?.publicKey?.signingPubli
 
 await alice.stop();
 await bob.stop();`
+  },
+  {
+    id: 'cqrs-replica',
+    title: 'CQRS — publisher + query replica',
+    description: 'Domain events from a tiered PeerGroup hydrate a read-only DignityQueryReplica.',
+    code: `const { DignityP2P, DignityQueryReplica, InMemoryNetworkHub, InMemoryNetworkAdapter } = dignity;
+
+const hub = new InMemoryNetworkHub();
+const security = helpers.fastSecurity();
+
+const publisher = new DignityP2P({
+  nodeId: 'publisher',
+  networkAdapter: new InMemoryNetworkAdapter(hub),
+  security
+});
+const reader = new DignityP2P({
+  nodeId: 'reader',
+  networkAdapter: new InMemoryNetworkAdapter(hub),
+  security
+});
+
+helpers.track(publisher, reader);
+await publisher.start();
+await reader.start();
+
+await publisher.joinPeerGroup('feed:demo', {
+  role: 'publisher',
+  tiered: true,
+  liveCap: 100,
+  domainEvents: true,
+  fanout: 2,
+  maxActivePeers: 4
+});
+
+const replica = new DignityQueryReplica(reader, {
+  groupId: 'feed:demo',
+  collections: ['posts'],
+  publisherId: 'publisher'
+});
+await replica.start({ bootstrapPeerIds: ['publisher'] });
+await helpers.sleep(40);
+
+await publisher.create('posts', { text: 'CQRS demo post' }, {
+  id: 'p1',
+  peerGroupId: 'feed:demo'
+});
+await helpers.sleep(60);
+
+const record = replica.read('posts', 'p1');
+log('replica read:', JSON.stringify(record?.data));
+log('chain ok:', replica.verifyChain().ok);
+log('stats:', JSON.stringify(replica.getViewStats()));
+
+await replica.stop();
+await publisher.stop();
+await reader.stop();`
   }
 ];

package/docs/assets/playground.css

@@ -155,20 +155,68 @@
   color: #cf222e;
 }
 
-#code-editor {
+.playground-editor-wrap {
+  position: relative;
   flex: 1;
+  min-height: 360px;
+  overflow: hidden;
+  display: grid;
+  background: var(--bg);
+}
+
+.playground-editor-highlight,
+#code-editor {
+  grid-area: 1 / 1;
   width: 100%;
+  height: 100%;
   min-height: 360px;
   margin: 0;
   padding: 16px;
   border: 0;
-  resize: none;
   font-family: var(--font-mono);
   font-size: 0.875rem;
   line-height: 1.55;
-  color: var(--text);
-  background: var(--bg);
   tab-size: 2;
+  overflow: auto;
+  white-space: pre;
+  word-wrap: normal;
+  overflow-wrap: normal;
+  box-sizing: border-box;
+}
+
+.playground-editor-highlight {
+  pointer-events: none;
+  z-index: 0;
+  background: var(--bg);
+  color: var(--text);
+}
+
+.playground-editor-highlight code {
+  display: block;
+  min-height: calc(100% - 32px);
+  padding: 0;
+  margin: 0;
+  font: inherit;
+  line-height: inherit;
+  background: transparent !important;
+  border: 0 !important;
+  border-radius: 0 !important;
+  color: inherit;
+}
+
+.playground-editor-highlight code.hljs {
+  padding: 0 !important;
+  border: 0 !important;
+  border-left: 0 !important;
+}
+
+#code-editor {
+  resize: none;
+  z-index: 1;
+  color: transparent !important;
+  -webkit-text-fill-color: transparent !important;
+  caret-color: var(--text);
+  background: transparent;
 }
 
 #code-editor:focus {
@@ -176,6 +224,24 @@
   box-shadow: inset 0 0 0 2px var(--accent-soft);
 }
 
+#code-editor::selection {
+  background: rgba(91, 127, 255, 0.35);
+  color: transparent;
+  -webkit-text-fill-color: transparent;
+}
+
+@media (prefers-color-scheme: dark) {
+  .playground-editor-wrap,
+  .playground-editor-highlight {
+    background: #0d1117;
+    color: #e6edf3;
+  }
+
+  #code-editor {
+    caret-color: #e6edf3;
+  }
+}
+
 #output {
   flex: 1;
   min-height: 360px;

package/docs/assets/playground.js

@@ -6,6 +6,8 @@ const els = {
   featureSelect: document.getElementById('feature-select'),
   featureDesc: document.getElementById('feature-desc'),
   editor: document.getElementById('code-editor'),
+  highlightCode: document.getElementById('code-highlight'),
+  highlightPre: document.querySelector('.playground-editor-highlight'),
   runBtn: document.getElementById('run-btn'),
   resetBtn: document.getElementById('reset-btn'),
   clearBtn: document.getElementById('clear-btn'),
@@ -13,6 +15,8 @@ const els = {
   status: document.getElementById('run-status')
 };
 
+let highlightTimer = null;
+
 let activeCleanup = null;
 let running = false;
 
@@ -26,10 +30,48 @@ function populateFeatureSelect() {
   ).join('');
 }
 
+function syncEditorScroll() {
+  if (!els.highlightPre) {
+    return;
+  }
+  els.highlightPre.scrollTop = els.editor.scrollTop;
+  els.highlightPre.scrollLeft = els.editor.scrollLeft;
+}
+
+function updateHighlight() {
+  if (!els.highlightCode || typeof hljs === 'undefined') {
+    return;
+  }
+
+  const source = els.editor.value;
+  els.highlightCode.textContent = source.endsWith('\n') ? source : `${source}\n`;
+
+  if (typeof hljs.highlight === 'function') {
+    const { value } = hljs.highlight(source, { language: 'javascript' });
+    els.highlightCode.innerHTML = value;
+    els.highlightCode.classList.add('hljs', 'language-javascript');
+  } else {
+    hljs.highlightElement(els.highlightCode);
+  }
+
+  syncEditorScroll();
+}
+
+function scheduleHighlight() {
+  if (highlightTimer) {
+    cancelAnimationFrame(highlightTimer);
+  }
+  highlightTimer = requestAnimationFrame(() => {
+    highlightTimer = null;
+    updateHighlight();
+  });
+}
+
 function loadDemo(demo, { pushHash = true } = {}) {
   els.featureSelect.value = demo.id;
   els.featureDesc.textContent = demo.description;
   els.editor.value = demo.code;
+  scheduleHighlight();
   if (pushHash) {
     history.replaceState(null, '', `#${demo.id}`);
   }
@@ -151,7 +193,10 @@ async function runCode() {
   }
 }
 
-function initEditorTabs() {
+function initEditor() {
+  els.editor.addEventListener('input', scheduleHighlight);
+  els.editor.addEventListener('scroll', syncEditorScroll);
+
   els.editor.addEventListener('keydown', (event) => {
     if (event.key !== 'Tab') {
       return;
@@ -161,6 +206,7 @@ function initEditorTabs() {
     const next = `${value.slice(0, selectionStart)}  ${value.slice(selectionEnd)}`;
     els.editor.value = next;
     els.editor.selectionStart = els.editor.selectionEnd = selectionStart + 2;
+    scheduleHighlight();
   });
 }
 
@@ -172,7 +218,8 @@ function initFromHash() {
 
 populateFeatureSelect();
 initFromHash();
-initEditorTabs();
+initEditor();
+updateHighlight();
 
 els.featureSelect.addEventListener('change', () => {
   loadDemo(getDemoById(els.featureSelect.value));

package/docs/assets/styles.css

@@ -14,7 +14,7 @@
   --green: #1a7f37;
   --green-bg: #dafbe1;
   --sidebar-width: 280px;
-  --header-height: 56px;
+  --header-height: 64px;
   --content-max: 920px;
   --radius: 8px;
   --shadow: 0 1px 3px rgba(27, 31, 36, 0.08);
@@ -135,7 +135,7 @@ pre code.hljs {
 }
 
 .site-header__brand img {
-  height: 40px;
+  height: 54px;
   width: auto;
 }
 

package/docs/index.html

@@ -3,7 +3,7 @@
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <meta name="description" content="dignity.js v0.6.0 — REST-like P2P object API for decentralized JavaScript applications." />
+    <meta name="description" content="dignity.js v0.8.0 — REST-like P2P object API for decentralized JavaScript applications." />
     <title>dignity.js · Documentation</title>
     <link rel="icon" href="./assets/favicon.svg" type="image/svg+xml" />
     <link rel="icon" href="./favicon.ico" sizes="32x32" />
@@ -16,7 +16,7 @@
       <a class="site-header__brand" href="#overview">
         <img src="./assets/dignity-logo.svg" alt="" width="344" height="80" />
         <!-- <span>dignity.js</span> -->
-        <span class="site-header__version">v0.6.0</span>
+        <span class="site-header__version">v0.8.0</span>
       </a>
       <div class="site-header__links">
         <a href="https://www.npmjs.com/package/dignity.js" target="_blank" rel="noopener noreferrer">npm</a>
@@ -47,6 +47,7 @@
             <a href="#object-api">Object API</a>
             <a href="#discovery">Room discovery</a>
             <a href="#peer-groups">PeerGroup gossip</a>
+            <a href="#cqrs-tiers">CQRS tiers</a>
             <a href="#messaging">Direct messaging</a>
             <a href="#concurrency">Concurrency</a>
             <a href="#content-hashes">Content hashes</a>
@@ -96,6 +97,10 @@
                 <h3>Content hashes</h3>
                 <p><code>record.hash</code> — <code>sha512:</code> digests over canonical <code>data</code> via <code>stableStringify</code>.</p>
               </article>
+              <article class="card">
+                <h3>CQRS PeerGroups (v0.8+)</h3>
+                <p>Live + bulk tiers, signed domain events, and <code>DignityQueryReplica</code> read views for massive audiences.</p>
+              </article>
             </div>
           </section>
 
@@ -480,7 +485,7 @@ await node.leaveDiscovery('team:red');</code></pre>
   bootstrapPeerIds: [hostPeerId],
   fanout: 3,
   maxActivePeers: 8,
-  maxHops: 6,
+  maxHops: 64,
   metadata: { role: 'spectator' }
 });
 
@@ -521,6 +526,14 @@ node.getPeerGroupStats();
                     <td><code>record:snapshot</code></td>
                     <td>Late-joiner catch-up</td>
                   </tr>
+                  <tr>
+                    <td><code>domain:event</code></td>
+                    <td>Signed, versioned write event (auto-published on CRUD when <code>domainEvents: true</code>)</td>
+                  </tr>
+                  <tr>
+                    <td><code>domain:checkpoint</code></td>
+                    <td>Bulk-tier catch-up anchor (<code>lastEventHash</code>, <code>recordCount</code>)</td>
+                  </tr>
                   <tr>
                     <td>App-defined</td>
                     <td>Custom payloads via <code>publishToPeerGroup</code> (emits <code>peergroupmessage</code>)</td>
@@ -539,6 +552,46 @@ node.getPeerGroupStats();
               <li>Set <code>relayEnabled: false</code> on a group to receive updates without re-forwarding.</li>
             </ul>
 
+            <h3 id="cqrs-tiers">CQRS tiers &amp; query replicas (v0.8+)</h3>
+            <p>
+              For audiences above ~5&nbsp;000 subscribers <em>per publisher</em>, use the command/query split:
+              publishers write locally and emit signed domain events; subscribers maintain read-only materialized views.
+            </p>
+            <ul>
+              <li><strong>Live tier</strong> — first <code>liveCap</code> subscribers (default 5&nbsp;000) receive real-time gossip via <code>publishToPeerGroup</code>.</li>
+              <li><strong>Bulk tier</strong> — overflow subscribers receive batched updates via <code>publishPeerGroupBulk</code> and elected bulk relays.</li>
+              <li><strong>Domain events</strong> — every <code>create</code> / <code>update</code> / <code>remove</code> on a publisher group auto-emits <code>domain:event</code> with hash-chain linking.</li>
+              <li><strong>Query replica</strong> — <code>DignityQueryReplica</code> hydrates local <code>read</code> / <code>list</code> views without contacting the owner.</li>
+            </ul>
+            <div class="code-block">
+              <pre><code class="language-javascript">const { DignityP2P, DignityQueryReplica } = dignity;
+
+// Publisher (command path)
+await publisher.joinPeerGroup('feed:alice', {
+  role: 'publisher',
+  tiered: true,
+  liveCap: 5000,
+  domainEvents: true
+});
+await publisher.create('posts', { text: 'hello' }, {
+  id: 'p1',
+  peerGroupId: 'feed:alice'   // auto-publishes domain:event
+});
+
+// Read-only replica (query path)
+const replica = new DignityQueryReplica(reader, {
+  groupId: 'feed:alice',
+  collections: ['posts'],
+  publisherId: 'alice'
+});
+await replica.start({ bootstrapPeerIds: ['alice'] });
+replica.read('posts', 'p1');
+replica.verifyChain();  // hash-chain consistency</code></pre>
+            </div>
+            <p>
+              Try the <a href="./playground/index.html">live playground</a> demo <em>CQRS — publisher + query replica</em>.
+            </p>
+
             <h3>Chess spectators</h3>
             <p>
               The <a href="./chess/index.html">3D Chess demo</a> mixes both replication modes:
@@ -573,8 +626,8 @@ node.getPeerGroupStats();
                   </tr>
                   <tr>
                     <td><code>maxHops</code></td>
-                    <td>6</td>
-                    <td>Covers large graphs with low diameter</td>
+                    <td>64</td>
+                    <td>Covers large graphs (fanout³×⁶⁴) without per-group tuning</td>
                   </tr>
                   <tr>
                     <td><code>globalMaxOpenConnections</code></td>
@@ -591,6 +644,9 @@ node.getPeerGroupStats();
             </div>
 
             <h3>Roadmap</h3>
+            <p><strong>v0.8.0 (current)</strong> — CQRS tiered PeerGroups, domain events, DignityQueryReplica, hash chains, bulk relay, maxHops 64.</p>
+            <p><strong>v0.7.1</strong> — live docs playground, demo fixes, syntax highlighting.</p>
+            <p><strong>v0.7.0 (shipped)</strong> — credential-derived keys, identity rotation, PeerGroup hardening, stress harness.</p>
             <p><strong>v0.6.0 (shipped)</strong> — core gossip, chess spectators, unit + e2e tests.</p>
             <p><strong>v0.6.x polish</strong> — <code>subscribeObjectFeed</code> wrapper, connection LRU trim, IndexedDB joined-group persistence, React <code>usePeerGroup</code> hook, 50+ node integration test.</p>
             <p><strong>Future</strong> — publisher rate limits, partial snapshot / delta feeds, cross-group fan-in metrics.</p>
@@ -912,7 +968,7 @@ const pool = createDefaultSignalingPool({
                 <tbody>
                   <tr>
                     <td><code>dignity.js</code></td>
-                    <td><code>DignityP2P</code>, <code>IndexedDBPersistence</code>, signaling providers, in-memory adapters, security utilities</td>
+                    <td><code>DignityP2P</code>, <code>DignityQueryReplica</code>, <code>IndexedDBPersistence</code>, signaling providers, in-memory adapters, PeerGroup + CQRS helpers (<code>domain-events</code>, <code>peer-group-tiers</code>, <code>bulk-relay</code>), security utilities</td>
                   </tr>
                   <tr>
                     <td><code>dignity.js/react</code></td>
@@ -963,10 +1019,10 @@ const pool = createDefaultSignalingPool({
           <section id="development" class="section">
             <h2>Development</h2>
             <div class="code-block">
-              <pre><code class="language-bash"># Run tests (237+ passing, ~91% line coverage)
+              <pre><code class="language-bash"># Run tests (289+ passing)
 npm test
 
-# PeerGroup unit + e2e tests only
+# PeerGroup + CQRS unit + integration tests
 npm run test:peer-group
 
 # Build browser + Node bundles
@@ -983,7 +1039,7 @@ npm run example:chess</code></pre>
 
           <footer class="site-footer">
             <p>
-              dignity.js v0.6.0 ·
+              dignity.js v0.8.0 ·
               <a href="https://github.com/jose-compu/dignity.js/blob/main/LICENSE">Apache 2.0</a> ·
               <a href="https://github.com/jose-compu/dignity.js">GitHub</a> ·
               <a href="https://www.npmjs.com/package/dignity.js">npm</a>

package/docs/openapi-like.json

@@ -1,6 +1,6 @@
 {
   "name": "dignity.js",
-  "version": "0.5.4",
+  "version": "0.8.0",
   "description": "REST-like object API over peer-to-peer replication",
   "resources": {
     "collections/{collection}/{id}": {
@@ -60,18 +60,31 @@
       "broadcastMessage": "custom app messages; options.connectToPeers"
     },
     "peerGroups": {
-      "joinPeerGroup": "join scalable gossip group (multiplexed); options.fanout, maxActivePeers, bootstrapPeerIds",
+      "joinPeerGroup": "join scalable gossip group; options: fanout, maxActivePeers, maxHops (default 64), role, tiered, liveCap, tierMode, domainEvents, publisherId",
       "leavePeerGroup": "leave gossip group and scoped presence",
       "listPeerGroupMembers": "list presence in gossip:{groupId} scope",
-      "publishToPeerGroup": "epidemic publish with bounded fanout; inner types: operation, record:snapshot, custom",
+      "publishToPeerGroup": "epidemic publish to live tier when tiered; inner types: operation, record:snapshot, domain:event, custom",
+      "publishPeerGroupBulk": "bulk-tier publish (publisher only); batched domain events and checkpoints",
+      "publishPeerGroupCheckpoint": "publish domain-event chain checkpoint to bulk tier",
       "publishRecordToPeerGroup": "publish normalized record snapshot into gossip group",
+      "getPeerGroupConfig": "returns joined group config including tier and domainEvents flags",
       "getPeerGroupStats": "{ joinedGroups, seenGossipCount, openConnectionCount, globalMaxOpenConnections }"
+    },
+    "cqrs": {
+      "DignityQueryReplica": "read-only materialized view from domain events; methods: start, stop, read, list, verifyChain, getViewStats",
+      "domainEvents": "operationToDomainEvent, verifyDomainEvent, verifyEventChain, DOMAIN_EVENT_SCHEMA_VERSION",
+      "tiers": "assignPeerGroupTier, DEFAULT_LIVE_CAP (5000), filterPeersByTier",
+      "bulkRelay": "electBulkRelays, DEFAULT_BULK_RELAY_COUNT"
     }
   },
   "events": {
     "change": "object create/update/delete/snapshot applied",
     "conflict": "local or remote version mismatch",
-    "warning": "orphan-operation, peer-connect-failed, presence failures, content-hash-mismatch",
+    "warning": "orphan-operation, peer-connect-failed, presence failures, content-hash-mismatch, domain-event-rejected",
+    "domainevent": "signed domain event applied or emitted locally",
+    "chainbroken": "domain event hash chain verification failed",
+    "bulkrelaychanged": "bulk relay peer set changed for a tiered group",
+    "checkpointpublished": "publisher published domain-event checkpoint",
     "peerdiscovered": "peer joined discovery scope",
     "peerleft": "peer left or timed out",
     "message": "custom decrypted message received"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dignity.js",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "P2P object API for decentralized JavaScript applications",
   "homepage": "https://jose-compu.github.io/dignity.js/",
   "repository": {
@@ -41,7 +41,7 @@
   "scripts": {
     "test": "jest --coverage",
     "test:unit": "jest tests/unit --runInBand",
-    "test:peer-group": "jest tests/unit/peer-group-gossip.test.js tests/unit/peer-group-helpers.test.js tests/integration/peer-group-gossip-e2e.test.js --runInBand --coverage=false",
+    "test:peer-group": "jest tests/unit/peer-group-gossip.test.js tests/unit/peer-group-helpers.test.js tests/unit/domain-events.test.js tests/unit/peer-group-tiers.test.js tests/unit/query-replica.test.js tests/unit/view-consistency.test.js tests/integration/peer-group-gossip-e2e.test.js tests/integration/cqrs-tiered-peergroup.test.js --runInBand --coverage=false",
     "test:stress-peer-group": "RUN_STRESS_TESTS=1 jest tests/stress/peer-group-scale.test.js --runInBand --coverage=false",
     "stress:peer-group": "node scripts/stress-peer-group.js",
     "test:cloudflare-live": "RUN_CLOUDFLARE_LIVE_TESTS=1 jest tests/integration/cloudflare-signaling-live.test.js --runInBand",