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

package/src/lib/encryption/subscriber.ts

@@ -50,6 +50,31 @@ function isJsonColumnProperty(prop: unknown): boolean {
   return typeof customTypeName === 'string' && customTypeName.toLowerCase().includes('json')
 }
 
+// Encryption is configured on but the service reports disabled — the KMS is
+// unreachable, so this write lands as plaintext. Throttle the warning so a long
+// outage does not flood the log while still leaving an ongoing signal that the
+// fail-open window is open (#5948).
+const ENCRYPTION_PAUSED_WARN_INTERVAL_MS = 60_000
+let lastEncryptionPausedWarnAt = 0
+
+function warnEncryptionPaused(entity: string | undefined): void {
+  const now = Date.now()
+  if (lastEncryptionPausedWarnAt && now - lastEncryptionPausedWarnAt < ENCRYPTION_PAUSED_WARN_INTERVAL_MS) return
+  lastEncryptionPausedWarnAt = now
+  try {
+    logger.warn(
+      'Tenant data encryption is enabled but the KMS is unavailable - entity writes persist as plaintext until it recovers',
+      { entity },
+    )
+  } catch {
+    // ignore
+  }
+}
+
+export function resetEncryptionPausedWarnThrottle(): void {
+  lastEncryptionPausedWarnAt = 0
+}
+
 const registeredEventManagers = new WeakSet<object>()
 
 const subscribersByService = new WeakMap<TenantDataEncryptionService, TenantEncryptionSubscriber>()
