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

package/src/helpers/integration/workflowsUi.ts

@@ -0,0 +1,318 @@
+import { expect, type Locator, type Page } from '@playwright/test'
+
+/**
+ * Shared browser-side helpers for the workflow Studio specs.
+ *
+ * The Studio is the ONLY workflow editor (workflows/AGENTS.md → "The Form Editor
+ * Is Retired"). Three facts about it broke every spec written against the old
+ * form editor, and each of them is centralised here so a future move is one
+ * edit rather than twenty:
+ *
+ * 1. **Definition metadata lives in a modal Drawer that starts CLOSED.**
+ *    `workflowId` / `workflowName` / `description` / triggers / `contextSchema`
+ *    are inside `DefinitionMetadataDrawer`, which the header does not expose
+ *    directly: it is the `Settings` entry of the header's `More` menu
+ *    (`ActionsDropdown`, so a `role="button"` named `More` opening
+ *    `role="menuitem"`s). They are plain `Input`s with `id=` — there is no
+ *    `data-crud-field-id` on definition metadata (that attribute survives only
+ *    inside the step/route inspectors, which do use `CrudForm`).
+ * 2. **The trigger summary is FOLDED onto the START node.** `TriggerCap` floats
+ *    above the START pill from inside that node's own render, so it adds no node
+ *    of its own — assert it with `WORKFLOW_TRIGGER_CAP_TESTID`. The separate
+ *    overlay node + dashed connector it replaced (`__workflow_trigger__`,
+ *    `components/nodes/TriggerNode.tsx`) are deprecated and no longer mounted;
+ *    `workflowStepNodes` / `workflowRouteEdges` still filter them out so a spec
+ *    counts the author's steps and routes either way.
+ * 3. **The step and route inspectors are a wide overlay `Drawer`.** Both forms
+ *    outgrew the 384px docked rail, so each now opens as the wide modal Drawer
+ *    that mirrors the definition metadata drawer, whatever the viewport. The
+ *    `docked` variant of `InspectorPanel` (an `<aside role="complementary">` in
+ *    the editor row) is still supported by the component but no longer mounted
+ *    by the Studio. BOTH variants carry `data-slot="workflow-inspector"` plus a
+ *    `data-variant`, so `workflowInspector` matches either and a spec never has
+ *    to know which layout it got.
+ */
+
+export const WORKFLOW_TRIGGER_NODE_ID = '__workflow_trigger__'
+export const WORKFLOW_TRIGGER_EDGE_ID = '__workflow_trigger_edge__'
+
+/** Accessible name of the Studio header's overflow menu (`workflows.visualEditor.more`). */
+export const WORKFLOW_MORE_MENU_LABEL = 'More'
+/** The menu entry that opens the metadata drawer (`workflows.visualEditor.metadata.buttonLabel`). */
+export const WORKFLOW_DETAILS_MENU_ITEM_LABEL = 'Settings'
+/** The menu entry that drops a customized definition back to its code version. */
+export const WORKFLOW_RESET_TO_CODE_MENU_ITEM_LABEL = 'Reset to code version'
+/**
+ * The menu entry that opens the read/edit Code view
+ * (`workflows.visualEditor.codeView.title`).
+ *
+ * It used to be a header BUTTON labelled "Show the definition JSON"
+ * (`…codeView.open`); the toolbar declutter moved it into the More menu under
+ * the shorter "Code".
+ */
+export const WORKFLOW_CODE_VIEW_MENU_ITEM_LABEL = 'Code'
+export const WORKFLOW_DETAILS_DRAWER_TITLE = 'Workflow details'
+export const WORKFLOW_INSPECTOR_SELECTOR = '[data-slot="workflow-inspector"]'
+/** The START node's trigger cap — the only affordance that opens `TriggersDialog`. */
+export const WORKFLOW_TRIGGER_CAP_TESTID = 'workflow-trigger-cap'
+/** The add button inside `TriggersDialog` (`workflows.triggers.add`). */
+export const WORKFLOW_ADD_TRIGGER_LABEL = 'Add Trigger'
+
+export function visualEditorHref(definitionId?: string | null): string {
+  return definitionId
+    ? `/backend/definitions/visual-editor?id=${encodeURIComponent(definitionId)}`
+    : '/backend/definitions/visual-editor'
+}
+
+/**
+ * The author's steps, without the render-time trigger pill.
+ */
+export function workflowStepNodes(page: Page): Locator {
+  return page.locator(`.react-flow__node:not([data-id="${WORKFLOW_TRIGGER_NODE_ID}"])`)
+}
+
+/**
+ * The element carrying a node's OWN label (`WORKFLOW_NODE_TITLE_SLOT`).
+ *
+ * A whole-card text match is NOT a way to find a node by name: every card also
+ * renders an unconditional `sr-only` status name (spec §4.6 — status is never
+ * colour-only), which in the editor is always "Not started". Playwright's
+ * `hasText` is a case-insensitive SUBSTRING match, so `hasText: 'Start'` over a
+ * card matches "Not started" and therefore matches every node on the canvas.
+ * The START node compounds it: its trigger cap says "manual / API start".
+ */
+export const WORKFLOW_NODE_TITLE_SELECTOR = '[data-slot="workflow-node-title"]'
+
+function escapeForRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/**
+ * The single author step whose label is exactly `title`.
+ *
+ * Scoped to the title element and anchored, so it neither matches the status
+ * copy nor a longer label that merely contains this one.
+ */
+export function workflowNodeByTitle(page: Page, title: string): Locator {
+  return workflowStepNodes(page).filter({
+    has: page.locator(WORKFLOW_NODE_TITLE_SELECTOR, {
+      hasText: new RegExp(`^\\s*${escapeForRegExp(title)}\\s*$`),
+    }),
+  })
+}
+
+/**
+ * The author's routes, without the trigger pill's connector.
+ */
+export function workflowRouteEdges(page: Page): Locator {
+  return page.locator(`.react-flow__edge:not([data-id="${WORKFLOW_TRIGGER_EDGE_ID}"])`)
+}
+
+/**
+ * The step/route inspector, docked at >=1280px and a modal Drawer below it.
+ * Distinguish the two by heading: "Edit Step" vs "Edit Transition".
+ */
+export function workflowInspector(page: Page): Locator {
+  return page.locator(WORKFLOW_INSPECTOR_SELECTOR)
+}
+
+export function workflowDetailsDrawer(page: Page): Locator {
+  return page.getByRole('dialog', { name: WORKFLOW_DETAILS_DRAWER_TITLE })
+}
+
+/**
+ * Open the Studio on an existing definition and wait for the canvas to paint.
+ *
+ * Goes straight to `/backend/definitions/visual-editor?id=…` rather than through
+ * the `/backend/definitions/<id>` bridge route: the bridge only exists so old
+ * bookmarks keep working and costs a client-side `router.replace`.
+ */
+export async function openWorkflowStudio(page: Page, definitionId: string): Promise<void> {
+  await page.goto(visualEditorHref(definitionId))
+  await expect(workflowStepNodes(page).first()).toBeVisible({ timeout: 30_000 })
+}
+
+/** The Studio header's overflow-menu trigger. */
+export function workflowHeaderMenuTrigger(page: Page): Locator {
+  return page.getByRole('button', { name: WORKFLOW_MORE_MENU_LABEL, exact: true })
+}
+
+/**
+ * One entry of the header's overflow menu.
+ *
+ * `ActionsDropdown` renders entries as `<Button role="menuitem">`, so the
+ * explicit role wins over the implicit one and `getByRole('button', …)` never
+ * matches them — and nothing is in the DOM at all until the menu is open.
+ */
+export function workflowHeaderMenuItem(page: Page, label: string): Locator {
+  return page.getByRole('menuitem', { name: label, exact: true })
+}
+
+/**
+ * Open the header's overflow menu.
+ *
+ * Hover, never click. `ActionsDropdown` opens on `mouseenter` and its trigger
+ * *toggles* on click, so Playwright's `click()` — which moves the pointer over
+ * the element first — opens the menu on the way in and closes it again on the
+ * press. The row-action menus in these specs are driven the same way.
+ */
+export async function openWorkflowHeaderMenu(page: Page): Promise<void> {
+  await workflowHeaderMenuTrigger(page).hover()
+}
+
+/**
+ * Close the header's overflow menu by moving the pointer off it.
+ *
+ * `handleMouseLeave` closes on a 150 ms timer, so callers that go on to touch
+ * the page underneath should await this rather than race the overlay.
+ */
+export async function closeWorkflowHeaderMenu(page: Page, label: string): Promise<void> {
+  await page.mouse.move(0, 0)
+  await expect(workflowHeaderMenuItem(page, label)).toBeHidden({ timeout: 10_000 })
+}
+
+/**
+ * Run a Studio command from the Cmd/Ctrl+K palette.
+ *
+ * The palette is the complete non-pointer path (spec section 4.6), and it is
+ * also the only way to reach an action the header renders no button for — Save
+ * among them.
+ */
+export async function runWorkflowPaletteCommand(page: Page, query: string): Promise<void> {
+  await page.keyboard.press('ControlOrMeta+k')
+  const search = page.getByPlaceholder('Search commands…')
+  await expect(search).toBeVisible({ timeout: 15_000 })
+  await search.fill(query)
+  await expect(page.getByRole('option').filter({ hasText: query }).first()).toBeVisible({ timeout: 15_000 })
+  await page.keyboard.press('Enter')
+  await expect(search).toBeHidden({ timeout: 15_000 })
+}
+
+/**
+ * Predicate matching the Studio's SAVE, and nothing else.
+ *
+ * The editor also autosaves to `…/definitions/<id>/draft`, so a `url.includes(id)
+ * && method === 'PUT'` matcher — what these specs used to write — is satisfied by
+ * the autosave. A spec then walks on to read the definition the save never wrote
+ * and reports a persistence bug that is not there (TC-WF-037 did exactly this).
+ * Matching the pathname's END keeps the draft out.
+ */
+export function isWorkflowDefinitionSave(response: { url(): string; request(): { method(): string } }, definitionId: string): boolean {
+  if (response.request().method() !== 'PUT') return false
+  try {
+    return new URL(response.url()).pathname.endsWith(`/api/workflows/definitions/${definitionId}`)
+  } catch {
+    return false
+  }
+}
+
+/** Open the header's overflow menu and pick `label`. */
+export async function invokeWorkflowHeaderAction(page: Page, label: string): Promise<void> {
+  await openWorkflowHeaderMenu(page)
+  await workflowHeaderMenuItem(page, label).click()
+}
+
+/**
+ * Assert a header action is offered, then close the menu again.
+ *
+ * The pre-Studio header rendered these as always-visible buttons, so specs used
+ * to assert availability with a bare `toBeVisible()`; the equivalent now is
+ * "the menu offers it".
+ */
+export async function expectWorkflowHeaderAction(
+  page: Page,
+  label: string,
+  { available = true }: { available?: boolean } = {},
+): Promise<void> {
+  await openWorkflowHeaderMenu(page)
+  const item = workflowHeaderMenuItem(page, label)
+  if (available) await expect(item).toBeVisible({ timeout: 10_000 })
+  else await expect(item).toHaveCount(0)
+  await closeWorkflowHeaderMenu(page, label)
+}
+
+/**
+ * Open the focused Triggers modal and wait for it.
+ *
+ * Triggers are NOT part of the definition drawer. The Studio routes them
+ * through `TriggersDialog`, opened from the START node's trigger cap on the
+ * canvas — page.tsx puts it plainly: the author clicked "what starts this", so
+ * the affordance opens exactly that, "NOT the five-section definition drawer".
+ * (The older `DefinitionTriggersEditor` survives only in the mobile sheet.)
+ */
+export async function openWorkflowTriggersDialog(page: Page): Promise<void> {
+  await page.getByTestId(WORKFLOW_TRIGGER_CAP_TESTID).click()
+  await expect(page.getByRole('button', { name: WORKFLOW_ADD_TRIGGER_LABEL })).toBeVisible({
+    timeout: 15_000,
+  })
+}
+
+/**
+ * Open the definition-metadata drawer and wait for it.
+ *
+ * Every metadata field is unmounted until this runs, which is why so many specs
+ * time out on a field that does still exist.
+ */
+export async function openWorkflowDetailsDrawer(page: Page): Promise<Locator> {
+  const drawer = workflowDetailsDrawer(page)
+  if (!(await drawer.isVisible().catch(() => false))) {
+    await invokeWorkflowHeaderAction(page, WORKFLOW_DETAILS_MENU_ITEM_LABEL)
+  }
+  await expect(drawer).toBeVisible({ timeout: 15_000 })
+  return drawer
+}
+
+/**
+ * Save from INSIDE the drawer.
+ *
+ * With the drawer open there are two buttons named `Save`/`Update` — the page
+ * header's and the drawer footer's — so an unscoped `getByRole('button', …)`
+ * fails Playwright's strict mode. The drawer's button submits the same
+ * `handleSave`, header and all.
+ */
+export async function saveWorkflowFromDetailsDrawer(page: Page): Promise<void> {
+  const drawer = workflowDetailsDrawer(page)
+  await drawer.getByRole('button', { name: /^(save|update)$/i }).click()
+}
+
+/**
+ * The Studio's "Show last run" execution overlay (spec §8.3).
+ *
+ * The toggle is off by default and PERSISTED per author
+ * (`om:wf-editor-last-run`), and it fetches nothing until it is on — so a spec
+ * must click it, and a spec must not assume a previous test left it on.
+ *
+ * It is a header BUTTON rather than a More-menu entry, unlike the other view
+ * toggles: it is stateful (`aria-pressed`) and it reports "(never run)" beside
+ * its label, neither of which a fire-and-forget menu item can carry.
+ */
+export const WORKFLOW_LAST_RUN_TOGGLE_LABEL = 'Show the last run on the canvas'
+
+export function workflowLastRunToggle(page: Page): Locator {
+  return page.getByRole('button', { name: WORKFLOW_LAST_RUN_TOGGLE_LABEL })
+}
+
+/**
+ * The run status the canvas painted for one step, read off the node card's
+ * `data-node-status` attribute.
+ *
+ * The value is a `WorkflowStatus`, not the `StepRunStatus` the overlay derives:
+ * each node component funnels `data.status` through `toWorkflowStatus`, which
+ * collapses `active` to `in_progress` and anything it does not know (including
+ * an absent status, i.e. the plain editor) to `not_started`.
+ */
+export function workflowNodeStatus(page: Page, stepId: string): Locator {
+  return page.locator(`.react-flow__node[data-id="${stepId}"] [data-node-status]`).first()
+}
+
+/**
+ * The visible stroke of one route. The overlay paints a TAKEN route by setting
+ * the edge's `state` to `completed`, which reaches the DOM only as the inline
+ * `stroke` (there is no `data-*` marker), so `EDGE_COLORS.completed.stroke` —
+ * `var(--status-success-icon)` — is what a spec has to look for.
+ */
+export function workflowEdgePath(page: Page, transitionId: string): Locator {
+  return page.locator(`.react-flow__edge[data-id="${transitionId}"] path.react-flow__edge-path`).first()
+}
+
+export const WORKFLOW_TAKEN_ROUTE_STROKE = 'var(--status-success-icon)'

