Merge pull request #353 from mean-weasel/codex/per-install-feedback-count

feat: count feedback by GitHub installation

Author: neonwatty

docs/installation-usage-counting.md

@@ -0,0 +1,61 @@
+# Per-installation successful feedback counts
+
+BugDrop can privately count successful GitHub Issues per GitHub App installation without adding a
+database. The feature reuses the existing `FEEDBACK_COUNTER` Durable Object namespace for atomic
+counts and asynchronously mirrors the latest durable integer into the existing
+`INSTALLATION_ANALYTICS` KV namespace for the operator-only consent review.
+
+## Data boundary
+
+Each usage record contains exactly:
+
+```json
+{
+  "schemaVersion": 1,
+  "installationId": 123,
+  "successfulFeedbackCount": 7
+}
+```
+
+The count covers successful feedback Issues created in every repository available through that
+installation. It is prospective and does not backfill older Issues. BugDrop does not store the
+repository, Issue contents, reporter, submission timestamp, or last-active date in this record.
+The public aggregate feedback counter remains separate and rounded.
+
+## Activation and rollback
+
+Collection is off unless `INSTALLATION_USAGE_ENABLED` is exactly `true`. Do not enable it until the
+published privacy policy accurately discloses the purpose, fields, retention, and deletion behavior.
+Turning the setting off immediately stops accepting new per-installation events without affecting
+the public anonymous total. A count already accepted by the Durable Object may finish mirroring to
+KV. Keep the existing `FEEDBACK_COUNTER` binding available after activation so uninstall cleanup
+can remove previously stored durable counts.
+
+After enabling it, dogfood one controlled installation and verify that its private record has only
+the three allowed fields above. Uninstall it and verify that the identity, usage mirror, and atomic
+counter are removed.
+
+## Deletion behavior
+
+While collection is enabled, an uninstall webhook or retention sweep first writes a seven-day
+opaque KV deletion guard, then sets a strongly consistent seven-day deletion marker in the
+installation's Durable Object. It then deletes the atomic count and KV usage mirror, and removes the
+installation identity last. This order makes a partial cleanup retryable and prevents a delayed
+in-flight submission from recreating usage after uninstall. While collection is disabled, cleanup
+hard-purges any old counter and mirror without creating those guards. No installation ID or account
+identity is exposed through a public endpoint.
+
+The Durable Object coalesces bursts into a single delayed KV write, avoiding Workers KV's
+same-key write-rate limit. Its alarm retries a failed mirror write; the operator view can lag a
+successful submission briefly while the durable count remains authoritative.
+
+The mirror is not created until the installation identity record is visible. If that record is
+still propagating, the Durable Object makes at most 1,440 one-minute retry checks without resetting
+the original budget. The budget is a non-temporal integer; no submission timestamp is stored. If no
+identity arrives, it purges the unanchored counter instead of retaining usage that the scheduled
+cleanup cannot discover. This intentionally favors deletion safety over completeness for a
+pre-tracking installation or a permanently missed installation-created webhook.
+
+Delivery uses one opaque event ID across retries, so an ambiguous retry does not increment twice.
+It has the same best-effort delivery boundary as the existing anonymous public counter; it is not a
+billing ledger.

docs/social-proof-consent.md

@@ -12,8 +12,9 @@ authorizes public display from an installation alone.
   inside the repository, including paths reached through a symlinked parent directory, and refuses
   input files readable or writable by other users.
 - Never commit the registry, fingerprint key, permission evidence, or installation identities.
-- Do not add repository information, usage frequency, issue counts, email addresses, or other
-  enrichment to this workflow.
+- Do not add repository information, issue contents, reporter details, email addresses, last-active
+  dates, or other enrichment to this workflow. The only allowed usage signal is the exact count of
+  successful feedback Issues associated with an installation.
 - Contact an app owner at most once unless they reply. Record `contacted`, `declined`, `approved`,
   or `withdrawn` before reviewing candidates again.
 - Publishing requires affirmative permission from an authorized representative. Copy only the
