@cosmicdrift/kumiko-bundled-features 0.383.0 → 0.384.0

package/dist/audit/event-classification.d.ts

@@ -0,0 +1,8 @@
+export declare const TECHNICAL_EVENT: "technical";
+export type AuditEventStance = typeof TECHNICAL_EVENT | {
+    readonly labelKey: string;
+};
+export declare const AUDIT_EVENT_STANCES: Readonly<Record<string, AuditEventStance>>;
+export declare const FRAMEWORK_SYSTEM_EVENT_TYPES: readonly string[];
+export declare const TECHNICAL_EVENT_TYPES: readonly string[];
+export declare function eventLabelKeyOf(type: string): string | null;

package/dist/audit/event-classification.js

@@ -0,0 +1,69 @@
+// Events that are not entity lifecycle events (`<entity>.created` etc.) need an explicit
+// audit stance: a label key for the log, or "technical" to hide them behind the facet.
+// The boot-registry test fails for a bundled event type that has neither.
+import { WORKFLOW_SYSTEM_EVENT_DEFS } from "@cosmicdrift/kumiko-framework/engine";
+import { ESCAPE_HATCH_USED_EVENT } from "./escape-hatch-audit-sink.js";
+export const TECHNICAL_EVENT = "technical";
+const label = (name) => ({ labelKey: `audit.log.event.${name}` });
+export const AUDIT_EVENT_STANCES = {
+    [ESCAPE_HATCH_USED_EVENT]: TECHNICAL_EVENT,
+    "delivery:event:attempt": TECHNICAL_EVENT,
+    "delivery:event:attempt-address-erased": TECHNICAL_EVENT,
+    "cap-counter:event:rolling-incremented": TECHNICAL_EVENT,
+    "cap-counter:event:rolling-released": TECHNICAL_EVENT,
+    "inbound-mail-foundation:event:inbound-message-received": TECHNICAL_EVENT,
+    "inbound-mail-foundation:event:mail-thread-updated": TECHNICAL_EVENT,
+    "document-ingest-foundation:event:document-ingest-requested": TECHNICAL_EVENT,
+    "document-ingest-foundation:event:document-ingest-skipped": TECHNICAL_EVENT,
+    "tenant-lifecycle:event:tenant-destruction-stage-started": TECHNICAL_EVENT,
+    "tenant-lifecycle:event:tenant-destruction-stage-succeeded": TECHNICAL_EVENT,
+    "tenant-lifecycle:event:tenant-destruction-stage-progressed": TECHNICAL_EVENT,
+    "tenant-lifecycle:event:tenant-destruction-stage-failed": TECHNICAL_EVENT,
+    "tenant-lifecycle:event:tenant-destruction-stage-abandoned": TECHNICAL_EVENT,
+    "custom-fields:event:custom-field-set": label("custom-field-set"),
+    "custom-fields:event:custom-field-cleared": label("custom-field-cleared"),
+    "custom-fields:event:field-definition-deleted": label("field-definition-deleted"),
+    "secrets:event:read": label("secret-read"),
+    "sessions:event:session-revoked": label("session-revoked"),
+    "crypto-shredding:event:subject-forgotten": label("subject-forgotten"),
+    "crypto-shredding:event:forget-denied": label("forget-denied"),
+    "personal-access-tokens:event:pat-revoked": label("pat-revoked"),
+    "inbound-mail-foundation:event:mail-account-connected": label("mail-account-connected"),
+    "inbound-mail-foundation:event:mail-account-updated": label("mail-account-updated"),
+    "inbound-mail-foundation:event:mail-account-disconnected": label("mail-account-disconnected"),
+    "billing-foundation:event:subscription-created": label("subscription-created"),
+    "billing-foundation:event:subscription-updated": label("subscription-updated"),
+    "billing-foundation:event:subscription-canceled": label("subscription-canceled"),
+    "billing-foundation:event:invoice-paid": label("invoice-paid"),
+    "billing-foundation:event:invoice-payment-failed": label("invoice-payment-failed"),
+    "billing-foundation:event:payment-received": label("payment-received"),
+    "billing-foundation:event:checkout-consent-recorded": label("checkout-consent-recorded"),
+    "billing-foundation:event:contract-confirmation-issued": label("contract-confirmation-issued"),
+    "billing-foundation:event:contract-termination-requested": label("contract-termination-requested"),
+    "billing-foundation:event:contract-termination-declared": label("contract-termination-declared"),
+    "billing-foundation:event:contract-termination-unmatched": label("contract-termination-unmatched"),
+    "billing-foundation:event:contract-termination-revoked": label("contract-termination-revoked"),
+    "tenant-lifecycle:event:destruction-requested": label("destruction-requested"),
+    "tenant-lifecycle:event:destruction-cancelled": label("destruction-cancelled"),
+    "tenant-lifecycle:event:tenant-destruction-started": label("tenant-destruction-started"),
+    "tenant-lifecycle:event:tenant-destruction-completed": label("tenant-destruction-completed"),
+    "tenant-lifecycle:event:tenant-destruction-failed": label("tenant-destruction-failed"),
+    "tenant-handover:event:claimed": label("tenant-handover-claimed"),
+    "waitlist:event:exported": label("waitlist-exported"),
+    "waitlist:event:purged": label("waitlist-purged"),
+    "feature-toggles:event:toggle-set": label("feature-toggle-set"),
+};
+// Framework system events (kumiko:system:*) are engine plumbing, never audit-worthy on their own.
+export const FRAMEWORK_SYSTEM_EVENT_TYPES = [
+    ...WORKFLOW_SYSTEM_EVENT_DEFS.keys(),
+];
+export const TECHNICAL_EVENT_TYPES = [
+    ...Object.entries(AUDIT_EVENT_STANCES)
+        .filter(([, stance]) => stance === TECHNICAL_EVENT)
+        .map(([type]) => type),
+    ...FRAMEWORK_SYSTEM_EVENT_TYPES,
+];
+export function eventLabelKeyOf(type) {
+    const stance = AUDIT_EVENT_STANCES[type];
+    return stance === undefined || stance === TECHNICAL_EVENT ? null : stance.labelKey;
+}

