PSA/ee/docs/plans/2026-03-07-workflow-v2-time-based-clock-triggers/SCRATCHPAD.md

Scratchpad — Workflow V2 Time-Based Clock Triggers

• Plan slug: workflow-v2-time-based-clock-triggers
• Created: 2026-03-07

What This Is

Keep a lightweight, continuously-updated log of discoveries and decisions made while planning and implementing Workflow V2 pure clock triggers.

Decisions

• (2026-03-07) Scope starts with pure clock triggers only. Each fire starts one workflow run. No domain-record fan-out.
• (2026-03-07) Cron support is limited to 5-field cron. No seconds field and no 6-field cron syntax.
• (2026-03-07) This capability is EE-only.
• (2026-03-07) “No trigger” remains the no-trigger shape. Do not add an explicit manual trigger type in this scope.
• (2026-03-07) Preferred architecture is first-class time triggers, not synthetic event catalog entries.
• (2026-03-07) Preferred scheduling substrate is the job-runner abstraction (scheduleJobAt and scheduleRecurringJob), not the legacy JobScheduler.
• (2026-03-07) Time-triggered workflows should use a fixed synthetic payload contract and pinned payload schema mode in v1.
• (2026-03-07) Run creation should be unified behind one launcher service shared by event and time triggers.
• (2026-03-07) Canonical Workflow V2 trigger discriminants will be event, schedule, and recurring; one-time and recurring triggers stay first-class instead of overloading event names.
• (2026-03-07) Create/update action inputs should continue to accept trigger variants by delegating to workflowDefinitionSchema rather than duplicating a second trigger union.

Discoveries / Constraints

• (2026-03-07) The canonical Workflow V2 definition schema only supports trigger.type = 'event' today. Key file: shared/workflow/runtime/types.ts.
• (2026-03-07) The designer trigger UX is event-only and tightly coupled to event catalog lookups, source schema overrides, and trigger mapping. Key file: ee/server/src/components/workflow-designer/WorkflowDesigner.tsx.
• (2026-03-07) Publish validation is split between shared runtime validation and server-action validation. Trigger-specific logic currently assumes event triggers.
• (2026-03-07) Event-trigger run start logic already exists in more than one path and has behavioral drift. Adding a third bespoke path for time triggers would worsen consistency problems.
• (2026-03-07) Workflow V2 already has durable wait/retry timing inside runs, but not durable scheduled starts for workflow definitions.
• (2026-03-07) The extension scheduler is the strongest reusable scheduling implementation already in the repo and persists both internal job ids and external runner schedule ids.
• (2026-03-07) IJobRunner supports both one-time scheduled execution and recurring scheduled execution. This is the correct reuse seam for workflow time triggers.
• (2026-03-07) The legacy JobScheduler is not a safe base for real cron semantics because it coarsens cron-ish input to a delayed interval path.
• (2026-03-07) Current workflow list/filter code still contains trigger-type heuristics that infer “scheduled” from event-name strings. That should be removed once real trigger types exist.
• (2026-03-07) Existing job-runner handler signatures do not provide a per-occurrence recurring fire id. PgBoss cron schedules inject the stable registration jobServiceId into each delivery, and the runner calls handlers with that value instead of the transient PgBoss job id. Temporal recurring schedules likewise start each occurrence with the stable registration jobRecord.jobId. That means scheduleId + jobId is safe for one-time schedules but would incorrectly dedupe every recurring fire after the first one. Key files: server/src/lib/jobs/runners/PgBossJobRunner.ts, ee/server/src/lib/jobs/runners/TemporalJobRunner.ts, ee/temporal-workflows/src/workflows/generic-job-workflow.ts.
• (2026-03-07) Importing the broad server/src/lib/jobs barrel from workflow runtime code drags in unrelated handlers; for scheduling lifecycle code, the safer seam is server/src/lib/jobs/JobRunnerFactory so action/import paths do not depend on optional job-handler modules.
• (2026-03-07) Existing workflow_runs columns are sufficient for event provenance but not honest enough for time-trigger provenance. Added explicit trigger_type plus trigger_metadata_json so clock-triggered runs are not represented as fake event names.
• (2026-03-07) Direct trigger.eventName and trigger.sourcePayloadSchemaRef access already exists in shared bundling, runtime actions, and run-studio UI; widening the trigger union requires explicit event-trigger narrowing at those call sites.
• (2026-03-07) payload_schema_mode is persisted on the workflow definition record, not on publish input. That means publish must explicitly reject time-trigger definitions if an older draft is still marked inferred.
• (2026-03-07) Local Workflow V2 integration tests in this worktree could not use the usual DB-backed harness because PostgreSQL was unavailable on localhost:5438; a mock-backed unit suite was a better fit for publish-path validation coverage.
• (2026-03-07) The paged workflow list action still filtered scheduled workflows by checking trigger.eventName for schedule/cron substrings. Real trigger filtering needs to key off trigger.type.
• (2026-03-08) Workflow V2 server actions resolve auth/database through @alga-psa/auth and @alga-psa/db, not the older server/src/lib/db seam used by some legacy tests. The new DB-backed integration coverage had to mock those actual entrypoints to keep action writes on the test database.
• (2026-03-08) The EE schedule-state table stores job_id as a UUID, so DB-backed scheduling tests must return UUID-shaped mocked runner job ids even when the runner itself is stubbed.