@@ -45,11 +46,13 @@ npm run social-proof:consent -- review \
   --exclude mean-weasel,neonwatty
 ```
 
-The private terminal displays the currently eligible account, profile, installation date, and its
-keyed fingerprint. The command does not save those installation identities to another file. Close
-the terminal session after finishing the review. The command rejects installation records with any
-fields beyond the approved minimal schema. The exclusion list is required so owned and controlled
-test accounts cannot accidentally enter the outreach queue.
+The private terminal displays the currently eligible account, profile, installation date, keyed
+fingerprint, and—when collection was enabled for that installation—the successful-feedback count.
+Known counts are ranked highest first; a missing count is not presented as zero. The command does
+not save installation identities or usage counts to another file. Close the terminal session after
+finishing the review. The command rejects identity and usage records with any fields beyond their
+approved minimal schemas. The exclusion list is required so owned and controlled test accounts
+cannot accidentally enter the outreach queue.
 
 ## Record decisions
 
@@ -80,6 +83,6 @@ npm run social-proof:consent -- export-approved \
   --output /private/path/bugdrop-approved-social-proof.json
 ```
 
-This export contains only approved public profile fields. It omits account fingerprints, private
-evidence references, contact status, and all unapproved apps. Review the output against the
-permission evidence before copying it into the website repository.
+This export contains only approved public profile fields. It omits account fingerprints, usage
+counts, private evidence references, contact status, and all unapproved apps. Review the output
+against the permission evidence before copying it into the website repository.

scripts/social-proof-consent-lib.mjs

@@ -27,20 +27,33 @@ export function buildCandidateReview(
   registry,
   excludedLogins,
   fingerprintKey,
-  generatedAt = new Date().toISOString()
+  generatedAt = new Date().toISOString(),
+  usageRecords = []
 ) {
   validateRegistry(registry);
   validateRegistryKey(registry, fingerprintKey);
   assertIsoDate(generatedAt);
   const excluded = new Set(validateExcludedLogins(excludedLogins));
+  const usageByInstallation = new Map();
+  for (const record of usageRecords) {
+    const valid = validateInstallationUsageRecord(record);
+    if (usageByInstallation.has(valid.installationId)) {
+      throw new Error('Duplicate installation usage record');
+    }
+    usageByInstallation.set(valid.installationId, valid.successfulFeedbackCount);
+  }
   const decided = registry.entries.map(entry => Buffer.from(entry.accountFingerprint, 'hex'));
   const eligible = records
     .map(validateInstallationRecord)
-    .map(record => ({
-      account: record.account,
-      installedAt: record.installedAt,
-      accountFingerprint: fingerprintAccount(record.account.login, fingerprintKey),
-    }))
+    .map(record => {
+      const successfulFeedbackCount = usageByInstallation.get(record.installationId);
+      return {
+        account: record.account,
+        installedAt: record.installedAt,
+        accountFingerprint: fingerprintAccount(record.account.login, fingerprintKey),
+        ...(successfulFeedbackCount === undefined ? {} : { successfulFeedbackCount }),
+      };
+    })
     .filter(
       record =>
         !excluded.has(record.account.login.toLocaleLowerCase('en-US')) &&
@@ -56,13 +69,26 @@ export function buildCandidateReview(
       candidatesByAccount.set(candidate.accountFingerprint, candidate);
     }
   }
-  const candidates = [...candidatesByAccount.values()].sort((a, b) =>
-    a.installedAt.localeCompare(b.installedAt)
-  );
+  const candidates = [...candidatesByAccount.values()].sort(compareCandidatePriority);
 
   return { schemaVersion: 1, generatedAt, candidates };
 }
 
