@cosmicdrift/kumiko-samples 0.388.0 → 0.390.0

package/packages/bundled-features/src/cap-counter/with-cap-enforcement.ts

@@ -12,7 +12,7 @@
 // after a rollback, failure result or failed COMMIT only gives back what is still booked, so an
 // unknown COMMIT outcome cannot under-count. No connection is held across the handler. Rows a
 // crashed process left behind expire after CAP_RESERVATION_TTL_MINUTES and are given back before the
-// next reserve of the same cap. Reached through a nested ctx.write the cap is not reserved, so the
+// next reserve of the same cap. Reached through a nested ctx.dispatch.write the cap is not reserved, so the
 // dispatcher rejects that call unless the top-level batch reserved the same handler.
 //
 // The wrapper spreads the wrapped handler and chains its reserveBeforeTransaction: inner reserves
@@ -25,7 +25,7 @@
 // (enforce-cap.ts).
 
 import type {
-  HandlerContext,
+  ReservationContext,
   WriteEvent,
   WriteHandlerDef,
 } from "@cosmicdrift/kumiko-framework/engine";
@@ -67,7 +67,7 @@ export type CalendarCapDef = {
  *  tier from DB. */
 export type CalendarCapResolver = (
   event: WriteEvent,
-  ctx: HandlerContext,
+  ctx: ReservationContext,
 ) => Promise<CalendarCapDef> | CalendarCapDef;
 
 /**
@@ -111,7 +111,7 @@ export type RollingCapDef = {
 
 export type RollingCapResolver = (
   event: WriteEvent,
-  ctx: HandlerContext,
+  ctx: ReservationContext,
 ) => Promise<RollingCapDef> | RollingCapDef;
 
 /**

package/packages/bundled-features/src/cap-overview/feature.ts

@@ -61,6 +61,7 @@ export function createCapOverviewFeature(opts: CreateCapOverviewOptions): Featur
   }
 
   return defineFeature(CAP_OVERVIEW_FEATURE, (r) => {
+    r.adoptsBundledLists();
     r.describe(
       "Read-only visibility into per-tenant tier assignment and cap usage. SystemAdmin gets a platform-wide tenant list with usage bars; tenant admins (or the roles in `usageVisibleTo`) get their own tenant's usage as dashboard cards. Reads tier-engine, billing-foundation, and tenant data plus app-owned usage tables via caller-supplied CapSpec callbacks — never writes.",
     );

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

@@ -76,7 +76,7 @@ export function createCapsUsageQuery(
 
       // Override path: limits must read the TARGET tenant's config, not the
       // SystemAdmin caller's.
-      const config = override === undefined ? ctx.config : ctx.configFor?.(targetTenantId);
+      const config = override === undefined ? ctx.config : ctx.tenants.config?.(targetTenantId);
 
       const rows: CapUsageWithMeta[] = await Promise.all(
         caps.map(async (cap) => {

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

@@ -251,7 +251,7 @@ export function createTenantCapsListQuery(caps: readonly CapSpec[], listCaps: re
       const limitByTenantAndCap = await resolveLimitsByTenantAndCap(
         listedCaps,
         page,
-        ctx.configFor,
+        ctx.tenants.config,
       );
 
       const rows: TenantCapsListRow[] = page.map((row) => {

package/packages/bundled-features/src/compliance-profiles/seeding.ts

@@ -20,12 +20,12 @@ import {
   type DbConnection,
   fetchOne,
 } from "@cosmicdrift/kumiko-framework/db";
-import type { SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import {
-  runEventStoreSeed,
-  type SeedIfExists,
-  TestUsers,
-} from "@cosmicdrift/kumiko-framework/seeding";
+  createSystemUser,
+  type SessionUser,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { runEventStoreSeed, type SeedIfExists } from "@cosmicdrift/kumiko-framework/seeding";
 
 import {
   tenantComplianceProfileEntity,
@@ -52,8 +52,13 @@ export async function seedComplianceProfile(
 ): Promise<{ id: string }> {
   // user.tenantId must equal opts.tenantId so the Event Store stream
   // and projection remain in the same tenant bucket.
-  const by = opts.by ?? { ...TestUsers.systemAdmin, tenantId: opts.tenantId };
-  const tdb = createTenantDb({ db, tenantId: opts.tenantId, mode: "system" });
+  const by = opts.by ?? createSystemUser(opts.tenantId);
+  const tdb = createTenantDb({
+    db,
+    tenantId: opts.tenantId,
+    mode: "system",
+    reason: "seeding writes the compliance profile into an explicitly named tenant",
+  });
   const overrideJson = opts.override !== undefined ? JSON.stringify(opts.override) : null;
 
   const existing = (await fetchOne(db, tenantComplianceProfileTable, {

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

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.389.0",
+    "type": "improvement",
+    "title": "config:write:set passes readCascade to validators",
+    "detail": "The set handler binds readCascade to the config resolver, the tenant-scoped db and the secrets reader, so validators see the same cascade as the value queries."
+  },
   {
     "version": "0.388.0",
     "type": "improvement",

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

@@ -111,15 +111,15 @@ export function createConfigAccessorFactory(
 // session reads "config feature not wired into AppContext" instead of a
 // generic "configResolver missing".
 export function requireConfigResolver(ctx: HandlerContext, handlerName: string): ConfigResolver {
-  if (!ctx.configResolver) {
+  if (!ctx.services.configResolver) {
     throw new InternalError({
       message:
-        `[${handlerName}] ctx.configResolver missing — pass createConfigAccessorFactory's ` +
+        `[${handlerName}] ctx.services.configResolver missing — pass createConfigAccessorFactory's ` +
         `output via extraContext.configAccessorFactory and the resolver via ` +
         `extraContext.configResolver at boot.`,
     });
   }
-  return ctx.configResolver;
+  return ctx.services.configResolver;
 }
 
 // Config declares r.systemScope() (raw ctx.db is unfiltered across tenants
@@ -156,14 +156,14 @@ export function requireSystemDb(
 // if a handler tries to write an encrypted key without the provider in
 // place, pointing at the exact wiring gap).
 export function requireConfigEncryption(ctx: HandlerContext, handlerName: string): EnvelopeCipher {
-  if (!ctx.configEncryption) {
+  if (!ctx.services.configEncryption) {
     throw new InternalError({
       message:
-        `[${handlerName}] ctx.configEncryption missing — at least one config key declares ` +
+        `[${handlerName}] ctx.services.configEncryption missing — at least one config key declares ` +
         `encrypted: true, so the boot wiring must pass an EnvelopeCipher via ` +
         `extraContext.configEncryption (run{Prod,Dev}App wire it automatically from ` +
         `KUMIKO_SECRETS_MASTER_KEY_V<n>; same instance the resolver was built with).`,
     });
   }
-  return ctx.configEncryption;
+  return ctx.services.configEncryption;
 }

package/packages/bundled-features/src/config/handlers/cascade.query.ts

@@ -59,7 +59,7 @@ export const cascadeQuery = defineQueryHandler({
       query.user.tenantId,
       query.user.id,
       db,
-      ctx.secrets,
+      ctx.services.secrets,
     );
 
     const result: Record<string, ConfigCascade> = {};

package/packages/bundled-features/src/config/handlers/readiness.query.ts

@@ -106,7 +106,7 @@ export async function collectMissingRequiredConfig(
     user.tenantId,
     user.id,
     db,
-    ctx.secrets,
+    ctx.services.secrets,
   );
   for (const [qualifiedKey, keyDef] of candidates) {
     // Deliberately the unredacted cascade value: readiness asks "does this

package/packages/bundled-features/src/config/handlers/reencrypt.job.ts

@@ -69,22 +69,22 @@ export type ReencryptJobResult = {
 
 export const reencryptJob: JobHandlerFn = async (rawPayload, ctx): Promise<void> => {
   const payload = rawPayload as ReencryptJobPayload; // @cast-boundary engine-payload
-  const maybeCipher = ctx.configEncryption;
+  const maybeCipher = ctx.services.configEncryption;
   if (!maybeCipher) {
     throw new InternalError({
       message:
-        "[config:reencrypt] ctx.configEncryption missing — provide a master key " +
+        "[config:reencrypt] ctx.services.configEncryption missing — provide a master key " +
         "(KUMIKO_SECRETS_MASTER_KEY_V<n>) so the boot wires the envelope cipher.",
     });
   }
   // hoisted function declarations below capture these — pin the narrowed
   // type explicitly so TS keeps it inside the closures
   const cipher: EnvelopeCipher = maybeCipher;
-  const provider = ctx.masterKeyProvider;
+  const provider = ctx.services.masterKeyProvider;
   if (!provider) {
     throw new InternalError({
       message:
-        "[config:reencrypt] ctx.masterKeyProvider missing — wire it via extraContext.masterKeyProvider at boot.",
+        "[config:reencrypt] ctx.services.masterKeyProvider missing — wire it via extraContext.masterKeyProvider at boot.",
     });
   }
   if (!ctx.registry) {
@@ -116,8 +116,8 @@ export const reencryptJob: JobHandlerFn = async (rawPayload, ctx): Promise<void>
       handler: "config:job:reencrypt",
       tenantId,
       actor: "system",
-      sink: ctx._escapeHatchAuditSink,
-      log: ctx.log,
+      sink: ctx.services._escapeHatchAuditSink,
+      log: ctx.obs.log,
     });
   }
 
@@ -125,7 +125,12 @@ export const reencryptJob: JobHandlerFn = async (rawPayload, ctx): Promise<void>
   function tdbFor(tenantId: TenantId): TenantDb {
     let existing = tdbCache.get(tenantId);
     if (!existing) {
-      existing = createTenantDb({ db, tenantId, mode: "system" });
+      existing = createTenantDb({
+        db,
+        tenantId,
+        mode: "system",
+        reason: "KEK rotation job re-encrypts config values of every tenant",
+      });
       tdbCache.set(tenantId, existing);
     }
     return existing;
@@ -146,7 +151,12 @@ export const reencryptJob: JobHandlerFn = async (rawPayload, ctx): Promise<void>
   // tenant's writes — sharing it with sdbFor(SYSTEM_TENANT_ID) would make a
   // write-path cache entry double as the scan's ack gate.
   const scanDb = createSystemDbView(
-    createTenantDb({ db, tenantId: SYSTEM_TENANT_ID, mode: "system" }),
+    createTenantDb({
+      db,
+      tenantId: SYSTEM_TENANT_ID,
+      mode: "system",
+      reason: "KEK rotation scan enumerates config values across all tenants",
+    }),
     undefined,
     reportEscapeHatchFor(SYSTEM_TENANT_ID),
   );
@@ -219,7 +229,7 @@ export const reencryptJob: JobHandlerFn = async (rawPayload, ctx): Promise<void>
       // format) — never a supported re-encrypt input, so fail loudly
       // instead of relying on cipher.decrypt to reject it. Log only the
       // row id, never the value (ciphertext-adjacent).
-      ctx.log?.warn?.(
+      ctx.obs.log?.warn?.(
         `[config:reencrypt] row ${row.id} is not a current-cipher envelope, not re-encryptable`,
       );
       return "failed";
@@ -244,7 +254,7 @@ export const reencryptJob: JobHandlerFn = async (rawPayload, ctx): Promise<void>
     // holds a fresh envelope written by the set handler — already fine.
     if (!result.isSuccess) {
       if (result.error.code === "version_conflict") return "skipped";
-      ctx.log?.warn?.(`[config:reencrypt] executor rejected row ${row.id}`, {
+      ctx.obs.log?.warn?.(`[config:reencrypt] executor rejected row ${row.id}`, {
         code: result.error.code,
       });
       return "failed";
@@ -257,9 +267,9 @@ export const reencryptJob: JobHandlerFn = async (rawPayload, ctx): Promise<void>
     migrateRow,
     maxFailures,
     deadlineAt: deadline,
-    signal: ctx.signal,
+    signal: ctx.lifecycle.signal,
     onRowError: ({ row }, err) => {
-      ctx.log?.warn?.(`[config:reencrypt] failed to re-encrypt row ${row.id}`, { err });
+      ctx.obs.log?.warn?.(`[config:reencrypt] failed to re-encrypt row ${row.id}`, { err });
     },
   });
 
@@ -269,5 +279,5 @@ export const reencryptJob: JobHandlerFn = async (rawPayload, ctx): Promise<void>
     alreadyCurrent,
     stoppedReason: outcome.stoppedReason,
   };
-  ctx.log?.info?.(`[config:reencrypt] complete: ${JSON.stringify(result)}`);
+  ctx.obs.log?.info?.(`[config:reencrypt] complete: ${JSON.stringify(result)}`);
 };

package/packages/bundled-features/src/config/handlers/reset.write.ts

@@ -48,14 +48,14 @@ export const resetWrite = defineWriteHandler({
     // backing="secrets": clear the secret from the secrets store. delete() is
     // idempotent (returns false if absent) — mirrors the config no-op contract.
     if (keyDef.backing === "secrets") {
-      if (!ctx.secrets) {
+      if (!ctx.services.secrets) {
         throw new InternalError({
           message:
             `[config:write:reset] key "${event.payload.key}" declares backing="secrets" but ` +
-            `ctx.secrets is not wired — provide extraContext.secrets (and a MasterKeyProvider).`,
+            `ctx.services.secrets is not wired — provide extraContext.secrets (and a MasterKeyProvider).`,
         });
       }
-      await ctx.secrets.delete(SYSTEM_TENANT_ID, event.payload.key, {
+      await ctx.services.secrets.delete(SYSTEM_TENANT_ID, event.payload.key, {
         deletedBy: event.user.id,
       });
       return { isSuccess: true, data: { key: event.payload.key, scope } };

package/packages/bundled-features/src/config/handlers/selected-extensions.query.ts

@@ -53,7 +53,7 @@ export const selectedExtensionsQuery = defineQueryHandler({
       query.user.tenantId,
       query.user.id,
       db,
-      ctx.secrets,
+      ctx.services.secrets,
     );
     const selected: Record<string, string> = {};
     for (const [selectorKey, keyDef] of readableSelectors) {

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

@@ -18,7 +18,7 @@ import {
   writeFailure,
 } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
-import { requireConfigEncryption, requireSystemDb } from "../feature.ts";
+import { requireConfigEncryption, requireConfigResolver, requireSystemDb } from "../feature.ts";
 import { MASKED } from "../read-redaction.ts";
 import { configValueEntity, configValuesTable } from "../table.ts";
 import {
@@ -106,13 +106,30 @@ export const setWrite = defineWriteHandler({
     if (patternError) return writeFailure(patternError);
 
     if (keyDef.validate) {
+      const validateDb = scopeTenantDbToTenant(db, tenantId);
       try {
         await keyDef.validate(event.payload.value, {
           key: event.payload.key,
           scope,
           tenantId,
           userId,
-          db: scopeTenantDbToTenant(db, tenantId),
+          db: validateDb,
+          readCascade: (qualifiedKey) => {
+            const cascadeKeyDef = ctx.registry.getConfigKey(qualifiedKey);
+            if (!cascadeKeyDef) {
+              throw new InternalError({
+                message: `[config:write:set] readCascade: unknown config key "${qualifiedKey}"`,
+              });
+            }
+            return requireConfigResolver(ctx, "config:write:set").getCascade(
+              qualifiedKey,
+              cascadeKeyDef,
+              tenantId,
+              event.user.id,
+              validateDb,
+              ctx.services.secrets,
+            );
+          },
         });
       } catch (error) {
         if (isKumikoError(error)) return writeFailure(error);
@@ -129,14 +146,14 @@ export const setWrite = defineWriteHandler({
     // serialization as a config row so the read path round-trips via
     // deserializeValue. system-scope is guaranteed by the boot-guard.
     if (keyDef.backing === "secrets") {
-      if (!ctx.secrets) {
+      if (!ctx.services.secrets) {
         throw new InternalError({
           message:
             `[config:write:set] key "${event.payload.key}" declares backing="secrets" but ` +
-            `ctx.secrets is not wired — provide extraContext.secrets (and a MasterKeyProvider).`,
+            `ctx.services.secrets is not wired — provide extraContext.secrets (and a MasterKeyProvider).`,
         });
       }
-      await ctx.secrets.set(
+      await ctx.services.secrets.set(
         SYSTEM_TENANT_ID,
         event.payload.key,
         JSON.stringify(event.payload.value),

package/packages/bundled-features/src/config/handlers/values.query.ts

@@ -59,7 +59,7 @@ export const valuesQuery = defineQueryHandler({
       query.user.tenantId,
       query.user.id,
       db,
-      ctx.secrets,
+      ctx.services.secrets,
     );
 
     const result: Record<

package/packages/bundled-features/src/crypto-shredding/changes.json

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.389.0",
+    "type": "improvement",
+    "title": "Tests pin the erasure write purpose in forget-subject and the forget cleanup",
+    "detail": "A pre-KMS user whose key was already erased still ends deleted, loses its tokens and gets the erased sentinel in the update event."
+  },
+  {
+    "version": "0.389.0",
+    "type": "improvement",
+    "title": "The subject file purge reads candidate rows in pages",
+    "detail": "A user owning many records no longer loads them all into memory at once; every page is purged, not only the first."
+  },
   {
     "version": "0.388.0",
     "type": "fix",

package/packages/bundled-features/src/crypto-shredding/handlers/forget-subject.write.ts

@@ -257,7 +257,7 @@ async function appendDenialAuditEvent(
       new InternalError({
         message:
           "[crypto-shredding] forget-subject denial audit event cannot be appended without " +
-          "ctx.dbOutsideTransaction — dispatch wiring is missing the outside-tx db source.",
+          "ctx.db.outsideTransaction — dispatch wiring is missing the outside-tx db source.",
       }),
     );
   }
@@ -340,11 +340,11 @@ async function sweepDerivedSubjectData(
 
     // Derived search index still holds plaintext — purge next to the
     // blind-index sweep. No adapter → no-op (apps without search).
-    if (ctx.searchAdapter) {
+    if (ctx.services.searchAdapter) {
       await purgeSearchDocumentsForSubject(
         crossTenantSubjectRunner,
         ctx.registry.features,
-        ctx.searchAdapter,
+        ctx.services.searchAdapter,
         subjectKey,
         subject,
       );
@@ -432,7 +432,7 @@ async function appendSubjectForgotten(
   outsideRunner: DbRunner | undefined,
 ): Promise<void> {
   if (!outsideRunner) {
-    await ctx.unsafeAppendEvent({
+    await ctx.events.unsafeAppend({
       aggregateId,
       aggregateType: CRYPTO_SHREDDING_AGGREGATE_TYPE,
       type: SUBJECT_FORGOTTEN_EVENT_NAME,
@@ -521,7 +521,7 @@ export const forgetSubjectWrite = defineWriteHandler({
         subjectKey,
         raw.kind,
         denialReasonOf(tenantScopeDenial),
-        ctx.dbOutsideTransaction?.unsafeRaw(),
+        ctx.db.outsideTransaction?.unsafeRaw(),
       );
       return auditFailure ?? tenantScopeDenial;
     }
@@ -537,7 +537,7 @@ export const forgetSubjectWrite = defineWriteHandler({
         subjectKey,
         raw.kind,
         TARGET_RECORD_RETENTION_BLOCK_DELETE,
-        ctx.dbOutsideTransaction?.unsafeRaw(),
+        ctx.db.outsideTransaction?.unsafeRaw(),
       );
       return auditFailure ?? retentionDenial;
     }
@@ -562,7 +562,7 @@ export const forgetSubjectWrite = defineWriteHandler({
     //   - user.updated as lifecycle event (updateUserLifecycle), so a
     //     read_users rebuild doesn't wipe the flip
     //   - sessions don't need active revocation — session-callbacks
-    //     re-validate user.status on every request (isPrincipalBlocked
+    //     re-validate the user row on every request (isPrincipalRowBlocked
     //     blocks Deleted).
     // Both idempotent (status set / revokedAt IS NULL filter), retry after
     // crash recovery is safe. User-feature guard: without the user feature
@@ -575,7 +575,7 @@ export const forgetSubjectWrite = defineWriteHandler({
       await closeUserLoginDoor(
         ctx,
         raw.userId,
-        ctx.dbOutsideTransaction?.unsafeRaw(),
+        ctx.db.outsideTransaction?.unsafeRaw(),
         ctx.db.unsafeRaw(),
       );
     }
@@ -599,7 +599,7 @@ export const forgetSubjectWrite = defineWriteHandler({
         forgottenBy: event.user.id,
         ...(cleanupError !== undefined && { cleanupError }),
       },
-      ctx.dbOutsideTransaction?.unsafeRaw(),
+      ctx.db.outsideTransaction?.unsafeRaw(),
     );
 
     if (cleanupError !== undefined) {

package/packages/bundled-features/src/crypto-shredding/resolve-file-bytes-deleter.ts

@@ -5,16 +5,16 @@ import type { DeleteFileBytes } from "../shared/index.ts";
 
 const ERROR_CONTEXT = "crypto-shredding:forget-subject";
 
-// The upload resolver, not ctx.files: ctx.files is bound to the acting user's tenant, while a
+// The upload resolver, not ctx.services.files: ctx.services.files is bound to the acting user's tenant, while a
 // subject's rows can live in any tenant. Resolved eagerly so a missing provider surfaces as
 // missing_file_storage instead of a failed delete.
 export function resolveFileBytesDeleter(
   ctx: HandlerContext,
 ): (tenantId: TenantId) => Promise<DeleteFileBytes | undefined> {
   return async (tenantId) => {
-    const resolver = ctx._fileProviderResolver;
+    const resolver = ctx.services._fileProviderResolver;
     if (resolver === undefined) {
-      const own = tenantId === ctx.user.tenantId ? ctx.files : undefined;
+      const own = tenantId === ctx.user.tenantId ? ctx.services.files : undefined;
       return own && ((key) => deleteFileRefBytes(own, { storageKey: key }, ERROR_CONTEXT));
     }
     try {

package/packages/bundled-features/src/custom-fields/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.390.0",
+    "type": "fix",
+    "title": "wireCustomFieldsUserDataRightsFor is exported from ./custom-fields",
+    "detail": "The helper that adds custom fields to the user-data-rights export is documented as an app call but was missing from the subpath exports. It is exported again together with its options type."
+  },
   {
     "version": "0.370.0",
     "type": "breaking",

package/packages/bundled-features/src/custom-fields/handlers/clear-custom-field.write.ts

@@ -59,7 +59,7 @@ export const clearCustomFieldHandler: WriteHandlerDef = {
       });
     }
 
-    await ctx.unsafeAppendEvent({
+    await ctx.events.unsafeAppend({
       aggregateId: payload.entityId,
       aggregateType: payload.entityName,
       type: createCustomFieldsFeature().exports.clearedEvent.name,

package/packages/bundled-features/src/custom-fields/handlers/delete-system-field.write.ts

@@ -34,7 +34,7 @@ export const deleteSystemFieldHandler: WriteHandlerDef = {
     // Cascade-cleanup event — host-entity MSPs remove orphaned values from their
     // customFields jsonb in the same transaction for atomicity.
     if (result.isSuccess) {
-      await ctx.unsafeAppendEvent({
+      await ctx.events.unsafeAppend({
         aggregateId,
         aggregateType: FIELD_DEFINITION_AGGREGATE_TYPE,
         type: createCustomFieldsFeature().exports.fieldDefinitionDeletedEvent.name,

package/packages/bundled-features/src/custom-fields/handlers/delete-tenant-field.write.ts

@@ -55,7 +55,7 @@ export function createDeleteTenantFieldHandler(
       // registered via wireCustomFieldsFor consume it and remove orphaned values
       // from their customFields jsonb. The same transaction makes cleanup atomic.
       if (result.isSuccess) {
-        await ctx.unsafeAppendEvent({
+        await ctx.events.unsafeAppend({
           aggregateId,
           aggregateType: FIELD_DEFINITION_AGGREGATE_TYPE,
           type: createCustomFieldsFeature().exports.fieldDefinitionDeletedEvent.name,

package/packages/bundled-features/src/custom-fields/handlers/set-custom-field.write.ts

@@ -97,7 +97,7 @@ export const setCustomFieldHandler: WriteHandlerDef = {
     // cross-feature augmentation for this event type; the qualified string
     // name is used directly. The value is ALWAYS included in the event
     // (custom fields carry no PII), so replay fully reproduces the projection.
-    await ctx.unsafeAppendEvent({
+    await ctx.events.unsafeAppend({
       aggregateId: payload.entityId,
       aggregateType: payload.entityName,
       type: createCustomFieldsFeature().exports.setEvent.name,

package/packages/bundled-features/src/custom-fields/index.ts

@@ -37,3 +37,7 @@ export {
   type SupportedFieldType,
 } from "./web/constants.ts";
 export { customFieldsField, wireCustomFieldsFor } from "./wire-for-entity.ts";
+export {
+  type WireCustomFieldsUserDataRightsOptions,
+  wireCustomFieldsUserDataRightsFor,
+} from "./wire-user-data-rights.ts";

package/packages/bundled-features/src/custom-fields/lib/parse-serialized-field.ts

@@ -1,7 +1,7 @@
 // Centralised parser for `fieldDefinition.serializedField`.
 //
 // The column is stored as `text` in B1 (entity.ts) — what the db row hands
-// back depends on the driver: postgres-js returns text as a `string`, but
+// back depends on the driver: text normally arrives as a `string`, but
 // jsonb-tolerant drivers and middleware can deliver an already-parsed
 // object. This helper normalises both, validates the shape, and centralises
 // the single boundary cast so callers don't sprinkle `as { … }`-narrowings

package/packages/bundled-features/src/data-retention/feature.ts

@@ -101,7 +101,7 @@ export function createDataRetentionFeature(): FeatureDefinition {
           tenantId,
           preloadedTenantPreset: tenantPreset,
           now: T.Now.instant(),
-          files: ctx.files,
+          files: ctx.services.files,
         });
         if (result.skipped.length > 0) {
           // biome-ignore lint/suspicious/noConsole: operator-visibility for skipped entities

package/packages/bundled-features/src/data-retention/run-retention-cleanup.ts

@@ -254,7 +254,12 @@ async function forgetRowAndEraseKeys(args: {
   readonly registry: Registry;
 }): Promise<{ readonly isSuccess: boolean }> {
   return runInSubTransaction(args.db, async (sp) => {
-    const tdb = createTenantDb({ db: sp, tenantId: args.tenantId, mode: "system" });
+    const tdb = createTenantDb({
+      db: sp,
+      tenantId: args.tenantId,
+      mode: "system",
+      reason: "retention sweep forgets rows of the tenant being swept, outside any request scope",
+    });
     const result = await args.executor.forget({ id: args.rowId }, args.systemUser, tdb);
     if (!result.isSuccess) return { isSuccess: false };
     await eraseHardDeletedRowKeys({
@@ -508,7 +513,12 @@ export async function runRetentionCleanup(
   // the daily cron converges (hardDelete removes rows, softDelete's isDeleted
   // filter shrinks the set). A single batched forget/delete event is a follow-up.
   const systemUser = createSystemUser(tenantId);
-  const tdb = createTenantDb({ db, tenantId, mode: "system" });
+  const tdb = createTenantDb({
+    db,
+    tenantId,
+    mode: "system",
+    reason: "retention sweep forgets rows of the tenant being swept, outside any request scope",
+  });
   const fileHolders = collectSingleFileHolders(registry);
 
   // Pre-load every override row for this tenant ONCE — N entities × M

package/packages/bundled-features/src/delivery/attempt-log.ts

@@ -63,7 +63,7 @@ async function writeAttemptEvent(
 ): Promise<void> {
   const { tenantId, ...rest } = entry;
   // Masked here, the only place attempt events are written, so no event or projection row ever holds the full address.
-  // Schema-parse to match ctx.appendEvent's guarantee: a payload drift between
+  // Schema-parse to match ctx.events.append's guarantee: a payload drift between
   // service/job + feature-registration fails loudly here instead of landing on
   // the events-table and crashing a consumer later.
   const payload = deliveryAttemptSchema.parse({

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

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.389.0",
+    "type": "fix",
+    "title": "Unsubscribe link origin is looked up once per notify call",
+    "detail": "The tenantOrigin callback runs once per tenant for a notify call with many recipients, and a fallback warning is logged once. A callback that hangs is still not guarded by a timeout, so keep it fast."
+  },
+  {
+    "version": "0.389.0",
+    "type": "improvement",
+    "title": "buildSystemChannelContext for system tenant mails outside a handler",
+    "detail": "buildSystemChannelContext(deps, { config, secrets }) returns a ChannelContext for the system tenant whose readAttachment reads file and inline attachments. SystemWireDeps (wire hook and runWorkerApp wireComponents) has a new required filesForTenant that deps can pass straight in."
+  },
   {
     "version": "0.388.0",
     "type": "fix",