Commands / Runbooks

• (2026-03-07) Inspect Workflow V2 trigger contract:
  • sed -n '260,325p' shared/workflow/runtime/types.ts
• (2026-03-07) Inspect Workflow Designer trigger UI:
  • rg -n "workflow-designer-trigger|Trigger event|payloadMapping|event catalog" ee/server/src/components/workflow-designer/WorkflowDesigner.tsx
  • sed -n '3460,3875p' ee/server/src/components/workflow-designer/WorkflowDesigner.tsx
• (2026-03-07) Inspect publish validation and event-trigger launch path:
  • rg -n "computeValidation|submitWorkflowEventAction|publishWorkflowDefinitionAction" packages/workflows/src/actions/workflow-runtime-v2-actions.ts
• (2026-03-07) Inspect scheduling substrate:
  • sed -n '36,140p' server/src/lib/jobs/interfaces/IJobRunner.ts
  • sed -n '400,590p' ee/server/src/lib/extensions/schedulerHostApi.ts
  • sed -n '260,420p' server/src/lib/jobs/runners/PgBossJobRunner.ts
• (2026-03-07) Validate initial schema slice:
  • cd server && pnpm vitest run src/test/unit/workflowTimeTriggerSchemas.unit.test.ts --config vitest.config.ts
  • pnpm exec eslint shared/workflow/runtime/types.ts shared/workflow/bundle/dependencySummaryV1.ts packages/workflows/src/actions/workflow-runtime-v2-actions.ts ee/server/src/components/workflow-run-studio/RunStudioShell.tsx server/src/test/unit/workflowTimeTriggerSchemas.unit.test.ts
• (2026-03-07) Validate time-trigger publish/contract slice:
  • cd server && pnpm vitest run src/test/unit/workflowTimeTriggerSchemas.unit.test.ts src/test/unit/workflowTimeTriggerPublishValidation.unit.test.ts --config vitest.config.ts
  • pnpm exec eslint shared/workflow/runtime/types.ts shared/workflow/runtime/init.ts shared/workflow/runtime/index.ts shared/workflow/runtime/schemas/workflowClockTriggerSchema.ts server/src/lib/features.ts packages/workflows/src/actions/workflow-runtime-v2-actions.ts server/src/test/unit/workflowTimeTriggerPublishValidation.unit.test.ts
• (2026-03-07) Validate workflow list trigger-type filtering:
  • cd server && pnpm vitest run src/test/unit/workflowDefinitionListTriggerFilters.unit.test.ts --config vitest.config.ts
  • pnpm exec eslint packages/workflows/src/actions/workflow-runtime-v2-schemas.ts packages/workflows/src/actions/workflow-runtime-v2-actions.ts packages/workflows/src/components/automation-hub/WorkflowList.tsx server/src/test/unit/workflowDefinitionListTriggerFilters.unit.test.ts
• (2026-03-07) Validate Workflow Designer time-trigger UI:
  • pnpm exec eslint ee/server/src/components/workflow-designer/WorkflowDesigner.tsx ee/server/src/__tests__/page-objects/WorkflowDesignerPage.ts ee/server/src/__tests__/integration/workflow-designer-time-triggers.playwright.test.ts
  • cd ee/server && npm run typecheck
  • cd ee/server && npx playwright test -c playwright.config.ts src/__tests__/integration/workflow-designer-time-triggers.playwright.test.ts --headed
• (2026-03-07) Validate scheduling lifecycle and launcher wiring:
  • cd server && pnpm vitest run src/test/unit/workflowTimeTriggerSchedulingLifecycle.unit.test.ts src/test/unit/workflowScheduledRunHandlers.unit.test.ts src/test/unit/workflowEventLauncherRouting.unit.test.ts --config vitest.config.ts
  • cd ee/server && npm run typecheck
