Updates

core-infrastructure/hyper-p2p-vector-clock/docs/architecture.md

@@ -1,44 +1,52 @@
 # Architecture: hyper-p2p-vector-clock
 
-**Category:** Core infrastructure
+**Category:** `core-infrastructure` · **Protocol:** `vector-clock/v1`
+
+## Role
+
+Reusable vector clock for causal ordering across P2P peers: tick, merge, compare, prune, optional Hyperbee persistence and gossip sync.
 
 ```mermaid
 flowchart LR
-  App[Application] --> Mod[HyperP2PVectorClock]
-  Mod --> Mux[Protomux vector-clock/v1]
-  Mux --> Swarm[Hyperswarm]
+  App[CRDT / memory / bus] --> VC[VectorClock]
+  VC --> P2P[p2p-bare gossip]
+  VC --> HB[Hyperbee optional]
 ```
 
-## Sequence (P2P)
+## Sequence
 
 ```mermaid
 sequenceDiagram
-  participant App
-  participant Mod as Module
-  participant SW as Hyperswarm
-  participant Peer
-  App->>Mod: ready(topic)
-  Mod->>SW: join(topic)
-  SW->>Peer: connection
-  Mod->>Peer: gossip / Protomux
-  Peer-->>Mod: onmessage
-  Mod-->>App: emit(event)
+  participant A
+  participant VC as VectorClock
+  participant B
+  A->>VC: tick()
+  A->>VC: gossip()
+  VC-->>B: { clock }
+  B->>VC: merge(clock)
 ```
 
 ## Wire messages
 
-| type | fields | direction | behavior |
-|------|--------|-----------|----------|
-| `merge` | Returns, clock, type | gossip | Handled in onmessage / gossipSend |
-| `tick` | clock, type | gossip | Handled in onmessage / gossipSend |
+| type | direction | fields | behavior |
+|------|-----------|--------|----------|
+| (gossip body) | gossip | `clock` | Plain object `peerId → counter`; `merge` on receive |
+
+Protomux protocol id: `vector-clock/v1`. `gossip()` sends `{ clock: toJSON() }` via `gossipSend`.
 
 ## State model
 
-- In-memory `Map` / `Set` structures for hot path
-- Optional Hyperbee/Hypercore persistence when `storageDir` or `memoryOnly` is configured
-- `close()` tears down swarm, timers, and clears ephemeral state
+| Structure | Purpose |
+|-----------|---------|
+| `clock` | Map id → non-negative integer counter |
+| `localId` | This peer's key |
+
+`compare()` returns `-1` (happens-before), `1` (happens-after), `0` (equal), `null` (concurrent).
+
+Prune: `_trimTo(maxEntries)` keeps highest counters when over limit.
 
 ## Composition
 
-Composes with: `hyper-p2p-presence`, `hyper-p2p-rpc`, `hyper-p2p-capabilities`.
-
+- **`hyper-p2p-agent-memory`** — memory causality
+- **`hyper-p2p-distributed-event-bus`** — event vector metadata
+- **`hyper-p2p-temporal-index`** — optional `setVectorClock`

core-infrastructure/hyper-p2p-vector-clock/examples/basic.js

@@ -0,0 +1,10 @@
+require('bare-process/global')
+const HyperP2PVectorClock = require('../index.js')
+
+async function main () {
+  const clock = new HyperP2PVectorClock('peer-a')
+  clock.tick('peer-a')
+  clock.merge({ 'peer-b': 2 })
+  console.log('[vector-clock]', clock.toJSON(), clock.compare({ 'peer-a': 1 }, { 'peer-b': 2 }))
+}
+main().catch(console.error)