feat(v0.8.671): Phase 696 OAuth grant CSV and install token mesh parity

Signed OAuth grant CSV (guild bots as application grants) and install token export CSV follow the bot/slash CSV mesh pattern: oauth-csv-ui, oauth-csv-mixin, delivery-receipts collections, guild gossip, ui-flow IPC, deep link ?oauth-csv=1, oauth-errors dev filter, and agentctl journeys. Adds test:ci-phase696 (static + boot + agentctl) and bumps app to 0.8.671. Documents OAUTH_GRANT_CSV.md, RELEASE_v0.8.671, and opens Phase 697 on the roadmap.
2026-06-03 02:03:19 -04:00
parent 51d734eda1
commit d510209e7e
3 changed files with 480 additions and 4 deletions
@@ -2,12 +2,14 @@

 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 696 (v0.8.671):** OAuth grant CSV & install token export — `oauth-csv-mixin.js`, `oauth.csv` spans (`guildOAuthGrantCount`), `pushOAuthGrantCsvToMesh`, `pushOAuthInstallTokenExportToMesh`, deep link `openOAuthCsv`. Bundle: `npm run test:ci-phase696`.
+
+**Phase 695 (v0.8.670):** Slash registry CSV & invoke audit — `slash-csv-mixin.js`, `slash.csv` spans (`guildSlashRegistryCount`), `pushSlashRegistryCsvToMesh`, `pushSlashInvokeAuditExportToMesh`, deep link `openSlashCsv`. Bundle: `npm run test:ci-phase695`.
+
 **Phase 692 (v0.8.667):** Digest relay handoff CSV & archive export — `relay-csv-mixin.js`, `relay.csv` spans, `pushDigestRelayHandoffCsvToMesh`, `pushArchivePeerExportToMesh`, deep link `openRelayCsv`. Bundle: `npm run test:ci-phase692`.

 **Phase 693 (v0.8.668):** Worker release CSV & integration manifest — `worker-csv-mixin.js`, `worker.csv` spans (`guildWorkerReleaseCount`), `pushWorkerReleaseCsvToMesh`, `pushIntegrationManifestExportToMesh`, deep link `openWorkerCsv`. Bundle: `npm run test:ci-phase693`.

-**Phase 695 (v0.8.670):** Slash registry CSV & invoke audit — `slash-csv-mixin.js`, `slash.csv` spans (`guildSlashRegistryCount`), `pushSlashRegistryCsvToMesh`, `pushSlashInvokeAuditExportToMesh`, deep link `openSlashCsv`. Bundle: `npm run test:ci-phase695`.
-
 **Phase 694 (v0.8.669):** Bot registry CSV & webhook execute — `bot-csv-mixin.js`, `bot.csv` spans (`guildBotRegistryCount`), `pushBotRegistryCsvToMesh`, `pushWebhookExecuteExportToMesh`, deep link `openBotCsv`. Bundle: `npm run test:ci-phase694`.

 **Phase 691 (v0.8.666):** Hook failure digest CSV & compliance snapshot — `digest-csv-mixin.js`, `digest.csv` spans (`guildDigestCsvCount`), CSV gossip dedupe, `_healHookFailureDigestCsvCursorOnPartition` + `_healComplianceSnapshotCursorOnPartition`, `clearHookFailureDigestCsvExports`, `getLastComplianceSnapshot`, deep link `openDigestCsv`. Bundle: `npm run test:ci-phase691`.
