@cosmicdrift/kumiko-bundled-features 0.57.2 → 0.60.0

package/src/tags/aggregate-id.ts

@@ -0,0 +1,23 @@
+import { v5 as uuidv5 } from "uuid";
+
+// Fixed UUID namespace for tag-assignment aggregate-id derivation. Generated
+// once (2026-06-18), frozen: changing it would re-key every existing assignment
+// stream → broken replay. Drift-pinned in __tests__.
+const TAG_ASSIGNMENT_NAMESPACE = "a7f3c9d2-1b4e-4c8a-9f6d-2e5b8a1c3f7d";
+
+/**
+ * Deterministic aggregate-id for a tag-assignment from the tuple
+ * (tenantId, tagId, entityType, entityId). Exactly one aggregate exists per
+ * (tenant, tag, entity), so assigning the same tag twice collides on the same
+ * stream → version_conflict instead of a duplicate row. The assign handler
+ * pre-checks existence to keep re-assign idempotent (TX-safe).
+ */
+// @wrapper-known uuid-domain
+export function tagAssignmentAggregateId(
+  tenantId: string,
+  tagId: string,
+  entityType: string,
+  entityId: string,
+): string {
+  return uuidv5(`${tenantId}|${tagId}|${entityType}|${entityId}`, TAG_ASSIGNMENT_NAMESPACE);
+}

package/src/tags/constants.ts

@@ -0,0 +1,37 @@
+// @runtime client
+// tags bundle constants — feature-name + qualified handler/query names.
+//
+// Spec: kumiko-platform/docs/plans/features/tags.md
+// C#1 design: money-horse/docs/plans/cashcolt-vertragspakete.md
+
+import type { AccessRule } from "@cosmicdrift/kumiko-framework/engine";
+
+export const TAGS_FEATURE_NAME = "tags";
+
+// Qualified handler names (QN format: scope:type:name). Clients reference the
+// object instead of magic strings (mirror custom-fields' Handlers/Queries).
+export const TagsHandlers = {
+  createTag: "tags:write:create-tag",
+  assignTag: "tags:write:assign-tag",
+  removeTag: "tags:write:remove-tag",
+} as const;
+
+export const TagsQueries = {
+  // defineEntityListHandler("tag", ...) → "tag:list", qualified by the feature
+  // to "tags:query:tag:list".
+  tagList: "tags:query:tag:list",
+  assignmentList: "tags:query:tag-assignment:list",
+} as const;
+
+// Default RBAC for every tag write/read path. Tags are a low-sensitivity
+// collaboration tool, so both tenant roles may use them. Apps with their own
+// role vocabulary (e.g. "Admin"/"Editor") override via createTagsFeature({ roles }),
+// or adopt the host's whole access model with createTagsFeature({ access }) —
+// otherwise the hard-wired QNs are access_denied for their users.
+export const DEFAULT_TAG_ROLES = ["TenantAdmin", "TenantMember"] as const;
+
+// The default access rule applied to every tag handler when the app passes
+// neither `access` nor `roles`. createTagsFeature({ access: { openToAll: true } })
+// makes tagging reachable for any authenticated tenant user — matching apps
+// whose other handlers are openToAll rather than role-gated.
+export const DEFAULT_TAG_ACCESS: AccessRule = { roles: DEFAULT_TAG_ROLES };

package/src/tags/entity.ts

