@open-mercato/ai-assistant 0.6.7 → 0.6.8-develop.6874.1.982d6097d8

package/src/modules/ai_assistant/lib/agent-runtime.ts

@@ -27,6 +27,20 @@ import {
 import type { StopCondition } from 'ai'
 import type { ZodTypeAny } from 'zod'
 import { createModelFactory, resolveAllowRuntimeOverride } from './model-factory'
+import { computeEndUserIdentifier } from '@open-mercato/shared/lib/ai/safety-identifier'
+import { llmProviderRegistry } from '@open-mercato/shared/lib/ai/llm-provider-registry'
+import type { EnvLookup } from '@open-mercato/shared/lib/ai/llm-provider'
+import {
+  AiModerationBlockedError,
+  AiModerationUnavailableError,
+  type ModerationService,
+} from './moderation'
+import {
+  isModerationActive,
+  resolveModerationPolicy,
+  shouldFailClosed,
+} from './moderation-policy'
+import { recordModerationFlag } from './moderation-flag-recorder'
 import type {
   AiAgentDefinition,
   AiAgentLoopConfig,
@@ -342,6 +356,16 @@ export interface PreparedAiSdkOptions {
    * Phase 5 of spec `2026-04-28-ai-agents-agentic-loop-controls`.
    */
   toolLoopAgent?: ToolLoopAgent<never, ToolSet>
+  /**
+   * Provider-specific `providerOptions` fragment carrying the mapped end-user
+   * safety identifier (e.g. OpenAI `safety_identifier`). Present only when an
+   * identifier was derived and the resolved provider supports the mapping.
+   * Callers using the `generateText` escape-hatch MUST forward it to the SDK
+   * call so the identifier reaches the provider.
+   *
+   * Spec `2026-06-04-ai-input-moderation-and-safety-identifiers`.
+   */
+  providerOptions?: Record<string, unknown>
 }
 
 /**
@@ -968,6 +992,15 @@ interface ResolvedAgentModel {
   model: LanguageModel
   modelId: string
   providerId: string
+  /**
+   * Provider-specific `providerOptions` fragment carrying the mapped end-user
+   * safety identifier (undefined when no identifier or no provider mapping).
+   */
+  providerOptions?: Record<string, unknown>
+  /** Whether the resolved chat provider supports input moderation. */
+  supportsInputModeration: boolean
+  /** Resolved base URL (if any), reused by the moderation endpoint call. */
+  baseURL?: string
 }
 
 function resolveAgentModel(
@@ -979,6 +1012,7 @@ function resolveAgentModel(
   tenantOverride?: { providerId?: string | null; modelId?: string | null; baseURL?: string | null } | null,
   requestOverride?: { providerId?: string | null; modelId?: string | null; baseURL?: string | null } | null,
   tenantAllowlist?: TenantAllowlistSnapshot | null,
+  endUserIdentifier?: string,
 ): ResolvedAgentModel {
   const effectiveContainer = container ?? createContainer()
   const resolution = createModelFactory(effectiveContainer).resolveModel({
@@ -993,11 +1027,145 @@ function resolveAgentModel(
     tenantOverride: tenantOverride ?? undefined,
     requestOverride: requestOverride ?? undefined,
     tenantAllowlist: tenantAllowlist ?? null,
+    endUserIdentifier,
   })
   return {
     model: resolution.model as LanguageModel,
     modelId: resolution.modelId,
     providerId: resolution.providerId,
+    providerOptions: resolution.providerOptions,
+    supportsInputModeration: resolution.supportsInputModeration === true,
+    baseURL: resolution.baseURL,
+  }
+}
+
+/**
+ * Concatenates the text parts of the most recent user message. Only the new
+ * user turn is moderated (prior history was screened on its own turn). Returns
+ * an empty string when there is no user message or no text content.
+ */
+export function extractLatestUserText(messages: UIMessage[]): string {
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    const raw = messages[index] as unknown as {
+      role?: string
+      content?: string
+      parts?: Array<{ type?: string; text?: string }>
+    }
+    if (raw.role !== 'user') continue
+    if (Array.isArray(raw.parts)) {
+      return raw.parts
+        .filter((part) => part?.type === 'text' && typeof part.text === 'string')
+        .map((part) => part.text as string)
+        .join('\n')
+    }
+    return typeof raw.content === 'string' ? raw.content : ''
+  }
+  return ''
+}
+
+export interface InputModerationGateParams {
+  untrustedInput?: boolean
+  supportsInputModeration: boolean
+  userText: string
+  service: ModerationService | null
+  /**
+   * Lazy resolver for the moderation provider's API key. Invoked only when the
+   * gate actually proceeds (policy active, provider supports moderation, text
+   * non-empty, service present) — so callers never pay for (or fail on) key
+   * resolution on the common skip paths.
+   */
+  resolveApiKey: () => string | null
+  baseURL?: string
+  moderationModel?: string
+  perAgentOverride?: boolean | null
+  tenantWideOverride?: boolean | null
+  env?: EnvLookup
+  /**
+   * Best-effort side effect invoked with the flagged categories right before
+   * the gate throws {@link AiModerationBlockedError}. Phase 3 wires the audit
+   * insert + event emit here; it MUST NOT throw (failures are swallowed by the
+   * caller) and MUST NOT block the rejection.
+   */
+  onFlagged?: (categories: Record<string, { flagged: boolean; score: number }>) => void | Promise<void>
+}
+
+/**
+ * Pre-loop input moderation gate. Runs the moderation check for the current
+ * user turn before the model call. Decoupled from the registry/container so it
+ * is unit-testable: the caller resolves the {@link ModerationService} and API
+ * key. Throws {@link AiModerationBlockedError} when flagged; honors
+ * fail-closed (enforced) vs fail-open (opt-in) on endpoint unavailability.
+ */
+export async function runInputModerationGate(params: InputModerationGateParams): Promise<void> {
+  const policy = resolveModerationPolicy({
+    untrustedInput: params.untrustedInput,
+    perAgentOverride: params.perAgentOverride,
+    tenantWideOverride: params.tenantWideOverride,
+    env: params.env,
+  })
+  if (!isModerationActive(policy)) return
+  // The resolved chat provider has no moderation endpoint — rely on its own
+  // server-side filtering and skip the gate.
+  if (!params.supportsInputModeration) return
+  const text = params.userText.trim()
+  if (!text) return
+
+  const failClosed = shouldFailClosed(policy)
+  const failOpenOrThrow = (reason: string, error?: unknown): void => {
+    if (failClosed) {
+      if (error instanceof AiModerationUnavailableError) throw error
+      throw new AiModerationUnavailableError(reason, error)
+    }
+    logger.warn('Input moderation unavailable; failing open for opt-in surface', { reason })
+  }
+
+  if (!params.service) {
+    return failOpenOrThrow('moderation service is not available in the container')
+  }
+  const apiKey = params.resolveApiKey()
+  if (!apiKey) {
+    return failOpenOrThrow('no API key available for the moderation provider')
+  }
+
+  let result
+  try {
+    result = await params.service.checkInput({
+      text,
+      apiKey,
+      baseURL: params.baseURL,
+      model: params.moderationModel,
+    })
+  } catch (error) {
+    if (error instanceof AiModerationUnavailableError) {
+      return failOpenOrThrow(error.message, error)
+    }
+    throw error
+  }
+
+  if (result.flagged) {
+    if (params.onFlagged) {
+      try {
+        await params.onFlagged(result.categories)
+      } catch (error) {
+        logger.error('Moderation flag side effect failed (rejection still applies)', { err: error })
+      }
+    }
+    throw new AiModerationBlockedError(result.categories)
+  }
+}
+
+/**
+ * Compute the tenant-salted end-user safety identifier for a chat turn,
+ * best-effort. Returns undefined (never throws) so a derivation failure — e.g.
+ * a missing base secret in a misconfigured environment — degrades to "no
+ * identifier attached" instead of breaking the chat. Failures are logged.
+ */
+function resolveEndUserIdentifier(authContext: AiChatRequestContext): string | undefined {
+  try {
+    return computeEndUserIdentifier(authContext.tenantId, authContext.userId)
+  } catch (error) {
+    logger.warn('Failed to derive end-user safety identifier', { err: error })
+    return undefined
   }
 }
 
@@ -1198,6 +1366,44 @@ async function resolveRuntimeModelOverride(
   }
 }
 
+/**
+ * Resolves the per-agent and tenant-wide `input_moderation` override values for
+ * the moderation policy precedence. Best-effort and fail-open (returns nulls on
+ * any error so the gate falls back to the env default). Returns the two values
+ * separately because the precedence treats per-agent and tenant-wide as
+ * distinct steps.
+ */
+async function resolveModerationOverrideValues(
+  container: AwilixContainer | undefined,
+  tenantId: string | null,
+  organizationId: string | null,
+  agentId: string,
+): Promise<{ perAgentOverride: boolean | null; tenantWideOverride: boolean | null }> {
+  const empty = { perAgentOverride: null, tenantWideOverride: null }
+  if (!tenantId || !container) return empty
+  let em: EntityManager | null = null
+  try {
+    em = container.resolve<EntityManager>('em')
+  } catch {
+    em = null
+  }
+  if (!em) return empty
+  try {
+    const repo = new AiAgentRuntimeOverrideRepository(em)
+    const [agentRow, tenantRow] = await Promise.all([
+      repo.getExact({ tenantId, organizationId: organizationId ?? null, agentId }),
+      repo.getDefault({ tenantId, organizationId: organizationId ?? null, agentId: null }),
+    ])
+    return {
+      perAgentOverride: agentRow?.inputModeration ?? null,
+      tenantWideOverride: tenantRow?.inputModeration ?? null,
+    }
+  } catch (error) {
+    logger.warn('Moderation override lookup failed; falling back to env default', { agentId, err: error })
+    return empty
+  }
+}
+
 /**
  * Normalizes simple `{ role, content }` chat messages into the AI SDK
  * `UIMessage` shape that `convertToModelMessages` requires. When the
@@ -1484,9 +1690,59 @@ export async function runAiAgentText(input: RunAiAgentTextInput): Promise<Respon
     tenantRuntimeOverride,
     input.requestOverride,
     tenantAllowlistSnapshot,
+    resolveEndUserIdentifier(input.authContext),
   )
   const { model } = resolvedModel
+  const modelProviderOptions = resolvedModel.providerOptions
   const normalizedMessages = ensureUiMessageShape(input.messages)
+
+  // Pre-loop input moderation gate (spec 2026-06-04). Runs before the model
+  // call on enabled/enforced surfaces where the provider supports moderation.
+  // Throws AiModerationBlockedError (flagged) or AiModerationUnavailableError
+  // (enforced + outage); both are surfaced by the SSE error path.
+  let moderationService: ModerationService | null = null
+  try {
+    moderationService = input.container?.resolve<ModerationService>('moderationService') ?? null
+  } catch {
+    moderationService = null
+  }
+  // Read tenant overrides only when the provider can moderate and the agent is
+  // not already enforced (untrustedInput short-circuits to enforced) — avoids a
+  // DB round-trip on the common skip paths.
+  const moderationOverrides =
+    resolvedModel.supportsInputModeration && agent.untrustedInput !== true
+      ? await resolveModerationOverrideValues(
+          input.container,
+          input.authContext.tenantId,
+          input.authContext.organizationId,
+          agent.id,
+        )
+      : { perAgentOverride: null, tenantWideOverride: null }
+  await runInputModerationGate({
+    untrustedInput: agent.untrustedInput,
+    supportsInputModeration: resolvedModel.supportsInputModeration,
+    perAgentOverride: moderationOverrides.perAgentOverride,
+    tenantWideOverride: moderationOverrides.tenantWideOverride,
+    userText: extractLatestUserText(normalizedMessages),
+    service: moderationService,
+    resolveApiKey: () => llmProviderRegistry.get(resolvedModel.providerId)?.resolveApiKey() ?? null,
+    baseURL: resolvedModel.baseURL,
+    moderationModel: process.env.OM_AI_MODERATION_MODEL,
+    onFlagged: (categories) =>
+      recordModerationFlag(
+        {
+          tenantId: input.authContext.tenantId,
+          organizationId: input.authContext.organizationId,
+          agentId: agent.id,
+          userId: input.authContext.userId,
+          providerId: resolvedModel.providerId,
+          modelId: resolvedModel.modelId,
+          categories,
+        },
+        input.container,
+      ),
+  })
+
   const hydratedMessages = attachAttachmentsToMessages(normalizedMessages, resolvedAttachments)
   const modelMessages = await convertToModelMessages(hydratedMessages)
 
@@ -1579,6 +1835,7 @@ export async function runAiAgentText(input: RunAiAgentTextInput): Promise<Respon
         : {}),
       ...(sdkActiveTools !== undefined ? { activeTools: sdkActiveTools } : {}),
       ...(sdkToolChoice !== undefined ? { toolChoice: sdkToolChoice } : {}),
+      ...(modelProviderOptions !== undefined ? { providerOptions: modelProviderOptions as never } : {}),
     }
     builtToolLoopAgent = new ToolLoopAgent(agentSettings)
   }
@@ -1600,6 +1857,7 @@ export async function runAiAgentText(input: RunAiAgentTextInput): Promise<Respon
     toolChoice: sdkToolChoice,
     abortSignal: abortController.signal,
     finalizeLoopTrace: () => loopTraceCollector.finalize(budgetEnforcer.abortReason),
+    ...(modelProviderOptions !== undefined ? { providerOptions: modelProviderOptions } : {}),
     ...(builtToolLoopAgent !== undefined ? { toolLoopAgent: builtToolLoopAgent } : {}),
   }
 
@@ -1672,6 +1930,7 @@ export async function runAiAgentText(input: RunAiAgentTextInput): Promise<Respon
     experimental_repairToolCall: effectiveLoop.repairToolCall as never,
     ...(sdkActiveTools !== undefined ? { activeTools: sdkActiveTools } : {}),
     ...(sdkToolChoice !== undefined ? { toolChoice: sdkToolChoice } : {}),
+    ...(modelProviderOptions !== undefined ? { providerOptions: modelProviderOptions as never } : {}),
     abortSignal: abortController.signal,
   })
   if (wallClockTimer !== undefined) {

package/src/modules/ai_assistant/lib/ai-agent-definition.ts

@@ -384,6 +384,16 @@ export interface AiAgentDefinition {
   uiParts?: string[]
   readOnly?: boolean
   mutationPolicy?: AiAgentMutationPolicy
+  /**
+   * Marks this agent as accepting untrusted end-user input (e.g. a customer
+   * portal or public-widget surface). When `true`, input pre-moderation is
+   * ENFORCED on every turn wherever the resolved chat provider supports it —
+   * tenants cannot disable it. Other agents default to off and are tenant
+   * opt-in. Additive + optional; omitting it preserves today's behavior.
+   *
+   * Spec `2026-06-04-ai-input-moderation-and-safety-identifiers`.
+   */
+  untrustedInput?: boolean
   /**
    * @deprecated Use `loop.maxSteps` instead. Honored as alias when `loop` is
    * omitted. When both `maxSteps` and `loop.maxSteps` are specified, `loop.maxSteps`

package/src/modules/ai_assistant/lib/auth.ts

@@ -2,7 +2,7 @@ import { createLogger } from '@open-mercato/shared/lib/logger'
 import type { AwilixContainer } from 'awilix'
 import type { EntityManager } from '@mikro-orm/postgresql'
 import type { RbacService } from '@open-mercato/core/modules/auth/services/rbacService'
-import { hasAllFeatures } from '@open-mercato/shared/lib/auth/featureMatch'
+import { authorizeFeatures } from '@open-mercato/shared/security/featurePolicy'
 
 const logger = createLogger('ai_assistant')
 
@@ -137,20 +137,11 @@ export function hasRequiredFeatures(
   isSuperAdmin: boolean,
   rbacService?: RbacService
 ): boolean {
-  if (isSuperAdmin) return true
-  if (!requiredFeatures?.length) return true
-
-  // Delegate to RbacService if provided
-  if (rbacService) {
-    return rbacService.hasAllFeatures(requiredFeatures, userFeatures)
-  }
-
-  // Fallback for cases without rbacService: delegate to the canonical
-  // wildcard-aware matcher so this path stays consistent with
-  // RbacService.hasAllFeatures (which uses the same helper). The previous
-  // bespoke loop rejected a bare-segment requirement (e.g. 'entities')
-  // against an 'entities.*' grant, diverging from the canonical matcher.
-  return hasAllFeatures(requiredFeatures, userFeatures)
+  void rbacService
+  return authorizeFeatures(requiredFeatures ?? [], {
+    grantedFeatures: userFeatures,
+    unrestricted: isSuperAdmin,
+  })
 }
 
 /**

package/src/modules/ai_assistant/lib/entity-graph.ts

@@ -7,6 +7,7 @@
 
 import { ReferenceKind, type MikroORM } from '@mikro-orm/core'
 import type { PostgreSqlDriver } from '@mikro-orm/postgresql'
+import { listEntityMetadata } from '@open-mercato/shared/lib/db/entityMetadata'
 
 /**
  * Relationship types mapped from MikroORM reference kinds.
@@ -86,13 +87,12 @@ function getSimpleTypeName(type: string | ((...args: unknown[]) => unknown) | un
  * Extract the entity graph from MikroORM metadata.
  */
 export async function extractEntityGraph(orm: MikroORM<PostgreSqlDriver>): Promise<EntityGraph> {
-  const metadata = orm.getMetadata()
-  const allMetadata = metadata.getAll()
+  const allMetadata = listEntityMetadata(orm)
 
   const nodes: EntityNode[] = []
   const edges: EntityTriple[] = []
 
-  for (const [, entityMeta] of Object.entries(allMetadata)) {
+  for (const entityMeta of allMetadata) {
     // Skip abstract entities and embeddables
     if (entityMeta.abstract || entityMeta.embeddable) continue
 

package/src/modules/ai_assistant/lib/llm-adapters/anthropic.ts

@@ -90,6 +90,16 @@ export function createAnthropicAdapter(): LlmProvider {
       return envKeys[0]
     },
 
+    mapEndUserIdentifier(identifier: string): Record<string, unknown> {
+      // Anthropic Messages API accepts `metadata.user_id` so abuse enforcement
+      // can target a single hashed end user instead of the org key. The key MUST
+      // be the AI SDK provider-option name `userId` (camelCase) — the SDK
+      // translates it to the `metadata.user_id` request-body field and strips
+      // unknown providerOptions keys, so a snake_case key would be dropped and
+      // never reach Anthropic.
+      return { anthropic: { metadata: { userId: identifier } } }
+    },
+
     createModel(options: LlmCreateModelOptions): unknown {
       const anthropic = createAnthropic({
         apiKey: options.apiKey,

package/src/modules/ai_assistant/lib/llm-adapters/openai.ts

@@ -62,6 +62,23 @@ export interface OpenAICompatiblePreset {
    * The first non-empty value wins and overrides {@link baseURL}.
    */
   baseURLEnvKeys?: readonly string[]
+  /**
+   * When `true`, the provider exposes OpenAI's `/v1/moderations` endpoint and
+   * the runtime may run input pre-moderation through it. Only the native
+   * `openai` preset sets this — OpenAI-compatible backends (Groq, DeepInfra,
+   * Together, …) do not implement the moderations endpoint, so they leave it
+   * unset and rely on their own server-side filtering.
+   */
+  supportsInputModeration?: boolean
+  /**
+   * When `true`, the provider maps the runtime end-user safety identifier into
+   * OpenAI's per-request `safetyIdentifier` provider option. Only the native
+   * `openai` preset sets this — `safety_identifier` is an OpenAI-specific body
+   * field, and OpenAI-compatible/self-hosted backends (Groq, DeepInfra, Azure,
+   * Ollama, LM Studio, …) may reject the unknown parameter, so they leave it
+   * unset and send no identifier (matching pre-feature behavior).
+   */
+  supportsEndUserSafetyIdentifier?: boolean
   /**
    * True when this gateway's model ids are `vendor/model` strings (OpenRouter,
    * Requesty, LiteLLM). Surfaced on the resolved `LlmProvider` so the model
@@ -116,12 +133,13 @@ export function createOpenAICompatibleProvider(
     return preset.baseURL
   }
 
-  return {
+  const provider: LlmProvider = {
     id: preset.id,
     name: preset.name,
     envKeys: preset.envKeys,
     defaultModel: preset.defaultModel,
     defaultModels: preset.defaultModels,
+    supportsInputModeration: preset.supportsInputModeration ?? false,
     usesVendorPrefixedModelIds: preset.usesVendorPrefixedModelIds ?? false,
 
     isConfigured(env?: EnvLookup): boolean {
@@ -151,4 +169,17 @@ export function createOpenAICompatibleProvider(
       return openai(options.modelId)
     },
   }
+
+  // Only the native OpenAI preset maps the end-user safety identifier. The key
+  // MUST be the AI SDK provider-option name `safetyIdentifier` (camelCase) — the
+  // SDK translates it to the `safety_identifier` request-body field and strips
+  // any unknown providerOptions keys, so a snake_case key would be silently
+  // dropped and never reach OpenAI.
+  if (preset.supportsEndUserSafetyIdentifier) {
+    provider.mapEndUserIdentifier = (identifier: string): Record<string, unknown> => ({
+      openai: { safetyIdentifier: identifier },
+    })
+  }
+
+  return provider
 }

package/src/modules/ai_assistant/lib/model-factory.ts

@@ -217,6 +217,16 @@ export interface AiModelFactoryInput {
    * intersecting at resolution time.
    */
   tenantAllowlist?: TenantAllowlistSnapshot | null
+  /**
+   * Optional opaque end-user identifier (tenant-salted HMAC). When set and the
+   * resolved provider implements {@link LlmProvider.mapEndUserIdentifier}, the
+   * factory returns the provider-specific `providerOptions` fragment on the
+   * resolution so the runtime can attach it to the model call. No-op for
+   * providers without a mapping or when no identifier is supplied.
+   *
+   * @see .ai/specs/2026-06-04-ai-input-moderation-and-safety-identifiers.md
+   */
+  endUserIdentifier?: string
 }
 
 /**
@@ -268,6 +278,20 @@ export interface AiModelResolution {
     originalModelId: string
     reason: string
   }
+  /**
+   * Provider-specific `providerOptions` fragment produced by mapping the input
+   * {@link AiModelFactoryInput.endUserIdentifier} through the resolved
+   * provider's {@link LlmProvider.mapEndUserIdentifier}. Undefined when no
+   * identifier was supplied or the provider has no mapping. The runtime merges
+   * this into the AI SDK `providerOptions` for the model call.
+   */
+  providerOptions?: Record<string, unknown>
+  /**
+   * Mirror of the resolved provider's {@link LlmProvider.supportsInputModeration}
+   * capability flag. The runtime uses this to decide whether to run the input
+   * pre-moderation gate before the model call.
+   */
+  supportsInputModeration?: boolean
 }
 
 /**
@@ -776,17 +800,26 @@ export function createModelFactory(
         )
       }
 
+      const endUserIdentifier = normalizeOverride(input.endUserIdentifier)
+      const providerOptions =
+        endUserIdentifier && finalProvider.mapEndUserIdentifier
+          ? finalProvider.mapEndUserIdentifier(endUserIdentifier)
+          : undefined
+
       const model = finalProvider.createModel({
         modelId: finalModelId,
         apiKey: finalApiKey,
         baseURL: resolvedBaseURL,
+        ...(endUserIdentifier ? { endUserIdentifier } : {}),
       })
       return {
         model,
         modelId: finalModelId,
         providerId: finalProvider.id,
         source: finalSource,
+        supportsInputModeration: finalProvider.supportsInputModeration === true,
         ...(resolvedBaseURL !== undefined ? { baseURL: resolvedBaseURL } : {}),
+        ...(providerOptions !== undefined ? { providerOptions } : {}),
         ...(allowlistResult.fallback
           ? {
               allowlistFallback: {

package/src/modules/ai_assistant/lib/moderation-flag-recorder.ts

@@ -0,0 +1,75 @@
+import type { AwilixContainer } from 'awilix'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { AiModerationFlagRepository } from '../data/repositories/AiModerationFlagRepository'
+import { emitAiAssistantEvent } from '../events'
+import type { ModerationCategoryResult } from './moderation'
+
+const logger = createLogger('ai_assistant')
+
+export interface RecordModerationFlagInput {
+  tenantId: string | null
+  organizationId: string | null
+  agentId: string
+  userId: string
+  providerId: string
+  modelId: string
+  categories: Record<string, ModerationCategoryResult>
+}
+
+/**
+ * Persists one `ai_moderation_flags` audit row and emits
+ * `ai_assistant.moderation_flag.created`, best-effort.
+ *
+ * SAFETY CONTRACT: this MUST NEVER throw — the moderation rejection is the
+ * primary effect and is thrown by the gate regardless. A missing tenant scope
+ * (e.g. a system-scope caller) means the row cannot be tenant-scoped, so the
+ * audit write is skipped. Any persistence/emit failure is logged and
+ * swallowed so the user still receives the rejection.
+ *
+ * Spec `2026-06-04-ai-input-moderation-and-safety-identifiers`.
+ */
+export async function recordModerationFlag(
+  input: RecordModerationFlagInput,
+  container: AwilixContainer | undefined,
+): Promise<void> {
+  if (!container) return
+  if (!input.tenantId) return
+
+  let createdId: string | null = null
+  try {
+    const em = container.resolve<EntityManager>('em')
+    const repo = new AiModerationFlagRepository(em.fork())
+    const flag = await repo.create({
+      tenantId: input.tenantId,
+      organizationId: input.organizationId,
+      agentId: input.agentId,
+      userId: input.userId,
+      providerId: input.providerId,
+      modelId: input.modelId,
+      categories: input.categories,
+    })
+    createdId = flag.id
+  } catch (error) {
+    logger.error('Failed to persist moderation flag (rejection still applies)', { err: error })
+    return
+  }
+
+  // Emit AFTER a successful write, detached so a failed emit never retroactively
+  // fails the audit insert.
+  try {
+    const flaggedCategories = Object.entries(input.categories)
+      .filter(([, value]) => value.flagged)
+      .map(([name]) => name)
+    await emitAiAssistantEvent('ai_assistant.moderation_flag.created', {
+      id: createdId,
+      tenantId: input.tenantId,
+      organizationId: input.organizationId,
+      agentId: input.agentId,
+      userId: input.userId,
+      categories: flaggedCategories,
+    })
+  } catch (error) {
+    logger.error('Failed to emit moderation_flag.created (audit row persisted)', { err: error })
+  }
+}