• (2026-03-07) Attempt event-trigger regression validation after launcher extraction:
  • cd server && pnpm vitest run src/test/integration/workflowRuntimeV2.eventTrigger.integration.test.ts --coverage.enabled=false --config vitest.config.ts
• (2026-03-07) Validate run provenance persistence:
  • cd server && pnpm vitest run src/test/unit/workflowRunTriggerProvenance.unit.test.ts src/test/unit/workflowScheduledRunHandlers.unit.test.ts src/test/unit/workflowEventLauncherRouting.unit.test.ts src/test/unit/workflowTimeTriggerSchedulingLifecycle.unit.test.ts --coverage.enabled=false --config vitest.config.ts
  • cd ee/server && npm run typecheck
• (2026-03-07) Validate run provenance, dedupe, and UI trigger-label helpers after recurring-fire-key fix:
  • cd server && pnpm vitest run src/test/unit/workflowScheduledRunHandlers.unit.test.ts src/test/unit/workflowRunLauncher.unit.test.ts src/test/unit/workflowRunTriggerProvenance.unit.test.ts src/test/unit/workflowEventLauncherRouting.unit.test.ts src/test/unit/workflowTimeTriggerSchedulingLifecycle.unit.test.ts --coverage.enabled=false --config vitest.config.ts
  • cd ee/server && pnpm vitest run src/__tests__/unit/workflowRunTriggerPresentation.unit.test.ts
  • cd ee/server && npm run typecheck
  • cd ee/temporal-workflows && npm run type-check
• (2026-03-08) Validate DB-backed schedule registration and publish/event regressions against the local GreenMail PostgreSQL instance:
  • cd server && DB_HOST=localhost DB_PORT=55433 DB_PASSWORD_ADMIN=postpass123 DB_PASSWORD_SERVER=postpass123 DB_USER_ADMIN=postgres DB_USER_SERVER=app_user pnpm vitest run src/test/integration/workflowTimeTriggerScheduling.integration.test.ts --coverage.enabled=false --config vitest.config.ts
  • cd server && DB_HOST=localhost DB_PORT=55433 DB_PASSWORD_ADMIN=postpass123 DB_PASSWORD_SERVER=postpass123 DB_USER_ADMIN=postgres DB_USER_SERVER=app_user pnpm vitest run src/test/integration/workflowTimeTriggerRegression.integration.test.ts --coverage.enabled=false --config vitest.config.ts

Progress Log

• (2026-03-07) Completed F001/F002 and T001-T005.
  • Added workflowTriggerSchema as a discriminated union in shared/workflow/runtime/types.ts with event, schedule, and recurring variants plus reusable type guards.
  • Kept no-trigger behavior unchanged by leaving trigger optional on workflowDefinitionSchema.
  • Confirmed create/update action inputs accept time-trigger variants via the shared definition schema instead of separate action-only trigger parsing.
  • Added server/src/test/unit/workflowTimeTriggerSchemas.unit.test.ts covering shared schema acceptance, no-trigger preservation, and create/update input parsing.
  • Narrowed existing event-only call sites in dependency summary extraction, workflow runtime actions, and run-studio trigger display so the widened trigger union stays type-safe.
• (2026-03-07) Completed F003-F007 and T006-T015.
  • Added the fixed clock payload contract schema/registry entry at payload.WorkflowClockTrigger.v1.
  • Time-trigger draft saves now normalize onto the fixed clock payload contract and reject CE create/update attempts at action time.
  • Publish now rejects CE time-trigger workflows and rejects any time-trigger publish attempt that still uses inferred payload schema mode.
  • Added publish-time validation for one-time schedules (runAt required, valid ISO timestamp, future-only) and recurring schedules (valid 5-field cron, valid IANA timezone).
  • Added server/src/test/unit/workflowTimeTriggerPublishValidation.unit.test.ts to cover EE gating, fixed schema resolution, inferred-mode rejection, and one-time/recurring validation behavior without depending on a local PostgreSQL harness.
• (2026-03-07) Completed F008 and T016-T017.
  • Replaced workflow-definition list filtering on trigger.eventName substring heuristics with direct trigger.type comparisons.
  • Preserved backward compatibility for legacy trigger=scheduled URLs by mapping that filter to both schedule and recurring trigger types.
  • Updated the workflow list UI to label and iconize event, schedule, recurring, and manual directly from persisted trigger types.
  • Added server/src/test/unit/workflowDefinitionListTriggerFilters.unit.test.ts to verify one-time and recurring filters hit the real trigger.type query path and return the corresponding trigger types intact.
