@open-mercato/shared 0.10.1-develop.7576.1.21d5b50435 → 0.10.1-develop.7577.1.477f2486e5

package/src/lib/catalog-visibility/canonicalizeEffectiveScope.ts

@@ -0,0 +1,41 @@
+import type { AssortmentScope, EffectiveAssortmentScope } from './types'
+
+const ID_LIST_KEYS = [
+  'categoryIds',
+  'excludeCategoryIds',
+  'excludeProductIds',
+  'excludeTagIds',
+  'tagIds',
+] as const
+
+function compareStrings(left: string, right: string): number {
+  if (left < right) return -1
+  if (left > right) return 1
+  return 0
+}
+
+function sortedUnique(values: string[]): string[] {
+  return Array.from(new Set(values)).sort(compareStrings)
+}
+
+function canonicalizeBranch(scope: AssortmentScope): string {
+  const members: string[] = []
+  const nested = (scope.allOf ?? []).map(canonicalizeBranch)
+  if (nested.length > 0) members.push(`"allOf":[${sortedUnique(nested).join(',')}]`)
+  for (const key of ID_LIST_KEYS) {
+    const ids = scope[key] ?? []
+    if (ids.length > 0) members.push(`${JSON.stringify(key)}:${JSON.stringify(sortedUnique(ids))}`)
+  }
+  return `{${members.join(',')}}`
+}
+
+/**
+ * Deterministic serialization of a resolved scope. `null` (unrestricted) serializes as `null`
+ * and `[]` (deny-all) as `[]`, so the two never collide. Empty and absent arrays are
+ * equivalent, id lists are sorted and deduplicated, and OR-branches and `allOf` entries are
+ * ordered by their own canonical form with identical ones collapsed.
+ */
+export function canonicalizeEffectiveScope(scope: EffectiveAssortmentScope): string {
+  if (scope === null) return 'null'
+  return `[${sortedUnique(scope.map(canonicalizeBranch)).join(',')}]`
+}

package/src/lib/catalog-visibility/hashEffectiveScope.ts

@@ -0,0 +1,8 @@
+import { createHash } from 'node:crypto'
+import { canonicalizeEffectiveScope } from './canonicalizeEffectiveScope'
+import type { EffectiveAssortmentScope } from './types'
+
+/** 16-hex-character sha256 digest of the canonical scope (SPEC-029 §6.1 truncation). Server-only: uses node:crypto. */
+export function hashEffectiveScope(scope: EffectiveAssortmentScope): string {
+  return createHash('sha256').update(canonicalizeEffectiveScope(scope)).digest('hex').slice(0, 16)
+}

package/src/lib/catalog-visibility/index.ts

@@ -3,3 +3,5 @@ export { matchesOne } from './matchesOne'
 export { matchesScope } from './matchesScope'
 export { unionScopes } from './unionScopes'
 export { intersectScopes } from './intersectScopes'
+export { canonicalizeEffectiveScope } from './canonicalizeEffectiveScope'
+export { hashEffectiveScope } from './hashEffectiveScope'

package/src/lib/commands/__tests__/command-bus.test.ts

@@ -7,7 +7,7 @@ import {
   isCommandInterceptorError,
 } from '@open-mercato/shared/lib/commands'
 import { registerCommandInterceptors } from '@open-mercato/shared/lib/commands/command-interceptor-store'
