# 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.
- uexecute: FAITHFUL wiring chosen by user — /query moves onto core-go's
  authenticated router (WithDefaultMiddleware → core-go auth + server/database
  contexts) so the core-go webhook engine works unchanged. Accepted trade-off:
  AGENTS lose GraphQL /query reads (they keep MCP + REST; owner keeps /query;
  web/MCP/REST stay on the anon router with spec's authn). A cookie→INTERNAL
  override on /query makes NewAuthConfig/FilterWebhooks accept the owner (they
  refuse AUTH_COOKIE). Owner "user" row seeded at startup so core-go's LookupUser
  never calls out to meta.sr.ht.

### New deploy requirements (faithful path)
- `[mail] smtp-from` is now REQUIRED — WithDefaultMiddleware builds core-go's
  notification/email queue, which panics without it. A valid address; SMTP need
  not actually work for webhooks.
- Redis: WithDefaultMiddleware creates a client (default `redis://`), but it is
  lazy and outbound webhook delivery never touches it — no redis server needed.
- Agents can no longer read GraphQL /query (core-go auth is OAuth2/cookie only);
  they use MCP + REST. Owner keeps /query (cookie).

### 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). DONE in phase 4; reproducible.
- **Phase 3 runtime wiring — STRUCTURAL BLOCKER, needs user decision.** The
  core-go webhook engine's delivery (`WebhookContext.Exec`) requires
  `server.ForContext(ctx)` for Schema+MaxComplexity. `serverCtxKey` is
  UNEXPORTED with no public installer — the server context is installed ONLY by
  `WithDefaultMiddleware` (request path) and `WithQueues` (worker path, which
  needs WithDefaultMiddleware's db). WithDefaultMiddleware also installs core-go
  `auth.Middleware` on /query, which 401s spec's AGENT bearer tokens (core-go's
  bearer path is OAuth2-only). Net: faithful engine ⟹ /query behind core-go
  auth ⟹ agents lose GraphQL /query reads (they keep MCP/REST; owner keeps
  /query; web/MCP/REST unaffected on the anon router). Redis is a non-issue
  (lazy client, unused by outbound delivery). Two paths:
    (a) Adopt WithDefaultMiddleware for /query (faithful; accept the agent
        /query-read regression).
    (b) Spec-local firing: reuse dowork + crypto.SignWebhook + the gqlgen
        executor, skip core-go's server-context-coupled Exec (keeps agent
        /query, no core-go auth on /query; diverges from the "standard" engine).
  Phases 1-4 (DB, bridge, schema/models/resolvers) are committed and green
  regardless of this choice.