Dispatch admin feedback subscription events

[kentcdodds]

Summary

• enqueue an opaque platform.feedback.submitted event after successful feedback persistence
• add a dedicated Cloudflare Queue with retries/DLQ and route delivery to current admin-owned package subscribers
• bound fan-out concurrency and retry discovery/pre-execution infrastructure failures without retrying terminal handler errors

Testing

• npm run validate passes: formatting, lint, typecheck, primitive map, 897 unit tests, 15 Playwright E2E tests, and 2 MCP E2E tests.
• Focused queue, routing, provisioning, admin/non-admin fan-out, retry, and system-email regression tests pass.
• Two independent final architecture reviews report CLEAN.

System recap — adds a new primitive (high risk)

Mode: recap · Base: main @ b962f946 · Head: 69365373

Classification: adds — introduces a dedicated durable platform-feedback dispatch queue while extending existing feedback and package-subscription behavior.

Primitives touched

Primitive	Group	Impact
platform-feedback-dispatch-queue	storage	adds — producer, consumer, retries, and DLQ
platform-feedback	assistant	extends — enqueues opaque metadata after persistence
saved-packages	assistant	extends — discovers current admin-owned subscribers
capability-registry	assistant	extends — subscription discovery and guide metadata
email-delivery-queue	storage	extends — shares queue routing without changing email payloads
email	assistant	composes — retains best-effort fan-out defaults

System map

Persisted feedback enqueues only its id; the durable consumer rebuilds opaque event metadata, rechecks current admin roles, and invokes matching saved-package handlers with bounded concurrency.

Legend: green = composes (wiring only) · amber = extended by this PR · red = new primitive · gray = context (unchanged, included only when an edge crosses it).

flowchart LR
	platformFeedback["platform-feedback<br/>Platform feedback"]:::extended
	feedbackQueue["platform-feedback-dispatch-queue<br/>Platform feedback dispatch queue"]:::added
	rbac["rbac<br/>Role-based access control"]:::untouched
	savedPackages["saved-packages<br/>Saved packages"]:::extended
	packageRuntime["package-runtime<br/>Package runtime"]:::untouched
	emailQueue["email-delivery-queue<br/>Email delivery event queue"]:::extended
	platformFeedback -->|"send { feedbackId } after insert"| feedbackQueue
	feedbackQueue -->|"load opaque id/category/status/time"| rbac
	rbac -->|"fresh admin-owner selection"| savedPackages
	savedPackages -->|"bounded idempotent handler invocation"| packageRuntime
	emailQueue -->|"shared Worker queue router"| packageRuntime
	classDef touched fill:#1a7f37,color:#fff
	classDef extended fill:#9a6700,color:#fff
	classDef added fill:#cf222e,color:#fff
	classDef untouched fill:#57606a,color:#fff

Loading

Change flow

sequenceDiagram
	participant Agent
	participant Feedback as Platform feedback
	participant Queue as Feedback dispatch queue
	participant RBAC
	participant Packages as Saved packages
	participant Runtime as Package runtime
	Agent->>Feedback: Approved interactive submission
	Feedback->>Feedback: Persist open feedback row
	Feedback->>Queue: Enqueue feedback id
	Feedback-->>Agent: Return immediately after durable enqueue
	Queue->>Feedback: Load current record metadata
	Queue->>RBAC: Query current admin accounts
	RBAC-->>Packages: Admin owner ids only
	Packages->>Runtime: Invoke matching handlers, max five concurrently
	Queue->>Queue: Ack success/terminal failure; retry discovery/infrastructure failure

Loading

Invariants

• The queue and package-event payloads contain no submitter identity or user-authored text.
• Rejected feedback emits nothing; enqueue failure never turns a persisted submission into a client-visible failure.
• Every delivery re-reads current admin roles; non-admin package declarations are inert.
• Queue redelivery is safe through per-feedback/per-package invocation idempotency.
• Discovery and pre-execution infrastructure failures retry/DLQ; terminal handler failures stay isolated.

  

Summary by CodeRabbit

• New Features

  • Added an admin-only platform.feedback.submitted subscription topic.
  • Platform feedback submissions now support durable delivery with privacy-preserving metadata.
  • Added automatic retries and dead-letter recovery for temporary delivery failures.
  • Subscriber failures are isolated so they do not block other package notifications.

• Documentation

  • Updated subscription, setup, architecture, and contribution guides with event behavior, privacy boundaries, and recovery details.

• Bug Fixes

  • Failed notification delivery no longer affects successful feedback submission responses.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 90a91763-41c7-432b-9800-8f8cfa0297df

📥 Commits

Reviewing files that changed from the base of the PR and between b962f94 and 6936537.

📒 Files selected for processing (30)