package/src/modules/attachments/lib/createFromBuffer.ts

@@ -0,0 +1,120 @@
+import { randomUUID } from 'node:crypto'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { emitCrudSideEffects } from '@open-mercato/shared/lib/commands/helpers'
+import { Attachment, AttachmentPartition } from '../data/entities'
+import { StorageDriverFactory } from './drivers'
+import { ensureDefaultPartitions, resolveDefaultPartitionCode } from './partitions'
+import { buildAttachmentFileUrl } from './imageUrls'
+import { mergeAttachmentMetadata, upsertAssignment } from './metadata'
+import { assertAttachmentScopeInvariant } from './access'
+import { attachmentCrudEvents, attachmentCrudIndexer } from './crud'
+
+/** DataEngine handle whose exact type is derived from `emitCrudSideEffects` (no `any`). */
+type CrudDataEngine = Parameters<typeof emitCrudSideEffects>[0]['dataEngine']
+
+export type CreateAttachmentFromBufferInput = {
+  em: EntityManager
+  /** When provided, fires CRUD side effects (events + indexing). Omit to skip. */
+  dataEngine?: CrudDataEngine
+  tenantId: string
+  organizationId: string
+  /** Domain entity this attachment is linked to (e.g. 'customers:deal'). */
+  entityId: string
+  recordId: string
+  fileName: string
+  mimeType: string
+  buffer: Buffer
+  /** Storage partition; defaults to the entity's default partition. */
+  partitionCode?: string | null
+}
+
+export type CreatedAttachment = {
+  id: string
+  fileName: string
+  mimeType: string
+  fileSize: number
+  url: string
+}
+
+/**
+ * Create a durable `Attachment` from an in-memory buffer, linked to a domain
+ * record. Additive reusable seam extracted from the upload route's store block so
+ * server-side producers (e.g. the agent file-plane artifact-promotion effector,
+ * #12) can materialize an attachment without going through the multipart HTTP
+ * route. Resolves the partition + driver, stores the bytes, persists the row
+ * atomically, and (when a `dataEngine` is passed) fires CRUD side effects so the
+ * attachment is indexed and its events emitted — exactly like an uploaded file.
+ */
+export async function createAttachmentFromBuffer(input: CreateAttachmentFromBufferInput): Promise<CreatedAttachment> {
+  const { em } = input
+  const code = (input.partitionCode && input.partitionCode.length > 0)
+    ? input.partitionCode
+    : resolveDefaultPartitionCode(input.entityId)
+
+  let partition = await em.findOne(AttachmentPartition, { code })
+  if (!partition) {
+    await ensureDefaultPartitions(em)
+    partition = await em.findOne(AttachmentPartition, { code })
+  }
+  if (!partition) throw new Error(`[internal] attachment partition "${code}" is not available`)
+
+  const driver = await new StorageDriverFactory(em).resolveForPartition(partition.code, {
+    tenantId: input.tenantId,
+    organizationId: input.organizationId,
+  })
+  const stored = await driver.store({
+    partitionCode: partition.code,
+    orgId: input.organizationId,
+    tenantId: input.tenantId,
+    fileName: input.fileName,
+    buffer: input.buffer,
+  })
+
+  const metadata = mergeAttachmentMetadata(null, {
+    assignments: upsertAssignment([], { type: input.entityId, id: input.recordId }),
+  })
+  const attachmentId = randomUUID()
+  assertAttachmentScopeInvariant({ tenantId: input.tenantId, organizationId: input.organizationId })
+  const attachment = em.create(Attachment, {
+    id: attachmentId,
+    entityId: input.entityId,
+    recordId: input.recordId,
+    organizationId: input.organizationId,
+    tenantId: input.tenantId,
+    fileName: input.fileName,
+    mimeType: input.mimeType,
+    fileSize: input.buffer.length,
+    partitionCode: partition.code,
+    storageDriver: partition.storageDriver || 'local',
+    storagePath: stored.storagePath,
+    url: buildAttachmentFileUrl(attachmentId),
+    content: null,
+    storageMetadata: metadata,
+  })
+  await em.transactional(async (tx) => {
+    await tx.persist(attachment).flush()
+  })
+
+  if (input.dataEngine) {
+    await emitCrudSideEffects({
+      dataEngine: input.dataEngine,
+      action: 'created',
+      entity: attachment,
+      identifiers: {
+        id: attachment.id,
+        organizationId: attachment.organizationId ?? null,
+        tenantId: attachment.tenantId ?? null,
+      },
+      events: attachmentCrudEvents,
+      indexer: attachmentCrudIndexer,
+    })
+  }
+
+  return {
+    id: attachmentId,
+    fileName: input.fileName,
+    mimeType: input.mimeType,
+    fileSize: input.buffer.length,
+    url: attachment.url,
+  }
+}

