@cosmicdrift/kumiko-bundled-features 0.57.1 → 0.59.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.57.1",
+  "version": "0.59.1",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -29,6 +29,7 @@
     "./cap-counter": "./src/cap-counter/index.ts",
     "./custom-fields": "./src/custom-fields/index.ts",
     "./custom-fields/web": "./src/custom-fields/web/index.ts",
+    "./tags": "./src/tags/index.ts",
     "./billing-foundation": "./src/billing-foundation/index.ts",
     "./subscription-stripe": "./src/subscription-stripe/index.ts",
     "./subscription-mollie": "./src/subscription-mollie/index.ts",
@@ -72,6 +73,7 @@
     "./text-content/seeding": "./src/text-content/seeding.ts",
     "./text-content/web": "./src/text-content/web/index.ts",
     "./template-resolver": "./src/template-resolver/index.ts",
+    "./template-resolver/testing": "./src/template-resolver/testing.ts",
     "./renderer-foundation": "./src/renderer-foundation/index.ts",
     "./legal-pages": "./src/legal-pages/index.ts",
     "./legal-pages/web": "./src/legal-pages/web/index.ts",
@@ -80,18 +82,18 @@
     "./step-dispatcher": "./src/step-dispatcher/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.55.1",
-    "@cosmicdrift/kumiko-framework": "0.55.1",
-    "@cosmicdrift/kumiko-headless": "0.55.1",
-    "@cosmicdrift/kumiko-renderer": "0.55.1",
-    "@cosmicdrift/kumiko-renderer-web": "0.55.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.57.2",
+    "@cosmicdrift/kumiko-framework": "0.57.2",
+    "@cosmicdrift/kumiko-headless": "0.57.2",
+    "@cosmicdrift/kumiko-renderer": "0.57.2",
+    "@cosmicdrift/kumiko-renderer-web": "0.57.2",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/nodemailer": "^8.0.0",
     "clsx": "^2.1.1",
     "lucide-react": "^1.14.0",
     "marked": "^18.0.3",
-    "nodemailer": "^8.0.7",
+    "nodemailer": "^9.0.1",
     "react": "^19.2.6",
     "stripe": "^22.1.1",
     "tailwind-merge": "^3.6.0"

package/src/auth-email-password/i18n.ts