-import type { CommandInterceptor } from '@open-mercato/shared/lib/commands/command-interceptor'
+import type { CommandInterceptor, CommandInterceptorContext } from '@open-mercato/shared/lib/commands/command-interceptor'
 
 describe('CommandBus', () => {
   afterEach(() => {
@@ -296,6 +296,57 @@ describe('CommandBus', () => {
     )
   })
 
+  it('defers opted-in before snapshots until after the transactional write guard', async () => {
+    const calls: string[] = []
+    const transactionalEm = { id: 'transaction-em' }
+    const buildLogMock = jest.fn(() => ({
+      actionLabel: 'Transaction snapshot',
+      resourceKind: 'test',
+      resourceId: 'transactional',
+    }))
+    const prepare = jest.fn(async (_input, ctx) => {
+      calls.push('prepare')
+      expect(ctx.transactionalEm).toBe(transactionalEm)
+      return { before: { state: 'locked-before' } }
+    })
+
+    registerCommand({
+      id: 'test.command.transactional-snapshot',
+      prepare,
+      prepareSnapshotInsideTransaction: true,
+      execute: jest.fn(async (_input, ctx) => {
+        calls.push('execute')
+        await ctx.beforeTransactionalWrite?.(transactionalEm as never)
+        calls.push('mutate')
+        return { ok: true }
+      }),
+      buildLog: buildLogMock,
+    })
+
+    const logMock = jest.fn(async () => ({ id: 'transaction-log' }))
+    const container = createContainer({ injectionMode: InjectionMode.CLASSIC })
+    container.register({ actionLogService: asValue({ log: logMock }) })
+    const bus = new CommandBus()
+    const ctx = {
+      container,
+      auth: { sub: 'user-transaction', tenantId: 'tenant-transaction', orgId: null },
+      organizationScope: null,
+      selectedOrganizationId: null,
+      organizationIds: null,
+      beforeTransactionalWrite: jest.fn(async () => {
+        calls.push('lock')
+      }),
+    }
+
+    await bus.execute('test.command.transactional-snapshot', { input: {}, ctx })
+
+    expect(calls).toEqual(['execute', 'lock', 'prepare', 'mutate'])
+    expect(prepare).toHaveBeenCalledTimes(1)
+    expect(buildLogMock).toHaveBeenCalledWith(expect.objectContaining({
+      snapshots: { before: { state: 'locked-before' }, after: undefined },
+    }))
+  })
+
   it('loads a command file lazily before execution', async () => {
     const execute = jest.fn(async () => ({ ok: true }))
     registerCommandLoaders([
@@ -538,6 +589,54 @@ describe('CommandBus', () => {
   })
 
   describe('interceptor rejections', () => {
+    it('passes the original request to beforeExecute for preflight version checks', async () => {
+      registerCommand({ id: 'test.request-context', execute: jest.fn(async () => ({ ok: true })) })
+      const beforeExecute = jest.fn(async (_input: unknown, context: { request?: Request | null }) => {
+        expect(context.request?.headers.get('x-om-ext-optimistic-lock-expected-updated-at')).toBe('2026-09-29T11:00:00.000Z')
+        return { ok: false, status: 422 }
+      })
+      registerCommandInterceptors([{ moduleId: 'test', interceptors: [{
+        id: 'test.request-context-interceptor', targetCommand: 'test.request-context', beforeExecute,
+      }] }])
+      const request = new Request('http://localhost/test', { headers: { 'x-om-ext-optimistic-lock-expected-updated-at': '2026-09-29T11:00:00.000Z' } })
+      const container = createContainer({ injectionMode: InjectionMode.CLASSIC })
+      const bus = new CommandBus()
+      await expect(bus.execute('test.request-context', { input: {}, ctx: {
+        container,
+        auth: { sub: 'user-1', tenantId: 'tenant-1', orgId: null },
+        organizationScope: null,
+        selectedOrganizationId: null,
+        organizationIds: null,
+        request,
+      } })).rejects.toMatchObject({ status: 422 })
+      expect(beforeExecute).toHaveBeenCalledTimes(1)
+    })
+
+    it('passes request and organization scope to both execution lifecycle hooks', async () => {
+      registerCommand({ id: 'test.lifecycle-context', execute: async () => ({ ok: true }) })
+      const request = new Request('http://localhost/test')
+      const organizationScope = { selectedId: 'parent', filterIds: ['parent', 'child'], allowedIds: ['parent', 'child'], tenantId: 'tenant-1' }
+      const beforeExecute = jest.fn(async (_input: unknown, context: CommandInterceptorContext) => {
+        expect(context.request).toBe(request)
+        expect(context.organizationScope).toBe(organizationScope)
+        return { ok: true }
+      })
+      const afterExecute = jest.fn(async (_input: unknown, _result: unknown, context: CommandInterceptorContext) => {
+        expect(context.request).toBe(request)
+        expect(context.organizationScope).toBe(organizationScope)
+      })
+      registerCommandInterceptors([{ moduleId: 'test', interceptors: [{
+        id: 'test.lifecycle-context-interceptor', targetCommand: 'test.lifecycle-context', beforeExecute, afterExecute,
+      }] }])
+      await new CommandBus().execute('test.lifecycle-context', { input: {}, ctx: {
+        container: createContainer({ injectionMode: InjectionMode.CLASSIC }),
+        auth: { sub: 'user-1', tenantId: 'tenant-1', orgId: 'parent' },
+        organizationScope, selectedOrganizationId: 'parent', organizationIds: ['parent', 'child'], request,
+      } })
+      expect(beforeExecute).toHaveBeenCalledTimes(1)
+      expect(afterExecute).toHaveBeenCalledTimes(1)
+    })
+
     const blockingInterceptor = (result: Record<string, unknown>): CommandInterceptor => ({
       id: 'test.block',
       targetCommand: 'test.*',

package/src/lib/commands/command-bus.ts

@@ -297,6 +297,8 @@ export class CommandBus {
         auth: baseOptions.ctx.auth ?? null,
         selectedOrganizationId: baseOptions.ctx.selectedOrganizationId ?? baseOptions.ctx.auth?.orgId ?? null,
         container: baseOptions.ctx.container,
+        organizationScope: baseOptions.ctx.organizationScope ?? null,
+        request: baseOptions.ctx.request ?? null,
       }
       const beforeResult = await runCommandInterceptorsBefore(
         allInterceptors, commandId, baseOptions.input, interceptorCtx, resolvedUserFeatures,
@@ -338,16 +340,40 @@ export class CommandBus {
     }
 
     const executeCore = async (coreOptions: CommandExecutionOptions<TInput>) => {
-      const sourceLog = coreOptions.redoLogEntry ?? null
-      const snapshots = await this.prepareSnapshots(handler, coreOptions)
+      const snapshots: { before?: unknown } = {}
+      let executionOptions = coreOptions
+      if (handler.prepareSnapshotInsideTransaction && handler.prepare) {
+        const prepare = handler.prepare
+        const originalCtx = coreOptions.ctx
+        const originalBeforeTransactionalWrite = originalCtx.beforeTransactionalWrite
+        let prepared = false
+        let transactionalCtx: CommandRuntimeContext
+        transactionalCtx = {
+          ...originalCtx,
+          beforeTransactionalWrite: async (em, input) => {
+            await originalBeforeTransactionalWrite?.(em, input)
+            if (prepared) return
+            Object.assign(
+              snapshots,
+              (await prepare(coreOptions.input, { ...transactionalCtx, transactionalEm: em })) ?? {},
+            )
+            prepared = true
+          },
+        }
+        executionOptions = { ...coreOptions, ctx: transactionalCtx }
+      } else {
+        Object.assign(snapshots, await this.prepareSnapshots(handler, coreOptions))
+      }
+      effectiveOptions = executionOptions
+      const sourceLog = executionOptions.redoLogEntry ?? null
       const result =
         sourceLog && typeof handler.redo === 'function'
-          ? await handler.redo({ input: coreOptions.input, ctx: coreOptions.ctx, logEntry: sourceLog })
-          : await handler.execute(coreOptions.input, coreOptions.ctx)
-      const afterSnapshot = await this.captureAfter(handler, coreOptions, result)
+          ? await handler.redo({ input: executionOptions.input, ctx: executionOptions.ctx, logEntry: sourceLog })
+          : await handler.execute(executionOptions.input, executionOptions.ctx)
+      const afterSnapshot = await this.captureAfter(handler, executionOptions, result)
       const snapshotsWithAfter = { ...snapshots, after: afterSnapshot }
-      const logMeta = await this.buildLog(handler, coreOptions, result, snapshotsWithAfter)
-      let mergedMeta = this.mergeMetadata(coreOptions.metadata, logMeta)
+      const logMeta = await this.buildLog(handler, executionOptions, result, snapshotsWithAfter)
+      let mergedMeta = this.mergeMetadata(executionOptions.metadata, logMeta)
       // Interceptors opt into audit-log enrichment with a reserved `logContext` key rather
       // than the generic `context` one, so the metadata an interceptor already passes to its
       // own afterExecute hook is never silently promoted into audit storage.
@@ -362,7 +388,7 @@ export class CommandBus {
           ...logContextRecord,
         }
       }
-      const baseContext = asRecord(coreOptions.metadata?.context) ?? {}
+      const baseContext = asRecord(executionOptions.metadata?.context) ?? {}
       const logMetaContext = asRecord(logMeta?.context) ?? {}
       if (Object.keys(interceptorContextMerged).length > 0 || Object.keys(baseContext).length > 0 || Object.keys(logMetaContext).length > 0) {
         mergedMeta = mergedMeta ?? {}
@@ -376,7 +402,7 @@ export class CommandBus {
       if (undoable && mergedMeta?.replayable !== false) {
         mergedMeta = mergedMeta ?? {}
         if (!mergedMeta.undoToken) mergedMeta.undoToken = defaultUndoToken()
-        if (mergedMeta.actorUserId === undefined) mergedMeta.actorUserId = coreOptions.ctx.auth?.sub ?? null
+        if (mergedMeta.actorUserId === undefined) mergedMeta.actorUserId = executionOptions.ctx.auth?.sub ?? null
       } else if (mergedMeta?.replayable === false) {
         mergedMeta.undoToken = null
       }
@@ -405,7 +431,7 @@ export class CommandBus {
           if (inferred) mergedMeta.changes = inferred
         }
       }
-      const logEntry = await this.persistLog(commandId, coreOptions, mergedMeta)
+      const logEntry = await this.persistLog(commandId, executionOptions, mergedMeta)
       return { result, mergedMeta, logEntry }
     }
 
@@ -474,6 +500,8 @@ export class CommandBus {
           auth: effectiveOptions.ctx.auth ?? null,
           selectedOrganizationId: effectiveOptions.ctx.selectedOrganizationId ?? effectiveOptions.ctx.auth?.orgId ?? null,
           container: effectiveOptions.ctx.container,
+          organizationScope: effectiveOptions.ctx.organizationScope ?? null,
+          request: effectiveOptions.ctx.request ?? null,
         }
         const afterResult = await runCommandInterceptorsAfter(
           allInterceptors, commandId, effectiveOptions.input, result, interceptorCtx,
@@ -545,6 +573,8 @@ export class CommandBus {
         auth: replayCtx.auth ?? null,
         selectedOrganizationId: replayCtx.selectedOrganizationId ?? replayCtx.auth?.orgId ?? null,
         container: replayCtx.container,
+        organizationScope: replayCtx.organizationScope ?? null,
+        request: replayCtx.request ?? null,
       }
       const beforeResult = await runCommandInterceptorsBeforeUndo(
         allInterceptors, log.commandId, undoCtx, interceptorCtx, resolvedUserFeatures,
@@ -659,6 +689,8 @@ export class CommandBus {
           auth: ctx.auth ?? null,
           selectedOrganizationId: ctx.selectedOrganizationId ?? ctx.auth?.orgId ?? null,
           container: ctx.container,
+          organizationScope: ctx.organizationScope ?? null,
+          request: ctx.request ?? null,
         }
         await runCommandInterceptorsAfterUndo(
           allInterceptors, log.commandId, undoCtx, interceptorCtx,

package/src/lib/commands/command-interceptor.ts

@@ -1,4 +1,5 @@
 import type { AwilixContainer } from 'awilix'
+import type { OrganizationScope } from '@open-mercato/shared/lib/auth/principal-service'
 import type { AuthContext } from '@open-mercato/shared/lib/auth/server'
 
 export interface CommandInterceptor {
@@ -47,8 +48,11 @@ export interface CommandInterceptorContext {
   auth: AuthContext | null
   /** Selected organization ID */
   selectedOrganizationId: string | null
+  organizationScope?: OrganizationScope | null
   /** DI container (read-only usage recommended) */
   container: AwilixContainer
+  /** Original request, when the command was called through HTTP. */
+  request?: Request | null
   /** Metadata passthrough from beforeExecute to afterExecute (or beforeUndo to afterUndo) */
   metadata?: Record<string, unknown>
 }

package/src/lib/commands/types.ts

@@ -67,6 +67,14 @@ export type CommandRuntimeContext = {
    * surrounding work as a single atomic, single-locked operation.
    */
   transactionalEm?: EntityManager
+  /**
+   * Optional server-side guard that supported command handlers invoke after
+   * opening their write transaction and before reading or mutating records.
+   * The guard receives that same transaction-bound EntityManager and, when the
+   * handler provides it, the final input after command interceptors. The input
+   * stays optional so existing handlers and callers remain source-compatible.
+   */
+  beforeTransactionalWrite?: (em: EntityManager, input?: unknown) => Promise<void>
   /**
    * Identifies the owner of an already-active {@link transactionalEm} lifetime.
    * Atomic replay accepts an ambient EntityManager only when this is the exact
@@ -243,6 +251,12 @@ export interface CommandHandler<TInput = unknown, TResult = unknown> {
    */
   readonly outputSchema?: ZodTypeAny
   prepare?(input: TInput, ctx: CommandRuntimeContext): Promise<{ before?: unknown } | null> | { before?: unknown } | null
+  /**
+   * Opt in to taking the undo snapshot inside the write transaction. The bus
+   * defers `prepare()` into `ctx.beforeTransactionalWrite`, after the handler's
+   * transaction guard and before its first read or mutation.
+   */
+  readonly prepareSnapshotInsideTransaction?: boolean
   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

package/src/lib/crud/__tests__/exporters.test.ts

@@ -28,4 +28,22 @@ describe('CRUD export serializers', () => {
       '"\'\t=HYPERLINK(""https://example.invalid"")","\'\r+1+1",\'-7',
     ])
   })
+
+  it('escapes and neutralizes CSV header cells the same way as data cells', () => {
+    const serialized = serializeExport({
+      columns: [
+        { field: 'company', header: 'Name, Inc.' },
+        { field: 'formula', header: '=HEADER' },
+        { field: 'plain', header: 'Balance' },
+      ],
+      rows: [
+        { company: 'Acme', formula: 'ok', plain: 1 },
+      ],
+    }, 'csv')
+
+    expect(serialized.body.split('\n')).toEqual([
+      '"Name, Inc.",\'=HEADER,Balance',
+      'Acme,ok,1',
+    ])
+  })
 })

package/src/lib/crud/__tests__/ids.test.ts

@@ -1,4 +1,11 @@
-import { MAX_IDS_PER_REQUEST, mergeIdFilter, parseIdsParam, isIdsParamProvided } from '@open-mercato/shared/lib/crud/ids'
+import {
+  MAX_IDS_PER_REQUEST,
+  mergeIdFilter,
+  parseIdsParam,
+  isIdsParamProvided,
+  isUuidListParam,
+  splitIdListParam,
+} from '@open-mercato/shared/lib/crud/ids'
 
 describe('crud ids helpers', () => {
   const idA = '550e8400-e29b-41d4-a716-446655440001'
@@ -168,4 +175,30 @@ describe('crud ids helpers', () => {
       tenantId: 't1',
     })
   })
+
+  it('splitIdListParam trims entries and drops empty ones', () => {
+    expect(splitIdListParam(` ${idA} ,, ${idB} ,`)).toEqual([idA, idB])
+    expect(splitIdListParam(undefined)).toEqual([])
+    expect(splitIdListParam(['not', 'a', 'string'])).toEqual([])
+  })
+
+  it('isUuidListParam accepts absent, empty, and all-UUID lists', () => {
+    expect(isUuidListParam(undefined)).toBe(true)
+    expect(isUuidListParam('')).toBe(true)
+    expect(isUuidListParam(` ${idA}, ${idB.toUpperCase()} `)).toBe(true)
+    expect(isUuidListParam('00000000-0000-0000-0000-000000000000')).toBe(true)
+  })
+
+  it('isUuidListParam rejects malformed and mixed lists', () => {
+    expect(isUuidListParam('not-a-uuid')).toBe(false)
+    expect(isUuidListParam(`${idA},not-a-uuid`)).toBe(false)
+    expect(isUuidListParam(`${idA}0`)).toBe(false)
+    expect(isUuidListParam(`{${idA}}`)).toBe(false)
+  })
+
+  it('isUuidListParam fails closed on non-string values', () => {
+    expect(isUuidListParam(['not-a-uuid'])).toBe(false)
+    expect(isUuidListParam([idA])).toBe(false)
+    expect(isUuidListParam(null)).toBe(false)
+  })
 })

package/src/lib/crud/exporters.ts

@@ -81,7 +81,7 @@ function escapeXmlValue(value: string): string {
 }
 
 function serializeCsv(prepared: PreparedExport): SerializedExport {
-  const headers = prepared.columns.map((col) => col.header)
+  const headers = prepared.columns.map((col) => escapeCsv(neutralizeSpreadsheetFormula(col.header)))
   const lines = [headers.join(',')]
   for (const row of prepared.rows) {
     const values = prepared.columns.map((col) => {

package/src/lib/crud/ids.ts

@@ -51,6 +51,30 @@ export function parseIdsParam(raw: unknown, maxIds: number = MAX_IDS_PER_REQUEST
   return parsed.slice(0, safeMax)
 }
 
+const UUID_SHAPE_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+/**
+ * Splits a comma-separated id list query param into its trimmed, non-empty entries.
+ */
+export function splitIdListParam(raw: unknown): string[] {
+  if (typeof raw !== 'string') return []
+  return raw
+    .split(',')
+    .map((value) => value.trim())
+    .filter((value) => value.length > 0)
+}
+
+/**
+ * Whether every entry of a comma-separated id list query param is UUID-shaped, so it can be
+ * bound to a uuid column without a database error. Use it to reject a malformed or mixed list
+ * with a 400 instead of dropping the bad entries and widening the result set (#7265).
+ */
+export function isUuidListParam(raw: unknown): boolean {
+  if (raw === undefined) return true
+  if (typeof raw !== 'string') return false
+  return splitIdListParam(raw).every((value) => UUID_SHAPE_REGEX.test(value))
+}
+
 /**
  * Whether an `?ids=` param was supplied at all (a non-empty string, or repeated
  * `?ids=` occurrences), regardless of whether any value survived UUID