lifecycle hooks at ingestion, query, alert evaluation and webhook dispatch (#216)

[Polliog]

Refs #216.

What

A small, typed set of four named lifecycle hooks, no-op by default in OSS:

Phase	When	Context
beforeIngest	after auth/PII/quota, before reservoir write (covers HTTP + OTLP logs)	org, project, eventCount, byteSize, mutable records
beforeQuery	top of queryLogs, before the cache key	org, projectIds, mutable params
beforeAlertEvaluation	per rule in the eval loop	org, ruleId, ruleType
beforeWebhookDispatch	before safeFetch (channel + legacy alert paths)	org, channelId/ruleId, readonly url/host, mutable headers/body

Handlers run sequentially in registration order, may mutate the documented fields, and abort by throwing HookRejectionError(code, message, statusCode) which the global error handler surfaces like capability errors. Unexpected hook errors fail closed (500, chained via Error.cause), except in the alert loop where a failing hook skips only that rule and the batch continues.

Registration

• Code-level: hooks.register(...) from src/hooks/index.js in a downstream bootstrap.
• Container: HOOKS_MODULES env (comma-separated module paths default-exporting (hooks, helpers) => void), loaded at boot on server and worker, fatal on load failure. External modules receive { HookRejectionError } as the second arg so they can produce clean 4xx rejections.

Notes

• beforeIngest realigns downstream consumers (sigma, exceptions, pipelines, metering, correlation) when a hook filters records; a tenancy guard fails closed if a hook rewrites a record's projectId.
• OTLP logs route passes 4xx hook statuses through and maps 5xx hook failures to retryable 503 (a 400 would tell exporters to permanently drop the batch).
• Contract documented in docs/lifecycle-hooks.md.

Tests

56 new hook tests (registry, loader, all four call sites, HTTP-stack rejection). Full backend suite green except the pre-existing env-only digests/generator number-locale failures on Windows.

[codecov]

Codecov Report

❌ Patch coverage is 93.79845% with 16 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
packages/backend/src/modules/ingestion/service.ts	82.35%	9 Missing ⚠️
...otification-channels/providers/webhook-provider.ts	91.66%	2 Missing ⚠️
...kages/backend/src/queue/jobs/alert-notification.ts	95.45%	2 Missing ⚠️
...ckend/src/modules/notification-channels/service.ts	0.00%	1 Missing ⚠️
packages/backend/src/modules/otlp/routes.ts	92.30%	1 Missing ⚠️
packages/backend/src/server.ts	50.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!