@cosmicdrift/kumiko-samples 0.383.1 → 0.385.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.383.1",
+  "version": "0.385.0",
   "description": "Source trees of the Kumiko sample recipes, sample apps and bundled features in repo layout, for tooling such as few-shot corpus builds.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/packages/bundled-features/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.383.1",
+  "version": "0.385.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -122,6 +122,7 @@
     "./presets": "./src/presets/index.ts",
     "./secrets": "./src/secrets/index.ts",
     "./sessions": "./src/sessions/index.ts",
+    "./sessions/web": "./src/sessions/web/index.ts",
     "./auth-mfa": "./src/auth-mfa/index.ts",
     "./auth-mfa-user-data": "./src/auth-mfa-user-data/index.ts",
     "./auth-mfa/web": "./src/auth-mfa/web/index.ts",
@@ -594,6 +595,10 @@
         "types": "./dist/sessions/index.d.ts",
         "default": "./dist/sessions/index.js"
       },
+      "./sessions/web": {
+        "types": "./dist/sessions/web/index.d.ts",
+        "default": "./dist/sessions/web/index.js"
+      },
       "./auth-mfa": {
         "types": "./dist/auth-mfa/index.d.ts",
         "default": "./dist/auth-mfa/index.js"

package/packages/bundled-features/src/audit/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.384.0",
+    "type": "improvement",
+    "title": "Audit log shows a label for every event type and hides technical entries",
+    "detail": "Events that are not entity lifecycle events get a readable label (for example \"Custom field value set\") or are classified technical (delivery attempts, counters, tenant-destruction stages) and hidden by default behind \"Show technical entries\". New event types of bundled features need an entry in the audit classification; a test over all registered events fails without one. Apps that add their own event types are unaffected, they keep the entity and action wording or the raw type."
+  },
   {
     "version": "0.383.0",
     "type": "improvement",

package/packages/bundled-features/src/audit/event-classification.ts

@@ -0,0 +1,83 @@
+// 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.ts";
+
+export const TECHNICAL_EVENT = "technical" as const;
+
+export type AuditEventStance = typeof TECHNICAL_EVENT | { readonly labelKey: string };
+
+const label = (name: string): AuditEventStance => ({ labelKey: `audit.log.event.${name}` });
+
+export const AUDIT_EVENT_STANCES: Readonly<Record<string, AuditEventStance>> = {
+  [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: readonly string[] = [
+  ...WORKFLOW_SYSTEM_EVENT_DEFS.keys(),
+];
+
+export const TECHNICAL_EVENT_TYPES: readonly string[] = [
+  ...Object.entries(AUDIT_EVENT_STANCES)
+    .filter(([, stance]) => stance === TECHNICAL_EVENT)
+    .map(([type]) => type),
+  ...FRAMEWORK_SYSTEM_EVENT_TYPES,
+];
+
+export function eventLabelKeyOf(type: string): string | null {
+  const stance = AUDIT_EVENT_STANCES[type];
+  return stance === undefined || stance === TECHNICAL_EVENT ? null : stance.labelKey;
+}

package/packages/bundled-features/src/audit/feature.ts

@@ -17,6 +17,7 @@ import {
   AUDIT_LOG_COLUMNS,
   AUDIT_LOG_DATE_RANGE_FACET,
   AUDIT_LOG_DETAIL_FIELD_LABELS,
+  AUDIT_LOG_TECHNICAL_FACET,
   AUDIT_LOG_TENANT_FACET,
   auditLogDetailLayout,
 } from "./screens.ts";
@@ -111,7 +112,7 @@ export function createAuditFeature(): FeatureDefinition {
         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",
@@ -143,7 +144,7 @@ export function createAuditFeature(): FeatureDefinition {
         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/packages/bundled-features/src/audit/handlers/audit-events.ts

@@ -6,10 +6,17 @@
 // REDACTED_PII_PLACEHOLDER before returning (payload and metadata), since the API leak guard refuses ciphertext.
 
 import { selectMany, type TenantDb, type WhereObject } from "@cosmicdrift/kumiko-framework/db";
+import type { Registry } from "@cosmicdrift/kumiko-framework/engine";
 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.ts";
+import { eventLabelKeyOf, TECHNICAL_EVENT_TYPES } from "../event-classification.ts";
+import {
+  AUDIT_EVENT_ACTIONS,
+  type AuditEventAction,
+  INCLUDE_TECHNICAL_FILTER,
+} from "../web/constants.ts";
 
 const MAX_LIMIT = 100;
 
@@ -31,6 +38,21 @@ export const auditListPayloadShape = {
   to: z.iso.datetime().optional(),
 } as const;
 
+// 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: readonly { readonly field: string; readonly value: readonly unknown[] }[] | undefined,
+): boolean {
+  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");
@@ -69,6 +91,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. */
@@ -81,7 +104,12 @@ export function buildAuditWhere(
   if (p.aggregateType) where["aggregateType"] = p.aggregateType;
   if (p.aggregateId) 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);
   if (range) where["createdAt"] = range;
@@ -105,7 +133,29 @@ type AuditEventRow = {
   createdBy: string;
 };
 
-export function serializeAuditEvent(r: AuditEventRow) {
+function eventActionOf(type: string): AuditEventAction | null {
+  const suffix = type.slice(type.lastIndexOf(".") + 1);
+  return type.includes(".") ? (AUDIT_EVENT_ACTIONS.find((a) => a === suffix) ?? null) : null;
+}
+
+// Entity events carry the entity name as aggregateType; the noun key is the
+// renderer's own `<feature>:entity:<entity>:noun` convention.
+export type EntityNounKeyResolver = (aggregateType: string) => string | null;
+
+export function createEntityNounKeyResolver(registry: Registry | undefined): EntityNounKeyResolver {
+  const featureByEntity = new Map<string, string>();
+  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: AuditEventRow, nounKeyOf: EntityNounKeyResolver) {
   return {
     id: String(r.id),
     tenantId: r.tenantId,
@@ -113,6 +163,9 @@ export function serializeAuditEvent(r: AuditEventRow) {
     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,
@@ -120,10 +173,14 @@ export function serializeAuditEvent(r: AuditEventRow) {
   };
 }
 
-export async function loadAuditEvent(db: TenantDb, where: WhereObject) {
+export async function loadAuditEvent(
+  db: TenantDb,
+  where: WhereObject,
+  nounKeyOf: EntityNounKeyResolver,
+) {
   const rows = await selectMany<AuditEventRow>(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(
@@ -131,6 +188,7 @@ export async function listAuditEvents(
   where: WhereObject,
   p: { limit: number; sort?: "createdAt" | "type" | undefined },
   direction: "asc" | "desc",
+  nounKeyOf: EntityNounKeyResolver,
 ) {
   const rows = await selectMany<AuditEventRow>(db, eventsTable, where, {
     // The id cursor only resumes an id-ordered listing. created_at comes from the
@@ -145,7 +203,7 @@ export async function listAuditEvents(
         : [{ 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/packages/bundled-features/src/audit/handlers/details-all-tenants.query.ts

@@ -2,7 +2,7 @@
 
 import { access, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
-import { auditEventIdSchema, loadAuditEvent } from "./audit-events.ts";
+import { auditEventIdSchema, createEntityNounKeyResolver, loadAuditEvent } from "./audit-events.ts";
 import { requireAuditSystemDb } from "./audit-system-db.ts";
 import { allTenantsCondition, assertMayReadAllTenants } from "./resolve-audit-tenant.ts";
 
@@ -18,9 +18,10 @@ export const detailsAllTenantsQuery = defineQueryHandler({
       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/packages/bundled-features/src/audit/handlers/details.query.ts

@@ -6,7 +6,7 @@
 import { access, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 import { AUDIT_SCOPE_VALUES } from "../web/constants.ts";
-import { auditEventIdSchema, loadAuditEvent } from "./audit-events.ts";
+import { auditEventIdSchema, createEntityNounKeyResolver, loadAuditEvent } from "./audit-events.ts";
 import { requireAuditSystemDb } from "./audit-system-db.ts";
 import { resolveAuditScopeFilter } from "./resolve-audit-tenant.ts";
 
@@ -24,10 +24,16 @@ 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 }),
-      id: BigInt(query.payload.id),
-    });
+    return loadAuditEvent(
+      db,
+      {
+        tenantId: scopeFilter.tenantId,
+        ...(scopeFilter.aggregateType !== undefined && {
+          aggregateType: scopeFilter.aggregateType,
+        }),
+        id: BigInt(query.payload.id),
+      },
+      createEntityNounKeyResolver(ctx.registry),
+    );
   },
 });

package/packages/bundled-features/src/audit/handlers/list-all-tenants.query.ts

@@ -7,7 +7,10 @@ import {
   AUDIT_DATE_RANGE_CHECK,
   auditListPayloadShape,
   buildAuditWhere,
+  createEntityNounKeyResolver,
+  includesTechnicalEntries,
   listAuditEvents,
+  technicalEntriesFilterSchema,
 } from "./audit-events.ts";
 import { requireAuditSystemDb } from "./audit-system-db.ts";
 import { allTenantsCondition, assertMayReadAllTenants } from "./resolve-audit-tenant.ts";
@@ -15,33 +18,38 @@ import { allTenantsCondition, assertMayReadAllTenants } from "./resolve-audit-te
 const MAX_TENANT_FILTER_IDS = 100;
 
 // The reference facet on the tenant column sends exactly this shape.
-const tenantIdFiltersSchema = z
-  .array(
-    z.strictObject({
-      field: z.literal("tenantId"),
-      op: z.literal("in"),
-      value: z.array(z.uuid()).max(MAX_TENANT_FILTER_IDS),
-    }),
-  )
-  .max(1);
+const tenantIdFilterSchema = z.strictObject({
+  field: z.literal("tenantId"),
+  op: z.literal("in"),
+  value: z.array(z.uuid()).max(MAX_TENANT_FILTER_IDS),
+});
+
+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/packages/bundled-features/src/audit/handlers/list.query.ts

@@ -16,7 +16,10 @@ import {
   AUDIT_DATE_RANGE_CHECK,
   auditListPayloadShape,
   buildAuditWhere,
+  createEntityNounKeyResolver,
+  includesTechnicalEntries,
   listAuditEvents,
+  technicalEntriesFilterSchema,
 } from "./audit-events.ts";
 import { requireAuditSystemDb } from "./audit-system-db.ts";
 import { resolveAuditScopeFilter } from "./resolve-audit-tenant.ts";
@@ -26,7 +29,11 @@ export const listQuery = defineQueryHandler({
   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) => {
@@ -35,12 +42,16 @@ export const listQuery = defineQueryHandler({
     const direction = p.sortDirection ?? "desc";
     const where = buildAuditWhere(
       scopeFilter.tenantId,
-      { ...p, aggregateType: scopeFilter.aggregateType ?? p.aggregateType },
+      {
+        ...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/packages/bundled-features/src/audit/screens.ts

@@ -3,6 +3,11 @@
 
 import { i18nKey } from "@cosmicdrift/kumiko-framework/engine";
 import type { EditLayout, ListColumnSpec } from "@cosmicdrift/kumiko-framework/ui-types";
+import {
+  AUDIT_EVENT_CELL_COMPONENT,
+  AUDIT_OBJECT_CELL_COMPONENT,
+  INCLUDE_TECHNICAL_FILTER,
+} from "./web/constants.ts";
 
 const TENANT_REFERENCE = { refEntity: "tenant:tenant", refLabelField: "name" } as const;
 const ACTOR_REFERENCE = { refEntity: "user:user", refLabelField: "displayName" } as const;
@@ -17,18 +22,32 @@ const TENANT_COLUMN = {
   label: i18nKey("audit.log.col.tenant"),
   ...TENANT_REFERENCE,
 } as const satisfies ListColumnSpec;
-const TYPE_COLUMN = { field: "type", label: i18nKey("audit.log.col.type") } as const;
+const EVENT_RENDERER = { react: { __component: AUDIT_EVENT_CELL_COMPONENT } } as const;
+const OBJECT_RENDERER = { react: { __component: AUDIT_OBJECT_CELL_COMPONENT } } as const;
+
+const TYPE_COLUMN = {
+  field: "type",
+  label: i18nKey("audit.log.col.type"),
+  renderer: EVENT_RENDERER,
+} as const satisfies ListColumnSpec;
+const OBJECT_COLUMN = {
+  field: "aggregateType",
+  label: i18nKey("audit.log.col.aggregateType"),
+  renderer: OBJECT_RENDERER,
+  hideOnNarrow: true,
+} as const satisfies ListColumnSpec;
 const ACTOR_COLUMN = {
   field: "createdBy",
   label: i18nKey("audit.log.col.actor"),
   ...ACTOR_REFERENCE,
 } as const satisfies ListColumnSpec;
 
-export const AUDIT_LOG_COLUMNS = [WHEN_COLUMN, TYPE_COLUMN, ACTOR_COLUMN] as const;
+export const AUDIT_LOG_COLUMNS = [WHEN_COLUMN, TYPE_COLUMN, OBJECT_COLUMN, ACTOR_COLUMN] as const;
 export const AUDIT_LOG_ALL_TENANTS_COLUMNS = [
   WHEN_COLUMN,
   TENANT_COLUMN,
   TYPE_COLUMN,
+  OBJECT_COLUMN,
   ACTOR_COLUMN,
 ] as const;
 
@@ -39,6 +58,15 @@ export const AUDIT_LOG_DATE_RANGE_FACET = {
   params: { from: "from", to: "to" },
 } as const;
 
+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") },
+  ],
+} as const;
+
 export const AUDIT_LOG_TENANT_FACET = {
   type: "reference",
   field: "tenantId",
@@ -63,10 +91,10 @@ export function auditLogDetailLayout(options: { readonly withTenant: boolean }):
     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/packages/bundled-features/src/audit/web/audit-event-cell.tsx

@@ -0,0 +1,22 @@
+// 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 { type ColumnRendererProps, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import type { ReactNode } from "react";
+import { auditEntityLabel, isAuditEventAction } from "./audit-event-labels.ts";
+
+export function AuditEventCell({ value, row }: ColumnRendererProps): ReactNode {
+  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 }: ColumnRendererProps): ReactNode {
+  const t = useTranslation();
+  return auditEntityLabel(t, row) ?? "";
+}

package/packages/bundled-features/src/audit/web/audit-event-labels.ts

@@ -0,0 +1,30 @@
+import type { useTranslation } from "@cosmicdrift/kumiko-renderer";
+import { AUDIT_EVENT_ACTIONS, type AuditEventAction } from "./constants.ts";
+
+type Translate = ReturnType<typeof useTranslation>;
+
+export function isAuditEventAction(value: unknown): value is AuditEventAction {
+  return AUDIT_EVENT_ACTIONS.some((action) => action === value);
+}
+
+function humanizeEntityName(aggregateType: string): string {
+  const spaced = aggregateType.replaceAll("-", " ").replace(/([a-z])([A-Z])/g, "$1 $2");
+  return spaced.charAt(0).toUpperCase() + spaced.slice(1).toLowerCase();
+}
+
+/** Singular entity noun: the entity's own `:noun` key, then the audit log's label for bundled entities, then the humanized aggregate type. */
+export function auditEntityLabel(
+  t: Translate,
+  row: Readonly<Record<string, unknown>>,
+): string | null {
+  const aggregateType = row["aggregateType"];
+  if (typeof aggregateType !== "string") return null;
+  const nounKey = row["entityNounKey"];
+  if (typeof nounKey === "string") {
+    const noun = t(nounKey, { count: 1 });
+    if (noun !== nounKey) return noun;
+  }
+  const bundledKey = `audit.log.entity.${aggregateType}`;
+  const bundledLabel = t(bundledKey);
+  return bundledLabel === bundledKey ? humanizeEntityName(aggregateType) : bundledLabel;
+}

package/packages/bundled-features/src/audit/web/client-plugin.tsx

@@ -1,6 +1,11 @@
 import { mergeTranslations, type TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
 import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer/web";
-import { AUDIT_FEATURE } from "./constants.ts";
+import { AuditEventCell, AuditObjectCell } from "./audit-event-cell.tsx";
+import {
+  AUDIT_EVENT_CELL_COMPONENT,
+  AUDIT_FEATURE,
+  AUDIT_OBJECT_CELL_COMPONENT,
+} from "./constants.ts";
 import { defaultTranslations } from "./default-translations.ts";
 
 export type AuditClientOptions = {
@@ -11,5 +16,9 @@ export function auditClient(options?: AuditClientOptions): ClientFeatureDefiniti
   return {
     name: AUDIT_FEATURE,
     translations: mergeTranslations(defaultTranslations, options?.translations ?? {}),
+    columnRenderers: {
+      [AUDIT_EVENT_CELL_COMPONENT]: AuditEventCell,
+      [AUDIT_OBJECT_CELL_COMPONENT]: AuditObjectCell,
+    },
   };
 }

package/packages/bundled-features/src/audit/web/constants.ts

@@ -13,6 +13,17 @@ export const SYSTEM_ACTOR_IDS: ReadonlySet<string> = new Set([
   "00000000-0000-0000-0000-000000000000",
 ]);
 
+/** Column-renderer names shared by screens.ts and `auditClient()`. */
+export const AUDIT_EVENT_CELL_COMPONENT = "audit-event-cell" as const;
+export const AUDIT_OBJECT_CELL_COMPONENT = "audit-object-cell" as const;
+
+/** Action suffix of entity events (`<entity>.<action>`); other event types have none. */
+export const AUDIT_EVENT_ACTIONS = ["created", "updated", "deleted", "restored"] as const;
+export type AuditEventAction = (typeof AUDIT_EVENT_ACTIONS)[number];
+
+/** Value of the facet that brings technical entries (escape-hatch use) back into the log. */
+export const INCLUDE_TECHNICAL_FILTER = "include-technical" as const;
+
 export const AuditQueries = {
   list: "audit:query:list",
   details: "audit:query:details",