@@ -206,8 +231,10 @@ export class TenantEncryptionSubscriber implements EventSubscriber<any> {
     em?: { getMetadata?: () => any; getComparator?: () => any },
     changeSet?: { payload?: Record<string, unknown> },
   ) {
-    if (!isTenantDataEncryptionEnabled() || !this.service.isEnabled()) {
+    const encryptionConfigured = isTenantDataEncryptionEnabled()
+    if (!encryptionConfigured || !this.service.isEnabled()) {
       debug('⚪️ subscriber.skip', { reason: 'disabled', entity: meta?.className || meta?.name })
+      if (encryptionConfigured) warnEncryptionPaused(meta?.className || meta?.name)
       return
     }
     const resolvedMeta = this.resolveMeta(meta, target, em)

package/src/lib/openapi/__tests__/generator-response-fallback.test.ts

@@ -0,0 +1,73 @@
+import { z } from 'zod'
+import { buildOpenApiDocument } from '../generator'
+import type { Module } from '../../../modules/registry'
+
+type SchemaNode = {
+  type?: string
+  description?: string
+  properties?: Record<string, SchemaNode>
+}
+
+type OperationNode = {
+  responses?: Record<string, { content?: Record<string, { schema?: SchemaNode }> }>
+}
+
+const noopHandler = async () => new Response(null)
+
+function makeModules(): Module[] {
+  return [
+    {
+      id: 'example',
+      apis: [
+        {
+          path: '/example/undeclared',
+          handlers: { GET: noopHandler },
+          docs: {
+            methods: {
+              GET: {
+                summary: 'Undeclared schema',
+                responses: [{ status: 200, description: 'Success' }],
+              },
+            },
+          },
+        },
+        {
+          path: '/example/declared',
+          handlers: { GET: noopHandler },
+          docs: {
+            methods: {
+              GET: {
+                summary: 'Declared schema',
+                responses: [
+                  { status: 200, description: 'Success', schema: z.object({ ok: z.boolean() }) },
+                ],
+              },
+            },
+          },
+        },
+      ],
+    } as unknown as Module,
+  ]
+}
+
+function responseSchema(doc: ReturnType<typeof buildOpenApiDocument>, path: string): SchemaNode | undefined {
+  const pathItem = doc.paths[path] as Record<string, OperationNode> | undefined
+  return pathItem?.get?.responses?.['200']?.content?.['application/json']?.schema
+}
+
+describe('buildOpenApiDocument response schema fallback', () => {
+  it('marks responses without a declared schema with an advisory description', () => {
+    const doc = buildOpenApiDocument(makeModules())
+    expect(responseSchema(doc, '/example/undeclared')).toEqual({
+      type: 'object',
+      description: 'Schema not declared',
+    })
+  })
+
+  it('leaves declared schemas untouched', () => {
+    const doc = buildOpenApiDocument(makeModules())
+    const schema = responseSchema(doc, '/example/declared')
+    expect(schema?.description).toBeUndefined()
+    expect(schema?.properties?.ok?.type).toBe('boolean')
+  })
+})

package/src/lib/openapi/generator.ts

@@ -17,7 +17,7 @@ type PathParamInfo = {
 
 type ParameterLocation = 'query' | 'path' | 'header'
 
-type JsonSchema = Record<string, unknown>
+export type JsonSchema = Record<string, unknown>
 
 type SchemaConversionContext = {
   memo: WeakMap<ZodTypeAny, JsonSchema>
@@ -258,7 +258,7 @@ function extractZodDescription(schema?: ZodTypeAny): string | undefined {
   return undefined
 }
 
-function zodToJsonSchema(schema?: ZodTypeAny, ctx?: SchemaConversionContext): JsonSchema | undefined {
+export function zodToJsonSchema(schema?: ZodTypeAny, ctx?: SchemaConversionContext): JsonSchema | undefined {
   if (!schema) return undefined
   const context: SchemaConversionContext = ctx ?? { memo: new WeakMap<ZodTypeAny, JsonSchema>() }
 
@@ -823,7 +823,7 @@ function buildResponses(
         : {
             content: {
               [mediaType]: {
-                schema: schema ?? { type: 'object' },
+                schema: schema ?? { type: 'object', description: 'Schema not declared' },
                 ...(example !== undefined ? { example } : {}),
               },
             },

package/src/lib/openapi/index.ts

@@ -1,5 +1,5 @@
 export * from './types'
-export { buildOpenApiDocument, generateMarkdownFromOpenApi } from './generator'
+export { buildOpenApiDocument, generateMarkdownFromOpenApi, zodToJsonSchema, type JsonSchema } from './generator'
 export * from './crud'
 export { sanitizeOpenApiDocument } from './sanitize'
 export { attachOpenApiDocsToModules } from './attach-docs'

package/src/lib/seed/__tests__/seed-crypto.test.ts

@@ -0,0 +1,64 @@
+import {
+  decryptSeedEnvelope,
+  encryptSeedDocument,
+  generateSeedKey,
+  resolveSeedKey,
+  SEED_KEY_ENV,
+} from '../crypto'
+import { encryptedSeedEnvelopeSchema, type SeedDocument } from '../types'
+
+const sampleDocument: SeedDocument = {
+  format: 'om-seed',
+  version: 1,
+  records: [
+    { entity: 'customers:customer_entity', match: ['id'], data: { id: 'abc', displayName: 'Jane Doe' } },
+    { entity: 'customers:customer_address', data: { name: 'HQ', city: 'Warsaw' } },
+  ],
+}
+
+describe('seed crypto', () => {
+  const originalEnv = process.env[SEED_KEY_ENV]
+  afterEach(() => {
+    if (originalEnv === undefined) delete process.env[SEED_KEY_ENV]
+    else process.env[SEED_KEY_ENV] = originalEnv
+  })
+
+  it('generates a 32-byte base64 key', () => {
+    const key = generateSeedKey()
+    expect(Buffer.from(key, 'base64')).toHaveLength(32)
+  })
+
+  it('round-trips a document through encrypt/decrypt', () => {
+    const key = generateSeedKey()
+    const envelope = encryptSeedDocument(sampleDocument, key)
+    expect(() => encryptedSeedEnvelopeSchema.parse(envelope)).not.toThrow()
+    // The envelope must not leak plaintext.
+    expect(envelope.payload).not.toContain('Jane Doe')
+    const decrypted = decryptSeedEnvelope(envelope, key)
+    expect(decrypted).toEqual(sampleDocument)
+  })
+
+  it('produces a different ciphertext each time (randomized IV)', () => {
+    const key = generateSeedKey()
+    const a = encryptSeedDocument(sampleDocument, key)
+    const b = encryptSeedDocument(sampleDocument, key)
+    expect(a.payload).not.toEqual(b.payload)
+  })
+
+  it('fails to decrypt with the wrong key', () => {
+    const envelope = encryptSeedDocument(sampleDocument, generateSeedKey())
+    expect(() => decryptSeedEnvelope(envelope, generateSeedKey())).toThrow()
+  })
+
+  it('resolves the key from OM_SEED_KEY', () => {
+    const key = generateSeedKey()
+    process.env[SEED_KEY_ENV] = key
+    expect(resolveSeedKey()).toBe(key)
+  })
+
+  it('rejects a missing or malformed key', () => {
+    delete process.env[SEED_KEY_ENV]
+    expect(() => resolveSeedKey()).toThrow()
+    expect(() => resolveSeedKey('not-32-bytes')).toThrow()
+  })
+})

package/src/lib/seed/crypto.ts

@@ -0,0 +1,87 @@
+import crypto from 'node:crypto'
+import { decryptWithAesGcm, encryptWithAesGcm } from '../encryption/aes'
+import {
+  ENCRYPTED_SEED_ALGORITHM,
+  ENCRYPTED_SEED_FORMAT,
+  ENCRYPTED_SEED_VERSION,
+  encryptedSeedEnvelopeSchema,
+  seedDocumentSchema,
+  type EncryptedSeedEnvelope,
+  type SeedDocument,
+} from './types'
+
+/**
+ * Distribution-layer key for encrypting seed blobs committed to the repo. This is
+ * deliberately separate from the platform's per-tenant field-encryption keys
+ * (Vault / TENANT_DATA_ENCRYPTION_*): rotating or sharing the seed key never
+ * touches data-at-rest encryption.
+ */
+export const SEED_KEY_ENV = 'OM_SEED_KEY'
+
+const SEED_KEY_BYTES = 32
+
+function normalizeKey(value: string): string {
+  return value.trim().replace(/(?:^['"]|['"]$)/g, '')
+}
+
+/** Generate a fresh base64-encoded 32-byte seed key. */
+export function generateSeedKey(): string {
+  return crypto.randomBytes(SEED_KEY_BYTES).toString('base64')
+}
+
+/**
+ * Resolve and validate the seed key from an explicit value or `OM_SEED_KEY`.
+ * Throws a clear, actionable error when missing or malformed.
+ */
+export function resolveSeedKey(explicit?: string | null): string {
+  const raw = normalizeKey(explicit ?? process.env[SEED_KEY_ENV] ?? '')
+  if (!raw) {
+    throw new Error(
+      `[internal] Seed key missing: set ${SEED_KEY_ENV} (base64, 32 bytes) or pass --key. Generate one with "mercato seeds keygen".`,
+    )
+  }
+  let decoded: Buffer
+  try {
+    decoded = Buffer.from(raw, 'base64')
+  } catch {
+    throw new Error(`[internal] ${SEED_KEY_ENV} must be base64-encoded.`)
+  }
+  if (decoded.length !== SEED_KEY_BYTES) {
+    throw new Error(
+      `[internal] ${SEED_KEY_ENV} must decode to ${SEED_KEY_BYTES} bytes (got ${decoded.length}). Generate one with "mercato seeds keygen".`,
+    )
+  }
+  return raw
+}
+
+/** Encrypt a validated seed document into the opaque, committable envelope. */
+export function encryptSeedDocument(document: SeedDocument, key: string): EncryptedSeedEnvelope {
+  const doc = seedDocumentSchema.parse(document)
+  const json = JSON.stringify(doc)
+  const { value } = encryptWithAesGcm(json, key)
+  if (!value) {
+    throw new Error('[internal] Seed encryption produced no payload.')
+  }
+  return {
+    format: ENCRYPTED_SEED_FORMAT,
+    version: ENCRYPTED_SEED_VERSION,
+    algorithm: ENCRYPTED_SEED_ALGORITHM,
+    payload: value,
+  }
+}
+
+/** Decrypt and validate an envelope back into a seed document. */
+export function decryptSeedEnvelope(envelope: unknown, key: string): SeedDocument {
+  const parsed = encryptedSeedEnvelopeSchema.parse(envelope)
+  const json = decryptWithAesGcm(parsed.payload, key)
+  if (json === null) {
+    throw new Error('[internal] Seed decryption failed — wrong key or corrupted payload.')
+  }
+  let raw: unknown
+  try {
+    raw = JSON.parse(json)
+  } catch {
+    throw new Error('[internal] Decrypted seed is not valid JSON.')
+  }
+  return seedDocumentSchema.parse(raw)
+}

package/src/lib/seed/index.ts

@@ -0,0 +1,3 @@
+export * from './types'
+export * from './crypto'
+export * from './loader'

package/src/lib/seed/loader.ts

@@ -0,0 +1,124 @@
+import type { EntityManager, EntityMetadata } from '@mikro-orm/postgresql'
+import { resolveEntityIdFromMetadata } from '../encryption/entityIds'
+import { seedDocumentSchema, type SeedDocument } from './types'
+
+export type SeedLoadScope = {
+  tenantId: string
+  organizationId: string
+}
+
+export type SeedLoadProgress = {
+  index: number
+  total: number
+  entity: string
+  action: 'created' | 'skipped'
+}
+
+export type SeedLoadOptions = {
+  /** Apply inside a transaction and roll it back; reports what would happen. */
+  dryRun?: boolean
+  onProgress?: (progress: SeedLoadProgress) => void
+}
+
+export type SeedLoadResult = {
+  total: number
+  created: number
+  skipped: number
+}
+
+class SeedDryRunRollback extends Error {}
+
+function resolveEntityClass(meta: EntityMetadata<any>): unknown {
+  return (meta as any).class ?? meta.className ?? meta.name
+}
+
+function buildEntityIdIndex(em: EntityManager): Map<string, EntityMetadata<any>> {
+  const storage = em.getMetadata() as unknown as {
+    getAll?: () =>
+      | Map<unknown, EntityMetadata<any>>
+      | Record<string, EntityMetadata<any>>
+      | EntityMetadata<any>[]
+    metadata?: Record<string, EntityMetadata<any>>
+  }
+  const all = (typeof storage.getAll === 'function' ? storage.getAll() : storage.metadata) ?? {}
+  // MikroORM v7's instance getAll() returns a Map; older shapes returned a plain
+  // object or array. Normalize all three to a flat list.
+  const list: EntityMetadata<any>[] =
+    all instanceof Map ? [...all.values()] : Array.isArray(all) ? all : Object.values(all)
+  const index = new Map<string, EntityMetadata<any>>()
+  for (const meta of list) {
+    if (!meta || (meta as any).abstract) continue
+    const entityId = resolveEntityIdFromMetadata(meta)
+    if (!entityId) continue
+    if (!index.has(entityId)) index.set(entityId, meta)
+  }
+  return index
+}
+
+function hasProperty(meta: EntityMetadata<any>, name: string): boolean {
+  return Boolean(meta.properties && (meta.properties as Record<string, unknown>)[name])
+}
+
+/**
+ * Insert seed records through the ORM so the tenant-data-encryption subscriber
+ * encrypts marked fields at rest automatically. Records are applied in order;
+ * `tenantId`/`organizationId` are injected from `scope` for every entity that
+ * declares them. Records with a `match` list are skipped when an existing row
+ * matches (idempotent re-runs); match fields MUST be non-encrypted natural keys.
+ */
+export async function loadSeedDocument(
+  em: EntityManager,
+  document: SeedDocument,
+  scope: SeedLoadScope,
+  options: SeedLoadOptions = {},
+): Promise<SeedLoadResult> {
+  const doc = seedDocumentSchema.parse(document)
+  const index = buildEntityIdIndex(em)
+  const total = doc.records.length
+  let created = 0
+  let skipped = 0
+
+  const run = async (tem: EntityManager) => {
+    for (let i = 0; i < doc.records.length; i += 1) {
+      const record = doc.records[i]
+      const meta = index.get(record.entity)
+      if (!meta) {
+        throw new Error(
+          `[internal] Unknown seed entity "${record.entity}" at record ${i}: not a registered entity id.`,
+        )
+      }
+      const entityClass = resolveEntityClass(meta)
+      const data: Record<string, unknown> = { ...record.data }
+      if (hasProperty(meta, 'tenantId')) data.tenantId = scope.tenantId
+      if (hasProperty(meta, 'organizationId')) data.organizationId = scope.organizationId
+
+      if (record.match && record.match.length) {
+        const where: Record<string, unknown> = {}
+        for (const field of record.match) where[field] = data[field]
+        if (hasProperty(meta, 'tenantId')) where.tenantId = scope.tenantId
+        if (hasProperty(meta, 'organizationId')) where.organizationId = scope.organizationId
+        const existing = await tem.findOne(entityClass as any, where as any)
+        if (existing) {
+          skipped += 1
+          options.onProgress?.({ index: i, total, entity: record.entity, action: 'skipped' })
+          continue
+        }
+      }
+
+      const entity = tem.create(entityClass as any, data as any)
+      tem.persist(entity)
+      await tem.flush()
+      created += 1
+      options.onProgress?.({ index: i, total, entity: record.entity, action: 'created' })
+    }
+    if (options.dryRun) throw new SeedDryRunRollback()
+  }
+
+  try {
+    await em.transactional(run)
+  } catch (err) {
+    if (!(err instanceof SeedDryRunRollback)) throw err
+  }
+
+  return { total, created, skipped }
+}

package/src/lib/seed/types.ts

@@ -0,0 +1,48 @@
+import { z } from 'zod'
+
+export const SEED_DOCUMENT_FORMAT = 'om-seed'
+export const SEED_DOCUMENT_VERSION = 1
+
+export const ENCRYPTED_SEED_FORMAT = 'om-encrypted-seed'
+export const ENCRYPTED_SEED_VERSION = 1
+export const ENCRYPTED_SEED_ALGORITHM = 'aes-256-gcm'
+
+/**
+ * A single record to seed. `entity` is the platform entity id (`module:entity`,
+ * e.g. `customers:customer_entity`). `data` keys are the entity's own property
+ * names (camelCase, as declared on the MikroORM entity). `match`, when present,
+ * lists property names used for an idempotent existence check before insert —
+ * these MUST be non-encrypted natural keys (id, slug, code, *_hash); encrypted
+ * fields cannot be matched because their ciphertext is non-deterministic.
+ */
+export const seedRecordSchema = z.object({
+  entity: z.string().min(1),
+  match: z.array(z.string().min(1)).optional(),
+  data: z.record(z.string(), z.unknown()),
+})
+export type SeedRecord = z.infer<typeof seedRecordSchema>
+
+/**
+ * The plaintext seed document. Records are applied in array order so authors can
+ * satisfy foreign-key dependencies (create the parent before the child). The
+ * document MUST NOT hard-code `tenantId`/`organizationId` — the loader injects
+ * the target scope at load time so the same document seeds any tenant.
+ */
+export const seedDocumentSchema = z.object({
+  format: z.literal(SEED_DOCUMENT_FORMAT),
+  version: z.literal(SEED_DOCUMENT_VERSION),
+  records: z.array(seedRecordSchema),
+})
+export type SeedDocument = z.infer<typeof seedDocumentSchema>
+
+/**
+ * The committed-to-repo, opaque envelope. `payload` is the encrypted seed
+ * document in the shared AES-GCM `iv:ct:tag:v1` wire format.
+ */
+export const encryptedSeedEnvelopeSchema = z.object({
+  format: z.literal(ENCRYPTED_SEED_FORMAT),
+  version: z.literal(ENCRYPTED_SEED_VERSION),
+  algorithm: z.literal(ENCRYPTED_SEED_ALGORITHM),
+  payload: z.string().min(1),
+})
+export type EncryptedSeedEnvelope = z.infer<typeof encryptedSeedEnvelopeSchema>

package/src/modules/events/__tests__/factory.test.ts

@@ -1,3 +1,99 @@
+/**
+ * Events factory — payloadSchema declaration and the generated CRUD default.
+ *
+ * Verifies the additive `payloadSchema` contract on `EventDefinition`:
+ * platform CRUD after-events (`*.created`/`*.updated`/`*.deleted`, category
+ * `crud`) receive the generated `{ id, organizationId, tenantId, syncOrigin }`
+ * default; explicit declarations are preserved untouched; lifecycle/system
+ * events and CRUD "before" events get no default; and `getDeclaredEvents()`
+ * exposes the same definitions the module config carries.
+ */
+
+import {
+  createModuleEvents,
+  getDeclaredEvents,
+  DEFAULT_CRUD_PAYLOAD_SCHEMA,
+} from '../factory'
+import type { EventPayloadSchema } from '../types'
+
+const explicitSchema: EventPayloadSchema = {
+  fields: [
+    { path: 'id', type: 'text' },
+    { path: 'amount', type: 'number', optional: true },
+    { path: 'meta', type: 'object' },
+  ],
+}
+
+const config = createModuleEvents({
+  moduleId: 'factory_test',
+  events: [
+    { id: 'factory_test.widget.created', label: 'Widget Created', entity: 'widget', category: 'crud' },
+    { id: 'factory_test.widget.updated', label: 'Widget Updated', entity: 'widget', category: 'crud' },
+    { id: 'factory_test.widget.deleted', label: 'Widget Deleted', entity: 'widget', category: 'crud' },
+    { id: 'factory_test.widget.creating', label: 'Widget Creating', entity: 'widget', category: 'crud', excludeFromTriggers: true },
+    { id: 'factory_test.widget.archived', label: 'Widget Archived', entity: 'widget', category: 'lifecycle' },
+    { id: 'factory_test.widget.scored', label: 'Widget Scored', entity: 'widget', category: 'lifecycle', payloadSchema: explicitSchema },
+    { id: 'factory_test.widget.replaced', label: 'Widget Replaced', entity: 'widget', category: 'crud', payloadSchema: explicitSchema },
+  ] as const,
+})
+
+function findEvent(id: string) {
+  const event = config.events.find(e => e.id === id)
+  if (!event) throw new Error(`[internal] event ${id} missing from config`)
+  return event
+}
+
+describe('createModuleEvents payloadSchema', () => {
+  it('attaches the generated CRUD default to platform CRUD after-events', () => {
+    for (const suffix of ['created', 'updated', 'deleted']) {
+      expect(findEvent(`factory_test.widget.${suffix}`).payloadSchema).toEqual(DEFAULT_CRUD_PAYLOAD_SCHEMA)
+    }
+  })
+
+  it('generated default mirrors the engine emit payload fields', () => {
+    expect(DEFAULT_CRUD_PAYLOAD_SCHEMA.fields.map(f => f.path)).toEqual([
+      'id',
+      'organizationId',
+      'tenantId',
+      'syncOrigin',
+    ])
+    const idField = DEFAULT_CRUD_PAYLOAD_SCHEMA.fields.find(f => f.path === 'id')
+    expect(idField).toEqual({ path: 'id', type: 'text' })
+    expect(DEFAULT_CRUD_PAYLOAD_SCHEMA.fields.filter(f => f.optional).map(f => f.path)).toEqual([
+      'organizationId',
+      'tenantId',
+      'syncOrigin',
+    ])
+  })
+
+  it('does not default CRUD "before" lifecycle suffixes or non-crud categories', () => {
+    expect(findEvent('factory_test.widget.creating').payloadSchema).toBeUndefined()
+    expect(findEvent('factory_test.widget.archived').payloadSchema).toBeUndefined()
+  })
+
+  it('preserves an explicit payloadSchema over the generated default', () => {
+    expect(findEvent('factory_test.widget.replaced').payloadSchema).toBe(explicitSchema)
+    expect(findEvent('factory_test.widget.scored').payloadSchema).toBe(explicitSchema)
+  })
+
+  it('exposes the same definitions through getDeclaredEvents()', () => {
+    const declared = getDeclaredEvents().filter(e => e.module === 'factory_test')
+    expect(declared).toHaveLength(config.events.length)
+    const declaredCreated = declared.find(e => e.id === 'factory_test.widget.created')
+    expect(declaredCreated?.payloadSchema).toEqual(DEFAULT_CRUD_PAYLOAD_SCHEMA)
+    const declaredScored = declared.find(e => e.id === 'factory_test.widget.scored')
+    expect(declaredScored?.payloadSchema).toBe(explicitSchema)
+  })
+
+  it('keeps unrelated declaration fields intact when defaulting', () => {
+    const creating = findEvent('factory_test.widget.creating')
+    expect(creating.excludeFromTriggers).toBe(true)
+    const created = findEvent('factory_test.widget.created')
+    expect(created.module).toBe('factory_test')
+    expect(created.entity).toBe('widget')
+  })
+})
+
 const GLOBAL_EVENT_REGISTRY_KEY = '__openMercatoEventDefinitionRegistry__'
 
 type EventFactoryModule = typeof import('../factory')

package/src/modules/events/factory.ts

@@ -9,6 +9,7 @@ import type {
   EventDefinition,
   EventModuleConfig,
   EventPayload,
+  EventPayloadSchema,
   EmitOptions,
   CreateModuleEventsOptions,
   ModuleEventEmitter,
@@ -101,18 +102,44 @@ function getEventRegistryState(): EventRegistryState {
   }
 }
 
+const CRUD_AFTER_EVENT_SUFFIXES = ['.created', '.updated', '.deleted'] as const
+
+/**
+ * Generated payload schema for platform-emitted CRUD after-events. Mirrors the
+ * default payload built by the data engine's `emitOrmEntityEvent` when no
+ * `buildPayload` override is configured: `{ id, organizationId, tenantId }`
+ * plus `syncOrigin` when the write originated from a sync. organizationId and
+ * tenantId keys are always present but may be null, so they are `optional`.
+ */
+export const DEFAULT_CRUD_PAYLOAD_SCHEMA: EventPayloadSchema = {
+  fields: [
+    { path: 'id', type: 'text' },
+    { path: 'organizationId', type: 'text', optional: true },
+    { path: 'tenantId', type: 'text', optional: true },
+    { path: 'syncOrigin', type: 'text', optional: true },
+  ],
+}
+
+function applyDefaultCrudPayloadSchema(event: EventDefinition): EventDefinition {
+  if (event.payloadSchema) return event
+  if (event.category !== 'crud') return event
+  if (!CRUD_AFTER_EVENT_SUFFIXES.some(suffix => event.id.endsWith(suffix))) return event
+  return { ...event, payloadSchema: DEFAULT_CRUD_PAYLOAD_SCHEMA }
+}
+
 function addDeclaredEvent(event: EventDefinition): void {
+  const declared = applyDefaultCrudPayloadSchema(event)
   const state = getEventRegistryState()
-  state.declaredEventIds.add(event.id)
-  const existingIndex = state.declaredEvents.findIndex((candidate) => candidate.id === event.id)
+  state.declaredEventIds.add(declared.id)
+  const existingIndex = state.declaredEvents.findIndex((candidate) => candidate.id === declared.id)
   if (existingIndex < 0) {
-    state.declaredEvents.push(event)
+    state.declaredEvents.push(declared)
     return
   }
   // Refresh a module's own definition in place during HMR without allowing a
   // duplicate declaration from another module to take over the event id.
-  if (state.declaredEvents[existingIndex]?.module === event.module) {
-    state.declaredEvents[existingIndex] = event
+  if (state.declaredEvents[existingIndex]?.module === declared.module) {
+    state.declaredEvents[existingIndex] = declared
   }
 }
 
@@ -271,11 +298,15 @@ export function createModuleEvents<
   // Build set of valid event IDs for runtime validation
   const validEventIds = new Set(events.map(e => e.id))
 
-  // Build full event definitions with module added
-  const fullEvents: EventDefinition[] = events.map(e => ({
-    ...e,
-    module: moduleId,
-  }))
+  // Build full event definitions with module added and the generated CRUD
+  // payload-schema default applied, so config consumers and the global
+  // registry see the same definitions.
+  const fullEvents: EventDefinition[] = events.map(e =>
+    applyDefaultCrudPayloadSchema({
+      ...e,
+      module: moduleId,
+    }),
+  )
 
   // Register all event IDs and definitions in the global registry.
   for (const event of fullEvents) {