@digimuza/system-core 0.2.0-rc.2 → 0.3.0-rc.1

package/src/ai/tools.ts

@@ -0,0 +1,128 @@
+// Tools & permissions of the AI module (DIG-71): defining tools and agents, and
+// running one tool call as the run's actor with the same guarantees as any
+// other system-core function (permission, module enabled, role view, audit).
+import type { z } from "zod"
+import { rehydrateActor, type Actor, type ActorRef } from "../core/access.js"
+import { recordAudit, type AuditInput } from "../core/audit.js"
+import { PERMISSION_ID } from "../core/catalog.js"
+import type { SystemContext } from "../core/context.js"
+import { toSystemError } from "../core/errors.js"
+import { authorizeJob } from "../core/jobs.js"
+import { AI_AUDIT, type AiAgentDefinition, type AiTool, type ToolExecutionResult } from "./contract.js"
+
+/** `module.verb_object`, e.g. `finance.list_invoices`. */
+export const AI_TOOL_ID = /^[a-z][a-z0-9-]*\.[a-z][a-z0-9_]*$/
+export const AI_AGENT_ID = /^[a-z][a-z0-9-]{1,47}$/
+
+const isZodSchema = (s: unknown): s is z.ZodType => !!s && typeof s === "object" && typeof (s as { safeParse?: unknown }).safeParse === "function"
+
+/**
+ * Declares a tool. Identity at runtime; validates the definition (id format, permission format).
+ *
+ * Handler rule: check everything (existence, state, uniqueness, limits) BEFORE the
+ * first write. A failed handler's earlier writes are committed, because
+ * `executeAiTool` reports the failure as a result instead of throwing, so the
+ * mutation (and its `ai.tool.run` audit event) commits. The finance tools follow
+ * this: their shared invoice operations validate first, then insert/patch once.
+ *
+ * Conventions: `permission` is the owning module's own permission; anything that
+ * writes sets `requiresApproval: true`.
+ */
+export function defineAiTool<I extends z.ZodType, O>(tool: AiTool<I, O>): AiTool<I, O> {
+  const id = typeof tool?.id === "string" ? tool.id : ""
+  if (!AI_TOOL_ID.test(id)) throw new Error(`defineAiTool: invalid tool id "${id}" (expected module.verb_object, e.g. finance.list_invoices)`)
+  if (typeof tool.permission !== "string" || !PERMISSION_ID.test(tool.permission)) {
+    throw new Error(`defineAiTool(${id}): invalid permission "${String(tool.permission)}" (expected module:resource:action)`)
+  }
+  if (typeof tool.description !== "string" || !tool.description.trim()) throw new Error(`defineAiTool(${id}): description is required`)
+  if (!isZodSchema(tool.input)) throw new Error(`defineAiTool(${id}): input must be a zod schema`)
+  if (typeof tool.handler !== "function") throw new Error(`defineAiTool(${id}): handler must be a function`)
+  return tool
+}
+
+/** Declares an agent. Identity at runtime; validates ids and that tool ids are unique. */
+export function defineAiAgent<const A extends AiAgentDefinition>(agent: A): A {
+  const id = typeof agent?.id === "string" ? agent.id : ""
+  if (!AI_AGENT_ID.test(id)) throw new Error(`defineAiAgent: invalid agent id "${id}" (expected ${AI_AGENT_ID.source})`)
+  if (typeof agent.instructions !== "string" || !agent.instructions.trim()) throw new Error(`defineAiAgent(${id}): instructions are required`)
+  if (!Array.isArray(agent.tools)) throw new Error(`defineAiAgent(${id}): tools must be an array`)
+  const seen = new Set<string>()
+  for (const tool of agent.tools) {
+    if (seen.has(tool.id)) throw new Error(`defineAiAgent(${id}): duplicate tool id "${tool.id}"`)
+    seen.add(tool.id)
+  }
+  return agent
+}
+
+/** Field paths of the failed issues, never their values. */
+function invalidFields(error: z.ZodError): string[] {
+  const paths = error.issues.map((i) => (i.path.length ? i.path.map((p) => String(p)).join(".") : "(root)"))
+  return [...new Set(paths)]
+}
+
+/**
+ * Runs one tool call as the run's actor, inside a mutation:
+ * validates `args` with the tool's zod schema (VALIDATION), re-authorizes the
+ * actor for `tool.permission` with system-core `authorizeJob` (FORBIDDEN when
+ * null: revoked key, suspended user, role view, disabled module…), runs the
+ * handler, maps SystemError to its code, and audits `ai.tool.run`.
+ *
+ * Handlers must validate before they write: the failure is returned (not
+ * thrown) so the audit is kept, which means the surrounding mutation also
+ * commits whatever the handler wrote before it failed.
+ */
+export async function executeAiTool(input: {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  db: any
+  sys: SystemContext
+  actorRef: ActorRef
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  tool: AiTool<any, any>
+  args: unknown
+  toolCallId: string
+}): Promise<ToolExecutionResult> {
+  const { db, sys, actorRef, tool, args, toolCallId } = input
+  // Who the audit event names: the rehydrated actor if still valid, else "system".
+  let auditActor: Actor | "system" = (await rehydrateActor(sys, actorRef)) ?? "system"
+
+  const audit = (result: NonNullable<AuditInput["result"]>, reason?: string) => {
+    const event: AuditInput = { action: AI_AUDIT.toolRun, targetType: "ai_tool", targetId: tool.id, result, changes: { toolCallId } }
+    if (reason) event.reason = reason
+    return recordAudit(sys, auditActor, event)
+  }
+  const failure = async (code: string, message: string): Promise<ToolExecutionResult> => {
+    await audit(code === "FORBIDDEN" || code === "UNAUTHENTICATED" ? "denied" : "failed", code)
+    return { ok: false, code, message }
+  }
+
+  const parsed = tool.input.safeParse(args)
+  if (!parsed.success) {
+    const fields = invalidFields(parsed.error)
+    sys.logger.info("ai_tool_invalid_args", { toolId: tool.id, fields })
+    return failure("VALIDATION", `Invalid arguments for ${tool.id}: ${fields.join(", ")}`)
+  }
+
+  const auth = await authorizeJob(sys, actorRef, tool.permission)
+  if (!auth) return failure("FORBIDDEN", `Not allowed to use ${tool.id}.`)
+  auditActor = auth.actor
+
+  let result: unknown
+  try {
+    result = await tool.handler({ db, sys, actor: auth.actor }, parsed.data)
+  } catch (e) {
+    const se = toSystemError(e)
+    if (se) return failure(se.code, se.toPublic().message)
+    sys.logger.error("ai_tool_failed", { toolId: tool.id, error: e })
+    return failure("UNAVAILABLE", "The tool failed.")
+  }
+
+  let json: unknown
+  try {
+    json = result === undefined ? null : JSON.parse(JSON.stringify(result))
+  } catch (e) {
+    sys.logger.error("ai_tool_result_not_json", { toolId: tool.id, error: e })
+    return failure("UNAVAILABLE", "The tool returned an invalid result.")
+  }
+  await audit("success")
+  return { ok: true, result: json }
+}

