create-mercato-app 0.4.6-develop-079c26bb68 → 0.4.6-develop-02aac88968

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-mercato-app",
-  "version": "0.4.6-develop-079c26bb68",
+  "version": "0.4.6-develop-02aac88968",
   "type": "module",
   "description": "Create a new Open Mercato application",
   "main": "./dist/index.js",

package/template/src/app/globals.css

@@ -58,6 +58,7 @@ TODO: Fix that latter to have reference by the package names
 }
 
 :root {
+  color-scheme: light;
   --radius: 0.625rem;
   --background: oklch(1 0 0);
   --foreground: oklch(0.145 0 0);
@@ -104,6 +105,7 @@ TODO: Fix that latter to have reference by the package names
 }
 
 .dark {
+  color-scheme: dark;
   --background: oklch(0.145 0 0);
   --foreground: oklch(0.985 0 0);
   --card: oklch(0.205 0 0);
@@ -155,6 +157,11 @@ TODO: Fix that latter to have reference by the package names
   body {
     @apply bg-background text-foreground;
   }
+  select,
+  select option {
+    background-color: var(--background);
+    color: var(--foreground);
+  }
 }
 
 .rbc-calendar {

package/template/src/bootstrap.ts

@@ -46,6 +46,8 @@ import { analyticsModuleConfigs } from '@/.mercato/generated/analytics.generated
 import { enricherEntries } from '@/.mercato/generated/enrichers.generated'
 import { interceptorEntries } from '@/.mercato/generated/interceptors.generated'
 import { componentOverrideEntries } from '@/.mercato/generated/component-overrides.generated'
+import { guardEntries } from '@/.mercato/generated/guards.generated'
+import { commandInterceptorEntries } from '@/.mercato/generated/command-interceptors.generated'
 import { messageTypes } from '@/.mercato/generated/message-types.generated'
 import { messageObjectTypes } from '@/.mercato/generated/message-objects.generated'
 import { registerMessageTypes } from '@open-mercato/core/modules/messages/lib/message-types-registry'
@@ -74,6 +76,8 @@ export const bootstrap = createBootstrap({
   enricherEntries,
   interceptorEntries,
   componentOverrideEntries,
+  guardEntries,
+  commandInterceptorEntries,
 })
 
 export { isBootstrapped }

package/template/src/modules/example/__integration__/TC-UMES-006-mutation-lifecycle.spec.ts

@@ -0,0 +1,461 @@
+/**
+ * TC-UMES-006: Mutation Lifecycle — API Integration Tests (Phase M)
+ *
+ * Validates mutation guard registry (m1), sync event subscribers (m2),
+ * and command interceptors (m4) through API-level tests against the
+ * example todo CRUD endpoints.
+ *
+ * Spec reference: SPEC-041m — Mutation Lifecycle Hooks
+ * Source scenarios:
+ *   - .ai/qa/scenarios/TC-UMES-ML01-guard-registry-allows-valid-create.md
+ *   - .ai/qa/scenarios/TC-UMES-ML02-sync-subscriber-auto-default-priority.md
+ *   - .ai/qa/scenarios/TC-UMES-ML03-sync-subscriber-blocks-uncomplete.md
+ *   - .ai/qa/scenarios/TC-UMES-ML04-sync-subscriber-audit-delete.md
+ *   - .ai/qa/scenarios/TC-UMES-ML07-command-interceptor-customer-audit.md
+ *   - .ai/qa/scenarios/TC-UMES-ML08-sync-before-update-with-previous-data.md
+ *   - .ai/qa/scenarios/TC-UMES-ML09-sync-before-delete-blocks-operation.md
+ *   - .ai/qa/scenarios/TC-UMES-ML10-full-mutation-lifecycle-e2e.md
+ */
+import { test, expect } from '@playwright/test'
+import {
+  getAuthToken,
+  apiRequest,
+} from '@open-mercato/core/modules/core/__integration__/helpers/api'
+import {
+  createCompanyFixture,
+  deleteEntityIfExists,
+} from '@open-mercato/core/modules/core/__integration__/helpers/crmFixtures'
+
+async function createTodo(
+  request: Parameters<typeof apiRequest>[0],
+  token: string,
+  data: Record<string, unknown>,
+): Promise<{ id: string; [key: string]: unknown }> {
+  const response = await apiRequest(request, 'POST', '/api/example/todos', {
+    token,
+    data,
+  })
+  expect(response.ok()).toBeTruthy()
+  expect(response.status()).toBe(201)
+  const body = await response.json()
+  expect(typeof body.id).toBe('string')
+  return body
+}
+
+async function deleteTodo(
+  request: Parameters<typeof apiRequest>[0],
+  token: string,
+  id: string | null,
+) {
+  if (!id) return
+  try {
+    await apiRequest(request, 'DELETE', `/api/example/todos?id=${encodeURIComponent(id)}`, {
+      token,
+    })
+  } catch {
+    // ignore cleanup failure
+  }
+}
+
+async function updateTodo(
+  request: Parameters<typeof apiRequest>[0],
+  token: string,
+  data: Record<string, unknown>,
+) {
+  return apiRequest(request, 'PUT', '/api/example/todos', {
+    token,
+    data,
+  })
+}
+
+test.describe('TC-UMES-006: Mutation Lifecycle — API Tests', () => {
+  let adminToken = ''
+
+  test.beforeAll(async ({ request }) => {
+    adminToken = await getAuthToken(request, 'admin')
+  })
+
+  // ── Phase m1: Mutation Guard Registry ──────────────────────────────
+
+  test('TC-UMES-ML01: guard registry allows valid todo creation', async ({
+    request,
+  }) => {
+    let todoId: string | null = null
+    try {
+      const body = await createTodo(request, adminToken, {
+        title: `ML01-guard-test-${Date.now()}`,
+      })
+      todoId = body.id
+
+      // Verify the entity exists via GET
+      const getResponse = await apiRequest(
+        request,
+        'GET',
+        `/api/example/todos?id=${encodeURIComponent(todoId)}`,
+        { token: adminToken },
+      )
+      expect(getResponse.ok()).toBeTruthy()
+    } finally {
+      await deleteTodo(request, adminToken, todoId)
+    }
+  })
+
+  test('TC-UMES-ML01b: creating todo without auth returns 401', async ({
+    request,
+  }) => {
+    const response = await apiRequest(request, 'POST', '/api/example/todos', {
+      token: 'invalid-token',
+      data: { title: 'should-fail' },
+    })
+    expect(response.status()).toBe(401)
+  })
+
+  // ── Phase m2: Sync Event Subscribers ───────────────────────────────
+
+  test('TC-UMES-ML02: auto-default-priority subscriber runs on create without blocking', async ({
+    request,
+  }) => {
+    let todoId: string | null = null
+    try {
+      // Create without priority field — sync before-create subscriber fires and
+      // injects modifiedPayload. The subscriber mechanism works (201 returned),
+      // although the bare `priority` key is not persisted as a custom field
+      // (would need `cf_priority` prefix for custom field routing).
+      const body = await createTodo(request, adminToken, {
+        title: `ML02-no-priority-${Date.now()}`,
+      })
+      todoId = body.id
+
+      // Verify the todo was created and is fetchable
+      const getResponse = await apiRequest(
+        request,
+        'GET',
+        `/api/example/todos?id=${encodeURIComponent(todoId)}`,
+        { token: adminToken },
+      )
+      expect(getResponse.ok()).toBeTruthy()
+      const payload = await getResponse.json()
+      const items = payload?.items ?? payload?.data ?? []
+      const todo = items.find((item: Record<string, unknown>) => item.id === todoId)
+      expect(todo).toBeDefined()
+      expect(todo.title).toContain('ML02-no-priority')
+    } finally {
+      await deleteTodo(request, adminToken, todoId)
+    }
+  })
+
+  test('TC-UMES-ML02b: creating with extra fields in body does not break pipeline', async ({
+    request,
+  }) => {
+    let todoId: string | null = null
+    try {
+      // Send extra fields — the passthrough schema accepts them and the
+      // subscriber checks for `priority` in body (finds it, so returns void)
+      const body = await createTodo(request, adminToken, {
+        title: `ML02b-with-priority-${Date.now()}`,
+        priority: 'high',
+      })
+      todoId = body.id
+
+      // Verify creation succeeded through the full pipeline
+      const getResponse = await apiRequest(
+        request,
+        'GET',
+        `/api/example/todos?id=${encodeURIComponent(todoId)}`,
+        { token: adminToken },
+      )
+      expect(getResponse.ok()).toBeTruthy()
+      const payload = await getResponse.json()
+      const items = payload?.items ?? payload?.data ?? []
+      const todo = items.find((item: Record<string, unknown>) => item.id === todoId)
+      expect(todo).toBeDefined()
+      expect(todo.title).toContain('ML02b-with-priority')
+    } finally {
+      await deleteTodo(request, adminToken, todoId)
+    }
+  })
+
+  test('TC-UMES-ML03: prevent-uncomplete blocks reverting completed todo with 422', async ({
+    request,
+  }) => {
+    let todoId: string | null = null
+    try {
+      const body = await createTodo(request, adminToken, {
+        title: `ML03-block-test-${Date.now()}`,
+      })
+      todoId = body.id
+
+      // Mark as done
+      const markDoneResponse = await updateTodo(request, adminToken, {
+        id: todoId,
+        is_done: true,
+      })
+      expect(markDoneResponse.ok()).toBeTruthy()
+
+      // Attempt to revert — should be blocked
+      const revertResponse = await updateTodo(request, adminToken, {
+        id: todoId,
+        is_done: false,
+      })
+      expect(revertResponse.status()).toBe(422)
+      const revertBody = await revertResponse.json()
+      expect(revertBody.error).toContain('Completed todos cannot be reverted to pending')
+    } finally {
+      await deleteTodo(request, adminToken, todoId)
+    }
+  })
+
+  test('TC-UMES-ML03b: updating non-done todo title succeeds freely', async ({
+    request,
+  }) => {
+    let todoId: string | null = null
+    try {
+      const body = await createTodo(request, adminToken, {
+        title: `ML03b-title-only-${Date.now()}`,
+      })
+      todoId = body.id
+
+      // Update title without touching is_done
+      const updateResponse = await updateTodo(request, adminToken, {
+        id: todoId,
+        title: `ML03b-updated-${Date.now()}`,
+      })
+      expect(updateResponse.ok()).toBeTruthy()
+    } finally {
+      await deleteTodo(request, adminToken, todoId)
+    }
+  })
+
+  test('TC-UMES-ML04: audit-delete subscriber fires without errors on deletion', async ({
+    request,
+  }) => {
+    // Create a todo
+    const body = await createTodo(request, adminToken, {
+      title: `ML04-delete-audit-${Date.now()}`,
+    })
+    const todoId = body.id
+
+    // Delete — after-delete subscriber should run without causing errors
+    const deleteResponse = await apiRequest(
+      request,
+      'DELETE',
+      `/api/example/todos?id=${encodeURIComponent(todoId)}`,
+      { token: adminToken },
+    )
+    expect(deleteResponse.ok()).toBeTruthy()
+
+    // Verify todo is gone
+    const getResponse = await apiRequest(
+      request,
+      'GET',
+      `/api/example/todos?id=${encodeURIComponent(todoId)}`,
+      { token: adminToken },
+    )
+    expect(getResponse.ok()).toBeTruthy()
+    const payload = await getResponse.json()
+    const items = payload?.items ?? payload?.data ?? []
+    const found = items.find((item: Record<string, unknown>) => item.id === todoId)
+    expect(found).toBeUndefined()
+  })
+
+  // ── Phase m2: previousData in before-update ────────────────────────
+
+  test('TC-UMES-ML08: before-update subscriber receives previousData and uses it for comparison', async ({
+    request,
+  }) => {
+    let todoId: string | null = null
+    try {
+      const body = await createTodo(request, adminToken, {
+        title: `ML08-previous-data-${Date.now()}`,
+      })
+      todoId = body.id
+
+      // Step 1: Update title only — should succeed (is_done not changing)
+      const titleUpdate = await updateTodo(request, adminToken, {
+        id: todoId,
+        title: `ML08-updated-title-${Date.now()}`,
+      })
+      expect(titleUpdate.ok()).toBeTruthy()
+
+      // Step 2: Mark as done — transition from false → true is allowed
+      const markDone = await updateTodo(request, adminToken, {
+        id: todoId,
+        is_done: true,
+      })
+      expect(markDone.ok()).toBeTruthy()
+
+      // Step 3: Update title while done — should succeed (not changing is_done)
+      const titleWhileDone = await updateTodo(request, adminToken, {
+        id: todoId,
+        title: `ML08-still-done-${Date.now()}`,
+      })
+      expect(titleWhileDone.ok()).toBeTruthy()
+
+      // Step 4: Try to revert — should be blocked because previousData shows is_done=true
+      const revert = await updateTodo(request, adminToken, {
+        id: todoId,
+        is_done: false,
+      })
+      expect(revert.status()).toBe(422)
+    } finally {
+      await deleteTodo(request, adminToken, todoId)
+    }
+  })
+
+  // ── Phase m2: before-delete pipeline ───────────────────────────────
+
+  test('TC-UMES-ML09: before-delete event is wired and deletion completes through full pipeline', async ({
+    request,
+  }) => {
+    const body = await createTodo(request, adminToken, {
+      title: `ML09-delete-pipeline-${Date.now()}`,
+    })
+    const todoId = body.id
+
+    // Delete through the full pipeline (*.deleting → mutation → *.deleted)
+    const deleteResponse = await apiRequest(
+      request,
+      'DELETE',
+      `/api/example/todos?id=${encodeURIComponent(todoId)}`,
+      { token: adminToken },
+    )
+    expect(deleteResponse.ok()).toBeTruthy()
+
+    // Verify soft-deleted
+    const verifyResponse = await apiRequest(
+      request,
+      'GET',
+      `/api/example/todos?id=${encodeURIComponent(todoId)}`,
+      { token: adminToken },
+    )
+    expect(verifyResponse.ok()).toBeTruthy()
+    const payload = await verifyResponse.json()
+    const items = payload?.items ?? payload?.data ?? []
+    expect(items.find((item: Record<string, unknown>) => item.id === todoId)).toBeUndefined()
+  })
+
+  // ── Phase m4: Command Interceptors ─────────────────────────────────
+
+  test('TC-UMES-ML07: command interceptor runs on customer operations without blocking', async ({
+    request,
+  }) => {
+    let companyId: string | null = null
+    try {
+      // Create a company — interceptor targets customers.*
+      companyId = await createCompanyFixture(request, adminToken, `ML07-Interceptor-${Date.now()}`)
+      expect(typeof companyId).toBe('string')
+
+      // Update the company — interceptor should observe but not block
+      const updateResponse = await apiRequest(
+        request,
+        'PUT',
+        '/api/customers/companies',
+        {
+          token: adminToken,
+          data: { id: companyId, name: `ML07-Interceptor-Updated-${Date.now()}` },
+        },
+      )
+      expect(updateResponse.ok()).toBeTruthy()
+    } finally {
+      await deleteEntityIfExists(request, adminToken, '/api/customers/companies', companyId)
+    }
+  })
+
+  // ── Full E2E Lifecycle ─────────────────────────────────────────────
+
+  test('TC-UMES-ML10: full mutation lifecycle — create → update → block → delete', async ({
+    request,
+  }) => {
+    let todoId: string | null = null
+    try {
+      // Step 1: Create — guard passes, sync before-create subscriber fires
+      const created = await createTodo(request, adminToken, {
+        title: `ML10-e2e-lifecycle-${Date.now()}`,
+      })
+      todoId = created.id
+
+      // Step 2: Verify todo exists
+      const getAfterCreate = await apiRequest(
+        request,
+        'GET',
+        `/api/example/todos?id=${encodeURIComponent(todoId)}`,
+        { token: adminToken },
+      )
+      expect(getAfterCreate.ok()).toBeTruthy()
+      const afterCreatePayload = await getAfterCreate.json()
+      const afterCreateItems = afterCreatePayload?.items ?? afterCreatePayload?.data ?? []
+      const afterCreate = afterCreateItems.find(
+        (item: Record<string, unknown>) => item.id === todoId,
+      )
+      expect(afterCreate).toBeDefined()
+      expect(afterCreate.title).toContain('ML10-e2e-lifecycle')
+
+      // Step 3: Update title — should succeed
+      const titleUpdate = await updateTodo(request, adminToken, {
+        id: todoId,
+        title: `ML10-e2e-updated-${Date.now()}`,
+      })
+      expect(titleUpdate.ok()).toBeTruthy()
+
+      // Step 4: Mark as done
+      const markDone = await updateTodo(request, adminToken, {
+        id: todoId,
+        is_done: true,
+      })
+      expect(markDone.ok()).toBeTruthy()
+
+      // Step 5: Attempt revert — should be blocked by prevent-uncomplete
+      const revert = await updateTodo(request, adminToken, {
+        id: todoId,
+        is_done: false,
+      })
+      expect(revert.status()).toBe(422)
+      const revertBody = await revert.json()
+      expect(revertBody.error).toContain('Completed todos cannot be reverted to pending')
+
+      // Step 6: Verify todo is still done
+      const getAfterRevert = await apiRequest(
+        request,
+        'GET',
+        `/api/example/todos?id=${encodeURIComponent(todoId)}`,
+        { token: adminToken },
+      )
+      expect(getAfterRevert.ok()).toBeTruthy()
+      const afterRevertPayload = await getAfterRevert.json()
+      const afterRevertItems = afterRevertPayload?.items ?? afterRevertPayload?.data ?? []
+      const afterRevert = afterRevertItems.find(
+        (item: Record<string, unknown>) => item.id === todoId,
+      )
+      expect(afterRevert).toBeDefined()
+      expect(afterRevert.is_done).toBe(true)
+
+      // Step 7: Delete — audit-delete fires
+      const deleteResponse = await apiRequest(
+        request,
+        'DELETE',
+        `/api/example/todos?id=${encodeURIComponent(todoId)}`,
+        { token: adminToken },
+      )
+      expect(deleteResponse.ok()).toBeTruthy()
+      todoId = null // cleaned up
+
+      // Step 8: Verify gone
+      if (afterRevert?.id) {
+        const verifyGone = await apiRequest(
+          request,
+          'GET',
+          `/api/example/todos?id=${encodeURIComponent(afterRevert.id)}`,
+          { token: adminToken },
+        )
+        expect(verifyGone.ok()).toBeTruthy()
+        const gonePayload = await verifyGone.json()
+        const goneItems = gonePayload?.items ?? gonePayload?.data ?? []
+        expect(
+          goneItems.find((item: Record<string, unknown>) => item.id === afterRevert.id),
+        ).toBeUndefined()
+      }
+    } finally {
+      await deleteTodo(request, adminToken, todoId)
+    }
+  })
+})

package/template/src/modules/example/__integration__/TC-UMES-007.spec.ts

@@ -0,0 +1,175 @@
+/**
+ * TC-UMES-007: Mutation Lifecycle — UI Showcase Page Tests (Phase M)
+ *
+ * Validates the Phase M showcase page at /backend/mutation-lifecycle.
+ * Exercises the guard probe (m1) and sync subscriber probe (m2) through
+ * the interactive UI, verifying status updates, probe results, and
+ * error handling via data-testid attributes.
+ *
+ * Spec reference: SPEC-041m — Mutation Lifecycle Hooks
+ * Source scenarios:
+ *   - .ai/qa/scenarios/TC-UMES-ML05-showcase-page-guard-probe.md
+ *   - .ai/qa/scenarios/TC-UMES-ML06-showcase-page-sync-probe.md
+ */
+import { test, expect } from '@playwright/test'
+import { login } from '@open-mercato/core/modules/core/__integration__/helpers/auth'
+
+test.describe('TC-UMES-007: Mutation Lifecycle — Showcase Page', () => {
+  test.beforeEach(async ({ page }) => {
+    await login(page, 'admin')
+    await page.goto('/backend/mutation-lifecycle')
+    await page.waitForLoadState('domcontentloaded')
+  })
+
+  test('TC-UMES-ML05a: showcase page renders all four phase sections', async ({
+    page,
+  }) => {
+    // Verify all 4 phase sections are visible
+    await expect(page.getByText('Phase m1 — Mutation Guard Registry')).toBeVisible()
+    await expect(page.getByText('Phase m2 — Sync Event Subscribers')).toBeVisible()
+    await expect(page.getByText('Phase m3 — Client-Side Event Filtering')).toBeVisible()
+    await expect(page.getByText('Phase m4 — Command Interceptors')).toBeVisible()
+
+    // Verify initial status is idle for interactive probes
+    await expect(page.getByTestId('phase-m-status-m1')).toContainText('phaseM1=idle')
+    await expect(page.getByTestId('phase-m-status-m2')).toContainText('phaseM2=idle')
+
+    // m3 and m4 are informational — show ok
+    await expect(page.getByTestId('phase-m-status-m3')).toContainText('phaseM3=ok')
+    await expect(page.getByTestId('phase-m-status-m4')).toContainText('phaseM4=ok')
+  })
+
+  test('TC-UMES-ML05b: guard probe creates and cleans up a todo successfully', async ({
+    page,
+  }) => {
+    // Click the guard probe button
+    await page.getByTestId('phase-m1-run-probe').click()
+
+    // Wait for completion
+    await expect(page.getByTestId('phase-m1-status')).toContainText('status=ok', {
+      timeout: 15_000,
+    })
+
+    // Verify result contains an id (todo was created)
+    const resultText = await page.getByTestId('phase-m1-result').textContent()
+    expect(resultText).toContain('"id"')
+
+    // Verify no error is displayed
+    await expect(page.getByTestId('phase-m1-error')).not.toBeVisible()
+  })
+
+  test('TC-UMES-ML05c: guard probe is idempotent — runs twice with same result', async ({
+    page,
+  }) => {
+    // First run
+    await page.getByTestId('phase-m1-run-probe').click()
+    await expect(page.getByTestId('phase-m1-status')).toContainText('status=ok', {
+      timeout: 15_000,
+    })
+
+    // Second run
+    await page.getByTestId('phase-m1-run-probe').click()
+    await expect(page.getByTestId('phase-m1-status')).toContainText('status=ok', {
+      timeout: 15_000,
+    })
+
+    await expect(page.getByTestId('phase-m1-error')).not.toBeVisible()
+  })
+
+  test('TC-UMES-ML06a: sync subscriber probe — all three probes pass', async ({
+    page,
+  }) => {
+    // Click the sync probe button
+    await page.getByTestId('phase-m2-run-probe').click()
+
+    // Wait for overall status to resolve
+    await expect(page.getByTestId('phase-m2-status')).toContainText('status=ok', {
+      timeout: 20_000,
+    })
+
+    // Verify no error displayed
+    await expect(page.getByTestId('phase-m2-error')).not.toBeVisible()
+  })
+
+  test('TC-UMES-ML06b: sync probe — defaultPriority reports ok with 201', async ({
+    page,
+  }) => {
+    await page.getByTestId('phase-m2-run-probe').click()
+
+    // Wait for completion
+    await expect(page.getByTestId('phase-m2-status')).not.toContainText('status=pending', {
+      timeout: 20_000,
+    })
+
+    // Check individual probe result
+    const defaultPriority = page.getByTestId('phase-m2-probe-defaultPriority')
+    await expect(defaultPriority).toContainText('status=ok')
+    await expect(defaultPriority).toContainText('httpStatus=201')
+    await expect(defaultPriority).toContainText('auto-default-priority')
+  })
+
+  test('TC-UMES-ML06c: sync probe — preventUncomplete reports ok with 422', async ({
+    page,
+  }) => {
+    await page.getByTestId('phase-m2-run-probe').click()
+
+    await expect(page.getByTestId('phase-m2-status')).not.toContainText('status=pending', {
+      timeout: 20_000,
+    })
+
+    const preventUncomplete = page.getByTestId('phase-m2-probe-preventUncomplete')
+    await expect(preventUncomplete).toContainText('status=ok')
+    await expect(preventUncomplete).toContainText('httpStatus=422')
+    await expect(preventUncomplete).toContainText('prevent-uncomplete')
+  })
+
+  test('TC-UMES-ML06d: sync probe — auditDelete reports ok with 200', async ({
+    page,
+  }) => {
+    await page.getByTestId('phase-m2-run-probe').click()
+
+    await expect(page.getByTestId('phase-m2-status')).not.toContainText('status=pending', {
+      timeout: 20_000,
+    })
+
+    const auditDelete = page.getByTestId('phase-m2-probe-auditDelete')
+    await expect(auditDelete).toContainText('status=ok')
+    await expect(auditDelete).toContainText('httpStatus=200')
+    await expect(auditDelete).toContainText('audit-delete')
+  })
+
+  test('TC-UMES-ML06e: sync probe — payloads section shows all step data', async ({
+    page,
+  }) => {
+    await page.getByTestId('phase-m2-run-probe').click()
+
+    await expect(page.getByTestId('phase-m2-status')).toContainText('status=ok', {
+      timeout: 20_000,
+    })
+
+    // The result section should contain payloads from all steps
+    const resultText = await page.getByTestId('phase-m2-result').textContent()
+    expect(resultText).toContain('"create"')
+    expect(resultText).toContain('"markDone"')
+    expect(resultText).toContain('"revert"')
+    expect(resultText).toContain('"delete"')
+  })
+
+  // ── Navigation links ───────────────────────────────────────────────
+
+  test('TC-UMES-ML-nav: phase m3 link navigates to CrudForm injection page', async ({
+    page,
+  }) => {
+    const phaseGLink = page.getByRole('link', { name: /Open Phase G/i })
+    await expect(phaseGLink).toBeVisible()
+    await expect(phaseGLink).toHaveAttribute('href', '/backend/umes-extensions')
+  })
+
+  test('TC-UMES-ML-nav2: phase m4 link navigates to customers page', async ({
+    page,
+  }) => {
+    const customersLink = page.getByRole('link', { name: /Open customers/i })
+    await expect(customersLink).toBeVisible()
+    await expect(customersLink).toHaveAttribute('href', '/backend/customers/people')
+  })
+})

package/template/src/modules/example/backend/mutation-lifecycle/page.meta.ts

@@ -0,0 +1,24 @@
+import React from 'react'
+
+const shieldIcon = React.createElement(
+  'svg',
+  { width: 16, height: 16, viewBox: '0 0 24 24', fill: 'none', stroke: 'currentColor', strokeWidth: 2 },
+  React.createElement('path', { d: 'M12 22s8-4 8-10V5l-8-3-8 3v7c0 6 8 10 8 10z' }),
+)
+
+export const metadata = {
+  requireAuth: true,
+  requireFeatures: ['example.todos.view'],
+  pageTitle: 'Phase M — Mutation Lifecycle',
+  pageTitleKey: 'example.menu.mutationLifecycle',
+  pageGroup: 'Example',
+  pageGroupKey: 'example.nav.group',
+  pageOrder: 20700,
+  icon: shieldIcon,
+  breadcrumb: [
+    { label: 'General tasks', labelKey: 'example.todos.page.title', href: '/backend/todos' },
+    { label: 'Phase M — Mutation Lifecycle', labelKey: 'example.mutationLifecycle.title' },
+  ],
+}
+
+export default metadata

package/template/src/modules/example/backend/mutation-lifecycle/page.tsx

@@ -0,0 +1,386 @@
+'use client'
+
+import * as React from 'react'
+import Link from 'next/link'
+import { Page, PageBody } from '@open-mercato/ui/backend/Page'
+import { Button } from '@open-mercato/ui/primitives/button'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { apiCall } from '@open-mercato/ui/backend/utils/apiCall'
+
+type PhaseStatus = 'idle' | 'pending' | 'ok' | 'error'
+
+type SyncProbeKey = 'defaultPriority' | 'preventUncomplete' | 'auditDelete'
+
+type SyncProbeResult = {
+  key: SyncProbeKey
+  label: string
+  status: PhaseStatus
+  httpStatus: number | null
+  ok: boolean
+  details: string
+}
+
+const syncProbeOrder: SyncProbeKey[] = ['defaultPriority', 'preventUncomplete', 'auditDelete']
+const hintClassName = 'rounded-md border border-amber-500/40 bg-amber-50 dark:bg-amber-400/10 p-2 text-xs text-amber-800 dark:text-amber-100/90'
+
+function print(value: unknown): string {
+  try {
+    return JSON.stringify(value ?? null, null, 2)
+  } catch {
+    return String(value)
+  }
+}
+
+function createSyncProbeResult(partial?: Partial<SyncProbeResult>): SyncProbeResult {
+  return {
+    key: partial?.key ?? 'defaultPriority',
+    label: partial?.label ?? '',
+    status: partial?.status ?? 'idle',
+    httpStatus: partial?.httpStatus ?? null,
+    ok: partial?.ok ?? false,
+    details: partial?.details ?? '',
+  }
+}
+
+export default function MutationLifecyclePage() {
+  const t = useT()
+
+  // Phase m1 state
+  const [guardStatus, setGuardStatus] = React.useState<PhaseStatus>('idle')
+  const [guardPayload, setGuardPayload] = React.useState<unknown>(null)
+  const [guardError, setGuardError] = React.useState<string | null>(null)
+
+  // Phase m2 state
+  const [syncStatus, setSyncStatus] = React.useState<PhaseStatus>('idle')
+  const [syncError, setSyncError] = React.useState<string | null>(null)
+  const [syncPayloads, setSyncPayloads] = React.useState<unknown>(null)
+  const [syncProbeResults, setSyncProbeResults] = React.useState<Record<SyncProbeKey, SyncProbeResult>>({
+    defaultPriority: createSyncProbeResult({ key: 'defaultPriority', label: t('example.mutationLifecycle.m2.probe.defaultPriority.label', 'auto-default-priority (before-create)') }),
+    preventUncomplete: createSyncProbeResult({ key: 'preventUncomplete', label: t('example.mutationLifecycle.m2.probe.preventUncomplete.label', 'prevent-uncomplete (before-update)') }),
+    auditDelete: createSyncProbeResult({ key: 'auditDelete', label: t('example.mutationLifecycle.m2.probe.auditDelete.label', 'audit-delete (after-delete)') }),
+  })
+
+  // Phase m3/m4 are informational
+  const phaseM3Status = React.useMemo<PhaseStatus>(() => 'ok', [])
+  const phaseM4Status = React.useMemo<PhaseStatus>(() => 'ok', [])
+
+  // ── Phase m1: Mutation Guard Probe ──────────────────────────────
+  const runGuardProbe = React.useCallback(async () => {
+    setGuardStatus('pending')
+    setGuardError(null)
+    setGuardPayload(null)
+
+    try {
+      // POST a todo — the guard pipeline runs on create
+      const createResponse = await apiCall<{ id: string }>('/api/example/todos', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ title: 'm1-guard-probe' }),
+      })
+
+      setGuardPayload(createResponse.result)
+
+      if (!createResponse.ok) {
+        setGuardStatus('error')
+        setGuardError(
+          t(
+            'example.mutationLifecycle.m1.createFailed',
+            `Guard probe failed: expected 201, got ${createResponse.status}.`,
+          ),
+        )
+        return
+      }
+
+      // Clean up — delete the created todo
+      const todoId = (createResponse.result as { id?: string })?.id
+      if (todoId) {
+        await apiCall(`/api/example/todos?id=${todoId}`, { method: 'DELETE' })
+      }
+
+      setGuardStatus('ok')
+    } catch (error) {
+      setGuardStatus('error')
+      setGuardError(error instanceof Error ? error.message : String(error))
+    }
+  }, [t])
+
+  // ── Phase m2: Sync Subscriber Probe ─────────────────────────────
+  const runSyncProbe = React.useCallback(async () => {
+    setSyncStatus('pending')
+    setSyncError(null)
+    setSyncPayloads(null)
+
+    setSyncProbeResults((prev) => {
+      const next = { ...prev }
+      for (const key of syncProbeOrder) {
+        next[key] = { ...next[key], status: 'pending', httpStatus: null, ok: false, details: '' }
+      }
+      return next
+    })
+
+    const nextResults: Record<SyncProbeKey, SyncProbeResult> = {
+      defaultPriority: createSyncProbeResult({ key: 'defaultPriority', label: t('example.mutationLifecycle.m2.probe.defaultPriority.label', 'auto-default-priority (before-create)'), status: 'pending' }),
+      preventUncomplete: createSyncProbeResult({ key: 'preventUncomplete', label: t('example.mutationLifecycle.m2.probe.preventUncomplete.label', 'prevent-uncomplete (before-update)'), status: 'pending' }),
+      auditDelete: createSyncProbeResult({ key: 'auditDelete', label: t('example.mutationLifecycle.m2.probe.auditDelete.label', 'audit-delete (after-delete)'), status: 'pending' }),
+    }
+
+    const payloads: Record<string, unknown> = {}
+    let createdTodoId: string | null = null
+
+    try {
+      // ── Probe 1: auto-default-priority (before-create) ──
+      const createResponse = await apiCall<{ id: string }>('/api/example/todos', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ title: 'm2-sync-probe' }),
+      })
+      payloads.create = createResponse.result
+      const createOk = createResponse.ok && createResponse.status === 201
+      createdTodoId = createOk ? (createResponse.result as { id?: string })?.id ?? null : null
+
+      nextResults.defaultPriority = {
+        ...nextResults.defaultPriority,
+        status: createOk ? 'ok' : 'error',
+        httpStatus: createResponse.status,
+        ok: createOk,
+        details: createOk
+          ? t('example.mutationLifecycle.m2.probe.defaultPriority.ok', 'Todo created (201). Sync before-event example.todo.creating fired — auto-default-priority subscriber injects priority if absent.')
+          : t('example.mutationLifecycle.m2.probe.defaultPriority.error', `Expected 201, got ${createResponse.status}.`),
+      }
+
+      if (!createdTodoId) {
+        const skipMsg = t('example.mutationLifecycle.m2.probe.skipped', 'Skipped — no todo was created in probe 1.')
+        nextResults.preventUncomplete = {
+          ...nextResults.preventUncomplete,
+          status: 'error',
+          details: skipMsg,
+        }
+        nextResults.auditDelete = {
+          ...nextResults.auditDelete,
+          status: 'error',
+          details: skipMsg,
+        }
+        setSyncStatus('error')
+        setSyncError(t('example.mutationLifecycle.m2.createFailed', 'Could not create todo for sync subscriber probe.'))
+        setSyncPayloads(payloads)
+        setSyncProbeResults(nextResults)
+        return
+      }
+
+      // ── Probe 2: prevent-uncomplete (before-update) ──
+      // Step 2a: Mark as done
+      const markDoneResponse = await apiCall('/api/example/todos', {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ id: createdTodoId, is_done: true }),
+      })
+      payloads.markDone = markDoneResponse.result
+      const markDoneOk = markDoneResponse.ok
+
+      if (!markDoneOk) {
+        nextResults.preventUncomplete = {
+          ...nextResults.preventUncomplete,
+          status: 'error',
+          httpStatus: markDoneResponse.status,
+          details: t('example.mutationLifecycle.m2.probe.preventUncomplete.markDoneFailed', `Failed to mark todo as done: status ${markDoneResponse.status}.`),
+        }
+      } else {
+        // Step 2b: Try to revert to pending — should be blocked by prevent-uncomplete subscriber
+        const revertResponse = await apiCall('/api/example/todos', {
+          method: 'PUT',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ id: createdTodoId, is_done: false }),
+        })
+        payloads.revert = revertResponse.result
+        const revertBlocked = revertResponse.status === 422
+        nextResults.preventUncomplete = {
+          ...nextResults.preventUncomplete,
+          status: revertBlocked ? 'ok' : 'error',
+          httpStatus: revertResponse.status,
+          ok: revertBlocked,
+          details: revertBlocked
+            ? t('example.mutationLifecycle.m2.probe.preventUncomplete.ok', 'Revert blocked (422). Sync before-event example.todo.updating fired — prevent-uncomplete subscriber rejected the operation.')
+            : t('example.mutationLifecycle.m2.probe.preventUncomplete.error', `Expected 422 (blocked), got ${revertResponse.status}.`),
+        }
+      }
+
+      // ── Probe 3: audit-delete (after-delete) ──
+      const deleteResponse = await apiCall(`/api/example/todos?id=${createdTodoId}`, {
+        method: 'DELETE',
+      })
+      payloads.delete = deleteResponse.result
+      const deleteOk = deleteResponse.ok
+      nextResults.auditDelete = {
+        ...nextResults.auditDelete,
+        status: deleteOk ? 'ok' : 'error',
+        httpStatus: deleteResponse.status,
+        ok: deleteOk,
+        details: deleteOk
+          ? t('example.mutationLifecycle.m2.probe.auditDelete.ok', 'Todo deleted (200). Sync after-event example.todo.deleted fired — audit-delete subscriber logged to server console.')
+          : t('example.mutationLifecycle.m2.probe.auditDelete.error', `Expected 200, got ${deleteResponse.status}.`),
+      }
+      createdTodoId = null
+
+      const allOk = syncProbeOrder.every((key) => nextResults[key].ok)
+      setSyncStatus(allOk ? 'ok' : 'error')
+      if (!allOk) {
+        setSyncError(t('example.mutationLifecycle.m2.partial', 'One or more sync subscriber probes failed. Review rows below.'))
+      }
+    } catch (error) {
+      setSyncStatus('error')
+      setSyncError(error instanceof Error ? error.message : String(error))
+    } finally {
+      // Clean up if a todo was left behind
+      if (createdTodoId) {
+        await apiCall(`/api/example/todos?id=${createdTodoId}`, { method: 'DELETE' }).catch(() => {})
+      }
+      setSyncPayloads(payloads)
+      setSyncProbeResults(nextResults)
+    }
+  }, [t])
+
+  return (
+    <Page>
+      <PageBody className="space-y-4">
+        <div>
+          <h1 className="text-xl font-semibold">{t('example.mutationLifecycle.title', 'UMES Phase M — Mutation Lifecycle')}</h1>
+          <p className="text-sm text-muted-foreground">
+            {t('example.mutationLifecycle.description', 'Validation page for mutation guards, sync event subscribers, client-side event filtering, and command interceptors.')}
+          </p>
+        </div>
+
+        {/* Status overview */}
+        <div className="grid gap-2 rounded border border-border p-3 text-xs text-muted-foreground">
+          <div data-testid="phase-m-status-m1">phaseM1={guardStatus}</div>
+          <div data-testid="phase-m-status-m2">phaseM2={syncStatus}</div>
+          <div data-testid="phase-m-status-m3">phaseM3={phaseM3Status}</div>
+          <div data-testid="phase-m-status-m4">phaseM4={phaseM4Status}</div>
+        </div>
+
+        {/* ── Phase m1: Mutation Guard Registry ── */}
+        <div className="space-y-3 rounded border border-border p-4">
+          <div>
+            <h2 className="text-base font-semibold">{t('example.mutationLifecycle.m1.title', 'Phase m1 — Mutation Guard Registry')}</h2>
+            <p className="text-sm text-muted-foreground">
+              {t('example.mutationLifecycle.m1.description', 'Create a todo via the CRUD pipeline to verify the mutation guard registry evaluates the `example.todo-limit` guard on POST.')}
+            </p>
+          </div>
+          <div className={`grid gap-1 ${hintClassName}`}>
+            <div className="font-medium text-amber-900 dark:text-amber-50">{t('example.mutationLifecycle.hintHeading', 'What should be visible and how it should work')}</div>
+            <div>{t('example.mutationLifecycle.m1.hint1', '1. Guard `example.todo-limit` targets `example.todo` on `create` operations with priority 50.')}</div>
+            <div>{t('example.mutationLifecycle.m1.hint2', '2. Guard validates `organizationId` presence — creation fails with 422 if missing.')}</div>
+            <div>{t('example.mutationLifecycle.m1.hint3', '3. Multiple guards run by priority order; first rejection stops the pipeline.')}</div>
+            <div>{t('example.mutationLifecycle.m1.hint4', '4. Legacy `crudMutationGuardService` is automatically bridged as a guard with priority 0.')}</div>
+          </div>
+          <div className="flex flex-wrap items-center gap-2">
+            <Button data-testid="phase-m1-run-probe" type="button" onClick={() => void runGuardProbe()}>
+              {t('example.mutationLifecycle.m1.run', 'Run guard probe')}
+            </Button>
+            <span data-testid="phase-m1-status" className="text-xs text-muted-foreground">status={guardStatus}</span>
+          </div>
+          {guardError ? <div data-testid="phase-m1-error" className="text-xs text-destructive">{guardError}</div> : null}
+          <div data-testid="phase-m1-result" className="rounded border border-border bg-muted/30 p-2 text-xs text-muted-foreground">
+            response={print(guardPayload)}
+          </div>
+        </div>
+
+        {/* ── Phase m2: Sync Event Subscribers ── */}
+        <div className="space-y-3 rounded border border-border p-4">
+          <div>
+            <h2 className="text-base font-semibold">{t('example.mutationLifecycle.m2.title', 'Phase m2 — Sync Event Subscribers')}</h2>
+            <p className="text-sm text-muted-foreground">
+              {t('example.mutationLifecycle.m2.description', 'Run a multi-step probe: create a todo (verify auto-default-priority), mark as done then try to revert (verify prevent-uncomplete blocks with 422), and delete (verify audit-delete fires).')}
+            </p>
+          </div>
+          <div className={`grid gap-1 ${hintClassName}`}>
+            <div className="font-medium text-amber-900 dark:text-amber-50">{t('example.mutationLifecycle.hintHeading', 'What should be visible and how it should work')}</div>
+            <div>{t('example.mutationLifecycle.m2.hint1', '1. `auto-default-priority`: Injects `priority: \'normal\'` when creating a todo without explicit priority (sync before-create).')}</div>
+            <div>{t('example.mutationLifecycle.m2.hint2', '2. `prevent-uncomplete`: Blocks reverting completed todos to pending with 422 (sync before-update).')}</div>
+            <div>{t('example.mutationLifecycle.m2.hint3', '3. `audit-delete`: Logs deletion audit trail to server console (sync after-delete, non-blocking).')}</div>
+            <div>{t('example.mutationLifecycle.m2.hint4', '4. Sync subscribers run inside the CRUD pipeline, before/after the actual mutation — unlike async subscribers which run post-commit.')}</div>
+          </div>
+          <div className="flex flex-wrap items-center gap-2">
+            <Button data-testid="phase-m2-run-probe" type="button" onClick={() => void runSyncProbe()}>
+              {t('example.mutationLifecycle.m2.run', 'Run sync subscriber probe')}
+            </Button>
+            <span data-testid="phase-m2-status" className="text-xs text-muted-foreground">status={syncStatus}</span>
+          </div>
+          {syncError ? <div data-testid="phase-m2-error" className="text-xs text-destructive">{syncError}</div> : null}
+          <div className="grid gap-2">
+            {syncProbeOrder.map((key) => {
+              const probe = syncProbeResults[key]
+              return (
+                <div key={probe.key} className="grid gap-1 rounded border border-border p-2 text-xs" data-testid={`phase-m2-probe-${probe.key}`}>
+                  <div className="font-medium text-foreground">{probe.label}</div>
+                  <div className="text-muted-foreground">status={probe.status} httpStatus={probe.httpStatus ?? 'n/a'}</div>
+                  <div className="text-muted-foreground">{probe.details}</div>
+                </div>
+              )
+            })}
+          </div>
+          <div data-testid="phase-m2-result" className="rounded border border-border bg-muted/30 p-2 text-xs text-muted-foreground">
+            payloads={print(syncPayloads)}
+          </div>
+        </div>
+
+        {/* ── Phase m3: Client-Side Event Filtering ── */}
+        <div className="space-y-3 rounded border border-border p-4">
+          <div>
+            <h2 className="text-base font-semibold">{t('example.mutationLifecycle.m3.title', 'Phase m3 — Client-Side Event Filtering')}</h2>
+            <p className="text-sm text-muted-foreground">
+              {t('example.mutationLifecycle.m3.description', 'Widget injection event handlers can now declare an operation filter to skip events for specific CRUD operations.')}
+            </p>
+          </div>
+          <div className={`grid gap-1 ${hintClassName}`}>
+            <div className="font-medium text-amber-900 dark:text-amber-50">{t('example.mutationLifecycle.hintHeading', 'What should be visible and how it should work')}</div>
+            <div>{t('example.mutationLifecycle.m3.hint1', '1. Widgets can declare `eventHandlers.filter.operations` to skip specific CRUD operations (e.g., only fire on `update`).')}</div>
+            <div>{t('example.mutationLifecycle.m3.hint2', '2. CrudForm now passes `operation` (\'create\' or \'update\') in the injection context.')}</div>
+            <div>{t('example.mutationLifecycle.m3.hint3', '3. Widgets without a filter continue to fire for all operations (backward compatible).')}</div>
+            <div>{t('example.mutationLifecycle.m3.hint4', '4. Type: `WidgetInjectionEventFilter = { operations?: (\'create\' | \'update\' | \'delete\')[] }`')}</div>
+          </div>
+          <div className="flex flex-wrap items-center gap-2 text-xs text-muted-foreground">
+            <Button asChild type="button" variant="outline">
+              <Link href="/backend/umes-extensions">{t('example.mutationLifecycle.m3.openPhaseG', 'Open Phase G — CrudForm injection')}</Link>
+            </Button>
+            <span>{t('example.mutationLifecycle.m3.note', 'The filter is a type-level extension. See Phase G page for CrudForm injection demo.')}</span>
+          </div>
+          <div className="rounded border border-border bg-muted/30 p-2 text-xs text-muted-foreground">
+            type={print({ operations: ['create', 'update', 'delete'] })}
+          </div>
+        </div>
+
+        {/* ── Phase m4: Command Interceptors ── */}
+        <div className="space-y-3 rounded border border-border p-4">
+          <div>
+            <h2 className="text-base font-semibold">{t('example.mutationLifecycle.m4.title', 'Phase m4 — Command Interceptors')}</h2>
+            <p className="text-sm text-muted-foreground">
+              {t('example.mutationLifecycle.m4.description', 'The `example.audit-logging` interceptor wraps all `customers.*` command bus operations with timing metadata.')}
+            </p>
+          </div>
+          <div className={`grid gap-1 ${hintClassName}`}>
+            <div className="font-medium text-amber-900 dark:text-amber-50">{t('example.mutationLifecycle.hintHeading', 'What should be visible and how it should work')}</div>
+            <div>{t('example.mutationLifecycle.m4.hint1', '1. `example.audit-logging` intercepts all `customers.*` commands (wildcard pattern).')}</div>
+            <div>{t('example.mutationLifecycle.m4.hint2', '2. `beforeExecute` stores `auditStartedAt` timestamp in metadata.')}</div>
+            <div>{t('example.mutationLifecycle.m4.hint3', '3. `afterExecute` reads metadata and logs: `[example:audit] Command {id} completed in {ms}ms`.')}</div>
+            <div>{t('example.mutationLifecycle.m4.hint4', '4. Pattern matching supports `*` (all), exact ID, and `prefix.*` (namespace wildcard).')}</div>
+            <div>{t('example.mutationLifecycle.m4.hint5', '5. Interceptors run on both `execute()` and `undo()` code paths.')}</div>
+          </div>
+          <div className="flex flex-wrap items-center gap-2 text-xs text-muted-foreground">
+            <Button asChild type="button" variant="outline">
+              <Link href="/backend/customers/people">{t('example.mutationLifecycle.m4.openCustomers', 'Open customers')}</Link>
+            </Button>
+            <span>{t('example.mutationLifecycle.m4.note', 'Create or edit a customer, then check server console for the audit log entry.')}</span>
+          </div>
+          <div className="rounded border border-border bg-muted/30 p-2 text-xs text-muted-foreground">
+            interceptor={print({
+              id: 'example.audit-logging',
+              targetCommand: 'customers.*',
+              priority: 50,
+              hooks: ['beforeExecute', 'afterExecute'],
+            })}
+          </div>
+        </div>
+      </PageBody>
+    </Page>
+  )
+}

