@open-mercato/core 0.8.1-develop.7296.1.2111d779db → 0.9.0

package/src/modules/forms/api/[id]/theme-logo/route.ts

@@ -0,0 +1,147 @@
+/**
+ * Form logo upload — POST /api/forms/:id/theme-logo
+ *
+ * Authoring-only (`forms.design`). Stores a brand logo/header image so a themed
+ * form can render it. The author NEVER supplies a URL — only the uploaded bytes;
+ * the route returns an `assetId` that the studio writes into `x-om-theme.logo`.
+ *
+ * The image is validated (magic bytes + dimensions + size) and stored via the
+ * core attachments storage into a PUBLIC, UNSCOPED partition row (`formLogos`,
+ * no org/tenant) so the public image route can serve it to anonymous form
+ * visitors on `/f/:slug` and `/embed/:slug` (see D4 in
+ * `.ai/specs/2026-05-22-forms-styling-ux-and-branding.md`). The asset is
+ * referenced only by opaque UUID.
+ */
+
+import { NextResponse, type NextRequest } from 'next/server'
+import { randomUUID } from 'node:crypto'
+import { z } from 'zod'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { OpenApiRouteDoc, OpenApiMethodDoc } from '@open-mercato/shared/lib/openapi'
+import { storePartitionFile } from '@open-mercato/core/modules/attachments/lib/storage'
+import {
+  detectImageMimeType,
+  validateImageMagicBytes,
+  validateImageDimensions,
+} from '@open-mercato/core/modules/attachments/lib/imageSafety'
+import { buildAttachmentFileUrl } from '@open-mercato/core/modules/attachments/lib/imageUrls'
+import { Attachment, AttachmentPartition } from '@open-mercato/core/modules/attachments/data/entities'
+import { Form } from '../../../data/entities'
+import { buildFormsRouteContext, handleRouteError, jsonError } from '../../helpers'
+
+export const metadata = {
+  POST: { requireAuth: true, requireFeatures: ['forms.design'] },
+}
+
+const LOGO_PARTITION_CODE = 'formLogos'
+const MAX_LOGO_BYTES = 2 * 1024 * 1024 // 2 MiB — logos/headers are small
+
+async function ensureLogoPartition(em: EntityManager): Promise<void> {
+  const existing = await em.findOne(AttachmentPartition, { code: LOGO_PARTITION_CODE })
+  if (existing) return
+  const partition = em.create(AttachmentPartition, {
+    code: LOGO_PARTITION_CODE,
+    title: 'Form logos',
+    description: 'Public logos/headers uploaded for branded forms.',
+    storageDriver: 'local',
+    isPublic: true,
+    requiresOcr: false,
+  })
+  em.persist(partition)
+  await em.flush()
+}
+
+export async function POST(
+  req: NextRequest,
+  context: { params: { id: string } | Promise<{ id: string }> },
+) {
+  try {
+    const { ctx, organizationId, tenantId } = await buildFormsRouteContext(req)
+    const em = ctx.container.resolve('em') as EntityManager
+    const params = await Promise.resolve(context.params)
+    const formId = String(params.id)
+
+    // Ownership: the form must exist within the caller's scope.
+    const form = await em.findOne(Form, {
+      id: formId,
+      ...(organizationId ? { organizationId } : {}),
+      ...(tenantId ? { tenantId } : {}),
+    })
+    if (!form) return jsonError(404, 'forms.errors.not_found')
+
+    const contentType = req.headers.get('content-type') ?? ''
+    if (!contentType.includes('multipart/form-data')) {
+      return jsonError(400, 'forms.errors.invalid_upload')
+    }
+    const formData = await req.formData()
+    const file = formData.get('file')
+    if (!(file instanceof File) || file.size === 0) {
+      return jsonError(422, 'forms.errors.invalid_upload')
+    }
+    if (file.size > MAX_LOGO_BYTES) {
+      return jsonError(413, 'forms.errors.file_too_large')
+    }
+
+    const buffer = Buffer.from(await file.arrayBuffer())
+    const detectedMime = detectImageMimeType(buffer)
+    const magic = validateImageMagicBytes(buffer, detectedMime)
+    if (!magic.ok) return jsonError(422, 'forms.errors.invalid_image')
+    const dimensions = await validateImageDimensions(buffer)
+    if (!dimensions.ok) return jsonError(422, 'forms.errors.invalid_image')
+
+    await ensureLogoPartition(em)
+
+    const stored = await storePartitionFile({
+      partitionCode: LOGO_PARTITION_CODE,
+      orgId: null,
+      tenantId: null,
+      fileName: file.name || 'logo',
+      buffer,
+    })
+
+    const assetId = randomUUID()
+    const attachment = em.create(Attachment, {
+      id: assetId,
+      entityId: 'forms:theme-logo',
+      recordId: formId,
+      organizationId: null,
+      tenantId: null,
+      partitionCode: LOGO_PARTITION_CODE,
+      fileName: stored.fileName,
+      mimeType: detectedMime ?? 'image/png',
+      fileSize: buffer.length,
+      storageDriver: 'local',
+      storagePath: stored.storagePath,
+      url: buildAttachmentFileUrl(assetId),
+      storageMetadata: null,
+    })
+    em.persist(attachment)
+    await em.flush()
+
+    return NextResponse.json({ assetId }, { status: 201 })
+  } catch (error) {
+    return handleRouteError('theme-logo', error)
+  }
+}
+
+const errorSchema = z.object({ error: z.string() })
+const responseSchema = z.object({ assetId: z.string().uuid() })
+
+const postMethodDoc: OpenApiMethodDoc = {
+  summary: 'Upload a form logo/header image',
+  description:
+    'Stores a brand logo as a public, unscoped attachment and returns its assetId for x-om-theme.logo. Requires forms.design.',
+  tags: ['Forms Authoring'],
+  responses: [{ status: 201, description: 'Logo stored', schema: responseSchema }],
+  errors: [
+    { status: 400, description: 'Not a multipart upload', schema: errorSchema },
+    { status: 404, description: 'Form not found in scope', schema: errorSchema },
+    { status: 413, description: 'File too large', schema: errorSchema },
+    { status: 422, description: 'Missing file or not a valid image', schema: errorSchema },
+  ],
+}
+
+export const openApi: OpenApiRouteDoc = {
+  summary: 'Form logo upload',
+  methods: { POST: postMethodDoc },
+}

