PSA/ee/docs/plans/2026-03-08-workflow-v1-hard-removal-design.md

# Workflow V1 Hard Removal Design

- Date: `2026-03-08`
- Status: Approved

## Summary

Alga PSA currently ships two workflow systems:

- workflow v1: AssemblyScript/code-editor driven, bootstrapped from `shared/workflow/core` and `shared/workflow/init`
- workflow v2: data-driven workflow designer/runtime under `shared/workflow/runtime` and `packages/workflows/src/actions/workflow-runtime-v2-actions.ts`

This change hard-removes workflow v1 from product surfaces, server bootstraps, actions, and database schema. No legacy workflows will be migrated. Templates remain a product concept, but the existing template library is v1-only and is removed as part of this cut. A future v2-native template system will be designed separately.

## Goals

- Make the application workflow-v2-only.
- Remove workflow v1 editor, template library, runtime actions, and runtime/bootstrap wiring.
- Drop workflow v1 database tables and seeded/system records.
- Keep workflow v2 workflow editor, runs, schedules, events, and event catalog working.

## Non-goals

- Migrating existing v1 workflows to v2.
- Delivering a v2-native template library in this change.
- Preserving legacy v1 APIs for compatibility.

## Recommended Approach

Use a hard cut, not a compatibility shim.

Why:

- The current template library and legacy editor are actively misleading because they only operate on the retired AssemblyScript model.
- Leaving v1 bootstraps or dead tables behind guarantees future regressions and increases maintenance cost.
- Workflow v2 already has the live product surface; this is primarily a removal and cleanup effort.

Rejected alternatives:

- Soft-disable v1 in the UI but keep bootstraps/tables: lower immediate risk, but leaves dead architecture in place.
- Remove only bootstraps and keep old code in-tree: still leaves stale routes, action exports, and schema detritus.

## Scope

### Code and Product Surface

Remove:

- legacy workflow runtime from `shared/workflow/core/*`
- legacy workflow initialization/registration from `shared/workflow/init/*`
- v1 workflow editor actions and runtime actions
- v1 template library actions and UI
- v1 workflow editor components and related dialogs/modals
- remaining references to the old template library tab in workflow control

Keep:

- workflow v2 designer/editor
- workflow v2 run history and run details
- workflow v2 schedules
- workflow v2 events/event catalog/dead-letter views

### Database Cleanup

Drop the workflow v1 persistence footprint, including:

- `workflow_template_categories`
- `workflow_templates`
- `workflow_registrations`
- `workflow_registration_versions`
- `system_workflow_registrations`
- `system_workflow_registration_versions`
- `workflow_executions`
- `workflow_events`
- `workflow_event_processing`
- `workflow_snapshots`

Also remove legacy seeded data and system workflow records that exist only for workflow v1.

## Implementation Slices

### 1. Surface cleanup

- Remove `Template Library` from workflow control.
- Remove legacy workflow editor components and template-library UI.
- Delete or repoint routes and links that still reach v1-only flows.

### 2. Action and model cleanup

- Remove v1 actions from `packages/workflows/src/actions/index.ts`.
- Delete v1 action modules that only operate on legacy tables/runtime.
- Remove models/helpers that only serve legacy registration/version tables.

### 3. Runtime/bootstrap cleanup

- Remove `getWorkflowRuntime()` and the shared singleton runtime.
- Remove legacy workflow initialization from server/shared startup.
- Delete v1 persistence models and event-sourcing helpers under `shared/workflow/persistence`.

### 4. Database cleanup

- Add destructive migration(s) to delete legacy data and drop v1 tables.
- Update tenant export/deletion/distribution code that still references dropped tables.

## Data Flow After This Change

- Authoring uses workflow v2 definitions only.
- Manual runs, event-driven runs, and schedules all launch via workflow v2 actions/runtime.
- The control panel exposes only workflow-v2 operations.
- No server bootstrap path initializes or processes workflow v1 definitions/events.

## Risks

- Some non-obvious consumers still query v1 tables directly, especially inbox/activity/integration code.
- Schema drops may break tenant export/deletion or citus distribution helpers if not updated in the same pass.
- Old tests that still import `getWorkflowRuntime()` or v1 actions will fail until removed or rewritten.

## Mitigations

- Remove surface area first so stale UI is gone before backend cleanup.
- Audit all `getWorkflowRuntime()` and legacy action imports before deleting core runtime files.
- Run focused typecheck/tests after each slice and boot the local app before applying DB drops.

## Acceptance Criteria

- No menu/tab/route in the app exposes workflow v1 editor or template library.
- No code in the app bootstraps or calls workflow v1 runtime.
- No exports remain for v1 workflow actions.
- Legacy v1 workflow tables are dropped by migration and no active code references them.
- `/msp/workflow-editor` and `/msp/workflow-control` remain operational for workflow v2.