• (2026-03-07) Completed F009-F013 and T018-T021.
  • Replaced the event-only trigger control in WorkflowDesigner.tsx with an explicit trigger-type selector that switches among no trigger, event, one-time schedule, and recurring schedule.
  • Added one-time schedule editing via a future datetime-local input and recurring schedule editing via a cron input plus searchable timezone selector with 5-field guidance.
  • Time-trigger selection now hides event-only catalog/mapping controls, forces the fixed clock contract into pinned mode, and disables schema overrides while a time trigger is active.
  • Added an inline clock-contract preview card that surfaces payload.WorkflowClockTrigger.v1 and its fixed payload fields directly in the trigger section.
  • Added ee/server/src/__tests__/integration/workflow-designer-time-triggers.playwright.test.ts plus page-object helpers for the new controls.
  • npm run typecheck passed in ee/server.
  • The targeted Playwright run could not complete in this environment because the EE Playwright web-server bootstrap never brought http://localhost:3300 up; the worker stalled before any browser steps ran.
• (2026-03-07) Completed F014-F023 and T008/T025-T034.
  • Added the EE migration ee/server/migrations/20260307200000_create_workflow_schedule_tables.cjs plus shared/workflow/persistence/workflowScheduleStateModel.ts for durable workflow schedule registration state.
  • Added server/src/lib/workflow-runtime-v2/workflowScheduleLifecycle.ts to build desired schedule state, register one-time and recurring jobs through IJobRunner, compensate failed reschedules, and clean up registrations on pause/delete/trigger changes.
  • Added server/src/lib/workflow-runtime-v2/workflowRunLauncher.ts as the shared published-workflow launcher, then routed both submitWorkflowEventAction and WorkflowRuntimeV2EventStreamWorker through it.
  • Added server/src/lib/jobs/handlers/workflowScheduledRunHandlers.ts and registered EE-only one-time/recurring schedule handlers in server/src/lib/jobs/registerAllHandlers.ts.
  • Publishing, pausing, deleting, and re-publishing time-triggered workflows now synchronize schedule registration state from packages/workflows/src/actions/workflow-runtime-v2-actions.ts.
  • Narrowed workflow schedule lifecycle imports to server/src/lib/jobs/JobRunnerFactory so the new scheduler path does not pull the entire jobs barrel during action imports.
  • Added unit coverage in server/src/test/unit/workflowTimeTriggerSchedulingLifecycle.unit.test.ts, server/src/test/unit/workflowScheduledRunHandlers.unit.test.ts, and server/src/test/unit/workflowEventLauncherRouting.unit.test.ts for launcher wiring, fixed payload contract emission, schedule registration calls, pause/delete/change-away cleanup, and one-time/recurring reschedule replacement.
  • Left T022-T024 false because this checkpoint still lacks DB-backed integration coverage that exercises real tenant_workflow_schedule rows against a migrated test database; current coverage is action/handler-focused unit coverage.
  • Left T046 false because the targeted event-trigger integration suite could not run in this local environment: PostgreSQL was unavailable on 127.0.0.1:5438/::1:5438, so the suite skipped its tests during setup and failed before exercising the regression path.
• (2026-03-07) Completed F024 and T035/T037/T038.
  • One-time schedule handler success now marks tenant_workflow_schedule rows completed, clears runner handles, disables the schedule, and nulls next_fire_at.
  • Re-delivery after a successful one-time fire now short-circuits on the existing enabled/status guard, so later ticks do not launch another run.
  • Re-ran cd server && pnpm vitest run src/test/unit/workflowScheduledRunHandlers.unit.test.ts src/test/unit/workflowEventLauncherRouting.unit.test.ts src/test/unit/workflowTimeTriggerSchedulingLifecycle.unit.test.ts --coverage.enabled=false --config vitest.config.ts.
• (2026-03-07) Completed F025 and T039/T040.
  • Added server/migrations/20260308010000_add_workflow_run_trigger_provenance.cjs to store trigger_type and trigger_metadata_json on workflow_runs.
  • WorkflowRuntimeV2.startRun() now persists trigger provenance explicitly, and launchPublishedWorkflowRun() threads that metadata through for both event and time-triggered launches.
  • Time-trigger job handlers now pass the fixed clock payload through as trigger metadata, while event launches tag runs as trigger_type = 'event' with lightweight trigger metadata for parity.
  • listWorkflowRunsAction() now selects the new provenance fields so downstream UI can distinguish schedule and recurring runs without inferring from event_type.
  • Added server/src/test/unit/workflowRunTriggerProvenance.unit.test.ts and re-ran the unit provenance/lifecycle suite plus cd ee/server && npm run typecheck.