package/src/modules/forms/api/[id]/versions/[versionId]/diff/route.ts

@@ -0,0 +1,137 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { FormVersion } from '../../../../../data/entities'
+import { formVersionDiffQuerySchema } from '../../../../../data/validators'
+import { buildFormsRouteContext, handleRouteError, jsonError } from '../../../../helpers'
+import type { FormVersionCompiler } from '../../../../../services/form-version-compiler'
+import type { FormVersionDiffer } from '../../../../../services/form-version-differ'
+
+export const metadata = {
+  GET: { requireAuth: true, requireFeatures: ['forms.view'] },
+}
+
+const fieldDescriptorSchema = z.object({
+  key: z.string(),
+  type: z.string(),
+  sectionKey: z.string().nullable(),
+  sensitive: z.boolean(),
+  editableBy: z.array(z.string()),
+  visibleTo: z.array(z.string()),
+  required: z.boolean(),
+})
+
+const fieldDiffSchema = z.discriminatedUnion('kind', [
+  z.object({ kind: z.literal('added'), key: z.string(), field: fieldDescriptorSchema }),
+  z.object({ kind: z.literal('removed'), key: z.string(), field: fieldDescriptorSchema }),
+  z.object({
+    kind: z.literal('modified'),
+    key: z.string(),
+    changes: z.array(
+      z.object({ path: z.string(), before: z.unknown(), after: z.unknown() }),
+    ),
+  }),
+])
+
+const responseSchema = z.object({
+  base: z.object({
+    id: z.string().uuid(),
+    versionNumber: z.number().int(),
+    schemaHash: z.string(),
+  }),
+  against: z.object({
+    id: z.string().uuid(),
+    versionNumber: z.number().int(),
+    schemaHash: z.string(),
+  }),
+  diff: z.array(fieldDiffSchema),
+})
+
+const errorSchema = z.object({ error: z.string() })
+
+function extractIds(req: Request): { formId: string; versionId: string } {
+  const url = new URL(req.url)
+  const segments = url.pathname.split('/').filter(Boolean)
+  const formsIdx = segments.findIndex((segment) => segment === 'forms')
+  const versionsIdx = segments.findIndex((segment) => segment === 'versions')
+  const formId = formsIdx >= 0 ? segments[formsIdx + 1] ?? '' : ''
+  const versionId = versionsIdx >= 0 ? segments[versionsIdx + 1] ?? '' : ''
+  return { formId, versionId }
+}
+
+export async function GET(req: Request) {
+  try {
+    const { ctx, organizationId, tenantId } = await buildFormsRouteContext(req)
+    if (!organizationId || !tenantId) {
+      return jsonError(400, 'forms.errors.organization_required')
+    }
+    const { formId, versionId } = extractIds(req)
+    if (!formId || !versionId) return jsonError(400, 'forms.errors.invalid_id')
+
+    const url = new URL(req.url)
+    const queryRaw = { against: url.searchParams.get('against') ?? '' }
+    const parsed = formVersionDiffQuerySchema.parse(queryRaw)
+
+    const em = ctx.container.resolve('em') as EntityManager
+    const [base, against] = await Promise.all([
+      em.findOne(FormVersion, { id: versionId, formId, tenantId, organizationId }),
+      em.findOne(FormVersion, {
+        id: parsed.against,
+        formId,
+        tenantId,
+        organizationId,
+      }),
+    ])
+    if (!base) return jsonError(404, 'forms.errors.version_not_found')
+    if (!against) return jsonError(404, 'forms.errors.version_not_found')
+
+    const compiler = ctx.container.resolve('formVersionCompiler') as FormVersionCompiler
+    const differ = ctx.container.resolve('formVersionDiffer') as FormVersionDiffer
+
+    const baseCompiled = compiler.compile({
+      id: base.id,
+      updatedAt: base.updatedAt,
+      schema: base.schema,
+      uiSchema: base.uiSchema,
+    })
+    const againstCompiled = compiler.compile({
+      id: against.id,
+      updatedAt: against.updatedAt,
+      schema: against.schema,
+      uiSchema: against.uiSchema,
+    })
+
+    return NextResponse.json({
+      base: {
+        id: base.id,
+        versionNumber: base.versionNumber,
+        schemaHash: baseCompiled.schemaHash,
+      },
+      against: {
+        id: against.id,
+        versionNumber: against.versionNumber,
+        schemaHash: againstCompiled.schemaHash,
+      },
+      diff: differ.diff(againstCompiled, baseCompiled),
+    })
+  } catch (error) {
+    return handleRouteError('forms.versions.diff.GET', error)
+  }
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'Forms',
+  summary: 'Compute a structural diff between two form versions',
+  pathParams: z.object({ id: z.string().uuid(), versionId: z.string().uuid() }),
+  methods: {
+    GET: {
+      summary: 'Diff form versions',
+      description:
+        'Returns added/removed/modified fields between the URL `versionId` (newer) and the `against` query param (older).',
+      query: formVersionDiffQuerySchema,
+      responses: [{ status: 200, description: 'Diff payload', schema: responseSchema }],
+      errors: [{ status: 404, description: 'Version not found', schema: errorSchema }],
+    },
+  },
+}