@@ -98,6 +98,12 @@ const {
  buildSlashInvokeAuditExportCsvBody,
  signSlashInvokeAuditExportCsv,
  verifySlashInvokeAuditExportCsv,
+  buildOAuthGrantCsvBody,
+  signOAuthGrantCsv,
+  verifyOAuthGrantCsv,
+  buildOAuthInstallTokenExportCsvBody,
+  signOAuthInstallTokenExportCsv,
+  verifyOAuthInstallTokenExportCsv,
  formatAutomationScheduleDigestExport,
  mergeHookFailureDigests,
  buildAutomationScheduleDashboard,
@@ -1688,6 +1694,12 @@ class PearcordPlatform extends EventEmitter {
    const slashInvokeAuditCsvHeal = await this._healSlashInvokeAuditExportCursorOnPartition(gid).catch(() => ({
      relisted: 0
    }))
+    const oauthGrantCsvHeal = await this._healOAuthGrantExportCursorOnPartition(gid).catch(() => ({
+      relisted: 0
+    }))
+    const oauthInstallTokenCsvHeal = await this._healOAuthInstallTokenExportCursorOnPartition(gid).catch(() => ({
+      relisted: 0
+    }))
    return {
      voiceApplied,
      emojiSlots,
@@ -1744,7 +1756,9 @@ class PearcordPlatform extends EventEmitter {
      botRegistryCsvHeal,
      webhookExecuteCsvHeal,
      slashRegistryCsvHeal,
-      slashInvokeAuditCsvHeal
+      slashInvokeAuditCsvHeal,
+      oauthGrantCsvHeal,
+      oauthInstallTokenCsvHeal
    }
  }

@@ -8706,6 +8720,8 @@ class PearcordPlatform extends EventEmitter {
    let webhookExecuteExportCsvExport = null
    let slashRegistryCsvExport = null
    let slashInvokeAuditExportCsvExport = null
+    let oauthGrantCsvExport = null
+    let oauthInstallTokenExportCsvExport = null
    let archiveHealthPrefs = null
    await this._initDeliveryReceipts(guild.id)
    if (this.deliveryReceipts) {
@@ -8735,6 +8751,9 @@ class PearcordPlatform extends EventEmitter {
      slashRegistryCsvExport = await this.deliveryReceipts.exportSlashRegistryCsvSlice()
      slashInvokeAuditExportCsvExport =
        await this.deliveryReceipts.exportSlashInvokeAuditExportCsvSlice()
+      oauthGrantCsvExport = await this.deliveryReceipts.exportOAuthGrantCsvSlice()
+      oauthInstallTokenExportCsvExport =
+        await this.deliveryReceipts.exportOAuthInstallTokenExportCsvSlice()
      digestRelayHandoff = await this.deliveryReceipts.exportDigestRelayHandoffSlice()
      const digestSnap = await this.deliveryReceipts.getHookFailureDigestSnapshot()
      if (digestSnap) {
@@ -8915,6 +8934,8 @@ class PearcordPlatform extends EventEmitter {
      webhookExecuteExportCsvExport,
      slashRegistryCsvExport,
      slashInvokeAuditExportCsvExport,
+      oauthGrantCsvExport,
+      oauthInstallTokenExportCsvExport,
      archiveHealthPrefs,
      modDigestGroupDmMeta,
      workerReleaseHint,
@@ -10052,6 +10073,27 @@ class PearcordPlatform extends EventEmitter {
          this._slashInvokeAuditExportCsvDuplicateAt = ingested.exportedAt || slice.exportedAt || null
        }
      }
+      if (payload.oauthGrantCsvExport) {
+        await this._initDeliveryReceipts(payload.guildId)
+        const slice = payload.oauthGrantCsvExport
+        this._shouldGossipOAuthGrantCsv(slice)
+        const ingested = await this.deliveryReceipts.ingestOAuthGrantCsvSlice(payload.guildId, slice)
+        if (ingested?.duplicate) {
+          this._oauthGrantCsvDuplicateAt = ingested.exportedAt || slice.exportedAt || null
+        }
+      }
+      if (payload.oauthInstallTokenExportCsvExport) {
+        await this._initDeliveryReceipts(payload.guildId)
+        const slice = payload.oauthInstallTokenExportCsvExport
+        this._shouldGossipOAuthInstallTokenExportCsv(slice)
+        const ingested = await this.deliveryReceipts.ingestOAuthInstallTokenExportCsvSlice(
+          payload.guildId,
+          slice
+        )
+        if (ingested?.duplicate) {
+          this._oauthInstallTokenExportCsvDuplicateAt = ingested.exportedAt || slice.exportedAt || null
+        }
+      }
      if (payload.auditExportCsvExport) {
        await this._initDeliveryReceipts(payload.guildId)
        const slice = payload.auditExportCsvExport
@@ -10926,6 +10968,12 @@ class PearcordPlatform extends EventEmitter {
    guildInstance.on('slash-invoke-audit-export-csv-sync', (payload) => {
      this._onSlashInvokeAuditExportCsvGossip(payload).catch(() => {})
    })
+    guildInstance.on('oauth-grant-csv-sync', (payload) => {
+      this._onOAuthGrantCsvGossip(payload).catch(() => {})
+    })
+    guildInstance.on('oauth-install-token-export-csv-sync', (payload) => {
+      this._onOAuthInstallTokenExportCsvGossip(payload).catch(() => {})
+    })
    guildInstance.on('message-search-request', (payload) => {
      this._onMessageSearchRequestGossip(payload).catch(() => {})
    })
@@ -18349,7 +18397,8 @@ class PearcordPlatform extends EventEmitter {
        openRelayCsv: !!parsed.openRelayCsv,
        openWorkerCsv: !!parsed.openWorkerCsv,
        openBotCsv: !!parsed.openBotCsv,
-        openSlashCsv: !!parsed.openSlashCsv
+        openSlashCsv: !!parsed.openSlashCsv,
+        openOAuthCsv: !!parsed.openOAuthCsv
      }
    }

@@ -22179,6 +22228,290 @@ class PearcordPlatform extends EventEmitter {
    }
  }

+  async getOAuthGrantCsvExport () {
+    const gid = this.guild?.guild?.id || null
+    const span = this.log.time('oauth.csv', {
+      spanKind: 'oauth.csv',
+      guildId: gid,
+      context: 'read'
+    })
+    try {
+      if (!this.guild?.guild) {
+        span.end({ guildOAuthGrantCount: 0, skipped: true })
+        return null
+      }
+      await this._initDeliveryReceipts(this.guild.guild.id)
+      const row = await this.deliveryReceipts.getOAuthGrantCsvExport()
+      if (!row?.signature) {
+        span.end({ guildOAuthGrantCount: row ? 1 : 0, hasSignature: false, bridgeKind: 'oauth.csv' })
+        return row
+      }
+      const verified = verifyOAuthGrantCsv(row.csvBody, row.signature, {
+        guildId: this.guild.guild.id,
+        relaySecret: this.guild.guild.id
+      })
+      const out = { ...row, signatureValid: verified.ok }
+      span.end({
+        guildOAuthGrantCount: 1,
+        hasSignature: true,
+        signatureValid: verified.ok,
+        bridgeKind: 'oauth.csv'
+      })
+      return out
+    } catch (err) {
+      this.log.error('oauth.csv error', {
+        guildId: gid,
+        context: 'read',
+        error: err?.message || String(err)
+      })
+      span.fail(err)
+      throw err
+    }
+  }
+
+  async exportOAuthGrantCsv (opts = {}) {
+    if (!this.guild?.guild) throw new Error('no guild')
+    await this._initDeliveryReceipts(this.guild.guild.id)
+    const bots = await this.listBots()
+    const entries = bots.map((b) => ({
+      id: b.id,
+      name: b.name,
+      clientId: b.applicationId || b.id,
+      scopeState: b.publicKey ? 'verified' : 'pending',
+      scopeMask: b.permissions || 0,
+      createdAt: b.createdAt || Date.now()
+    }))
+    const csvBody = buildOAuthGrantCsvBody(entries)
+    const signed = signOAuthGrantCsv(csvBody, {
+      guildId: this.guild.guild.id,
+      relaySecret: this.guild.guild.id
+    })
+    const exportedAt = Date.now()
+    if (opts.recordMesh !== false) {
+      await this.deliveryReceipts.recordOAuthGrantCsvExport({
+        csvBody: signed.csv,
+        signature: signed.signature,
+        signatureAlg: signed.signatureAlg,
+        exportedAt
+      })
+    }
+    return {
+      format: 'csv',
+      body: signed.csv,
+      signature: signed.signature,
+      signatureAlg: signed.signatureAlg,
+      exportedAt,
+      grantCount: entries.length
+    }
+  }
+
+  async pushOAuthGrantCsvToMesh () {
+    const gid = this.guild?.guild?.id || null
+    const span = this.log.time('oauth.csv', {
+      spanKind: 'oauth.csv',
+      guildId: gid,
+      context: 'mesh.push'
+    })
+    try {
+      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 sync OAuth grant CSV')
+      }
+      const exported = await this.exportOAuthGrantCsv({ recordMesh: false })
+      if (!exported.signature) throw new Error('OAuth grant 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
+      }
+      if (this.guild.gossipOAuthGrantCsvSync) {
+        this.guild.gossipOAuthGrantCsvSync(payload)
+      }
+      this.emit('oauth-grant-csv-sync', payload)
+      await this.deliveryReceipts.recordOAuthGrantCsvExport({
+        csvBody: exported.body,
+        signature: exported.signature,
+        signatureAlg: exported.signatureAlg,
+        exportedAt: exported.exportedAt
+      })
+      span.end({
+        guildOAuthGrantCount: exported.grantCount || 1,
+        meshPushed: true,
+        bridgeKind: 'oauth.csv'
+      })
+      return exported
+    } catch (err) {
+      this.log.error('oauth.csv error', {
+        guildId: gid,
+        context: 'mesh.push',
+        error: err?.message || String(err)
+      })
+      span.fail(err)
+      throw err
+    }
+  }
+
+  async clearOAuthGrantCsvExports () {
+    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 clear OAuth grant CSV exports')
+    }
+    await this._initDeliveryReceipts(this.guild.guild.id)
+    const removed = await this.deliveryReceipts.clearOAuthGrantCsvExports()
+    this.emit('oauth-grant-csv-cleared', { removed })
+    return { removed }
+  }
+
+  async getLastOAuthInstallTokenExport () {
+    if (!this.guild?.guild) return null
+    const snap = this._lastOAuthInstallTokenExport
+    if (snap?.guildId === this.guild.guild.id) return snap
+    const commands = await this.listBots().catch(() => [])
+    return {
+      guildId: this.guild.guild.id,
+      exportedAt: Date.now(),
+      grantCount: commands.length,
+      signed: false,
+      meshPushed: false
+    }
+  }
+
+  async exportOAuthInstallTokenMesh (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 oauth install token mesh')
+    }
+    const bots = await this.listBots()
+    const entries = bots.slice(0, 32).map((b) => ({
+      name: b.name,
+      appName: b.name,
+      clientId: b.applicationId || b.id,
+      scopeState: b.publicKey ? 'verified' : 'pending',
+      exportedAt: Date.now(),
+      tokenIssued: !!b.publicKey
+    }))
+    const csvBody = buildOAuthInstallTokenExportCsvBody(entries)
+    const signed = signOAuthInstallTokenExportCsv(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,
+      grantCount: entries.length,
+      signed: !!signed.signature,
+      meshPushed: false
+    }
+    this._lastOAuthInstallTokenExport = meta
+    if (opts.recordMesh !== false) {
+      await this.deliveryReceipts.recordOAuthInstallTokenExportCsv({
+        csvBody: signed.csv,
+        signature: signed.signature,
+        signatureAlg: signed.signatureAlg,
+        exportedAt,
+        grantCount: entries.length
+      })
+    }
+    return {
+      format: 'csv',
+      body: signed.csv,
+      signature: signed.signature,
+      signatureAlg: signed.signatureAlg,
+      exportedAt,
+      grantCount: entries.length,
+      meta
+    }
+  }
+
+  async pushOAuthInstallTokenExportToMesh () {
+    const gid = this.guild?.guild?.id || null
+    const span = this.log.time('oauth.csv', {
+      spanKind: 'oauth.csv',
+      guildId: gid,
+      context: 'mesh.invoke'
+    })
+    try {
+      const exported = await this.exportOAuthInstallTokenMesh({ recordMesh: false })
+      if (!exported.signature) throw new Error('oauth install token 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,
+        grantCount: exported.grantCount || 0
+      }
+      if (this.guild.gossipOAuthInstallTokenExportCsvSync) {
+        this.guild.gossipOAuthInstallTokenExportCsvSync(payload)
+      }
+      this.emit('oauth-install-token-export-csv-sync', payload)
+      await this.deliveryReceipts.recordOAuthInstallTokenExportCsv({
+        csvBody: exported.body,
+        signature: exported.signature,
+        signatureAlg: exported.signatureAlg,
+        exportedAt: exported.exportedAt,
+        grantCount: exported.grantCount
+      })
+      this._lastOAuthInstallTokenExport = {
+        ...exported.meta,
+        meshPushed: true
+      }
+      span.end({
+        guildOAuthGrantCount: exported.grantCount || 0,
+        meshPushed: true,
+        bridgeKind: 'oauth.csv'
+      })
+      return exported
+    } catch (err) {
+      this.log.error('oauth.csv error', {
+        guildId: gid,
+        context: 'mesh.invoke',
+        error: err?.message || String(err)
+      })
+      span.fail(err)
+      throw err
+    }
+  }
+
+
+  async _onOAuthGrantCsvGossip (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._shouldGossipOAuthGrantCsv(payload)
+    const row = await this.deliveryReceipts.ingestOAuthGrantCsvSlice(payload.guildId, payload)
+    if (row?.duplicate) {
+      this._oauthGrantCsvDuplicateAt = row.exportedAt || payload.exportedAt || null
+    }
+    if (row) this.emit('oauth-grant-csv-sync', payload)
+    return row
+  }
+
+  async _onOAuthInstallTokenExportCsvGossip (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._shouldGossipOAuthInstallTokenExportCsv(payload)
+    const row = await this.deliveryReceipts.ingestOAuthInstallTokenExportCsvSlice(
+      payload.guildId,
+      payload
+    )
+    if (row?.duplicate) {
+      this._oauthInstallTokenExportCsvDuplicateAt = row.exportedAt || payload.exportedAt || null
+    }
+    if (row) this.emit('oauth-install-token-export-csv-sync', payload)
+    return row
+  }
+
  async getAuditExportSchedule () {
    if (!this.guild?.guild) {
      return { enabled: false, intervalHours: 24, filter: 'all', lastExportAt: 0 }
@@ -27038,6 +27371,10 @@ class PearcordPlatform extends EventEmitter {
    let slashRegistryCsvRows = []
    let slashInvokeAuditExportCsvRows = []
    let lastSlashInvokeAuditExport = null
+    let oauthGrantCsvMeta = null
+    let oauthGrantCsvRows = []
+    let oauthInstallTokenExportCsvRows = []
+    let lastOAuthInstallTokenExport = null
    let lastComplianceSnapshot = null
    let lastArchivePeerExport = null
    let automationScheduleDashboard = null
@@ -27159,6 +27496,27 @@ class PearcordPlatform extends EventEmitter {
        return { ...row, signatureValid: verified.ok }
      })
      lastSlashInvokeAuditExport = await this.getLastSlashInvokeAuditExport()
+      oauthGrantCsvMeta = await this.getOAuthGrantCsvExport().catch(() => null)
+      const oauthCsvHistory = await this.deliveryReceipts.listOAuthGrantCsvExports(32)
+      oauthGrantCsvRows = oauthCsvHistory.map((row) => {
+        if (!row?.signature || !guild?.id) return row
+        const verified = verifyOAuthGrantCsv(row.csvBody, row.signature, {
+          guildId: guild.id,
+          relaySecret: guild.id
+        })
+        return { ...row, signatureValid: verified.ok }
+      })
+      const oauthInstallCsvHistory =
+        await this.deliveryReceipts.listOAuthInstallTokenExportCsvExports(32)
+      oauthInstallTokenExportCsvRows = oauthInstallCsvHistory.map((row) => {
+        if (!row?.signature || !guild?.id) return row
+        const verified = verifyOAuthInstallTokenExportCsv(row.csvBody, row.signature, {
+          guildId: guild.id,
+          relaySecret: guild.id
+        })
+        return { ...row, signatureValid: verified.ok }
+      })
+      lastOAuthInstallTokenExport = await this.getLastOAuthInstallTokenExport()
      automationHealthDashboard = await this.getAutomationHealthDashboard()
      automationScheduleDashboard = automationHealthDashboard
      automationDigestNotifyPrefs = await this.getAutomationDigestNotifyPrefs()
@@ -28247,6 +28605,7 @@ const { relayCsvMixin } = require('./relay-csv-mixin')
 const { workerCsvMixin } = require('./worker-csv-mixin')
 const { botCsvMixin } = require('./bot-csv-mixin')
 const { slashCsvMixin } = require('./slash-csv-mixin')
+const { oauthCsvMixin } = require('./oauth-csv-mixin')
 Object.assign(PearcordPlatform.prototype, pollSchedulingMixin)
 Object.assign(PearcordPlatform.prototype, notificationsActivityMixin)
 Object.assign(PearcordPlatform.prototype, userSettingsMixin)
@@ -28269,3 +28628,4 @@ Object.assign(PearcordPlatform.prototype, relayCsvMixin)
 Object.assign(PearcordPlatform.prototype, workerCsvMixin)
 Object.assign(PearcordPlatform.prototype, botCsvMixin)
 Object.assign(PearcordPlatform.prototype, slashCsvMixin)
+Object.assign(PearcordPlatform.prototype, oauthCsvMixin)
@@ -0,0 +1,114 @@
+'use strict'
+
+const oauthCsvMixin = {
+  _oauthGrantCsvGossipKeys: null,
+  _oauthCsvHealWatermark: null,
+  _oauthInstallTokenCsvHealWatermark: null,
+
+  _initOauthCsvMixinState () {
+    if (!this._oauthGrantCsvGossipKeys) {
+      this._oauthGrantCsvGossipKeys = new Set()
+    }
+  },
+
+  _shouldGossipOAuthGrantCsv (slice) {
+    this._initOauthCsvMixinState()
+    if (!slice?.guildId || !slice?.signature) return true
+    const hash = `${slice.guildId}:${slice.exportedAt || 0}:${slice.signature}`
+    if (this._oauthGrantCsvGossipKeys.has(hash)) return false
+    this._oauthGrantCsvGossipKeys.add(hash)
+    if (this._oauthGrantCsvGossipKeys.size > 8192) {
+      const first = this._oauthGrantCsvGossipKeys.values().next().value
+      if (first) this._oauthGrantCsvGossipKeys.delete(first)
+    }
+    return true
+  },
+
+  _shouldGossipOAuthInstallTokenExportCsv (slice) {
+    this._initOauthCsvMixinState()
+    if (!slice?.guildId || !slice?.signature) return true
+    const hash = `install:${slice.guildId}:${slice.exportedAt || 0}:${slice.signature}`
+    if (this._oauthGrantCsvGossipKeys.has(hash)) return false
+    this._oauthGrantCsvGossipKeys.add(hash)
+    return true
+  },
+
+  async _healOAuthGrantExportCursorOnPartition (guildId) {
+    const gid = guildId || this.guild?.guild?.id || null
+    const span = this.log.time('oauth.csv', {
+      spanKind: 'oauth.csv',
+      guildId: gid,
+      context: 'heal.grant'
+    })
+    try {
+      if (!gid || !this.deliveryReceipts) {
+        span.end({ relisted: 0, skipped: true, guildOAuthGrantCount: 0 })
+        return { relisted: 0, skipped: true }
+      }
+      await this._initDeliveryReceipts(gid)
+      const rows = await this.deliveryReceipts.listOAuthGrantCsvExports(64)
+      let relisted = 0
+      for (const row of rows) {
+        if (this._shouldGossipOAuthGrantCsv(row)) relisted++
+      }
+      const watermark = Date.now()
+      this._oauthCsvHealWatermark = watermark
+      span.end({
+        relisted,
+        watermark,
+        guildOAuthGrantCount: rows.length,
+        bridgeKind: 'oauth.csv'
+      })
+      return { relisted, watermark, guildOAuthGrantCount: rows.length }
+    } catch (err) {
+      this.log.error('oauth.csv error', {
+        guildId: gid,
+        context: 'heal.grant',
+        error: err?.message || String(err)
+      })
+      span.fail(err)
+      return { relisted: 0, error: err?.message || String(err) }
+    }
+  },
+
+  async _healOAuthInstallTokenExportCursorOnPartition (guildId) {
+    const gid = guildId || this.guild?.guild?.id || null
+    const span = this.log.time('oauth.csv', {
+      spanKind: 'oauth.csv',
+      guildId: gid,
+      context: 'heal.install'
+    })
+    try {
+      if (!gid || !this.deliveryReceipts) {
+        span.end({ relisted: 0, skipped: true, guildOAuthGrantCount: 0 })
+        return { relisted: 0, skipped: true }
+      }
+      await this._initDeliveryReceipts(gid)
+      const rows = await this.deliveryReceipts.listOAuthInstallTokenExportCsvExports(64)
+      let relisted = 0
+      for (const row of rows) {
+        if (this._shouldGossipOAuthInstallTokenExportCsv(row)) relisted++
+      }
+      const watermark = Date.now()
+      this._oauthInstallTokenCsvHealWatermark = watermark
+      span.end({
+        relisted,
+        watermark,
+        guildOAuthGrantCount: rows.length,
+        grantCount: rows[0]?.grantCount || 0,
+        bridgeKind: 'oauth.csv'
+      })
+      return { relisted, watermark, grantCount: rows[0]?.grantCount || 0 }
+    } catch (err) {
+      this.log.error('oauth.csv error', {
+        guildId: gid,
+        context: 'heal.install',
+        error: err?.message || String(err)
+      })
+      span.fail(err)
+      return { relisted: 0, error: err?.message || String(err) }
+    }
+  }
+}
+
+module.exports = { oauthCsvMixin }