@cosmicdrift/kumiko-samples 0.389.0 → 0.390.0

package/packages/bundled-features/src/user/db/queries/stream-tenant-backfill.ts

@@ -1,32 +1,20 @@
-// One-time migration tooling for older user event streams.
-//
-// Making `user` a systemStream entity means every executor op addresses the
-// stream on SYSTEM_TENANT_ID. Streams created before that live on whichever
-// tenant created them ("scattered"), so newer writes version-conflict
-// against the empty SYSTEM stream. The raw UPDATE breaks as soon as an
-// aggregate has BOTH a legacy stream and newer SYSTEM events
-// (split stream — e.g. a skipOptimisticLock
-// lifecycle write appended v1 on SYSTEM while v1..n live on the old
-// tenant): retenanting then trips events_aggregate_version_uq.
-//
-// This tool merges per aggregate: all user events, ordered by global event
-// id, are renumbered 1..n and retenanted to SYSTEM_TENANT_ID — two-phase
-// version writes (negative interim values) dodge the unique index while the
-// per-aggregate transaction is in flight. Snapshots of migrated aggregates
-// are dropped (version numbering changed; the next snapshotting load
-// recreates them); archived-stream markers move with the stream.
-//
-// Idempotent: the candidate query only matches aggregates that still have
-// non-SYSTEM events. One failing aggregate does not abort the run — the
-// rest of the estate migrates, failures are reported.
-//
-// After a run, rebuild the user projection so read_users.tenant_id reflects
-// the stream move: rebuildProjection("user:projection:user-entity", ...) or
-// the jobs:job:projection-rebuild job.
+// Moves legacy user streams onto SYSTEM_TENANT_ID (user is a systemStream
+// entity). After a run, rebuild the user projection so read_users.tenant_id
+// reflects the move: rebuildProjection("user:projection:user-entity", ...) or
+// the jobs:job:projection-rebuild job. `backfillUserStreamTenantsWithDerivedState`
+// does the move, the old-bucket search cleanup, the rebuild and the reindex in one call.
 
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
-import { asRawClient, transaction, unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/db";
-import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import type { Registry } from "@cosmicdrift/kumiko-framework/engine";
+import type { SearchAdapter } from "@cosmicdrift/kumiko-framework/search";
+import {
+  backfillAggregateStreamTenants,
+  createSearchBucketCleanup,
+  type DerivedStateMode,
+  rebuildAndReindex,
+  type StreamBackfillStepFailure,
+  stepFailures,
+} from "../../../shared/index.ts";
 
 export type UserStreamBackfillResult = {
   readonly aggregatesMigrated: number;
@@ -34,80 +22,66 @@ export type UserStreamBackfillResult = {
   readonly failed: ReadonlyArray<{ readonly aggregateId: string; readonly error: string }>;
 };
 
-export async function backfillUserStreamTenants(
+const USER_AGGREGATE = "user";
+const USER_PROJECTION = "user:projection:user-entity";
+
+export function backfillUserStreamTenants(
   db: DbConnection,
+  options: { readonly scanTenantIds?: readonly string[] } = {},
 ): Promise<UserStreamBackfillResult> {
-  const candidates = await unsafeReadRetrying<{ aggregate_id: string }>(
-    db,
-    `SELECT DISTINCT "aggregate_id" FROM "kumiko_events"
-      WHERE "aggregate_type" = 'user' AND "tenant_id" <> $1::uuid`,
-    [SYSTEM_TENANT_ID],
-  );
-
-  let aggregatesMigrated = 0;
-  let eventsMigrated = 0;
-  const failed: Array<{ aggregateId: string; error: string }> = [];
-
-  for (const { aggregate_id } of candidates) {
-    try {
-      eventsMigrated += await migrateAggregate(db, aggregate_id);
-      aggregatesMigrated++;
-    } catch (e) {
-      failed.push({
-        aggregateId: aggregate_id,
-        error: e instanceof Error ? e.message : String(e),
-      });
-    }
-  }
-  return { aggregatesMigrated, eventsMigrated, failed };
+  return backfillAggregateStreamTenants(db, {
+    aggregateType: USER_AGGREGATE,
+    target: { kind: "system" },
+    ...options,
+  });
 }
 
-async function migrateAggregate(db: DbConnection, aggregateId: string): Promise<number> {
-  return transaction(db, async (tx) => {
-    const raw = asRawClient(tx);
-    // Global id order = commit-adjacent replay order; merges a split stream
-    // (legacy tenant + SYSTEM) into one consistent version sequence.
-    const events = await raw.unsafe<{ id: bigint | string }>(
-      `SELECT "id" FROM "kumiko_events"
-        WHERE "aggregate_type" = 'user' AND "aggregate_id" = $1::uuid
-        ORDER BY "id" ASC
-        FOR UPDATE`,
-      [aggregateId],
-    );
-
-    // Negative interim versions — real versions are always >= 1, so
-    // nothing can collide with events_aggregate_version_uq mid-migration.
-    for (const [i, ev] of events.entries()) {
-      await raw.unsafe(
-        `UPDATE "kumiko_events" SET "tenant_id" = $1::uuid, "version" = $2 WHERE "id" = $3`,
-        [SYSTEM_TENANT_ID, -(i + 1), ev.id],
-      );
-    }
-    // Final contiguous 1..n.
-    for (const [i, ev] of events.entries()) {
-      await raw.unsafe(`UPDATE "kumiko_events" SET "version" = $1 WHERE "id" = $2`, [i + 1, ev.id]);
-    }
-
-    // Version numbering changed → any snapshot of this aggregate is stale.
-    await raw.unsafe(`DELETE FROM "kumiko_snapshots" WHERE "aggregate_id" = $1::uuid`, [
-      aggregateId,
-    ]);
-
-    // Archived markers key on (tenant_id, aggregate_id) — move them with the
-    // stream, keeping an existing SYSTEM marker if both exist.
-    await raw.unsafe(
-      `INSERT INTO "kumiko_archived_streams" ("tenant_id", "aggregate_id", "aggregate_type", "archived_at", "archived_by", "reason")
-        SELECT $1::uuid, "aggregate_id", "aggregate_type", "archived_at", "archived_by", "reason"
-          FROM "kumiko_archived_streams"
-         WHERE "aggregate_id" = $2::uuid AND "tenant_id" <> $1::uuid
-        ON CONFLICT DO NOTHING`,
-      [SYSTEM_TENANT_ID, aggregateId],
-    );
-    await raw.unsafe(
-      `DELETE FROM "kumiko_archived_streams" WHERE "aggregate_id" = $1::uuid AND "tenant_id" <> $2::uuid`,
-      [aggregateId, SYSTEM_TENANT_ID],
-    );
+export type UserStreamBackfillWithDerivedStateResult = {
+  readonly streams: UserStreamBackfillResult;
+  readonly projectionsRebuilt: readonly string[];
+  readonly reindexedUsers: number;
+  readonly failures: readonly StreamBackfillStepFailure[];
+};
 
-    return events.length;
+export async function backfillUserStreamTenantsWithDerivedState(deps: {
+  readonly db: DbConnection;
+  readonly registry: Registry;
+  readonly searchAdapter?: SearchAdapter;
+  readonly derived?: DerivedStateMode;
+  readonly scanTenantIds?: readonly string[];
+  readonly onFirstCandidate?: () => Promise<"proceed" | "skip">;
+}): Promise<UserStreamBackfillWithDerivedStateResult> {
+  const {
+    db,
+    registry,
+    searchAdapter,
+    derived = "if-moved",
+    scanTenantIds,
+    onFirstCandidate,
+  } = deps;
+  const searchCleanup = createSearchBucketCleanup(searchAdapter, USER_AGGREGATE);
+  const streams = await backfillAggregateStreamTenants(db, {
+    aggregateType: USER_AGGREGATE,
+    target: { kind: "system" },
+    beforeMove: searchCleanup.beforeMove,
+    ...(scanTenantIds && { scanTenantIds }),
+    ...(onFirstCandidate && { onFirstCandidate }),
+  });
+  const failures = stepFailures("user-streams", streams.failed);
+  if (streams.aggregatesMigrated === 0 && derived === "if-moved") {
+    return { streams, projectionsRebuilt: [], reindexedUsers: 0, failures };
+  }
+  const rebuilt = await rebuildAndReindex({
+    db,
+    registry,
+    ...(searchAdapter && { searchAdapter }),
+    projections: [USER_PROJECTION],
+    searchEntity: USER_AGGREGATE,
   });
+  return {
+    streams,
+    projectionsRebuilt: rebuilt.projectionsRebuilt,
+    reindexedUsers: rebuilt.reindexedRows,
+    failures: [...failures, ...rebuilt.failures],
+  };
 }

package/packages/bundled-features/src/user/handlers/find-for-auth.query.ts

@@ -6,14 +6,14 @@ import { userTable } from "../schema/user.ts";
 
 // Privileged auth lookup: returns the full user row — including passwordHash —
 // by email OR id (exactly one, enforced by the schema). Used by the auth
-// features via ctx.queryAs(systemUser, ...).
+// features via ctx.dispatch.queryAs(systemUser, ...).
 //
 // Access is system-only, NOT access.privileged: every query handler is
 // reachable via POST /api/query, and "SystemAdmin" is an assignable app
 // role — privileged would hand any SystemAdmin the raw passwordHash over
 // HTTP. The "system" role can't be minted into a session (only
 // createSystemUser() carries it), so system-only keeps this handler
-// internal to ctx.queryAs(systemUser, ...) callers.
+// internal to ctx.dispatch.queryAs(systemUser, ...) callers.
 export const findForAuthQuery = defineQueryHandler({
   name: "user:find-for-auth",
   schema: z

package/packages/bundled-features/src/user/handlers/update-roles.ts

@@ -164,7 +164,7 @@ export async function applyUserRolesUpdate(
 
   const revoker = ctx.registry.getWriteHandler(REVOKE_ALL_SESSIONS_QN);
   if (revoker) {
-    const revokeResult = await ctx.writeAs(
+    const revokeResult = await ctx.dispatch.writeAs(
       createSystemUser(event.user.tenantId ?? SYSTEM_TENANT_ID),
       REVOKE_ALL_SESSIONS_QN,
       {
@@ -176,7 +176,7 @@ export async function applyUserRolesUpdate(
     // skip: sessions feature not mounted — no live JWTs to revoke; role update
     // still commits. Apps that mount user without sessions accept stale claims
     // until JWT TTL.
-    ctx.log?.warn(
+    ctx.obs.log?.warn(
       "user:update-roles: sessions revoke-all handler missing; role change commits without session invalidation",
       {
         userId: event.payload.id,

package/packages/bundled-features/src/user/index.ts

@@ -1,7 +1,9 @@
 export { UserCommandSchemas } from "./command-schemas.ts";
 export {
   backfillUserStreamTenants,
+  backfillUserStreamTenantsWithDerivedState,
   type UserStreamBackfillResult,
+  type UserStreamBackfillWithDerivedStateResult,
 } from "./db/queries/stream-tenant-backfill.ts";
 export { createUserFeature } from "./feature.ts";
 export {

package/packages/bundled-features/src/user/invited-global-roles.ts

@@ -45,7 +45,12 @@ export async function grantInvitedGlobalRoles(
   const updateResult = await userExecutor.update(
     { id: existing.id, version: existing.version, changes: { roles } },
     createSystemUser(SYSTEM_TENANT_ID),
-    createTenantDb({ db, tenantId: SYSTEM_TENANT_ID, mode: "system" }),
+    createTenantDb({
+      db,
+      tenantId: SYSTEM_TENANT_ID,
+      mode: "system",
+      reason: "global roles live on the tenant-agnostic user row in the system tenant",
+    }),
   );
   if (!updateResult.isSuccess) return updateResult;
   return grantedGlobalRoles(roles);

package/packages/bundled-features/src/user/principal-status.ts

@@ -39,7 +39,7 @@ export const principalStatusPlugin: PrincipalStatusPlugin = {
     return isPrincipalRowBlocked(row) ? "blocked" : "active";
   },
 
-  // ctx.queryAsMember's global-roles/timezone/locale source — same fields
+  // ctx.dispatch.queryAsMember's global-roles/timezone/locale source — same fields
   // login mints a session from (see login.write.ts gateBuildSession).
   async resolveProfile(userId, { db }): Promise<PrincipalProfile | null> {
     const row = await fetchOne<{ roles: unknown; timezone: string | null; locale: string | null }>(

package/packages/bundled-features/src/user/seeding.ts

@@ -17,8 +17,11 @@ import {
   type DbConnection,
   fetchOne,
 } from "@cosmicdrift/kumiko-framework/db";
-import type { SessionUser } from "@cosmicdrift/kumiko-framework/engine";
-import { TestUsers } from "@cosmicdrift/kumiko-framework/seeding";
+import {
+  createSystemUser,
+  type SessionUser,
+  SYSTEM_TENANT_ID,
+} from "@cosmicdrift/kumiko-framework/engine";
 // kumiko-lint-ignore cross-feature-import shares the postSave-hooks fixture contract with tenant/seeding
 import { fireEntityPostSave, type SeedTenantHooks } from "../tenant/seeding.ts";
 import { userEntity, userTable } from "./schema/user.ts";
@@ -61,11 +64,16 @@ export async function seedUser(
   // that opt in. Omit to keep today's hook-less behavior.
   hooks?: SeedTenantHooks,
 ): Promise<{ id: string }> {
-  const by = options.by ?? TestUsers.systemAdmin;
+  const by = options.by ?? createSystemUser(SYSTEM_TENANT_ID);
   // executor.create expects a TenantDb (with an .insert() API). Although
   // User is tenant-agnostic (it has no tenant_id column), the runtime
   // interface requires this wrapper.
-  const tdb = createTenantDb({ db, tenantId: by.tenantId, mode: "system" });
+  const tdb = createTenantDb({
+    db,
+    tenantId: by.tenantId,
+    mode: "system",
+    reason: "User is tenant-agnostic, seeding writes it through a system-mode handle",
+  });
 
   const existing = await fetchOne(db, userTable, { email: options.email, isDeleted: false });
   // @cast-boundary db-row: users.id is a uuid column (string), and fetchOne
@@ -111,7 +119,12 @@ export async function reconcileSeededUserEmailVerified(
   // @cast-boundary db-row: users.id is a uuid column (string), and fetchOne
   // returns the projection row as Record<string, unknown>.
   const id = existingRow["id"] as string;
-  const tdb = createTenantDb({ db, tenantId: by.tenantId, mode: "system" });
+  const tdb = createTenantDb({
+    db,
+    tenantId: by.tenantId,
+    mode: "system",
+    reason: "User is tenant-agnostic, seeding writes it through a system-mode handle",
+  });
   const result = await userExecutor.update(
     { id, version: existingRow["version"] as number, changes: { emailVerified: true } },
     by,
@@ -157,7 +170,12 @@ export async function rewriteSeededUserEmail(
     // skip: the stored blind index already matches, a rewrite would only append a no-op event.
     if (indexed) return;
   }
-  const tdb = createTenantDb({ db, tenantId: by.tenantId, mode: "system" });
+  const tdb = createTenantDb({
+    db,
+    tenantId: by.tenantId,
+    mode: "system",
+    reason: "User is tenant-agnostic, seeding writes it through a system-mode handle",
+  });
   const result = await userExecutor.update({ id, version, changes: { email } }, by, tdb);
   // version_conflict: a concurrent write already changed the row — fine for a seed helper.
   // unique_violation: a duplicate row already holds the blind index; the repair

package/packages/bundled-features/src/user/testing.ts

@@ -2,4 +2,26 @@
 // reason: helpers are shared between tests and Dev-Server bootstrap,
 // and /seeding is the stable home.
 
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import {
+  deleteRowViaEventStore,
+  updateRowViaEventStore,
+} from "@cosmicdrift/kumiko-testing/helpers";
+import { userEntity, userTable } from "./schema/user.ts";
+
 export * from "./seeding.ts";
+
+const userTarget = { table: userTable, entity: userEntity, entityName: "user" } as const;
+
+// The user stream is systemStream, so the default system-tenant actor addresses it.
+export function updateUserViaEventStore(
+  db: DbConnection,
+  userId: string,
+  changes: Readonly<Record<string, unknown>>,
+): Promise<void> {
+  return updateRowViaEventStore(db, userTarget, { id: userId }, changes);
+}
+
+export function softDeleteUserViaEventStore(db: DbConnection, userId: string): Promise<void> {
+  return deleteRowViaEventStore(db, userTarget, { id: userId });
+}

package/packages/bundled-features/src/user-data-rights/COMPLIANCE.md

@@ -18,7 +18,7 @@ Dieses Dokument bündelt die **technischen Fakten** zur DSGVO-Pipeline
 
 | Artikel | Endpoint / Runner | Wer ruft auf | Was passiert |
 |---------|-------------------|--------------|--------------|
-| **Art. 15 (Auskunft, light)** | `user-data-rights:query:my-audit-log` | User | Liest eigene Framework-Events aus `kumiko_events` (account-weit über alle Memberships). Filterbar nach `eventType`, `aggregateType`, `from`/`to`. Domain-Entities ohne `ctx.appendEvent` erscheinen NICHT — die kommen im Export-Bundle (Art. 20). |
+| **Art. 15 (Auskunft, light)** | `user-data-rights:query:my-audit-log` | User | Liest eigene Framework-Events aus `kumiko_events` (account-weit über alle Memberships). Filterbar nach `eventType`, `aggregateType`, `from`/`to`. Domain-Entities ohne `ctx.events.append` erscheinen NICHT — die kommen im Export-Bundle (Art. 20). |
 | **Art. 15 + 20 (Auskunft + Portabilität)** | `user-data-rights:write:request-export` | User | Async Job → ZIP mit user-Profil + fileRefs + alle EXT_USER_DATA-Provider-Daten (cross-tenant) + signed Magic-Link per Email. Idempotent: nur 1 active Job pro User (`ACTIVE_JOB_CONSTRAINT`). |
 | **Art. 15 + 20** | `GET /user-export/by-token` (interstitial) + `POST /user-export/by-token` (exchange) | Anonym (Magic-Link-Pfad) | Email-Link trägt den Token als URL-Fragment (`#token=`, nie an den Server gesendet, issue #1271); Interstitial-Script liest das Fragment client-seitig und tauscht es per POST-Body gegen die signed Storage-URL. Kein `?token=`-Query-Fallback (#1512) — Query-Param landet unveränderlich in Proxy-/Access-Logs. Multi-use innerhalb TTL. Audit: `lastUsedAt`, `lastUsedFromIp`, `lastUsedUserAgent`. |
 | **Art. 15 + 20** | `GET /user-export/by-job/:jobId` | User (Session-Auth) | UI-Klick-Pfad. Cross-tenant-same-user: User in Tenant B kann Job aus Tenant A laden wenn er der Owner ist. |

package/packages/bundled-features/src/user-data-rights/README.md

@@ -44,7 +44,7 @@ Hook-Signaturen in `framework/src/engine/extensions/user-data.ts`:
 
 | Article | Handler | Zweck |
 |---------|---------|-------|
-| Art. 15 | `user-data-rights:query:my-audit-log` | User sieht eigene Framework-Events (account-weit über alle Memberships). Domain-Entities ohne `ctx.appendEvent` erscheinen NICHT — nur im Export-Bundle. |
+| Art. 15 | `user-data-rights:query:my-audit-log` | User sieht eigene Framework-Events (account-weit über alle Memberships). Domain-Entities ohne `ctx.events.append` erscheinen NICHT — nur im Export-Bundle. |
 | Art. 15+20 | `user-data-rights:write:request-export` | Async Job → ZIP mit user-Profil + fileRefs + alle EXT_USER_DATA-Provider-Daten + signed Magic-Link |
 | Art. 17 | `user-data-rights:write:request-deletion` | Soft-Delete mit Grace-Period, anschließend Cron anonymisiert User + cleant Domain-Entities |
 | Art. 17 | `user-data-rights:write:cancel-deletion` | User widerruft seinen Forget-Request während der Grace |

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

@@ -53,7 +53,12 @@ export interface RecordDownloadUseArgs {
 export async function recordDownloadUse(args: RecordDownloadUseArgs): Promise<void> {
   const { db, tokenId, tokenVersion, tokenUseCount, tenantId, now, ip, userAgent } = args;
   const executor = createSystemUser(tenantId);
-  const tdb = createTenantDb({ db, tenantId, mode: "system" });
+  const tdb = createTenantDb({
+    db,
+    tenantId,
+    mode: "system",
+    reason: "download audit writes into the token's tenant, outside a request scope",
+  });
 
   await tokenCrud
     .update(
@@ -102,7 +107,12 @@ export interface RecordInvalidAttemptArgs {
 export async function recordInvalidAttempt(args: RecordInvalidAttemptArgs): Promise<void> {
   const { db, tenantId, now } = args;
   const executor = createSystemUser(tenantId);
-  const tdb = createTenantDb({ db, tenantId, mode: "system" });
+  const tdb = createTenantDb({
+    db,
+    tenantId,
+    mode: "system",
+    reason: "download audit writes into the token's tenant, outside a request scope",
+  });
   await attemptCrud
     .create(
       {

package/packages/bundled-features/src/user-data-rights/changes.json

@@ -1,4 +1,28 @@
 [
+  {
+    "version": "0.390.0",
+    "type": "fix",
+    "title": "export cleanup stays quiet when metrics are off",
+    "detail": "The cleanup gauges are not registered without metrics, so the job logged \"Gauge not registered\" on every pass."
+  },
+  {
+    "version": "0.390.0",
+    "type": "fix",
+    "title": "User data export and forget cleanup run in system scope",
+    "detail": "runUserExport and runForgetCleanup walk every tenant of a user, so they enter the system scope themselves instead of depending on the caller's scope. A direct call outside a job no longer exports or erases nothing under row level security \"on\"."
+  },
+  {
+    "version": "0.390.0",
+    "type": "improvement",
+    "title": "QN constants for the forget-cleanup job and the download-attempt list screen",
+    "detail": "UserDataRightsJobs.runForgetCleanup (\"user-data-rights:job:run-forget-cleanup\") and UserDataRightsScreens.downloadAttemptList (\"user-data-rights:screen:download-attempt-list\") are exported next to the existing QN constants, from the feature barrel and from user-data-rights/web. Use the screen constant in an app's r.nav instead of the literal string."
+  },
+  {
+    "version": "0.390.0",
+    "type": "improvement",
+    "title": "QN constants for the export job and the export job list screen",
+    "detail": "UserDataRightsJobs.runExportJobs (\"user-data-rights:job:run-export-jobs\") and UserDataRightsScreens.exportJobList (\"user-data-rights:screen:export-job-list\") are exported next to UserDataRightsQueries and UserDataRightsHandlers, from the feature barrel and from user-data-rights/web. Use the screen constant in an app's r.nav instead of the literal string."
+  },
   {
     "version": "0.389.0",
     "type": "improvement",

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

@@ -12,8 +12,8 @@ import {
 } from "@cosmicdrift/kumiko-framework/engine";
 import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
 import {
-  createMetricsHandle,
   createNoopMetricsHandle,
+  createSafeMetricsHandle,
 } from "@cosmicdrift/kumiko-framework/observability";
 import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import { createConfigAccessor } from "../config/index.ts";
@@ -62,6 +62,7 @@ import {
   type SendExportReadyEmailFn,
 } from "./run-export-jobs.ts";
 import {
+  FORGET_CLEANUP_HANDLER_NAME,
   runForgetCleanup,
   type SendDeletionExecutedEmailFn,
   sanitizeReasonForLog,
@@ -80,6 +81,7 @@ import {
   STATUS_OPTION_KEY_PREFIX,
   USER_ME_QUERY,
   UserDataRightsHandlers,
+  UserDataRightsScreens,
 } from "./web/constants.ts";
 import { USER_DATA_RIGHTS_I18N } from "./web/i18n.ts";
 
@@ -334,7 +336,7 @@ export function createUserDataRightsFeature(opts: UserDataRightsOptions = {}): F
       id: "export-job-list",
       label: "user-data-rights:nav.exportJobs",
       icon: "download",
-      screen: "user-data-rights:screen:export-job-list",
+      screen: UserDataRightsScreens.exportJobList,
       order: 25,
       access: { roles: ["SystemAdmin"] },
     });
@@ -620,11 +622,12 @@ export function createUserDataRightsFeature(opts: UserDataRightsOptions = {}): F
         const exportDb =
           ctx.db.unsafeRaw() as import("@cosmicdrift/kumiko-framework/db").DbConnection; // @cast-boundary db-operator — jobs never run inside a DbTx
         const exportRegistry = ctx.registry;
-        // JobContext carries ctx.meter (raw), not ctx.metrics — that bound
+        // JobContext carries ctx.meter (raw), not ctx.obs.metrics — that bound
         // handle only exists on HandlerContext (built per write/query call
-        // in dispatch-shared.ts). Build the same handle explicitly here.
-        const exportMetrics = ctx.meter
-          ? createMetricsHandle(ctx.meter, "user-data-rights")
+        // in dispatch-shared.ts). Build the handle explicitly; the safe variant is a no-op when
+        // metrics are off and the gauges were never registered on the meter.
+        const exportMetrics = ctx.obs.meter
+          ? createSafeMetricsHandle(ctx.obs.meter, "user-data-rights")
           : createNoopMetricsHandle();
 
         // Without explicit send*Email options, a mounted mail transport sends the
@@ -634,7 +637,7 @@ export function createUserDataRightsFeature(opts: UserDataRightsOptions = {}): F
         // The cron runs across tenants, so each mail needs a notify function
         // bound to the recipient's tenant for template overrides and channel
         // configuration.
-        const notifyFactory = ctx._notifyFactory;
+        const notifyFactory = ctx.services._notifyFactory;
         const exportNotifyFor =
           notifyFactory !== undefined && isGdprMailDeliveryAvailable(exportRegistry)
             ? (tenantId: TenantId) => notifyFactory(createSystemUser(tenantId), tenantId)
@@ -671,8 +674,8 @@ export function createUserDataRightsFeature(opts: UserDataRightsOptions = {}): F
           // createFileProviderForTenant throws and every export lands on failed.
           buildStorageProvider: makeTenantStorageProviderResolver({
             registry: exportRegistry,
-            configResolver: ctx.configResolver,
-            secrets: ctx.secrets,
+            configResolver: ctx.services.configResolver,
+            secrets: ctx.services.secrets,
             db: exportDb,
             userId: exportUserId,
             handlerName: "user-data-rights:run-export-jobs",
@@ -686,8 +689,8 @@ export function createUserDataRightsFeature(opts: UserDataRightsOptions = {}): F
           ...(opts.appExportDownloadUrl !== undefined && {
             appExportDownloadUrl: opts.appExportDownloadUrl,
           }),
-          escapeHatchAuditSink: ctx._escapeHatchAuditSink,
-          escapeHatchAuditLog: ctx.log,
+          escapeHatchAuditSink: ctx.services._escapeHatchAuditSink,
+          escapeHatchAuditLog: ctx.obs.log,
           actor: ctx.systemUser.id,
           metrics: exportMetrics,
         });
@@ -716,7 +719,7 @@ export function createUserDataRightsFeature(opts: UserDataRightsOptions = {}): F
         const forgetRegistry = ctx.registry;
         const tenantModel = await resolveAppTenantModel({
           registry: forgetRegistry,
-          configResolver: ctx.configResolver,
+          configResolver: ctx.services.configResolver,
           db: forgetDb,
           userId: forgetUserId,
         });
@@ -724,7 +727,7 @@ export function createUserDataRightsFeature(opts: UserDataRightsOptions = {}): F
         // Without an app callback the default mail goes out when an email channel or a
         // mail transport, plus a mail renderer, are mounted. The user is already erased
         // here, so it bypasses the delivery log: an attempt row would be new personal data.
-        const forgetConfigResolver = ctx.configResolver;
+        const forgetConfigResolver = ctx.services.configResolver;
         const sendDeletionExecutedEmail =
           opts.sendDeletionExecutedEmail ??
           ((isGdprMailDeliveryAvailable(forgetRegistry) ||
@@ -734,14 +737,14 @@ export function createUserDataRightsFeature(opts: UserDataRightsOptions = {}): F
                 {
                   registry: forgetRegistry,
                   db: forgetDb,
-                  ...(ctx.secrets !== undefined && { secrets: ctx.secrets }),
+                  ...(ctx.services.secrets !== undefined && { secrets: ctx.services.secrets }),
                   resolveTransport: makeTenantMailTransportResolver({
                     registry: forgetRegistry,
                     configResolver: forgetConfigResolver,
-                    secrets: ctx.secrets,
+                    secrets: ctx.services.secrets,
                     db: forgetDb,
                     userId: forgetUserId,
-                    handlerName: "user-data-rights:run-forget-cleanup",
+                    handlerName: FORGET_CLEANUP_HANDLER_NAME,
                   }),
                   configFor: (tenantId) =>
                     forgetConfigResolver &&
@@ -762,29 +765,31 @@ export function createUserDataRightsFeature(opts: UserDataRightsOptions = {}): F
           registry: forgetRegistry,
           now: T.Now.instant(),
           tenantModel,
-          ...(ctx.searchAdapter !== undefined && { searchAdapter: ctx.searchAdapter }),
+          ...(ctx.services.searchAdapter !== undefined && {
+            searchAdapter: ctx.services.searchAdapter,
+          }),
           // Same per-tenant provider resolution as the export cron — forget
           // deletes binaries from the store upload + export use.
           buildStorageProvider: makeTenantStorageProviderResolver({
             registry: forgetRegistry,
-            configResolver: ctx.configResolver,
-            secrets: ctx.secrets,
+            configResolver: ctx.services.configResolver,
+            secrets: ctx.services.secrets,
             db: forgetDb,
             userId: forgetUserId,
-            handlerName: "user-data-rights:run-forget-cleanup",
+            handlerName: FORGET_CLEANUP_HANDLER_NAME,
           }),
           ...(sendDeletionExecutedEmail && { sendDeletionExecutedEmail }),
-          escapeHatchAuditSink: ctx._escapeHatchAuditSink,
-          escapeHatchAuditLog: ctx.log,
+          escapeHatchAuditSink: ctx.services._escapeHatchAuditSink,
+          escapeHatchAuditLog: ctx.obs.log,
           actor: ctx.systemUser.id,
         });
 
         // Persist each incomplete report on the job-run log. The write
         // handler returns incomplete[] in its response; the cron path used to
         // discard the array (only a console.warn for rolledBack cases).
-        // ctx.log feeds createJobRunLogger → store_job_run_logs.
+        // ctx.obs.log feeds createJobRunLogger → store_job_run_logs.
         for (const entry of forgetResult.incomplete) {
-          ctx.log?.warn?.(
+          ctx.obs.log?.warn?.(
             `[user-data-rights:run-forget-cleanup] incomplete hook ` +
               `userId=${entry.userId} tenantId=${entry.tenantId} ` +
               `entityName=${entry.entityName} rolledBack=${entry.rolledBack} ` +

package/packages/bundled-features/src/user-data-rights/handlers/confirm-deletion-by-token.write.ts

@@ -59,7 +59,7 @@ export function createConfirmDeletionByTokenHandler(opts: ConfirmDeletionByToken
     access: { roles: ["anonymous", "Member", "User", "TenantAdmin", "SystemAdmin"] },
     escapeHatch: {
       reason:
-        "resolveGracePeriod reads the tenant compliance profile via ctx.queryAs(SYSTEM, " +
+        "resolveGracePeriod reads the tenant compliance profile via ctx.dispatch.queryAs(SYSTEM, " +
         "...) to compute the grace period end — the anonymous token holder has no read access " +
         "to that tenant-config projection. startDeletionGracePeriod also appends the user " +
         "lifecycle event on the SYSTEM_TENANT_ID user stream.",

package/packages/bundled-features/src/user-data-rights/handlers/deletion-grace-period.ts

@@ -29,7 +29,7 @@ export async function resolveGracePeriod(
     reason:
       "reads the tenant compliance profile via queryAs(SYSTEM, ...) to compute the grace period end; the calling user's own identity has no read access to that tenant-config projection",
   });
-  const profile = (await ctx.queryAs(
+  const profile = (await ctx.dispatch.queryAs(
     createSystemUser(tenantId),
     "compliance-profiles:query:for-tenant",
     {},

package/packages/bundled-features/src/user-data-rights/handlers/download-by-job.query.ts

@@ -149,8 +149,8 @@ export const downloadByJobQuery = defineQueryHandler({
     // can differ from query.user.tenantId).
     const provider = await makeTenantStorageProviderResolver({
       registry: ctx.registry,
-      configResolver: ctx.configResolver,
-      secrets: ctx.secrets,
+      configResolver: ctx.services.configResolver,
+      secrets: ctx.services.secrets,
       // @cast-boundary db-runner — helpers use only the query API that
       // DbConnection and DbTx share.
       db: runner as import("@cosmicdrift/kumiko-types/db-connection").DbConnection,

package/packages/bundled-features/src/user-data-rights/handlers/download-by-token.query.ts

@@ -201,8 +201,8 @@ export const downloadByTokenQuery = defineQueryHandler({
     // has none under resolverTrust: "authoritative").
     const provider = await makeTenantStorageProviderResolver({
       registry: ctx.registry,
-      configResolver: ctx.configResolver,
-      secrets: ctx.secrets,
+      configResolver: ctx.services.configResolver,
+      secrets: ctx.services.secrets,
       // @cast-boundary db-runner — helpers use only the query API that
       // DbConnection and DbTx share.
       db: runner as import("@cosmicdrift/kumiko-types/db-connection").DbConnection,

package/packages/bundled-features/src/user-data-rights/handlers/request-deletion.write.ts

@@ -50,7 +50,7 @@ export function createRequestDeletionHandler(opts: RequestDeletionOptions = {})
     escapeHatch: {
       grants: ["systemIdentity", "unsafeRaw"],
       reason:
-        "resolveGracePeriod reads the tenant compliance profile via ctx.queryAs(SYSTEM, " +
+        "resolveGracePeriod reads the tenant compliance profile via ctx.dispatch.queryAs(SYSTEM, " +
         "...) to compute the grace period end — the calling user's own identity has no read " +
         "access to that tenant-config projection. startDeletionGracePeriod also appends the " +
         "user lifecycle event on the SYSTEM_TENANT_ID user stream.",