@open-mercato/shared 0.7.1-develop.7193.1.910a5b0a1e → 0.7.1-develop.7194.1.ab4fc81f82

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

@@ -298,6 +298,70 @@ describe('CommandBus', () => {
     )
   })
 
+  // Agent Identity & On-Behalf-Of (Wave 4 P2): when ctx.runAs is set the SAME
+  // audit path attributes the write to the agent principal on behalf of the human,
+  // sourced 'agent' — not a parallel audit route.
+  it('stamps actorUserId=agent + onBehalfOfUserId=human + source=agent when ctx.runAs is set', async () => {
+    const logMock = jest.fn(async () => ({ id: 'log-runas' }))
+    registerCommand({
+      id: 'test.command.runas',
+      execute: jest.fn(async () => ({ ok: true })),
+      buildLog: jest.fn(() => ({ actionLabel: 'Agent write', resourceKind: 'deal', resourceId: 'deal-9' })),
+    })
+
+    const container = createContainer({ injectionMode: InjectionMode.CLASSIC })
+    container.register({ actionLogService: asValue({ log: logMock }) })
+
+    const bus = new CommandBus()
+    const ctx = {
+      container,
+      // The invoking human still carries the JWT auth, but runAs overrides the actor.
+      auth: { sub: 'human-1', tenantId: 'tenant-1', orgId: 'org-1' },
+      organizationScope: null,
+      selectedOrganizationId: 'org-1',
+      organizationIds: ['org-1'],
+      runAs: { actorUserId: 'agent-user-1', onBehalfOfUserId: 'human-1', source: 'agent' as const },
+    }
+
+    await bus.execute('test.command.runas', { input: {}, ctx })
+
+    expect(logMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        commandId: 'test.command.runas',
+        actorUserId: 'agent-user-1',
+        onBehalfOfUserId: 'human-1',
+        context: expect.objectContaining({ source: 'agent' }),
+      })
+    )
+  })
+
+  it('does not set onBehalfOfUserId for ordinary (non-runAs) human writes — additive default', async () => {
+    const logMock = jest.fn(async () => ({ id: 'log-plain' }))
+    registerCommand({
+      id: 'test.command',
+      execute: jest.fn(async () => ({ ok: true })),
+      buildLog: jest.fn(() => ({ actionLabel: 'Plain', resourceKind: 'test', resourceId: '7' })),
+    })
+
+    const container = createContainer({ injectionMode: InjectionMode.CLASSIC })
+    container.register({ actionLogService: asValue({ log: logMock }) })
+
+    const bus = new CommandBus()
+    const ctx = {
+      container,
+      auth: { sub: 'user-1', tenantId: 'tenant-1', orgId: null },
+      organizationScope: null,
+      selectedOrganizationId: null,
+      organizationIds: null,
+    }
+
+    await bus.execute('test.command', { input: {}, ctx })
+
+    const payload = logMock.mock.calls[0][0] as Record<string, unknown>
+    expect(payload.actorUserId).toBe('user-1')
+    expect(payload.onBehalfOfUserId).toBeUndefined()
+  })
+
   describe('interceptor rejections', () => {
     const blockingInterceptor = (result: Record<string, unknown>): CommandInterceptor => ({
       id: 'test.block',

package/src/lib/commands/__tests__/registry.test.ts

@@ -1,3 +1,4 @@
+import { z } from 'zod'
 import { commandRegistry, registerCommand, registerCommandLoaders } from '@open-mercato/shared/lib/commands'
 import { createLogger } from '@open-mercato/shared/lib/logger'
 
@@ -104,6 +105,40 @@ describe('command registry registration', () => {
     expect(commandRegistry.list()).not.toContain('test:commands:fallback')
   })
 
+  it('returns the outputSchema for a registered handler that declares one and null otherwise', () => {
+    const outputSchema = z.object({ dealId: z.string().uuid() })
+
+    registerCommand({
+      id: 'test.command.with-output',
+      execute: jest.fn(),
+      outputSchema,
+    })
+    registerCommand({
+      id: 'test.command.without-output',
+      execute: jest.fn(),
+    })
+
+    expect(commandRegistry.outputSchemaOf('test.command.with-output')).toBe(outputSchema)
+    expect(commandRegistry.outputSchemaOf('test.command.without-output')).toBeNull()
+    expect(commandRegistry.outputSchemaOf('test.command.never-registered')).toBeNull()
+  })
+
+  it('does not trigger lazy loaders when resolving output schemas', () => {
+    const load = jest.fn(async () => {})
+
+    registerCommandLoaders([
+      {
+        moduleId: 'test',
+        id: 'test.command.lazy-output',
+        key: 'test:commands:lazy-output',
+        load,
+      },
+    ])
+
+    expect(commandRegistry.outputSchemaOf('test.command.lazy-output')).toBeNull()
+    expect(load).not.toHaveBeenCalled()
+  })
+
   it('loads sibling module command files with an exact lazy command', async () => {
     registerCommandLoaders([
       {

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

@@ -543,6 +543,7 @@ export class CommandBus {
       tenantId: secondary?.tenantId ?? primary?.tenantId ?? null,
       organizationId: secondary?.organizationId ?? primary?.organizationId ?? null,
       actorUserId: secondary?.actorUserId ?? primary?.actorUserId ?? null,
+      onBehalfOfUserId: secondary?.onBehalfOfUserId ?? primary?.onBehalfOfUserId ?? null,
       actionLabel: secondary?.actionLabel ?? primary?.actionLabel ?? null,
       resourceKind: secondary?.resourceKind ?? primary?.resourceKind ?? null,
       resourceId: secondary?.resourceId ?? primary?.resourceId ?? null,
@@ -582,7 +583,13 @@ export class CommandBus {
     const tenantId = metadata.tenantId ?? options.ctx.auth?.tenantId ?? null
     const organizationId =
       metadata.organizationId ?? options.ctx.selectedOrganizationId ?? options.ctx.auth?.orgId ?? null
-    const actorUserId = metadata.actorUserId ?? options.ctx.auth?.sub ?? null
+    // On-behalf-of attribution (Wave 4 P2): when `ctx.runAs` is set the actor is
+    // the agent principal and the human it acts for is recorded separately. This
+    // funnels agent writes through the SAME ActionLog path as a human's — only the
+    // attribution differs (actorUserId=agent, onBehalfOfUserId=human, source='agent').
+    const runAs = options.ctx.runAs ?? null
+    const actorUserId = runAs?.actorUserId ?? metadata.actorUserId ?? options.ctx.auth?.sub ?? null
+    const onBehalfOfUserId = runAs ? (runAs.onBehalfOfUserId ?? null) : (metadata.onBehalfOfUserId ?? null)
     const systemActorContext = !actorUserId && options.ctx.systemActor === true
       ? { systemActor: 'system:command' }
       : null
@@ -590,6 +597,7 @@ export class CommandBus {
       tenantId: tenantId ?? undefined,
       organizationId: organizationId ?? undefined,
       actorUserId: actorUserId ?? undefined,
+      onBehalfOfUserId: onBehalfOfUserId ?? undefined,
       commandId,
     }
 
@@ -613,6 +621,13 @@ export class CommandBus {
       }
     }
 
+    if (runAs) {
+      // Stamp the audit source so `deriveActionLogSource` projects `sourceKey='agent'`.
+      // Merge into any caller-provided context rather than replacing it.
+      const baseContext = asRecord(payload.context) ?? {}
+      payload.context = { ...baseContext, source: runAs.source }
+    }
+
     const redoEnvelope = wrapRedoPayload('commandPayload' in payload ? (payload.commandPayload as unknown) : undefined, options.input)
     payload.commandPayload = redoEnvelope
 

package/src/lib/commands/registry.ts

@@ -1,3 +1,4 @@
+import type { ZodTypeAny } from 'zod'
 import type { CommandHandler } from './types'
 import { createLogger } from '../logger'
 
@@ -78,6 +79,16 @@ class CommandRegistry {
     return this.handlers.has(id) || this.loadersById.has(id)
   }
 
+  /**
+   * Returns the `outputSchema` declared by an already-registered handler, or
+   * `null` when the handler declares none. Sync over registered handlers only:
+   * it never triggers lazy loaders, so a handler that is known but not yet
+   * loaded also yields `null` — call `load(id)` first when that matters.
+   */
+  outputSchemaOf(id: string): ZodTypeAny | null {
+    return this.get(id)?.outputSchema ?? null
+  }
+
   /**
    * List all known command IDs, including exact lazy loaders that have not
    * been imported yet.

package/src/lib/commands/types.ts

@@ -1,5 +1,6 @@
 import type { AwilixContainer } from 'awilix'
 import type { EntityManager } from '@mikro-orm/postgresql'
+import type { ZodTypeAny } from 'zod'
 import { randomUUID } from 'crypto'
 import type { AuthContext } from '../auth/server'
 import type { OrganizationScope } from '@open-mercato/core/modules/directory/utils/organizationScope'
@@ -57,6 +58,28 @@ export type CommandRuntimeContext = {
    * surrounding work as a single atomic, single-locked operation.
    */
   transactionalEm?: EntityManager
+  /**
+   * On-behalf-of attribution for non-human principals (Agent Identity &
+   * On-Behalf-Of, Wave 4 P2). When an agent runs on behalf of a human, the
+   * orchestrator's `runAs` wrapper sets this so every `ActionLog` the command
+   * path writes records `actorUserId = runAs.actorUserId` (the agent principal's
+   * `auth.User` id), `onBehalfOfUserId = runAs.onBehalfOfUserId` (the invoking
+   * human, or null for system-invoked agents), and `sourceKey = runAs.source`
+   * (`'agent'`). Additive + optional: callers that omit it keep the existing
+   * `ctx.auth.sub`-derived attribution unchanged. This threads agent attribution
+   * through the SAME audited Command/CRUD path as a human action — not a parallel
+   * audit path.
+   */
+  runAs?: CommandRunAsContext
+}
+
+export type CommandRunAsContext = {
+  /** The actor stamped on every ActionLog this context produces (agent `auth.User` id). */
+  actorUserId: string
+  /** The human (or system) principal the actor acts on behalf of; null when system-invoked. */
+  onBehalfOfUserId?: string | null
+  /** The audit source key for the attributed writes; `'agent'` for agent runs. */
+  source: 'agent'
 }
 
 export type CommandLogMetadata = {
@@ -64,6 +87,7 @@ export type CommandLogMetadata = {
   tenantId?: string | null
   organizationId?: string | null
   actorUserId?: string | null
+  onBehalfOfUserId?: string | null
   actionLabel?: string | null
   resourceKind?: string | null
   resourceId?: string | null
@@ -129,6 +153,13 @@ export type CommandLogBuilderArgs<TInput, TResult> = {
 export interface CommandHandler<TInput = unknown, TResult = unknown> {
   readonly id: string
   readonly isUndoable?: boolean
+  /**
+   * Optional Zod schema describing the command's return value. Feeds the
+   * workflows context ledger so downstream activities can reason about the
+   * shape a command produces; when absent the ledger renders the output as
+   * unknown.
+   */
+  readonly outputSchema?: ZodTypeAny
   prepare?(input: TInput, ctx: CommandRuntimeContext): Promise<{ before?: unknown } | null> | { before?: unknown } | null
   execute(input: TInput, ctx: CommandRuntimeContext): Promise<TResult> | TResult
   buildLog?(args: CommandLogBuilderArgs<TInput, TResult>): Promise<CommandLogMetadata | null | undefined> | CommandLogMetadata | null | undefined

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>