@open-mercato/shared 0.6.5-develop.4463.1.4c4698f8f8 → 0.6.5-develop.4476.1.644044a657

package/AGENTS.md

@@ -121,6 +121,15 @@ import { hasFeature, hasAllFeatures } from '@open-mercato/shared/security/featur
 - Use `parseIdsParam()` and `mergeIdFilter()` from `@open-mercato/shared/lib/crud/ids` for factory-level `ids` query support.
 - Keep `ids` format as comma-separated UUIDs (`?ids=uuid1,uuid2`) and intersect with existing `id` filters.
 
+### Command Undo Pattern — read the snapshot via `extractUndoPayload`
+
+A command's `buildLog()` returns `payload: { undo: { before, after } }`, but the command bus persists that under `commandPayload` (column `command_payload`, wrapped in a redo envelope) — **the stored `ActionLog` row has no top-level `payload`**. Reading `logEntry.payload` inside an `undo()` handler is therefore always `undefined`, which makes undo a silent no-op (issue #2504).
+
+MUST rules:
+- Inside `undo()`, read the snapshot **only** through `extractUndoPayload<UndoPayload<TSnapshot>>(logEntry)` from `@open-mercato/shared/lib/commands/undo`. It unwraps `commandPayload` (and the redo envelope) and falls back to `snapshotBefore`/`snapshotAfter`.
+- NEVER access `logEntry.payload` in an undo handler. The `logEntry` parameter is typed as `CommandUndoLogEntry`, which intentionally omits `payload` so this footgun is a compile-time error.
+- Delete-undo should be robust to either deletion strategy: clear `deletedAt` when the row survives (soft delete), otherwise re-create the entity from the snapshot (mirror `packages/core/src/modules/sales/commands/configuration.ts`).
+
 ### Module-Level Overrides (`@open-mercato/shared/modules/overrides`)
 
 Downstream apps replace or disable any contract a module presents through a single `entry.overrides` field on a `ModuleEntry`. The umbrella spec is `.ai/specs/2026-05-04-modules-ts-unified-overrides.md`; phases 1-18 are wired.