@@ -0,0 +1,35 @@
+import { createEntity, createTextField } from "@cosmicdrift/kumiko-framework/engine";
+
+// tag — per-tenant tag catalog. Event-sourced entity (create/rename/delete via
+// the standard executor); the framework projects `read_tags` from its own CRUD
+// events. tenantId is a base column set by the framework → tenant-scoped.
+export const tagEntity = createEntity({
+  table: "read_tags",
+  fields: {
+    name: createTextField({ required: true, maxLength: 64 }),
+    // Optional UI hint (hex or token). No enforcement — purely for rendering.
+    color: createTextField({ maxLength: 32 }),
+  },
+});
+
+// tag-assignment — host-agnostic join row keyed by (entityType, entityId). This
+// is the event-sourced, feature-owned projection that replaces a relational
+// pivot+JOIN: the framework projects `read_tag_assignments` from this entity's
+// own CRUD events, so tagging needs NO column on the host entity.
+//
+// The assignment's aggregate-id is derived deterministically from
+// (tenantId, tagId, entityType, entityId) — see aggregate-id.ts — so there is
+// exactly one row per (tag, entity) and assign is idempotent.
+//
+// Cross-entity views compose in the read-layer (no JOIN):
+//   - tags of an entity   → list assignments filter { field: "entityId", op: "eq" }
+//   - entities with a tag  → list assignments filter { field: "tagId",   op: "eq" }
+export const tagAssignmentEntity = createEntity({
+  table: "read_tag_assignments",
+  fields: {
+    tagId: createTextField({ required: true, maxLength: 64 }),
+    entityType: createTextField({ required: true, maxLength: 64 }),
+    // Host entity ids are uuid/text; 128 covers uuid plus non-uuid text keys.
+    entityId: createTextField({ required: true, maxLength: 128 }),
+  },
+});

package/src/tags/executor.ts

@@ -0,0 +1,11 @@
+import { createEntityExecutor } from "@cosmicdrift/kumiko-framework/engine";
+import { tagAssignmentEntity, tagEntity } from "./entity";
+
+// Shared executors for the tag + tag-assignment write-handlers.
+// createEntityExecutor is side-effect-free; instantiating once keeps the
+// table+executor pair in one place instead of rebuilding it per handler module.
+export const { executor: tagExecutor } = createEntityExecutor("tag", tagEntity);
+export const { executor: tagAssignmentExecutor } = createEntityExecutor(
+  "tag-assignment",
+  tagAssignmentEntity,
+);

package/src/tags/feature.ts