package/src/modules/forms/api/[id]/versions/[versionId]/publish/route.ts

@@ -0,0 +1,108 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import type { CommandBus } from '@open-mercato/shared/lib/commands'
+import { getCommandInterceptorHttpRejection } from '@open-mercato/shared/lib/commands/errors'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
+import {
+  formVersionPublishCommandSchema,
+  formVersionPublishRequestSchema,
+  type FormVersionPublishCommandInput,
+} from '../../../../../data/validators'
+import {
+  attachOperationMetadata,
+  buildFormsRouteContext,
+  handleRouteError,
+  jsonError,
+  withMutationGuard,
+  withScopedPayload,
+} from '../../../../helpers'
+import { FORM_VERSION_RESOURCE_KIND } from '../../../../../commands/shared'
+
+export const metadata = {
+  POST: { requireAuth: true, requireFeatures: ['forms.design'] },
+}
+
+const responseSchema = z.object({
+  versionId: z.string().uuid(),
+  versionNumber: z.number().int(),
+  updatedAt: z.string(),
+})
+
+const errorSchema = z.object({ error: z.string() })
+
+function extractIds(req: Request): { formId: string; versionId: string } {
+  const url = new URL(req.url)
+  const segments = url.pathname.split('/').filter(Boolean)
+  const formsIdx = segments.findIndex((segment) => segment === 'forms')
+  const versionsIdx = segments.findIndex((segment) => segment === 'versions')
+  const formId = formsIdx >= 0 ? segments[formsIdx + 1] ?? '' : ''
+  const versionId = versionsIdx >= 0 ? segments[versionsIdx + 1] ?? '' : ''
+  return { formId, versionId }
+}
+
+export async function POST(req: Request) {
+  try {
+    const { ctx, organizationId, tenantId, translate } = await buildFormsRouteContext(req)
+    if (!organizationId || !tenantId) {
+      return jsonError(400, 'forms.errors.organization_required')
+    }
+    const { formId, versionId } = extractIds(req)
+    if (!formId || !versionId) return jsonError(400, 'forms.errors.invalid_id')
+
+    const body = (await readJsonSafe<Record<string, unknown>>(req, {})) ?? {}
+    const parsed = formVersionPublishRequestSchema.parse(body)
+    const scoped = withScopedPayload({ ...parsed, formId, versionId }, ctx, translate)
+    const input = formVersionPublishCommandSchema.parse(scoped) satisfies FormVersionPublishCommandInput
+
+    return await withMutationGuard({
+      ctx,
+      tenantId,
+      organizationId,
+      resourceKind: FORM_VERSION_RESOURCE_KIND,
+      resourceId: versionId,
+      operation: 'custom',
+      request: req,
+      payload: scoped as Record<string, unknown>,
+      run: async () => {
+        const commandBus = ctx.container.resolve('commandBus') as CommandBus
+        const { result, logEntry } = await commandBus.execute<
+          FormVersionPublishCommandInput,
+          { versionId: string; versionNumber: number; updatedAt: string }
+        >('forms.form_version.publish', { input, ctx })
+        const response = NextResponse.json({
+          versionId: result?.versionId ?? versionId,
+          versionNumber: result?.versionNumber ?? null,
+          updatedAt: result?.updatedAt,
+        })
+        return attachOperationMetadata(response, logEntry, FORM_VERSION_RESOURCE_KIND, result?.versionId ?? versionId)
+      },
+    })
+  } catch (error) {
+    const interceptorRejection = getCommandInterceptorHttpRejection(error)
+    if (interceptorRejection) {
+      return NextResponse.json(interceptorRejection.body, { status: interceptorRejection.status })
+    }
+    return handleRouteError('forms.versions.publish.POST', error)
+  }
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'Forms',
+  summary: 'Publish a form version',
+  pathParams: z.object({ id: z.string().uuid(), versionId: z.string().uuid() }),
+  methods: {
+    POST: {
+      summary: 'Publish version',
+      description:
+        'Publishes a draft version. Emits forms.form_version.published, advances form.current_published_version_id, and pins registry_version. Rejects with 422 no_op_publish if schema is unchanged.',
+      requestBody: { contentType: 'application/json', schema: formVersionPublishRequestSchema },
+      responses: [{ status: 200, description: 'Version published', schema: responseSchema }],
+      errors: [
+        { status: 404, description: 'Version not found', schema: errorSchema },
+        { status: 409, description: 'Version is frozen', schema: errorSchema },
+        { status: 422, description: 'No-op or schema invalid', schema: errorSchema },
+      ],
+    },
+  },
+}

