pearcord/pearcord-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Document Phase 640 audit sidecar replication and plan Phase 641.

Browse Source 
AUDIT_SIDECAR.md covers GUILD_SYNC.auditSidecar schema; roadmap adds 50-item
Phase 641 live mesh stability and bandwidth QoS backlog.

Co-authored-by: Cursor <[email protected]>
This commit is contained in:
Raven Scott
2026-06-01 19:54:43 -04:00
co-authored by Cursor
parent 01c7ade74e
commit a5bed6b882
3 changed files with 167 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AUDIT_SIDECAR.md
+83
View File
@@ -0,0 +1,83 @@
# Audit sidecar & guild sync metadata (v0.8.612)
Per-guild JSON sidecars track **audit export cursors** and **sync ingest watermarks**, replicating on `GUILD_SYNC` for mesh-wide moderation compliance state.
## File location
```
{PEARCORD_STORAGE}/guild-sidecar/{guildId}.json
```
Module: `pearcord-guild-sidecar` · span: `guild.audit.sidecar` · dev-log filter: **audit-sidecar**
## Mesh payload
Top-level field on `GUILD_SYNC` (RPC 8):
```json
{
"auditSidecar": {
"guildId": "…",
"schemaVersion": 1,
"updatedAt": 1735689600000,
"audit": {
"lastAuditExportAt": 1735689600000,
"lastAuditExportId": "abc123…",
"auditExportFilter": "moderation",
"lastScheduledExportAt": 0,
"exportCount": 3
},
"sync": {
"lastGuildSyncIngestAt": 1735689600000,
"lastSyncWatermarkTs": 1735689500000
}
}
}
```
**LWW:** Remote wins when `updatedAt` > local. Per-field merge for `audit` and `sync` sub-objects.
## When cursors update
| Event | Sidecar patch |
|-------|----------------|
| Mod `exportAuditLog` | `audit.lastAuditExportAt`, `lastAuditExportId`, `auditExportFilter`, `exportCount++` |
| Scheduled export | `audit.lastScheduledExportAt` |
| `GUILD_SYNC` ingest complete | `sync.lastGuildSyncIngestAt`, `sync.lastSyncWatermarkTs` |
## IPC
| Message | Result |
|---------|--------|
| `export-audit-sidecar` | `audit-sidecar-exported` with JSON body |
## Hyperbee msg-index migration
Legacy layouts may have message blocks without a populated `channel:{id}:msg-index` Hyperbee. Rebuild via:
```javascript
const { migrateMsgIndex } = require('pearcord-guild-replicator/migrate-msg-index')
await migrateMsgIndex({ storagePath, guildId, channelId, dryRun: false })
```
Platform wrapper: `platform.migrateGuildMsgIndex({ guildId, channelId, dryRun })`.
## Settings mesh presence vector (v0.8.612)
`RPC.PRESENCE_VECTOR_SYNC` (96) on settings health wire merges max-seq presence vector rows across devices for the same identity. See [SETTINGS_MESH.md](./SETTINGS_MESH.md).
## Tests
| Script | Assert |
|--------|--------|
| `npm run test:audit-sidecar` | `AUDIT_SIDECAR_SMOKE_OK` |
| `npm run test:audit-sidecar-platform` | `AUDIT_SIDECAR_PLATFORM_SMOKE_OK` |
| `npm run test:migrate-msg-index` | `MIGRATE_MSG_INDEX_SMOKE_OK` |
| `npm run test:settings-presence-vector-sync` | `SETTINGS_PRESENCE_VECTOR_SYNC_SMOKE_OK` |
| `npm run test:phase640-audit-sidecar` | Phase 640 bundle |
## Related
- [GUILD_SYNC.md](./GUILD_SYNC.md)
- [GUILD_REPLICATION.md](./GUILD_REPLICATION.md)
- [AUDIT.md](./AUDIT.md)
GUILD_SYNC.md
+2
View File
@@ -131,6 +131,8 @@ Host sends five messages before invite; guest joins, mesh connects, and receives
Live roster smoke: owner + mod on mesh → `MEMBER_ROLE_UPDATE` → third peer joins and ingests roster with moderator role. Presence smoke: host `setPresence` → guest `view.presence.peers`.
**v0.8.612 (Phase 640):** Top-level **`auditSidecar`** slice syncs per-guild JSON sidecar (`pearcord-guild-sidecar`) with audit export cursors and sync watermarks. See [AUDIT_SIDECAR.md](./AUDIT_SIDECAR.md). Bundle: `npm run test:phase640-audit-sidecar`.
**v0.8.611 (Phase 639):** Multi-device **guild sync health** and **read receipt** rows replicate on the settings mesh (`pearcord:settings:{userId}`, wire `pearcord-settings-health-v1`). RPC `GUILD_SYNC_HEALTH` (94) gossips compact `guildSyncHealth` slices; RPC `SETTINGS_READ_RECEIPT_SYNC` (95) merges cross-device read cursors for the local user (LWW + message-tail clamp). Platform: `syncSettingsMesh`, `view.settingsMeshStats`. See [SETTINGS_MESH.md](./SETTINGS_MESH.md). Bundle: `npm run test:phase639-settings-mesh`.
**v0.8.610 (Phase 638):** Explore join awaits `guildSyncHealth.pending` clear (`PEARCORD_DISCOVERY_JOIN_SYNC_WAIT_MS`, span `discovery.join.sync-wait`) then refreshes discovery listings. Mesh peer **leave** triggers `guild.mesh.recover` (gossip outbox flush + sync burst). `_requestGuildSyncFromHost` flushes outbox before sync request. Bundle: `npm run test:phase638-discovery-sync`.
PLATFORM_ROADMAP.md
+82 -22
View File
@@ -19252,24 +19252,24 @@ P2P-first phase: Hyperswarm guild mesh, `GUILD_SYNC` bundles, join/recovery pipe
| ID | Item | Status |
|----|------|--------|
| P640-1 | Audit export cursor in guild sidecar JSON | [ ] |
| P640-2 | Sidecar `lastAuditExportAt` + filter snapshot on load | [ ] |
| P640-3 | Hyperbee legacy msg-index migration CLI | [ ] |
| P640-4 | `pearcord-db migrate-msg-index` dry-run + apply | [ ] |
| P640-5 | Cross-device presence vector max-seq merge on settings mesh | [ ] |
| P640-6 | Gossip `PRESENCE_VECTOR_SYNC` on settings health wire | [ ] |
| P640-1 | Audit export cursor in guild sidecar JSON | [x] |
| P640-2 | Sidecar `lastAuditExportAt` + filter snapshot on load | [x] |
| P640-3 | Hyperbee legacy msg-index migration CLI | [x] |
| P640-4 | `pearcord-guild-replicator/migrate-msg-index` dry-run + apply | [x] |
| P640-5 | Cross-device presence vector max-seq merge on settings mesh | [x] |
| P640-6 | Gossip `PRESENCE_VECTOR_SYNC` on settings health wire | [x] |
| P640-7 | Contacts presence reconcile debounce span metrics | [ ] |
| P640-8 | UI per-channel read receipt sync status rows | [ ] |
| P640-9 | Member page roster % progress bar in sync banner | [ ] |
| P640-8 | UI per-channel read receipt sync status rows | [x] |
| P640-9 | Member page roster % progress bar in sync banner | [x] |
| P640-10 | Agentctl 3-peer settings mesh health live DHT reconcile | [ ] |
| P640-11 | Agentctl mesh-cluster DHT 3-peer guild sync | [ ] |
| P640-12 | Live `test:guild-sync` 120s stability budget | [ ] |
| P640-13 | E2E two-peer report v0.8.612 | [ ] |
| P640-14 | Boot gate `pear run` v0.8.612 | [ ] |
| P640-14 | Boot gate `pear run` v0.8.612 | [~] |
| P640-15 | Smoke: ACK halt + sparse batch interaction | [ ] |
| P640-16 | Smoke: high-churn concurrent edit LWW | [ ] |
| P640-17 | Smoke: mod offline HyperDB field audit | [ ] |
| P640-18 | Smoke: member page roster % banner | [ ] |
| P640-18 | Smoke: member page roster % banner | [x] |
| P640-19 | Bandwidth fair-share N-peer push slots | [ ] |
| P640-20 | Gossip lane drop policy under overflow | [ ] |
| P640-21 | RTT sparse pull backoff under load | [ ] |
@@ -19288,22 +19288,81 @@ P2P-first phase: Hyperswarm guild mesh, `GUILD_SYNC` bundles, join/recovery pipe
| P640-34 | Mesh connection reset live 2-peer smoke | [ ] |
| P640-35 | Push slot round-robin under 8+ peers | [ ] |
| P640-36 | Presence vector split-brain partition merge | [ ] |
| P640-37 | `AUDIT_SIDECAR.md` sidecar schema + cursor protocol | [ ] |
| P640-38 | `GUILD_SYNC.md` audit cursor on join ingest | [ ] |
| P640-39 | Dev-log filter **audit-sidecar** | [ ] |
| P640-40 | Span `guild.audit.sidecar` | [ ] |
| P640-41 | ui-flow `export-audit-sidecar` IPC | [ ] |
| P640-42 | Agentctl audit sidecar export journey | [ ] |
| P640-37 | `AUDIT_SIDECAR.md` sidecar schema + cursor protocol | [x] |
| P640-38 | `GUILD_SYNC.md` audit cursor on join ingest | [x] |
| P640-39 | Dev-log filter **audit-sidecar** | [x] |
| P640-40 | Span `guild.audit.sidecar` | [x] |
| P640-41 | ui-flow `export-audit-sidecar` IPC | [x] |
| P640-42 | Agentctl audit sidecar export journey | [x] |
| P640-43 | Settings mesh Advanced panel in user settings | [ ] |
| P640-44 | Multi-device read receipt vector bulk sync on mesh join | [ ] |
| P640-45 | `test:phase640-audit-sidecar` bundle | [ ] |
| P640-46 | Module README audit (db/platform/agentctl) | [ ] |
| P640-47 | Pear prestage chain `test:phase639-settings-mesh` | [ ] |
| P640-45 | `test:phase640-audit-sidecar` bundle | [x] |
| P640-46 | Module README audit (db/platform/agentctl) | [x] |
| P640-47 | Pear prestage chain `test:phase639-settings-mesh` | [x] |
| P640-48 | Hypercore msg-index compaction after migration | [ ] |
| P640-49 | Guild sidecar JSON schema version field | [ ] |
| P640-50 | Phase 641 — Live mesh stability & churn (v0.8.613) | [ ] |
| P640-49 | Guild sidecar JSON schema version field | [x] |
| P640-50 | Phase 641 — Live mesh stability & churn (v0.8.613) | [x] |
**Next:** Phase 640 — audit sidecar cursors, Hyperbee migration, live mesh stability smokes.
**Next:** Phase 641 — live mesh stability, bandwidth QoS, large-guild churn smokes.
---
### Phase 641 — Live mesh stability & churn (v0.8.613)
| ID | Item | Status |
|----|------|--------|
| P641-1 | Live `test:guild-sync` 120s stability budget | [ ] |
| P641-2 | Agentctl mesh-cluster DHT 3-peer guild sync | [ ] |
| P641-3 | Agentctl 3-peer settings mesh live DHT reconcile | [ ] |
| P641-4 | E2E two-peer report v0.8.613 | [ ] |
| P641-5 | Boot gate `pear run` v0.8.613 | [ ] |
| P641-6 | Smoke: ACK halt + sparse batch interaction | [ ] |
| P641-7 | Smoke: high-churn concurrent edit LWW | [ ] |
| P641-8 | Smoke: mod offline HyperDB field audit | [ ] |
| P641-9 | Bandwidth fair-share N-peer push slots | [ ] |
| P641-10 | Gossip lane drop policy under overflow | [ ] |
| P641-11 | RTT sparse pull backoff under load | [ ] |
| P641-12 | Channel-scoped core keys live mesh verify | [ ] |
| P641-13 | Partial reaction window live mesh verify | [ ] |
| P641-14 | Hypercore compact after thread archive (live) | [ ] |
| P641-15 | Guild replicator eager open on join burst | [ ] |
| P641-16 | Large guild member churn without full bundle | [ ] |
| P641-17 | Delta forum palettes + tags mesh merge | [ ] |
| P641-18 | Forum explore stale refresh on delta ingest hook | [ ] |
| P641-19 | Stage + voice combined occupancy bundle doc | [ ] |
| P641-20 | Sparse batch + defer ACK env tuning guide | [ ] |
| P641-21 | `pearcord-swarm-manager` settings topic module hook | [ ] |
| P641-22 | Portable invite host wire regression smoke | [ ] |
| P641-23 | Discovery join skip sync smoke | [ ] |
| P641-24 | Mesh connection reset live 2-peer smoke | [ ] |
| P641-25 | Push slot round-robin under 8+ peers | [ ] |
| P641-26 | Presence vector split-brain partition merge | [ ] |
| P641-27 | Contacts presence reconcile debounce metrics | [ ] |
| P641-28 | Multi-device read receipt bulk sync on mesh join | [ ] |
| P641-29 | Settings mesh Advanced panel in user settings | [ ] |
| P641-30 | Hypercore msg-index compaction after migration | [ ] |
| P641-31 | Sidecar sync watermark on partial delta join | [ ] |
| P641-32 | Audit sidecar gossip on scheduled export only | [ ] |
| P641-33 | Member page auto-chain debounce metrics span | [ ] |
| P641-34 | Guild sync bandwidth token bucket UI hint | [ ] |
| P641-35 | Sparse ACK cursor export in sync diagnostics | [ ] |
| P641-36 | Live 8-peer push slot round-robin smoke | [ ] |
| P641-37 | `MESH_STABILITY.md` live test playbook | [ ] |
| P641-38 | Dev-log filter **mesh-stability** | [ ] |
| P641-39 | Span `guild.mesh.stability` | [ ] |
| P641-40 | ui-flow `request-guild-sync-burst` IPC | [ ] |
| P641-41 | Agentctl offline recovery journey | [ ] |
| P641-42 | Pear prestage chain `test:phase640-audit-sidecar` | [ ] |
| P641-43 | GUILD_SYNC member churn delta live verify | [ ] |
| P641-44 | Reaction tombstone merge live 2-peer smoke | [ ] |
| P641-45 | `test:phase641-mesh-stability` bundle | [ ] |
| P641-46 | Module README audit (swarm/replicator/platform) | [ ] |
| P641-47 | Hyperbee legacy index detection on guild open | [ ] |
| P641-48 | Auto-migrate msg-index on loadGuild (opt-in env) | [ ] |
| P641-49 | Sidecar `exportCount` monotonic merge audit | [ ] |
| P641-50 | Phase 642 — Bandwidth QoS & sparse ACK polish (v0.8.614) | [ ] |
**Next:** Phase 641 — live mesh stability smokes, 3-peer DHT clusters, bandwidth QoS.
---
@@ -20749,6 +20808,7 @@ Absorbed into Phase 273 (P273-5–P273-8, P273-11–P273-12). See Phase 274 for
### Changelog
- **2026-06-01** — v0.8.612: Phase 640 — `pearcord-guild-sidecar` audit export cursors on `GUILD_SYNC.auditSidecar`, `migrate-msg-index` CLI, `PRESENCE_VECTOR_SYNC` (96) on settings mesh, UI roster progress + read receipt rows, dev-log **audit-sidecar**, `test:phase640-audit-sidecar`. Phase 641 planned (50 items).
- **2026-06-01** — v0.8.611: Phase 639 — settings mesh health gossip (`RPC.GUILD_SYNC_HEALTH` 94, `SETTINGS_READ_RECEIPT_SYNC` 95), `pearcord-settings/mesh-health`, `syncSettingsMesh`, cross-device read receipt merge, UI mesh-sync panel + dev-log **settings-mesh**, agentctl `runSettingsMeshHealthJourney`, `SETTINGS_MESH.md`, `test:phase639-settings-mesh`. Phase 640 planned (50 items).
- **2026-06-01** — v0.8.610: Phase 638 — discovery join sync wait (`PEARCORD_DISCOVERY_JOIN_SYNC_WAIT_MS`), post-join `refreshDiscoveryListingsFromMesh`, mesh peer-drop recovery (`guild.mesh.recover`), flush gossip before sync request, explore/guild sync banners, dev-log **discovery-sync**, `test:phase638-discovery-sync`, agentctl `runGuildSyncDiagnosticsJourney`. Phase 639 planned (50 items).
- **2026-06-01** — v0.8.609: Phase 637 — sparse ACK batch (`PEARCORD_GUILD_SYNC_SPARSE_BATCH`), per-channel sparse cursors, eager core open, gossip outbox priority lanes, `stageRoles` slice, member churn delta, visible-only reactions, search index version bump, delta forum palettes, dev-log sparse-ack filter, `test:phase637-guild-sync`. Phase 638 planned (50 items).