@@ -0,0 +1,75 @@
+// tags — generic, host-agnostic tagging for ANY entity.
+//
+// **Event-sourced, not relational.** There is no pivot table with foreign keys
+// and JOINs. The feature owns two event-sourced entities:
+//   1. `tag` (read_tags)            — per-tenant tag catalog.
+//   2. `tag-assignment` (read_tag_assignments) — join rows keyed by
+//      (entityType, entityId), with a deterministic aggregate-id so assign is
+//      idempotent. The framework projects both tables from their own CRUD
+//      events; no host column and no hand-written MSP are needed.
+//
+// Cross-entity views compose in the read-layer (no JOIN) by listing
+// tag-assignments filtered on entityId (tags of an entity) or tagId (entities
+// with a tag). See entity.ts.
+//
+// v1 scope: create-tag, assign-tag, remove-tag, list tags, list assignments.
+// Deferred: rename/delete-tag, optional host-projection decoration
+// (`wireTagsFor`), search indexing, user-data-rights anonymization.
+
+import {
+  type AccessRule,
+  defineEntityListHandler,
+  defineFeature,
+  type FeatureRegistrar,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { DEFAULT_TAG_ACCESS, TAGS_FEATURE_NAME } from "./constants";
+import { tagAssignmentEntity, tagEntity } from "./entity";
+import { createAssignTagHandler } from "./handlers/assign-tag.write";
+import { createCreateTagHandler } from "./handlers/create-tag.write";
+import { createRemoveTagHandler } from "./handlers/remove-tag.write";
+
+function registerTags(r: FeatureRegistrar<typeof TAGS_FEATURE_NAME>, access: AccessRule): void {
+  r.describe(
+    "Generic, host-agnostic tagging for any entity. Owns two event-sourced entities — the per-tenant `tag` catalog (`read_tags`) 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. Provides write-handlers `create-tag`, `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. Every path uses one access rule — adopt the host's model with createTagsFeature({ access: { openToAll: true } }) or pin roles with createTagsFeature({ roles }).",
+  );
+
+  r.entity("tag", tagEntity);
+  r.entity("tag-assignment", tagAssignmentEntity);
+
+  r.writeHandler(createCreateTagHandler(access));
+  r.writeHandler(createAssignTagHandler(access));
+  r.writeHandler(createRemoveTagHandler(access));
+
+  r.queryHandler(defineEntityListHandler("tag", tagEntity, { access }));
+  r.queryHandler(defineEntityListHandler("tag-assignment", tagAssignmentEntity, { access }));
+}
+
+export const tagsFeature = defineFeature(TAGS_FEATURE_NAME, (r) =>
+  registerTags(r, DEFAULT_TAG_ACCESS),
+);
+
+export type TagsFeatureOptions = {
+  /** Access rule for all tag write/read paths. Default { roles: ["TenantAdmin","TenantMember"] }.
+   *  Adopt the host's model — e.g. { openToAll: true } when the host lets any
+   *  authenticated tenant user tag (like the rest of its handlers), or
+   *  { roles: ["Admin"] } for a custom role vocabulary. Takes precedence over `roles`. */
+  readonly access?: AccessRule;
+  /** Shorthand for { access: { roles } }. Ignored when `access` is set. */
+  readonly roles?: 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 build a fresh feature-definition.
+export function createTagsFeature(opts: TagsFeatureOptions = {}): typeof tagsFeature {
+  if (opts.access === undefined && opts.roles === undefined) {
+    return tagsFeature;
+  }
+  const access = resolveAccess(opts);
+  return defineFeature(TAGS_FEATURE_NAME, (r) => registerTags(r, access));
+}

package/src/tags/handlers/assign-tag.write.ts

@@ -0,0 +1,48 @@
+import type { AccessRule, WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { tagAssignmentAggregateId } from "../aggregate-id";
+import { DEFAULT_TAG_ACCESS } from "../constants";
+import { tagAssignmentExecutor } from "../executor";
+import { type AssignTagPayload, assignTagPayloadSchema } from "../schemas";
+
+// assign-tag — links a tag to a host entity by (entityType, entityId). The
+// assignment id is deterministic, so the row is unique per (tag, entity).
+//
+// Idempotency: a re-assign hits the existing stream and would version_conflict,
+// which leaves the transaction aborted — so we pre-check existence and return
+// success when the assignment is already present (the requested end state). A
+// concurrent first-time race still version_conflicts (409); acceptable, since
+// assigning is a low-frequency UI action.
+export function createAssignTagHandler(access: AccessRule = DEFAULT_TAG_ACCESS): WriteHandlerDef {
+  return {
+    name: "assign-tag",
+    schema: assignTagPayloadSchema,
+    access,
+    handler: async (event, ctx) => {
+      const payload = event.payload as AssignTagPayload; // @cast-boundary engine-payload
+      const id = tagAssignmentAggregateId(
+        event.user.tenantId,
+        payload.tagId,
+        payload.entityType,
+        payload.entityId,
+      );
+
+      const existing = await tagAssignmentExecutor.detail({ id }, event.user, ctx.db);
+      if (existing) {
+        return { isSuccess: true as const, data: { id } };
+      }
+
+      return tagAssignmentExecutor.create(
+        {
+          id,
+          tagId: payload.tagId,
+          entityType: payload.entityType,
+          entityId: payload.entityId,
+        },
+        event.user,
+        ctx.db,
+      );
+    },
+  };
+}
+
+export const assignTagHandler: WriteHandlerDef = createAssignTagHandler();

package/src/tags/handlers/create-tag.write.ts

@@ -0,0 +1,23 @@
+import type { AccessRule, WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { DEFAULT_TAG_ACCESS } from "../constants";
+import { tagExecutor } from "../executor";
+import { type CreateTagPayload, createTagPayloadSchema } from "../schemas";
+
+// create-tag — adds a tag to the tenant's catalog. The framework mints a fresh
+// UUIDv7 id (no explicit id passed). Tag names are not unique by design: the
+// catalog is a free list and dedup is a UI concern (autocomplete from existing
+// tags). Rename/delete are deferred to a later iteration (v1 scope: create,
+// assign, remove, list).
+export function createCreateTagHandler(access: AccessRule = DEFAULT_TAG_ACCESS): WriteHandlerDef {
+  return {
+    name: "create-tag",
+    schema: createTagPayloadSchema,
+    access,
+    handler: async (event, ctx) => {
+      const payload = event.payload as CreateTagPayload; // @cast-boundary engine-payload
+      return tagExecutor.create(payload, event.user, ctx.db);
+    },
+  };
+}
+
+export const createTagHandler: WriteHandlerDef = createCreateTagHandler();

package/src/tags/handlers/remove-tag.write.ts

@@ -0,0 +1,34 @@
+import type { AccessRule, WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { tagAssignmentAggregateId } from "../aggregate-id";
+import { DEFAULT_TAG_ACCESS } from "../constants";
+import { tagAssignmentExecutor } from "../executor";
+import { type RemoveTagPayload, removeTagPayloadSchema } from "../schemas";
+
+// remove-tag — unlinks a tag from a host entity. Idempotent: removing an
+// assignment that doesn't exist is already the requested end state (not
+// assigned), so we pre-check and return success without a delete.
+export function createRemoveTagHandler(access: AccessRule = DEFAULT_TAG_ACCESS): WriteHandlerDef {
+  return {
+    name: "remove-tag",
+    schema: removeTagPayloadSchema,
+    access,
+    handler: async (event, ctx) => {
+      const payload = event.payload as RemoveTagPayload; // @cast-boundary engine-payload
+      const id = tagAssignmentAggregateId(
+        event.user.tenantId,
+        payload.tagId,
+        payload.entityType,
+        payload.entityId,
+      );
+
+      const existing = await tagAssignmentExecutor.detail({ id }, event.user, ctx.db);
+      if (!existing) {
+        return { isSuccess: true as const, data: { id } };
+      }
+
+      return tagAssignmentExecutor.delete({ id }, event.user, ctx.db);
+    },
+  };
+}
+
+export const removeTagHandler: WriteHandlerDef = createRemoveTagHandler();

package/src/tags/index.ts

@@ -0,0 +1,30 @@
+export { tagAssignmentAggregateId } from "./aggregate-id";
+export {
+  DEFAULT_TAG_ACCESS,
+  DEFAULT_TAG_ROLES,
+  TAGS_FEATURE_NAME,
+  TagsHandlers,
+  TagsQueries,
+} from "./constants";
+export { tagAssignmentEntity, tagEntity } from "./entity";
+export { createTagsFeature, type TagsFeatureOptions, tagsFeature } from "./feature";
+export {
+  assignTagHandler,
+  createAssignTagHandler,
+} from "./handlers/assign-tag.write";
+export {
+  createCreateTagHandler,
+  createTagHandler,
+} from "./handlers/create-tag.write";
+export {
+  createRemoveTagHandler,
+  removeTagHandler,
+} from "./handlers/remove-tag.write";
+export {
+  type AssignTagPayload,
+  assignTagPayloadSchema,
+  type CreateTagPayload,
+  createTagPayloadSchema,
+  type RemoveTagPayload,
+  removeTagPayloadSchema,
+} from "./schemas";

package/src/tags/schemas.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+
+export const createTagPayloadSchema = z.object({
+  name: z.string().min(1).max(64),
+  color: z.string().max(32).optional(),
+});
+export type CreateTagPayload = z.infer<typeof createTagPayloadSchema>;
+
+// assign + remove share the (tag, entity) reference shape.
+const entityTagRef = {
+  tagId: z.string().min(1).max(64),
+  entityType: z.string().min(1).max(64),
+  entityId: z.string().min(1).max(128),
+} as const;
+
+export const assignTagPayloadSchema = z.object(entityTagRef);
+export type AssignTagPayload = z.infer<typeof assignTagPayloadSchema>;
+
+export const removeTagPayloadSchema = z.object(entityTagRef);
+export type RemoveTagPayload = z.infer<typeof removeTagPayloadSchema>;

package/src/template-resolver/README.md

@@ -81,6 +81,28 @@ archive ───────► status: "archived"
 
 Resolver returnt **nur** Templates mit `status: "active"`. draft/archived werden ignoriert.
 
+## Consumer Conformance
+
+Plugins and features that call `resolveTemplate` can verify correct edge-case handling:
+
+```typescript
+import { describe, test } from "bun:test";
+import { runTemplateConsumerConformance } from "@cosmicdrift/kumiko-bundled-features/template-resolver/testing";
+
+describe("my-mail-renderer :: template-resolver conformance", () => {
+  runTemplateConsumerConformance(
+    test,
+    {
+      resolve: (args) => templateResolver.resolveTemplate(args),
+      resolveResources: async (template) => resolveLinkedResources(ctx, template),
+    },
+    { getDb: () => db, tenantId: ctx.user.tenantId },
+  );
+});
+```
+
+The harness checks `TemplateNotFoundError` propagation, locale-fallback, and (when `resolveResources` is provided) missing resource keys.
+
 ## Out-of-Scope
 
 - Rendering (Markdown/MJML → HTML/PDF) — siehe `renderer-foundation`

package/src/template-resolver/__tests__/conformance.integration.test.ts

@@ -0,0 +1,79 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import {
+  setupTestStack,
+  type TestStack,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { createTemplateResolverApi, TemplateNotFoundError } from "../api";
+import { createTemplateResolverFeature } from "../feature";
+import { templateResourceEntity } from "../table";
+import {
+  assertConsumerHandlesNotFound,
+  runTemplateConsumerConformance,
+  type TemplateConsumer,
+} from "../testing";
+
+const TENANT_A = "11111111-1111-4111-8111-111111111111";
+
+let stack: TestStack;
+let db: DbConnection;
+
+const feature = createTemplateResolverFeature();
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [feature] });
+  db = stack.db;
+  await unsafeCreateEntityTable(db, templateResourceEntity);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("template-resolver :: conformance harness", () => {
+  const conformantConsumer: TemplateConsumer = {
+    resolve: (args) => createTemplateResolverApi(db).resolveTemplate(args),
+    resolveResources: async (template) => {
+      const resolved: Record<string, string> = {};
+      for (const key of Object.keys(template.linkedResources)) {
+        resolved[key] = `placeholder:${key}`;
+      }
+      return resolved;
+    },
+  };
+
+  describe("positive control — direct API consumer", () => {
+    runTemplateConsumerConformance(test, conformantConsumer, {
+      getDb: () => db,
+      tenantId: TENANT_A,
+    });
+  });
+
+  test("harness detects non-conformant not-found handling", async () => {
+    const badConsumer: TemplateConsumer = {
+      resolve: async () => {
+        throw new Error("generic failure instead of TemplateNotFoundError");
+      },
+    };
+
+    await expect(
+      assertConsumerHandlesNotFound(badConsumer, { getDb: () => db, tenantId: TENANT_A }),
+    ).rejects.toThrow("expected TemplateNotFoundError, received Error");
+  });
+
+  test("conformant consumer propagates TemplateNotFoundError", async () => {
+    const apiConsumer: TemplateConsumer = {
+      resolve: (args) => createTemplateResolverApi(db).resolveTemplate(args),
+    };
+
+    await expect(
+      apiConsumer.resolve({
+        tenantId: TENANT_A,
+        slug: "conformance-not-found-slug",
+        kind: "mail-html",
+        locale: "de",
+      }),
+    ).rejects.toBeInstanceOf(TemplateNotFoundError);
+  });
+});

package/src/template-resolver/testing.ts

@@ -0,0 +1,192 @@
+// Test-only helpers for template-resolver consumers. Import via
+// `@cosmicdrift/kumiko-bundled-features/template-resolver/testing`.
+// No bun:test here — callers register cases with their own test runner.
+
+import { insertOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { ResolveRequest, TemplateResource } from "./api";
+import { TemplateNotFoundError } from "./api";
+import {
+  type ContentFormat,
+  FALLBACK_LOCALE,
+  type RenderKind,
+  SYSTEM_TENANT_ID,
+  type TemplateScope,
+  type TemplateStatus,
+} from "./constants";
+import { templateResourcesTable } from "./table";
+
+export type TemplateConsumer = {
+  readonly resolve: (args: ResolveRequest) => Promise<TemplateResource>;
+  readonly resolveResources?: (template: TemplateResource) => Promise<Record<string, string>>;
+};
+
+export type TemplateConsumerConformanceOptions = {
+  readonly getDb: () => DbConnection;
+  readonly tenantId: string;
+};
+
+export type ConformanceTestRegistrar = (name: string, fn: () => Promise<void>) => void;
+
+export class ConformanceAssertionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ConformanceAssertionError";
+  }
+}
+
+type SeedTemplateArgs = {
+  tenantId: string;
+  slug: string;
+  kind: RenderKind;
+  locale: string;
+  scope: TemplateScope;
+  status?: TemplateStatus;
+  content?: string;
+  contentFormat?: ContentFormat;
+  variableSchema?: Record<string, unknown>;
+  linkedResources?: Record<string, string>;
+  parentTemplateId?: string;
+};
+
+async function seedTemplate(db: DbConnection, args: SeedTemplateArgs): Promise<void> {
+  await insertOne(db, templateResourcesTable, {
+    tenantId: args.tenantId,
+    slug: args.slug,
+    kind: args.kind,
+    locale: args.locale,
+    scope: args.scope,
+    status: args.status ?? "active",
+    content: args.content ?? `content for ${args.slug} (${args.locale})`,
+    contentFormat: args.contentFormat ?? "markdown",
+    variableSchema: JSON.stringify(args.variableSchema ?? {}),
+    linkedResources: JSON.stringify(args.linkedResources ?? {}),
+    parentTemplateId: args.parentTemplateId ?? null,
+    createdBy: "conformance",
+    updatedBy: "conformance",
+  });
+}
+
+export async function assertConsumerHandlesNotFound(
+  consumer: TemplateConsumer,
+  opts: TemplateConsumerConformanceOptions,
+): Promise<void> {
+  const { tenantId } = opts;
+  let rejected = false;
+  let err: unknown;
+  try {
+    await consumer.resolve({
+      tenantId,
+      slug: "conformance-not-found-slug",
+      kind: "mail-html",
+      locale: "de",
+    });
+  } catch (e) {
+    rejected = true;
+    err = e;
+  }
+  if (!rejected) {
+    throw new ConformanceAssertionError("expected resolve to reject with TemplateNotFoundError");
+  }
+  if (!(err instanceof TemplateNotFoundError)) {
+    const label = err instanceof Error ? err.constructor.name : typeof err;
+    throw new ConformanceAssertionError(`expected TemplateNotFoundError, received ${label}`);
+  }
+}
+
+export async function assertConsumerRespectsLocaleFallback(
+  consumer: TemplateConsumer,
+  opts: TemplateConsumerConformanceOptions,
+): Promise<void> {
+  const db = opts.getDb();
+  const { tenantId } = opts;
+  const slug = `conformance-fallback-${crypto.randomUUID()}`;
+  await seedTemplate(db, {
+    tenantId: SYSTEM_TENANT_ID,
+    slug,
+    kind: "notification",
+    locale: FALLBACK_LOCALE,
+    scope: "system",
+    content: "conformance-fallback-content",
+  });
+  const result = await consumer.resolve({
+    tenantId,
+    slug,
+    kind: "notification",
+    locale: "tr",
+  });
+  if (result.locale !== FALLBACK_LOCALE) {
+    throw new ConformanceAssertionError(
+      `expected locale ${FALLBACK_LOCALE}, received ${result.locale}`,
+    );
+  }
+  if (result.content !== "conformance-fallback-content") {
+    throw new ConformanceAssertionError(`expected fallback content, received ${result.content}`);
+  }
+}
+
+export async function assertConsumerHandlesMissingResourceKeys(
+  consumer: TemplateConsumer,
+  opts: TemplateConsumerConformanceOptions,
+): Promise<void> {
+  const resolveResources = consumer.resolveResources;
+  if (!resolveResources) {
+    throw new ConformanceAssertionError(
+      "assertConsumerHandlesMissingResourceKeys requires consumer.resolveResources",
+    );
+  }
+
+  const db = opts.getDb();
+  const { tenantId } = opts;
+  const slug = `conformance-resources-${crypto.randomUUID()}`;
+  await seedTemplate(db, {
+    tenantId: SYSTEM_TENANT_ID,
+    slug,
+    kind: "mail-html",
+    locale: "de",
+    scope: "system",
+    linkedResources: { logo: "file_missing" },
+  });
+  const template = await consumer.resolve({
+    tenantId,
+    slug,
+    kind: "mail-html",
+    locale: "de",
+  });
+
+  try {
+    const resources = await resolveResources(template);
+    if (resources === undefined) {
+      throw new ConformanceAssertionError("resolveResources returned undefined");
+    }
+  } catch (err) {
+    if (err instanceof ConformanceAssertionError) throw err;
+    if (!(err instanceof Error)) {
+      throw new ConformanceAssertionError(`resolveResources threw non-Error: ${typeof err}`);
+    }
+    if (err instanceof TypeError) {
+      throw new ConformanceAssertionError(
+        `resolveResources threw TypeError (unhandled missing key?): ${err.message}`,
+      );
+    }
+  }
+}
+
+/** Register conformance cases with the caller's test runner (e.g. bun `test`). */
+export function runTemplateConsumerConformance(
+  register: ConformanceTestRegistrar,
+  consumer: TemplateConsumer,
+  opts: TemplateConsumerConformanceOptions,
+): void {
+  register("consumer handles TemplateNotFoundError gracefully", () =>
+    assertConsumerHandlesNotFound(consumer, opts),
+  );
+  register("consumer respects locale-fallback", () =>
+    assertConsumerRespectsLocaleFallback(consumer, opts),
+  );
+  if (consumer.resolveResources) {
+    register("consumer handles missing resource keys", () =>
+      assertConsumerHandlesMissingResourceKeys(consumer, opts),
+    );
+  }
+}

package/src/tier-engine/__tests__/drift.test.ts

@@ -18,6 +18,10 @@ describe("tier-engine drift pins", () => {
     expect(TierEngineHandlers.update).toBe("tier-engine:write:tier-assignment:update");
     expect(TierEngineQueries.list).toBe("tier-engine:query:tier-assignment:list");
     expect(TierEngineQueries.getActiveTier).toBe("tier-engine:query:get-active-tier");
+    // Screen↔Handler-Contract: der TierAdminScreen dispatcht exakt diese QNs.
+    expect(TierEngineHandlers.setTenantTier).toBe("tier-engine:write:set-tenant-tier");
+    expect(TierEngineQueries.getTenantTier).toBe("tier-engine:query:get-tenant-tier");
+    expect(TierEngineQueries.tierOptions).toBe("tier-engine:query:tier-options");
 
     // Every QN must start with the feature-name as scope.
     for (const qn of [...Object.values(TierEngineHandlers), ...Object.values(TierEngineQueries)]) {