docs: research — event-driven agent triggers (App Event) for external source systems

[esafwan]

Research dossier feeding the App Event implementation plan (source: CodeDiscovery B-02 + owner design brief). Analysis only, no code.

Contents (all code claims file:line-verified against develop @ 95daa90; external claims cited to primary docs):

• Part 1 — current state: only Schedule + Doc Event triggers are wired; App Event is schema-only with zero backend; feat(agent-trigger): Webhook and Manual trigger backends (CodeDiscovery B-02) #412's Webhook/Manual foundation (unmerged branch reviewed); the google_services assumption checked — it does NOT hold (sibling checkout is an unrelated Google Places app, no OAuth; HUF's real Google path is refresh-token POSTs via credentials.py, no consent flow, unpersisted access tokens).
• Part 2 — external mechanics: Gmail watch+Pub/Sub (OIDC JWT auth, 7-day re-watch, pings not payloads), Calendar channels (headers-only, ~1 week, overlap dupes), Slack Events API (HMAC signing secret + url_verification + 3s ack), Frappe outbound Webhook (HMAC signature header).
• Part 3 — critical evaluation of the proposed design (Source System DocType + one endpoint + virtual-trigger matcher): 6 elements hold (2 with modifications), 9 concrete breaks/underspecs identified — the big ones: one slug/key endpoint cannot authenticate all four systems (needs per-system auth adapters); Google delivers pings not events (sync loop, not webhook relay); per-event external_id would fragment conversations; conversation identity must be per source-user.
• Part 4 — verdicts + phase-1 Gmail spike outline + 8 open questions for the owner (incl. ordering: research recommends proving the bus with Slack/ERPNext first — cheapest true end-to-end — and taking Google as the first sync-driven system).

Agent contributions

Research + report by the automated release-orchestration pipeline (task RES-app-event-triggers); pipeline-reviewed.

Tests

None (docs-only).