@cosmicdrift/kumiko-samples 0.354.0 → 0.355.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.354.0",
+  "version": "0.355.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.354.0",
+  "version": "0.355.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>",

package/packages/bundled-features/src/agent-tools/agent-manifest.ts

@@ -251,6 +251,7 @@ function buildHandlerEntry(
   }
 
   const entity = getHandlerEntity(qn);
+  const excludedFields = "excludedFields" in def ? def.excludedFields : undefined;
   return {
     qn,
     kind,
@@ -258,6 +259,7 @@ function buildHandlerEntry(
     risk: exposure.risk,
     inputSchema,
     ...(entity !== undefined && { entity }),
+    ...(excludedFields !== undefined && { excludedFields }),
   };
 }
 

package/packages/bundled-features/src/agent-tools/types.ts

@@ -152,6 +152,8 @@ export type AgentManifestHandler = {
   readonly risk: AgentRisk;
   readonly inputSchema: Readonly<Record<string, unknown>>;
   readonly entity?: string;
+  /** Fields this generic create/update handler never writes; sending one fails validation. */
+  readonly excludedFields?: readonly string[];
 };
 
 export type AgentManifestScreen = {

package/packages/bundled-features/src/audit/escape-hatch-audit-sink.ts

@@ -23,6 +23,7 @@ export const escapeHatchUsedSchema = z.object({
   kind: z.enum(escapeHatchKinds),
   reason: z.string(),
   actor: z.string(),
+  caller: z.string().optional(),
   targetUserId: z.string().optional(),
   targetTenantId: z.string().optional(),
 });
@@ -36,6 +37,7 @@ export function createEscapeHatchAuditSink(opts: {
       kind: event.kind,
       reason: event.reason,
       actor: event.actor,
+      ...(event.caller !== undefined && { caller: event.caller }),
       ...(event.target && { targetUserId: event.target.id, targetTenantId: event.target.tenantId }),
     });
     // Appends on the unbound pool, never the handler tx — an audit entry must

package/packages/bundled-features/src/audit/handlers/resolve-audit-tenant.ts

@@ -1,4 +1,5 @@
-import { crossTenantOverrideDenied, type SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+import { mayOverrideTenant, type SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+import { AccessDeniedError, FrameworkReasons } from "@cosmicdrift/kumiko-framework/errors";
 import { APP_INSTANCE_STREAM_TYPE } from "@cosmicdrift/kumiko-framework/event-store";
 import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-types/identifiers";
 import { type AuditScope, AuditScopes } from "../constants.js";
@@ -12,11 +13,11 @@ export function resolveAuditScopeFilter(
   scope: AuditScope | undefined,
 ): AuditScopeFilter {
   if (scope !== AuditScopes.system) return { tenantId: user.tenantId };
-  const denied = crossTenantOverrideDenied(
-    user,
-    SYSTEM_TENANT_ID,
-    "audit.errors.systemScopeRequiresSystemAdmin",
-  );
-  if (denied) throw denied;
+  if (!mayOverrideTenant(user)) {
+    throw new AccessDeniedError({
+      i18nKey: "audit.errors.systemScopeRequiresSystemAdmin",
+      details: { reason: FrameworkReasons.tenantOverrideRequiresSystemAdmin },
+    });
+  }
   return { tenantId: SYSTEM_TENANT_ID, aggregateType: APP_INSTANCE_STREAM_TYPE };
 }

package/packages/bundled-features/src/billing-foundation/consumer-protection/register-consent.ts

@@ -1,5 +1,4 @@
 import type { FeatureRegistrar } from "@cosmicdrift/kumiko-framework/engine";
-import { createSystemUser } from "@cosmicdrift/kumiko-framework/engine";
 import { paymentAggregateId, subscriptionAggregateId } from "../aggregate-id.js";
 import { SubscriptionFoundationHandlers, SubscriptionStatuses } from "../constants.js";
 import {
@@ -75,17 +74,13 @@ export function registerConsumerProtection(
         // user), never from payload data.
         const tenantId = ctx.systemUser.tenantId;
         const currentPeriodEndIso = payload["currentPeriodEndIso"];
-        const result = await ctx.writeAs(
-          createSystemUser(tenantId),
-          SubscriptionFoundationHandlers.issueContractConfirmation,
-          {
-            consentId,
-            sourceAggregateId: isSubscriptionEvent
-              ? subscriptionAggregateId(tenantId)
-              : paymentAggregateId(tenantId),
-            ...(typeof currentPeriodEndIso === "string" && { currentPeriodEndIso }),
-          },
-        );
+        const result = await ctx.write(SubscriptionFoundationHandlers.issueContractConfirmation, {
+          consentId,
+          sourceAggregateId: isSubscriptionEvent
+            ? subscriptionAggregateId(tenantId)
+            : paymentAggregateId(tenantId),
+          ...(typeof currentPeriodEndIso === "string" && { currentPeriodEndIso }),
+        });
         if (!result.isSuccess) {
           throw new Error(
             `billing-foundation:${trigger.jobName}: issue-contract-confirmation failed: ${JSON.stringify(result.error)}`,

package/packages/bundled-features/src/billing-foundation/consumer-protection/register-termination.ts

@@ -1,4 +1,4 @@
-import { createSystemUser, type FeatureRegistrar } from "@cosmicdrift/kumiko-framework/engine";
+import type { FeatureRegistrar } from "@cosmicdrift/kumiko-framework/engine";
 import { SubscriptionCancelTimings, SubscriptionFoundationHandlers } from "../constants.js";
 import {
   CONTRACT_TERMINATION_DECLARED_EVENT_QN,
@@ -59,22 +59,18 @@ export function registerContractTermination(
       const declared = contractTerminationDeclaredPayloadSchema.safeParse(payload);
       // skip: trigger event carries no usable declaration
       if (!declared.success) return;
-      const result = await ctx.writeAs(
-        createSystemUser(ctx.systemUser.tenantId),
-        SubscriptionFoundationHandlers.recordContractTermination,
-        {
-          requestId: declared.data.requestId,
-          declarationType: declared.data.declarationType,
-          terminationKind: declared.data.terminationKind,
-          channel: "public",
-          when:
-            declared.data.declarationType === "withdrawal"
-              ? "none"
-              : SubscriptionCancelTimings.periodEnd,
-          receivedAtIso: declared.data.receivedAtIso,
-          locale: declared.data.locale,
-        },
-      );
+      const result = await ctx.write(SubscriptionFoundationHandlers.recordContractTermination, {
+        requestId: declared.data.requestId,
+        declarationType: declared.data.declarationType,
+        terminationKind: declared.data.terminationKind,
+        channel: "public",
+        when:
+          declared.data.declarationType === "withdrawal"
+            ? "none"
+            : SubscriptionCancelTimings.periodEnd,
+        receivedAtIso: declared.data.receivedAtIso,
+        locale: declared.data.locale,
+      });
       if (!result.isSuccess) {
         throw new Error(
           `billing-foundation:cancel-on-public-termination-declared: record-contract-termination failed: ${JSON.stringify(result.error)}`,

package/packages/bundled-features/src/cap-overview/handlers/caps-usage.query.ts

@@ -1,12 +1,16 @@
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
 import {
-  crossTenantOverrideDenied,
   defineQueryHandler,
+  mayOverrideTenant,
   type QueryHandlerDefinition,
   type TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
-import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import {
+  AccessDeniedError,
+  FrameworkReasons,
+  InternalError,
+} from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
 import { tierAssignmentEntity } from "../../tier-engine/index.js";
 import type { CapSpec, CapUsageWithMeta } from "../types.js";
@@ -39,12 +43,12 @@ export function createCapsUsageQuery(
         });
       }
       const override = query.payload.tenantId;
-      const overrideDenied = crossTenantOverrideDenied(
-        query.user,
-        override,
-        "cap-overview.errors.tenantOverrideRequiresSystemAdmin",
-      );
-      if (overrideDenied) throw overrideDenied;
+      if (override !== undefined && !mayOverrideTenant(query.user)) {
+        throw new AccessDeniedError({
+          i18nKey: "cap-overview.errors.tenantOverrideRequiresSystemAdmin",
+          details: { reason: FrameworkReasons.tenantOverrideRequiresSystemAdmin },
+        });
+      }
 
       const targetTenantId = override ?? query.user.tenantId;
       // Both branches return the SAME unfiltered system-mode db —

package/packages/bundled-features/src/compliance-profiles/handlers/set-profile.write.ts

@@ -4,12 +4,7 @@ import {
   SELECTABLE_PROFILE_KEYS,
 } from "@cosmicdrift/kumiko-framework/compliance";
 import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
-import {
-  access,
-  crossTenantOverrideDenied,
-  defineWriteHandler,
-  type TenantId,
-} from "@cosmicdrift/kumiko-framework/engine";
+import { access, defineWriteHandler, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import {
   UnprocessableError,
   validationErrorFromZod,
@@ -63,12 +58,6 @@ export const setProfileWrite = defineWriteHandler({
     "Sets or replaces a tenant's compliance profile key plus an optional JSON override, for onboarding or a later region change; a system admin may target a different tenant through tenantIdOverride.",
   handler: async (event, ctx) => {
     const tenantOverride = event.payload.tenantIdOverride;
-    const overrideDenied = crossTenantOverrideDenied(
-      event.user,
-      tenantOverride,
-      "complianceProfiles.errors.tenantOverrideRequiresSystemAdmin",
-    );
-    if (overrideDenied) return writeFailure(overrideDenied);
     const tenantId = (tenantOverride ?? event.user.tenantId) as TenantId; // @cast-boundary engine-payload
     const executorUser = tenantOverride !== undefined ? { ...event.user, tenantId } : event.user;
 

package/packages/bundled-features/src/delivery/delivery-service.ts

@@ -190,7 +190,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
       tenantId,
       actor: systemUser.id,
       sink: escapeHatchAuditSink,
-      log,
+      log: logError,
     });
     // ctx.db/dbOutsideTransaction are tenant-filtered even for a systemScope handler:
     // the dispatcher closes them off entirely there, so "system" mode would hand this

package/packages/bundled-features/src/managed-pages/handlers/by-tenant-published.query.ts

@@ -1,9 +1,6 @@
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { castTenantRows } from "@cosmicdrift/kumiko-framework/db";
-import {
-  crossTenantOverrideDenied,
-  defineQueryHandler,
-} from "@cosmicdrift/kumiko-framework/engine";
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 import { type PageRow, pagesTable } from "../table.js";
 
@@ -33,12 +30,6 @@ export const byTenantPublishedQuery = defineQueryHandler({
     "Lists every published page of a tenant with slug, language, title and last-change time but no body; use it to enumerate the public pages for sitemap.xml or llms.txt, rather than by-slug which fetches one page's content.",
   handler: async (query, ctx) => {
     const override = query.payload.tenantIdOverride;
-    const overrideDenied = crossTenantOverrideDenied(
-      query.user,
-      override,
-      "managedPages.errors.tenantOverrideRequiresSystemAdmin",
-    );
-    if (overrideDenied) throw overrideDenied;
     const tenantId = override ?? query.user.tenantId;
     const rows = castTenantRows<PageRow>(
       await selectMany(ctx.db, pagesTable, { tenantId: tenantId, published: true }),

package/packages/bundled-features/src/managed-pages/handlers/set.write.ts

@@ -1,11 +1,6 @@
 import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import { createEventStoreExecutor, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
-import {
-  crossTenantOverrideDenied,
-  defineWriteHandler,
-  type TenantId,
-} from "@cosmicdrift/kumiko-framework/engine";
-import { writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { defineWriteHandler, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 import { type PageRow, pageEntity, pagesTable } from "../table.js";
 
@@ -55,12 +50,6 @@ export const setWrite = defineWriteHandler({
   handler: async (event, ctx) => {
     const db = ctx.db;
     const override = event.payload.tenantIdOverride;
-    const overrideDenied = crossTenantOverrideDenied(
-      event.user,
-      override,
-      "managedPages.errors.tenantOverrideRequiresSystemAdmin",
-    );
-    if (overrideDenied) return writeFailure(overrideDenied);
     const tenantId = override ?? event.user.tenantId;
     // override: point the executor context at the target tenant, else getStreamVersion runs against user.tenantId → version_conflict.
     const executorUser =

package/packages/bundled-features/src/template-resolver/handlers/by-slug.query.ts

@@ -1,8 +1,5 @@
 import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
-import {
-  crossTenantOverrideDenied,
-  defineQueryHandler,
-} from "@cosmicdrift/kumiko-framework/engine";
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 import { TEXT_BLOCK_KIND } from "../constants.js";
 import { type TemplateResourceRow, templateResourcesTable } from "../table.js";
@@ -33,12 +30,6 @@ export const bySlugQuery = defineQueryHandler({
     "Reads one text-block of a tenant by slug and locale together with its body and format; it is pinned to the text-block kind so mail templates and AI prompts in the same table stay unreachable through this anonymous-capable path.",
   handler: async (query, ctx) => {
     const override = query.payload.tenantIdOverride;
-    const overrideDenied = crossTenantOverrideDenied(
-      query.user,
-      override,
-      "templateResolver.errors.tenantOverrideRequiresSystemAdmin",
-    );
-    if (overrideDenied) throw overrideDenied;
     const tenantId = override ?? query.user.tenantId;
     const row = await fetchOne<TemplateResourceRow>(ctx.db, templateResourcesTable, {
       tenantId,

package/packages/bundled-features/src/template-resolver/handlers/by-tenant.query.ts

@@ -1,9 +1,6 @@
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { castTenantRows } from "@cosmicdrift/kumiko-framework/db";
-import {
-  crossTenantOverrideDenied,
-  defineQueryHandler,
-} from "@cosmicdrift/kumiko-framework/engine";
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import type { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import * as z from "zod";
 import { TEXT_BLOCK_KIND } from "../constants.js";
@@ -39,12 +36,6 @@ export const byTenantQuery = defineQueryHandler({
     "Lists every text-block of a tenant with slug, locale, title and body so a public content tree can be rendered in one call; use it for the whole sidebar, and by-slug when only one block is needed.",
   handler: async (query, ctx) => {
     const override = query.payload.tenantIdOverride;
-    const overrideDenied = crossTenantOverrideDenied(
-      query.user,
-      override,
-      "templateResolver.errors.tenantOverrideRequiresSystemAdmin",
-    );
-    if (overrideDenied) throw overrideDenied;
     const tenantId = override ?? query.user.tenantId;
     const rows = castTenantRows<TemplateResourceRow>(
       await selectMany(ctx.db, templateResourcesTable, { tenantId, kind: TEXT_BLOCK_KIND }),

package/packages/bundled-features/src/template-resolver/handlers/collection-item.query.ts

@@ -1,7 +1,6 @@
 import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   type ContentCollectionDefinition,
-  crossTenantOverrideDenied,
   defineQueryHandler,
 } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
@@ -31,12 +30,6 @@ export function makeCollectionItemQuery(collection: ContentCollectionDefinition)
         : `Reads one tenant-wide "${collection.id}" entry by slug and locale, returning null when it does not exist; use it to open a single entry in the editor rather than to list the collection.`,
     handler: async (query, ctx) => {
       const override = query.payload.tenantIdOverride;
-      const overrideDenied = crossTenantOverrideDenied(
-        query.user,
-        override,
-        "templateResolver.errors.tenantOverrideRequiresSystemAdmin",
-      );
-      if (overrideDenied) throw overrideDenied;
       const tenantId = override ?? query.user.tenantId;
       const row = await fetchOne<CollectionEntryRow>(ctx.db, store.table, {
         tenantId,

package/packages/bundled-features/src/template-resolver/handlers/collection-list.query.ts

@@ -2,7 +2,6 @@ import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { castTenantRows } from "@cosmicdrift/kumiko-framework/db";
 import {
   type ContentCollectionDefinition,
-  crossTenantOverrideDenied,
   defineQueryHandler,
 } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
@@ -36,12 +35,6 @@ export function makeCollectionListQuery(collection: ContentCollectionDefinition)
         : `Lists the tenant-wide entries of the "${collection.id}" content collection (${collection.kind} content) with slug, locale, title and body; every caller who may reach this collection sees the same shared set.`,
     handler: async (query, ctx) => {
       const override = query.payload.tenantIdOverride;
-      const overrideDenied = crossTenantOverrideDenied(
-        query.user,
-        override,
-        "templateResolver.errors.tenantOverrideRequiresSystemAdmin",
-      );
-      if (overrideDenied) throw overrideDenied;
       const tenantId = override ?? query.user.tenantId;
       const rows = castTenantRows<CollectionEntryRow>(
         await selectMany(ctx.db, store.table, {

package/packages/bundled-features/src/template-resolver/handlers/collection-set.write.ts

@@ -1,11 +1,9 @@
 import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   type ContentCollectionDefinition,
-  crossTenantOverrideDenied,
   defineWriteHandler,
   type TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
-import { writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
 import {
   type CollectionEntryRow,
@@ -43,12 +41,6 @@ export function makeCollectionSetWrite(collection: ContentCollectionDefinition)
     handler: async (event, ctx) => {
       const db = ctx.db;
       const override = event.payload.tenantIdOverride;
-      const overrideDenied = crossTenantOverrideDenied(
-        event.user,
-        override,
-        "templateResolver.errors.tenantOverrideRequiresSystemAdmin",
-      );
-      if (overrideDenied) return writeFailure(overrideDenied);
       // @cast-boundary engine-payload — override is a zod-validated string, the
       // user's own tenantId is already TenantId-branded.
       const tenantId = (override ?? event.user.tenantId) as TenantId;

package/packages/bundled-features/src/template-resolver/handlers/set.write.ts

@@ -1,11 +1,9 @@
 import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
-  crossTenantOverrideDenied,
   defineWriteHandler,
   SYSTEM_TENANT_ID,
   type TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
-import { writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
 import { TEMPLATE_KINDS, TEXT_BLOCK_KIND } from "../constants.js";
 import { type TemplateResourceRow, templateResourcesTable } from "../table.js";
@@ -52,12 +50,6 @@ export const setWrite = defineWriteHandler({
   handler: async (event, ctx) => {
     const db = ctx.db;
     const override = event.payload.tenantIdOverride;
-    const overrideDenied = crossTenantOverrideDenied(
-      event.user,
-      override,
-      "templateResolver.errors.tenantOverrideRequiresSystemAdmin",
-    );
-    if (overrideDenied) return writeFailure(overrideDenied);
     // @cast-boundary engine-payload — override is a zod-validated string, the
     // user's own tenantId is already TenantId-branded.
     const tenantId = (override ?? event.user.tenantId) as TenantId;

package/packages/bundled-features/src/template-resolver/handlers/upsert-tenant.write.ts

@@ -1,6 +1,5 @@
 import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
-  crossTenantOverrideDenied,
   defineWriteHandler,
   SYSTEM_TENANT_ID,
   type TenantId,
@@ -28,12 +27,6 @@ export const upsertTenantWrite = defineWriteHandler({
   handler: async (event, ctx) => {
     const db = ctx.db;
     const override = event.payload.tenantIdOverride;
-    const overrideDenied = crossTenantOverrideDenied(
-      event.user,
-      override,
-      "templateResolver.errors.tenantOverrideRequiresSystemAdmin",
-    );
-    if (overrideDenied) return writeFailure(overrideDenied);
     // upsertTenant erzeugt scope='tenant'. SYSTEM_TENANT_ID-Override würde
     // scope='tenant' unter SYSTEM_TENANT_ID schreiben → inkonsistenter Zustand
     // (Resolver-Logik trennt sauber zwischen system+tenant). SystemAdmin muss

package/packages/bundled-features/src/template-resolver/seeding.ts

@@ -51,8 +51,7 @@ async function resolveExistingForEventStoreSeed(
         `seed orphan check: projection ${id} has no events for tenant ${tenantId} but unscoped stream version is ${unscoped} — refusing delete/recreate to avoid wiping a live stream`,
       );
     }
-    // @cast-boundary orphan projection cleanup: empty stream, no executor verb;
-    // plain table ident trips guard-direct-entity-writes (infra EXCLUDE follow-up).
+    // The cast strips the executor-only brand that WritableTable rejects; the orphan row has no events, so no executor verb applies.
     await deleteMany(tdb, templateResourcesTable as EntityTableMeta, { id, tenantId });
     return null;
   }

package/packages/bundled-features/src/tenant-lifecycle/feature.ts

@@ -155,6 +155,7 @@ export function createTenantLifecycleFeature(): FeatureDefinition {
           fileProviderResolver: ctx._fileProviderResolver,
           searchAdapter: ctx.searchAdapter,
           escapeHatchAuditSink: ctx._escapeHatchAuditSink,
+          escapeHatchAuditLog: ctx.log,
           actor: ctx.systemUser.id,
         });
       },

package/packages/bundled-features/src/tenant-lifecycle/run-tenant-destroy.ts

@@ -14,6 +14,7 @@ import {
   VersionConflictError,
 } from "@cosmicdrift/kumiko-framework/event-store";
 import type { FileProviderResolver } from "@cosmicdrift/kumiko-framework/files";
+import type { Logger } from "@cosmicdrift/kumiko-framework/logging";
 import type { SearchAdapter } from "@cosmicdrift/kumiko-framework/search";
 import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
 import { tenantEntity, tenantTable } from "../tenant/index.js";
@@ -283,6 +284,7 @@ export async function runNextDestructionStage(args: {
   readonly fileProviderResolver?: FileProviderResolver;
   readonly searchAdapter?: SearchAdapter;
   readonly escapeHatchAuditSink?: EscapeHatchAuditSink;
+  readonly escapeHatchAuditLog?: Logger;
   readonly actor?: string;
 }): Promise<StageTickResult> {
   const events = await loadAggregate(args.db, args.tenantId, args.tenantId);
@@ -308,6 +310,7 @@ export async function runNextDestructionStage(args: {
     fileProviderResolver: args.fileProviderResolver,
     searchAdapter: args.searchAdapter,
     escapeHatchAuditSink: args.escapeHatchAuditSink,
+    escapeHatchAuditLog: args.escapeHatchAuditLog,
     actor: args.actor,
     deadlineAt: Date.now() + DESTRUCTION_STAGE_TICK_BUDGET_MS,
   };
@@ -410,6 +413,7 @@ export async function runTenantDestructionSweep(args: {
   readonly fileProviderResolver?: FileProviderResolver;
   readonly searchAdapter?: SearchAdapter;
   readonly escapeHatchAuditSink?: EscapeHatchAuditSink;
+  readonly escapeHatchAuditLog?: Logger;
   readonly actor?: string;
 }): Promise<{ readonly triggered: number; readonly advanced: number }> {
   const T = getTemporal();
@@ -457,6 +461,7 @@ export async function runTenantDestructionSweep(args: {
         fileProviderResolver: args.fileProviderResolver,
         searchAdapter: args.searchAdapter,
         escapeHatchAuditSink: args.escapeHatchAuditSink,
+        escapeHatchAuditLog: args.escapeHatchAuditLog,
         actor: args.actor,
       });
       if (!result.error && !result.halted) advanced++;

package/packages/bundled-features/src/tenant-lifecycle/stages.ts

@@ -27,6 +27,7 @@ import {
   type TenantResourceExtensionName,
 } from "@cosmicdrift/kumiko-framework/engine";
 import type { FileProviderResolver } from "@cosmicdrift/kumiko-framework/files";
+import { createFallbackLogger, type Logger } from "@cosmicdrift/kumiko-framework/logging";
 import {
   createEscapeHatchReporter,
   UNATTRIBUTED_ACTOR,
@@ -61,6 +62,7 @@ export type DestructionStageCtx = {
   // systemUser.id); runTenantDataHooks uses them to attribute+audit any
   // EXT_TENANT_DATA usage's declared escapeHatch.
   readonly escapeHatchAuditSink?: EscapeHatchAuditSink;
+  readonly escapeHatchAuditLog?: Logger;
   readonly actor?: string;
   // Epoch ms the stage must hand back by returning { done: false }.
   readonly deadlineAt: number;
@@ -136,6 +138,7 @@ async function runTenantDataHooks(ctx: DestructionStageCtx): Promise<StageRunOut
       tenantId: ctx.tenantId,
       actor: ctx.actor ?? UNATTRIBUTED_ACTOR,
       sink: ctx.escapeHatchAuditSink,
+      log: ctx.escapeHatchAuditLog ?? createFallbackLogger("tenant-lifecycle"),
     });
     const hookCtx: TenantDataHookCtx = {
       db: createTenantDb(ctx.db, ctx.tenantId, "tenant", undefined, undefined, undefined, {

package/packages/bundled-features/src/user-data-rights/feature.ts

@@ -663,6 +663,7 @@ export function createUserDataRightsFeature(opts: UserDataRightsOptions = {}): F
             appExportDownloadUrl: opts.appExportDownloadUrl,
           }),
           escapeHatchAuditSink: ctx._escapeHatchAuditSink,
+          escapeHatchAuditLog: ctx.log,
           actor: ctx.systemUser.id,
           metrics: exportMetrics,
         });
@@ -732,6 +733,7 @@ export function createUserDataRightsFeature(opts: UserDataRightsOptions = {}): F
           }),
           ...(sendDeletionExecutedEmail && { sendDeletionExecutedEmail }),
           escapeHatchAuditSink: ctx._escapeHatchAuditSink,
+          escapeHatchAuditLog: ctx.log,
           actor: ctx.systemUser.id,
         });
 

package/packages/bundled-features/src/user-data-rights/run-export-jobs.ts

@@ -1,3 +1,4 @@
+import type { Logger } from "@cosmicdrift/kumiko-framework/logging";
 // Async Export-Job Worker (S2.U3 Atom 3b) — pure Pipeline-Function.
 //
 // Spec: docs/plans/architecture/user-data-rights.md "Async Export-Pipeline".
@@ -176,6 +177,7 @@ export interface RunExportJobsArgs {
   // fw#2914 — sourced from the owning job's ctx (_escapeHatchAuditSink,
   // systemUser.id); threaded into runUserExport's per-hook TenantDb.
   readonly escapeHatchAuditSink?: EscapeHatchAuditSink;
+  readonly escapeHatchAuditLog?: Logger;
   readonly actor?: string;
 
   /**
@@ -248,6 +250,7 @@ export async function runExportJobs(args: RunExportJobsArgs): Promise<RunExportJ
       now,
       job,
       escapeHatchAuditSink: args.escapeHatchAuditSink,
+      escapeHatchAuditLog: args.escapeHatchAuditLog,
       actor: args.actor,
     });
     if (outcome.kind === "done") {
@@ -369,6 +372,7 @@ async function processJob(args: {
   now: Instant;
   job: JobRow;
   escapeHatchAuditSink?: EscapeHatchAuditSink;
+  escapeHatchAuditLog?: Logger;
   actor?: string;
 }): Promise<ProcessOutcome> {
   const { db, registry, buildStorageProvider, now, job } = args;
@@ -415,6 +419,7 @@ async function processJob(args: {
       userId: job.userId,
       now,
       escapeHatchAuditSink: args.escapeHatchAuditSink,
+      escapeHatchAuditLog: args.escapeHatchAuditLog,
       actor: args.actor,
     });
 

package/packages/bundled-features/src/user-data-rights/run-forget-cleanup.ts

@@ -1,3 +1,4 @@
+import { createFallbackLogger, type Logger } from "@cosmicdrift/kumiko-framework/logging";
 // Forget-Cleanup-Runner (S2.U5b) — pure-Function Pipeline.
 //
 // After the grace period (S2.U5a sets gracePeriodEnd) this runner iterates
@@ -157,6 +158,7 @@ export interface RunForgetCleanupArgs {
   // systemUser.id); attributes+audits any EXT_USER_DATA usage's declared
   // escapeHatch when its delete hook calls ctx.db.unsafeRaw().
   readonly escapeHatchAuditSink?: EscapeHatchAuditSink;
+  readonly escapeHatchAuditLog?: Logger;
   readonly actor?: string;
 }
 
@@ -209,13 +211,18 @@ function buildHookDb(
   db: DbRunner,
   tenantId: TenantId,
   entry: HookEntry,
-  args: { readonly escapeHatchAuditSink?: EscapeHatchAuditSink; readonly actor?: string },
+  args: {
+    readonly escapeHatchAuditSink?: EscapeHatchAuditSink;
+    readonly escapeHatchAuditLog?: Logger;
+    readonly actor?: string;
+  },
 ) {
   const report = createEscapeHatchReporter({
     handler: `${EXT_USER_DATA}:${entry.entityName}`,
     tenantId,
     actor: args.actor ?? UNATTRIBUTED_ACTOR,
     sink: args.escapeHatchAuditSink,
+    log: args.escapeHatchAuditLog ?? createFallbackLogger("user-data-rights"),
   });
   return createTenantDb(db, tenantId, "tenant", undefined, undefined, undefined, {
     unsafeRaw:
@@ -296,6 +303,7 @@ export async function runForgetCleanup(
       kms,
       searchAdapter: args.searchAdapter,
       escapeHatchAuditSink: args.escapeHatchAuditSink,
+      escapeHatchAuditLog: args.escapeHatchAuditLog,
       actor: args.actor,
     });
     hookCallsAttempted += userResult.hookCallsAttempted;
@@ -362,6 +370,7 @@ async function processUser(args: {
   kms?: KmsAdapter;
   searchAdapter?: SearchAdapter;
   escapeHatchAuditSink?: EscapeHatchAuditSink;
+  escapeHatchAuditLog?: Logger;
   actor?: string;
 }): Promise<ProcessUserResult> {
   const { db, registry, userId, hookEntries, buildStorageProvider, appTenantModel, kms } = args;
@@ -460,6 +469,7 @@ async function processUser(args: {
             {
               db: buildHookDb(tx, tenantId, entry, {
                 escapeHatchAuditSink: args.escapeHatchAuditSink,
+                escapeHatchAuditLog: args.escapeHatchAuditLog,
                 actor: args.actor,
               }),
               registry,

package/packages/bundled-features/src/user-data-rights/run-user-export.ts

@@ -1,3 +1,4 @@
+import { createFallbackLogger, type Logger } from "@cosmicdrift/kumiko-framework/logging";
 // User-Data-Export-Pipeline (S2.U3) — DSGVO Art. 15 (Auskunft) +
 // Art. 20 (Datenportabilität).
 //
@@ -62,6 +63,7 @@ export interface RunUserExportArgs {
   // systemUser.id); attributes+audits any EXT_USER_DATA usage's declared
   // escapeHatch when its export hook calls ctx.db.unsafeRaw().
   readonly escapeHatchAuditSink?: EscapeHatchAuditSink;
+  readonly escapeHatchAuditLog?: Logger;
   readonly actor?: string;
 }
 
@@ -110,13 +112,14 @@ function buildHookDb(
   db: DbRunner,
   tenantId: TenantId,
   entry: HookEntry,
-  args: Pick<RunUserExportArgs, "escapeHatchAuditSink" | "actor">,
+  args: Pick<RunUserExportArgs, "escapeHatchAuditSink" | "escapeHatchAuditLog" | "actor">,
 ) {
   const report = createEscapeHatchReporter({
     handler: `${EXT_USER_DATA}:${entry.entityName}`,
     tenantId,
     actor: args.actor ?? UNATTRIBUTED_ACTOR,
     sink: args.escapeHatchAuditSink,
+    log: args.escapeHatchAuditLog ?? createFallbackLogger("user-data-rights"),
   });
   return createTenantDb(db, tenantId, "tenant", undefined, undefined, undefined, {
     unsafeRaw: