# Scratchpad — Extension scheduled tasks (endpoint-based)

- Plan slug: `extension-scheduled-tasks`
- Created: `2026-01-01`

## What This Is

Keep a lightweight, continuously-updated log of discoveries and decisions made while implementing this plan.

Prefer short bullets. Append new entries as you learn things, and also *update earlier notes* when a decision changes or an open question is resolved.

## Decisions

- (2026-01-01) Schedules invoke *manifest-declared API endpoints* (method+path) using the existing Runner `/v1/execute` HTTP-shaped payload, rather than introducing a new “scheduled handler” ABI.
- (2026-01-01) Schedules reference endpoints by `endpoint_id` (normalized endpoint table) for stronger guarantees; extension version updates remap schedules by matching `(method,path)` and are blocked if remapping fails (unless explicitly overridden).
- (2026-01-01) No DB cascades (Citus constraints). All cleanup (uninstall/delete/update) is performed in application/business logic.
- (2026-01-01) Extension version updates use a remap-by-(method,path) step; if any schedule cannot be remapped, the update returns a 409 conflict (`SCHEDULE_REMAP_FAILED`) unless `disableMissingSchedules=true` is provided.
- (2026-01-01) Schedule CRUD and execution controls require `extension:read` / `extension:write` permissions (consistent with extension settings access).

## Discoveries / Constraints

- (2026-01-01) Gateway → Runner request today always uses `{ context, http, limits, providers?, secret_envelope?, user? }` (`server/src/app/api/ext/[extensionId]/[[...path]]/route.ts`).
- (2026-01-01) EE install config is available via `getInstallConfig` / `getInstallConfigByInstallId` (`ee/server/src/lib/extensions/installConfig.ts`).
- (2026-01-01) Job runner abstraction supports cron recurrence in both backends:
  - Temporal schedules in EE (`ee/server/src/lib/jobs/runners/TemporalJobRunner.ts`)
  - PG Boss schedules in CE (`server/src/lib/jobs/runners/PgBossJobRunner.ts`)
- (2026-01-01) Registry v2 currently stores endpoints in `extension_version.api_endpoints` (JSON) and has an older facade reading `extension_version.api`; we should standardize endpoint storage to avoid drift.
- (2026-01-01) Temporal schedule creation now passes `timezoneName` (when available) from schedule metadata; PG Boss ignores timezone.
- (2026-01-01) v1 cron validation is restricted to 5-field crons and blocks overly-frequent (every-minute) schedules; schedulable endpoints exclude path params and restrict to GET/POST.
- (2026-01-01) Citus: `tenant_extension_schedule` is distributed by `tenant_id`; `extension_api_endpoint` must be a Citus reference table to support distributed joins in schedule list queries.

## Commands / Runbooks

- Validate plan artifacts: `python3 /Users/roberisaacs/.codex/skills/alga-plan/scripts/validate_plan.py ee/docs/plans/2026-01-01-extension-scheduled-tasks`
- Run Vitest schedules integration tests: `cd ee/server && npx vitest run src/__tests__/integration/extension-schedules.actions.integration.test.ts`
- Run Playwright schedules UI test: `cd ee/server && PW_REUSE=false npx playwright test src/__tests__/integration/extension-schedules.playwright.test.ts --project=chromium --reporter=list`

## Links / References

- Extension settings UI: `ee/server/src/components/settings/extensions/ExtensionSettings.tsx`
- Gateway Runner invoke contract: `server/src/app/api/ext/[extensionId]/[[...path]]/route.ts`
- EE install config lookup: `ee/server/src/lib/extensions/installConfig.ts`
- Job runner abstraction: `server/src/lib/jobs/interfaces/IJobRunner.ts`
- Schedule actions: `ee/server/src/lib/actions/extensionScheduleActions.ts`
- Extension update API: `ee/server/src/app/api/v1/extensions/update/route.ts`

## Tests / Implementation Notes

- (2026-01-01) Added Vitest integration coverage for endpoint materialization + schedule CRUD + run-now + rate limiting:
  - `ee/server/src/__tests__/integration/extension-schedules.actions.integration.test.ts`
