@cosmicdrift/kumiko-samples 0.388.0 → 0.390.0

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/tags/feature.ts

@@ -54,6 +54,7 @@ function registerTags(
   ownership: EntityDefinition["access"] | undefined,
   parents: readonly string[] | undefined,
 ): void {
+  r.adoptsBundledLists();
   r.describe(
     "Generic, host-agnostic tagging for any entity. Owns two event-sourced entities — the per-tenant `tag` catalog (`read_tags`, with optional `color` and `scope`) and `tag-assignment` join rows keyed by (entityType, entityId) (`read_tag_assignments`) — so tagging adds NO column to the host entity and needs no relational pivot or JOIN. Catalog screens are declarative (`entityList` + `entityEdit`) and use convention QNs `tag:{create,update,delete}`; TagManager/TagPicker keep `create-tag`/`update-tag`/`delete-tag`. Also: `assign-tag` (idempotent), `remove-tag` (idempotent) and list queries for the catalog and the assignments. Read which tags an entity has, or which entities carry a tag, by listing `tag-assignment` filtered on `entityId` or `tagId` and composing in the read-layer. A tag with empty `scope` is global; a `scope` of an entityType restricts it to that type in the picker. Every path uses one access rule — adopt the host's model with createTagsFeature({ access: { openToAll: { reason } } }) or pin roles with createTagsFeature({ roles }). Pass { toggleable: { default: false } } to make the whole feature tier-gatable via the tier-engine (no host hook).",
   );

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,58 @@
 [
+  {
+    "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",
+    "title": "copy-locale reads source files from the owning tenant's storage",
+    "detail": "The copy of linked files uses readFileRefContent with the provider of the fileRef's tenant. A source file whose fileRef row exists but whose bytes cannot be read fails the copy with template_resource_source_unreadable and releases the files already copied. A deleted fileRef is still left out of the copy."
+  },
+  {
+    "version": "0.389.0",
+    "type": "improvement",
+    "title": "replaceText explains finds across formatting or placeholders",
+    "detail": "replaceText matches inside single text nodes so formatting stays intact. A find that appears in the block line but crosses a formatting change now fails with text_spans_formatting, and a find with a {{placeholder}} fails with placeholder_not_replaceable, both with translated messages. Only a string that is not in the block at all still gives text_not_found."
+  },
+  {
+    "version": "0.389.0",
+    "type": "fix",
+    "title": "send-test-status follows the tenantEditable roles",
+    "detail": "send-test-status takes its access from templateEditAccess(policy.tenantEditable), like send-test. Roles that may send a test mail now get the status, and a TenantAdmin without an edit opt-in gets a 403 on both."
+  },
+  {
+    "version": "0.389.0",
+    "type": "fix",
+    "title": "overview follows the tenantEditable roles",
+    "detail": "The overview query takes its access from templateEditAccess(policy.tenantEditable). An opted-in role lists exactly the released templates, and a TenantAdmin without an opt-in is refused with a 403, matching the screen visibility and the write handlers."
+  },
+  {
+    "version": "0.389.0",
+    "type": "fix",
+    "title": "overview search and sort use the translated title",
+    "detail": "The overview query translates a seeded titleI18nKey with the request locale before it filters by search and sorts by title. A search for the visible title now matches, and the raw key is still searchable."
+  },
+  {
+    "version": "0.389.0",
+    "type": "fix",
+    "title": "legalContentSeed keeps and can set the content folder",
+    "detail": "seedTextBlock no longer resets the folder of an existing block to null when the seed passes no folder. legalContentSeed takes an optional folder, so apps do not need their own seed loop to keep legal blocks in the SystemAdmin content tree."
+  },
   {
     "version": "0.388.0",
     "type": "fix",

package/packages/bundled-features/src/template-resolver/document-ops.ts

@@ -389,6 +389,23 @@ function removeBlockOp(
   return null;
 }
 
+export const REPLACE_TEXT_ISSUE_CODES = {
+  notFound: "text_not_found",
+  spansFormatting: "text_spans_formatting",
+  placeholderNotReplaceable: "placeholder_not_replaceable",
+} as const;
+
+// document-blocks shows the line across formatting runs with placeholders as {{name}},
+// so a find that is visible there but lies in no single text node needs its own explanation.
+function textNotMatchedCode(block: JSONContent, find: string): string {
+  if (!textLinesOf(block).some((line) => line.includes(find))) {
+    return REPLACE_TEXT_ISSUE_CODES.notFound;
+  }
+  return find.includes("{{")
+    ? REPLACE_TEXT_ISSUE_CODES.placeholderNotReplaceable
+    : REPLACE_TEXT_ISSUE_CODES.spansFormatting;
+}
+
 function replaceTextOp(
   state: OpState,
   op: Extract<DocumentOp, { op: "replaceText" }>,
@@ -401,7 +418,9 @@ function replaceTextOp(
     (sum, node) => sum + occurrencesOf(node.text ?? "", op.find),
     0,
   );
-  if (count === 0) return patchIssue(`${path}.find`, "text_not_found", { find: op.find });
+  if (count === 0) {
+    return patchIssue(`${path}.find`, textNotMatchedCode(entry.node, op.find), { find: op.find });
+  }
   if (count > 1) return patchIssue(`${path}.find`, "text_ambiguous", { find: op.find, count });
   entry.node = replaceInContent([entry.node], op.find, op.replace)[0] ?? entry.node;
   return null;

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

@@ -29,7 +29,7 @@ import { makeResourceLinkPdfWrite } from "./handlers/resource-link-pdf.write.ts"
 import { makeResourceRemoveWrite } from "./handlers/resource-remove.write.ts";
 import { makeResourceUploadWrite } from "./handlers/resource-upload.write.ts";
 import { makeSendTestWrite } from "./handlers/send-test.write.ts";
-import { sendTestStatusQuery } from "./handlers/send-test-status.query.ts";
+import { makeSendTestStatusQuery } from "./handlers/send-test-status.query.ts";
 import { makeSetWrite } from "./handlers/set.write.ts";
 import { tenantOverrideCountsQuery } from "./handlers/tenant-override-counts.query.ts";
 import { tenantOverridesQuery } from "./handlers/tenant-overrides.query.ts";
@@ -191,7 +191,7 @@ export function createTemplateResolverFeature(opts: TemplateResolverOptions = {}
       preview: r.queryHandler(previewQuery),
       documentBlocks: r.queryHandler(documentBlocksQuery),
       exportBundle: r.queryHandler(exportBundleQuery),
-      sendTestStatus: r.queryHandler(sendTestStatusQuery),
+      sendTestStatus: r.queryHandler(makeSendTestStatusQuery(policy)),
     };
 
     for (const collection of collections) {

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/layout-source.query.ts

@@ -1,5 +1,6 @@
 import { selectMany } from "@cosmicdrift/kumiko-framework/db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { AccessDeniedError } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
 import { filterDeliveredTo } from "../api.ts";
 import { type LayoutRegions, readLayoutRegions } from "../layout-regions.ts";
@@ -14,6 +15,7 @@ import {
 } from "../template-draft.ts";
 import { type MailLayoutMeta, readMailLayoutMeta } from "../template-meta.ts";
 import { FALLBACK_LOCALE } from "../web/constants.ts";
+import { TemplateResolverErrors } from "../web/qualified-names.ts";
 import { localeSchema, templateSlugSchema } from "./shared.ts";
 import { parseStoredJson } from "./template-gates.ts";
 
@@ -66,20 +68,29 @@ function layoutFormat(row: WorkingRow): "html" | "mjml" | null {
   return row.contentFormat === "html" || row.contentFormat === "mjml" ? row.contentFormat : null;
 }
 
+type EditScope = "tenant" | "system";
+
 function pickEditedRows(
   rows: readonly TemplateResourceRow[],
-  user: { readonly tenantId: string; readonly roles: readonly string[] },
+  caller: { readonly tenantId: string; readonly roles: readonly string[] },
+  scope: EditScope,
   locale: string | undefined,
 ): {
   readonly tenantRow: WorkingRow | null;
   readonly systemRow: WorkingRow | null;
 } {
-  const tenantRow = user.roles.includes("SystemAdmin")
-    ? null
-    : pickByLocale(
-        rows.filter((row) => row.scope === "tenant"),
-        locale,
-      );
+  // A SystemAdmin editing the tenant layout sees the system version like a tenant does: served only, no draft.
+  const user =
+    scope === "system"
+      ? caller
+      : { ...caller, roles: caller.roles.filter((role) => role !== "SystemAdmin") };
+  const tenantRow =
+    scope === "system"
+      ? null
+      : pickByLocale(
+          rows.filter((row) => row.scope === "tenant"),
+          locale,
+        );
   const systemRow = pickByLocale(
     rows.filter((row) => row.scope === "system" && !isHiddenSystemDraft(user, row)),
     locale,
@@ -136,13 +147,21 @@ export const layoutSourceQuery = defineQueryHandler({
     kind: z.enum(["mail-layout", "pdf-layout"]),
     slug: templateSlugSchema.default("default"),
     locale: localeSchema.optional(),
+    scope: z.enum(["tenant", "system"]).optional(),
   }),
   access: { roles: ["TenantAdmin", "SystemAdmin"] },
   description:
-    "Reads the layout the caller edits: the tenant's own version and the system version of one layout slug (each the open draft if there is one, else the stored version, with `active` naming the served version), the header, signature and footer regions of the effective html version, and the locale a save has to use; a SystemAdmin edits the system version and also receives its mjml source. Use it to load the layout editor.",
+    "Reads the layout the caller edits: the tenant's own version and the system version of one layout slug (each the open draft if there is one, else the stored version, with `active` naming the served version), the header, signature and footer regions of the effective html version, and the locale a save has to use; a SystemAdmin edits the system version by default and also receives its mjml source; scope tenant loads the SystemAdmin's own tenant layout instead, and scope system is refused for everyone else. Use it to load the layout editor.",
   handler: async (query, ctx): Promise<LayoutSourceResponse> => {
     const { kind, slug, locale } = query.payload;
-    const isSystemAdmin = query.user.roles.includes("SystemAdmin");
+    const callerIsSystemAdmin = query.user.roles.includes("SystemAdmin");
+    const scope = query.payload.scope ?? (callerIsSystemAdmin ? "system" : "tenant");
+    if (scope === "system" && !callerIsSystemAdmin) {
+      throw new AccessDeniedError({
+        i18nKey: "errors.access.denied",
+        details: { reason: TemplateResolverErrors.systemAdminRequired },
+      });
+    }
     const policy = deliveryPolicyOf(ctx.registry);
     const rows = await filterDeliveredTo(
       ctx.db,
@@ -150,7 +169,13 @@ export const layoutSourceQuery = defineQueryHandler({
       query.user,
       await selectMany<TemplateResourceRow>(ctx.db, templateResourcesTable, { kind, slug }),
     );
-    const { tenantRow, systemRow } = pickEditedRows(rows, query.user, locale);
-    return buildLayoutSource({ kind, locale, isSystemAdmin, tenantRow, systemRow });
+    const { tenantRow, systemRow } = pickEditedRows(rows, query.user, scope, locale);
+    return buildLayoutSource({
+      kind,
+      locale,
+      isSystemAdmin: scope === "system",
+      tenantRow,
+      systemRow,
+    });
   },
 });

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

@@ -1,5 +1,6 @@
 import { selectMany } from "@cosmicdrift/kumiko-framework/db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { createI18n } from "@cosmicdrift/kumiko-framework/i18n";
 import * as z from "zod";
 import { type TemplateResourceRow, templateResourcesTable } from "../table.ts";
 import {
@@ -16,7 +17,11 @@ import {
   parseTemplateDraft,
   servedVersionOf,
 } from "../template-draft.ts";
-import { mayEditTemplate, type TemplateEditPolicy } from "../template-edit-policy.ts";
+import {
+  mayEditTemplate,
+  type TemplateEditPolicy,
+  templateEditAccess,
+} from "../template-edit-policy.ts";
 import { isSystemOnlyTemplateHiddenFrom } from "../template-system-only.ts";
 import { collectTemplateUsage, type EffectiveMailLayoutSlugs } from "../template-usage.ts";
 import {
@@ -204,7 +209,15 @@ function splitDocumentSlug(slug: string): { feature: string; notification: strin
     : { feature: slug.slice(0, separator), notification: slug.slice(separator + 1) };
 }
 
-function compareBy(field: SortField, a: OverviewRow, b: OverviewRow): number {
+type ShownTitle = (row: OverviewRow) => string;
+
+function compareBy(
+  field: SortField,
+  a: OverviewRow,
+  b: OverviewRow,
+  shownTitle: ShownTitle,
+): number {
+  if (field === "title") return shownTitle(a).localeCompare(shownTitle(b));
   return String(a[field]).localeCompare(String(b[field]));
 }
 
@@ -351,11 +364,17 @@ function filterRows(
   search: string | undefined,
   filters: readonly OverviewFilter[],
   layoutSlug: string | undefined,
+  shownTitle: ShownTitle,
 ): OverviewRow[] {
   const needle = search?.trim().toLowerCase() ?? "";
   return rows.filter((row) => {
     if (layoutSlug !== undefined && row.layoutSlug !== layoutSlug) return false;
-    if (needle !== "" && !`${row.title} ${row.slug}`.toLowerCase().includes(needle)) return false;
+    if (
+      needle !== "" &&
+      !`${shownTitle(row)} ${row.title} ${row.slug}`.toLowerCase().includes(needle)
+    ) {
+      return false;
+    }
     return filters.every((filter) => filter.value.includes(String(row[filter.field])));
   });
 }
@@ -379,7 +398,7 @@ export function makeOverviewQuery(policy: TemplateEditPolicy) {
       offset: z.number().int().min(0).optional(),
       totalCount: z.boolean().optional(),
     }),
-    access: { roles: ["TenantAdmin", "SystemAdmin"] },
+    access: templateEditAccess(policy.tenantEditable),
     description:
       "Lists mail, PDF and layout templates as one row per slug and kind for the caller's tenant (optionally only the mails and PDFs using one layout slug): where the effective version comes from (own override or system), its locales, status and version (the served one; `draftVersion` is set when an unpublished draft waits beside it, `activeSince` says since when the served version applies), the system version it overrides, the layout it uses and which notifications or templates use it; templates of notifications registered with `systemOnly` are listed for SystemAdmins only, and a TenantAdmin sees only the templates the app lists in tenantEditable; a tenant override of a template that is not listed is not delivered, so the row shows the system version with `lockedOverride` true (SystemAdmin only); use it to browse and filter all templates at a glance.",
     handler: async (query, ctx) => {
@@ -393,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,
         });
       }
@@ -415,21 +434,27 @@ export function makeOverviewQuery(policy: TemplateEditPolicy) {
         ? withOverriddenBy(
             rowsWithUsage,
             tenantOverrideCountsResultSchema.parse(
-              await ctx.query(TemplateResolverQueries.tenantOverrideCounts, {}),
+              await ctx.dispatch.query(TemplateResolverQueries.tenantOverrideCounts, {}),
             ),
           )
         : rowsWithUsage;
+      // A seeded title can be an i18n key; search and sort must see what the admin sees.
+      const i18n = createI18n(ctx.registry, { defaultLocale: "en" });
+      const shownTitle: ShownTitle = (row) => i18n.t(row.title, ctx.locale);
       const filtered = filterRows(
         overviewRows,
         payload.search,
         payload.filters ?? [],
         payload.layoutSlug,
+        shownTitle,
       );
 
       const sortField: SortField =
         payload.sort !== undefined && isSortField(payload.sort) ? payload.sort : "modifiedAt";
       const direction = (payload.sortDirection ?? "desc") === "desc" ? -1 : 1;
-      filtered.sort((a, b) => direction * compareBy(sortField, a, b) || a.id.localeCompare(b.id));
+      filtered.sort(
+        (a, b) => direction * compareBy(sortField, a, b, shownTitle) || a.id.localeCompare(b.id),
+      );
 
       const offset = payload.offset ?? 0;
       return {

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

@@ -40,7 +40,7 @@ export function makePatchDraftWrite(policy: TemplateEditPolicy) {
     }),
     access: templateEditAccess(policy.tenantEditable),
     description:
-      "Changes a mail or PDF document template with structured operations instead of a full rewrite and saves the result as the caller's tenant draft (never published, an active version keeps being served until publish): insertBlock after a block id (null = at the start; paragraph, heading, image, button, divider, pageBreak), replaceText inside one block (the text must occur exactly once), removeBlock, setResource on an image block, setMeta (flat merge, null removes a key) and setVariable (adds, replaces or with null removes a variable definition; refused when a notification declares the variables). Block ids and base come from document-blocks and refer to the state that was read; if the template changed since, the call fails with version_conflict and nothing is written. A patch that removes a required placeholder is refused. A TenantAdmin may patch only templates the app lists in tenantEditable, otherwise SystemAdmin only. Returns the written row.",
+      "Changes a mail or PDF document template with structured operations instead of a full rewrite and saves the result as the caller's tenant draft (never published, an active version keeps being served until publish): insertBlock after a block id (null = at the start; paragraph, heading, image, button, divider, pageBreak), replaceText inside one block (the text must occur exactly once within one formatting run and cannot contain a {{placeholder}}: a find across a formatting change fails with text_spans_formatting, a find with a placeholder with placeholder_not_replaceable, and the formatting of the replaced text is kept), removeBlock, setResource on an image block, setMeta (flat merge, null removes a key) and setVariable (adds, replaces or with null removes a variable definition; refused when a notification declares the variables). Block ids and base come from document-blocks and refer to the state that was read; if the template changed since, the call fails with version_conflict and nothing is written. A patch that removes a required placeholder is refused. A TenantAdmin may patch only templates the app lists in tenantEditable, otherwise SystemAdmin only. Returns the written row.",
     handler: async (event, ctx) => {
       const { slug, kind, locale, base, ops } = event.payload;
       const refused = refuseTemplateEdit(policy, event.user, { slug, kind });

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-status.query.ts

@@ -1,5 +1,6 @@
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
+import { type TemplateEditPolicy, templateEditAccess } from "../template-edit-policy.ts";
 import {
   emailChannelOf,
   resolveTestMailAddress,
@@ -10,22 +11,24 @@ export type SendTestStatus =
   | { readonly canSend: true; readonly reason: null }
   | { readonly canSend: false; readonly reason: "no_channel" | "no_address" };
 
-export const sendTestStatusQuery = defineQueryHandler({
-  name: "send-test-status",
-  schema: z.object({}),
-  access: { roles: ["TenantAdmin", "SystemAdmin"] },
-  description:
-    "Tells whether send-test can reach the calling user: canSend is true when an email channel is mounted and resolves an address for the caller, otherwise reason is no_channel or no_address; the address itself is never returned.",
-  handler: async (query, ctx): Promise<SendTestStatus> => {
-    const channel = emailChannelOf(ctx.registry);
-    if (channel === undefined) return { canSend: false, reason: "no_channel" };
-    const address = await resolveTestMailAddress(
-      channel,
-      testMailChannelContext(ctx, query.user),
-      query.user,
-    );
-    return address === null
-      ? { canSend: false, reason: "no_address" }
-      : { canSend: true, reason: null };
-  },
-});
+export function makeSendTestStatusQuery(policy: TemplateEditPolicy) {
+  return defineQueryHandler({
+    name: "send-test-status",
+    schema: z.object({}),
+    access: templateEditAccess(policy.tenantEditable),
+    description:
+      "Tells whether send-test can reach the calling user: canSend is true when an email channel is mounted and resolves an address for the caller, otherwise reason is no_channel or no_address; the address itself is never returned.",
+    handler: async (query, ctx): Promise<SendTestStatus> => {
+      const channel = emailChannelOf(ctx.registry);
+      if (channel === undefined) return { canSend: false, reason: "no_channel" };
+      const address = await resolveTestMailAddress(
+        channel,
+        testMailChannelContext(ctx, query.user),
+        query.user,
+      );
+      return address === null
+        ? { canSend: false, reason: "no_address" }
+        : { canSend: true, reason: null };
+    },
+  });
+}

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,
         });
       }