#Phase 5a — GraphQL-native webhooks (proposal lifecycle)

Mode: hands-off Branch: feat/phase5a-webhooks Beads: spec-3m9 (epic), spec-8y4 (conventions), spec-45j (webhook feature)

#Design

Emit webhooks on proposal open/merge/reject, GraphQL-native, matching the core-go webhook engine used by pages.sr.ht / lists.sr.ht. spec.sr.ht keeps its own authn (owner/agent/anonymous + provenance) as the single auth policy — core-go's auth model has no agent concept — and a thin adapter derives the core-go auth.AuthContext the webhook engine consumes. Webhooks are owner-scoped (gql_user_wh_sub, one user = the owner); events are PROPOSAL_OPENED / PROPOSAL_MERGED / PROPOSAL_REJECTED; the agent identity that triggered an event rides in the payload (the proposal), not the auth context.

Reference: /Users/blikh/data/home/tmp/pages.sr.ht (same fork).

#Plan (phases)

1. DB foundation — user table + owner seed; webhook_event / auth_method enums; gql_user_wh_sub + gql_user_wh_delivery tables. schema.sql + migrations/0003.
2. AuthContext bridge — an in-spec adapter mapping authn.Principal → core-go auth.AuthContext (owner→AUTH_COOKIE+UserID; agent→owner's UserID), factored to lift into a future sr-ht-ext module.
3. Server + context wiring — install core-go database + webhooks context on /query and the delivery worker; keep spec's surfaces/auth intact (no core-go 401-by-default).
4. Webhook SDL + models + resolvers — WebhookEvent/Subscription/Delivery/ Payload types, create/delete mutations, webhooks/webhook queries, the webhook payload root field; gqlgen regen.
5. Firing — service event hook → webhooks.Schedule on open/merge/reject.

#Conclusion

#Hands-off decisions

• make: Mode hands-off (user invoked /up:handsoff).
• make: dedicated branch feat/phase5a-webhooks; worktree skipped — session is configured for in-place work; isolation via the branch, master untouched.
• udesign: keep spec's authn as the single auth policy; derive a core-go auth.AuthContext for the webhook engine only (core-go auth cannot model agents/provenance without breaking Phases 3-4).
• uplan: adopt core-go's webhook ENGINE (queue/delivery/Ed25519 signing/ GraphQL-native Exec) + the pages.sr.ht schema/SDL shape; do NOT rewrite the existing read resolvers onto database.Model — only the webhook models need it.
• uplan: webhooks are owner-scoped (gql_user_wh_sub), matching pages.sr.ht's user-scoped pattern; the single owner is the only user.

#Deferred (needs user input)

• extensions-go / sr-ht-ext module — extracting spec's agent model into a shared module (location, name, publish target, CI wiring). User said it's "too early to judge"; building the bridge in-spec, factored for later extraction. Revisit when a second consumer exists or after this ships.
• gqlgen regeneration runs go generate ./graph (pulls gqlgen at generate-time and rewrites graph/api/generated.go). Will run during phase 4; flagged.