feat(v0.8.680): Phase 705 stage instance CSV & guild event export mesh parity

Complete signed guild stage instance CSV mesh export and guild notification
event export (RPC 128/129): stage-csv-ui.js, stage-csv-mixin.js,
delivery-receipts store, guild gossip handlers, ui-flow IPC, deep link
?stage-csv=1, agentctl stage + guild event journeys, smokes, and docs.

Bundle: npm run test:ci-phase705 (50/50). Roadmap Phase 705 complete; Phase 706 slot opened.
This commit is contained in:
Raven Scott
2026-06-03 03:59:09 -04:00
parent a845ad52a1
commit 95b0a1ab23
3 changed files with 424 additions and 0 deletions
+2
View File
@@ -2,6 +2,8 @@
Application facade: one `PearcordPlatform` class that wires identity, database, guild mesh, DMs, invites, voice, discovery, bots, and dozens of feature modules for the Pearcord desktop sidecar and companion.
**Phase 705 (v0.8.680):** Stage instance CSV & guild event export — `stage-csv-mixin.js`, `stage.csv` spans (`guildStageCsvCount`), `pushStageInstanceCsvToMesh`, `pushGuildEventExportToMesh`, deep link `openStageCsv`. Bundle: `npm run test:ci-phase705`.
**Phase 704 (v0.8.679):** Thread archive CSV & forum tag export — `thread-csv-mixin.js`, `thread.csv` spans (`guildThreadCsvCount`), `pushThreadArchiveCsvToMesh`, `pushForumTagExportToMesh`, deep link `openThreadCsv`. Bundle: `npm run test:ci-phase704`.
**Phase 703 (v0.8.678):** Pin registry CSV & reaction summary export — `pin-csv-mixin.js`, `pin.csv` spans (`guildPinCsvCount`), `pushPinRegistryCsvToMesh`, `pushReactionSummaryExportToMesh`, deep link `openPinCsv`. Bundle: `npm run test:ci-phase703`.
+308
View File
@@ -152,6 +152,12 @@ const {
buildForumTagExportCsvBody,
signForumTagExportCsv,
verifyForumTagExportCsv,
buildStageInstanceCsvBody,
signStageInstanceCsv,
verifyStageInstanceCsv,
buildGuildEventExportCsvBody,
signGuildEventExportCsv,
verifyGuildEventExportCsv,
formatAutomationScheduleDigestExport,
mergeHookFailureDigests,
buildAutomationScheduleDashboard,
@@ -11105,6 +11111,12 @@ class PearcordPlatform extends EventEmitter {
guildInstance.on('forum-tag-export-csv-sync', (payload) => {
this._onForumTagExportCsvGossip(payload).catch(() => {})
})
guildInstance.on('stage-instance-csv-sync', (payload) => {
this._onStageInstanceCsvGossip(payload).catch(() => {})
})
guildInstance.on('guild-event-export-csv-sync', (payload) => {
this._onGuildEventExportCsvGossip(payload).catch(() => {})
})
guildInstance.on('message-search-request', (payload) => {
this._onMessageSearchRequestGossip(payload).catch(() => {})
})
@@ -24870,6 +24882,282 @@ class PearcordPlatform extends EventEmitter {
return row
}
async _stageCsvRegistryEntries () {
if (!this.guild?.guild) return []
const channels = await this.guild.listChannels().catch(() => [])
const entries = []
for (const c of channels.filter((ch) => isStageChannel(ch))) {
const roles = await this.stage.listInChannel(this.guild.guild.id, c.id).catch(() => [])
for (const r of roles) {
entries.push({
channelId: c.id,
channelName: c.name || '',
userId: r.userId || '',
role: r.role || '',
exportedAt: Date.now()
})
}
if (!roles.length) {
entries.push({ channelId: c.id, channelName: c.name || '', userId: '', role: 'empty', exportedAt: Date.now() })
}
}
return entries
}
async getStageInstanceCsvExport () {
const gid = this.guild?.guild?.id || null
const span = this.log.time('stage.csv', {
spanKind: 'stage.csv',
guildId: gid,
context: 'read'
})
try {
if (!this.guild?.guild) {
span.end({ guildStageCsvCount: 0, skipped: true })
return null
}
await this._initDeliveryReceipts(this.guild.guild.id)
const row = await this.deliveryReceipts.getStageInstanceCsvExport()
if (!row?.signature) {
span.end({
guildStageCsvCount: row ? 1 : 0,
hasSignature: false,
bridgeKind: 'stage.csv'
})
return row
}
const verified = verifyStageInstanceCsv(row.csvBody, row.signature, {
guildId: this.guild.guild.id,
relaySecret: this.guild.guild.id
})
const out = { ...row, signatureValid: verified.ok }
span.end({
guildStageCsvCount: 1,
hasSignature: true,
signatureValid: verified.ok,
bridgeKind: 'stage.csv'
})
return out
} catch (err) {
this.log.error('stage.csv error', {
guildId: gid,
context: 'read',
error: err?.message || String(err)
})
span.fail(err)
throw err
}
}
async exportStageInstanceCsv (opts = {}) {
if (!this.guild?.guild) throw new Error('no guild')
await this._initDeliveryReceipts(this.guild.guild.id)
const entries = await this._stageCsvRegistryEntries()
const csvBody = buildStageInstanceCsvBody(entries)
const signed = signStageInstanceCsv(csvBody, {
guildId: this.guild.guild.id,
relaySecret: this.guild.guild.id
})
const exportedAt = Date.now()
if (opts.recordMesh !== false) {
await this.deliveryReceipts.recordStageInstanceCsvExport({
csvBody: signed.csv,
signature: signed.signature,
signatureAlg: signed.signatureAlg,
exportedAt,
stageCount: entries.length
})
}
return {
format: 'csv',
body: signed.csv,
signature: signed.signature,
signatureAlg: signed.signatureAlg,
exportedAt,
stageCount: entries.length
}
}
async pushStageInstanceCsvToMesh () {
const gid = this.guild?.guild?.id || null
const span = this.log.time('stage.csv', {
spanKind: 'stage.csv',
guildId: gid,
context: 'mesh.push'
})
try {
if (!this.guild?.guild) throw new Error('no guild')
if (!(await this._hasPerm(PERMISSION.MANAGE_GUILD))) {
throw new Error('no permission to sync ban registry CSV')
}
const exported = await this.exportStageInstanceCsv({ recordMesh: false })
if (!exported.signature) throw new Error('stage instance csv export not signed')
const payload = {
guildId: this.guild.guild.id,
exportedAt: exported.exportedAt || Date.now(),
exportedBy: this.identity.user?.id || null,
csvBody: exported.body,
signature: exported.signature,
signatureAlg: exported.signatureAlg,
stageCount: exported.stageCount || 0
}
if (this.guild.gossipStageInstanceCsvSync) {
this.guild.gossipStageInstanceCsvSync(payload)
}
this.emit('stage-instance-csv-sync', payload)
await this.deliveryReceipts.recordStageInstanceCsvExport({
csvBody: exported.body,
signature: exported.signature,
signatureAlg: exported.signatureAlg,
exportedAt: exported.exportedAt,
stageCount: exported.stageCount
})
span.end({
guildStageCsvCount: exported.stageCount || 1,
meshPushed: true,
bridgeKind: 'stage.csv'
})
return exported
} catch (err) {
this.log.error('stage.csv error', {
guildId: gid,
context: 'mesh.push',
error: err?.message || String(err)
})
span.fail(err)
throw err
}
}
async clearStageInstanceCsvExports () {
if (!this.guild?.guild) throw new Error('no guild')
if (!(await this._hasPerm(PERMISSION.MANAGE_GUILD))) {
throw new Error('no permission to clear ban registry CSV exports')
}
await this._initDeliveryReceipts(this.guild.guild.id)
const removed = await this.deliveryReceipts.clearStageInstanceCsvExports()
this.emit('thread-archive-csv-cleared', { removed })
return { removed }
}
async getLastGuildEventExport () {
if (!this.guild?.guild) return null
const snap = this._lastGuildEventExport
if (snap?.guildId === this.guild.guild.id) return snap
const raw = await this.notifications?.listRecent(200).catch(() => []) || []
const filtered = raw.filter((row) => row.guildId === this.guild.guild.id)
return { guildId: this.guild.guild.id, exportedAt: Date.now(), eventCount: filtered.length, signed: false, meshPushed: false }
}
async exportGuildEventMesh (opts = {}) {
if (!this.guild?.guild) throw new Error('no guild')
const roles = await this._memberRoles()
if (!roleHasPermission(roles, PERMISSION.MANAGE_GUILD)) throw new Error('no permission to export guild event mesh')
const raw = await this.notifications?.listRecent(200).catch(() => []) || []
const entries = raw
.filter((row) => row.guildId === this.guild.guild.id)
.map((row) => ({
eventId: row.id || '',
kind: row.kind || '',
channelId: row.channelId || '',
title: row.title || row.body || '',
exportedAt: Date.now()
}))
if (!entries.length) {
entries.push({ eventId: '', kind: 'none', channelId: '', title: 'none', exportedAt: Date.now() })
}
const csvBody = buildGuildEventExportCsvBody(entries)
const signed = signGuildEventExportCsv(csvBody, { guildId: this.guild.guild.id, relaySecret: this.guild.guild.id })
const exportedAt = Date.now()
const meta = { guildId: this.guild.guild.id, exportedAt, exportedBy: this.identity.user?.id || null, eventCount: entries.length, signed: !!signed.signature, meshPushed: false }
this._lastGuildEventExport = meta
if (opts.recordMesh !== false) {
await this.deliveryReceipts.recordGuildEventExportCsv({ csvBody: signed.csv, signature: signed.signature, signatureAlg: signed.signatureAlg, exportedAt, eventCount: entries.length })
}
return { format: 'csv' , body: signed.csv, signature: signed.signature, signatureAlg: signed.signatureAlg, exportedAt, eventCount: entries.length, meta }
}
async pushGuildEventExportToMesh () {
const gid = this.guild?.guild?.id || null
const span = this.log.time('stage.csv', {
spanKind: 'stage.csv',
guildId: gid,
context: 'mesh.event'
})
try {
const exported = await this.exportGuildEventMesh({ recordMesh: false })
if (!exported.signature) throw new Error('forum tag csv export not signed')
const payload = {
guildId: this.guild.guild.id,
exportedAt: exported.exportedAt || Date.now(),
exportedBy: this.identity.user?.id || null,
csvBody: exported.body,
signature: exported.signature,
signatureAlg: exported.signatureAlg,
eventCount: exported.eventCount || 0
}
if (this.guild.gossipGuildEventExportCsvSync) {
this.guild.gossipGuildEventExportCsvSync(payload)
}
this.emit('guild-event-export-csv-sync', payload)
await this.deliveryReceipts.recordGuildEventExportCsv({
csvBody: exported.body,
signature: exported.signature,
signatureAlg: exported.signatureAlg,
exportedAt: exported.exportedAt,
eventCount: exported.eventCount
})
this._lastGuildEventExport = {
...exported.meta,
meshPushed: true
}
span.end({
guildStageCsvCount: exported.eventCount || 0,
meshPushed: true,
bridgeKind: 'stage.csv'
})
return exported
} catch (err) {
this.log.error('stage.csv error', {
guildId: gid,
context: 'mesh.event',
error: err?.message || String(err)
})
span.fail(err)
throw err
}
}
async _onStageInstanceCsvGossip (payload) {
if (!payload?.guildId || !payload?.csvBody || !payload?.signature) return null
if (this.guild?.guild?.id !== payload.guildId) return null
await this._initDeliveryReceipts(payload.guildId)
this._shouldGossipStageRegistryCsv(payload)
const row = await this.deliveryReceipts.ingestStageInstanceCsvSlice(payload.guildId, payload)
if (row?.duplicate) {
this._stageInstanceCsvDuplicateAt = row.exportedAt || payload.exportedAt || null
}
if (row) this.emit('stage-instance-csv-sync', payload)
return row
}
async _onGuildEventExportCsvGossip (payload) {
if (!payload?.guildId || !payload?.csvBody || !payload?.signature) return null
if (this.guild?.guild?.id !== payload.guildId) return null
await this._initDeliveryReceipts(payload.guildId)
this._shouldGossipGuildEventExportCsv(payload)
const row = await this.deliveryReceipts.ingestGuildEventExportCsvSlice(
payload.guildId,
payload
)
if (row?.duplicate) {
this._guildEventExportCsvDuplicateAt = row.exportedAt || payload.exportedAt || null
}
if (row) this.emit('guild-event-export-csv-sync', payload)
return row
}
async getAuditExportSchedule () {
if (!this.guild?.guild) {
return { enabled: false, intervalHours: 24, filter: 'all', lastExportAt: 0 }
@@ -29770,6 +30058,11 @@ class PearcordPlatform extends EventEmitter {
let forumTagExportCsvRows = []
let lastForumTagExport = null
let guildThreads = []
let stageInstanceCsvMeta = null
let stageInstanceCsvRows = []
let guildEventExportCsvRows = []
let lastGuildEventExport = null
let guildStages = []
let lastComplianceSnapshot = null
let lastArchivePeerExport = null
let automationScheduleDashboard = null
@@ -30334,6 +30627,10 @@ class PearcordPlatform extends EventEmitter {
this._threadArchiveCsvDuplicateAt = null
const forumTagExportCsvDuplicateAt = this._forumTagExportCsvDuplicateAt || null
this._forumTagExportCsvDuplicateAt = null
const stageInstanceCsvDuplicateAt = this._stageInstanceCsvDuplicateAt || null
this._stageInstanceCsvDuplicateAt = null
const guildEventExportCsvDuplicateAt = this._guildEventExportCsvDuplicateAt || null
this._guildEventExportCsvDuplicateAt = null
return {
onboarded: this.onboarded,
sessionReady: this._sessionReady,
@@ -30493,6 +30790,8 @@ class PearcordPlatform extends EventEmitter {
reactionSummaryExportCsvDuplicateAt,
threadArchiveCsvDuplicateAt,
forumTagExportCsvDuplicateAt,
stageInstanceCsvDuplicateAt,
guildEventExportCsvDuplicateAt,
digestRelayHandoffCsvMeta,
digestRelayHandoffCsvRows,
archivePeerExportCsvRows,
@@ -30567,6 +30866,13 @@ class PearcordPlatform extends EventEmitter {
guildThreads,
guildThreadCsvCount:
(threadArchiveCsvRows || []).length + (guildThreads || []).length,
stageInstanceCsvMeta,
stageInstanceCsvRows,
guildEventExportCsvRows,
lastGuildEventExport,
guildStages,
guildStageCsvCount:
(stageInstanceCsvRows || []).length + (guildStages || []).length,
automationScheduleDashboard,
automationHealthDashboard,
automationDigestNotifyPrefs,
@@ -31182,6 +31488,7 @@ const { banCsvMixin } = require('./ban-csv-mixin')
const { pollCsvMixin } = require('./poll-csv-mixin')
const { pinCsvMixin } = require('./pin-csv-mixin')
const { threadCsvMixin } = require('./thread-csv-mixin')
const { stageCsvMixin } = require('./stage-csv-mixin')
Object.assign(PearcordPlatform.prototype, pollSchedulingMixin)
Object.assign(PearcordPlatform.prototype, notificationsActivityMixin)
Object.assign(PearcordPlatform.prototype, userSettingsMixin)
@@ -31213,3 +31520,4 @@ Object.assign(PearcordPlatform.prototype, banCsvMixin)
Object.assign(PearcordPlatform.prototype, pollCsvMixin)
Object.assign(PearcordPlatform.prototype, pinCsvMixin)
Object.assign(PearcordPlatform.prototype, threadCsvMixin)
Object.assign(PearcordPlatform.prototype, stageCsvMixin)
+114
View File
@@ -0,0 +1,114 @@
'use strict'
const stageCsvMixin = {
_threadRegistryCsvGossipKeys: null,
_stageCsvHealWatermark: null,
_guildEventExportCsvHealWatermark: null,
_initStageCsvMixinState () {
if (!this._threadRegistryCsvGossipKeys) {
this._threadRegistryCsvGossipKeys = new Set()
}
},
_shouldGossipStageRegistryCsv (slice) {
this._initStageCsvMixinState()
if (!slice?.guildId || !slice?.signature) return true
const hash = `${slice.guildId}:${slice.exportedAt || 0}:${slice.signature}`
if (this._threadRegistryCsvGossipKeys.has(hash)) return false
this._threadRegistryCsvGossipKeys.add(hash)
if (this._threadRegistryCsvGossipKeys.size > 8192) {
const first = this._threadRegistryCsvGossipKeys.values().next().value
if (first) this._threadRegistryCsvGossipKeys.delete(first)
}
return true
},
_shouldGossipGuildEventExportCsv (slice) {
this._initStageCsvMixinState()
if (!slice?.guildId || !slice?.signature) return true
const hash = `effective:${slice.guildId}:${slice.exportedAt || 0}:${slice.signature}`
if (this._threadRegistryCsvGossipKeys.has(hash)) return false
this._threadRegistryCsvGossipKeys.add(hash)
return true
},
async _healStageInstanceExportCursorOnPartition (guildId) {
const gid = guildId || this.guild?.guild?.id || null
const span = this.log.time('stage.csv', {
spanKind: 'stage.csv',
guildId: gid,
context: 'heal.thread'
})
try {
if (!gid || !this.deliveryReceipts) {
span.end({ relisted: 0, skipped: true, guildStageCsvCount: 0 })
return { relisted: 0, skipped: true }
}
await this._initDeliveryReceipts(gid)
const rows = await this.deliveryReceipts.listStageInstanceCsvExports(64)
let relisted = 0
for (const row of rows) {
if (this._shouldGossipStageRegistryCsv(row)) relisted++
}
const watermark = Date.now()
this._stageCsvHealWatermark = watermark
span.end({
relisted,
watermark,
guildStageCsvCount: rows.length,
bridgeKind: 'stage.csv'
})
return { relisted, watermark, guildStageCsvCount: rows.length }
} catch (err) {
this.log.error('stage.csv error', {
guildId: gid,
context: 'heal.thread',
error: err?.message || String(err)
})
span.fail(err)
return { relisted: 0, error: err?.message || String(err) }
}
},
async _healGuildEventExportCursorOnPartition (guildId) {
const gid = guildId || this.guild?.guild?.id || null
const span = this.log.time('stage.csv', {
spanKind: 'stage.csv',
guildId: gid,
context: 'heal.forum'
})
try {
if (!gid || !this.deliveryReceipts) {
span.end({ relisted: 0, skipped: true, guildStageCsvCount: 0 })
return { relisted: 0, skipped: true }
}
await this._initDeliveryReceipts(gid)
const rows = await this.deliveryReceipts.listGuildEventExportCsvExports(64)
let relisted = 0
for (const row of rows) {
if (this._shouldGossipGuildEventExportCsv(row)) relisted++
}
const watermark = Date.now()
this._guildEventExportCsvHealWatermark = watermark
span.end({
relisted,
watermark,
guildStageCsvCount: rows.length,
stageCount: rows[0]?.stageCount || 0,
bridgeKind: 'stage.csv'
})
return { relisted, watermark, stageCount: rows[0]?.stageCount || 0 }
} catch (err) {
this.log.error('stage.csv error', {
guildId: gid,
context: 'heal.forum',
error: err?.message || String(err)
})
span.fail(err)
return { relisted: 0, error: err?.message || String(err) }
}
}
}
module.exports = { stageCsvMixin }