package/src/modules/forms/api/[id]/versions/[versionId]/route.ts

@@ -0,0 +1,200 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { CommandBus } from '@open-mercato/shared/lib/commands'
+import { getCommandInterceptorHttpRejection } from '@open-mercato/shared/lib/commands/errors'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
+import { FormVersion } from '../../../../data/entities'
+import {
+  OM_ROOT_KEYWORDS,
+  type OmAnswerMappings,
+} from '../../../../schema/jsonschema-extensions'
+import {
+  formVersionPatchRequestSchema,
+  formVersionUpdateDraftCommandSchema,
+  type FormVersionUpdateDraftCommandInput,
+} from '../../../../data/validators'
+import {
+  attachOperationMetadata,
+  buildFormsRouteContext,
+  handleRouteError,
+  jsonError,
+  withMutationGuard,
+  withScopedPayload,
+} from '../../../helpers'
+import { FORM_VERSION_RESOURCE_KIND } from '../../../../commands/shared'
+
+export const metadata = {
+  GET: { requireAuth: true, requireFeatures: ['forms.view'] },
+  PATCH: { requireAuth: true, requireFeatures: ['forms.design'] },
+}
+
+const versionResponseSchema = z.object({
+  id: z.string().uuid(),
+  formId: z.string().uuid(),
+  versionNumber: z.number().int(),
+  status: z.enum(['draft', 'published', 'archived']),
+  schema: z.record(z.string(), z.unknown()),
+  uiSchema: z.record(z.string(), z.unknown()),
+  roles: z.array(z.string()),
+  schemaHash: z.string(),
+  registryVersion: z.string(),
+  publishedAt: z.string().nullable(),
+  publishedBy: z.string().uuid().nullable(),
+  changelog: z.string().nullable(),
+  archivedAt: z.string().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+  /**
+   * Answer→target mapping (W8 / INT-5). Surfaced as config so consumers can
+   * drive entity binding without PII ever touching an event payload.
+   */
+  answerMappings: z.record(z.string(), z.string()),
+})
+
+/**
+ * Reads the `x-om-answer-mappings` config off a version schema (W8 / INT-5).
+ * The mapping is config — it carries no answers — so it is safe to expose on
+ * the authed read API. Consumer flow (e.g. dental-os): on the id-only
+ * `forms.submission.submitted` event, the subscriber loads the version via
+ * this API (or the runtime context) to read `answerMappings`, fetches the
+ * submission answers from the authed by-subject / GDPR export API, then applies
+ * the mapping to its own entities. The forms module never writes to any
+ * external entity and never emits answers in events (DP-8).
+ */
+function readAnswerMappings(schema: unknown): OmAnswerMappings {
+  if (!schema || typeof schema !== 'object' || Array.isArray(schema)) return {}
+  const raw = (schema as Record<string, unknown>)[OM_ROOT_KEYWORDS.answerMappings]
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return {}
+  const out: OmAnswerMappings = {}
+  for (const [fieldKey, targetPath] of Object.entries(raw as Record<string, unknown>)) {
+    if (typeof targetPath === 'string' && targetPath.length > 0) out[fieldKey] = targetPath
+  }
+  return out
+}
+
+const okSchema = z.object({ ok: z.literal(true), updatedAt: z.string() })
+const errorSchema = z.object({ error: z.string() })
+
+function extractIds(req: Request): { formId: string; versionId: string } {
+  const url = new URL(req.url)
+  const segments = url.pathname.split('/').filter(Boolean)
+  const formsIdx = segments.findIndex((segment) => segment === 'forms')
+  const versionsIdx = segments.findIndex((segment) => segment === 'versions')
+  const formId = formsIdx >= 0 ? segments[formsIdx + 1] ?? '' : ''
+  const versionId = versionsIdx >= 0 ? segments[versionsIdx + 1] ?? '' : ''
+  return { formId, versionId }
+}
+
+export async function GET(req: Request) {
+  try {
+    const { ctx, organizationId, tenantId } = await buildFormsRouteContext(req)
+    if (!organizationId || !tenantId) {
+      return jsonError(400, 'forms.errors.organization_required')
+    }
+    const { formId, versionId } = extractIds(req)
+    if (!formId || !versionId) return jsonError(400, 'forms.errors.invalid_id')
+
+    const em = ctx.container.resolve('em') as EntityManager
+    const version = await em.findOne(FormVersion, {
+      id: versionId,
+      formId,
+      tenantId,
+      organizationId,
+    })
+    if (!version) return jsonError(404, 'forms.errors.version_not_found')
+
+    return NextResponse.json({
+      id: version.id,
+      formId: version.formId,
+      versionNumber: version.versionNumber,
+      status: version.status,
+      schema: version.schema,
+      uiSchema: version.uiSchema,
+      roles: [...version.roles],
+      schemaHash: version.schemaHash,
+      registryVersion: version.registryVersion,
+      publishedAt: version.publishedAt ? version.publishedAt.toISOString() : null,
+      publishedBy: version.publishedBy ?? null,
+      changelog: version.changelog ?? null,
+      archivedAt: version.archivedAt ? version.archivedAt.toISOString() : null,
+      createdAt: version.createdAt.toISOString(),
+      updatedAt: version.updatedAt.toISOString(),
+      answerMappings: readAnswerMappings(version.schema),
+    })
+  } catch (error) {
+    return handleRouteError('forms.versions[versionId].GET', error)
+  }
+}
+
+export async function PATCH(req: Request) {
+  try {
+    const { ctx, organizationId, tenantId, translate } = await buildFormsRouteContext(req)
+    if (!organizationId || !tenantId) {
+      return jsonError(400, 'forms.errors.organization_required')
+    }
+    const { formId, versionId } = extractIds(req)
+    if (!formId || !versionId) return jsonError(400, 'forms.errors.invalid_id')
+
+    const body = (await readJsonSafe<Record<string, unknown>>(req, {})) ?? {}
+    const parsed = formVersionPatchRequestSchema.parse(body)
+    const scoped = withScopedPayload({ ...parsed, formId, versionId }, ctx, translate)
+    const input = formVersionUpdateDraftCommandSchema.parse(scoped) satisfies FormVersionUpdateDraftCommandInput
+
+    return await withMutationGuard({
+      ctx,
+      tenantId,
+      organizationId,
+      resourceKind: FORM_VERSION_RESOURCE_KIND,
+      resourceId: versionId,
+      operation: 'update',
+      request: req,
+      payload: scoped as Record<string, unknown>,
+      run: async () => {
+        const commandBus = ctx.container.resolve('commandBus') as CommandBus
+        const { result, logEntry } = await commandBus.execute<
+          FormVersionUpdateDraftCommandInput,
+          { versionId: string; updatedAt: string }
+        >(
+          'forms.form_version.update_draft',
+          { input, ctx },
+        )
+        const response = NextResponse.json({ ok: true, updatedAt: result?.updatedAt })
+        return attachOperationMetadata(response, logEntry, FORM_VERSION_RESOURCE_KIND, result?.versionId ?? versionId)
+      },
+    })
+  } catch (error) {
+    const interceptorRejection = getCommandInterceptorHttpRejection(error)
+    if (interceptorRejection) {
+      return NextResponse.json(interceptorRejection.body, { status: interceptorRejection.status })
+    }
+    return handleRouteError('forms.versions[versionId].PATCH', error)
+  }
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'Forms',
+  summary: 'Form version detail and draft updates',
+  pathParams: z.object({ id: z.string().uuid(), versionId: z.string().uuid() }),
+  methods: {
+    GET: {
+      summary: 'Get version detail',
+      description: 'Returns the full schema/uiSchema/roles for a form version.',
+      responses: [{ status: 200, description: 'Form version detail', schema: versionResponseSchema }],
+      errors: [{ status: 404, description: 'Version not found', schema: errorSchema }],
+    },
+    PATCH: {
+      summary: 'Update draft version',
+      description:
+        'Updates schema/uiSchema/roles/changelog on a draft version. Rejects with 409 (version_is_frozen) for non-draft versions.',
+      requestBody: { contentType: 'application/json', schema: formVersionPatchRequestSchema },
+      responses: [{ status: 200, description: 'Draft updated', schema: okSchema }],
+      errors: [
+        { status: 404, description: 'Version not found', schema: errorSchema },
+        { status: 409, description: 'Version is frozen', schema: errorSchema },
+        { status: 422, description: 'Schema validation failed', schema: errorSchema },
+      ],
+    },
+  },
+}

