Updates

applications-economy/hyper-p2p-auction-gossip/docs/architecture.md

@@ -4,18 +4,54 @@
 
 ## Role
 
-Gossip-synchronized auction state: each peer keeps a map of auctions and bid lists; highest bid wins on close.
+Gossip-synchronized auction room: peers share auction catalog and bid ordering; closing peer publishes winner snapshot.
+
+```mermaid
+flowchart LR
+  App[Market app] --> AG[HyperP2PAuctionGossip]
+  AG --> Map[_auctions Map]
+  AG --> P2P[p2p-bare gossipSend]
+  P2P --> Peers[Remote bidders]
+```
+
+## Sequence
+
+```mermaid
+sequenceDiagram
+  participant Seller
+  participant AG as AuctionGossip
+  participant SW as Hyperswarm
+  participant Buyer
+  Seller->>AG: openAuction(lot-1)
+  AG->>SW: auction-open
+  SW-->>Buyer: remote-open
+  Buyer->>AG: placeBid(lot-1, 42)
+  AG->>SW: auction-bid
+  Seller->>AG: closeAuction(lot-1)
+  AG->>SW: auction-close + winner
+```
 
 ## Wire messages
 
-| type | Fields |
-|------|--------|
-| `auction-open` | `auction` (id, meta, status, bids, openedBy, openedAt) |
-| `auction-bid` | `auctionId`, `bid` (amount, bidder, meta, at) |
-| `auction-close` | `auctionId`, `winner`, `closedAt` |
+| type | direction | fields | behavior |
+|------|-----------|--------|----------|
+| `auction-open` | gossip | `auction` | Replace/insert auction in `_auctions` |
+| `auction-bid` | gossip | `auctionId`, `bid` | Append bid if auction open; sort desc |
+| `auction-close` | gossip | `auctionId`, `winner`, `closedAt` | Set `status: closed`, assign winner |
 
-Uses `../../_shared/p2p-bare.js` (`initModuleSwarm`, `gossipSend`).
+Transport: `initModuleSwarm` + `gossipSend` from `../../_shared/p2p-bare.js`. Protomux channel id: `auction-gossip/v1`.
+
+## State model
+
+| Structure | Purpose |
+|-----------|---------|
+| `_auctions` | `id → { bids[], status, meta, openedBy, winner? }` |
+| `_stats` | `opened`, `bids`, `closed`, `gossipIn`, `gossipOut` |
+
+**Consistency:** last-writer on open; bids append-only per peer; close overwrites status. No CRDT merge on conflicting closes — application should designate an authority or use oracle settlement.
 
 ## Composition
 
-Pairs with `hyper-p2p-credit-ledger` for settlement and `hyper-p2p-marketplace-listing` for item catalog.
+- **`hyper-p2p-credit-ledger`** — settle winner payment after `close`
+- **`hyper-p2p-marketplace-listing`** — catalog items before auction
+- **`hyper-p2p-decentralized-oracle`** — external price/reserve attestation