@@ -40,6 +40,7 @@ export const defaultTranslations: TranslationsByLocale = {
     "auth.errors.signupEmailAlreadyRegistered":
       "Für diese E-Mail-Adresse existiert bereits ein Konto. Bitte logge dich ein oder setze dein Passwort zurück.",
     "auth.errors.unknownError": "Etwas ist schief gegangen. Bitte erneut versuchen.",
+    "auth.errors.originNotAllowed": "Zugriff von dieser Herkunft ist nicht erlaubt.",
     "auth.forgotPassword.title": "Passwort zurücksetzen",
     "auth.forgotPassword.intro":
       "Gib deine E-Mail-Adresse ein. Falls ein Konto existiert, schicken wir dir einen Reset-Link.",
@@ -140,6 +141,7 @@ export const defaultTranslations: TranslationsByLocale = {
     "auth.errors.signupEmailAlreadyRegistered":
       "An account already exists for this email. Please sign in or reset your password.",
     "auth.errors.unknownError": "Something went wrong. Please try again.",
+    "auth.errors.originNotAllowed": "Requests from this origin are not allowed.",
     "auth.forgotPassword.title": "Reset password",
     "auth.forgotPassword.intro":
       "Enter your email. If an account exists, we'll send you a reset link.",

package/src/config/__tests__/config.integration.test.ts

@@ -175,10 +175,7 @@ const integrationFeature = defineFeature("integration", (r) => {
         default: "initial",
         write: access.roles("Admin"),
       }),
-      // Settings-Hub system-scope proxies for the derived Stripe screen: a
-      // privileged boolean (billing-live = machine OR human-SystemAdmin) and
-      // an encrypted system secret (api-key). Both are surfaced to a human
-      // SystemAdmin by build-config-feature-schema and must be SET-able by them.
+      // Privileged + encrypted system keys must be SET-able by a human SystemAdmin (the derived Stripe screen surfaces both).
       billingLive: createSystemConfig("boolean", {
         default: false,
         write: access.privileged,

package/src/config/__tests__/env-overrides.test.ts

@@ -88,6 +88,27 @@ describe("buildEnvConfigOverrides", () => {
     expect(result.size).toBe(0);
   });
 
+  test("whitespace-only env var → skipped (semantically empty, must not clobber default)", () => {
+    // Number key: pre-fix `Number("   ".trim())` was 0 and finite → silently
+    // resolved to 0 instead of falling through to the declared default.
+    const reg = registryStub({
+      "a:config:n": createSystemConfig("number", { env: "N" }),
+      "a:config:x": createSystemConfig("text", { env: "X" }),
+    });
+    const result = buildEnvConfigOverrides(reg, { N: "   ", X: "\t\n" });
+    expect(result.size).toBe(0);
+  });
+
+  test("select value is trimmed before option membership (so ` dark` resolves)", () => {
+    const reg = registryStub({
+      "a:config:theme": createSystemConfig("select", {
+        env: "THEME",
+        options: ["light", "dark"],
+      }),
+    });
+    expect(buildEnvConfigOverrides(reg, { THEME: " dark " }).get("a:config:theme")).toBe("dark");
+  });
+
   test("keys without an env field are ignored even if a same-named var exists", () => {
     const reg = registryStub({
       "a:config:no-env": createSystemConfig("text", {}),

package/src/config/handlers/__tests__/prepare-config-write.test.ts

@@ -106,10 +106,7 @@ describe("prepareConfigWrite", () => {
   });
 
   test("privileged key (system + SystemAdmin) is writable by a human SystemAdmin", () => {
-    // The derived configEdit screen surfaces a `access.privileged`
-    // (`["system","SystemAdmin"]`) key to a human SystemAdmin (e.g. Stripe
-    // billing-live). The write must succeed — "system in the write-set"
-    // means machine-OR-operator, not machine-only.
+    // "system" in the write-set means machine-OR-operator, not machine-only — a human SystemAdmin must still be able to write.
     const privilegedKey = createSystemConfig("boolean", { write: access.privileged });
     const result = prepareConfigWrite({
       registry: registryStub({ "ns:config:billing-live": privilegedKey }),

package/src/config/handlers/cascade.query.ts

@@ -5,11 +5,9 @@ import {
 } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
 import { requireConfigResolver } from "../feature";
-import { redactInheritedCascade, shouldRedactInherited } from "../read-redaction";
+import { MASKED, redactInheritedCascade, shouldRedactInherited } from "../read-redaction";
 import { hasConfigAccess } from "../write-helpers";
 
-const MASKED = "••••••";
-
 export const cascadeQuery = defineQueryHandler({
   name: "cascade",
   schema: z.object({

package/src/config/handlers/readiness.query.ts

@@ -101,6 +101,12 @@ export async function collectMissingRequiredConfig(
     ctx.secrets,
   );
   for (const [qualifiedKey, keyDef] of candidates) {
+    // Deliberately the unredacted cascade value: readiness asks "does this
+    // tenant functionally have the value?", and an inheritedToTenant:false key
+    // set only at system-level IS inherited (the resolver ignores
+    // inheritedToTenant — that flag only redacts the value queries' display).
+    // Redacting here would report a working key as missing. The is-set bit this
+    // exposes is intentional; see read-redaction.ts.
     const value = cascades.get(qualifiedKey)?.value;
     if (isUnset(value, keyDef.type)) {
       missing.push({ key: qualifiedKey, scope: keyDef.scope, type: keyDef.type });

package/src/config/handlers/values.query.ts

@@ -6,11 +6,9 @@ import {
 } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
 import { requireConfigResolver } from "../feature";
-import { redactInheritedCascade, shouldRedactInherited } from "../read-redaction";
+import { MASKED, redactInheritedCascade, shouldRedactInherited } from "../read-redaction";
 import { hasConfigAccess } from "../write-helpers";
 
-const MASKED = "••••••";
-
 export const valuesQuery = defineQueryHandler({
   name: "values",
   schema: z.object({}),

package/src/config/read-redaction.ts

@@ -14,8 +14,19 @@ const OWN_SOURCES: ReadonlySet<ConfigValueSource> = new Set(["user-row", "tenant
 
 // A SystemAdmin owns the platform-level values and may always see them. Every
 // other viewer (TenantAdmin, User) is tenant-side — for an
-// inheritedToTenant:false key they must learn neither the inherited platform
-// value nor that it is set.
+// inheritedToTenant:false key the value-returning read handlers (cascade +
+// values) hide both the inherited platform value and that it is set.
+//
+// Scope note: redaction is display-only. The resolver does NOT consult
+// inheritedToTenant (zero reads in resolver.ts), so the tenant still
+// functionally inherits and uses the value, and config:query:readiness
+// deliberately reports such a key as satisfied (is-set) rather than missing —
+// flagging a working key as missing would nag tenants to set already-
+// functioning config. So "nor that it is set" holds for the value queries, not
+// for the functional readiness rollup. See readiness.query.ts.
+// Shared mask for redacted config values across the read handlers (cascade + values).
+export const MASKED = "••••••";
+
 export function mayViewInheritedValue(roles: readonly string[]): boolean {
   return roles.includes(SYSTEM_ADMIN_ROLE);
 }

package/src/config/resolver.ts

@@ -384,6 +384,12 @@ export function createConfigResolver(options: ConfigResolverOptions = {}): Confi
       return { value: undefined, source: "missing" };
     },
 
+    // NOTE: getAll / getAllWithSource read only config_values rows and do NOT
+    // dispatch to the secrets store (unlike get/getCascade/getWithSource). A
+    // backing="secrets" key has no config_values row, so it is simply ABSENT
+    // from the result map — never a stale/undefined value. Callers needing a
+    // secrets-backed value must use get/getCascade; these bulk readers are for
+    // the config_values-backed keys only.
     async getAll(tenantId, userId, db) {
       // Only load rows relevant to this user/tenant (system + tenant + user scope)
       const rows = await selectConfigRowsForScope(db, SYSTEM_TENANT_ID, tenantId, userId);
@@ -613,8 +619,8 @@ export function validateAppOverrides(
 // resolving to the wrong value. Reuses validateAppOverrides for the
 // existence / bounds / options / computed-conflict gates.
 //
-// undefined OR empty-string env vars are skipped — an unset (or `FOO=`)
-// variable must not clobber a declared default.
+// undefined OR blank env vars are skipped — an unset, empty (`FOO=`) or
+// whitespace-only (`FOO="   "`) variable must not clobber a declared default.
 
 type EnvSource = Readonly<Record<string, string | undefined>>;
 
@@ -646,8 +652,9 @@ function coerceEnvValue(
       `ENV config bridge: "${envName}" → "${qualifiedKey}" expects a boolean (true/false/1/0), got "${raw}".`,
     );
   }
-  // text | select — select-option membership is validated by validateAppOverrides
-  return raw;
+  // text | select — trimmed so e.g. `THEME=" dark"` resolves to a real option;
+  // select-option membership is validated by validateAppOverrides.
+  return raw.trim();
 }
 
 export function buildEnvConfigOverrides(
@@ -659,7 +666,7 @@ export function buildEnvConfigOverrides(
     const envName = keyDef.env;
     if (!envName) continue;
     const raw = env[envName];
-    if (raw === undefined || raw === "") continue;
+    if (raw === undefined || raw.trim() === "") continue;
     record[qualifiedKey] = coerceEnvValue(qualifiedKey, envName, keyDef.type, raw);
   }
   return validateAppOverrides(registry, record);

package/src/jobs/feature.ts

@@ -153,9 +153,7 @@ export function createJobsFeature(): FeatureDefinition {
       },
     });
 
-    // Framework-provided single-run rebuild job (QN `jobs:job:projection-rebuild`).
-    // Available whenever `jobs` is composed — `enqueueProjectionRebuild` dispatches
-    // it; every run is tracked in read_job_runs + retryable via jobs:write:retry.
+    // Framework-provided rebuild job — available whenever `jobs` is composed; enqueueProjectionRebuild dispatches it.
     r.job(
       "projectionRebuild",
       { trigger: { manual: true }, schema: projectionRebuildPayloadSchema },

package/src/jobs/handlers/projection-rebuild.job.ts

@@ -1,10 +1,4 @@
-// Single-run projection-rebuild worker (QN `jobs:job:projection-rebuild`).
-// Replays the event log into one projection via the framework's
-// `rebuildProjection`. Triggered manually — typically through
-// `enqueueProjectionRebuild` (migrations) as the self-service repair for an
-// emptied projection, a deliberate manual rebuild, or a post-upcaster refill.
-// Run-tracking (read_job_runs + read_job_run_logs) and retry come for free
-// from the jobs feature that registers this worker.
+// Single-run projection-rebuild worker (`jobs:job:projection-rebuild`); manually triggered, typically via enqueueProjectionRebuild to refill an emptied projection.
 
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import type { JobHandlerFn } from "@cosmicdrift/kumiko-framework/engine";

package/src/page-render/__tests__/security-headers.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, test } from "bun:test";
+import { securePageHeaders } from "../security-headers";
+
+describe("securePageHeaders", () => {
+  test("merges caller headers alongside the security defaults", () => {
+    const h = securePageHeaders({ "content-type": "text/html; charset=utf-8" });
+    expect(h["content-type"]).toBe("text/html; charset=utf-8");
+    expect(h["x-content-type-options"]).toBe("nosniff");
+    expect(h["content-security-policy"]).toContain("script-src 'none'");
+  });
+
+  test("a caller can NEVER override a hardened security header", () => {
+    const h = securePageHeaders({
+      "content-security-policy": "default-src *",
+      "x-frame-options": "ALLOWALL",
+    });
+    expect(h["content-security-policy"]).toBe(
+      "script-src 'none'; object-src 'none'; base-uri 'none'",
+    );
+    expect(h["x-frame-options"]).toBe("SAMEORIGIN");
+  });
+});

package/src/page-render/security-headers.ts

@@ -11,6 +11,9 @@ const PUBLIC_PAGE_SECURITY_HEADERS = {
   "referrer-policy": "strict-origin-when-cross-origin",
 } as const;
 
+// Security headers spread LAST so a caller's `extra` can never override a
+// hardened default (CSP/nosniff/frame-options); extra only adds non-security
+// headers like content-type/cache-control/vary.
 export function securePageHeaders(extra: Record<string, string>): Record<string, string> {
-  return { ...PUBLIC_PAGE_SECURITY_HEADERS, ...extra };
+  return { ...extra, ...PUBLIC_PAGE_SECURITY_HEADERS };
 }

package/src/tags/__tests__/drift.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, test } from "bun:test";
+import { tagAssignmentAggregateId } from "../aggregate-id";
+
+// Drift-Pin-Tests — these values are cross-boot contracts. If they go red:
+// stop, think, revert. aggregate-id.ts names this file.
+
+const TENANT = "00000000-0000-0000-0000-000000000001";
+
+describe("tags drift pins", () => {
+  test("tag-assignment aggregate-id namespace is stable across boots", () => {
+    // TAG_ASSIGNMENT_NAMESPACE is in stone — changing it re-keys every existing
+    // assignment stream and breaks event-replay. If this fails: revert the
+    // namespace, do not adjust the expected values.
+    const base = tagAssignmentAggregateId(TENANT, "tag-1", "credit", "c-1");
+
+    expect(base).toBe(tagAssignmentAggregateId(TENANT, "tag-1", "credit", "c-1")); // deterministic
+    // Every tuple component is part of the key (no collisions across the axes).
+    expect(base).not.toBe(
+      tagAssignmentAggregateId("11111111-1111-1111-1111-111111111111", "tag-1", "credit", "c-1"),
+    );
+    expect(base).not.toBe(tagAssignmentAggregateId(TENANT, "tag-2", "credit", "c-1"));
+    expect(base).not.toBe(tagAssignmentAggregateId(TENANT, "tag-1", "invoice", "c-1"));
+    expect(base).not.toBe(tagAssignmentAggregateId(TENANT, "tag-1", "credit", "c-2"));
+
+    // Pinned actual outputs — the drift-detector for the namespace constant.
+    expect(base).toBe("4f6e3d2e-033b-57f8-b044-6a3358647f65");
+    expect(
+      tagAssignmentAggregateId("11111111-1111-1111-1111-111111111111", "tag-1", "credit", "c-1"),
+    ).toBe("1bc17669-25ad-565b-9caf-72dbb18756da");
+    expect(tagAssignmentAggregateId(TENANT, "tag-2", "credit", "c-1")).toBe(
+      "6de1c5c6-25a1-508e-b1f8-de914745406d",
+    );
+    expect(tagAssignmentAggregateId(TENANT, "tag-1", "invoice", "c-1")).toBe(
+      "4e0d68b6-a69b-5dc1-9a2a-cd3f7e8b179d",
+    );
+    expect(tagAssignmentAggregateId(TENANT, "tag-1", "credit", "c-2")).toBe(
+      "659a1f64-31c0-5365-82e6-512fd822f002",
+    );
+  });
+
+  test("aggregate-id format is a valid uuid", () => {
+    expect(tagAssignmentAggregateId(TENANT, "tag-1", "credit", "c-1")).toMatch(
+      /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/,
+    );
+  });
+});

package/src/tags/__tests__/feature.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, test } from "bun:test";
+import { DEFAULT_TAG_ROLES } from "../constants";
+import { createTagsFeature } from "../feature";
+import { assignTagPayloadSchema, createTagPayloadSchema, removeTagPayloadSchema } from "../schemas";
+
+// Unit tests: feature-shape, role-options, schema-validation. The ES-loop
+// behaviour (idempotent assign/remove, projection, tenant-isolation, read
+// composition) needs a real stack → tags.integration.test.ts.
+
+function writeAccess(
+  feature: ReturnType<typeof createTagsFeature>,
+  nameMatch: string,
+): readonly string[] {
+  const entry = Object.entries(feature.writeHandlers).find(([qn]) => qn.includes(nameMatch));
+  if (!entry) throw new Error(`handler ${nameMatch} not registered`);
+  const access = entry[1].access;
+  if (!access || !("roles" in access)) throw new Error(`handler ${nameMatch} has no roles`);
+  return access.roles;
+}
+
+function queryAccess(
+  feature: ReturnType<typeof createTagsFeature>,
+  nameMatch: string,
+): readonly string[] {
+  const entry = Object.entries(feature.queryHandlers).find(([qn]) => qn.includes(nameMatch));
+  if (!entry) throw new Error(`query ${nameMatch} not registered`);
+  const access = entry[1].access;
+  if (!access || !("roles" in access)) throw new Error(`query ${nameMatch} has no roles`);
+  return access.roles;
+}
+
+describe("createTagsFeature shape", () => {
+  test("registers tag + tag-assignment entities, 3 write-handlers, 2 query-handlers", () => {
+    const feature = createTagsFeature();
+
+    expect(Object.keys(feature.entities ?? {})).toEqual(
+      expect.arrayContaining(["tag", "tag-assignment"]),
+    );
+
+    expect(Object.keys(feature.writeHandlers)).toEqual(
+      expect.arrayContaining([
+        expect.stringMatching(/create-tag/),
+        expect.stringMatching(/assign-tag/),
+        expect.stringMatching(/remove-tag/),
+      ]),
+    );
+    expect(Object.keys(feature.writeHandlers)).toHaveLength(3);
+
+    expect(Object.keys(feature.queryHandlers)).toEqual(
+      expect.arrayContaining([
+        expect.stringMatching(/tag:list/),
+        expect.stringMatching(/tag-assignment:list/),
+      ]),
+    );
+    expect(Object.keys(feature.queryHandlers)).toHaveLength(2);
+  });
+});
+
+describe("createTagsFeature access-options", () => {
+  test("without options: singleton with default roles on every path", () => {
+    const feature = createTagsFeature();
+    expect(feature).toBe(createTagsFeature());
+    expect(writeAccess(feature, "create-tag")).toEqual([...DEFAULT_TAG_ROLES]);
+    expect(writeAccess(feature, "assign-tag")).toEqual([...DEFAULT_TAG_ROLES]);
+    expect(writeAccess(feature, "remove-tag")).toEqual([...DEFAULT_TAG_ROLES]);
+    expect(queryAccess(feature, "tag:list")).toEqual([...DEFAULT_TAG_ROLES]);
+    expect(queryAccess(feature, "tag-assignment:list")).toEqual([...DEFAULT_TAG_ROLES]);
+  });
+
+  test("roles option overrides every write- and query-path", () => {
+    const feature = createTagsFeature({ roles: ["Admin", "Editor"] });
+    expect(writeAccess(feature, "create-tag")).toEqual(["Admin", "Editor"]);
+    expect(writeAccess(feature, "assign-tag")).toEqual(["Admin", "Editor"]);
+    expect(writeAccess(feature, "remove-tag")).toEqual(["Admin", "Editor"]);
+    expect(queryAccess(feature, "tag:list")).toEqual(["Admin", "Editor"]);
+    expect(queryAccess(feature, "tag-assignment:list")).toEqual(["Admin", "Editor"]);
+  });
+});
+
+describe("createTagPayloadSchema", () => {
+  test("accepts name only", () => {
+    expect(createTagPayloadSchema.safeParse({ name: "Kunde Müller" }).success).toBe(true);
+  });
+
+  test("accepts name + color", () => {
+    expect(createTagPayloadSchema.safeParse({ name: "VIP", color: "#d4af37" }).success).toBe(true);
+  });
+
+  test("rejects empty name", () => {
+    expect(createTagPayloadSchema.safeParse({ name: "" }).success).toBe(false);
+  });
+
+  test("rejects name over 64 chars", () => {
+    expect(createTagPayloadSchema.safeParse({ name: "x".repeat(65) }).success).toBe(false);
+  });
+});
+
+describe("assign/remove payload schemas", () => {
+  const valid = { tagId: "tag-1", entityType: "credit", entityId: "c-1" };
+
+  test("accept a full (tag, entity) reference", () => {
+    expect(assignTagPayloadSchema.safeParse(valid).success).toBe(true);
+    expect(removeTagPayloadSchema.safeParse(valid).success).toBe(true);
+  });
+
+  test("reject missing entityId", () => {
+    expect(assignTagPayloadSchema.safeParse({ tagId: "tag-1", entityType: "credit" }).success).toBe(
+      false,
+    );
+  });
+
+  test("reject empty tagId", () => {
+    expect(assignTagPayloadSchema.safeParse({ ...valid, tagId: "" }).success).toBe(false);
+  });
+
+  test("reject entityId over 128 chars", () => {
+    expect(assignTagPayloadSchema.safeParse({ ...valid, entityId: "x".repeat(129) }).success).toBe(
+      false,
+    );
+  });
+});

package/src/tags/__tests__/tags.integration.test.ts

@@ -0,0 +1,185 @@
+// Full-stack integration for the tags bundle. Drives create → assign → list →
+// remove through the real dispatcher + entity-projection + DB. Proves the
+// architecture end-to-end WITHOUT any host wiring (tags are host-agnostic — the
+// host is just the entityType/entityId strings on the assignment):
+//   - create-tag projects into read_tags
+//   - assign-tag projects a join row keyed by (entityType, entityId)
+//   - read-layer composition both directions (tags of an entity / entities of a tag)
+//   - assign + remove are idempotent (re-assign = one row, remove-missing = ok)
+//   - multi-tenant isolation
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { TagsHandlers, TagsQueries } from "../constants";
+import { tagAssignmentEntity, tagEntity } from "../entity";
+import { createTagsFeature } from "../feature";
+
+const tagsFeature = createTagsFeature();
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [tagsFeature] });
+  await unsafeCreateEntityTable(stack.db, tagEntity);
+  await unsafeCreateEntityTable(stack.db, tagAssignmentEntity);
+  await createEventsTable(stack.db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  await asRawClient(stack.db).unsafe("DELETE FROM kumiko_events");
+  await asRawClient(stack.db).unsafe("DELETE FROM read_tags");
+  await asRawClient(stack.db).unsafe("DELETE FROM read_tag_assignments");
+});
+
+const admin = createTestUser({ roles: ["TenantAdmin"] });
+const otherTenant = createTestUser({
+  roles: ["TenantAdmin"],
+  tenantId: "00000000-0000-4000-8000-0000000000aa",
+});
+
+async function createTag(name: string, user = admin): Promise<string> {
+  const tag = await stack.http.writeOk<{ id: string }>(TagsHandlers.createTag, { name }, user);
+  return tag.id;
+}
+
+async function assign(tagId: string, entityType: string, entityId: string, user = admin) {
+  return stack.http.writeOk(TagsHandlers.assignTag, { tagId, entityType, entityId }, user);
+}
+
+async function remove(tagId: string, entityType: string, entityId: string, user = admin) {
+  return stack.http.writeOk(TagsHandlers.removeTag, { tagId, entityType, entityId }, user);
+}
+
+async function listTags(user = admin): Promise<Array<Record<string, unknown>>> {
+  const res = await stack.http.queryOk<{ rows: Array<Record<string, unknown>> }>(
+    TagsQueries.tagList,
+    {},
+    user,
+  );
+  return res.rows;
+}
+
+async function listAssignments(
+  filter: { field: string; op: "eq"; value: unknown } | undefined,
+  user = admin,
+): Promise<Array<Record<string, unknown>>> {
+  const res = await stack.http.queryOk<{ rows: Array<Record<string, unknown>> }>(
+    TagsQueries.assignmentList,
+    filter ? { filter } : {},
+    user,
+  );
+  return res.rows;
+}
+
+async function countAssignments(tenantId: string): Promise<number> {
+  const rows = await asRawClient(stack.db).unsafe(
+    "SELECT count(*)::int AS n FROM read_tag_assignments WHERE tenant_id = $1",
+    [tenantId],
+  );
+  return (rows as ReadonlyArray<{ n: number }>)[0]?.n ?? 0;
+}
+
+describe("tags integration — catalog + assignment roundtrip", () => {
+  test("create-tag lands in read_tags", async () => {
+    const id = await createTag("Kunde Müller");
+    const tags = await listTags();
+    expect(tags).toHaveLength(1);
+    expect(tags[0]?.["id"]).toBe(id);
+    expect(tags[0]?.["name"]).toBe("Kunde Müller");
+  });
+
+  test("assign-tag → assignment queryable both composition directions", async () => {
+    const tagId = await createTag("VIP");
+    await assign(tagId, "credit", "credit-1");
+
+    // tags of an entity
+    const byEntity = await listAssignments({ field: "entityId", op: "eq", value: "credit-1" });
+    expect(byEntity).toHaveLength(1);
+    expect(byEntity[0]?.["tagId"]).toBe(tagId);
+    expect(byEntity[0]?.["entityType"]).toBe("credit");
+
+    // entities carrying a tag
+    const byTag = await listAssignments({ field: "tagId", op: "eq", value: tagId });
+    expect(byTag).toHaveLength(1);
+    expect(byTag[0]?.["entityId"]).toBe("credit-1");
+  });
+
+  test("remove-tag deletes the assignment", async () => {
+    const tagId = await createTag("temp");
+    await assign(tagId, "credit", "credit-2");
+    expect(await countAssignments(admin.tenantId)).toBe(1);
+
+    await remove(tagId, "credit", "credit-2");
+    expect(await countAssignments(admin.tenantId)).toBe(0);
+    const left = await listAssignments({ field: "entityId", op: "eq", value: "credit-2" });
+    expect(left).toHaveLength(0);
+  });
+});
+
+describe("tags integration — many-to-many composition", () => {
+  test("one entity carries multiple tags", async () => {
+    const a = await createTag("rot");
+    const b = await createTag("wasser");
+    await assign(a, "credit", "credit-3");
+    await assign(b, "credit", "credit-3");
+
+    const tags = await listAssignments({ field: "entityId", op: "eq", value: "credit-3" });
+    expect(tags.map((r) => r["tagId"]).sort()).toEqual([a, b].sort());
+  });
+
+  test("one tag spans multiple entities", async () => {
+    const tagId = await createTag("Mappe-2026");
+    await assign(tagId, "credit", "credit-4");
+    await assign(tagId, "credit", "credit-5");
+
+    const entities = await listAssignments({ field: "tagId", op: "eq", value: tagId });
+    expect(entities.map((r) => r["entityId"]).sort()).toEqual(["credit-4", "credit-5"]);
+  });
+});
+
+describe("tags integration — idempotency", () => {
+  test("re-assigning the same (tag, entity) keeps exactly one row", async () => {
+    const tagId = await createTag("dup");
+    await assign(tagId, "credit", "credit-6");
+    await assign(tagId, "credit", "credit-6"); // re-assign: must be a no-op success
+
+    expect(await countAssignments(admin.tenantId)).toBe(1);
+    const rows = await listAssignments({ field: "entityId", op: "eq", value: "credit-6" });
+    expect(rows).toHaveLength(1);
+  });
+
+  test("removing a never-assigned (tag, entity) succeeds (no error, no row)", async () => {
+    const tagId = await createTag("ghost");
+    // never assigned — remove must still succeed (idempotent end-state)
+    await remove(tagId, "credit", "credit-7");
+    expect(await countAssignments(admin.tenantId)).toBe(0);
+  });
+});
+
+describe("tags integration — multi-tenant isolation", () => {
+  test("tenant B sees neither tenant A's tags nor assignments", async () => {
+    const tagId = await createTag("A-only", admin);
+    await assign(tagId, "credit", "credit-8", admin);
+
+    expect(await listTags(otherTenant)).toHaveLength(0);
+    expect(
+      await listAssignments({ field: "entityId", op: "eq", value: "credit-8" }, otherTenant),
+    ).toHaveLength(0);
+
+    // tenant A still sees its own
+    expect(await listTags(admin)).toHaveLength(1);
+    expect(await countAssignments(admin.tenantId)).toBe(1);
+    expect(await countAssignments(otherTenant.tenantId)).toBe(0);
+  });
+});