package/src/audit/csv.ts

@@ -0,0 +1,60 @@
+// CSV export of audit events (DIG-73). Pure and browser-safe: no Convex, no env.
+// The UI pages through `listAudit`, calls `auditToCsv`, offers the download and
+// records the export with `recordAuditExport` (audit action `audit.export`).
+
+/** The fields of an audit event (`listAudit` items) the export reads. */
+export interface AuditCsvEvent {
+  at: number
+  action: string
+  result: string
+  actorKind?: string
+  actorUserId?: string
+  apiKeyId?: string
+  targetType: string
+  targetId: string
+  operationId: string
+  changes?: Record<string, unknown>
+  reason?: string
+}
+
+/** Stable column order. */
+export const AUDIT_CSV_COLUMNS = ["at", "action", "result", "actor", "apiKey", "target", "operationId", "details"] as const
+
+export interface AuditCsvOptions {
+  /** Prepend a UTF-8 BOM so Excel reads Lithuanian letters correctly. Default false. */
+  bom?: boolean
+}
+
+/** Characters that make spreadsheet apps evaluate a cell as a formula. */
+const FORMULA_START = /^[=+\-@\t\r]/
+
+/** One CSV cell: neutralizes formula injection (leading `'`), then RFC 4180 quoting. */
+export function csvCell(value: unknown): string {
+  let s = value === undefined || value === null ? "" : String(value)
+  if (FORMULA_START.test(s)) s = `'${s}`
+  return /[",\r\n]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s
+}
+
+function details(e: AuditCsvEvent): string {
+  const out: Record<string, unknown> = {}
+  if (e.changes !== undefined) out.changes = e.changes
+  if (e.reason !== undefined) out.reason = e.reason
+  return Object.keys(out).length ? JSON.stringify(out) : ""
+}
+
+/**
+ * Audit events as CSV (RFC 4180: CRLF line ends, quoted cells where needed),
+ * header row first. Columns: at (ISO 8601 UTC), action, result, actor (user ID,
+ * or `system` / `anonymous`), apiKey (key ID for agents), target
+ * (`type:id`), operationId, details (JSON of `changes` and `reason`).
+ * Cells starting with = + - @ tab or CR get a leading `'` (CSV formula injection).
+ */
+export function auditToCsv(events: readonly AuditCsvEvent[], options: AuditCsvOptions = {}): string {
+  const rows: string[] = [AUDIT_CSV_COLUMNS.join(",")]
+  for (const e of events) {
+    const at = Number.isFinite(e.at) ? new Date(e.at).toISOString() : ""
+    const actor = e.actorUserId ?? e.actorKind ?? ""
+    rows.push([at, e.action, e.result, actor, e.apiKeyId ?? "", `${e.targetType}:${e.targetId}`, e.operationId, details(e)].map(csvCell).join(","))
+  }
+  return `${options.bom ? "" : ""}${rows.join("\r\n")}\r\n`
+}

package/src/audit/index.ts

@@ -0,0 +1,7 @@
+// `@digimuza/system-core/audit`: browser-safe audit helpers (DIG-73).
+// The audit functions themselves (`listAudit`, `listAuditFacets`,
+// `recordAuditExport`) are part of `system.functions` (`@digimuza/system-core/convex`).
+export { auditToCsv, csvCell, AUDIT_CSV_COLUMNS, type AuditCsvEvent, type AuditCsvOptions } from "./csv.js"
+export { auditModuleOf, CORE_AUDIT_PREFIXES } from "../core/audit-module.js"
+export type { AuditEventRow } from "../core/store.js"
+export type { AuditFacets, AuditFilter, AuditExportFilter } from "../core/audit.js"

package/src/convex/functions.ts

@@ -21,7 +21,8 @@ import {
   type VerifiedIdentity,
 } from "../core/access.js"
 import * as apiKeys from "../core/api-keys.js"
-import { listAudit } from "../core/audit.js"
+import { listAudit, listAuditFacets, recordAuditExport } from "../core/audit.js"
+import type { Notifier } from "../core/notify.js"
 import { bindSystem, createSystem, type SystemContext, type SystemDefinition, type SystemOptions } from "../core/context.js"
 import { isSystemError, SystemError } from "../core/errors.js"
 import * as flags from "../core/feature-flags.js"
@@ -41,6 +42,15 @@ type Db = GenericDatabaseReader<any> | GenericDatabaseWriter<any>
 /** The subset of a Convex query/mutation ctx the system needs. Any app's ctx fits. */
 export interface DbCtx { db: Db; auth: Auth }
 
+/**
+ * Installs notifications into the system (`notificationsHook()` from
+ * `@digimuza/system-core/notifications`). The Convex layer binds one notifier per
+ * transaction, so core services and modules can notify from any mutation.
+ */
+export interface ConvexNotificationsHook {
+  bind(ctx: DbCtx, sys: SystemContext): Notifier
+}
+
 export interface ConvexSystemOptions extends SystemOptions {
   /**
    * Module path (relative to `convex/`) where you export `system.functions`.
@@ -53,6 +63,8 @@ export interface ConvexSystemOptions extends SystemOptions {
   inviteDelivery?: invites.InviteDeliveryAdapter
   /** Builds the one-time invite link. */
   inviteUrl?: (token: string) => string
+  /** Notifications (DIG-74). Without it every `notifyIfInstalled` is a no-op. */
+  notifications?: ConvexNotificationsHook
 }
 
 export interface ContextOptions { apiKey?: string | undefined; operationId?: string | undefined }
@@ -109,7 +121,11 @@ export function defineConvexSystem(options: ConvexSystemOptions = {}) {
   /** Binds the system to this transaction and resolves the actor (session or API key). */
   async function context(ctx: DbCtx, opts: ContextOptions = {}): Promise<{ sys: SystemContext; actor: Actor | null }> {
     const operationId = opts.operationId && OPERATION_ID.test(opts.operationId) ? opts.operationId : undefined
-    const sys = bindSystem(definition, createConvexStore(ctx.db), operationId ? { operationId } : {})
+    const hook = options.notifications
+    const sys = bindSystem(definition, createConvexStore(ctx.db), {
+      ...(operationId ? { operationId } : {}),
+      ...(hook ? { notifier: (s: SystemContext) => hook.bind(ctx, s) } : {}),
+    })
     // An explicit API key always wins: agents never inherit a browser session.
     const actor = opts.apiKey ? await resolveApiKeyActor(sys, opts.apiKey) : await resolveUserActor(sys, await verifiedIdentity(ctx))
     return { sys, actor }
@@ -172,6 +188,31 @@ export function defineConvexSystem(options: ConvexSystemOptions = {}) {
   const defined = <T extends Record<string, unknown>>(o: T) =>
     Object.fromEntries(Object.entries(o).filter(([, val]) => val !== undefined)) as { [K in keyof T]: Exclude<T[K], undefined> }
 
+  const auditFilterFields = {
+    from: v.optional(v.number()),
+    to: v.optional(v.number()),
+    actorUserId: v.optional(v.string()),
+    apiKeyId: v.optional(v.string()),
+    targetId: v.optional(v.string()),
+    filterOperationId: v.optional(v.string()),
+    action: v.optional(v.string()),
+    moduleId: v.optional(v.string()),
+    actionPrefix: v.optional(v.string()),
+  }
+  const auditFilterArg = v.object(auditFilterFields)
+  const auditFilter = (a: ObjectType<typeof auditFilterFields>) =>
+    defined({
+      from: a.from,
+      to: a.to,
+      actorUserId: a.actorUserId,
+      apiKeyId: a.apiKeyId,
+      targetId: a.targetId,
+      operationId: a.filterOperationId,
+      action: a.action,
+      moduleId: a.moduleId,
+      actionPrefix: a.actionPrefix,
+    })
+
   const subjectArg = v.union(v.object({ kind: v.literal("user"), userId: v.string() }), v.object({ kind: v.literal("agent"), apiKeyId: v.string() }))
   async function subjectActor(sys: SystemContext, ref: ActorRef): Promise<Actor> {
     if (ref.kind === "user") return ref
@@ -340,12 +381,16 @@ export function defineConvexSystem(options: ConvexSystemOptions = {}) {
         targetId: v.optional(v.string()),
         filterOperationId: v.optional(v.string()),
         action: v.optional(v.string()),
+        moduleId: v.optional(v.string()),
+        actionPrefix: v.optional(v.string()),
       },
-      (sys, actor, a) =>
-        listAudit(sys, actor, {
-          ...pageReq(a),
-          ...defined({ from: a.from, to: a.to, actorUserId: a.actorUserId, apiKeyId: a.apiKeyId, targetId: a.targetId, operationId: a.filterOperationId, action: a.action }),
-        }),
+      (sys, actor, a) => listAudit(sys, actor, { ...pageReq(a), ...auditFilter(a) }),
+    ),
+    /** `{ actions, moduleIds, scanned, complete }` of the newest events, for the filter UI. */
+    listAuditFacets: query({}, (sys, actor) => listAuditFacets(sys, actor)),
+    /** Audits a CSV export (`audit.export`) after the UI paged through `listAudit`. */
+    recordAuditExport: mutation({ filter: auditFilterArg, count: v.number() }, (sys, actor, a) =>
+      recordAuditExport(sys, actor, { filter: auditFilter(a.filter), count: a.count }),
     ),
 
     // --- Deployment -------------------------------------------------------------------------
@@ -388,6 +433,8 @@ export function defineConvexSystem(options: ConvexSystemOptions = {}) {
     requirePermission,
     run,
     functions,
+    /** The installed notifications hook, if any (read by `defineNotifications`). */
+    notifications: options.notifications,
   }
 }
 

package/src/convex/index.ts

@@ -1,7 +1,7 @@
 // Convex integration: schema tables, store adapter, system functions and guards.
 export { systemTables } from "./schema.js"
 export { createConvexStore } from "./store.js"
-export { defaultIdentity, defineConvexSystem, toConvexError, type ConvexSystem, type ConvexSystemOptions, type ContextOptions, type DbCtx } from "./functions.js"
+export { defaultIdentity, defineConvexSystem, toConvexError, type ConvexSystem, type ConvexSystemOptions, type ConvexNotificationsHook, type ContextOptions, type DbCtx } from "./functions.js"
 
 // Runtime-agnostic services, for custom Convex functions built on `system.context(ctx)`.
 export * from "../core/index.js"

package/src/core/access.ts

@@ -1,7 +1,7 @@
 import { forbidden, SystemError, unauthenticated } from "./errors.js"
 import { constantTimeEqual, sha256Hex } from "./crypto.js"
 import { normalizeEmail, type SystemContext } from "./context.js"
-import { pairKey, type ApiKeyRow, type ModuleRow, type UserRow } from "./store.js"
+import { pairKey, type ApiKeyRow, type ModuleRow, type Page, type UserRow } from "./store.js"
 import { WILDCARD_SCOPE } from "./system-modules.js"
 
 // --- Actors ------------------------------------------------------------------
@@ -270,6 +270,60 @@ export async function requireSuper(sys: SystemContext, actor: Actor | null): Pro
   return a
 }
 
+// --- Reverse computation: who holds a permission (notifications) -------------
+
+/** Most candidate users `usersWithPermission` evaluates (each costs a full `decide`). */
+export const PERMISSION_HOLDERS_SCAN_MAX = 300
+
+/**
+ * Active users who hold `permission` right now, by user ID, at most `limit`.
+ * Candidates come from the grant chain (permission → subrole → role → user)
+ * plus the deployment Super list; each is confirmed with `decide`, so module
+ * state, suspended accounts and a Super's role view apply exactly as for any
+ * other check. Bounded: at most PERMISSION_HOLDERS_SCAN_MAX candidates are
+ * evaluated (sorted by user ID, so the cut is deterministic).
+ */
+export async function usersWithPermission(sys: SystemContext, permission: string, limit: number): Promise<{ userIds: string[]; truncated: boolean }> {
+  const perm = sys.def.catalog.permissions.get(permission)
+  if (!perm || limit <= 0) return { userIds: [], truncated: false }
+  const candidates = new Set<string>()
+  for (const email of sys.superEmails) for (const u of await sys.store.findBy("users", "email", email)) candidates.add(u.key)
+  const roleIds = new Set<string>()
+  for (const sp of await sys.store.findBy("subrolePermissions", "permissionId", permission)) {
+    const sub = await sys.store.get("subroles", sp.subroleId)
+    if (!sub || sub.archived || sub.moduleId !== perm.moduleId) continue
+    for (const rs of await sys.store.findBy("roleSubroles", "subroleId", sub.key)) roleIds.add(rs.roleId)
+  }
+  let truncated = false
+  // An implicit role (Profile) grants it to everyone: page through users, bounded.
+  if (implicitRoleIds(sys).some((id) => roleIds.has(id))) {
+    let cursor: string | null = null
+    do {
+      const page: Page<UserRow> = await sys.store.page("users", { cursor, limit: 200 })
+      for (const u of page.items) candidates.add(u.key)
+      cursor = page.cursor
+    } while (cursor && candidates.size < PERMISSION_HOLDERS_SCAN_MAX)
+    if (cursor) truncated = true
+  }
+  for (const roleId of roleIds) {
+    const role = await sys.store.get("roles", roleId)
+    if (!role || role.archived) continue
+    for (const ur of await sys.store.findBy("userRoles", "roleId", roleId)) candidates.add(ur.userId)
+  }
+  const sorted = [...candidates].sort()
+  if (sorted.length > PERMISSION_HOLDERS_SCAN_MAX) truncated = true
+  const userIds: string[] = []
+  for (const userId of sorted.slice(0, PERMISSION_HOLDERS_SCAN_MAX)) {
+    if (!(await decide(sys, { kind: "user", userId }, permission)).allowed) continue
+    if (userIds.length >= limit) {
+      truncated = true
+      break
+    }
+    userIds.push(userId)
+  }
+  return { userIds, truncated }
+}
+
 // --- Forward computation (UI lists, delegation) -------------------------------
 
 /** Active, catalog-known permissions granted by the given roles. Ignores module enabled state. */

package/src/core/audit-module.ts

@@ -0,0 +1,26 @@
+// Which module an audit action belongs to. Pure (browser-safe).
+//
+// Business modules name their actions `<moduleId>.<object>.<verb>` (finance.invoice.create,
+// ai.tool.run), so the first segment is the module ID. The core's own actions use
+// shorter object names (role.assign, api_key.create); they map to their system module.
+
+/** First action segment → system module ID, for the core's own audit actions. */
+export const CORE_AUDIT_PREFIXES: Readonly<Record<string, string>> = {
+  api_key: "api-keys",
+  auth: "auth",
+  catalog: "modules",
+  delegation: "roles",
+  flag: "feature-flags",
+  invite: "invites",
+  module: "modules",
+  role: "roles",
+  subrole: "roles",
+  super: "roles",
+  user: "users",
+}
+
+/** Module ID of an audit action: `finance.invoice.create` → `finance`, `role.assign` → `roles`. */
+export function auditModuleOf(action: string): string {
+  const head = action.split(".", 1)[0] ?? action
+  return CORE_AUDIT_PREFIXES[head] ?? head
+}

package/src/core/audit.ts

@@ -1,4 +1,6 @@
-import { requirePermission, type Actor } from "./access.js"
+import { requireHuman, requirePermission, withOperation, type Actor } from "./access.js"
+import { auditModuleOf } from "./audit-module.js"
+import { validation } from "./errors.js"
 import { newId } from "./crypto.js"
 import { redact } from "./redact.js"
 import type { SystemContext } from "./context.js"
@@ -51,6 +53,10 @@ export interface AuditFilter {
   targetId?: string
   operationId?: string
   action?: string
+  /** Events of one module: `finance` matches `finance.*`; core actions map to their system module (`role.assign` → `roles`). */
+  moduleId?: string
+  /** Actions starting with this prefix, e.g. `finance.invoice.` or `ai.tool`. */
+  actionPrefix?: string
   cursor?: string | null
   limit?: number
 }
@@ -66,7 +72,9 @@ export async function listAudit(sys: SystemContext, actor: Actor | null, filter:
     (filter.apiKeyId === undefined || e.apiKeyId === filter.apiKeyId) &&
     (filter.targetId === undefined || e.targetId === filter.targetId) &&
     (filter.operationId === undefined || e.operationId === filter.operationId) &&
-    (filter.action === undefined || e.action === filter.action)
+    (filter.action === undefined || e.action === filter.action) &&
+    (filter.moduleId === undefined || auditModuleOf(e.action) === filter.moduleId) &&
+    (filter.actionPrefix === undefined || e.action.startsWith(filter.actionPrefix))
 
   // Use an index when the filter allows it; otherwise scan pages.
   const indexed = filter.operationId
@@ -86,3 +94,61 @@ export async function listAudit(sys: SystemContext, actor: Actor | null, filter:
   const page = await sys.store.page("auditEvents", { cursor: filter.cursor ?? null, limit, order: "desc" })
   return { ...page, items: page.items.filter(match) }
 }
+
+/** Newest events `listAuditFacets` scans. */
+export const AUDIT_FACETS_SCAN_MAX = 1000
+
+export interface AuditFacets {
+  /** Distinct actions among the scanned events, sorted. */
+  actions: string[]
+  /** Distinct module IDs (see `auditModuleOf`), sorted. */
+  moduleIds: string[]
+  /** Events scanned (newest first). */
+  scanned: number
+  /** True when every event was scanned (fewer than AUDIT_FACETS_SCAN_MAX exist). */
+  complete: boolean
+}
+
+/** Filter options for the audit UI: distinct actions and modules of the newest events. Same permission as `listAudit`. */
+export async function listAuditFacets(sys: SystemContext, actor: Actor | null): Promise<AuditFacets> {
+  await requirePermission(sys, actor, P.auditRead)
+  const actions = new Set<string>()
+  let scanned = 0
+  let cursor: string | null = null
+  let complete = false
+  while (scanned < AUDIT_FACETS_SCAN_MAX) {
+    const page: Page<AuditEventRow> = await sys.store.page("auditEvents", { cursor, limit: 200, order: "desc" })
+    for (const e of page.items) actions.add(e.action)
+    scanned += page.items.length
+    cursor = page.cursor
+    if (!cursor) {
+      complete = true
+      break
+    }
+  }
+  const sorted = [...actions].sort()
+  return { actions: sorted, moduleIds: [...new Set(sorted.map(auditModuleOf))].sort(), scanned, complete }
+}
+
+/** Filters an export may carry (stored in the `audit.export` event). */
+export type AuditExportFilter = Omit<AuditFilter, "cursor" | "limit">
+
+export const AUDIT_EXPORT_MAX = 1_000_000
+
+/**
+ * Records that the caller exported audit events (CSV built in the browser with
+ * `auditToCsv`). Same permission as reading; human sessions only.
+ */
+export async function recordAuditExport(sys: SystemContext, actor: Actor | null, input: { filter: AuditExportFilter; count: number }): Promise<{ eventId: string }> {
+  const human = requireHuman(sys, actor)
+  await requirePermission(sys, human, P.auditRead)
+  if (!Number.isInteger(input.count) || input.count < 0 || input.count > AUDIT_EXPORT_MAX) throw withOperation(sys, validation("invalid_count", ["count"]))
+  // `apiKeyId` would be masked by `redact` (its name looks like a credential); a key ID is not one.
+  const filter = Object.fromEntries(
+    Object.entries(input.filter)
+      .filter(([, v]) => v !== undefined)
+      .map(([k, v]) => [k === "apiKeyId" ? "keyId" : k, v]),
+  )
+  const eventId = await recordAudit(sys, human, { action: "audit.export", targetType: "audit", targetId: "csv", changes: { filter, count: input.count } })
+  return { eventId }
+}

package/src/core/catalog.ts

@@ -32,6 +32,26 @@ export interface FeatureFlagDefinition {
   default: boolean
 }
 
+/** `module.snake_case`, e.g. `finance.invoice_awaiting_approval`. */
+export const NOTIFICATION_TYPE_ID = /^[a-z][a-z0-9-]*\.[a-z][a-z0-9_]*$/
+
+/**
+ * A kind of notification a module sends. Core stores the type and its JSON
+ * params, never pre-rendered text: the app renders titles (LT/EN) from params.
+ */
+export interface NotificationTypeDefinition {
+  /** Stable `module.snake_case`; starts with `${moduleId}.`. */
+  id: string
+  /** Owning module. A type is visible to a user only while its module is enabled. */
+  moduleId: string
+  /** Channels used until the user sets a preference. */
+  defaultChannels: { inApp: boolean; email: boolean }
+  /** Fallback text for the preferences UI (the app translates by `id`). */
+  description?: string
+  /** Param names the type carries (documentation for the app's renderer). */
+  params?: readonly string[]
+}
+
 export interface ModuleManifest {
   id: string
   kind: ModuleKind
@@ -44,6 +64,8 @@ export interface ModuleManifest {
   dependsOn?: readonly string[]
   /** Config keys the module registers (documentation / status). */
   configKeys?: readonly string[]
+  /** Notification types the module sends (`@digimuza/system-core/notifications`). */
+  notificationTypes?: readonly NotificationTypeDefinition[]
 }
 
 const describedItem = { name: z.string().min(1).max(120), description: z.string().min(1).max(500) }
@@ -62,6 +84,17 @@ export const manifestSchema = z.strictObject({
     .optional(),
   dependsOn: z.array(z.string().regex(MODULE_ID)).optional(),
   configKeys: z.array(z.string().min(1)).optional(),
+  notificationTypes: z
+    .array(
+      z.strictObject({
+        id: z.string().regex(NOTIFICATION_TYPE_ID),
+        moduleId: z.string().regex(MODULE_ID),
+        defaultChannels: z.strictObject({ inApp: z.boolean(), email: z.boolean() }),
+        description: z.string().min(1).max(500).optional(),
+        params: z.array(z.string().min(1).max(64)).optional(),
+      }),
+    )
+    .optional(),
 })
 
 export class CatalogError extends Error {
@@ -101,9 +134,30 @@ export function manifestProblems(manifest: unknown): string[] {
     if (flagIds.has(f.id)) problems.push(`${m.id}: duplicate feature flag ${f.id}`)
     flagIds.add(f.id)
   }
+  const typeIds = new Set<string>()
+  for (const t of m.notificationTypes ?? []) {
+    if (t.moduleId !== m.id) problems.push(`${m.id}: notification type ${t.id} belongs to module ${t.moduleId}`)
+    if (!t.id.startsWith(`${m.id}.`)) problems.push(`${m.id}: notification type ${t.id} must start with "${m.id}."`)
+    if (typeIds.has(t.id)) problems.push(`${m.id}: duplicate notification type ${t.id}`)
+    typeIds.add(t.id)
+  }
   return problems
 }
 
+/**
+ * Declares a notification type. Validates eagerly (id format, module prefix)
+ * and returns a frozen copy. List it in the module manifest's `notificationTypes`.
+ */
+export function defineNotificationType<const T extends NotificationTypeDefinition>(type: T): T {
+  const id = typeof type?.id === "string" ? type.id : ""
+  if (!NOTIFICATION_TYPE_ID.test(id)) throw new Error(`defineNotificationType: invalid id "${id}" (expected module.snake_case, e.g. finance.invoice_awaiting_approval)`)
+  if (typeof type.moduleId !== "string" || !MODULE_ID.test(type.moduleId)) throw new Error(`defineNotificationType(${id}): invalid moduleId`)
+  if (!id.startsWith(`${type.moduleId}.`)) throw new Error(`defineNotificationType(${id}): id must start with "${type.moduleId}."`)
+  const ch = type.defaultChannels
+  if (!ch || typeof ch.inApp !== "boolean" || typeof ch.email !== "boolean") throw new Error(`defineNotificationType(${id}): defaultChannels { inApp, email } are required`)
+  return deepFreeze(structuredClone(type))
+}
+
 type DeepReadonly<T> = T extends readonly (infer U)[] ? readonly DeepReadonly<U>[] : T extends object ? { readonly [K in keyof T]: DeepReadonly<T[K]> } : T
 
 function deepFreeze<T>(value: T): T {
@@ -130,6 +184,7 @@ export type PermissionOf<M extends { permissions: readonly { id: string }[] }> =
 export interface CatalogPermission extends PermissionDefinition { moduleId: string; humanOnly: boolean }
 export interface CatalogSubrole extends SubroleTemplate { moduleId: string }
 export interface CatalogFlag extends FeatureFlagDefinition { moduleId: string }
+export type CatalogNotificationType = NotificationTypeDefinition
 
 export interface SystemRoleTemplate {
   id: string
@@ -147,6 +202,8 @@ export interface Catalog {
   readonly permissions: ReadonlyMap<string, CatalogPermission>
   readonly subroles: ReadonlyMap<string, CatalogSubrole>
   readonly flags: ReadonlyMap<string, CatalogFlag>
+  /** Notification types declared by the composed modules (not part of the catalog version). */
+  readonly notificationTypes: ReadonlyMap<string, CatalogNotificationType>
   readonly systemRoles: readonly SystemRoleTemplate[]
   /** Deterministic serialization of the catalog, for versioning. */
   readonly canonical: string
@@ -168,6 +225,7 @@ export function buildCatalog(
   const permissions = new Map<string, CatalogPermission>()
   const subroles = new Map<string, CatalogSubrole>()
   const flags = new Map<string, CatalogFlag>()
+  const notificationTypes = new Map<string, CatalogNotificationType>()
 
   for (const m of all) {
     problems.push(...manifestProblems(m))
@@ -188,6 +246,10 @@ export function buildCatalog(
       if (flags.has(f.id)) problems.push(`feature flag id collision: ${f.id}`)
       flags.set(f.id, { ...f, moduleId: m.id })
     }
+    for (const t of m.notificationTypes ?? []) {
+      if (notificationTypes.has(t.id)) problems.push(`notification type id collision: ${t.id}`)
+      notificationTypes.set(t.id, t)
+    }
   }
   for (const m of all) {
     for (const dep of m.dependsOn ?? []) if (!modules.has(dep)) problems.push(`${m.id}: depends on unknown module ${dep}`)
@@ -206,6 +268,7 @@ export function buildCatalog(
     permissions,
     subroles,
     flags,
+    notificationTypes,
     systemRoles,
     canonical,
     version: () => sha256Hex(canonical),