+function validateInstallationUsageRecord(record) {
+  if (
+    !isObject(record) ||
+    !hasExactKeys(record, ['schemaVersion', 'installationId', 'successfulFeedbackCount']) ||
+    record.schemaVersion !== 1
+  ) {
+    throw new Error('Invalid installation usage record');
+  }
+  assertPositiveInteger(record.installationId);
+  if (!Number.isSafeInteger(record.successfulFeedbackCount) || record.successfulFeedbackCount < 0) {
+    throw new Error('Invalid installation usage record');
+  }
+  return record;
+}
+
 export function buildApprovedExport(registry, generatedAt = new Date().toISOString()) {
   validateRegistry(registry);
   assertIsoDate(generatedAt);
@@ -193,6 +219,16 @@ function validateInstallationRecord(record) {
   return record;
 }
 
+function compareCandidatePriority(a, b) {
+  const aKnown = Number.isSafeInteger(a.successfulFeedbackCount);
+  const bKnown = Number.isSafeInteger(b.successfulFeedbackCount);
+  if (aKnown !== bKnown) return aKnown ? -1 : 1;
+  if (aKnown && a.successfulFeedbackCount !== b.successfulFeedbackCount) {
+    return b.successfulFeedbackCount - a.successfulFeedbackCount;
+  }
+  return b.installedAt.localeCompare(a.installedAt);
+}
+
 function normalizeGitHubLogin(value) {
   if (typeof value !== 'string' || !/^[A-Za-z0-9](?:[A-Za-z0-9-]{0,98}[A-Za-z0-9])?$/.test(value)) {
     throw new Error('Invalid GitHub account');

scripts/social-proof-consent.mjs

@@ -16,6 +16,7 @@ import {
 
 const execFileAsync = promisify(execFile);
 const INSTALLATION_PREFIX = 'installation:';
+const INSTALLATION_USAGE_PREFIX = 'installation-usage:';
 const REPOSITORY_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
 async function readInstallationRecords() {
@@ -38,10 +39,13 @@ async function readInstallationRecords() {
     const keys = JSON.parse(listed.stdout);
     if (!Array.isArray(keys)) throw new Error('invalid list');
 
-    const records = [];
+    const installations = [];
+    const usageRecords = [];
     for (const item of keys) {
       if (!isObject(item) || typeof item.name !== 'string') throw new Error('invalid key');
-      if (!item.name.startsWith(INSTALLATION_PREFIX)) continue;
+      const isInstallation = item.name.startsWith(INSTALLATION_PREFIX);
+      const isUsage = item.name.startsWith(INSTALLATION_USAGE_PREFIX);
+      if (!isInstallation && !isUsage) continue;
       const result = await execFileAsync(
         wrangler,
         [
@@ -58,9 +62,11 @@ async function readInstallationRecords() {
         ],
         { cwd: REPOSITORY_ROOT, maxBuffer: 1024 * 1024 }
       );
-      records.push(JSON.parse(result.stdout));
+      const record = JSON.parse(result.stdout);
+      if (isUsage) usageRecords.push(record);
+      else installations.push(record);
     }
-    return records;
+    return { installations, usageRecords };
   } catch {
     throw new Error('Unable to read installation records from Cloudflare KV');
   }
@@ -178,8 +184,17 @@ export async function runCli(args, dependencies = {}) {
     const registry = await readRegistry(options.registry);
     const fingerprintKey = await readFingerprintKey(options.key);
     validateRegistryKey(registry, fingerprintKey);
-    const records = await readRecords();
-    const review = buildCandidateReview(records, registry, excludedLogins, fingerprintKey);
+    const result = await readRecords();
+    const installations = Array.isArray(result) ? result : result.installations;
+    const usageRecords = Array.isArray(result) ? [] : result.usageRecords;
+    const review = buildCandidateReview(
+      installations,
+      registry,
+      excludedLogins,
+      fingerprintKey,
+      new Date().toISOString(),
+      usageRecords
+    );
     showReview(review);
     return `Reviewed ${review.candidates.length} outreach candidate(s) without saving identities.`;
   }