package/dist/lib/commands/types.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/lib/commands/types.ts"],
-  "sourcesContent": ["import type { AwilixContainer } from 'awilix'\nimport type { EntityManager } from '@mikro-orm/postgresql'\nimport { randomUUID } from 'crypto'\nimport type { AuthContext } from '../auth/server'\nimport type { OrganizationScope } from '@open-mercato/core/modules/directory/utils/organizationScope'\n\nexport type CommandRuntimeContext = {\n  container: AwilixContainer\n  auth: AuthContext | null\n  organizationScope: OrganizationScope | null\n  selectedOrganizationId: string | null\n  organizationIds: string[] | null\n  request?: Request\n  syncOrigin?: string | null\n  /**\n   * Marks a trusted server-side invocation (CLI seeding, tenant setup) that runs\n   * without an authenticated end-user actor. Commands that gate writes behind a\n   * privileged actor (e.g. super-admin-only platform tables) may treat this as\n   * an explicit system grant. HTTP request paths MUST NOT set this \u2014 they always\n   * carry a real `auth` actor, so a present-but-unprivileged actor stays denied.\n   */\n  systemActor?: boolean\n  /**\n   * When set, command handlers that support it MUST run their writes within this\n   * existing transactional EntityManager (reusing its row locks) instead of\n   * opening their own transaction. Lets a caller compose a command with its own\n   * surrounding work as a single atomic, single-locked operation.\n   */\n  transactionalEm?: EntityManager\n}\n\nexport type CommandLogMetadata = {\n  skipLog?: boolean\n  tenantId?: string | null\n  organizationId?: string | null\n  actorUserId?: string | null\n  actionLabel?: string | null\n  resourceKind?: string | null\n  resourceId?: string | null\n  parentResourceKind?: string | null\n  parentResourceId?: string | null\n  undoToken?: string | null\n  payload?: unknown\n  snapshotBefore?: unknown\n  snapshotAfter?: unknown\n  relatedResourceKind?: string | null\n  relatedResourceId?: string | null\n  changes?: Record<string, unknown> | null\n  context?: Record<string, unknown> | null\n}\n\nexport type CommandExecuteResult<TResult> = {\n  result: TResult\n  logEntry: any | null\n}\n\nexport type CommandLogBuilderArgs<TInput, TResult> = {\n  input: TInput\n  result: TResult\n  ctx: CommandRuntimeContext\n  snapshots: {\n    before?: unknown\n    after?: unknown\n  }\n}\n\nexport interface CommandHandler<TInput = unknown, TResult = unknown> {\n  readonly id: string\n  readonly isUndoable?: boolean\n  prepare?(input: TInput, ctx: CommandRuntimeContext): Promise<{ before?: unknown } | null> | { before?: unknown } | null\n  execute(input: TInput, ctx: CommandRuntimeContext): Promise<TResult> | TResult\n  buildLog?(args: CommandLogBuilderArgs<TInput, TResult>): Promise<CommandLogMetadata | null | undefined> | CommandLogMetadata | null | undefined\n  captureAfter?(input: TInput, result: TResult, ctx: CommandRuntimeContext): Promise<unknown> | unknown\n  undo?(params: { input: TInput; ctx: CommandRuntimeContext; logEntry: any }): Promise<void> | void\n}\n\nexport type CommandExecutionOptions<TInput> = {\n  input: TInput\n  ctx: CommandRuntimeContext\n  metadata?: CommandLogMetadata | null\n  skipCacheInvalidation?: boolean\n}\n\nexport function defaultUndoToken(): string {\n  return randomUUID()\n}\n"],
-  "mappings": "AAEA,SAAS,kBAAkB;AAiFpB,SAAS,mBAA2B;AACzC,SAAO,WAAW;AACpB;",
+  "sourcesContent": ["import type { AwilixContainer } from 'awilix'\nimport type { EntityManager } from '@mikro-orm/postgresql'\nimport { randomUUID } from 'crypto'\nimport type { AuthContext } from '../auth/server'\nimport type { OrganizationScope } from '@open-mercato/core/modules/directory/utils/organizationScope'\n\nexport type CommandRuntimeContext = {\n  container: AwilixContainer\n  auth: AuthContext | null\n  organizationScope: OrganizationScope | null\n  selectedOrganizationId: string | null\n  organizationIds: string[] | null\n  request?: Request\n  syncOrigin?: string | null\n  /**\n   * Marks a trusted server-side invocation (CLI seeding, tenant setup) that runs\n   * without an authenticated end-user actor. Commands that gate writes behind a\n   * privileged actor (e.g. super-admin-only platform tables) may treat this as\n   * an explicit system grant. HTTP request paths MUST NOT set this \u2014 they always\n   * carry a real `auth` actor, so a present-but-unprivileged actor stays denied.\n   */\n  systemActor?: boolean\n  /**\n   * When set, command handlers that support it MUST run their writes within this\n   * existing transactional EntityManager (reusing its row locks) instead of\n   * opening their own transaction. Lets a caller compose a command with its own\n   * surrounding work as a single atomic, single-locked operation.\n   */\n  transactionalEm?: EntityManager\n}\n\nexport type CommandLogMetadata = {\n  skipLog?: boolean\n  tenantId?: string | null\n  organizationId?: string | null\n  actorUserId?: string | null\n  actionLabel?: string | null\n  resourceKind?: string | null\n  resourceId?: string | null\n  parentResourceKind?: string | null\n  parentResourceId?: string | null\n  undoToken?: string | null\n  payload?: unknown\n  snapshotBefore?: unknown\n  snapshotAfter?: unknown\n  relatedResourceKind?: string | null\n  relatedResourceId?: string | null\n  changes?: Record<string, unknown> | null\n  context?: Record<string, unknown> | null\n}\n\nexport type CommandExecuteResult<TResult> = {\n  result: TResult\n  logEntry: any | null\n}\n\n/**\n * Shape of the persisted action log handed to a command's `undo()` handler.\n *\n * IMPORTANT: there is intentionally **no `payload` field**. `buildLog()` returns\n * a `payload` in its metadata, but the command bus persists that under\n * `commandPayload` (column `command_payload`, wrapped in a redo envelope) \u2014 the\n * stored row never has a top-level `payload`. Reading `logEntry.payload` in an\n * undo handler is therefore always `undefined` and silently no-ops the undo\n * (issue #2504). Always read the undo snapshot through\n * `extractUndoPayload(logEntry)` from `@open-mercato/shared/lib/commands/undo`,\n * which unwraps `commandPayload`/snapshots correctly. Omitting `payload` here\n * makes the footgun a compile-time error instead of a runtime silent failure.\n */\nexport type CommandUndoLogEntry = {\n  id?: string\n  commandId?: string\n  commandPayload?: unknown | null\n  snapshotBefore?: unknown | null\n  snapshotAfter?: unknown | null\n  resourceKind?: string | null\n  resourceId?: string | null\n  undoToken?: string | null\n  actionLabel?: string | null\n  tenantId?: string | null\n  organizationId?: string | null\n  actorUserId?: string | null\n  changesJson?: Record<string, unknown> | null\n  contextJson?: Record<string, unknown> | null\n  createdAt?: Date | string\n  updatedAt?: Date | string\n}\n\nexport type CommandLogBuilderArgs<TInput, TResult> = {\n  input: TInput\n  result: TResult\n  ctx: CommandRuntimeContext\n  snapshots: {\n    before?: unknown\n    after?: unknown\n  }\n}\n\nexport interface CommandHandler<TInput = unknown, TResult = unknown> {\n  readonly id: string\n  readonly isUndoable?: boolean\n  prepare?(input: TInput, ctx: CommandRuntimeContext): Promise<{ before?: unknown } | null> | { before?: unknown } | null\n  execute(input: TInput, ctx: CommandRuntimeContext): Promise<TResult> | TResult\n  buildLog?(args: CommandLogBuilderArgs<TInput, TResult>): Promise<CommandLogMetadata | null | undefined> | CommandLogMetadata | null | undefined\n  captureAfter?(input: TInput, result: TResult, ctx: CommandRuntimeContext): Promise<unknown> | unknown\n  undo?(params: { input: TInput; ctx: CommandRuntimeContext; logEntry: CommandUndoLogEntry }): Promise<void> | void\n}\n\nexport type CommandExecutionOptions<TInput> = {\n  input: TInput\n  ctx: CommandRuntimeContext\n  metadata?: CommandLogMetadata | null\n  skipCacheInvalidation?: boolean\n}\n\nexport function defaultUndoToken(): string {\n  return randomUUID()\n}\n"],
+  "mappings": "AAEA,SAAS,kBAAkB;AAiHpB,SAAS,mBAA2B;AACzC,SAAO,WAAW;AACpB;",
   "names": []
 }

