@cosmicdrift/kumiko-samples 0.389.0 → 0.390.0

package/packages/bundled-features/src/shared/stream-tenant-backfill.ts

@@ -0,0 +1,201 @@
+// One-time migration tooling for event streams that live on the wrong tenant.
+//
+// An aggregate type that became tenant-independent (systemStream) or whose
+// stream must follow the tenant in its payload has older streams on whichever
+// tenant happened to write them. Newer writes then version-conflict against
+// the empty target stream, and a raw tenant_id UPDATE trips
+// events_aggregate_version_uq as soon as an aggregate has BOTH a legacy
+// stream and newer events on the target (split stream).
+//
+// This tool merges per aggregate: all events of the aggregate, ordered by
+// global event id, are renumbered 1..n and retenanted to the target - 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: candidates are only aggregates that still have events outside
+// their target tenant. One failing aggregate does not abort the run: the rest
+// of the estate migrates, failures are reported.
+//
+// After a run, rebuild the affected projections so read-table tenant_id
+// reflects the stream move.
+
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import {
+  asRawClient,
+  toPostgresArrayLiteral,
+  transaction,
+  unsafeReadRetrying,
+} from "@cosmicdrift/kumiko-framework/db";
+import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+
+export type StreamTenantTarget =
+  | { readonly kind: "system" }
+  // The tenantId carried by the aggregate's earliest event payload.
+  | { readonly kind: "payload-tenant" };
+
+export type StreamBackfillCandidate = {
+  readonly aggregateId: string;
+  readonly targetTenantId: string;
+  readonly sourceTenantIds: readonly string[];
+};
+
+export type StreamBackfillFailure = { readonly aggregateId: string; readonly error: string };
+
+export type StreamBackfillResult = {
+  readonly aggregatesMigrated: number;
+  readonly eventsMigrated: number;
+  readonly failed: readonly StreamBackfillFailure[];
+};
+
+export type StreamBackfillOptions = {
+  readonly aggregateType: string;
+  readonly target: StreamTenantTarget;
+  // Runs per candidate before its events move; a throw skips the aggregate
+  // and lands in `failed` (search cleanup must not be lost by a move).
+  readonly beforeMove?: (candidate: StreamBackfillCandidate) => Promise<void>;
+  // Restricts the candidate scan to events on these tenants, which lets Postgres use
+  // events_tenant_type_idx instead of grouping every event of the type. Streams on a tenant
+  // outside the list are not found; omit it for the full scan.
+  readonly scanTenantIds?: readonly string[];
+  // Called once when the scan found candidates, before the first move. "skip" ends the run
+  // with nothing moved (this process cannot do the work); a throw propagates to the caller.
+  readonly onFirstCandidate?: () => Promise<"proceed" | "skip">;
+};
+
+type CandidateRow = {
+  aggregate_id: string;
+  target_tenant_id: string | null;
+  source_tenant_ids: string[];
+};
+
+export async function backfillAggregateStreamTenants(
+  db: DbConnection,
+  options: StreamBackfillOptions,
+): Promise<StreamBackfillResult> {
+  const rows = await readCandidateRows(db, options);
+  if (rows.length > 0 && options.onFirstCandidate) {
+    if ((await options.onFirstCandidate()) === "skip") {
+      return { aggregatesMigrated: 0, eventsMigrated: 0, failed: [] };
+    }
+  }
+
+  let aggregatesMigrated = 0;
+  let eventsMigrated = 0;
+  const failed: StreamBackfillFailure[] = [];
+
+  for (const row of rows) {
+    try {
+      if (!row.target_tenant_id) {
+        throw new Error(`earliest event of the aggregate carries no payload.tenantId`);
+      }
+      const candidate: StreamBackfillCandidate = {
+        aggregateId: row.aggregate_id,
+        targetTenantId: row.target_tenant_id,
+        sourceTenantIds: row.source_tenant_ids,
+      };
+      await options.beforeMove?.(candidate);
+      eventsMigrated += await migrateAggregate(db, options.aggregateType, candidate);
+      aggregatesMigrated++;
+    } catch (e) {
+      failed.push({
+        aggregateId: row.aggregate_id,
+        error: e instanceof Error ? e.message : String(e),
+      });
+    }
+  }
+  return { aggregatesMigrated, eventsMigrated, failed };
+}
+
+async function readCandidateRows(
+  db: DbConnection,
+  options: StreamBackfillOptions,
+): Promise<readonly CandidateRow[]> {
+  const targetSql =
+    options.target.kind === "system"
+      ? `$2::text`
+      : `(SELECT e2."payload"->>'tenantId' FROM "kumiko_events" e2
+           WHERE e2."aggregate_type" = $1 AND e2."aggregate_id" = e."aggregate_id"
+           ORDER BY e2."id" ASC LIMIT 1)`;
+  const params: unknown[] = [options.aggregateType];
+  if (options.target.kind === "system") params.push(SYSTEM_TENANT_ID);
+  let scanSql = "";
+  if (options.scanTenantIds) {
+    // Events already on the SYSTEM target are not legacy; leaving them out keeps the scan to
+    // the legacy events only. A payload target differs per aggregate, so nothing is left out.
+    const scanned =
+      options.target.kind === "system"
+        ? options.scanTenantIds.filter((id) => id !== SYSTEM_TENANT_ID)
+        : options.scanTenantIds;
+    params.push(toPostgresArrayLiteral(scanned));
+    scanSql = ` AND e."tenant_id" = ANY($${params.length}::uuid[])`;
+  }
+  // An aggregate whose earliest event has no payload tenant yields a NULL
+  // target and is reported as failed instead of being silently skipped.
+  return unsafeReadRetrying<CandidateRow>(
+    db,
+    `SELECT e."aggregate_id" AS aggregate_id,
+            ${targetSql} AS target_tenant_id,
+            array_agg(DISTINCT e."tenant_id"::text) AS source_tenant_ids
+       FROM "kumiko_events" e
+      WHERE e."aggregate_type" = $1${scanSql}
+      GROUP BY e."aggregate_id"
+     HAVING bool_or(e."tenant_id"::text IS DISTINCT FROM ${targetSql})`,
+    params,
+  );
+}
+
+async function migrateAggregate(
+  db: DbConnection,
+  aggregateType: string,
+  candidate: StreamBackfillCandidate,
+): Promise<number> {
+  const { aggregateId, targetTenantId } = candidate;
+  return transaction(db, async (tx) => {
+    const raw = asRawClient(tx);
+    // Global id order = commit-adjacent replay order; merges a split stream
+    // into one consistent version sequence.
+    const events = await raw.unsafe<{ id: bigint | string }>(
+      `SELECT "id" FROM "kumiko_events"
+        WHERE "aggregate_type" = $1 AND "aggregate_id" = $2::uuid
+        ORDER BY "id" ASC
+        FOR UPDATE`,
+      [aggregateType, 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`,
+        [targetTenantId, -(i + 1), ev.id],
+      );
+    }
+    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, so 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 target 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`,
+      [targetTenantId, aggregateId],
+    );
+    await raw.unsafe(
+      `DELETE FROM "kumiko_archived_streams" WHERE "aggregate_id" = $1::uuid AND "tenant_id" <> $2::uuid`,
+      [aggregateId, targetTenantId],
+    );
+
+    return events.length;
+  });
+}

package/packages/bundled-features/src/shared/stream-tenant-derived-state.ts

@@ -0,0 +1,107 @@
+// Derived state of a stream-tenant backfill: search docs in the buckets the streams
+// left, projection rows and the index on SYSTEM_TENANT_ID. The stream move itself lives
+// in stream-tenant-backfill.ts; this part is repeatable and safe to run without moves.
+
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { type Registry, SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import { rebuildProjection } from "@cosmicdrift/kumiko-framework/pipeline";
+import { reindexEntity, type SearchAdapter } from "@cosmicdrift/kumiko-framework/search";
+import type { StreamBackfillCandidate, StreamBackfillFailure } from "./stream-tenant-backfill.ts";
+
+export type StreamBackfillStepFailure = StreamBackfillFailure & { readonly step: string };
+
+// "if-moved" skips rebuild and reindex when no stream moved; "always" repairs
+// derived state after a run that moved streams and then crashed.
+export type DerivedStateMode = "if-moved" | "always";
+
+export function createSearchBucketCleanup(
+  searchAdapter: SearchAdapter | undefined,
+  entityType: string,
+): {
+  readonly beforeMove: (candidate: StreamBackfillCandidate) => Promise<void>;
+  readonly cleanedAggregates: () => number;
+} {
+  let cleaned = 0;
+  return {
+    cleanedAggregates: () => cleaned,
+    beforeMove: async (candidate) => {
+      // skip: no adapter means no search docs to clean
+      if (!searchAdapter) return;
+      const oldBuckets = candidate.sourceTenantIds.filter((id) => id !== candidate.targetTenantId);
+      for (const bucket of oldBuckets) {
+        if (searchAdapter.removeBatch) {
+          await searchAdapter.removeBatch(bucket, [
+            { entityType, entityId: candidate.aggregateId },
+          ]);
+        } else {
+          await searchAdapter.remove(bucket, entityType, candidate.aggregateId);
+        }
+      }
+      if (oldBuckets.length > 0) cleaned++;
+    },
+  };
+}
+
+export type DerivedStateResult = {
+  readonly projectionsRebuilt: readonly string[];
+  readonly reindexedRows: number;
+  readonly failures: readonly StreamBackfillStepFailure[];
+};
+
+export async function rebuildAndReindex(deps: {
+  readonly db: DbConnection;
+  readonly registry: Registry;
+  readonly searchAdapter?: SearchAdapter;
+  readonly projections: readonly string[];
+  readonly searchEntity: string;
+}): Promise<DerivedStateResult> {
+  const { db, registry, searchAdapter, projections, searchEntity } = deps;
+  const failures: StreamBackfillStepFailure[] = [];
+  const projectionsRebuilt: string[] = [];
+  for (const projection of projections) {
+    try {
+      await rebuildProjection(projection, { db, registry });
+      projectionsRebuilt.push(projection);
+    } catch (e) {
+      failures.push({ aggregateId: projection, step: "rebuild", error: messageOf(e) });
+    }
+  }
+
+  let reindexedRows = 0;
+  if (searchAdapter && isEntitySearchable(registry, searchEntity)) {
+    try {
+      const reindex = await reindexEntity(
+        db,
+        registry,
+        searchAdapter,
+        searchEntity,
+        SYSTEM_TENANT_ID,
+      );
+      reindexedRows = reindex.indexedRows;
+      for (const f of reindex.failures) {
+        failures.push({ aggregateId: f.entityId, step: "reindex", error: f.reason });
+      }
+    } catch (e) {
+      failures.push({ aggregateId: searchEntity, step: "reindex", error: messageOf(e) });
+    }
+  }
+  return { projectionsRebuilt, reindexedRows, failures };
+}
+
+function isEntitySearchable(registry: Registry, entityName: string): boolean {
+  return (
+    registry.getSearchableFields(entityName).length > 0 ||
+    registry.getSearchPayloadExtensions(entityName).length > 0
+  );
+}
+
+export function stepFailures(
+  step: string,
+  failed: readonly StreamBackfillFailure[],
+): StreamBackfillStepFailure[] {
+  return failed.map((f) => ({ ...f, step }));
+}
+
+function messageOf(e: unknown): string {
+  return e instanceof Error ? e.message : String(e);
+}

package/packages/bundled-features/src/step-dispatcher/feature.ts

@@ -94,7 +94,7 @@ export function createStepDispatcherFeature(): FeatureDefinition {
               tenantId,
               userId,
               callerFeature: STEP_DISPATCHER_FEATURE,
-              ...(ctx.secrets && { secrets: ctx.secrets }),
+              ...(ctx.services.secrets && { secrets: ctx.services.secrets }),
             }),
         });
       },