package/template/src/modules/example/commands/interceptors.ts

@@ -0,0 +1,33 @@
+import type { CommandInterceptor } from '@open-mercato/shared/lib/commands/command-interceptor'
+
+/**
+ * Example command interceptor: audit logging for customer commands.
+ *
+ * Demonstrates the command interceptor contract (m4): beforeExecute stores
+ * a timestamp in metadata, afterExecute logs the duration.
+ */
+const auditLoggingInterceptor: CommandInterceptor = {
+  id: 'example.audit-logging',
+  targetCommand: 'customers.*',
+  priority: 50,
+
+  async beforeExecute(_input, _context) {
+    return {
+      ok: true,
+      metadata: { auditStartedAt: Date.now() },
+    }
+  },
+
+  async afterExecute(_input, _result, context) {
+    const startedAt = context.metadata?.auditStartedAt as number | undefined
+    if (startedAt) {
+      const duration = Date.now() - startedAt
+      // eslint-disable-next-line no-console
+      console.log(
+        `[example:audit] Command ${context.commandId} completed in ${duration}ms`,
+      )
+    }
+  },
+}
+
+export const interceptors: CommandInterceptor[] = [auditLoggingInterceptor]

package/template/src/modules/example/data/guards.ts

@@ -0,0 +1,30 @@
+import type { MutationGuard } from '@open-mercato/shared/lib/crud/mutation-guard-registry'
+
+/**
+ * Example mutation guard: limits the number of active todos per tenant.
+ *
+ * Demonstrates the guard contract — runs on `create` operations for `example.todo`.
+ * The guard checks a simple policy before allowing the mutation to proceed.
+ */
+const todoLimitGuard: MutationGuard = {
+  id: 'example.todo-limit',
+  targetEntity: 'example.todo',
+  operations: ['create'],
+  priority: 50,
+
+  async validate(input) {
+    // Guard validates at the request level — business rules can check
+    // organizational limits, feature flags, or other policy constraints.
+    // For demonstration, we simply allow the operation.
+    if (!input.organizationId) {
+      return {
+        ok: false,
+        message: 'Organization is required to create todos',
+        status: 422,
+      }
+    }
+    return { ok: true }
+  },
+}
+
+export const guards: MutationGuard[] = [todoLimitGuard]