- (2026-01-01) Fixed schedule action validation errors to return `{ success:false, fieldErrors }` instead of throwing (cron/timezone/uuid validation).
- (2026-01-01) Fixed endpoint materialization to de-dupe within a batch by `(method,path)` to avoid Postgres `ON CONFLICT DO UPDATE command cannot affect row a second time`.
- (2026-01-01) Updated `ee/server/vitest.config.ts` aliases so Vitest can resolve mixed EE + CE path patterns used by the extension subsystem.
- (2026-01-01) Fixed `extRegistryV2Actions.ts` to only export async functions (Next.js server action restriction) by making helper types non-exported.
- (2026-01-01) Added Vitest integration coverage for scheduled invocation handler behavior (payload shaping, errors, timeout, no-overlap, endpoint-missing disable policy):
  - `ee/server/src/__tests__/integration/extension-scheduled-invocation.handler.integration.test.ts`
- (2026-01-01) Adjusted scheduled invocation handler to:
  - Use transaction-scoped advisory locks to enforce no-overlap without pooled-connection reentrancy issues.
  - Persist `last_run_*` fields even when execution fails (avoid transaction rollback losing the update).
  - Disable schedules when `endpoint_id` is broken/missing (policy).
- (2026-01-01) Added Vitest integration coverage for extension v2 update/remap behavior (block vs override + disable only missing + recreate runner schedules when handles missing):
  - `ee/server/src/__tests__/integration/extension-schedule-remap.integration.test.ts`
- (2026-01-01) Tightened schedule input validation to match policy and improve UX:
  - Reject cron when both DOM + DOW are set.
  - Require payload to be JSON object/array and enforce size limit.
  - Validate schedule name length and surface unique-name violations as field errors.
  - Reject schedule creation when extension install is disabled.
- (2026-01-01) Added unit coverage for Temporal runner schedule creation semantics (singletonKey => scheduleId, timezoneName):
  - `ee/server/src/__tests__/unit/temporalJobRunner.scheduleRecurringJob.test.ts`
- (2026-01-01) Added integration coverage for uninstall/toggle cleanup behavior (cancel jobs + delete schedules, pause/resume on extension enable/disable):
  - `ee/server/src/__tests__/integration/extension-schedule-cleanup.integration.test.ts`
- (2026-01-01) Added runner response size guardrail via `EXT_RUNNER_MAX_RESPONSE_BYTES` (default `262144`) and integration test coverage:
  - `server/src/lib/jobs/handlers/extensionScheduledInvocationHandler.ts`
  - `ee/server/src/__tests__/integration/extension-scheduled-invocation.handler.integration.test.ts`
- (2026-01-01) Expanded schedule actions integration coverage to include stable endpoint IDs/handler field and run-now disabled policy:
  - `ee/server/src/__tests__/integration/extension-schedules.actions.integration.test.ts`
- (2026-01-01) Stabilized Playwright schedule toggle assertions by polling DB state instead of fixed sleeps:
  - `ee/server/src/__tests__/integration/extension-schedules.playwright.test.ts`
- (2026-01-01) Added strict assertion that scheduled invocation does not inject extra headers into runner `http.headers` payload:
  - `ee/server/src/__tests__/integration/extension-scheduled-invocation.handler.integration.test.ts`
- (2026-01-01) Made schedule create/update/delete transactional with runner scheduling/cancellation (atomic failure semantics):
  - `ee/server/src/lib/actions/extensionScheduleActions.ts`
  - `ee/server/src/__tests__/integration/extension-schedules.actions.integration.test.ts`
- (2026-01-01) Defaulted schedule timezone input to current user's timezone (fallback UTC) and added Playwright coverage:
  - `ee/server/src/lib/actions/extensionScheduleActions.ts`
  - `ee/server/src/components/settings/extensions/ExtensionSettings.tsx`
  - `ee/server/src/__tests__/integration/extension-schedules.playwright.test.ts`

## Open Questions

- Tenant timezone source of truth (DB field? settings?).
- Policy on extension update when schedules can’t be remapped: block vs allow with forced disable.
  - Current v1 behavior: disallow selecting endpoints with path params; only allow static paths.