package/packages/bundled-features/src/subscription-dodo/plugin-methods.ts

@@ -225,7 +225,7 @@ async function fillPriceCache(
     } else {
       const message =
         outcome.reason instanceof Error ? outcome.reason.message : String(outcome.reason);
-      ctx.log?.warn("subscription-dodo: product lookup failed", { message });
+      ctx.obs.log?.warn("subscription-dodo: product lookup failed", { message });
     }
   }
 }

package/packages/bundled-features/src/subscription-dodo/runtime.ts

@@ -64,11 +64,11 @@ export function createDodoRuntimes(deps: DodoRuntimeDeps): DodoRuntimes {
 
   async function ctxApiKey(ctx: HandlerContext): Promise<string> {
     let key: string | undefined;
-    if (ctx.secrets) {
-      const got = await requireSecretsContext(ctx, SUBSCRIPTION_DODO_FEATURE).get(
-        SYSTEM_TENANT_ID,
-        deps.apiKeyHandle.name,
-      );
+    if (ctx.services.secrets) {
+      const got = await requireSecretsContext(
+        { secrets: ctx.services.secrets, user: ctx.user },
+        SUBSCRIPTION_DODO_FEATURE,
+      ).get(SYSTEM_TENANT_ID, deps.apiKeyHandle.name);
       key = parseStoredSecret(got?.reveal());
     }
     if (!key && deps.fallback.apiKey && deps.fallback.apiKey.length > 0) {
@@ -102,8 +102,8 @@ export function createDodoRuntimes(deps: DodoRuntimeDeps): DodoRuntimes {
         if (live !== true) return false;
         if (deps.fallback.apiKey !== undefined && deps.fallback.apiKey.length > 0) return true;
         // Existence-only probe on every billing-plans render: must stay un-audited.
-        return ctx.secrets
-          ? await ctx.secrets.has(SYSTEM_TENANT_ID, deps.apiKeyHandle.name)
+        return ctx.services.secrets
+          ? await ctx.services.secrets.has(SYSTEM_TENANT_ID, deps.apiKeyHandle.name)
           : false;
       },
     },

package/packages/bundled-features/src/subscription-stripe/plugin-methods.ts

@@ -169,7 +169,9 @@ export function createStripeCheckoutSession(
       if (!options.providerCustomerId || !isUnknownCustomerStripeError(error)) throw error;
       // Stripe account switch (test -> live) or a customer deleted in the dashboard leaves a
       // stored customer id Stripe no longer knows; checkout creates a fresh customer instead.
-      ctx.log?.warn("subscription-stripe: stored customer unknown to Stripe, retrying without it");
+      ctx.obs.log?.warn(
+        "subscription-stripe: stored customer unknown to Stripe, retrying without it",
+      );
       session = await stripe.checkout.sessions.create(sessionParams(undefined));
     }
 
@@ -383,7 +385,7 @@ async function resolvePricesViaCache(
     } else {
       const message =
         outcome.reason instanceof Error ? outcome.reason.message : String(outcome.reason);
-      ctx.log?.warn("subscription-stripe: prices.retrieve failed", { message });
+      ctx.obs.log?.warn("subscription-stripe: prices.retrieve failed", { message });
     }
   }
 }
@@ -402,7 +404,7 @@ export function createStripeRetrievePrices(runtime: StripeCtxRuntime, cache: Str
       const rawInterval = price.recurring?.interval;
       if (rawInterval && mapped.interval === null && !warnedUnknownIntervalPriceIds.has(priceId)) {
         warnedUnknownIntervalPriceIds.add(priceId);
-        ctx.log?.warn("subscription-stripe: price has an unknown recurring interval", {
+        ctx.obs.log?.warn("subscription-stripe: price has an unknown recurring interval", {
           priceId,
           interval: rawInterval,
         });

package/packages/bundled-features/src/subscription-stripe/runtime.ts

@@ -114,11 +114,11 @@ export function createStripeRuntimes(deps: StripeRuntimeDeps): StripeRuntimes {
 
   async function ctxApiKey(ctx: HandlerContext): Promise<string> {
     let key: string | undefined;
-    if (ctx.secrets) {
-      const got = await requireSecretsContext(ctx, SUBSCRIPTION_STRIPE_FEATURE).get(
-        SYSTEM_TENANT_ID,
-        deps.apiKeyHandle.name,
-      );
+    if (ctx.services.secrets) {
+      const got = await requireSecretsContext(
+        { secrets: ctx.services.secrets, user: ctx.user },
+        SUBSCRIPTION_STRIPE_FEATURE,
+      ).get(SYSTEM_TENANT_ID, deps.apiKeyHandle.name);
       key = parseStoredSecret(got?.reveal());
     }
     if (!key && deps.fallback.apiKey && deps.fallback.apiKey.length > 0) {
@@ -167,8 +167,8 @@ export function createStripeRuntimes(deps: StripeRuntimeDeps): StripeRuntimes {
         if (hasFallbackKey) return true;
         // Existence-only probe — called on every billing-plans page render,
         // must stay un-audited (see SecretsContext.has's own doc comment).
-        return ctx.secrets
-          ? await ctx.secrets.has(SYSTEM_TENANT_ID, deps.apiKeyHandle.name)
+        return ctx.services.secrets
+          ? await ctx.services.secrets.has(SYSTEM_TENANT_ID, deps.apiKeyHandle.name)
           : false;
       },
     },

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

@@ -332,12 +332,12 @@ export class TemplateNotFoundError extends Error {
 // Single source of truth for "this handler requires template-resolver".
 // Pattern symmetric with requireTextContent.
 export function requireTemplateResolver(
-  ctx: { readonly templateResolver?: TemplateResolverApi } | object,
+  ctx: { readonly services: { readonly extensions: Readonly<Record<string, unknown>> } },
   callerName: string,
 ): TemplateResolverApi {
   // @cast-boundary engine-bridge — templateResolver kommt per extraContext
-  // from App-Bootstrap; the framework container does not know this field on its own.
-  const api = (ctx as { templateResolver?: TemplateResolverApi }).templateResolver;
+  // from App-Bootstrap and lands in services.extensions; the framework does not know its type.
+  const api = ctx.services.extensions["templateResolver"] as TemplateResolverApi | undefined;
   if (!api) {
     throw new InternalError({
       message:

package/packages/bundled-features/src/template-resolver/changes.json

@@ -1,4 +1,22 @@
 [
+  {
+    "version": "0.390.0",
+    "type": "fix",
+    "title": "Rail inserts no longer do nothing after the placeholder labels load",
+    "detail": "Inserting a placeholder into the subject, preheader, header chip or footer field could silently do nothing once the placeholder labels had loaded, because the replaced editor unregistered the handle of its remounted successor. The editors now report their handle from the React commit instead of tiptap's create and destroy callbacks."
+  },
+  {
+    "version": "0.390.0",
+    "type": "fix",
+    "title": "Placeholder inserts keep working after a line editor remounts",
+    "detail": "When a placeholder line editor (subject, preheader, header chip, footer note) remounted (labels arriving from the async validate query, or a new external value), TipTap could destroy the replaced editor after the new one was created. Its late null report then removed the live handle and placeholder inserts into that field did nothing. A null from a superseded editor is now ignored."
+  },
+  {
+    "version": "0.390.0",
+    "type": "improvement",
+    "title": "Split DocumentTiptapEditor into a model hook and render functions",
+    "detail": "DocumentTiptapEditor and its insert panel compose a model hook, pure helpers and render functions for toolbar, bubble menu, content and insert fields. Rendered markup and behavior are unchanged."
+  },
   {
     "version": "0.389.0",
     "type": "fix",

package/packages/bundled-features/src/template-resolver/handlers/bundle-import.ts

@@ -14,6 +14,7 @@ import {
 import { requireForTenant } from "../../shared/index.ts";
 import type { TemplateWriteScope } from "../layout-regions.ts";
 import type { LinkedResourceEntry } from "../linked-resources.ts";
+import type { PrepareContext } from "../store-template-resource.ts";
 import {
   attachmentLimitFailure,
   attachmentNeedsMailTemplate,
@@ -48,8 +49,8 @@ export function targetExistsIssue(locale: string): FieldIssue {
   };
 }
 
-type BundleImport = {
-  readonly ctx: HandlerContext;
+type BundleImport<TCtx extends PrepareContext = HandlerContext> = {
+  readonly ctx: TCtx;
   readonly user: SessionUser;
   readonly tenantId: TenantId;
   readonly scope: TemplateWriteScope;
@@ -60,7 +61,7 @@ type BundleImport = {
 type BundleImportStatus = "draft" | "active";
 
 async function collectBundleIssues(
-  args: BundleImport,
+  args: BundleImport<PrepareContext>,
   status: BundleImportStatus,
 ): Promise<readonly FieldIssue[]> {
   const { ctx, tenantId, scope, bundle, overwrite } = args;
@@ -113,7 +114,7 @@ function checkBundleAttachments(bundle: TemplateBundle): WriteResult<null> {
 // beforeTransaction half: validates the bundle and uploads every resource file to the target
 // tenant's storage. A failed or throwing upload releases the ones before it.
 export async function prepareTemplateBundleBeforeTransaction(
-  args: BundleImport & { readonly status: BundleImportStatus },
+  args: BundleImport<PrepareContext> & { readonly status: BundleImportStatus },
 ): Promise<BeforeTransactionResult<PreparedBundleResources>> {
   const refused =
     refuseTenantScopeUnderSystemTenant(args.scope, args.tenantId) ??

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

@@ -1,7 +1,6 @@
 import { fetchOne } from "@cosmicdrift/kumiko-framework/db";
 import {
   defineWriteHandler,
-  type HandlerContext,
   type SessionUser,
   SYSTEM_TENANT_ID,
   type TenantId,
@@ -18,6 +17,7 @@ import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
 import * as z from "zod";
 import { requireForTenant } from "../../shared/index.ts";
 import { type LinkedResourceEntry, parseLinkedResourceEntries } from "../linked-resources.ts";
+import type { PrepareContext } from "../store-template-resource.ts";
 import {
   createLinkedResourceCopies,
   prepareLinkedResourceCopiesBeforeTransaction,
@@ -43,7 +43,7 @@ import {
 } from "./template-write.ts";
 
 type CopyScope = "tenant" | "system";
-type WriteCtx = HandlerContext;
+type WriteCtx = PrepareContext;
 
 function readDbFor(ctx: WriteCtx, scope: CopyScope) {
   return scope === "system" ? requireForTenant(ctx, SYSTEM_TENANT_ID).db : ctx.db;

package/packages/bundled-features/src/template-resolver/handlers/export-bundle.query.ts

@@ -124,7 +124,7 @@ export const exportBundleQuery = defineQueryHandler({
       }
       const attachment = isFileAttachmentEntry(entry);
       const file = await readTemplateResource(
-        { db: ctx.db, files: ctx.files, user: query.user },
+        { db: ctx.db, services: { files: ctx.services.files, extensions: {} }, user: query.user },
         attachment ? entry.fileRefId : entry,
       );
       if (!file) throw new NotFoundError("template-resource-file", key);

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

@@ -412,7 +412,7 @@ export function makeOverviewQuery(policy: TemplateEditPolicy) {
       const truncated = fetchedRows.length > OVERVIEW_ROW_LIMIT;
       const rows = truncated ? fetchedRows.slice(0, OVERVIEW_ROW_LIMIT) : fetchedRows;
       if (truncated) {
-        ctx.log?.warn("template overview: row limit reached, result is incomplete", {
+        ctx.obs.log?.warn("template overview: row limit reached, result is incomplete", {
           limit: OVERVIEW_ROW_LIMIT,
         });
       }
@@ -434,7 +434,7 @@ export function makeOverviewQuery(policy: TemplateEditPolicy) {
         ? withOverriddenBy(
             rowsWithUsage,
             tenantOverrideCountsResultSchema.parse(
-              await ctx.query(TemplateResolverQueries.tenantOverrideCounts, {}),
+              await ctx.dispatch.query(TemplateResolverQueries.tenantOverrideCounts, {}),
             ),
           )
         : rowsWithUsage;

package/packages/bundled-features/src/template-resolver/handlers/send-test-shared.ts

@@ -17,7 +17,7 @@ export function testMailChannelContext(ctx: HandlerContext, user: SessionUser):
     registry: ctx.registry,
     sseBroker: undefined,
     tenantId: user.tenantId,
-    secrets: ctx.secrets,
+    secrets: ctx.services.secrets,
     config: ctx.config,
     readAttachment: createEmailAttachmentReader(
       ctx.db,

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

@@ -112,7 +112,7 @@ export function makeSendTestWrite(policy: TemplateEditPolicy) {
         sentStatus = result.status;
       } catch (error) {
         // Class and code only: the message can carry the address or a provider response body.
-        ctx.log?.warn("template test mail: channel threw", {
+        ctx.obs.log?.warn("template test mail: channel threw", {
           tenantId: event.user.tenantId,
           errorClass: error instanceof Error ? error.name : typeof error,
           errorCode: errorCodeOf(error),
@@ -120,7 +120,7 @@ export function makeSendTestWrite(policy: TemplateEditPolicy) {
         return testMailFailed("channel_error");
       }
       if (sentStatus !== "sent") {
-        ctx.log?.warn("template test mail: channel did not send", {
+        ctx.obs.log?.warn("template test mail: channel did not send", {
           tenantId: event.user.tenantId,
           status: sentStatus,
         });

package/packages/bundled-features/src/template-resolver/handlers/tenant-override-selection.ts

@@ -10,7 +10,9 @@ const tenantIdsSchema = z.array(z.string());
 
 type TenantIdQueryContext = {
   readonly registry: { getQueryHandler(name: string): unknown };
-  readonly query: (name: string, payload: Record<string, never>) => Promise<unknown>;
+  readonly dispatch: {
+    readonly query: (name: string, payload: Record<string, never>) => Promise<unknown>;
+  };
 };
 
 /** Null when the tenant feature is not installed: every tenant row then counts. */
@@ -18,7 +20,9 @@ export async function loadEnabledTenantIds(
   ctx: TenantIdQueryContext,
 ): Promise<ReadonlySet<string> | null> {
   if (ctx.registry.getQueryHandler(TenantQueries.activeTenantIds) === undefined) return null;
-  return new Set(tenantIdsSchema.parse(await ctx.query(TenantQueries.activeTenantIds, {})));
+  return new Set(
+    tenantIdsSchema.parse(await ctx.dispatch.query(TenantQueries.activeTenantIds, {})),
+  );
 }
 
 export type OverrideCandidate = Pick<TemplateResourceRow, "tenantId" | "status" | "version">;

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

@@ -31,7 +31,9 @@ function chunksOf<T>(items: readonly T[], size: number): T[][] {
 }
 
 type DirectoryQueryContext = {
-  readonly query: (name: string, payload: { ids: string[] }) => Promise<unknown>;
+  readonly dispatch: {
+    readonly query: (name: string, payload: { ids: string[] }) => Promise<unknown>;
+  };
 };
 
 // Looks up only the ids the overrides need, so labels never depend on the directory's default cap.
@@ -42,7 +44,7 @@ async function labelsFor(
 ): Promise<ReadonlyMap<string, string>> {
   const labels = new Map<string, string>();
   for (const chunk of chunksOf([...ids], MAX_LIST_LIMIT)) {
-    const raw = await ctx.query(queryName, { ids: chunk });
+    const raw = await ctx.dispatch.query(queryName, { ids: chunk });
     for (const row of directorySchema.parse(raw).rows) labels.set(row.id, row.label);
   }
   return labels;

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

@@ -28,7 +28,7 @@ export function makeUsageQuery(policy: TemplateEditPolicy) {
         { orderBy: { col: "id", direction: "asc" }, limit: MAIL_ROW_LIMIT + 1 },
       );
       if (fetchedRows.length > MAIL_ROW_LIMIT) {
-        ctx.log?.warn("template usage: row limit reached, result is incomplete", {
+        ctx.obs.log?.warn("template usage: row limit reached, result is incomplete", {
           limit: MAIL_ROW_LIMIT,
         });
       }

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

@@ -107,7 +107,12 @@ export async function seedSystemTemplate(
 ): Promise<{ id: string }> {
   const tenantId = SYSTEM_TENANT_ID;
   const by = opts.by ?? createSystemUser(tenantId);
-  const tdb = createTenantDb({ db, tenantId, mode: "system" });
+  const tdb = createTenantDb({
+    db,
+    tenantId,
+    mode: "system",
+    reason: "system templates live in the system tenant",
+  });
 
   const label = `seedSystemTemplate ${opts.slug}/${opts.kind}/${opts.locale}`;
   const slug = templateSlugSchema.safeParse(opts.slug);
@@ -408,7 +413,12 @@ export async function seedTextBlock(
   opts: SeedTextBlockOptions,
 ): Promise<{ id: string }> {
   const by = opts.by ?? createSystemUser(opts.tenantId);
-  const tdb = createTenantDb({ db, tenantId: opts.tenantId, mode: "system" });
+  const tdb = createTenantDb({
+    db,
+    tenantId: opts.tenantId,
+    mode: "system",
+    reason: "seeding writes text blocks into an explicitly named tenant",
+  });
 
   const existingRow = await fetchOne<TemplateResourceRow>(db, templateResourcesTable, {
     tenantId: opts.tenantId,