package/dist/lib/version.js

@@ -1,4 +1,4 @@
-const APP_VERSION = "0.6.5-develop.4463.1.4c4698f8f8";
+const APP_VERSION = "0.6.5-develop.4476.1.644044a657";
 const appVersion = APP_VERSION;
 export {
   APP_VERSION,

package/dist/lib/version.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/lib/version.ts"],
-  "sourcesContent": ["// Build-time generated version\nexport const APP_VERSION = '0.6.5-develop.4463.1.4c4698f8f8'\nexport const appVersion = APP_VERSION\n"],
+  "sourcesContent": ["// Build-time generated version\nexport const APP_VERSION = '0.6.5-develop.4476.1.644044a657'\nexport const appVersion = APP_VERSION\n"],
   "mappings": "AACO,MAAM,cAAc;AACpB,MAAM,aAAa;",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/shared",
-  "version": "0.6.5-develop.4463.1.4c4698f8f8",
+  "version": "0.6.5-develop.4476.1.644044a657",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
@@ -92,7 +92,7 @@
     "@mikro-orm/core": "^7.1.3",
     "@mikro-orm/decorators": "^7.1.3",
     "@mikro-orm/postgresql": "^7.1.3",
-    "@open-mercato/cache": "0.6.5-develop.4463.1.4c4698f8f8",
+    "@open-mercato/cache": "0.6.5-develop.4476.1.644044a657",
     "dotenv": "^17.4.2",
     "rate-limiter-flexible": "^11.1.0",
     "re2js": "2.8.3",

package/src/lib/commands/types.ts

@@ -54,6 +54,38 @@ export type CommandExecuteResult<TResult> = {
   logEntry: any | null
 }
 
+/**
+ * Shape of the persisted action log handed to a command's `undo()` handler.
+ *
+ * IMPORTANT: there is intentionally **no `payload` field**. `buildLog()` returns
+ * a `payload` in its metadata, but the command bus persists that under
+ * `commandPayload` (column `command_payload`, wrapped in a redo envelope) — the
+ * stored row never has a top-level `payload`. Reading `logEntry.payload` in an
+ * undo handler is therefore always `undefined` and silently no-ops the undo
+ * (issue #2504). Always read the undo snapshot through
+ * `extractUndoPayload(logEntry)` from `@open-mercato/shared/lib/commands/undo`,
+ * which unwraps `commandPayload`/snapshots correctly. Omitting `payload` here
+ * makes the footgun a compile-time error instead of a runtime silent failure.
+ */
+export type CommandUndoLogEntry = {
+  id?: string
+  commandId?: string
+  commandPayload?: unknown | null
+  snapshotBefore?: unknown | null
+  snapshotAfter?: unknown | null
+  resourceKind?: string | null
+  resourceId?: string | null
+  undoToken?: string | null
+  actionLabel?: string | null
+  tenantId?: string | null
+  organizationId?: string | null
+  actorUserId?: string | null
+  changesJson?: Record<string, unknown> | null
+  contextJson?: Record<string, unknown> | null
+  createdAt?: Date | string
+  updatedAt?: Date | string
+}
+
 export type CommandLogBuilderArgs<TInput, TResult> = {
   input: TInput
   result: TResult
@@ -71,7 +103,7 @@ export interface CommandHandler<TInput = unknown, TResult = unknown> {
   execute(input: TInput, ctx: CommandRuntimeContext): Promise<TResult> | TResult
   buildLog?(args: CommandLogBuilderArgs<TInput, TResult>): Promise<CommandLogMetadata | null | undefined> | CommandLogMetadata | null | undefined
   captureAfter?(input: TInput, result: TResult, ctx: CommandRuntimeContext): Promise<unknown> | unknown
-  undo?(params: { input: TInput; ctx: CommandRuntimeContext; logEntry: any }): Promise<void> | void
+  undo?(params: { input: TInput; ctx: CommandRuntimeContext; logEntry: CommandUndoLogEntry }): Promise<void> | void
 }
 
 export type CommandExecutionOptions<TInput> = {