feat: DO-backed webhook workflow - thread-safe, stateful, topic-separated

[brendadeeznuts1111]

🎯 Purpose

Implements complete DO-backed webhook workflow for thread-safe, stateful GitHub webhooks.

Problem:

• Existing webhooks are stateless and can have race conditions
• No persistence of pinned message state
• Manual wrangler/cf commands required
• No topic separation for different streams

Solution:

• Durable Object-backed webhooks with thread-safety guarantees
• Stateful persistence of pinned message IDs
• Topic-separated DO instances per stream
• Complete CLI-wrapped workflow using ./tgk
• Zero downtime deployments via stage promotion

---

📋 Changes

🏗️ Implementation

DO Class (src/do/github-agent.ts)

• Thread-safe webhook processing via DO single-threading
• Stateful pinned message ID persistence
• Automatic unpin/pin message management
• Topic-specific Telegram routing

Worker Entry (workers/github-webhook/index.ts)

• Stream-based DO instance routing
• Topic header injection for DO class
• Default stream fallback to 'forum-polish'

Alchemy IaC (alchemy.run.ts patch)

• DurableObject resource definition
• Worker bindings with environment variables
• Stage/profile/scope mechanics integration

🚀 Workflow

7-Step Terminal Session:

1. Prep: Export topic IDs, configure GitHub webhook
2. Create: ./tgk stage create for feature branch
3. Write: Three artefacts (DO class, worker, IaC)
4. Deploy: ./tgk deploy (atomic transaction)
5. Test: Concurrency simulation to verify thread-safety
6. Promote: ./tgk stage promote to production
7. Monitor: ./tgk logs for observability

🔧 CLI Enhancements

New tgk Commands:

• ./tgk stage create <name> - Create branch + stage
• ./tgk deploy - Deploy with wrapper
• ./tgk hook simulate <stream> --pr <num> --action <type> - Test concurrency
• ./tgk stage promote <from> <to> - Zero downtime promotion
• ./tgk logs worker <name> --stage <stage> --follow - Observability

---

🧪 Testing

Concurrency Test:

# Terminal 1
./tgk hook simulate mobile-app --pr 42 --action review

# Terminal 2 (immediate)
./tgk hook simulate mobile-app --pr 42 --action push

# Expected: Only second payload survives as pinned message
# Verifies DO thread-safety and state persistence

Production Promotion:

• Zero downtime via stage switching
• DO ID namespace change (pr-003 → prod)
• Automatic cleanup of old resources

---

✅ Pre-Submission Checklist

• DO Thread-Safety: Single-threaded execution guarantees
• State Persistence: Pinned message IDs survive restarts
• Topic Separation: Different DO instances per stream
• CLI Wrapped: No raw wrangler/cf commands
• Stage/Profile/Scope: Uses ratified Alchemy mechanics
• Zero Downtime: Atomic stage promotion
• Rollback Ready: Instant fallback to stateless mode

---

📚 Documentation

Added: docs/do-webhook-workflow.md

• Complete implementation guide
• Step-by-step workflow
• Artefact code samples
• Testing procedures
• Observability commands

---

🔗 Related

Builds on:

• feat: AlchemistOrgDoc v2.0 - Complete Documentation Suite + Automation #42 (AlchemistOrgDoc v2.0 - merged)
• feat(profiles): implement profile validation, rotation, and auto-refresh #43 (Profile enhancements - tracked)
• feat(scopes): implement state-file locking, granular finalize, and retry logic #44 (Scope enhancements - tracked)

References branches:

• main (current production)
• telegram-worker-clean (merged to main)
• telegram (diverged, contains some related work)

---

👥 Reviewers

Infrastructure Team: @brendadeeznuts1111
Department: Infrastructure
Type: Feature
Component: Worker, Webhook, DO

---

📊 Impact

Thread-Safety: Eliminates webhook race conditions
Statefulness: Persistent pinned messages across deployments
Topic Separation: Stream-specific DO instances
CLI Experience: Never leave ./tgk wrapper
Zero Downtime: Production deployments without interruption

---

Ready to review and merge! 🚀

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/do-backed-webhook-workflow

---

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 and usage tips.}