package/template/src/modules/example/subscribers/audit-delete.ts

@@ -0,0 +1,24 @@
+import type { SyncCrudEventPayload } from '@open-mercato/shared/lib/crud/sync-event-types'
+
+/**
+ * Sync after-delete subscriber: logs a deletion audit trail.
+ *
+ * Fires after a todo has been deleted. After-event subscribers cannot block
+ * the operation — errors are swallowed with console.error. Demonstrates
+ * the sync after-event contract (m2).
+ */
+export const metadata = {
+  event: 'example.todo.deleted',
+  sync: true,
+  priority: 50,
+  id: 'example:audit-delete',
+}
+
+export default async function handler(
+  payload: SyncCrudEventPayload,
+): Promise<void> {
+  // eslint-disable-next-line no-console
+  console.log(
+    `[example:audit-delete] Todo ${payload.resourceId} deleted by user ${payload.userId} in org ${payload.organizationId}`,
+  )
+}

package/template/src/modules/example/subscribers/auto-default-priority.ts

@@ -0,0 +1,27 @@
+import type { SyncCrudEventPayload, SyncCrudEventResult } from '@open-mercato/shared/lib/crud/sync-event-types'
+
+/**
+ * Sync before-create subscriber: sets a default priority on new todos.
+ *
+ * When creating a todo without an explicit `priority` field, this subscriber
+ * injects `priority: 'normal'` into the payload. Demonstrates the sync
+ * before-event contract (m2).
+ */
+export const metadata = {
+  event: 'example.todo.creating',
+  sync: true,
+  priority: 50,
+  id: 'example:auto-default-priority',
+}
+
+export default async function handler(
+  payload: SyncCrudEventPayload,
+): Promise<SyncCrudEventResult | void> {
+  const body = payload.payload
+  if (body && typeof body === 'object' && !('priority' in body)) {
+    return {
+      ok: true,
+      modifiedPayload: { ...body, priority: 'normal' },
+    }
+  }
+}