• docs/contributing/architecture/authorization.md
• docs/contributing/architecture/primitives.yaml
• docs/contributing/packages-and-manifests.md
• docs/contributing/setup-manifest.md
• docs/guides/package-subscriptions.md
• packages/worker/src/email/delivery-queue.ts
• packages/worker/src/email/package-subscriptions.ts
• packages/worker/src/index.ts
• packages/worker/src/mcp/capabilities/admin/platform-feedback-shared.ts
• packages/worker/src/mcp/capabilities/coding/kody-official-guide.ts
• packages/worker/src/mcp/capabilities/meta/meta-platform-feedback-submit.ts
• packages/worker/src/mcp/capabilities/packages/list-package-subscriptions.ts
• packages/worker/src/mcp/capabilities/platform-feedback-capabilities.node.test.ts
• packages/worker/src/package-invocations/admin-package-subscriptions.ts
• packages/worker/src/platform-feedback/content-warning.ts
• packages/worker/src/platform-feedback/dispatch-queue-names.ts
• packages/worker/src/platform-feedback/dispatch-queue-producer.ts
• packages/worker/src/platform-feedback/dispatch-queue.node.test.ts
• packages/worker/src/platform-feedback/dispatch-queue.ts
• packages/worker/src/platform-feedback/package-subscriptions.node.test.ts
• packages/worker/src/platform-feedback/package-subscriptions.ts
• packages/worker/src/platform-feedback/platform-feedback-subscriptions.workers.test.ts
• packages/worker/src/platform-feedback/subscription-event.ts
• packages/worker/src/queue-handler.node.test.ts
• packages/worker/src/queue-handler.ts
• packages/worker/worker-configuration.d.ts
• packages/worker/wrangler.jsonc
• tools/ci/production-queue-resources.node.test.ts
• tools/ci/production-queue-resources.ts
• tools/ci/production-resources.ts

---

📝 Walkthrough

Walkthrough

This change adds durable platform.feedback.submitted queue dispatch for consent-gated platform feedback, admin-only package fan-out with opaque metadata, retry and DLQ handling, worker routing, production queue provisioning, and related documentation and capability metadata.

Changes

Platform feedback dispatch

Layer / File(s)	Summary
Event contract and durable enqueue packages/worker/src/platform-feedback/*, packages/worker/src/mcp/capabilities/meta/meta-platform-feedback-submit.ts, packages/worker/src/mcp/capabilities/platform-feedback-capabilities.node.test.ts	Feedback events contain limited metadata, and successful persistence enqueues the feedback ID without changing the response on enqueue failure.
Admin subscription discovery and invocation packages/worker/src/package-invocations/admin-package-subscriptions.ts, packages/worker/src/platform-feedback/package-subscriptions.ts, packages/worker/src/email/package-subscriptions.ts, packages/worker/src/platform-feedback/*test.ts	Shared admin fan-out discovers current subscriptions, applies bounded concurrency and idempotency, isolates terminal failures, and retries configured infrastructure failures.
Queue routing and feedback processing packages/worker/src/queue-handler.ts, packages/worker/src/platform-feedback/dispatch-queue.ts, packages/worker/src/index.ts, packages/worker/src/*queue*.test.ts	The worker routes queue batches, acknowledges invalid or missing feedback, dispatches valid records, and retries processing errors.
Production queue configuration and provisioning packages/worker/wrangler.jsonc, packages/worker/worker-configuration.d.ts, tools/ci/production-queue-resources.ts, tools/ci/production-resources.ts, tools/ci/production-queue-resources.node.test.ts	Production configuration and provisioning now validate and create the platform feedback dispatch queue and DLQ.
Documentation and capability metadata docs/contributing/*, docs/guides/package-subscriptions.md, packages/worker/src/mcp/capabilities/coding/kody-official-guide.ts, packages/worker/src/mcp/capabilities/packages/list-package-subscriptions.ts	Documentation and capability descriptions define the new topic, payload, authorization, retry, and queue behavior.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant FeedbackSubmit
  participant DispatchQueue
  participant QueueConsumer
  participant AdminPackageDispatcher
  participant PackageHandler
  FeedbackSubmit->>DispatchQueue: enqueue feedbackId
  DispatchQueue->>QueueConsumer: deliver feedbackId
  QueueConsumer->>AdminPackageDispatcher: dispatch valid feedback
  AdminPackageDispatcher->>PackageHandler: invoke matching admin subscription

Loading

Possibly related PRs

• kentcdodds/kody#783: Adds the consent-gated platform feedback capability and underlying storage/service foundation used by this dispatch pipeline.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 6.25% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: adding dispatch for admin-scoped feedback subscription events.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch cursor/platform-feedback-events-d866

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

🔎 Preview deployed: https://kody-pr-784.kody-a99.workers.dev

Worker: kody-pr-784
D1: kody-pr-784-db
KV: kody-pr-784-oauth-kv

Mocks:

• cloudflare: https://kody-pr-784-mock-cloudflare.kody-a99.workers.dev/__mocks (kody-pr-784-mock-cloudflare)