package/dist/audit/feature.js

@@ -5,7 +5,7 @@ import { detailsAllTenantsQuery } from "./handlers/details-all-tenants.query.js"
 import { listQuery } from "./handlers/list.query.js";
 import { listAllTenantsQuery } from "./handlers/list-all-tenants.query.js";
 import { runEscapeHatchRetention } from "./run-escape-hatch-retention.js";
-import { AUDIT_LOG_ALL_TENANTS_COLUMNS, AUDIT_LOG_COLUMNS, AUDIT_LOG_DATE_RANGE_FACET, AUDIT_LOG_DETAIL_FIELD_LABELS, AUDIT_LOG_TENANT_FACET, auditLogDetailLayout, } from "./screens.js";
+import { AUDIT_LOG_ALL_TENANTS_COLUMNS, AUDIT_LOG_COLUMNS, AUDIT_LOG_DATE_RANGE_FACET, AUDIT_LOG_DETAIL_FIELD_LABELS, AUDIT_LOG_TECHNICAL_FACET, AUDIT_LOG_TENANT_FACET, auditLogDetailLayout, } from "./screens.js";
 import { AUDIT_LOG_ALL_TENANTS_DETAIL_SCREEN_ID, AUDIT_LOG_ALL_TENANTS_NAV_ID, AUDIT_LOG_ALL_TENANTS_SCREEN_ID, AUDIT_LOG_DETAIL_SCREEN_ID, AUDIT_LOG_SCREEN_ID, AuditQueries, DEFAULT_ESCAPE_HATCH_RETENTION_DAYS, } from "./web/constants.js";
 import { AUDIT_I18N } from "./web/i18n.js";
 // Audit feature — exposes a filtered read over the framework's event log.
