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

package/src/modules/customers/workflows.ts

@@ -0,0 +1,57 @@
+/**
+ * Customers Module — Workflow Integration
+ *
+ * Declares which customers commands a workflow's UPDATE_ENTITY activity MAY
+ * execute. A declaration here is a CANDIDATE, not a grant: it is off for every
+ * tenant until an administrator ticks it in Workflow settings, and the acting
+ * user must still hold the declared features at execution time. See
+ * `apps/docs/docs/framework/workflows/entity-updates.mdx`.
+ *
+ * ## What is declared, and why only updates
+ *
+ * "Is a user allowed to do this?" and "is this safe to fire unattended?" are
+ * different questions. `UPDATE_ENTITY` carries no idempotency key, activities
+ * are retried on failure (`retryPolicy`, default up to 3 attempts), and an
+ * event trigger can fire the same workflow repeatedly. An UPDATE converges
+ * under all three — setting a field to a literal value twice leaves the same
+ * record, which is the module-level rule that workflow activity handlers must
+ * be idempotent.
+ *
+ * CREATE does not converge: a retry after a partial failure, or a trigger
+ * storm, turns one business event into N records that nobody asked for and
+ * that no bulk remedy exists for. DELETE does not survive stale context: a run
+ * parked on a 24h approval task holds a `{{context.id}}` captured before the
+ * pause, and the delete lands on whatever holds that id when the run wakes —
+ * irreversibly. The reversible expression of both intents is a status update,
+ * which the commands below already provide. Neither is declared; adding one
+ * needs its own argument, because a candidate in the catalogue is an
+ * invitation even when it ships switched off.
+ */
+
+import { createWorkflowsModuleConfig } from '@open-mercato/shared/modules/workflows'
+import { registerWorkflowSafeCommands } from '@open-mercato/core/modules/workflows/lib/workflow-safe-commands'
+
+registerWorkflowSafeCommands([
+  {
+    commandId: 'customers.deals.update',
+    requiredFeatures: ['customers.deals.manage'],
+    labelKey: 'customers.workflows.commands.deals.update',
+  },
+  {
+    commandId: 'customers.people.update',
+    requiredFeatures: ['customers.people.manage'],
+    labelKey: 'customers.workflows.commands.people.update',
+  },
+  {
+    commandId: 'customers.companies.update',
+    requiredFeatures: ['customers.companies.manage'],
+    labelKey: 'customers.workflows.commands.companies.update',
+  },
+])
+
+export const workflowsConfig = createWorkflowsModuleConfig({
+  moduleId: 'customers',
+  workflows: [],
+})
+
+export default workflowsConfig

package/src/modules/entities/api/records.ts

