@cosmicdrift/kumiko-samples 0.404.0 → 0.405.0

package/packages/bundled-features/src/subscription-paddle/price-methods.ts

@@ -2,10 +2,13 @@
 // cache misses, cached per price id.
 
 import {
+  createTtlPriceCache,
   KNOWN_RECURRING_INTERVALS,
   type ProviderPrice,
+  type TtlPriceCache,
 } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
 import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import { chunk } from "@cosmicdrift/kumiko-framework/utils";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import * as z from "zod";
 import type { PaddleCtxRuntime, PaddlePluginMethod } from "./runtime.ts";
@@ -61,10 +64,7 @@ function mapPaddlePrice(price: PaddlePrice): ProviderPrice {
   return { ...base, interval, intervalCount: interval ? cycle.frequency : null };
 }
 
-export type PaddlePriceCache = {
-  readonly get: (priceId: string) => ProviderPrice | undefined;
-  readonly set: (priceId: string, price: ProviderPrice) => void;
-};
+export type PaddlePriceCache = TtlPriceCache<ProviderPrice>;
 
 export type PaddlePriceCacheOptions = {
   readonly ttlMs?: number;
@@ -75,32 +75,10 @@ export type PaddlePriceCacheOptions = {
 // trigger an audited secret read on every billing-plans render. Failed lookups
 // are never cached.
 export function createPaddlePriceCache({
-  ttlMs = 600_000,
+  ttlMs,
   now = () => Temporal.Now.instant().epochMilliseconds,
 }: PaddlePriceCacheOptions = {}): PaddlePriceCache {
-  const store = new Map<string, { readonly price: ProviderPrice; readonly expiresAt: number }>();
-  return {
-    get: (priceId) => {
-      const entry = store.get(priceId);
-      if (!entry) return undefined;
-      if (entry.expiresAt <= now()) {
-        store.delete(priceId);
-        return undefined;
-      }
-      return entry.price;
-    },
-    set: (priceId, price) => {
-      store.set(priceId, { price, expiresAt: now() + ttlMs });
-    },
-  };
-}
-
-function chunked<T>(items: readonly T[], size: number): T[][] {
-  const chunks: T[][] = [];
-  for (let start = 0; start < items.length; start += size) {
-    chunks.push(items.slice(start, start + size));
-  }
-  return chunks;
+  return createTtlPriceCache<ProviderPrice>({ ttlMs, now });
 }
 
 async function fillPriceCache(
@@ -111,7 +89,7 @@ async function fillPriceCache(
 ): Promise<void> {
   const misses = [...new Set(priceIds.filter((priceId) => cache.get(priceId) === undefined))];
   const settled = await Promise.allSettled(
-    chunked(misses, PRICES_PER_REQUEST).map(async (ids) =>
+    chunk(misses, PRICES_PER_REQUEST).map(async (ids) =>
       pricesResponseSchema.parse(
         await runtime.call(ctx, {
           method: "GET",

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

@@ -7,7 +7,10 @@
 // HandlerContext; the pre-tenant webhook reads secrets un-audited from the
 // system SecretsContext the foundation passes in.
 
-import type { SubscriptionProviderPlugin } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+import {
+  parseStoredSecret,
+  type SubscriptionProviderPlugin,
+} from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
 import { requireSecretsContext } from "@cosmicdrift/kumiko-bundled-features/secrets";
 import {
   type ConfigKeyHandle,
@@ -16,7 +19,6 @@ import {
 } from "@cosmicdrift/kumiko-framework/engine";
 import { FeatureDisabledError, UnconfiguredError } from "@cosmicdrift/kumiko-framework/errors";
 import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
-import { parseJsonSafe } from "@cosmicdrift/kumiko-framework/utils";
 import { createPaddleHttp, type PaddleRequest, type PaddleSend } from "./client.ts";
 import {
   PADDLE_BASE_URLS,
@@ -47,19 +49,6 @@ export type PaddleRuntimeDeps = {
   readonly fallback: PaddleFallbacks;
 };
 
-// backing:"secrets" values are stored JSON-serialized, so the store read has to
-// be parsed back; the env fallback is a plain string and stays raw. The error
-// must not carry the input: the JSON parser's own message would repeat the
-// credential into logs and, for webhooks, into the 401 body.
-function parseStoredSecret(raw: string | undefined): string | undefined {
-  if (raw === undefined || raw.length === 0) return undefined;
-  const parsed = parseJsonSafe<unknown>(raw, undefined);
-  if (parsed === undefined) {
-    throw new Error("subscription-paddle credential (backing:secrets) is not valid JSON");
-  }
-  return typeof parsed === "string" && parsed.length > 0 ? parsed : undefined;
-}
-
 function hintFor(shortName: string): string {
   return `Set it via config:write:set on \`${SUBSCRIPTION_PADDLE_FEATURE}:config:${shortName}\` (or seed it from the matching PADDLE_* variable during the env bridge).`;
 }
@@ -108,7 +97,7 @@ export function createPaddleRuntimes(deps: PaddleRuntimeDeps): PaddleRuntimes {
         { secrets: ctx.services.secrets, user: ctx.user },
         SUBSCRIPTION_PADDLE_FEATURE,
       ).get(SYSTEM_TENANT_ID, handle.name);
-      value = parseStoredSecret(got?.reveal());
+      value = parseStoredSecret("subscription-paddle", got?.reveal());
     }
     if (!value && fallback && fallback.length > 0) value = fallback;
     if (!value) {
@@ -129,7 +118,7 @@ export function createPaddleRuntimes(deps: PaddleRuntimeDeps): PaddleRuntimes {
     if (systemSecrets) {
       // No auditCtx: every webhook would otherwise spam the audit trail.
       const got = await systemSecrets.get(SYSTEM_TENANT_ID, handle.name);
-      const stored = parseStoredSecret(got?.reveal());
+      const stored = parseStoredSecret("subscription-paddle", got?.reveal());
       if (stored) return stored;
     }
     if (fallback && fallback.length > 0) return fallback;

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

@@ -32,7 +32,10 @@
 // api key + webhook secret without auditing (a sanctioned framework-internal
 // read).
 
-import type { SubscriptionProviderPlugin } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+import {
+  type SubscriptionProviderPlugin,
+  validateOneOffPriceIds,
+} from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
 import {
   access,
   createSystemConfig,
@@ -144,23 +147,6 @@ export type SubscriptionStripeOptions = {
   readonly oneOffPriceIds?: readonly string[];
 };
 
-// Validated once at feature-build time (not per-request) so a config typo
-// (a pasted-twice priceId, a blank string from a bad env-join) fails app
-// startup instead of silently widening — or narrowing — the one-off
-// allowlist at request time. Mirrors legal-pages' validateRoutes.
-function validateOneOffPriceIds(priceIds: readonly string[]): void {
-  const seen = new Set<string>();
-  for (const priceId of priceIds) {
-    if (priceId.length === 0) {
-      throw new Error("subscription-stripe: oneOffPriceIds must not contain an empty string");
-    }
-    if (seen.has(priceId)) {
-      throw new Error(`subscription-stripe: duplicate oneOffPriceIds entry "${priceId}"`);
-    }
-    seen.add(priceId);
-  }
-}
-
 /**
  * Factory for the subscription-stripe feature. Always mounts (no
  * key-presence guard) — activity is gated at runtime through config/secrets
@@ -171,7 +157,7 @@ function validateOneOffPriceIds(priceIds: readonly string[]): void {
 export function createSubscriptionStripeFeature(
   options: SubscriptionStripeOptions = {},
 ): FeatureWithEnvSchema<FeatureDefinition, typeof subscriptionStripeEnvSchema.shape> {
-  validateOneOffPriceIds(options.oneOffPriceIds ?? []);
+  validateOneOffPriceIds("subscription-stripe", options.oneOffPriceIds ?? []);
   const feature: FeatureDefinition = defineFeature(SUBSCRIPTION_STRIPE_FEATURE, (r) => {
     r.describe(
       'Stripe payment provider plugin for `billing-foundation`. Reads its Stripe API key + webhook secret from system config keys with `backing:"secrets"` (envelope-encrypted in the secrets store under the system tenant) and a `billingLive` **system config** flag — all at runtime, so keys rotate and prod goes live without a redeploy. The `mask` on each key derives the sysadmin settings screen + nav, so no app wires a hand-written config UI. Mount via `createSubscriptionStripeFeature({ priceToTier })`; the optional `apiKey`/`webhookSecret` options are env→secrets bridge fallbacks. The plugin always mounts — `createCheckoutSession` throws `feature_disabled` unless `billingLive` is true, so sk_test_ keys in prod never produce a live checkout. Implements webhook verify, checkout, portal, cancel, `retrievePrices` (10-minute TTL-cached price lookup for the billing-plans catalog), `createPlanSwitchSession` (auto-provisions a Customer-Portal configuration for switching an existing subscription to another plan tier — each tier needs its own Stripe product), `retrieveSubscription` (live provider-side snapshot for the `sync-subscriptions` backfill job, mapped identically to the webhook path), plus `isBillingEnabled` (billingLive + an api-key existence probe, no secret read).',

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

@@ -17,12 +17,14 @@
 
 import { createHash } from "node:crypto";
 import {
+  createTtlPriceCache,
   KNOWN_RECURRING_INTERVALS,
   type ProviderPrice,
   type ProviderSubscriptionSnapshot,
   type RecurringInterval,
   SubscriptionCancelTimings,
   type SubscriptionProviderPlugin,
+  type TtlPriceCache,
 } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
 import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
 import { ConflictError, UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
@@ -332,10 +334,7 @@ function mapStripePrice(price: Stripe.Price): ProviderPrice {
 // requests the billing-plans catalog re-renders on every page load. Keyed by
 // priceId alone: Stripe priceIds are account-wide unique. Failed lookups are
 // never cached, so a transient Stripe outage self-heals on the next call.
-export type StripePriceCache = {
-  readonly get: (priceId: string) => Stripe.Price | undefined;
-  readonly set: (priceId: string, price: Stripe.Price) => void;
-};
+export type StripePriceCache = TtlPriceCache<Stripe.Price>;
 
 export type StripePriceCacheOptions = {
   readonly ttlMs?: number;
@@ -343,24 +342,10 @@ export type StripePriceCacheOptions = {
 };
 
 export function createStripePriceCache({
-  ttlMs = 600_000,
+  ttlMs,
   now = () => Date.now(),
 }: StripePriceCacheOptions = {}): StripePriceCache {
-  const store = new Map<string, { readonly price: Stripe.Price; readonly expiresAt: number }>();
-  return {
-    get: (priceId) => {
-      const entry = store.get(priceId);
-      if (!entry) return undefined;
-      if (entry.expiresAt <= now()) {
-        store.delete(priceId);
-        return undefined;
-      }
-      return entry.price;
-    },
-    set: (priceId, price) => {
-      store.set(priceId, { price, expiresAt: now() + ttlMs });
-    },
-  };
+  return createTtlPriceCache<Stripe.Price>({ ttlMs, now });
 }
 
 /** Fills `cache` for every priceId not already resolved — the only place

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

@@ -25,6 +25,7 @@
 //     un-audited framework-internal path). The foundation builds and passes
 //     this SecretsContext as the 3rd webhook arg.
 
+import { parseStoredSecret } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
 import { requireSecretsContext } from "@cosmicdrift/kumiko-bundled-features/secrets";
 import {
   type ConfigKeyHandle,
@@ -33,7 +34,6 @@ import {
 } from "@cosmicdrift/kumiko-framework/engine";
 import { FeatureDisabledError, UnconfiguredError } from "@cosmicdrift/kumiko-framework/errors";
 import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
-import { parseJsonSafe } from "@cosmicdrift/kumiko-framework/utils";
 import Stripe from "stripe";
 import { SUBSCRIPTION_STRIPE_FEATURE } from "./constants.ts";
 
@@ -63,22 +63,6 @@ export type StripeRuntimeDeps = {
   readonly fallback: { readonly apiKey?: string; readonly webhookSecret?: string };
 };
 
-// backing:"secrets" config keys store their value JSON-serialized in the
-// secrets store (config:write:set → JSON.stringify). A raw SecretsContext.get
-// (the un-audited webhook path + the audited ctx read here) therefore returns
-// the JSON-quoted string and must parse it back. The factory fallback is a
-// plain env string and stays raw — so parsing is applied only to the store
-// read, never to the fallback. The error must not carry the input: the JSON
-// parser's own message would repeat the credential into logs and the 401 body.
-function parseStoredSecret(raw: string | undefined): string | undefined {
-  if (raw === undefined || raw.length === 0) return undefined;
-  const parsed = parseJsonSafe<unknown>(raw, undefined);
-  if (parsed === undefined) {
-    throw new Error("subscription-stripe credential (backing:secrets) is not valid JSON");
-  }
-  return typeof parsed === "string" && parsed.length > 0 ? parsed : undefined;
-}
-
 /** Post-tenant runtime: used by checkout/portal/cancel which carry a full
  *  HandlerContext (audited secret reads, config-gate). */
 export type StripeCtxRuntime = {
@@ -119,7 +103,7 @@ export function createStripeRuntimes(deps: StripeRuntimeDeps): StripeRuntimes {
         { secrets: ctx.services.secrets, user: ctx.user },
         SUBSCRIPTION_STRIPE_FEATURE,
       ).get(SYSTEM_TENANT_ID, deps.apiKeyHandle.name);
-      key = parseStoredSecret(got?.reveal());
+      key = parseStoredSecret("subscription-stripe", got?.reveal());
     }
     if (!key && deps.fallback.apiKey && deps.fallback.apiKey.length > 0) {
       key = deps.fallback.apiKey;
@@ -143,7 +127,7 @@ export function createStripeRuntimes(deps: StripeRuntimeDeps): StripeRuntimes {
       // No auditCtx → un-audited framework-internal read (every webhook would
       // otherwise spam the audit trail). This is the sanctioned no-ctx path.
       const got = await systemSecrets.get(SYSTEM_TENANT_ID, handle.name);
-      const value = parseStoredSecret(got?.reveal());
+      const value = parseStoredSecret("subscription-stripe", got?.reveal());
       if (value && value.length > 0) return value;
     }
     return fallback && fallback.length > 0 ? fallback : undefined;

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

@@ -27,7 +27,7 @@ import {
   type EntityDefinition,
   type FeatureRegistrar,
 } from "@cosmicdrift/kumiko-framework/engine";
-import { assertNoWhereRuleInOwnershipWrite } from "../shared/index.ts";
+import { assertNoWhereRuleInOwnershipWrite, resolveFeatureAccess } from "../shared/index.ts";
 import { createTagAssignmentEntity, tagEntity } from "./entity.ts";
 import { createTagAssignmentExecutor } from "./executor.ts";
 import { createAssignTagHandler } from "./handlers/assign-tag.write.ts";
@@ -175,12 +175,6 @@ export type TagsFeatureOptions = {
   readonly parents?: readonly string[];
 };
 
-function resolveAccess(opts: TagsFeatureOptions): AccessRule {
-  if (opts.access !== undefined) return opts.access;
-  if (opts.roles !== undefined) return { roles: opts.roles };
-  return DEFAULT_TAG_ACCESS;
-}
-
 // Backwards-compat / options wrapper. Without options returns the module-level
 // singleton (no rebuild). access/roles/toggleable/ownership build a fresh
 // feature-definition.
@@ -203,7 +197,7 @@ export function createTagsFeature(opts: TagsFeatureOptions = {}): typeof default
     );
   }
   assertNoWhereRuleInOwnershipWrite("createTagsFeature", opts.ownership?.write);
-  const access = resolveAccess(opts);
+  const access = resolveFeatureAccess(opts, DEFAULT_TAG_ACCESS);
   return defineFeature(TAGS_FEATURE_NAME, (r) =>
     registerTags(r, access, opts.toggleable, opts.ownership, opts.parents),
   );

package/packages/bundled-features/src/tags/web/tag-manager.tsx

@@ -17,6 +17,7 @@ import {
 } from "@cosmicdrift/kumiko-renderer";
 import { pluralKey } from "@cosmicdrift/kumiko-renderer/headless";
 import { type ReactNode, useState } from "react";
+import { useDispatchedWrites } from "../../shared/web/use-dispatched-writes.ts";
 import { TagsHandlers, TagsQueries } from "./constants.ts";
 import { TagChip } from "./tag-chip.tsx";
 
@@ -117,8 +118,10 @@ export function TagManager({
   const [editColor, setEditColor] = useState("");
   const [editScope, setEditScope] = useState("");
   const [deleting, setDeleting] = useState<TagRow | null>(null);
-  const [busy, setBusy] = useState(false);
-  const [errorKey, setErrorKey] = useState<string | null>(null);
+  const refetch = async (): Promise<void> => {
+    await Promise.all([catalog.refetch(), assignments.refetch()]);
+  };
+  const { busy, errorKey, setErrorKey, writeOk, apply } = useDispatchedWrites(refetch);
 
   if (catalog.loading && catalog.data === null) {
     return (
@@ -149,29 +152,6 @@ export function TagManager({
       })
     : allTags;
 
-  const refetch = async (): Promise<void> => {
-    await Promise.all([catalog.refetch(), assignments.refetch()]);
-  };
-
-  const apply = async (writes: () => Promise<boolean>): Promise<void> => {
-    setBusy(true);
-    setErrorKey(null);
-    try {
-      if (await writes()) await refetch();
-    } finally {
-      setBusy(false);
-    }
-  };
-
-  const writeOk = async (type: string, payload: Record<string, unknown>): Promise<boolean> => {
-    const result = await dispatcher.write(type, payload);
-    if (!result.isSuccess) {
-      setErrorKey(result.error.i18nKey);
-      return false;
-    }
-    return true;
-  };
-
   const createTag = (): void => {
     const name = newName.trim();
     if (name === "") return;

package/packages/bundled-features/src/tags/web/tag-section.tsx

@@ -11,13 +11,9 @@
 //                   component: { react: { __component: TAGS_SECTION_EXTENSION_NAME } }
 //                   (RenderEdit passes { entityName, entityId }).
 
-import {
-  useDispatcher,
-  usePrimitives,
-  useQuery,
-  useTranslation,
-} from "@cosmicdrift/kumiko-renderer";
+import { usePrimitives, useQuery, useTranslation } from "@cosmicdrift/kumiko-renderer";
 import { type ReactNode, useState } from "react";
+import { useDispatchedWrites } from "../../shared/web/use-dispatched-writes.ts";
 import { TagsHandlers, TagsQueries } from "./constants.ts";
 import { TagChip } from "./tag-chip.tsx";
 import { TagPicker } from "./tag-picker.tsx";
@@ -53,7 +49,6 @@ export function TagSection({
 }): ReactNode {
   const { Banner, Button, Text } = usePrimitives();
   const t = useTranslation();
-  const dispatcher = useDispatcher();
   const enabled = entityId !== null;
   const catalog = useQuery<TagListResponse>(TagsQueries.tagList, {}, { enabled });
   // entityType server-side, not just entityId: it collapses the parent-ref
@@ -69,8 +64,7 @@ export function TagSection({
     { enabled },
   );
   const [pickerOpen, setPickerOpen] = useState(false);
-  const [busy, setBusy] = useState(false);
-  const [errorKey, setErrorKey] = useState<string | null>(null);
+  const { busy, setBusy, errorKey, setErrorKey, writeOk } = useDispatchedWrites();
 
   if (entityId === null) {
     return (
@@ -105,15 +99,6 @@ export function TagSection({
     await Promise.all([catalog.refetch(), assignments.refetch()]);
   };
 
-  const writeOk = async (type: string, payload: Record<string, unknown>): Promise<boolean> => {
-    const result = await dispatcher.write(type, payload);
-    if (!result.isSuccess) {
-      setErrorKey(result.error.i18nKey);
-      return false;
-    }
-    return true;
-  };
-
   const onPicked = (next: readonly string[]): void => {
     const { added, removed } = tagSelectionDelta(assignedIds, next);
     if (added.length === 0 && removed.length === 0) return;

package/packages/bundled-features/src/template-resolver/README.md

@@ -44,13 +44,13 @@ async function someHandler(ctx) {
 
 ## Kinds, format, and meta
 
-| kind | contentFormat | meta |
-|---|---|---|
-| `mail` | `html` (document schema, rebuilt server-side) | Required: `subject`; optional `previewText`, `layoutSlug`, `category` (`transactional`/`marketing`), `senderName`, `replyTo` |
-| `mail-layout` | `mjml` | empty (`{}`) or missing |
-| `pdf-layout` | `html` | empty (`{}`) or missing |
-| `document-pdf` | `html` | missing |
-| remaining kinds | arbitrary | missing |
+| kind            | contentFormat                                 | meta                                                                                                                         |
+| --------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `mail`          | `html` (document schema, rebuilt server-side) | Required: `subject`; optional `previewText`, `layoutSlug`, `category` (`transactional`/`marketing`), `senderName`, `replyTo` |
+| `mail-layout`   | `mjml`                                        | empty (`{}`) or missing                                                                                                      |
+| `pdf-layout`    | `html`                                        | empty (`{}`) or missing                                                                                                      |
+| `document-pdf`  | `html`                                        | missing                                                                                                                      |
+| remaining kinds | arbitrary                                     | missing                                                                                                                      |
 
 `meta` is stored as JSON in the `meta` column and is validated on write per kind against
 `template-meta.ts` (errors as field issues on `meta.*`). Subject and preview text allow only simple
@@ -105,22 +105,22 @@ await seedSystemTemplate(db, {
 
 ## Admin workflows (write handlers + queries)
 
-| Handler | QN | Who | What |
-|---|---|---|---|
-| `TemplateResolverHandlers.upsertSystem` | `template-resolver:write:upsert-system` | SystemAdmin | Creates or updates system default templates (`SYSTEM_TENANT_ID`, scope='system', status='active') |
-| `TemplateResolverHandlers.upsertTenant` | `template-resolver:write:upsert-tenant` | TenantAdmin (own tenant) + SystemAdmin via `tenantIdOverride` | Creates or updates tenant overrides (scope='tenant'), default status='draft' |
-| `TemplateResolverHandlers.publish` | `template-resolver:write:publish` | TenantAdmin (own tenant) | Sets status='active' |
-| `TemplateResolverHandlers.archive` | `template-resolver:write:archive` | TenantAdmin (own tenant) | Sets status='archived' (the resolver ignores it afterward) |
-| `TemplateResolverHandlers.publishSystem` | `template-resolver:write:publish-system` | SystemAdmin | Sets status='active' on a system default, with the same mail validation as `publish` |
-| `TemplateResolverHandlers.archiveSystem` | `template-resolver:write:archive-system` | SystemAdmin | Sets status='archived' on a system default; tenants without an override fall through |
-| `TemplateResolverHandlers.resetToSystem` | `template-resolver:write:reset-to-system` | TenantAdmin (own tenant) | Archives the own override so that the active system template applies again; without an active system template, `no_system_template` |
-| `TemplateResolverQueries.findById` | `template-resolver:query:find-by-id` | TenantAdmin + User (own tenant, system templates visible) | Raw lookup for the edit UI |
-| `TemplateResolverQueries.list` | `template-resolver:query:list` | same | Filters by kind/locale/status, optionally includeSystem |
-| `TemplateResolverQueries.usage` | `template-resolver:query:usage` | TenantAdmin | Which notifications use a mail template or mail layout, from the registry |
-| `TemplateResolverQueries.overview` | `template-resolver:query:overview` | TenantAdmin + SystemAdmin | One row per slug and type, mail, PDF, layouts, with origin, languages, status, version, layout, and usage; searchable, filterable, sortable, and pageable |
-| `TemplateResolverQueries.layoutSource` | `template-resolver:query:layout-source` | TenantAdmin + SystemAdmin | Own and system version of a layout, header/signature/footer regions of the effective HTML version, storage locale; MJML source only for SystemAdmin |
-| `TemplateResolverQueries.tenantOverrides` | `template-resolver:query:tenant-overrides` | SystemAdmin | Number of active/draft overrides of a system template and total active tenants, numbers only |
-| `TemplateResolverQueries.diffToSystem` | `template-resolver:query:diff-to-system` | TenantAdmin (own tenant) | Block and meta comparison of a tenant override with the system template |
+| Handler                                   | QN                                         | Who                                                           | What                                                                                                                                                      |
+| ----------------------------------------- | ------------------------------------------ | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `TemplateResolverHandlers.upsertSystem`   | `template-resolver:write:upsert-system`    | SystemAdmin                                                   | Creates or updates system default templates (`SYSTEM_TENANT_ID`, scope='system', status='active')                                                         |
+| `TemplateResolverHandlers.upsertTenant`   | `template-resolver:write:upsert-tenant`    | TenantAdmin (own tenant) + SystemAdmin via `tenantIdOverride` | Creates or updates tenant overrides (scope='tenant'), default status='draft'                                                                              |
+| `TemplateResolverHandlers.publish`        | `template-resolver:write:publish`          | TenantAdmin (own tenant)                                      | Sets status='active'                                                                                                                                      |
+| `TemplateResolverHandlers.archive`        | `template-resolver:write:archive`          | TenantAdmin (own tenant)                                      | Sets status='archived' (the resolver ignores it afterward)                                                                                                |
+| `TemplateResolverHandlers.publishSystem`  | `template-resolver:write:publish-system`   | SystemAdmin                                                   | Sets status='active' on a system default, with the same mail validation as `publish`                                                                      |
+| `TemplateResolverHandlers.archiveSystem`  | `template-resolver:write:archive-system`   | SystemAdmin                                                   | Sets status='archived' on a system default; tenants without an override fall through                                                                      |
+| `TemplateResolverHandlers.resetToSystem`  | `template-resolver:write:reset-to-system`  | TenantAdmin (own tenant)                                      | Archives the own override so that the active system template applies again; without an active system template, `no_system_template`                       |
+| `TemplateResolverQueries.findById`        | `template-resolver:query:find-by-id`       | TenantAdmin + User (own tenant, system templates visible)     | Raw lookup for the edit UI                                                                                                                                |
+| `TemplateResolverQueries.list`            | `template-resolver:query:list`             | same                                                          | Filters by kind/locale/status, optionally includeSystem                                                                                                   |
+| `TemplateResolverQueries.usage`           | `template-resolver:query:usage`            | TenantAdmin                                                   | Which notifications use a mail template or mail layout, from the registry                                                                                 |
+| `TemplateResolverQueries.overview`        | `template-resolver:query:overview`         | TenantAdmin + SystemAdmin                                     | One row per slug and type, mail, PDF, layouts, with origin, languages, status, version, layout, and usage; searchable, filterable, sortable, and pageable |
+| `TemplateResolverQueries.layoutSource`    | `template-resolver:query:layout-source`    | TenantAdmin + SystemAdmin                                     | Own and system version of a layout, header/signature/footer regions of the effective HTML version, storage locale; MJML source only for SystemAdmin       |
+| `TemplateResolverQueries.tenantOverrides` | `template-resolver:query:tenant-overrides` | SystemAdmin                                                   | Number of active/draft overrides of a system template and total active tenants, numbers only                                                              |
+| `TemplateResolverQueries.diffToSystem`    | `template-resolver:query:diff-to-system`   | TenantAdmin (own tenant)                                      | Block and meta comparison of a tenant override with the system template                                                                                   |
 
 **SystemAdmin cross-tenant access for publish/archive/findById:** deferred (Task 8), `upsertTenant` already has `tenantIdOverride`; publish/archive only need this when a system admin panel curates templates belonging to other tenants. `ctx.db` is tenant-scoped, foreign IDs result in NotFound without an override.
 
@@ -166,12 +166,12 @@ The harness checks `TemplateNotFoundError` propagation, locale fallback, and, wh
 Marketing, FAQ, and legal texts use the same store, but a separate write path: `set.write` carries
 `title` + `folder` (content tree) and has no draft status, saving publishes.
 
-| Handler | QN | Who | What |
-|---|---|---|---|
-| `TemplateResolverHandlers.set` | `template-resolver:write:set` | TenantAdmin + SystemAdmin (via `tenantIdOverride`, also on `SYSTEM_TENANT_ID`) | Upserts one resource per `(tenantId, slug, kind, locale)` |
-| `TemplateResolverQueries.bySlug` | `template-resolver:query:by-slug` | anonymous + User + Admins | One text block, the public read for landing/legal pages |
-| `TemplateResolverQueries.byTenant` | `template-resolver:query:by-tenant` | anonymous + User + Admins | All text blocks of a tenant for the content tree |
-| `<collection>-list` / `-item` / `-set` | `template-resolver:query:<id>-list` … | as declared | Per content collection, see below |
+| Handler                                | QN                                    | Who                                                                            | What                                                      |
+| -------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------- |
+| `TemplateResolverHandlers.set`         | `template-resolver:write:set`         | TenantAdmin + SystemAdmin (via `tenantIdOverride`, also on `SYSTEM_TENANT_ID`) | Upserts one resource per `(tenantId, slug, kind, locale)` |
+| `TemplateResolverQueries.bySlug`       | `template-resolver:query:by-slug`     | anonymous + User + Admins                                                      | One text block, the public read for landing/legal pages   |
+| `TemplateResolverQueries.byTenant`     | `template-resolver:query:by-tenant`   | anonymous + User + Admins                                                      | All text blocks of a tenant for the content tree          |
+| `<collection>-list` / `-item` / `-set` | `template-resolver:query:<id>-list` … | as declared                                                                    | Per content collection, see below                         |
 
 The two public queries are hardcoded to `kind: "text-block"` and accept **no** kind parameter. Mail
 templates and AI prompts are stored in the same table and use the handlers of their collection. This

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

@@ -248,8 +248,9 @@ export function withParsedDocument<T>(html: string, read: (body: ScanElement) =>
     );
     return read(parsed.body);
   } finally {
-    window.happyDOM.abort();
-    window.happyDOM.close();
+    // The window is never reused, so this sync API need not await the teardown promises.
+    void window.happyDOM.abort();
+    void window.happyDOM.close();
   }
 }
 

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

@@ -4,6 +4,7 @@ import {
   MAX_LIST_LIMIT,
   SYSTEM_TENANT_ID,
 } from "@cosmicdrift/kumiko-framework/engine";
+import { chunk } from "@cosmicdrift/kumiko-framework/utils";
 import * as z from "zod";
 import { TenantQueries } from "../../tenant/index.ts";
 import { type TemplateResourceRow, templateResourcesTable } from "../table.ts";
@@ -22,14 +23,6 @@ const directorySchema = z.object({
 
 type OverrideStatus = "active" | "draft";
 
-function chunksOf<T>(items: readonly T[], size: number): T[][] {
-  const chunks: T[][] = [];
-  for (let start = 0; start < items.length; start += size) {
-    chunks.push(items.slice(start, start + size));
-  }
-  return chunks;
-}
-
 type DirectoryQueryContext = {
   readonly dispatch: {
     readonly query: (name: string, payload: { ids: string[] }) => Promise<unknown>;
@@ -43,8 +36,8 @@ async function labelsFor(
   ids: ReadonlySet<string>,
 ): Promise<ReadonlyMap<string, string>> {
   const labels = new Map<string, string>();
-  for (const chunk of chunksOf([...ids], MAX_LIST_LIMIT)) {
-    const raw = await ctx.dispatch.query(queryName, { ids: chunk });
+  for (const idChunk of chunk([...ids], MAX_LIST_LIMIT)) {
+    const raw = await ctx.dispatch.query(queryName, { ids: idChunk });
     for (const row of directorySchema.parse(raw).rows) labels.set(row.id, row.label);
   }
   return labels;

package/packages/bundled-features/src/template-resolver/web/collection-entry-create-form.tsx

@@ -17,6 +17,7 @@ const SLUG_INVALID_ISSUE: FieldIssue = {
 export function createCollectionEntryCreateForm(
   tenantId: string | undefined,
 ): (props: { readonly target: TargetRef; readonly onClose: () => void }) => ReactNode {
+  // biome-ignore lint/correctness/noComponentHookFactories: setup-time factory, called once per templateResolverClient(); the resolver slot only passes target/onClose, so tenantId is bound here
   return function BoundCollectionEntryCreateForm(props) {
     return <CollectionEntryCreateForm {...props} tenantId={tenantId} />;
   };

package/packages/bundled-features/src/tenant/handlers/decrypt-member-users.ts

@@ -0,0 +1,30 @@
+import { decryptStoredPii, mapWithConcurrency } from "../../shared/index.ts";
+
+export type MemberUserRow = {
+  readonly id: unknown;
+  readonly email?: unknown;
+  readonly displayName?: unknown;
+};
+
+// Bounded, not Promise.all/sequential: each decrypt hits the KMS adapter's
+// own small dedicated pool (PgKmsAdapter default max: 4). Promise.all fires
+// one call per user unbounded and exhausts the pool once membership counts
+// exceed a handful, surfacing as "the connection was closed"; a strict
+// sequential loop caps concurrency at 1 and leaves 3 pool slots idle.
+export const KMS_POOL_CONCURRENCY = 4;
+
+export async function decryptMemberUsers(
+  users: readonly MemberUserRow[],
+  reason: string,
+): Promise<Map<string, { readonly email: string | null; readonly displayName: string | null }>> {
+  const decrypted = await mapWithConcurrency(users, KMS_POOL_CONCURRENCY, async (user) => {
+    const email =
+      typeof user.email === "string" ? await decryptStoredPii(user.email, "email", reason) : null;
+    const displayName =
+      typeof user.displayName === "string"
+        ? await decryptStoredPii(user.displayName, "displayName", reason)
+        : null;
+    return { userId: String(user.id), email, displayName };
+  });
+  return new Map(decrypted.map((d) => [d.userId, d]));
+}

package/packages/bundled-features/src/tenant/handlers/members.query.ts

@@ -3,18 +3,9 @@ import { access, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import { parseRoles } from "@cosmicdrift/kumiko-framework/utils";
 import * as z from "zod";
-import { decryptStoredPii, mapWithConcurrency } from "../../shared/index.ts";
 import { userTable } from "../../user/index.ts";
 import { tenantMembershipsTable } from "../membership-table.ts";
-
-type UserRow = { readonly id: unknown; readonly email?: unknown; readonly displayName?: unknown };
-
-// Bounded, not Promise.all/sequential: each decrypt hits the KMS adapter's
-// own small dedicated pool (PgKmsAdapter default max: 4). Promise.all fires
-// one call per user unbounded and exhausts the pool once membership counts
-// exceed a handful, surfacing as "the connection was closed"; a strict
-// sequential loop caps concurrency at 1 and leaves 3 pool slots idle.
-const KMS_POOL_CONCURRENCY = 4;
+import { decryptMemberUsers, type MemberUserRow } from "./decrypt-member-users.ts";
 
 export const membersQuery = defineQueryHandler({
   name: "members",
@@ -43,21 +34,10 @@ export const membersQuery = defineQueryHandler({
 
     const userIds = [...new Set(rows.map((row) => row["userId"]))];
     const users =
-      userIds.length > 0 ? await selectMany<UserRow>(db, userTable, { id: userIds }) : [];
+      userIds.length > 0 ? await selectMany<MemberUserRow>(db, userTable, { id: userIds }) : [];
     const userById = new Map(users.map((u) => [String(u.id), u]));
 
-    const decrypted = await mapWithConcurrency(users, KMS_POOL_CONCURRENCY, async (user) => {
-      const email =
-        typeof user.email === "string"
-          ? await decryptStoredPii(user.email, "email", "tenant:members")
-          : null;
-      const displayName =
-        typeof user.displayName === "string"
-          ? await decryptStoredPii(user.displayName, "displayName", "tenant:members")
-          : null;
-      return { userId: String(user.id), email, displayName };
-    });
-    const decryptedByUserId = new Map(decrypted.map((d) => [d.userId, d]));
+    const decryptedByUserId = await decryptMemberUsers(users, "tenant:members");
 
     return rows.map((row) => {
       const user = userById.get(String(row["userId"]));