PSA/ee/docs/plans/2026-03-13-workflow-ee-ownership-cutover/PRD.md

PRD — Workflow EE Ownership Cutover

• Slug: workflow-ee-ownership-cutover
• Date: 2026-03-13
• Status: Draft

Summary

Move workflow implementation ownership out of the global shared/workflow/* tree and into the EE workflows package at @alga-psa/workflows/*. This is a hard-cut refactor, not a shimmed migration: application code, worker code, EE server code, tests, and dependent packages should stop importing @shared/workflow* and @alga-psa/shared/workflow* and instead consume the EE package surface.

The cutover includes runtime, workers, persistence models, bundle helpers, streams and domain-event builders, workflow-specific secrets and services, expression-authoring helpers, types, and the new AI workflow step support. The goal is to align code ownership with product ownership so workflow is clearly EE-only and no longer leaks across the shared/core boundary.

Problem

Workflow is an EE feature, but the codebase still treats workflow as globally shared infrastructure. That has created two classes of problems:

1. Ownership confusion

• Engineers cannot tell whether workflow code is meant to be CE-safe or EE-only.
• Shared modules now contain EE-specific behavior, such as AI workflow registration.
• Product boundaries and package boundaries disagree, which makes architectural review and future refactors harder.

2. Concrete technical regressions

• EE-only dependencies can leak into shared runtime code.
• Workers, server actions, UI, and unrelated packages all import workflow from mixed namespaces.
• Workflow event-builder helpers and persistence surfaces are treated as globally shared, even though they are part of the workflow feature area.

The AI step work surfaced the problem sharply: shared workflow runtime code started importing EE AI services directly. That is a symptom of the larger issue, not an isolated mistake.

Goals

• Make @alga-psa/workflows/* the canonical import surface for workflow-owned code.
• Remove workflow implementation ownership from shared/workflow/*.
• Eliminate non-doc imports of @shared/workflow* and @alga-psa/shared/workflow* from application code and tests.
• Keep workflow behavior unchanged while moving ownership.
• Move AI-specific workflow behavior fully under the EE workflows package so shared/core no longer knows about it.
• Update dependent packages that use workflow-owned domain-event helpers to import them from the EE workflows package.
• Keep the worker, workflow runtime, designer, bundle import/export, task inbox, and workflow streams functioning after the cutover.

Non-goals

• Redesigning Workflow V2 behavior, schemas, node semantics, or persistence contracts.
• Introducing compatibility shims or a phased dual-namespace migration.
• Splitting workflow stream and event-builder helpers into a separate non-workflow package in this change.
• Redesigning workflow event publishing or domain event shapes.
• Changing workflow permissions, rollout strategy, feature flags, or observability platforms.
• Refactoring unrelated package boundaries outside the imports required for this workflow ownership cutover.

Users and Primary Flows

1. Workflow runtime owner updates imports

• Engineer works on runtime, worker, or workflow server code.
• Engineer imports workflow APIs from @alga-psa/workflows/*.
• Engineer no longer needs to reason about whether a workflow change is allowed under shared/core.

2. Dependent package emits workflow-owned domain events

• A package such as billing, scheduling, clients, documents, or notifications imports a workflow-owned event builder.
• The package imports the helper from @alga-psa/workflows/streams/....
• Event payload behavior remains unchanged.

3. Workflow worker and server continue to operate

• Worker boots through the EE workflows runtime entrypoints.
• EE workflow server actions validate, publish, and execute definitions using the EE package surface.
• Bundle import/export and task inbox behavior continue to work without behavioral changes.

4. AI workflow step remains intact after the ownership move

• Workflow designer and runtime continue to expose AI-specific behavior through the EE workflows package.
• Shared/core surfaces no longer reference AI-specific workflow logic.

UX / UI Notes

• There is no intended end-user UX change from this refactor.
• Workflow designer behavior, grouped palette behavior, AI step authoring, expression authoring, schema preview, and downstream reference browsing should all remain behaviorally unchanged.
• Any UI changes are limited to import-path and module-ownership rewiring behind existing interfaces.

Requirements

Functional Requirements

• @alga-psa/workflows/* must become the canonical module path for workflow-owned code.
• The EE workflows package must expose the workflow surfaces currently used by callers, including:
  • runtime APIs
  • client/types surfaces
  • workers
  • persistence models and interfaces
  • bundle helpers and types
  • streams and domain-event builders
  • expression-authoring helpers
  • workflow-specific secrets and services
• Workflow runtime bootstrap must execute through the EE workflows package.
• Workflow worker entrypoints must import workflow runtime and workers from the EE workflows package.
• EE workflow server actions must import workflow runtime, validation, persistence, bundle, and catalog helpers from the EE workflows package.
• Workflow designer and related EE UI code must import workflow client, catalog, expression, and AI helpers from the EE workflows package.
• AI workflow step support must live entirely under the EE workflows package, including:
  • AI schema helpers
  • AI action registration
  • AI-aware output-schema resolution
  • AI-aware publish validation
• Shared/core workflow runtime files must no longer import EE-only AI services.
• Non-workflow packages that depend on workflow-owned stream or domain-event helpers must import them from the EE workflows package after the cutover.
• Server code outside the EE package that still invokes workflow-owned runtime or persistence helpers must import them from the EE workflows package.
• Package manifests, TypeScript path aliases, and build/export configuration must support the new canonical workflow namespace.
• The hard cut must remove non-doc imports of @shared/workflow* and @alga-psa/shared/workflow* from repo code and tests.

Behavioral Compatibility Requirements

• Workflow runtime execution semantics must not change.
• Workflow bundle import/export behavior must not change.
• Workflow worker startup, event ingestion, and run processing behavior must not change.
• Workflow designer behavior and data-contract expectations must not change.
• Workflow task inbox and persistence behavior must not change.
• Workflow event-builder helper signatures and payload output must not change.
• AI workflow step behavior must not change beyond moving ownership into the EE package.

Data / API / Integrations

• Canonical package surface:
  • @alga-psa/workflows
  • @alga-psa/workflows/runtime/*
  • @alga-psa/workflows/workers/*
  • @alga-psa/workflows/persistence/*
  • @alga-psa/workflows/bundle/*
  • @alga-psa/workflows/streams/*
  • @alga-psa/workflows/expression-authoring/*
  • @alga-psa/workflows/secrets/*
  • @alga-psa/workflows/services/*
  • @alga-psa/workflows/types/*
• Build/export updates must happen in the EE workflows package so these deep imports resolve for server, worker, and package callers.
• TypeScript path alias updates must cover the root tsconfig plus server, EE server, and workflow worker tsconfigs.
• Workflow-owned code currently under shared/workflow/* becomes EE package code.

Security / Permissions

• No permission model changes are intended.
• Existing workflow read/write/publish/execute permissions remain unchanged.
• This refactor changes ownership and packaging only; it should not broaden access to workflow capabilities.

Rollout / Migration

• This is a single hard-cut migration within the branch.
• No compatibility shims should be left behind for old workflow import paths in application code.
• The package/build changes must land in the same change as the import rewrites so the repo builds consistently.
• Docs can be updated opportunistically, but code and test surfaces must be fully cut over in the same implementation effort.

Risks

• The import graph is wide: runtime, worker, EE server, regular server code, tests, and many packages use workflow-owned helpers.
• The EE workflows package currently exports only a narrow surface, so export-map and build config changes are required before the import rewrite will compile.
• Some current consumers of workflow-owned streams and domain-event helpers are not obviously “workflow features,” so the cutover will introduce explicit dependencies on the EE workflows package there.
• Wiring tests that assert import strings will fail until updated.
• The worker and server bootstrap paths are sensitive to runtime initialization order; the ownership move must preserve initialization behavior exactly.

Open Questions

• None for this cutover. The plan assumes workflow and workflow-owned helper surfaces are EE-only and should move together.

Acceptance Criteria (Definition of Done)

• All workflow-owned code is canonically consumed through @alga-psa/workflows/*.
• No non-doc imports remain from @shared/workflow* or @alga-psa/shared/workflow*.
• The EE workflows package exports the workflow surfaces currently needed by runtime, worker, server, UI, and dependent packages.
• Workflow worker, workflow runtime, workflow designer, bundle import/export, task inbox, and workflow stream/event publishing behavior continue to work.
• AI workflow step behavior remains intact and is owned entirely by the EE workflows package.
• The codebase no longer places workflow implementation ownership under the global shared namespace.