Define Edge Function environment variables and configuration schema
epic-scenario-based-follow-up-prompts-infrastructure-task-001 — Define and document all environment variables required by the Scenario Evaluation Edge Function, including SUPABASE_SERVICE_ROLE_KEY, cron frequency config, kill-switch feature flag name, and scheduler service endpoint. Create a typed configuration schema that validates all required env vars at function startup and throws descriptive errors on misconfiguration.
Acceptance Criteria
Technical Requirements
Implementation Notes
In Deno Edge Functions, environment variables are accessed via Deno.env.get(). Implement loadConfig() as a synchronous function that collects all validation errors into an array before throwing, so operators see the complete list of misconfiguration issues in a single deployment failure rather than finding them one-by-one. Export the config type as a readonly interface to prevent mutation after initialisation. Use const assertions on the default values.
The .env.example file is the canonical documentation for operators — keep it up to date as new variables are added. Avoid using a third-party validation library (e.g., zod) unless already present in the Edge Function dependencies — keep the function's dependency surface minimal for cold-start performance.
Testing Requirements
Deno unit tests (using Deno.test) in a config.test.ts file. Test cases: (1) all required env vars set → loadConfig() returns correct typed object, (2) SUPABASE_SERVICE_ROLE_KEY missing → ConfigurationError thrown with descriptive message naming the missing var, (3) multiple vars missing → single error listing all missing vars, (4) CRON_FREQUENCY_MINUTES set to non-numeric string → ConfigurationError with type mismatch message, (5) CRON_FREQUENCY_MINUTES absent → config returns with default value 60 and a warning is emitted. Run with deno test --allow-env.
Supabase Edge Functions on Deno can have cold-start latency of 500ms–2s. If the evaluation window contains many activities (e.g., post-holiday catch-up), the function may approach the 60-second invocation timeout before completing all evaluations.
Mitigation & Contingency
Mitigation: Implement pagination in the activity fetch query with a configurable page size; process pages sequentially and commit history records per page so partial runs are recoverable on the next invocation.
Contingency: If timeout remains an issue at scale, split the evaluation into per-chapter invocations triggered by a fan-out pattern using Supabase Realtime or a lightweight queue.
Supabase cron triggers (pg_cron or Edge Function schedules) may miss invocations during platform maintenance windows, causing evaluation gaps that delay time-sensitive prompts beyond their intended delivery window.
Mitigation & Contingency
Mitigation: Configure the look-back window to be 2× the cron interval (e.g., 2-hour look-back for hourly cron) so a single missed invocation does not result in missed prompts; log each run's look-back range for auditability.
Contingency: If missed invocations are detected via monitoring alerts, implement a manual re-trigger endpoint accessible to admins that runs the evaluation for a specified time range.