@@ -74,7 +74,7 @@ export function createAuditFeature() {
             columns: AUDIT_LOG_COLUMNS,
             searchable: true,
             defaultSort: { field: "createdAt", dir: "desc" },
-            facets: [AUDIT_LOG_DATE_RANGE_FACET],
+            facets: [AUDIT_LOG_DATE_RANGE_FACET, AUDIT_LOG_TECHNICAL_FACET],
             rowActions: [
                 {
                     kind: "navigate",
@@ -106,7 +106,7 @@ export function createAuditFeature() {
             query: AuditQueries.listAllTenants,
             columns: AUDIT_LOG_ALL_TENANTS_COLUMNS,
             defaultSort: { field: "createdAt", dir: "desc" },
-            facets: [AUDIT_LOG_DATE_RANGE_FACET, AUDIT_LOG_TENANT_FACET],
+            facets: [AUDIT_LOG_DATE_RANGE_FACET, AUDIT_LOG_TENANT_FACET, AUDIT_LOG_TECHNICAL_FACET],
             rowActions: [
                 {
                     kind: "navigate",

package/dist/audit/handlers/audit-events.d.ts

@@ -1,4 +1,5 @@
 import { type TenantDb, type WhereObject } from "@cosmicdrift/kumiko-framework/db";
+import type { Registry } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 export declare const auditListPayloadShape: {
     readonly cursor: z.ZodOptional<z.ZodString>;
@@ -20,6 +21,15 @@ export declare const auditListPayloadShape: {
     readonly from: z.ZodOptional<z.ZodISODateTime>;
     readonly to: z.ZodOptional<z.ZodISODateTime>;
 };
+export declare const technicalEntriesFilterSchema: z.ZodObject<{
+    field: z.ZodLiteral<"type">;
+    op: z.ZodLiteral<"in">;
+    value: z.ZodArray<z.ZodLiteral<"include-technical">>;
+}, z.core.$strict>;
+export declare function includesTechnicalEntries(filters: readonly {
+    readonly field: string;
+    readonly value: readonly unknown[];
+}[] | undefined): boolean;
 export declare const auditEventIdSchema: z.ZodString;
 export declare const AUDIT_DATE_RANGE_CHECK: {
     isValid: (v: {
@@ -41,6 +51,7 @@ export type AuditListFilters = {
     to?: string | undefined;
     cursor?: string | undefined;
     before?: string | undefined;
+    includeTechnical?: boolean | undefined;
 };
 /** `tenantCondition` is a tenant id, or an operator object for reads across tenants. */
 export declare function buildAuditWhere(tenantCondition: unknown, p: AuditListFilters, direction: "asc" | "desc"): WhereObject;
@@ -56,25 +67,33 @@ type AuditEventRow = {
     createdAt: unknown;
     createdBy: string;
 };
-export declare function serializeAuditEvent(r: AuditEventRow): {
+export type EntityNounKeyResolver = (aggregateType: string) => string | null;
+export declare function createEntityNounKeyResolver(registry: Registry | undefined): EntityNounKeyResolver;
+export declare function serializeAuditEvent(r: AuditEventRow, nounKeyOf: EntityNounKeyResolver): {
     id: string;
     tenantId: string;
     aggregateId: string;
     aggregateType: string;
     version: number;
     type: string;
+    eventAction: "created" | "deleted" | "restored" | "updated" | null;
+    eventLabelKey: string | null;
+    entityNounKey: string | null;
     payload: unknown;
     metadata: unknown;
     createdAt: unknown;
     createdBy: string;
 };
-export declare function loadAuditEvent(db: TenantDb, where: WhereObject): Promise<{
+export declare function loadAuditEvent(db: TenantDb, where: WhereObject, nounKeyOf: EntityNounKeyResolver): Promise<{
     id: string;
     tenantId: string;
     aggregateId: string;
     aggregateType: string;
     version: number;
     type: string;
+    eventAction: "created" | "deleted" | "restored" | "updated" | null;
+    eventLabelKey: string | null;
+    entityNounKey: string | null;
     payload: unknown;
     metadata: unknown;
     createdAt: unknown;
@@ -83,7 +102,7 @@ export declare function loadAuditEvent(db: TenantDb, where: WhereObject): Promis
 export declare function listAuditEvents(db: TenantDb, where: WhereObject, p: {
     limit: number;
     sort?: "createdAt" | "type" | undefined;
-}, direction: "asc" | "desc"): Promise<{
+}, direction: "asc" | "desc", nounKeyOf: EntityNounKeyResolver): Promise<{
     rows: {
         id: string;
         tenantId: string;
@@ -91,6 +110,9 @@ export declare function listAuditEvents(db: TenantDb, where: WhereObject, p: {
         aggregateType: string;
         version: number;
         type: string;
+        eventAction: "created" | "deleted" | "restored" | "updated" | null;
+        eventLabelKey: string | null;
+        entityNounKey: string | null;
         payload: unknown;
         metadata: unknown;
         createdAt: unknown;

package/dist/audit/handlers/audit-events.js

@@ -9,6 +9,8 @@ import { eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import * as z from "zod";
 import { redactPiiCiphertext } from "../../shared/index.js";
+import { eventLabelKeyOf, TECHNICAL_EVENT_TYPES } from "../event-classification.js";
+import { AUDIT_EVENT_ACTIONS, INCLUDE_TECHNICAL_FILTER, } from "../web/constants.js";
 const MAX_LIMIT = 100;
 // At most 18 digits keeps the id inside bigint, so an oversized cursor or id is a 422, not a 500.
 const CURSOR_PATTERN = /^\d{1,18}$/;
@@ -26,6 +28,15 @@ export const auditListPayloadShape = {
     from: z.iso.datetime().optional(),
     to: z.iso.datetime().optional(),
 };
+// The technical-entries facet rides on the `type` column (facets need a declared column).
+export const technicalEntriesFilterSchema = z.strictObject({
+    field: z.literal("type"),
+    op: z.literal("in"),
+    value: z.array(z.literal(INCLUDE_TECHNICAL_FILTER)).max(1),
+});
+export function includesTechnicalEntries(filters) {
+    return (filters?.some((f) => f.field === "type" && f.value.includes(INCLUDE_TECHNICAL_FILTER)) ?? false);
+}
 export const auditEventIdSchema = z
     .string()
     .regex(/^[1-9]\d{0,17}$/, "id must be a positive integer");
@@ -58,8 +69,12 @@ export function buildAuditWhere(tenantCondition, p, direction) {
         where["aggregateId"] = p.aggregateId;
     if (p.eventType)
         where["type"] = p.eventType;
-    else if (p.search)
-        where["type"] = { like: `%${escapeLikePattern(p.search)}%` };
+    else if (p.search || !p.includeTechnical) {
+        where["type"] = {
+            ...(p.search && { like: `%${escapeLikePattern(p.search)}%` }),
+            ...(!p.includeTechnical && { notIn: TECHNICAL_EVENT_TYPES }),
+        };
+    }
     if (p.userId)
         where["createdBy"] = p.userId;
     const range = buildDateRange(p.from, p.to);
@@ -72,7 +87,23 @@ export function buildAuditWhere(tenantCondition, p, direction) {
         where["id"] = direction === "asc" ? { gt: BigInt(cursor) } : { lt: BigInt(cursor) };
     return where;
 }
-export function serializeAuditEvent(r) {
+function eventActionOf(type) {
+    const suffix = type.slice(type.lastIndexOf(".") + 1);
+    return type.includes(".") ? (AUDIT_EVENT_ACTIONS.find((a) => a === suffix) ?? null) : null;
+}
+export function createEntityNounKeyResolver(registry) {
+    const featureByEntity = new Map();
+    for (const [featureName, feature] of registry?.features ?? []) {
+        for (const entityName of Object.keys(feature.entities ?? {})) {
+            featureByEntity.set(entityName, featureName);
+        }
+    }
+    return (aggregateType) => {
+        const featureName = featureByEntity.get(aggregateType);
+        return featureName === undefined ? null : `${featureName}:entity:${aggregateType}:noun`;
+    };
+}
+export function serializeAuditEvent(r, nounKeyOf) {
     return {
         id: String(r.id),
         tenantId: r.tenantId,
@@ -80,18 +111,21 @@ export function serializeAuditEvent(r) {
         aggregateType: r.aggregateType,
         version: r.version,
         type: r.type,
+        eventAction: eventActionOf(r.type),
+        eventLabelKey: eventLabelKeyOf(r.type),
+        entityNounKey: nounKeyOf(r.aggregateType),
         payload: redactPiiCiphertext(r.payload),
         metadata: redactPiiCiphertext(r.metadata),
         createdAt: r.createdAt,
         createdBy: r.createdBy,
     };
 }
-export async function loadAuditEvent(db, where) {
+export async function loadAuditEvent(db, where, nounKeyOf) {
     const rows = await selectMany(db, eventsTable, where, { limit: 1 });
     const row = rows[0];
-    return row === undefined ? null : serializeAuditEvent(row);
+    return row === undefined ? null : serializeAuditEvent(row, nounKeyOf);
 }
-export async function listAuditEvents(db, where, p, direction) {
+export async function listAuditEvents(db, where, p, direction, nounKeyOf) {
     const rows = await selectMany(db, eventsTable, where, {
         // The id cursor only resumes an id-ordered listing. created_at comes from the
         // transaction start and can run against insert order, so ordering by it would let
@@ -104,7 +138,7 @@ export async function listAuditEvents(db, where, p, direction) {
             : [{ col: "id", direction }],
         limit: p.limit,
     });
-    const serialised = rows.map(serializeAuditEvent);
+    const serialised = rows.map((row) => serializeAuditEvent(row, nounKeyOf));
     const last = serialised[serialised.length - 1];
     // An id cursor cannot resume a type-ordered listing, so that sort is one page.
     const nextId = serialised.length === p.limit && last && p.sort !== "type" ? last.id : null;

package/dist/audit/handlers/details-all-tenants.query.d.ts

@@ -8,6 +8,9 @@ export declare const detailsAllTenantsQuery: import("@cosmicdrift/kumiko-types/d
     aggregateType: string;
     version: number;
     type: string;
+    eventAction: "created" | "deleted" | "restored" | "updated" | null;
+    eventLabelKey: string | null;
+    entityNounKey: string | null;
     payload: unknown;
     metadata: unknown;
     createdAt: unknown;

package/dist/audit/handlers/details-all-tenants.query.js

@@ -1,7 +1,7 @@
 // One audit event of any tenant by its event-store id, for the all-tenants log's detail screen.
 import { access, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
-import { auditEventIdSchema, loadAuditEvent } from "./audit-events.js";
+import { auditEventIdSchema, createEntityNounKeyResolver, loadAuditEvent } from "./audit-events.js";
 import { requireAuditSystemDb } from "./audit-system-db.js";
 import { allTenantsCondition, assertMayReadAllTenants } from "./resolve-audit-tenant.js";
 export const detailsAllTenantsQuery = defineQueryHandler({
@@ -12,9 +12,6 @@ export const detailsAllTenantsQuery = defineQueryHandler({
     handler: async (query, ctx) => {
         assertMayReadAllTenants(query.user);
         const db = requireAuditSystemDb(ctx.systemDb, "audit:query:details-all-tenants").acknowledgeCrossTenant("SystemAdmin reads one audit event of any tenant");
-        return loadAuditEvent(db, {
-            tenantId: allTenantsCondition(undefined),
-            id: BigInt(query.payload.id),
-        });
+        return loadAuditEvent(db, { tenantId: allTenantsCondition(undefined), id: BigInt(query.payload.id) }, createEntityNounKeyResolver(ctx.registry));
     },
 });

package/dist/audit/handlers/details.query.d.ts

@@ -12,6 +12,9 @@ export declare const detailsQuery: import("@cosmicdrift/kumiko-types/define-hand
     aggregateType: string;
     version: number;
     type: string;
+    eventAction: "created" | "deleted" | "restored" | "updated" | null;
+    eventLabelKey: string | null;
+    entityNounKey: string | null;
     payload: unknown;
     metadata: unknown;
     createdAt: unknown;

package/dist/audit/handlers/details.query.js

@@ -5,7 +5,7 @@
 import { access, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 import { AUDIT_SCOPE_VALUES } from "../web/constants.js";
-import { auditEventIdSchema, loadAuditEvent } from "./audit-events.js";
+import { auditEventIdSchema, createEntityNounKeyResolver, loadAuditEvent } from "./audit-events.js";
 import { requireAuditSystemDb } from "./audit-system-db.js";
 import { resolveAuditScopeFilter } from "./resolve-audit-tenant.js";
 export const detailsQuery = defineQueryHandler({
@@ -21,8 +21,10 @@ export const detailsQuery = defineQueryHandler({
         const db = requireAuditSystemDb(ctx.systemDb, "audit:query:details").assertTenantMatch(query.user.tenantId);
         return loadAuditEvent(db, {
             tenantId: scopeFilter.tenantId,
-            ...(scopeFilter.aggregateType !== undefined && { aggregateType: scopeFilter.aggregateType }),
+            ...(scopeFilter.aggregateType !== undefined && {
+                aggregateType: scopeFilter.aggregateType,
+            }),
             id: BigInt(query.payload.id),
-        });
+        }, createEntityNounKeyResolver(ctx.registry));
     },
 });

package/dist/audit/handlers/list-all-tenants.query.d.ts

@@ -18,11 +18,15 @@ export declare const listAllTenantsQuery: import("@cosmicdrift/kumiko-types/defi
     }>>;
     from: z.ZodOptional<z.ZodISODateTime>;
     to: z.ZodOptional<z.ZodISODateTime>;
-    filters: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    filters: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
         field: z.ZodLiteral<"tenantId">;
         op: z.ZodLiteral<"in">;
         value: z.ZodArray<z.ZodUUID>;
-    }, z.core.$strict>>>;
+    }, z.core.$strict>, z.ZodObject<{
+        field: z.ZodLiteral<"type">;
+        op: z.ZodLiteral<"in">;
+        value: z.ZodArray<z.ZodLiteral<"include-technical">>;
+    }, z.core.$strict>]>>>;
 }, z.core.$strip>, {
     rows: {
         id: string;
@@ -31,6 +35,9 @@ export declare const listAllTenantsQuery: import("@cosmicdrift/kumiko-types/defi
         aggregateType: string;
         version: number;
         type: string;
+        eventAction: "created" | "deleted" | "restored" | "updated" | null;
+        eventLabelKey: string | null;
+        entityNounKey: string | null;
         payload: unknown;
         metadata: unknown;
         createdAt: unknown;

package/dist/audit/handlers/list-all-tenants.query.js

@@ -2,31 +2,33 @@
 // allTenantsCondition). Rows carry their tenantId so the screen can label the tenant.
 import { access, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
-import { AUDIT_DATE_RANGE_CHECK, auditListPayloadShape, buildAuditWhere, listAuditEvents, } from "./audit-events.js";
+import { AUDIT_DATE_RANGE_CHECK, auditListPayloadShape, buildAuditWhere, createEntityNounKeyResolver, includesTechnicalEntries, listAuditEvents, technicalEntriesFilterSchema, } from "./audit-events.js";
 import { requireAuditSystemDb } from "./audit-system-db.js";
 import { allTenantsCondition, assertMayReadAllTenants } from "./resolve-audit-tenant.js";
 const MAX_TENANT_FILTER_IDS = 100;
 // The reference facet on the tenant column sends exactly this shape.
-const tenantIdFiltersSchema = z
-    .array(z.strictObject({
+const tenantIdFilterSchema = z.strictObject({
     field: z.literal("tenantId"),
     op: z.literal("in"),
     value: z.array(z.uuid()).max(MAX_TENANT_FILTER_IDS),
-}))
-    .max(1);
+});
+const auditFiltersSchema = z
+    .array(z.union([tenantIdFilterSchema, technicalEntriesFilterSchema]))
+    .max(2);
 export const listAllTenantsQuery = defineQueryHandler({
     name: "list-all-tenants",
     description: "Lists audit-trail events of every tenant newest-first with cursor paging, each row carrying its tenantId; filterable by tenant, aggregate type, aggregate id, event type, actor and time range. SystemAdmin only; events of the system tenant are not included.",
     schema: z
-        .object({ ...auditListPayloadShape, filters: tenantIdFiltersSchema.optional() })
+        .object({ ...auditListPayloadShape, filters: auditFiltersSchema.optional() })
         .refine(AUDIT_DATE_RANGE_CHECK.isValid, AUDIT_DATE_RANGE_CHECK.params),
     access: { roles: access.systemAdmin },
     handler: async (query, ctx) => {
         assertMayReadAllTenants(query.user);
         const p = query.payload;
         const direction = p.sortDirection ?? "desc";
-        const where = buildAuditWhere(allTenantsCondition(p.filters?.[0]?.value), p, direction);
+        const requestedTenantIds = p.filters?.find((f) => f.field === "tenantId")?.value;
+        const where = buildAuditWhere(allTenantsCondition(requestedTenantIds), { ...p, includeTechnical: includesTechnicalEntries(p.filters) }, direction);
         const db = requireAuditSystemDb(ctx.systemDb, "audit:query:list-all-tenants").acknowledgeCrossTenant("SystemAdmin reads the audit trail of every tenant");
-        return listAuditEvents(db, where, p, direction);
+        return listAuditEvents(db, where, p, direction, createEntityNounKeyResolver(ctx.registry));
     },
 });

package/dist/audit/handlers/list.query.d.ts

@@ -22,6 +22,11 @@ export declare const listQuery: import("@cosmicdrift/kumiko-types/define-handler
         system: "system";
         tenant: "tenant";
     }>>;
+    filters: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        field: z.ZodLiteral<"type">;
+        op: z.ZodLiteral<"in">;
+        value: z.ZodArray<z.ZodLiteral<"include-technical">>;
+    }, z.core.$strict>>>;
 }, z.core.$strip>, {
     rows: {
         id: string;
@@ -30,6 +35,9 @@ export declare const listQuery: import("@cosmicdrift/kumiko-types/define-handler
         aggregateType: string;
         version: number;
         type: string;
+        eventAction: "created" | "deleted" | "restored" | "updated" | null;
+        eventLabelKey: string | null;
+        entityNounKey: string | null;
         payload: unknown;
         metadata: unknown;
         createdAt: unknown;

package/dist/audit/handlers/list.query.js

@@ -11,22 +11,30 @@
 import { access, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 import { AUDIT_SCOPE_VALUES } from "../web/constants.js";
-import { AUDIT_DATE_RANGE_CHECK, auditListPayloadShape, buildAuditWhere, listAuditEvents, } from "./audit-events.js";
+import { AUDIT_DATE_RANGE_CHECK, auditListPayloadShape, buildAuditWhere, createEntityNounKeyResolver, includesTechnicalEntries, listAuditEvents, technicalEntriesFilterSchema, } from "./audit-events.js";
 import { requireAuditSystemDb } from "./audit-system-db.js";
 import { resolveAuditScopeFilter } from "./resolve-audit-tenant.js";
 export const listQuery = defineQueryHandler({
     name: "list",
     description: 'Lists the tenant\'s audit-trail events newest-first with cursor paging, filterable by aggregate type, aggregate id, event type, actor and time range; use it to answer who changed what and when. A SystemAdmin can set scope "system" to read the app-instance system events (e.g. app.started) instead of the own tenant.',
     schema: z
-        .object({ ...auditListPayloadShape, scope: z.enum(AUDIT_SCOPE_VALUES).optional() })
+        .object({
+        ...auditListPayloadShape,
+        scope: z.enum(AUDIT_SCOPE_VALUES).optional(),
+        filters: z.array(technicalEntriesFilterSchema).max(1).optional(),
+    })
         .refine(AUDIT_DATE_RANGE_CHECK.isValid, AUDIT_DATE_RANGE_CHECK.params),
     access: { roles: access.admin },
     handler: async (query, ctx) => {
         const p = query.payload;
         const scopeFilter = resolveAuditScopeFilter(query.user, p.scope);
         const direction = p.sortDirection ?? "desc";
-        const where = buildAuditWhere(scopeFilter.tenantId, { ...p, aggregateType: scopeFilter.aggregateType ?? p.aggregateType }, direction);
+        const where = buildAuditWhere(scopeFilter.tenantId, {
+            ...p,
+            aggregateType: scopeFilter.aggregateType ?? p.aggregateType,
+            includeTechnical: includesTechnicalEntries(p.filters),
+        }, direction);
         const db = requireAuditSystemDb(ctx.systemDb, "audit:query:list").assertTenantMatch(query.user.tenantId);
-        return listAuditEvents(db, where, p, direction);
+        return listAuditEvents(db, where, p, direction, createEntityNounKeyResolver(ctx.registry));
     },
 });

package/dist/audit/screens.d.ts

@@ -8,6 +8,20 @@ export declare const AUDIT_LOG_COLUMNS: readonly [{
 }, {
     readonly field: "type";
     readonly label: string;
+    readonly renderer: {
+        readonly react: {
+            readonly __component: "audit-event-cell";
+        };
+    };
+}, {
+    readonly field: "aggregateType";
+    readonly label: string;
+    readonly renderer: {
+        readonly react: {
+            readonly __component: "audit-object-cell";
+        };
+    };
+    readonly hideOnNarrow: true;
 }, {
     readonly refEntity: "user:user";
     readonly refLabelField: "displayName";
@@ -28,6 +42,20 @@ export declare const AUDIT_LOG_ALL_TENANTS_COLUMNS: readonly [{
 }, {
     readonly field: "type";
     readonly label: string;
+    readonly renderer: {
+        readonly react: {
+            readonly __component: "audit-event-cell";
+        };
+    };
+}, {
+    readonly field: "aggregateType";
+    readonly label: string;
+    readonly renderer: {
+        readonly react: {
+            readonly __component: "audit-object-cell";
+        };
+    };
+    readonly hideOnNarrow: true;
 }, {
     readonly refEntity: "user:user";
     readonly refLabelField: "displayName";
@@ -43,6 +71,15 @@ export declare const AUDIT_LOG_DATE_RANGE_FACET: {
         readonly to: "to";
     };
 };
+export declare const AUDIT_LOG_TECHNICAL_FACET: {
+    readonly type: "select";
+    readonly field: "type";
+    readonly label: string;
+    readonly options: readonly [{
+        readonly value: "include-technical";
+        readonly label: string;
+    }];
+};
 export declare const AUDIT_LOG_TENANT_FACET: {
     readonly type: "reference";
     readonly field: "tenantId";

package/dist/audit/screens.js

@@ -1,6 +1,7 @@
 // Columns, labels and layout shared by the tenant audit log and its all-tenants variant, so the
 // two screen pairs cannot drift apart. The all-tenants variant only adds the tenant.
 import { i18nKey } from "@cosmicdrift/kumiko-framework/engine";
+import { AUDIT_EVENT_CELL_COMPONENT, AUDIT_OBJECT_CELL_COMPONENT, INCLUDE_TECHNICAL_FILTER, } from "./web/constants.js";
 const TENANT_REFERENCE = { refEntity: "tenant:tenant", refLabelField: "name" };
 const ACTOR_REFERENCE = { refEntity: "user:user", refLabelField: "displayName" };
 const WHEN_COLUMN = {
@@ -13,17 +14,30 @@ const TENANT_COLUMN = {
     label: i18nKey("audit.log.col.tenant"),
     ...TENANT_REFERENCE,
 };
-const TYPE_COLUMN = { field: "type", label: i18nKey("audit.log.col.type") };
+const EVENT_RENDERER = { react: { __component: AUDIT_EVENT_CELL_COMPONENT } };
+const OBJECT_RENDERER = { react: { __component: AUDIT_OBJECT_CELL_COMPONENT } };
+const TYPE_COLUMN = {
+    field: "type",
+    label: i18nKey("audit.log.col.type"),
+    renderer: EVENT_RENDERER,
+};
+const OBJECT_COLUMN = {
+    field: "aggregateType",
+    label: i18nKey("audit.log.col.aggregateType"),
+    renderer: OBJECT_RENDERER,
+    hideOnNarrow: true,
+};
 const ACTOR_COLUMN = {
     field: "createdBy",
     label: i18nKey("audit.log.col.actor"),
     ...ACTOR_REFERENCE,
 };
-export const AUDIT_LOG_COLUMNS = [WHEN_COLUMN, TYPE_COLUMN, ACTOR_COLUMN];
+export const AUDIT_LOG_COLUMNS = [WHEN_COLUMN, TYPE_COLUMN, OBJECT_COLUMN, ACTOR_COLUMN];
 export const AUDIT_LOG_ALL_TENANTS_COLUMNS = [
     WHEN_COLUMN,
     TENANT_COLUMN,
     TYPE_COLUMN,
+    OBJECT_COLUMN,
     ACTOR_COLUMN,
 ];
 export const AUDIT_LOG_DATE_RANGE_FACET = {
@@ -32,6 +46,14 @@ export const AUDIT_LOG_DATE_RANGE_FACET = {
     label: i18nKey("audit.log.col.when"),
     params: { from: "from", to: "to" },
 };
+export const AUDIT_LOG_TECHNICAL_FACET = {
+    type: "select",
+    field: "type",
+    label: i18nKey("audit.log.facet.technical"),
+    options: [
+        { value: INCLUDE_TECHNICAL_FILTER, label: i18nKey("audit.log.facet.technical.include") },
+    ],
+};
 export const AUDIT_LOG_TENANT_FACET = {
     type: "reference",
     field: "tenantId",
@@ -54,10 +76,10 @@ export function auditLogDetailLayout(options) {
         sections: [
             {
                 fields: [
-                    "type",
+                    { field: "type", renderer: EVENT_RENDERER },
                     { field: "createdAt", renderer: { format: "timestamp" } },
                     ...(options.withTenant ? [{ field: "tenantId", ...TENANT_REFERENCE }] : []),
-                    "aggregateType",
+                    { field: "aggregateType", renderer: OBJECT_RENDERER },
                     "aggregateId",
                     { field: "createdBy", ...ACTOR_REFERENCE },
                     "id",

package/dist/audit/web/audit-event-cell.d.ts

@@ -0,0 +1,4 @@
+import { type ColumnRendererProps } from "@cosmicdrift/kumiko-renderer";
+import type { ReactNode } from "react";
+export declare function AuditEventCell({ value, row }: ColumnRendererProps): ReactNode;
+export declare function AuditObjectCell({ row }: ColumnRendererProps): ReactNode;

package/dist/audit/web/audit-event-cell.js

@@ -0,0 +1,20 @@
+// Column renderers of the audit log, registered via `auditClient()`'s `columnRenderers`
+// (screens.ts references them by name). The list frame stays the generic projectionList.
+import { useTranslation } from "@cosmicdrift/kumiko-renderer";
+import { auditEntityLabel, isAuditEventAction } from "./audit-event-labels.js";
+export function AuditEventCell({ value, row }) {
+    const t = useTranslation();
+    const rawType = typeof value === "string" ? value : "";
+    const labelKey = row["eventLabelKey"];
+    if (typeof labelKey === "string")
+        return t(labelKey);
+    const action = row["eventAction"];
+    const entity = auditEntityLabel(t, row);
+    if (!isAuditEventAction(action) || entity === null)
+        return rawType;
+    return t("audit.log.event", { entity, action: t(`audit.log.action.${action}`) });
+}
+export function AuditObjectCell({ row }) {
+    const t = useTranslation();
+    return auditEntityLabel(t, row) ?? "";
+}

package/dist/audit/web/audit-event-labels.d.ts

@@ -0,0 +1,7 @@
+import type { useTranslation } from "@cosmicdrift/kumiko-renderer";
+import { type AuditEventAction } from "./constants.ts";
+type Translate = ReturnType<typeof useTranslation>;
+export declare function isAuditEventAction(value: unknown): value is AuditEventAction;
+/** Singular entity noun: the entity's own `:noun` key, then the audit log's label for bundled entities, then the humanized aggregate type. */
+export declare function auditEntityLabel(t: Translate, row: Readonly<Record<string, unknown>>): string | null;
+export {};