package/template/src/modules/example/subscribers/prevent-uncomplete.ts

@@ -0,0 +1,35 @@
+import type { SyncCrudEventPayload, SyncCrudEventResult } from '@open-mercato/shared/lib/crud/sync-event-types'
+
+/**
+ * Sync before-update subscriber: prevents reverting a completed todo.
+ *
+ * Once a todo is marked as done, this subscriber blocks any attempt to set
+ * `isDone` back to `false`. Demonstrates the sync before-event rejection
+ * contract (m2).
+ */
+export const metadata = {
+  event: 'example.todo.updating',
+  sync: true,
+  priority: 60,
+  id: 'example:prevent-uncomplete',
+}
+
+export default async function handler(
+  payload: SyncCrudEventPayload,
+): Promise<SyncCrudEventResult | void> {
+  const body = payload.payload
+  const previous = payload.previousData
+
+  if (!previous || !body || typeof body !== 'object') return
+
+  const wasDone = previous.isDone === true || previous.is_done === true
+  const wantUndone = ('isDone' in body && body.isDone === false) || ('is_done' in body && body.is_done === false)
+
+  if (wasDone && wantUndone) {
+    return {
+      ok: false,
+      message: 'Completed todos cannot be reverted to pending',
+      status: 422,
+    }
+  }
+}