@open-mercato/core 0.7.1-develop.7193.1.910a5b0a1e → 0.7.1-develop.7195.1.b5efd1d51a

package/src/modules/workflows/api/definitions/[id]/publish/route.ts

@@ -0,0 +1,250 @@
+/**
+ * Publish Workflow Definition Version
+ *
+ * POST /api/workflows/definitions/[id]/publish
+ *
+ * Mints a new frozen, published version of a workflow definition (snapshotting
+ * its current data + IO port contract). Runs breaking-change detection against
+ * callers of the workflow as a sub-workflow; when callers would break, the
+ * caller must pass `acknowledgeBreakingChanges: true`. Emits
+ * `workflows.definition.published`.
+ */
+
+import { randomUUID } from 'node:crypto'
+import { NextRequest, NextResponse } from 'next/server'
+import { z } from 'zod'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { resolveOrganizationScopeForRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
+import { validateCrudMutationGuard, runCrudMutationGuardAfterSuccess } from '@open-mercato/shared/lib/crud/mutation-guard'
+import { WorkflowDefinition } from '../../../../data/entities'
+import type { WorkflowIoContract } from '../../../../data/validators'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { serializeWorkflowDefinition } from '../../serialize'
+import { findSubWorkflowCallers } from '../../../../lib/caller-graph'
+import {
+  authorizeWorkflowGrantChange,
+  normalizeGrantedFeatures,
+  syncWorkflowDefinitionPrincipal,
+} from '../../../../lib/definition-grant'
+
+const logger = createLogger('workflows').child({ component: 'definition-publish-api' })
+
+export const metadata = {
+  requireAuth: true,
+  requireFeatures: ['workflows.definitions.publish'],
+}
+
+const publishInputSchema = z.object({
+  acknowledgeBreakingChanges: z.boolean().optional(),
+})
+
+interface RouteContext {
+  params: Promise<{ id: string }>
+}
+
+export async function POST(request: NextRequest, context: RouteContext) {
+  try {
+    const params = await context.params
+    const container = await createRequestContainer()
+    const em = container.resolve('em')
+    const auth = await getAuthFromRequest(request)
+
+    if (!auth) {
+      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+    }
+
+    const scope = await resolveOrganizationScopeForRequest({ container, auth, request })
+    const tenantId = auth.tenantId
+    const organizationId = scope?.selectedId ?? auth.orgId
+
+    if (!tenantId || !organizationId) {
+      return NextResponse.json({ error: 'Missing tenant or organization context' }, { status: 400 })
+    }
+
+    const body = await request.json().catch(() => ({}))
+    const parsed = publishInputSchema.safeParse(body)
+    if (!parsed.success) {
+      return NextResponse.json({ error: 'Validation failed', details: parsed.error.issues }, { status: 400 })
+    }
+
+    const guardResult = await validateCrudMutationGuard(container, {
+      tenantId,
+      organizationId,
+      userId: auth.sub ?? '',
+      resourceKind: 'workflows.definition',
+      resourceId: params.id,
+      operation: 'custom',
+      requestMethod: 'POST',
+      requestHeaders: request.headers,
+    })
+    if (guardResult && !guardResult.ok) {
+      return NextResponse.json(guardResult.body, { status: guardResult.status })
+    }
+
+    const source = await em.findOne(WorkflowDefinition, {
+      id: params.id,
+      tenantId,
+      organizationId,
+      deletedAt: null,
+    })
+    if (!source) {
+      return NextResponse.json({ error: 'Workflow definition not found' }, { status: 404 })
+    }
+
+    // Breaking-change detection: diff this definition's published port contract
+    // against every caller that invokes it as a sub-workflow.
+    const ports: WorkflowIoContract = (source.definition as { io?: WorkflowIoContract })?.io || {}
+    const breakingChanges = await findSubWorkflowCallers(em, {
+      subWorkflowId: source.workflowId,
+      tenantId,
+      organizationId,
+      ports,
+    })
+
+    if (breakingChanges.length > 0 && !parsed.data.acknowledgeBreakingChanges) {
+      return NextResponse.json(
+        {
+          error: 'Publishing would break existing sub-workflow mappings',
+          breakingChanges,
+        },
+        { status: 409 },
+      )
+    }
+
+    // Next version = max existing version for this workflowId/tenant + 1.
+    const latest = await em.findOne(
+      WorkflowDefinition,
+      { workflowId: source.workflowId, tenantId },
+      { orderBy: { version: 'DESC' } },
+    )
+    const nextVersion = (latest?.version ?? source.version) + 1
+
+    // The grant is per VERSION, so publishing mints a NEW execution principal
+    // from the source's grant — a new identity carrying those powers. It is
+    // therefore re-authorised against the PUBLISHER (`current: []` forces the
+    // check even though the feature list is unchanged): a user who may publish
+    // must not be able to bring a higher-privileged author's grant forward.
+    const grantedFeatures = normalizeGrantedFeatures(source.grantedFeatures)
+    const grantFailure = await authorizeWorkflowGrantChange(
+      container.resolve('rbacService') as Parameters<typeof authorizeWorkflowGrantChange>[0],
+      {
+        userId: auth.sub,
+        scope: { tenantId, organizationId },
+        requested: grantedFeatures,
+        current: [],
+      },
+    )
+    if (grantFailure) {
+      return NextResponse.json(grantFailure.body, { status: grantFailure.status })
+    }
+
+    // Assign the PK up front so it is available before flush (MikroORM does not
+    // generate UUIDs client-side).
+    const published = em.create(WorkflowDefinition, {
+      id: randomUUID(),
+      workflowId: source.workflowId,
+      codeWorkflowId: source.codeWorkflowId ?? null,
+      workflowName: source.workflowName,
+      description: source.description ?? null,
+      version: nextVersion,
+      definition: source.definition,
+      metadata: source.metadata ?? null,
+      enabled: true,
+      kind: source.kind,
+      lifecycle: 'published',
+      grantedFeatures: grantedFeatures.length ? grantedFeatures : null,
+      tenantId,
+      organizationId,
+      createdBy: auth.sub,
+      updatedBy: auth.sub,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    })
+    await syncWorkflowDefinitionPrincipal(container, published)
+    em.persist(published)
+    await em.flush()
+
+    if (guardResult?.shouldRunAfterSuccess) {
+      await runCrudMutationGuardAfterSuccess(container, {
+        tenantId,
+        organizationId,
+        userId: auth.sub ?? '',
+        resourceKind: 'workflows.definition',
+        resourceId: String(published.id),
+        operation: 'custom',
+        requestMethod: 'POST',
+        requestHeaders: request.headers,
+        metadata: guardResult.metadata,
+      })
+    }
+
+    try {
+      const eventBus = container.resolve('eventBus') as
+        | { emitEvent(event: string, payload: unknown, options?: unknown): Promise<void> }
+        | undefined
+      if (eventBus && typeof eventBus.emitEvent === 'function') {
+        await eventBus.emitEvent(
+          'workflows.definition.published',
+          {
+            id: published.id,
+            workflowId: published.workflowId,
+            version: published.version,
+            tenantId: published.tenantId,
+            organizationId: published.organizationId,
+            userId: auth.sub ?? null,
+          },
+          { tenantId: published.tenantId, organizationId: published.organizationId, persistent: true },
+        )
+      }
+    } catch (eventError) {
+      logger.error('failed to emit workflows.definition.published event', {
+        error: eventError instanceof Error ? eventError.message : String(eventError),
+      })
+    }
+
+    return NextResponse.json({
+      data: serializeWorkflowDefinition(published),
+      breakingChanges,
+      message: 'Workflow definition published successfully',
+    })
+  } catch (error) {
+    logger.error('error publishing workflow definition', {
+      error: error instanceof Error ? error.message : String(error),
+    })
+    return NextResponse.json({ error: 'Failed to publish workflow definition' }, { status: 500 })
+  }
+}
+
+export const openApi = {
+  methods: {
+    POST: {
+      summary: 'Publish a new workflow definition version',
+      description:
+        'Mints a frozen published version snapshotting the definition and its IO port contract. Returns affected sub-workflow callers; pass acknowledgeBreakingChanges=true to publish despite breaking changes.',
+      tags: ['Workflows'],
+      pathParams: z.object({ id: z.string().describe('Workflow definition id') }),
+      requestBody: publishInputSchema,
+      responses: [
+        {
+          status: 200,
+          description: 'Published',
+          example: {
+            data: { id: '…', workflowId: 'verify-policy', version: 2, lifecycle: 'published' },
+            breakingChanges: [],
+            message: 'Workflow definition published successfully',
+          },
+        },
+        {
+          status: 409,
+          description: 'Breaking changes not acknowledged',
+          example: {
+            error: 'Publishing would break existing sub-workflow mappings',
+            breakingChanges: [{ workflowId: 'order-flow', version: 1, stepId: 'sub', brokenMappings: ['input:orderId'] }],
+          },
+        },
+        { status: 404, description: 'Not found', example: { error: 'Workflow definition not found' } },
+      ],
+    },
+  },
+}

package/src/modules/workflows/api/definitions/[id]/reset-to-code/route.ts

@@ -15,6 +15,7 @@ import { resolveOrganizationScopeForRequest } from '@open-mercato/core/modules/d
 import { validateCrudMutationGuard, runCrudMutationGuardAfterSuccess } from '@open-mercato/shared/lib/crud/mutation-guard'
 import { WorkflowDefinition, WorkflowInstance } from '../../../../data/entities'
 import { serializeCodeWorkflowDefinition } from '../../serialize'
+import { workflowDefinitionResetResponseSchema, workflowErrorSchema } from '../../../openapi'
 import { getCodeWorkflow } from '../../../../lib/code-registry'
 import { invalidateTriggerCache } from '../../../../lib/event-trigger-service'
 import { createLogger } from '@open-mercato/shared/lib/logger'
@@ -222,6 +223,7 @@ export const openApi = {
         {
           status: 200,
           description: 'Workflow definition reset to code version',
+          schema: workflowDefinitionResetResponseSchema,
           example: {
             data: {
               id: 'code:checkout-flow',
@@ -238,6 +240,7 @@ export const openApi = {
         {
           status: 400,
           description: 'Definition is not a code-based override',
+          schema: workflowErrorSchema,
           example: {
             error: 'This workflow definition is not a code-based override and cannot be reset',
           },
@@ -245,6 +248,7 @@ export const openApi = {
         {
           status: 404,
           description: 'Workflow definition not found',
+          schema: workflowErrorSchema,
           example: {
             error: 'Workflow definition not found',
           },
@@ -252,6 +256,7 @@ export const openApi = {
         {
           status: 409,
           description: 'Cannot reset - active workflow instances exist',
+          schema: workflowErrorSchema,
           example: {
             error: 'Cannot reset workflow definition with 3 active instance(s)',
           },

package/src/modules/workflows/api/definitions/[id]/route.ts

@@ -13,15 +13,33 @@ import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
 import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
 import { resolveOrganizationScopeForRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
 import { resolveOrganizationScopeFilter } from '@open-mercato/core/modules/directory/utils/organizationScopeFilter'
-import { WorkflowDefinition } from '../../../data/entities'
+import { WorkflowDefinition, WorkflowInstance } from '../../../data/entities'
 import {
   updateWorkflowDefinitionInputSchema,
+  updateWorkflowDefinitionInputCheckedSchema,
   type UpdateWorkflowDefinitionApiInput,
 } from '../../../data/validators'
 import { serializeWorkflowDefinition, serializeCodeWorkflowDefinition } from '../serialize'
+import {
+  workflowDefinitionDetailResponseSchema,
+  workflowDefinitionMutationResponseSchema,
+  workflowDefinitionDeleteResponseSchema,
+  workflowErrorSchema,
+} from '../../openapi'
 import { invalidateTriggerCache } from '../../../lib/event-trigger-service'
+import { normalizeDefinitionValidationIssues } from '../../../lib/definition-error-body'
 import { getCodeWorkflow, getAllCodeWorkflows } from '../../../lib/code-registry'
 import { codeWorkflowUuid } from '../../../lib/find-definition'
+import {
+  ACTIVE_WORKFLOW_INSTANCE_STATUSES,
+  buildStructuralEditConflictBody,
+  diffDefinitionStructure,
+} from '../../../lib/definition-edit-safety'
+import {
+  authorizeWorkflowGrantChange,
+  normalizeGrantedFeatures,
+  syncWorkflowDefinitionPrincipal,
+} from '../../../lib/definition-grant'
 import { createGenericOptimisticLockReader } from '@open-mercato/shared/lib/crud/optimistic-lock'
 import { registerOptimisticLockReaderIfAbsent } from '@open-mercato/shared/lib/crud/optimistic-lock-store'
 import { validateCrudMutationGuard, runCrudMutationGuardAfterSuccess } from '@open-mercato/shared/lib/crud/mutation-guard'
@@ -170,12 +188,12 @@ export async function PUT(
     const body = await request.json()
 
     // Validate input
-    const validation = updateWorkflowDefinitionInputSchema.safeParse(body)
+    const validation = updateWorkflowDefinitionInputCheckedSchema.safeParse(body)
     if (!validation.success) {
       return NextResponse.json(
         {
           error: 'Validation failed',
-          details: validation.error.issues,
+          details: normalizeDefinitionValidationIssues(validation.error),
         },
         { status: 400 }
       )
@@ -208,11 +226,12 @@ export async function PUT(
         )
       }
 
-      // Check if an override already exists (including soft-deleted, due to unique constraint on workflowId+tenantId)
+      // Check if an override already exists. Pin to the latest version so the
+      // override update targets a deterministic row now that versions coexist.
       const existingOverride = await em.findOne(WorkflowDefinition, {
         workflowId: codeDef.workflowId,
         tenantId,
-      })
+      }, { orderBy: { version: 'DESC' } })
 
       let savedOverride: WorkflowDefinition
       if (existingOverride) {
@@ -337,6 +356,35 @@ export async function PUT(
       throw lockError
     }
 
+    // Edit-safety rule (spec 4.1). Instances pin this row and the engine
+    // re-reads it on every advance, so a topology rewrite would re-point routes
+    // under a running instance. Structural changes are refused while instances
+    // are still executing; the structured body offers the new-version remedy.
+    // Cosmetic, config and metadata edits stay in-place, and the per-user draft
+    // layer (a separate route) is untouched so work-in-progress stays saveable.
+    if (input.definition !== undefined) {
+      const structuralChanges = diffDefinitionStructure(definition.definition, input.definition)
+      if (structuralChanges.length > 0) {
+        const activeInstanceCount = await em.count(WorkflowInstance, {
+          definitionId: definition.id,
+          status: { $in: [...ACTIVE_WORKFLOW_INSTANCE_STATUSES] },
+          tenantId,
+          organizationId,
+          deletedAt: null,
+        })
+        if (activeInstanceCount > 0) {
+          return NextResponse.json(
+            buildStructuralEditConflictBody({
+              definitionId: definition.id,
+              activeInstanceCount,
+              changes: structuralChanges,
+            }),
+            { status: 409 },
+          )
+        }
+      }
+    }
+
     // Update fields. workflowId is intentionally ignored — it identifies the
     // row and renaming would break references. Version is user-managed and
     // applied when supplied so the edit form can bump it explicitly.
@@ -365,6 +413,29 @@ export async function PUT(
       definition.effectiveTo = input.effectiveTo
     }
 
+    // Execution identity. Absent leaves the stored grant untouched; an explicit
+    // value is authorised against the SAVING user's own current features (never
+    // the original author's) and the principal is re-scoped before the row is
+    // flushed, so the column and the role ACL can never disagree.
+    if (input.grantedFeatures !== undefined) {
+      const requestedGrant = normalizeGrantedFeatures(input.grantedFeatures)
+      const previousGrant = normalizeGrantedFeatures(definition.grantedFeatures)
+      const grantFailure = await authorizeWorkflowGrantChange(rbacService, {
+        userId: auth.sub,
+        scope: { tenantId, organizationId },
+        requested: requestedGrant,
+        current: previousGrant,
+      })
+      if (grantFailure) {
+        return NextResponse.json(grantFailure.body, { status: grantFailure.status })
+      }
+      definition.grantedFeatures = requestedGrant.length ? requestedGrant : null
+      // Clearing a grant re-scopes the existing principal to no features rather
+      // than leaving its old ACL behind.
+      await syncWorkflowDefinitionPrincipal(container, definition, { previousFeatures: previousGrant })
+    }
+
+    definition.updatedBy = auth.sub
     definition.updatedAt = new Date()
 
     await em.flush()
@@ -533,6 +604,7 @@ export const openApi = {
         {
           status: 200,
           description: 'Workflow definition found',
+          schema: workflowDefinitionDetailResponseSchema,
           example: {
             data: {
               id: '123e4567-e89b-12d3-a456-426614174000',
@@ -612,6 +684,7 @@ export const openApi = {
         {
           status: 404,
           description: 'Workflow definition not found',
+          schema: workflowErrorSchema,
           example: {
             error: 'Workflow definition not found',
           },
@@ -690,6 +763,7 @@ export const openApi = {
         {
           status: 200,
           description: 'Workflow definition updated successfully',
+          schema: workflowDefinitionMutationResponseSchema,
           example: {
             data: {
               id: '123e4567-e89b-12d3-a456-426614174000',
@@ -756,13 +830,16 @@ export const openApi = {
         {
           status: 400,
           description: 'Validation error',
+          schema: workflowErrorSchema,
           example: {
             error: 'Validation failed',
             details: [
               {
-                code: 'invalid_type',
-                message: 'Expected object, received string',
                 path: ['definition'],
+                code: 'invalid_type',
+                message: 'Invalid input: expected object, received string',
+                expected: 'object',
+                got: 'string',
               },
             ],
           },
@@ -770,10 +847,30 @@ export const openApi = {
         {
           status: 404,
           description: 'Workflow definition not found',
+          schema: workflowErrorSchema,
           example: {
             error: 'Workflow definition not found',
           },
         },
+        {
+          status: 409,
+          description:
+            'Structural change refused while instances are still running (or optimistic-lock conflict). Publish a new version and apply the change there.',
+          schema: workflowErrorSchema,
+          example: {
+            error: 'Structural changes require a new version while instances are still running',
+            code: 'WORKFLOW_STRUCTURAL_EDIT_REQUIRES_NEW_VERSION',
+            definitionId: '123e4567-e89b-12d3-a456-426614174000',
+            activeInstanceCount: 3,
+            activeStatuses: ['RUNNING', 'PAUSED', 'WAITING_FOR_ACTIVITIES', 'FORKED', 'COMPENSATING'],
+            changes: [{ kind: 'transitionRetargeted', id: 't_lz3k9_ab12cd34e' }],
+            remedy: {
+              action: 'createVersion',
+              method: 'POST',
+              endpoint: '/api/workflows/definitions/123e4567-e89b-12d3-a456-426614174000/publish',
+            },
+          },
+        },
       ],
     },
     DELETE: {
@@ -787,6 +884,7 @@ export const openApi = {
         {
           status: 200,
           description: 'Workflow definition deleted successfully',
+          schema: workflowDefinitionDeleteResponseSchema,
           example: {
             message: 'Workflow definition deleted successfully',
           },
@@ -794,6 +892,7 @@ export const openApi = {
         {
           status: 404,
           description: 'Workflow definition not found',
+          schema: workflowErrorSchema,
           example: {
             error: 'Workflow definition not found',
           },
@@ -801,6 +900,7 @@ export const openApi = {
         {
           status: 409,
           description: 'Cannot delete - active workflow instances exist',
+          schema: workflowErrorSchema,
           example: {
             error: 'Cannot delete workflow definition with 3 active instance(s)',
           },