• (2026-03-07) Completed F026/F027 and T036/T041-T044.
  • Added shared trigger/schedule presentation helpers at ee/server/src/components/workflow-designer/workflowRunTriggerPresentation.ts and wired workflow run list/details plus Run Studio to show one-time/recurring labels and current schedule state from getWorkflowScheduleStateAction().
  • Added server/migrations/20260308013000_add_workflow_run_trigger_fire_key.cjs plus launcher-level duplicate handling keyed by workflow_runs.trigger_fire_key.
  • Corrected the recurring dedupe design after discovering runner jobId is the stable registration id, not a per-occurrence id. PgBoss now injects jobExecutionId = job.id and Temporal now injects jobExecutionId = workflowInfo().workflowId; schedule fire keys now use that runner-supplied execution id so later recurring occurrences still launch while retries of the same occurrence remain idempotent.
  • One-time schedule handlers now store last_fire_key and complete/disable the schedule after a successful fire; recurring handlers store last_fire_key per occurrence while leaving the schedule active.
  • Added/updated unit coverage in server/src/test/unit/workflowScheduledRunHandlers.unit.test.ts, server/src/test/unit/workflowRunLauncher.unit.test.ts, and ee/server/src/__tests__/unit/workflowRunTriggerPresentation.unit.test.ts.
• (2026-03-08) Completed T022-T024 and T045-T046.
  • Added ensureWorkflowScheduleStateTable() to server/src/test/helpers/workflowRuntimeV2TestUtils.ts and made table resets include tenant_workflow_schedule when present so DB-backed Workflow V2 suites can exercise the EE schedule lifecycle safely.
  • Added server/src/test/integration/workflowTimeTriggerScheduling.integration.test.ts covering one-time schedule row creation, recurring schedule row creation, and persisted runner identifiers through the real publish action with a real PostgreSQL test database and mocked job runner.
  • Added server/src/test/integration/workflowTimeTriggerRegression.integration.test.ts covering no-trigger publish/start regression and event-trigger publish/start regression through the shared launcher path with persisted run provenance assertions.
  • Verified the new DB-backed coverage against the local greenmail_imap_postgres container exposed on localhost:55433.

Links / References

• Workflow definition schema: shared/workflow/runtime/types.ts
• Workflow publish/run actions: packages/workflows/src/actions/workflow-runtime-v2-actions.ts
• Workflow action input schemas: packages/workflows/src/actions/workflow-runtime-v2-schemas.ts
• Workflow definition persistence: shared/workflow/persistence/workflowDefinitionModelV2.ts
• Workflow run worker: shared/workflow/workers/WorkflowRuntimeV2Worker.ts
• Workflow event-stream worker: services/workflow-worker/src/v2/WorkflowRuntimeV2EventStreamWorker.ts
• Workflow designer: ee/server/src/components/workflow-designer/WorkflowDesigner.tsx
• Job runner interface: server/src/lib/jobs/interfaces/IJobRunner.ts
• PG Boss runner: server/src/lib/jobs/runners/PgBossJobRunner.ts
• EE Temporal runner: ee/server/src/lib/jobs/runners/TemporalJobRunner.ts
• EE extension scheduler API: ee/server/src/lib/extensions/schedulerHostApi.ts
• Extension schedule handler: server/src/lib/jobs/handlers/extensionScheduledInvocationHandler.ts
• Related existing schedule table migration: ee/server/migrations/20260101120000_create_extension_schedule_tables.cjs
• New DB-backed schedule tests: server/src/test/integration/workflowTimeTriggerScheduling.integration.test.ts
• New launcher regression tests: server/src/test/integration/workflowTimeTriggerRegression.integration.test.ts

Open Questions

• Should completed one-time schedules remain as durable rows forever or be archived/cleaned up later?
• Should the first version expose next-fire previews in the designer, or leave that to a follow-up?
• Should workflow run provenance for time triggers use new explicit columns, or be represented through structured run metadata layered on top of current provenance fields?
• (2026-03-07) What stable per-occurrence key should recurring schedule fires use across retries and across both PgBoss and Temporal runners? Current runner inputs expose schedule registration ids but not an occurrence id.