package/src/modules/audit_logs/data/entities.ts

@@ -6,6 +6,7 @@ export type ActionLogExecutionState = 'done' | 'undoing' | 'undone' | 'failed' |
 @Entity({ tableName: 'action_logs' })
 @Index({ name: 'action_logs_tenant_idx', properties: ['tenantId', 'createdAt'] })
 @Index({ name: 'action_logs_actor_idx', properties: ['actorUserId', 'createdAt'] })
+@Index({ name: 'action_logs_obo_idx', properties: ['onBehalfOfUserId'] })
 @Index({ name: 'action_logs_resource_idx', properties: ['tenantId', 'resourceKind', 'resourceId', 'createdAt'] })
 @Index({ name: 'action_logs_parent_resource_idx', properties: ['tenantId', 'parentResourceKind', 'parentResourceId', 'createdAt'] })
 @Index({ name: 'action_logs_action_type_idx', properties: ['tenantId', 'organizationId', 'actionType', 'createdAt'] })
@@ -26,6 +27,17 @@ export class ActionLog {
   @Property({ name: 'actor_user_id', type: 'uuid', nullable: true })
   actorUserId: string | null = null
 
+  /**
+   * The human (or system) principal an agent acted on behalf of. Null for direct
+   * human/system/api actions; set to the invoking human's `auth.User` id when the
+   * actor (`actorUserId`) is an agent principal running under `runAs` with
+   * `sourceKey = 'agent'`. FK id → `auth.User` (no cross-module ORM relation).
+   * Additive, nullable, indexed (`action_logs_obo_idx`); existing rows default null
+   * so no existing audit reader breaks (Agent Identity & On-Behalf-Of, Wave 4 P2).
+   */
+  @Property({ name: 'on_behalf_of_user_id', type: 'uuid', nullable: true })
+  onBehalfOfUserId: string | null = null
+
   @Property({ name: 'command_id', type: 'text' })
   commandId!: string
 

package/src/modules/audit_logs/data/validators.ts

@@ -16,6 +16,7 @@ const recordLike = z.union([
 
 export const actionLogCreateSchema = baseScopeSchema.extend({
   commandId: z.string().min(1),
+  onBehalfOfUserId: uuid.nullish(),
   actionLabel: z.string().min(1).optional(),
   resourceKind: z.string().min(1).optional(),
   resourceId: z.string().min(1).optional(),

package/src/modules/audit_logs/lib/projections.ts

@@ -2,7 +2,7 @@ import { extractChangeRows, isRecord } from './changeRows'
 
 export const ACTION_LOG_FILTER_TYPES = ['create', 'edit', 'delete', 'assign'] as const
 export const ACTION_LOG_PROJECTION_TYPES = [...ACTION_LOG_FILTER_TYPES, 'system'] as const
-export const ACTION_LOG_SOURCE_KEYS = ['ui', 'api', 'system'] as const
+export const ACTION_LOG_SOURCE_KEYS = ['ui', 'api', 'system', 'agent'] as const
 
 export type ActionLogFilterType = (typeof ACTION_LOG_FILTER_TYPES)[number]
 export type ActionLogProjectionType = (typeof ACTION_LOG_PROJECTION_TYPES)[number]
@@ -76,6 +76,10 @@ export function deriveActionLogSource(
   if (normalizedSource === 'api') return 'api'
   if (normalizedSource === 'system') return 'system'
   if (normalizedSource === 'ui') return 'ui'
+  // Agent-attributed writes flow through the same Command path as a human's; the
+  // `runAs` wrapper stamps `context.source = 'agent'` so the action is sourced to
+  // the agent principal (actorUserId) rather than defaulting to 'ui'.
+  if (normalizedSource === 'agent') return 'agent'
 
   return actorUserId ? 'ui' : 'system'
 }

package/src/modules/audit_logs/migrations/.snapshot-open-mercato.json

@@ -301,6 +301,22 @@
           "enumItems": [],
           "mappedType": "uuid"
         },
+        "on_behalf_of_user_id": {
+          "name": "on_behalf_of_user_id",
+          "type": "uuid",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": true,
+          "unique": false,
+          "length": null,
+          "precision": null,
+          "scale": null,
+          "default": null,
+          "comment": null,
+          "enumItems": [],
+          "mappedType": "uuid"
+        },
         "command_id": {
           "name": "command_id",
           "type": "text",
@@ -755,6 +771,16 @@
           "primary": false,
           "unique": false
         },
+        {
+          "keyName": "action_logs_obo_idx",
+          "columnNames": [
+            "on_behalf_of_user_id"
+          ],
+          "composite": false,
+          "constraint": false,
+          "primary": false,
+          "unique": false
+        },
         {
           "keyName": "action_logs_tenant_idx",
           "columnNames": [

package/src/modules/audit_logs/migrations/Migration20260625120000.ts

@@ -0,0 +1,15 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20260625120000 extends Migration {
+
+  override up(): void | Promise<void> {
+    this.addSql(`alter table "action_logs" add column "on_behalf_of_user_id" uuid null;`);
+    this.addSql(`create index "action_logs_obo_idx" on "action_logs" ("on_behalf_of_user_id");`);
+  }
+
+  override down(): void | Promise<void> {
+    this.addSql(`drop index "action_logs_obo_idx";`);
+    this.addSql(`alter table "action_logs" drop column "on_behalf_of_user_id";`);
+  }
+
+}

package/src/modules/audit_logs/services/actionLogService.ts

@@ -310,6 +310,7 @@ export class ActionLogService {
       tenantId: data.tenantId ?? null,
       organizationId: data.organizationId ?? null,
       actorUserId: data.actorUserId ?? null,
+      onBehalfOfUserId: data.onBehalfOfUserId ?? null,
       commandId: data.commandId,
       actionLabel: data.actionLabel ?? null,
       actionType: projection.actionType,
@@ -340,6 +341,7 @@ export class ActionLogService {
         tenantId: null,
         organizationId: null,
         actorUserId: null,
+        onBehalfOfUserId: null,
         commandId: 'unknown',
         actionLabel: undefined,
         resourceKind: undefined,
@@ -373,6 +375,7 @@ export class ActionLogService {
       tenantId: toNullableUuid(input.tenantId),
       organizationId: toNullableUuid(input.organizationId),
       actorUserId: normalizeActorUserId(input.actorUserId),
+      onBehalfOfUserId: toNullableUuid(input.onBehalfOfUserId),
       commandId: typeof input.commandId === 'string' && input.commandId.length > 0 ? input.commandId : 'unknown',
       actionLabel: toOptionalString(input.actionLabel) ?? undefined,
       resourceKind: toOptionalString(input.resourceKind) ?? undefined,

package/src/modules/auth/data/entities.ts

@@ -1,5 +1,16 @@
+import { OptionalProps } from '@mikro-orm/core'
 import { Entity, Index, ManyToOne, PrimaryKey, Property, Unique } from '@mikro-orm/decorators/legacy'
 
+/**
+ * The principal kind a `User` row represents. `human` (the default) is an
+ * interactively-authenticating person; `agent` is a non-interactive AI principal
+ * provisioned by the agent_orchestrator module (it owns no interactive credential
+ * and is barred from the password/SSO login flow); `service` is reserved for
+ * machine/system principals. Added additively (NOT NULL, default `'human'`) so
+ * every existing row backfills to `human` and no existing reader breaks.
+ */
+export type UserKind = 'human' | 'agent' | 'service'
+
 @Entity({ tableName: 'users' })
 // Email uniqueness is per-tenant, enforced by a partial unique index
 // (`users_tenant_email_hash_uniq`) on `(tenant_id, email_hash)` over live rows
@@ -12,6 +23,11 @@ import { Entity, Index, ManyToOne, PrimaryKey, Property, Unique } from '@mikro-o
 // login flow and leaks cross-tenant account existence (#2934). Mirrors
 // `customer_users_tenant_email_hash_uniq`.
 export class User {
+  // `kind` carries a default ('human'); marking it optional keeps every existing
+  // `em.create(User, …)` caller (which never passed `kind`) compiling unchanged —
+  // the additive column is backfilled by the default at the DB + entity level.
+  [OptionalProps]?: 'kind'
+
   @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
   id!: string
 
@@ -37,6 +53,11 @@ export class User {
   @Property({ name: 'is_confirmed', type: 'boolean', default: true })
   isConfirmed: boolean = true
 
+  // Principal kind. Default 'human' keeps every existing row + external reader
+  // unaffected; 'agent' marks a non-interactive AI principal (see UserKind).
+  @Property({ name: 'kind', type: 'varchar', length: 20, default: 'human' })
+  kind: UserKind = 'human'
+
   @Property({ name: 'last_login_at', type: Date, nullable: true })
   lastLoginAt?: Date