PSA/ee/docs/planning/adhoc/2026-01-26-202106-0-prereqs-do-this-once-per-environment/SCRATCHPAD.md

Scratchpad

Status

• Converted all scaffolded workflow-harness fixtures into business-valid, notification-based fixtures with deterministic DB assertions and cleanup.

Notes / Decisions

• Harness “channels” confirmed:
  • Session+tenant context: Cookie + x-tenant-id injected in tools/workflow-harness/lib/http.cjs (createHttpClient, lines ~22–36).
  • Optional REST API auth: auto-injects x-api-key from WORKFLOW_HARNESS_API_KEY / ALGA_API_KEY if not already set (tools/workflow-harness/lib/http.cjs, lines ~32–36).
  • DB assertions + cleanup: ctx.db read-only guard and ctx.dbWrite write-enabled client (tools/workflow-harness/lib/db.cjs, lines ~5–48; wired in tools/workflow-harness/run.cjs, lines ~126–190).
• Failure artifacts confirmed:
  • Root: <artifactsDir>/workflow-harness/<fixture>/<timestamp>[-<runId>]/... (tools/workflow-harness/lib/artifacts.cjs, lines ~15–37).
  • Failure payloads written in tools/workflow-harness/run.cjs catch block (starts ~262), including failure.context.json and failure.error.txt.
• Inventory results:
  • Found 139 scaffolded fixtures (bundle description contains “Scaffolded catalog fixture…” AND test.cjs uses _lib/scaffolded-fixture.cjs).
  • Scaffolded fixtures currently hardcode payload.TicketCreated.v1 regardless of event; conversion must fix schema refs first.
  • Unique event types across scaffolded fixtures include several not present in runtime schema registry today (need new payload.*.v1 refs + schemas):
    • APPOINTMENT_REQUEST_* (CREATED/APPROVED/DECLINED/CANCELLED)
    • SCHEDULE_ENTRY_* (CREATED/UPDATED/DELETED)
    • PROJECT_ASSIGNED, PROJECT_CLOSED
    • TIME_ENTRY_APPROVED, TIME_ENTRY_SUBMITTED
    • TASK_COMMENT_ADDED, TASK_COMMENT_UPDATED
    • TICKET_COMMENT_ADDED, TICKET_ADDITIONAL_AGENT_ASSIGNED
    • PROJECT_TASK_ADDITIONAL_AGENT_ASSIGNED
  • Note: /api/workflow/events ingestion auto-injects tenantId + occurredAt via buildWorkflowPayload(...) before schema validation (server/src/lib/actions/workflow-runtime-v2-actions.ts, around submitWorkflowEventAction), so tests can omit those fields.
• Conversion approach (scale decision):
  • Implemented a generic notification-based fixture template using notifications.send_in_app as the persisted side effect.
  • Standardized fixture-only payload fields:
    • payload.fixtureNotifyUserId (recipient user id)
    • payload.fixtureDedupeKey (deterministic marker/correlation + action idempotency)
    • payload.fixtureBadUserId (try/catch fixtures only)
    • payload.fixtureVariant (multi-branch fixtures only)
  • Control-flow patterns applied by fixture name:
    • default/idempotent: control.if
    • foreach*: control.forEach
    • trycatch*: control.tryCatch
    • multi-branch*: nested control.if
    • callworkflow*/subworkflow*: control.callWorkflow + child workflow, patched/published inside test.cjs
  • Assertion target: internal_notifications rows containing [fixture <name>] and the fixtureDedupeKey.
• Added runtime schema refs for legacy event types needed by the converted fixtures:
  • Scheduling legacy: payload.ScheduleEntry*, payload.AppointmentRequest*
  • Projects legacy: payload.ProjectAssigned, payload.ProjectClosed, payload.ProjectTaskAdditionalAgentAssigned, payload.TaskComment*
  • Tickets legacy: payload.TicketCommentAdded, payload.TicketAdditionalAgentAssigned
  • Time legacy: payload.TimeEntrySubmitted, payload.TimeEntryApproved

Commands / Runbook

• Find scaffolded fixtures:
  • rg -l "_lib/scaffolded-fixture" ee/test-data/workflow-harness/*/test.cjs | xargs -n1 dirname | sed 's|^ee/test-data/workflow-harness/||' | sort
  • rg -l "Scaffolded catalog fixture" ee/test-data/workflow-harness/*/bundle.json | xargs -n1 dirname | sed 's|^ee/test-data/workflow-harness/||' | sort
  • Both produced 139 identical fixture ids.
• Summarize scaffolded trigger event types:
  • cat /tmp/scaffolded-by-bundle.txt | while read -r f; do jq -r '.workflows[0].metadata.trigger.eventName' "ee/test-data/workflow-harness/$f/bundle.json"; done | sort | uniq -c | sort -nr
• Convert all scaffolded fixtures (one-time):
  • node tools/workflow-harness/convert-scaffolded-fixtures.cjs
• Quick sanity checks:
  • rg "_lib/scaffolded-fixture" ee/test-data/workflow-harness -S (expect none)
  • rg "Scaffolded catalog fixture" ee/test-data/workflow-harness -S (expect none)
  • node --test tools/workflow-harness/tests/runner-stubbed.test.cjs

Gotchas

• transform.assign evaluation order gotcha: don’t build a string from vars.marker inside the same assign map unless split into multiple steps (marker can be omitted).
• Zod validation in submitWorkflowEventAction checks success but does not replace payload with validation.data, so unknown payload keys remain available to workflows (useful for fixture-only fields like payload.fixtureNotifyUserId).
• notifications.send_in_app is idempotent; forEach fixtures must vary dedupe_key per iteration or inserts collapse to 1.