package/src/modules/forms/api/[id]/versions/fork/route.ts

@@ -0,0 +1,98 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import type { CommandBus } from '@open-mercato/shared/lib/commands'
+import { getCommandInterceptorHttpRejection } from '@open-mercato/shared/lib/commands/errors'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
+import {
+  formVersionForkDraftCommandSchema,
+  formVersionForkRequestSchema,
+  type FormVersionForkDraftCommandInput,
+} from '../../../../data/validators'
+import {
+  attachOperationMetadata,
+  buildFormsRouteContext,
+  handleRouteError,
+  jsonError,
+  withMutationGuard,
+  withScopedPayload,
+} from '../../../helpers'
+import { FORM_VERSION_RESOURCE_KIND } from '../../../../commands/shared'
+
+export const metadata = {
+  POST: { requireAuth: true, requireFeatures: ['forms.design'] },
+}
+
+const responseSchema = z.object({
+  versionId: z.string().uuid(),
+})
+
+const errorSchema = z.object({ error: z.string() })
+
+function extractFormId(req: Request): string {
+  const url = new URL(req.url)
+  const segments = url.pathname.split('/').filter(Boolean)
+  const idx = segments.findIndex((segment) => segment === 'forms')
+  return idx >= 0 ? segments[idx + 1] ?? '' : ''
+}
+
+export async function POST(req: Request) {
+  try {
+    const { ctx, organizationId, tenantId, translate } = await buildFormsRouteContext(req)
+    if (!organizationId || !tenantId) {
+      return jsonError(400, 'forms.errors.organization_required')
+    }
+    const formId = extractFormId(req)
+    if (!formId) return jsonError(400, 'forms.errors.invalid_id')
+
+    const body = (await readJsonSafe<Record<string, unknown>>(req, {})) ?? {}
+    const parsed = formVersionForkRequestSchema.parse(body)
+    const scoped = withScopedPayload({ ...parsed, formId }, ctx, translate)
+    const input = formVersionForkDraftCommandSchema.parse(scoped) satisfies FormVersionForkDraftCommandInput
+
+    return await withMutationGuard({
+      ctx,
+      tenantId,
+      organizationId,
+      resourceKind: FORM_VERSION_RESOURCE_KIND,
+      resourceId: 'new',
+      operation: 'create',
+      request: req,
+      payload: scoped as Record<string, unknown>,
+      run: async () => {
+        const commandBus = ctx.container.resolve('commandBus') as CommandBus
+        const { result, logEntry } = await commandBus.execute<FormVersionForkDraftCommandInput, { versionId: string }>(
+          'forms.form_version.fork_draft',
+          { input, ctx },
+        )
+        const response = NextResponse.json({ versionId: result?.versionId ?? null }, { status: 201 })
+        return attachOperationMetadata(response, logEntry, FORM_VERSION_RESOURCE_KIND, result?.versionId ?? null)
+      },
+    })
+  } catch (error) {
+    const interceptorRejection = getCommandInterceptorHttpRejection(error)
+    if (interceptorRejection) {
+      return NextResponse.json(interceptorRejection.body, { status: interceptorRejection.status })
+    }
+    return handleRouteError('forms[id].versions.fork.POST', error)
+  }
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'Forms',
+  summary: 'Fork a new draft form version',
+  pathParams: z.object({ id: z.string().uuid() }),
+  methods: {
+    POST: {
+      summary: 'Fork draft',
+      description:
+        'Creates a new draft version. Optionally clones from `fromVersionId`. Rejects if a draft already exists (422 draft_already_exists).',
+      requestBody: { contentType: 'application/json', schema: formVersionForkRequestSchema },
+      responses: [{ status: 201, description: 'Draft created', schema: responseSchema }],
+      errors: [
+        { status: 404, description: 'Form not found', schema: errorSchema },
+        { status: 422, description: 'Draft already exists', schema: errorSchema },
+      ],
+    },
+  },
+}