@@ -6,7 +6,7 @@ import type { QueryEngine, QueryOptions, Where, Sort } from '@open-mercato/share
 import { normalizeExportFormat, serializeExport, defaultExportFilename, ensureColumns } from '@open-mercato/shared/lib/crud/exporters'
 import type { RbacService } from '@open-mercato/core/modules/auth/services/rbacService'
 import { resolveOrganizationScope, getSelectedOrganizationFromRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
-import { SYSTEM_ENTITY_RECORDS_BLOCKED_CODE, isOrmBackedSystemEntityId } from '@open-mercato/shared/lib/data/engine'
+import { SYSTEM_ENTITY_RECORDS_BLOCKED_CODE } from '@open-mercato/shared/lib/data/engine'
 import { parseBooleanToken, parseBooleanWithDefault } from '@open-mercato/shared/lib/boolean'
 import { parseCommaSeparatedList } from '@open-mercato/shared/lib/string'
 import { setRecordCustomFields } from '../lib/helpers'
@@ -14,74 +14,30 @@ import { CustomFieldValue } from '../data/entities'
 import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
 import { enforceCommandOptimisticLockWithGuards } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
 import { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
-import { assertEntityAclForRequest, getDeclaredCustomEntityRestriction } from '../lib/entityAcl'
+import { assertEntityAclForRequest } from '../lib/entityAcl'
+import { classifyRecordsEntity } from '../lib/entityClassification'
 import { loadCustomFieldKinds } from '../lib/scoped-field-defs'
 import { createLogger } from '@open-mercato/shared/lib/logger'
 
-const logger = createLogger('entities').child({ component: 'records' })
+// Kept exported from this path: the classifier used to be private to this file
+// and the workflows task-visibility resolver reuses it, so both callers share
+// one precedence chain instead of growing a second, drifting copy.
+export {
+  classifyRecordsEntity,
+  isDeclaredCustomEntity,
+  loadDeclaredCustomEntities,
+  findScopedCustomEntity,
+} from '../lib/entityClassification'
+export type {
+  RecordsEntityScope,
+  RecordsEntityKind,
+  RecordsEntityClassification,
+} from '../lib/entityClassification'
 
-type RecordsEntityScope = { tenantId: string | null; organizationId: string | null }
-
-// Resolve the CustomEntity registration that applies to THIS caller, most-specific
-// first (org+tenant → tenant-global → instance-global), mirroring the overlay
-// precedence used by the entity-definitions list. Scoping matters because the
-// row's `access_restricted` flag is a security control: an unscoped lookup could
-// read another tenant's row for a colliding entityId (e.g. `user:vendors`) and
-// mis-decide the restriction. Returns null when the caller's scope has no row.
-async function findScopedCustomEntity(em: any, CustomEntity: any, entityId: string, scope: RecordsEntityScope) {
-  const { tenantId, organizationId } = scope
-  const candidates: Array<Record<string, unknown>> = [
-    { entityId, organizationId, tenantId },
-    { entityId, organizationId: null, tenantId },
-    { entityId, organizationId: null, tenantId: null },
-  ]
-  const seen = new Set<string>()
-  for (const where of candidates) {
-    const key = JSON.stringify(where)
-    if (seen.has(key)) continue
-    seen.add(key)
-    const row = await em.findOne(CustomEntity as any, where)
-    if (row) return row
-  }
-  return null
-}
+const logger = createLogger('entities').child({ component: 'records' })
 
 const CUSTOM_ENTITY_RECORD_RESOURCE_KIND = 'entities.record'
 
-type RecordsEntityKind = 'system' | 'custom' | 'unknown'
-
-// `restricted` is meaningful only when `kind === 'custom'`; it drives the
-// per-entity ACL gate in `assertEntityAclForRequest`.
-type RecordsEntityClassification = { kind: RecordsEntityKind; restricted: boolean }
-
-// This surface manages doc-storage records, which exist for CUSTOM entities only.
-// Module-declared ids backed by a registered ORM table are system entities — their
-// records live in their own module tables/APIs, and stray doc rows for them poisoned
-// read-path classification platform-wide (#2939) — so they are rejected outright. The
-// previous fallback that classified an entity by the mere presence of
-// `custom_entities_storage` rows is gone: within the allowed set, declaration (ce.ts)
-// or an active `custom_entities` registration is authoritative.
-async function classifyRecordsEntity(em: any, entityId: string, scope: RecordsEntityScope): Promise<RecordsEntityClassification> {
-  if (isOrmBackedSystemEntityId(em, entityId)) return { kind: 'system', restricted: false }
-  const declaredRestriction = getDeclaredCustomEntityRestriction(entityId)
-  if (declaredRestriction !== undefined) return { kind: 'custom', restricted: declaredRestriction }
-  try {
-    const { CustomEntity } = await import('../data/entities')
-    // Restriction is decided from the row that applies to THIS caller's scope so
-    // a colliding entityId in another tenant can't flip the flag.
-    const scoped = await findScopedCustomEntity(em, CustomEntity, entityId, scope)
-    if (scoped) return { kind: 'custom', restricted: (scoped as any).accessRestricted === true }
-    // No in-scope registration: preserve the historical custom-vs-unknown
-    // classification (any registration row — active or soft-deleted — proves the
-    // id is custom; records persist beyond soft delete, TC-ENTITIES-006). A row
-    // outside the caller's scope never marks the entity restricted for them, and
-    // the record query is itself tenant/org-scoped, so this cannot leak data.
-    const anyRow = await em.findOne(CustomEntity as any, { entityId })
-    if (anyRow) return { kind: 'custom', restricted: false }
-  } catch {}
-  return { kind: 'unknown', restricted: false }
-}
-
 function systemEntityRecordsRejection(entityId: string) {
   return NextResponse.json(
     { error: 'Records are available for custom entities only', code: SYSTEM_ENTITY_RECORDS_BLOCKED_CODE, entityId },

package/src/modules/entities/lib/entityClassification.ts

@@ -0,0 +1,102 @@
+/**
+ * Entity classification — "is this id an ORM-backed system entity, a custom
+ * entity, or nothing we know?"
+ *
+ * Extracted verbatim from `api/records.ts`, which still re-exports every symbol
+ * so its own import path is unchanged. It lives here because the precedence
+ * chain (ORM registry → module-declared `ce.ts` → scoped `custom_entities` row)
+ * is a security decision — `restricted` drives the per-entity ACL gate — and a
+ * second consumer that grew its own copy would drift from this one silently.
+ *
+ * The scoped lookup is the reason this cannot be a pure lookup table: the
+ * `access_restricted` flag is read from the registration row that applies to
+ * THIS caller, so a colliding entityId in another tenant cannot flip it.
+ */
+
+import { isOrmBackedSystemEntityId } from '@open-mercato/shared/lib/data/engine'
+import { getModules } from '@open-mercato/shared/lib/i18n/server'
+
+export type RecordsEntityScope = { tenantId: string | null; organizationId: string | null }
+
+export type RecordsEntityKind = 'system' | 'custom' | 'unknown'
+
+// `restricted` is meaningful only when `kind === 'custom'`; it drives the
+// per-entity ACL gate in `assertEntityAclForRequest`.
+export type RecordsEntityClassification = { kind: RecordsEntityKind; restricted: boolean }
+
+let declaredCustomEntityRestricted: Map<string, boolean> | null = null
+
+export function loadDeclaredCustomEntities(): Map<string, boolean> {
+  if (declaredCustomEntityRestricted === null) {
+    try {
+      const mods = getModules() as Array<{ customEntities?: Array<{ id?: string; accessRestricted?: boolean }> }>
+      const map = new Map<string, boolean>()
+      for (const mod of mods ?? []) {
+        for (const spec of mod?.customEntities ?? []) {
+          if (spec?.id) map.set(spec.id, spec.accessRestricted === true)
+        }
+      }
+      // Cache even when empty so we don't rebuild on every request (and fall back
+      // to the DB lookup unnecessarily). Only a thrown getModules() leaves it null
+      // so a genuinely-uninitialized registry is retried.
+      declaredCustomEntityRestricted = map
+    } catch {}
+  }
+  return declaredCustomEntityRestricted ?? new Map<string, boolean>()
+}
+
+export function isDeclaredCustomEntity(entityId: string): boolean {
+  return loadDeclaredCustomEntities().has(entityId)
+}
+
+// Resolve the CustomEntity registration that applies to THIS caller, most-specific
+// first (org+tenant → tenant-global → instance-global), mirroring the overlay
+// precedence used by the entity-definitions list. Scoping matters because the
+// row's `access_restricted` flag is a security control: an unscoped lookup could
+// read another tenant's row for a colliding entityId (e.g. `user:vendors`) and
+// mis-decide the restriction. Returns null when the caller's scope has no row.
+export async function findScopedCustomEntity(em: any, CustomEntity: any, entityId: string, scope: RecordsEntityScope) {
+  const { tenantId, organizationId } = scope
+  const candidates: Array<Record<string, unknown>> = [
+    { entityId, organizationId, tenantId },
+    { entityId, organizationId: null, tenantId },
+    { entityId, organizationId: null, tenantId: null },
+  ]
+  const seen = new Set<string>()
+  for (const where of candidates) {
+    const key = JSON.stringify(where)
+    if (seen.has(key)) continue
+    seen.add(key)
+    const row = await em.findOne(CustomEntity as any, where)
+    if (row) return row
+  }
+  return null
+}
+
+// This surface manages doc-storage records, which exist for CUSTOM entities only.
+// Module-declared ids backed by a registered ORM table are system entities — their
+// records live in their own module tables/APIs, and stray doc rows for them poisoned
+// read-path classification platform-wide (#2939) — so they are rejected outright. The
+// previous fallback that classified an entity by the mere presence of
+// `custom_entities_storage` rows is gone: within the allowed set, declaration (ce.ts)
+// or an active `custom_entities` registration is authoritative.
+export async function classifyRecordsEntity(em: any, entityId: string, scope: RecordsEntityScope): Promise<RecordsEntityClassification> {
+  if (isOrmBackedSystemEntityId(em, entityId)) return { kind: 'system', restricted: false }
+  const declared = loadDeclaredCustomEntities()
+  if (declared.has(entityId)) return { kind: 'custom', restricted: declared.get(entityId) === true }
+  try {
+    const { CustomEntity } = await import('../data/entities')
+    // Restriction is decided from the row that applies to THIS caller's scope so
+    // a colliding entityId in another tenant can't flip the flag.
+    const scoped = await findScopedCustomEntity(em, CustomEntity, entityId, scope)
+    if (scoped) return { kind: 'custom', restricted: (scoped as any).accessRestricted === true }
+    // No in-scope registration: preserve the historical custom-vs-unknown
+    // classification (any registration row — active or soft-deleted — proves the
+    // id is custom; records persist beyond soft delete, TC-ENTITIES-006). A row
+    // outside the caller's scope never marks the entity restricted for them, and
+    // the record query is itself tenant/org-scoped, so this cannot leak data.
+    const anyRow = await em.findOne(CustomEntity as any, { entityId })
+    if (anyRow) return { kind: 'custom', restricted: false }
+  } catch {}
+  return { kind: 'unknown', restricted: false }
+}

package/src/modules/sales/commands/documents.ts

@@ -5463,11 +5463,55 @@ const updateQuoteCommand: CommandHandler<
   },
 };
 
+/**
+ * Output contracts for the order commands, consumed by the workflows context
+ * ledger through `commandRegistry.outputSchemaOf`.
+ *
+ * `sales.orders.update` genuinely returns the mutated `SalesOrder` entity, not
+ * an id — so the schema describes the entity's own scalar columns. It is a
+ * curated subset, not the whole entity: relation properties (`channel`,
+ * `shippingMethod`, `lines`) are ORM references that do not survive the JSON
+ * context column, and the jsonb snapshot blobs carry no pickable shape. Zod
+ * objects do not claim exhaustiveness, so naming a subset stays honest while
+ * keeping the variable picker readable.
+ */
+const orderEntityOutputSchema = z.object({
+  id: z.string().uuid(),
+  organizationId: z.string().uuid(),
+  tenantId: z.string().uuid(),
+  orderNumber: z.string(),
+  channelId: z.string().uuid().nullable().optional(),
+  customerEntityId: z.string().uuid().nullable().optional(),
+  currencyCode: z.string(),
+  status: z.string().nullable().optional(),
+  statusEntryId: z.string().uuid().nullable().optional(),
+  fulfillmentStatus: z.string().nullable().optional(),
+  paymentStatus: z.string().nullable().optional(),
+  subtotalNetAmount: z.string(),
+  subtotalGrossAmount: z.string(),
+  discountTotalAmount: z.string(),
+  taxTotalAmount: z.string(),
+  grandTotalNetAmount: z.string(),
+  grandTotalGrossAmount: z.string(),
+  paidTotalAmount: z.string(),
+  outstandingAmount: z.string(),
+  lineItemCount: z.number(),
+  placedAt: z.date().nullable().optional(),
+  dueAt: z.date().nullable().optional(),
+  createdAt: z.date(),
+  updatedAt: z.date(),
+});
+
+const orderUpdateOutputSchema = z.object({ order: orderEntityOutputSchema });
+
+const orderIdOutputSchema = z.object({ orderId: z.string().uuid() });
+
 const updateOrderCommand: CommandHandler<
   DocumentUpdateInput,
   { order: SalesOrder }
 > = {
   id: "sales.orders.update",
+  outputSchema: orderUpdateOutputSchema,
   async prepare(input, ctx) {
     const parsed = documentUpdateSchema.parse(input ?? {});
     const em = ctx.container.resolve("em") as EntityManager;
@@ -5712,6 +5756,7 @@ const createOrderCommand: CommandHandler<
   { orderId: string; warnings?: OrderPaymentLedgerWarning[] }
 > = {
   id: "sales.orders.create",
+  outputSchema: orderIdOutputSchema,
   async execute(rawInput, ctx) {
     const generator = ctx.container.resolve(
       "salesDocumentNumberGenerator",
@@ -6155,6 +6200,7 @@ const deleteOrderCommand: CommandHandler<
   { orderId: string }
 > = {
   id: "sales.orders.delete",
+  outputSchema: orderIdOutputSchema,
   async prepare(input, ctx) {
     const id = requireId(input, "Order id is required");
     const em = ctx.container.resolve("em") as EntityManager;

package/src/modules/sales/events.ts

@@ -1,10 +1,28 @@
-import { createModuleEvents } from '@open-mercato/shared/modules/events'
+import { createModuleEvents, type EventPayloadSchema } from '@open-mercato/shared/modules/events'
 
 /**
  * Sales Module Events
  *
  * Declares all events that can be emitted by the sales module.
  */
+
+/**
+ * Payload emitted by `commands/documents.ts` (`emitTotalsCalculated`) for
+ * `sales.document.totals.calculated`. Fields mirror the emit call exactly;
+ * `totals` is the calculation result object, declared as `object`.
+ */
+const totalsCalculatedPayloadSchema: EventPayloadSchema = {
+  fields: [
+    { path: 'documentKind', type: 'text' },
+    { path: 'documentId', type: 'text' },
+    { path: 'organizationId', type: 'text' },
+    { path: 'tenantId', type: 'text' },
+    { path: 'customerId', type: 'text', optional: true },
+    { path: 'totals', type: 'object' },
+    { path: 'lineCount', type: 'number' },
+  ],
+}
+
 const events = [
   // Orders
   { id: 'sales.order.created', label: 'Sales Order Created', entity: 'order', category: 'crud' },
@@ -60,7 +78,7 @@ const events = [
   { id: 'sales.channel.deleted', label: 'Sales Channel Deleted', entity: 'channel', category: 'crud' },
 
   // Lifecycle events - Document calculations
-  { id: 'sales.document.totals.calculated', label: 'Document Totals Calculated', category: 'lifecycle' },
+  { id: 'sales.document.totals.calculated', label: 'Document Totals Calculated', category: 'lifecycle', payloadSchema: totalsCalculatedPayloadSchema },
   { id: 'sales.document.calculate.before', label: 'Before Document Calculate', category: 'lifecycle', excludeFromTriggers: true },
   { id: 'sales.document.calculate.after', label: 'After Document Calculate', category: 'lifecycle', excludeFromTriggers: true },
 

package/src/modules/sales/i18n/de.json

@@ -1490,5 +1490,6 @@
   "sales.widgets.newQuotes.settings.last24h": "Letzte 24 Stunden",
   "sales.widgets.newQuotes.settings.last30d": "Letzte 30 Tage",
   "sales.widgets.newQuotes.settings.last7d": "Letzte 7 Tage",
-  "sales.widgets.newQuotes.settings.pageSize": "Anzahl der Angebote"
+  "sales.widgets.newQuotes.settings.pageSize": "Anzahl der Angebote",
+  "sales.workflows.commands.orders.update": "Verkaufsauftrag aktualisieren"
 }

package/src/modules/sales/i18n/en.json

@@ -1490,5 +1490,6 @@
   "sales.widgets.newQuotes.settings.last24h": "Last 24 hours",
   "sales.widgets.newQuotes.settings.last30d": "Last 30 days",
   "sales.widgets.newQuotes.settings.last7d": "Last 7 days",
-  "sales.widgets.newQuotes.settings.pageSize": "Number of Quotes"
+  "sales.widgets.newQuotes.settings.pageSize": "Number of Quotes",
+  "sales.workflows.commands.orders.update": "Update sales order"
 }

package/src/modules/sales/i18n/es.json

@@ -1490,5 +1490,6 @@
   "sales.widgets.newQuotes.settings.last24h": "Últimas 24 horas",
   "sales.widgets.newQuotes.settings.last30d": "Últimos 30 días",
   "sales.widgets.newQuotes.settings.last7d": "Últimos 7 días",
-  "sales.widgets.newQuotes.settings.pageSize": "Número de cotizaciones"
+  "sales.widgets.newQuotes.settings.pageSize": "Número de cotizaciones",
+  "sales.workflows.commands.orders.update": "Actualizar pedido de venta"
 }

package/src/modules/sales/i18n/ko.json

@@ -1490,5 +1490,6 @@
   "sales.widgets.newQuotes.settings.last24h": "지난 24시간",
   "sales.widgets.newQuotes.settings.last30d": "지난 30일",
   "sales.widgets.newQuotes.settings.last7d": "지난 7일",
-  "sales.widgets.newQuotes.settings.pageSize": "견적 수"
+  "sales.widgets.newQuotes.settings.pageSize": "견적 수",
+  "sales.workflows.commands.orders.update": "Update sales order"
 }

package/src/modules/sales/i18n/pl.json

@@ -1490,5 +1490,6 @@
   "sales.widgets.newQuotes.settings.last24h": "Ostatnie 24 godziny",
   "sales.widgets.newQuotes.settings.last30d": "Ostatnie 30 dni",
   "sales.widgets.newQuotes.settings.last7d": "Ostatnie 7 dni",
-  "sales.widgets.newQuotes.settings.pageSize": "Liczba ofert"
+  "sales.widgets.newQuotes.settings.pageSize": "Liczba ofert",
+  "sales.workflows.commands.orders.update": "Aktualizuj zamówienie sprzedaży"
 }

package/src/modules/sales/workflows.ts

@@ -8,7 +8,18 @@ import { defineWorkflow, createWorkflowsModuleConfig } from '@open-mercato/share
 import { registerWorkflowSafeCommands } from '@open-mercato/core/modules/workflows/lib/workflow-safe-commands'
 
 registerWorkflowSafeCommands([
-  { commandId: 'sales.orders.update', requiredFeatures: ['sales.orders.manage'] },
+  {
+    commandId: 'sales.orders.update',
+    requiredFeatures: ['sales.orders.manage'],
+    labelKey: 'sales.workflows.commands.orders.update',
+    // GRANDFATHERED: the only command reachable by UPDATE_ENTITY before the
+    // tenant enablement setting existed, and the one `sales.order-approval`
+    // (shipped above, and as a gallery template) runs on every transition. A
+    // tenant that never opens the settings page must keep executing it, so this
+    // flag is what makes the gate ship without changing anybody's behaviour.
+    // New candidates MUST NOT copy it — see workflow-safe-commands.ts.
+    defaultEnabled: true,
+  },
 ])
 
 const orderApproval = defineWorkflow({

package/src/modules/seeds/README.md

@@ -0,0 +1,86 @@
+# Seeds module — encrypted data seeding
+
+Load confidential, identical baseline data into every tenant without committing the
+plaintext to the repo. The data lives in the repo only as an **opaque encrypted
+blob**; the decryption key is distributed out-of-band (e.g. at hackathon kickoff).
+
+## Why this exists
+
+Putting confidential data in a `seedExamples` function or a SQL dump leaks it: the
+plaintext is readable in the source tree (including by any agent/LLM that browses
+it). This module separates the two concerns:
+
+1. **Distribution confidentiality** — the seed file is AES-256-GCM encrypted with a
+   key (`OM_SEED_KEY`) that is *not* in the repo. Only the ciphertext is committed.
+2. **Encryption-at-rest** — records are inserted through the ORM, so the platform's
+   per-tenant field encryption (`TenantDataEncryptionService`) automatically
+   encrypts marked fields. You never touch tenant DEKs.
+
+`OM_SEED_KEY` is independent from the field-encryption keys
+(`TENANT_DATA_ENCRYPTION_*` / Vault) — rotating one never affects the other.
+
+## File format (plaintext, before encryption)
+
+```jsonc
+{
+  "format": "om-seed",
+  "version": 1,
+  "records": [
+    {
+      "entity": "customers:customer_entity",   // platform entity id (module:entity)
+      "match": ["id"],                          // optional idempotency keys (non-encrypted only)
+      "data": { "id": "…", "displayName": "Jane Doe", "primaryEmail": "…" }
+    }
+  ]
+}
+```
+
+- `data` keys are the **entity's property names** (camelCase, as declared on the
+  MikroORM entity), e.g. `displayName`, `primaryEmail`.
+- **Do not** put `tenantId`/`organizationId` in `data` — the loader injects the
+  target scope at load time, so the same blob seeds any tenant.
+- Records apply **in array order**; create parents before children for FK refs
+  (use explicit `id`s in `data` to reference them).
+- `match` enables idempotent re-runs (skip if a row already matches). Match fields
+  **must be non-encrypted natural keys** (`id`, `slug`, `code`, `*_hash`) —
+  encrypted fields have non-deterministic ciphertext and cannot be matched.
+
+See `examples/sample-seed.json` for a runnable template.
+
+## CLI
+
+```bash
+# 1. Generate a key once; distribute it out-of-band, never commit it.
+yarn mercato seeds keygen
+#   → prints a base64 32-byte key. Set OM_SEED_KEY=<key> for every participant.
+
+# 2. Author plaintext seed data locally (NOT committed), then encrypt it.
+OM_SEED_KEY=<key> yarn mercato seeds encrypt --in ./seed.json --out ./seed.enc.json
+#   → commit seed.enc.json (opaque); keep seed.json out of git (.gitignore).
+
+# 3. Edit later: decrypt → edit → re-encrypt.
+OM_SEED_KEY=<key> yarn mercato seeds decrypt --in ./seed.enc.json --out ./seed.json
+
+# 4. Load into a tenant (after `mercato auth setup` created the tenant/org).
+OM_SEED_KEY=<key> yarn mercato seeds load \
+  --in ./seed.enc.json --tenant <tenantId> --org <organizationId>
+
+#   Dry run (validates + reports counts, rolls back the transaction):
+OM_SEED_KEY=<key> yarn mercato seeds load --in ./seed.enc.json --tenant <t> --org <o> --dry-run
+
+#   Load an unencrypted file (local dev only):
+yarn mercato seeds load --in ./seed.json --tenant <t> --org <o> --plain
+```
+
+`--key <base64>` overrides `OM_SEED_KEY` on any command.
+
+## Hackathon flow
+
+1. Maintainer: `seeds keygen` → share the key privately with participants.
+2. Maintainer: author `seed.json`, `seeds encrypt` it, commit only `seed.enc.json`.
+3. Each participant: set `OM_SEED_KEY`, run `mercato auth setup …` to create their
+   tenant, then `mercato seeds load --in seed.enc.json --tenant <t> --org <o>`.
+
+The generic library lives in `@open-mercato/shared/lib/seed` (`crypto`, `loader`,
+`types`) and can be reused from a `setup.ts` `seedExamples` hook if you prefer
+automatic loading during `mercato auth setup --with-examples`.